Draft Release Notes
Use this skill to draft or update the [Unreleased] section of CHANGELOG.md from the actual changes since the last tag. Run this at any point during development to keep a working copy of the release narrative. Does NOT bump versions or create tags.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Draft Release Notes when an AI agent needs a reusable SKILL.md workflow for this job: Use this skill to draft or update the [Unreleased] section of CHANGELOG.md from the actual changes since the last tag. Run this at any point during development to keep a working copy of the release narrative. Does NOT bump versions or create tags.
When not to use it
Skip Draft Release Notes when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/draft-release-notes # Save SKILL.md to ~/.claude/skills/draft-release-notes/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/draft-release-notes/SKILL.md. For a shared project, commit the folder at .claude/skills/draft-release-notes/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Draft Release Notes skill for this task: Identify the last release tag and gather changes. Confirm any required inputs or files before making changes.
What supports this recommendation?
83/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 92/100
- Practical detail
- 92/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Draft Release Notes
## Goal
Update the `[Unreleased]` section at the top of `CHANGELOG.md` with a narrative release story based on the real changes since the last tag. This is a **non-destructive working copy** — run it as many times as you want during development.
## Workflow
1. **Identify the last release tag and gather changes.**
```bash LAST_TAG=$(git tag --list "v*" --sort=-v:refname | head -n 1) echo "Last tag: $LAST_TAG" ```
Then collect raw material from three sources:
a. **Commit log since last tag:** ```bash git log --oneline "$LAST_TAG"..HEAD ```
b. **GitHub-generated release notes preview** (PR titles, new contributors): ```bash gh api repos/:owner/:repo/releases/generate-notes \ -f tag_name="vNEXT" \ -f target_commitish="$(git rev-parse HEAD)" \ -f previous_tag_name="$LAST_TAG" \ --jq '.body' ```
c. **Diff stat for theme analysis:** ```bash git diff --stat "$LAST_TAG"..HEAD ```
2. **Draft the release narrative.**
Write markdown for the `[Unreleased]` section following the format below. Do not include the `## [Unreleased]` heading itself — just the body content.
3. **Update CHANGELOG.md.**
Replace everything between `## [Unreleased]` and the next `## [` heading with the new draft. Preserve the HTML comment header and all existing release sections below.
The `[Unreleased]` section must always exist and always be the first section after the header comments.
4. **Do NOT commit, tag, or bump versions.** Just leave the file modified in the working tree.
## Release Story Format
Structure the `[Unreleased]` section like this:
```markdown ## [Unreleased]
<One strong opening paragraph: what this release is about and why it matters. Tie it to concrete shipped changes. No vague hype.>
<One paragraph on major technical shifts, if applicable.>
### <Feature/Theme Group> - Bullet points with specifics - Reference PRs where available: ([#123](https://github.com/jamiepine/voicebox/pull/123))
### <Another Group> - ...
### Bug Fixes - ... ```
### Style Guidelines
- **Factual and specific.** Every claim should trace to a real commit or PR. - **Narrative over list.** Lead with paragraphs that tell the story, then support with bullets. - **Group by theme, not by commit.** Cluster related changes under descriptive headings. - **Reference PRs** where they exist, but don't fabricate them. - **Skip trivial chores** (typo fixes, CI tweaks) unless they're the bulk of the release. - **Match the voice of existing releases** — look at the v0.2.1 and v0.2.3 entries in CHANGELOG.md for tone reference.
## When There Are No Changes
If `git log "$LAST_TAG"..HEAD` is empty, leave the `[Unreleased]` section empty (just the heading) and tell the user there's nothing to draft.
## Notes
- This skill only touches the `[Unreleased]` section. It never modifies stamped release sections. - The agent can be asked to run this skill at any point — mid-feature, before a PR, or right before cutting a release. - The `release-bump` skill depends on this draft being up to date before it finalizes.
Intended uses
- Identify the last release tag and gather changes.
- Draft the release narrative.
- Update CHANGELOG.md.
- Do NOT commit, tag, or bump versions. Just leave the file modified in the working tree.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.