spb/ultra-sharp-agent-skills Public

1---2name: writing-release-notes3description: 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.4---56<!--7Author: Simon-Pierre Boucher8Contact: contact@spboucher.ai9-->1011# Writing Release Notes1213## When to use / when NOT to use14- **Use for:** release notes, changelog entries, "what's new" copy, version announcements — anything a **customer or end user** will read about a release.15- **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.16- If the audience is ambiguous, ask one question: "Is this for end users or for engineers?" Apply this skill only for end users.1718## House style — the five rules19201. **Lead with the user benefit, not the implementation.**21   - ✅ "Search results now load twice as fast."22   - ❌ "Migrated the search index to OpenSearch 2.x with query caching."23242. **Plain language, present tense, second person where natural.**25   - ✅ "You can now export reports as PDF."26   - ❌ "PDF export functionality has been implemented."27   - Never use: "leverage", "utilize", "robust", "seamless", "enhanced UX", ticket IDs, or internal codenames.28293. **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.30314. **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.32335. **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.3435## Workflow36371. Collect the changes (diff, commit list, or user's description). Discard anything rule 5 excludes.382. Classify each remaining change as Added / Improved / Fixed; identify breaking changes.393. Rewrite each change benefit-first (rule 1) in plain language (rule 2).404. Assemble in the output format below.415. Self-review against the five rules; fix violations before delivering.4243## Output format4445```markdown46## <Product name> <version> — <YYYY-MM-DD>4748> **Breaking:** <what breaks + migration action>   ← only if applicable4950<One-sentence summary of the release theme.>5152### Added53- <bullet>5455### Improved56- <bullet>5758### Fixed59- <bullet>60```6162Deliver 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.6364## Edge cases65- **No user-visible changes at all** → say so and propose the one-liner: "This release contains internal improvements only." Do not invent benefits.66- **Unclear whether a change is user-visible** → include it under Improved, phrased by observable effect; flag your assumption to the user.67- **Version or date unknown** → use placeholders `<version>` / `<date>` and tell the user to fill them in.6869## More examples70Full positive/negative example pairs, including a complete before/after release: see [references/examples.md](references/examples.md).71