When to use this
- Cutting a release and the changelog needs updating.
- Consolidating a batch of merged PRs into one changelog section.
- Not for internal-only engineering notes -- this is user/consumer-facing; keep pure refactors and internal tooling changes out unless they affect the consumer.
The skill file
Copy this verbatim. It's written in the SKILL.md format (YAML frontmatter + markdown instructions) that Claude Code, and increasingly other agent tools, read directly.
--- name: changelog-generator description: Generate a user-facing changelog entry from a range of commits or merged PRs, grouped by category (added/changed/fixed/removed) and written for the software's consumer, not its authors. Use when preparing a release. --- # Changelog Generator ## Audience check Every entry should answer "what does this mean for someone using the software," not "what did the code change." A commit like "refactor internal cache layer" produces no changelog entry unless it changes observable behavior (e.g. performance, an API response shape). ## Process 1. `git log <previous-tag>..<new-tag/HEAD> --oneline` (or the list of merged PRs) to get the full range. 2. Filter out anything with no user-visible effect: internal refactors, test-only changes, CI/tooling changes, dependency bumps with no behavior change. 3. Group what remains into standard categories: **Added**, **Changed**, **Fixed**, **Removed/Deprecated**, **Security**. 4. Rewrite each surviving item in plain, user-facing language -- translate from "fix null check in getUserSettings" to "fixed a crash that could occur when loading settings for a new account." ## Output Follow this repo's existing `CHANGELOG.md` format and heading convention if one exists; otherwise use Keep a Changelog style (version header, date, the category groups above).
Installing it elsewhere
The frontmatter/body split above is Claude Code's convention. Here's how to carry the same instructions into other tools:
Save the file below verbatim (frontmatter included) at that path, project-local or in ~/.claude/skills/ for a user-level skill. Claude Code loads the name/description pair to decide when to pull it in, or you invoke it directly as /changelog-generator.
Convert the YAML frontmatter to Cursor's rule format (description, globs, alwaysApply: false) and keep the markdown body as the rule content. Cursor surfaces it by description match, same idea as Claude Code's auto-load.
Codex CLI (and increasingly other agentic CLIs) read AGENTS.md at the repo root as always-on instructions. Paste the markdown body under a heading like ## {title}; for GitHub Copilot's coding agent, the equivalent file is .github/copilot-instructions.md.
Append the markdown body to .windsurfrules at the repo root. Windsurf treats the whole file as always-on context, so keep only the instructions you want applied on every request.
- Including pure internal refactors, CI changes, or test-only commits that have no user-visible effect.
- Leaving entries in engineer-speak ("fixed null check in X") instead of translating to user impact.
- Missing a breaking change buried in a routine-sounding commit message -- read the diff, not just the message, for anything that touches a public API.