| name | release-notes |
| description | Use when the user asks to draft release notes, write release notes, or summarize changes since the last release for the current repository. |
Release Notes
Write release notes for all the changes in the current repo's main (or master) since the last release.
Rules
- Use ASCII characters ONLY. No smart quotes, em dashes, ellipses, arrows, bullets, accented letters, or any other non-ASCII glyph. Use
-, ', ", ... instead.
- DO NOT mention Linear issues. Do not include
DEV-... identifiers or links to linear.app.
- Do not insert line breaks just to keep line length under some limit. Only break lines between paragraphs to keep natural flow. Each paragraph or bullet should be a single line.
- DO NOT try to imitate the style of past release notes. Their style may be no longer relevant.
- Keep the notes brief and succinct, especially for minor releases.
- Write the notes into an
.md file in the repo root.
Style: write for users, not maintainers
The audience is the people who use this repo's library/tool/service, not the people who contribute to it. Default to short, plain-English prose.
- Open with a one-line vibe-setter that frames the release ("A small quality-of-life release for people writing model SQL", "Bug-fix release for the auth flow", etc.). Skip it for major releases that need a real intro.
- Use second-person framing. "You can now ...", "If you ...", "your model", "your config". Describe what changed in terms of something the user can directly do or observe.
- Use the user's vocabulary, not the codebase's. Say "circular references between columns" instead of
ColumnCycleError; say "when you save the model" instead of storage.save_model. Examples should use realistic user-facing names (orders.bucket), not internal placeholders (<host>.<col>).
- Skip internal-only commits entirely. Refactors for cognitive complexity, test-fixture deduplication, internal renames, CI/quality-gate fixes do not belong in release notes - not even in
<details>. If a change has no effect anyone outside the repo can observe, omit it.
<details> is for implementation context, not for spillover. Use it only when there's genuine implementation-level context that downstream maintainers/integrators (not end users) need - class names, exception hierarchies, template methods, migration semantics. Label it <summary>Additional technical details</summary>. If there's nothing to say there, omit the block.- Prefer paragraphs over bullet lists unless the changes are genuinely a list of independent items. Two short paragraphs beat five terse bullets.
- Default to under ~150 words of body prose for a minor/patch release. If the draft is longer, ask whether anything can be cut before writing.
Steps
-
Identify the default branch (main or master) and the previous release. Prefer git describe --tags --abbrev=0 for the last tag; fall back to inspecting gh release list if tags are not used.
-
Collect the changes since that release using git log <last-tag>..HEAD --no-merges on the default branch. Read commit subjects and bodies; for non-trivial commits, also inspect the diff.
-
Determine the next version number from context (commits, package files, prior tags). If unclear, ask the user.
-
Draft the notes following the rules above. Group related changes; lead with user-visible features and fixes.
-
Write the notes to a new .md file in the repo root (e.g. RELEASE_NOTES_<version>.md, or append to an existing CHANGELOG.md if the repo uses one - check first).
-
Run the validator on the written file:
python ~/.claude/skills/release-notes/scripts/validate.py <path-to-file>
If the validator reports issues, fix them and re-run until it passes. Do not report the task as done until validation passes.
Validator
The validator checks for:
- non-ASCII characters (with line/column and the offending char)
- links to
linear.app (any URL containing that host)
- the literal string
DEV- (the typical Linear workspace prefix used in this org)
Exit code 0 = clean. Non-zero = problems found; details are printed to stdout.
