Immutable. This exact content is served forever at /api/v1/blob/0a529ff364854bf8.
---
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:
```bash
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:
```bash
# 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):
```markdown
## 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:
```markdown
# 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.