Release notes writer

Release Notes Writer

Overview

This skill turns raw engineering output — merged PRs, commit messages, issue references, and changelog fragments — into release notes that a real user can read and act on. It enforces a consistent structure, a user-facing voice (benefit first, not implementation detail), correct categorization (especially surfacing breaking changes), and an upgrade/migration section when needed.

Keywords: release notes, changelog, CHANGELOG.md, version bump, breaking changes, migration guide, semver, what's new, release announcement, GitHub release, conventional commits.

Use this skill whenever the user has a set of changes (any of: PR titles, git log output, conventional-commit messages, a list of Jira/GitHub issues, or an existing draft) and wants them shaped into publishable notes.

When NOT to use

• A single trivial change with no user impact — just describe it.
• Internal-only commit summaries with no audience — use a plain commit log.
• Writing the code itself — this skill writes the notes, not the changes.

Inputs to gather first

Before drafting, confirm or infer:

1. Version & date — e.g. v2.4.0, 2026-06-08. Infer semver bump from the changes (see references/categorization.md).
2. Audience — end users, API consumers/developers, or internal team. This changes vocabulary and depth.
3. Source material — PR list, commit log, or changelog fragments.
4. Format target — Markdown CHANGELOG.md (Keep a Changelog style), a GitHub Release body, a blog-style announcement, or in-app "What's New". If any are missing, ask once, concisely. Do not block on perfect input — infer sensible defaults and state your assumptions.

Workflow

1. Collect changes. If given a git range, run the helper: python scripts/parse_commits.py --range v2.3.0..HEAD (or pipe git log). It parses conventional commits, groups them, and flags !/BREAKING CHANGE as breaking. Review its output — never publish it raw.
2. Filter noise. Drop chore/ci/build/refactor/test/docs commits that have zero user impact. Merge duplicates and revert+reland pairs. Keep anything a user can see, feel, or must react to.
3. Categorize every surviving change into exactly one of: Breaking Changes, Features (✨ new), Improvements (⚡ enhancements/perf/UX), Bug Fixes (🐛), Deprecations, Security. Use the decision table in references/categorization.md.
4. Rewrite each line into the user-facing voice: lead with the benefit/outcome, present tense, active voice, no internal jargon, no PR/branch names in prose. Append issue/PR references in parentheses. See the rewrite patterns below and references/style-guide.md.
5. Determine the version bump from the highest-severity category present (breaking → major, feature → minor, fix-only → patch). State it.
6. Write the Breaking Changes + Migration section first if any exist — this is the highest-value content. Give before/after and concrete migration steps.
7. Assemble using templates/changelog-entry.md (for CHANGELOG.md) or templates/github-release.md (for a release body). Add a one-line highlight summary at the top.
8. Self-check against references/checklist.md. Verify ordering (Breaking → Security → Features → Improvements → Fixes → Deprecations), no empty sections, every breaking change has migration guidance, and links resolve.

Rewrite patterns (commit -> note)

Raw input	Rewritten user-facing note
fix: npe in auth when token nil	Fixed a crash that occurred when signing in with an expired session. (#412)
feat(api): add cursor pagination to /users	The /users endpoint now supports cursor-based pagination for faster, stable listing of large datasets. (#388)
perf: cache config lookups	Configuration screens now load up to 40% faster. (#401)
feat!: rename --output to --out	Breaking: The --output flag is renamed to --out. Update scripts accordingly. (#420)

Rules: describe the effect on the user, not the code path. Quantify when you can. One sentence per item where possible.

Voice and style (essentials)

• Present tense, active voice: "Adds…", "Fixes…", or noun-led "New export option for…".
• Second person for instructions ("You can now…"), never first person ("We added…") in changelogs; the announcement format may use "we".
• No internal identifiers (service names, ticket-only codes, engineer names) in user notes.
• Consistent terminology — pick one product noun and reuse it.
• Full detail lives in references/style-guide.md.

Best Practices

• Lead with breaking changes and highlights. Readers skim; put what forces action up top.
• One change, one line. Split multi-purpose PRs into separate notes.
• Quantify improvements ("2x faster", "30% smaller bundle") whenever metrics exist.
• Always pair a breaking change with a migration step. A breaking change with no "what to do" is a support ticket waiting to happen.
• Link everything — PR/issue numbers, docs, migration guides.
• Match semver to content. If you wrote breaking changes under a patch bump, the bump is wrong.
• Keep an Unreleased section in CHANGELOG.md so notes accrue continuously.

Common Pitfalls

• Copying commit messages verbatim (implementation jargon, no benefit).
• Burying a breaking change inside "Improvements".
• Mixing audiences — dumping API-internal changes into end-user notes.
• Empty category headers, or every change dumped under "Other".
• Vague entries: "Various bug fixes and improvements" with nothing actionable.
• Forgetting the date, version, or comparison link (v2.3.0...v2.4.0).
• Listing reverted-then-reapplied changes twice.

Bundled files

• references/style-guide.md — voice, tense, terminology, emoji policy, and good/bad examples.
• references/categorization.md — decision table for category + semver, conventional-commit mapping.
• references/checklist.md — pre-publish QA checklist.
• scripts/parse_commits.py — parses a git range / commit log into categorized JSON or Markdown.
• templates/changelog-entry.md — Keep a Changelog style entry.
• templates/github-release.md — GitHub Release body template.
• examples/sample-release.md — full worked example from raw commits to finished notes.