SPB Git

spb/ultra-sharp-agent-skills Public

Ultra-Sharp Agent Skills — a research-first skill-authoring system + 72 production-ready skills for AI agents.

aiagentsskillsclaude
Python 100%
3.5 KB
View source Raw Blame History

# name: writing-release-notes description: Writes user-facing release notes and changelog entries in the house style — benefit-first, plain language, grouped by Added/Improved/Fixed. Use when the user asks to write, draft, or edit release notes, a changelog entry, a "what's new" section, or a version announcement for end users. Do not use for git commit messages, internal PR descriptions, or API reference documentation.

# Writing Release Notes

# When to use / when NOT to use

  • Use for: release notes, changelog entries, "what's new" copy, version announcements — anything a customer or end user will read about a release.
  • Do NOT use for: git commit messages, PR titles/descriptions, internal engineering changelogs, API reference docs, or marketing landing pages. Those have different audiences and conventions — write them normally.
  • If the audience is ambiguous, ask one question: "Is this for end users or for engineers?" Apply this skill only for end users.

# House style — the five rules

  1. Lead with the user benefit, not the implementation.

    • ✅ "Search results now load twice as fast."
    • ❌ "Migrated the search index to OpenSearch 2.x with query caching."

  2. Plain language, present tense, second person where natural.

    • ✅ "You can now export reports as PDF."
    • ❌ "PDF export functionality has been implemented."
    • Never use: "leverage", "utilize", "robust", "seamless", "enhanced UX", ticket IDs, or internal codenames.

  3. Group entries under exactly three headings, in this order: ### Added, ### Improved, ### Fixed. Omit a heading only if it has no entries. One bullet per change, max 2 sentences per bullet.

  4. Every breaking change gets a > **Breaking:** blockquote at the TOP of the notes, before any heading, stating what breaks and the one-line migration action. Never bury a breaking change in a bullet.

  5. Cut the noise. Never include: dependency bumps with no user impact, internal refactors, test/CI changes, or "various bug fixes and improvements" filler. If a change has no observable effect for the user, it does not appear.

# Workflow

  1. Collect the changes (diff, commit list, or user's description). Discard anything rule 5 excludes.
  2. Classify each remaining change as Added / Improved / Fixed; identify breaking changes.
  3. Rewrite each change benefit-first (rule 1) in plain language (rule 2).
  4. Assemble in the output format below.
  5. Self-review against the five rules; fix violations before delivering.

# Output format

markdown
## <Product name> <version> — <YYYY-MM-DD>

> **Breaking:** <what breaks + migration action>   ← only if applicable

<One-sentence summary of the release theme.>

### Added
- <bullet>

### Improved
- <bullet>

### Fixed
- <bullet>

Deliver in chat by default; write to CHANGELOG.md (prepended above previous entries) only if the user names a file or the repo already has one.

# Edge cases

  • No user-visible changes at all → say so and propose the one-liner: "This release contains internal improvements only." Do not invent benefits.
  • Unclear whether a change is user-visible → include it under Improved, phrased by observable effect; flag your assumption to the user.
  • Version or date unknown → use placeholders <version> / <date> and tell the user to fill them in.

# More examples

Full positive/negative example pairs, including a complete before/after release: see references/examples.md.