Draft Release Notes

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

1. 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.
2. 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.
3. 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

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.