Release Notes Writer

Release notes are written for the people affected by the changes, not the people who made them. This skill turns a merge list into notes a user can scan in a minute: benefit-first highlights, fixes named by the symptom the user actually saw, and breaking changes that arrive with a migration step instead of an apology. The commit log is the input; it is never the output.

When to use this skill

• A release is shipping and the merged changes need turning into user-facing notes
• A changelog exists but reads like an internal ticket dump
• Breaking changes must be communicated with upgrade instructions people can follow
• The same release needs notes at several altitudes: in-app blurb, docs page, announcement
• Someone proposes publishing "various improvements and bug fixes" — intervene

Workflow

1. Gather the raw material: merged changes, closed tickets, commit subjects, and — most useful and most forgotten — the support threads that motivated the fixes.
2. Filter hard. Internal refactors, test changes, and dependency bumps with no observable effect are cut. If a user cannot perceive it, it is not a release note; it is an engineering diary.
3. Translate each survivor from implementation to effect: what can the user now do, or stop suffering? "Rewrote the export pipeline" becomes "Exports over 10,000 rows no longer time out."
4. Sort into sections: Highlights (three at most — when everything is a highlight, nothing is), Improvements, Fixes, Breaking changes, Deprecations.
5. Give every breaking change a migration: what breaks, who is affected, the exact step to take, and what happens to those who do nothing. A breaking change without a migration step is a support queue pre-ordered in bulk.
6. Write the one-paragraph header: the theme of this release in plain words, so a reader decides in ten seconds whether the rest concerns them.
7. Stamp the version, the date, and the upgrade command or link where one exists.
8. Do the final pass as a user of the previous version: for each line, can I tell whether I care? Lines that fail get a who-this-affects clause or get cut.

Output format

## <version> — <date>

<One-paragraph theme: what this release is about, in plain words.>

### Highlights
- <Benefit-first sentence: what you can now do, and where to find it.>

### Improvements
- <Smaller wins, one line each, user-visible only.>

### Fixes
- <The symptom that no longer happens.> (<reference>)

### Breaking changes
- <What breaks, and for whom> -> <the exact step to take> — by <version or date>

### Upgrade notes
<Command or link. What to back up first. Expected downtime, if any.>

Quality bar

• Fixes name the symptom the user saw, never the internal defect ("race condition in cache invalidation" helps nobody who met the bug).
• No entry reads "various improvements", "misc fixes", or "general polish".
• Breaking changes sit above the fold and cannot be missed by a skimmer.
• Every line stands alone — readers arrive from search, mid-page, with no context.
• The tone is even: no marketing confetti in patch notes, and no groveling either. Changes, effects, instructions.