Guides

Generating changelogs and release notes with Claude Code

Release notes are a good fit for Claude Code: the raw material (commits, merged PRs, diffs) is already in git, and the job is turning it into something a user can read. The risk is a confident summary of changes that didn't happen, so the recipes below feed Claude real git output and ask it to cite what it used.

The basic prompt

Inside a session in your repo, start with the range you want covered:

Write release notes for everything since the last tag.
1. Run `git describe --tags --abbrev=0` to find it, then `git log <tag>..HEAD --no-merges --format='%h %s'`.
2. Read the diff for any commit whose message is unclear.
3. Group into: Added, Changed, Fixed, Removed. Skip refactors, CI and test-only changes.
4. Write for users, not maintainers: say what changed for them, not which files moved.
5. Mark any breaking change clearly at the top.
6. Don't invent anything. If you can't tell what a commit does, list it under "Needs review".

Make it a reusable slash command

Save this as .claude/commands/release-notes.md (or as a skill at .claude/skills/release-notes/SKILL.md, the recommended format for new work). Running /release-notes v1.4.0 passes v1.4.0 in as $ARGUMENTS. The !`...` lines run before Claude sees the prompt, so it receives real git output instead of guessing.

---
description: Draft release notes since a given tag
argument-hint: [previous-tag]
allowed-tools: Bash(git log *) Bash(git diff *) Bash(git describe *)
---

## Commits since $ARGUMENTS
!`git log $ARGUMENTS..HEAD --no-merges --format='%h %an %s'`

## Files changed
!`git diff $ARGUMENTS..HEAD --stat | tail -40`

## Your task
Draft release notes for users from the commits above.
- Sections: Breaking changes, Added, Changed, Fixed.
- One line per change, plain language, no commit hashes in the output.
- Skip refactors, dependency bumps, CI and test-only commits.
- If a commit is ambiguous, read its diff with `git show <hash>` before describing it.
- Anything you still can't classify goes under "Needs review". Never guess.

For more on command and skill files, see custom slash commands.

One-liner for scripts and CI

Non-interactive mode (-p) reads stdin, so you can pipe the log straight in and write the result to a file:

git log "$(git describe --tags --abbrev=0)"..HEAD --no-merges --format='%h %s' \
  | claude -p "Write user-facing release notes from these commits. Group into Added, Changed, Fixed. Skip internal-only changes. Don't invent details." \
  > RELEASE_NOTES.md

Piping the data in means Claude needs no Bash permission at all. If you want it to inspect diffs itself, pre-approve only read-only git commands, using the same prefix-matching syntax as permission rules:

claude -p "Draft release notes since v1.4.0" \
  --allowedTools "Bash(git log *),Bash(git diff *),Bash(git show *)" \
  > RELEASE_NOTES.md

In CI, consider adding --bare so every run starts without loading hooks, plugins or CLAUDE.md from the host machine (it then needs ANTHROPIC_API_KEY rather than a subscription login). For a full pipeline, see Claude Code in CI with GitHub Actions.

Changelog file versus release notes

	CHANGELOG.md	Release notes
Audience	Developers and integrators	End users, customers
Detail	Every notable change, with PR links	Highlights, in plain language
Format	Keep a Changelog sections, newest on top	Short narrative plus a list
Prompt tip	"Prepend a new section, don't rewrite old ones"	"Lead with what users will notice"

To update an existing file safely:

Add a "## [Unreleased]" section at the top of CHANGELOG.md for commits since the
last tag, matching the existing format exactly. Do not edit any older entries.

Keep the output accurate

• Feed it real data. Commit messages like "fix stuff" produce vague notes. Reading the diff for unclear commits is worth the extra tokens.
• Use PR titles if you have them. With the GitHub CLI installed, gh pr list --state merged --search "merged:>2026-09-01" --json number,title gives cleaner input than commit subjects.
• Review the diff of the notes. Treat the draft like any other generated change: read it, check the breaking-changes section against the code, then commit.
• Ask for "Needs review". A visible bucket for uncertain items beats a smooth but wrong sentence.
• Don't paste secrets. Internal commit messages sometimes mention customers or keys. Skim the log before publishing the output.

Run it automatically

If you want a draft every time you tag a release, wire the one-liner into your release script or CI job. To trigger something inside a Claude Code session instead, such as reminding yourself to update the changelog before a commit, the free hook builder generates the hook configuration for you.