release-notes

name	release-notes
description	Draft a changelog for the next release by summarizing git commits since the last tag. Use only when the user asks to draft release notes, write a changelog entry, or prepare the next version's notes — never trigger automatically.
model	inherit
color	plum

Release Notes

Draft a release changelog by summarizing the commits since the last release, then suggest the next semver version and prepend the entry to CHANGELOG.md at the project root.

Steps

1. Find the commit range and version baseline. Determine the last released tag:

   git describe --tags --abbrev=0 2>/dev/null
   

   • If a tag exists, the range is <tag>..HEAD, and the tag itself is the version baseline.
   • If no tag exists (fresh repo), use the full history and ask the developer for the current version — do not infer it from any manifest, lockfile, or config file belonging to the project. This skill only reads git; it never inspects a project's toolchain.

2. Collect the commits in the range:

   # with a tag:
   git log <tag>..HEAD --oneline --no-merges
   # without a tag:
   git log --oneline --no-merges
   

3. Group the commits by type, inferring the type from the message (Conventional Commits prefix if present, otherwise from the wording):

   • Features — new functionality (feat, "Add", "Support")
   • Fixes — bug fixes (fix, "Fix", "Correct")
   • Chores / Maintenance — chore, refactor, docs, deps, tooling
   • Drop noise (pure formatting/typo commits) or fold them into a related entry.

4. Suggest the next version from the baseline established in Step 1 (the tag, or the version the developer gave you), using semver:

   • Breaking changes → major
   • Any new feature → minor
   • Only fixes/chores → patch

   State the bump explicitly (e.g. 1.1.0 → 1.2.0) and the one reason for it.

5. Draft the release entry in this shape (omit empty sections):

   ## v<next-version> — <YYYY-MM-DD>
   
   ### Features
   - <user-facing summary> (<short-sha>)
   
   ### Fixes
   - <user-facing summary> (<short-sha>)
   
   ### Maintenance
   - <user-facing summary> (<short-sha>)
   

6. Write the entry to CHANGELOG.md at the project root:

   • If CHANGELOG.md does not exist, create it with a top-level heading:

     # Changelog
     

   • Read the current contents of CHANGELOG.md.
   • Prepend the new entry (insert it immediately after the # Changelog heading line, before any existing entries) so the file stays newest-first.
   • Write the updated file.

   Use the Read and Write (or Edit) tools to do this — do not shell out to sed or awk.

7. Report to the user what was written: show the new entry inline and confirm the file was updated.

Notes

• Write entries from the user's perspective (what changed for them), not a verbatim commit-message dump.
• Include today's date (from the currentDate context, or date +%Y-%m-%d) in the entry heading.

You Must NOT

• Create, move, or push a git tag — the tag is the developer's release action, not yours.
• Bump the version in any manifest, lockfile, or config file. This skill records what changed; it does not perform the release.
• Push anything, or open a PR. The CHANGELOG.md edit stays in the working tree.
• Infer the current version from a project manifest when no tag exists — ask the developer instead. The version baseline is git's, never the toolchain's.
• Rewrite, reorder, or delete existing CHANGELOG.md entries — only prepend the new one.