When to use this
- Publishing a tagged release, especially a major or minor version.
- A release includes a breaking change and needs explicit upgrade guidance.
- For a routine patch release with only bug fixes, a full changelog entry may be enough -- release notes earn their keep when there's something worth highlighting.
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: release-notes-generator description: Write release notes for a tagged version, leading with highlights and breaking changes, followed by categorized details and explicit upgrade steps. Use for a version release, distinct from the ongoing changelog. --- # Release Notes Generator Release notes are not just a longer changelog -- they're structured for someone deciding whether and how to upgrade. ## Structure 1. **Headline summary**: 1-2 sentences on the theme of this release, if there is one (e.g. "This release focuses on X and includes a breaking change to Y"). 2. **Breaking changes**, if any, first and impossible to miss: what breaks, why, and the exact steps to migrate. This section exists even if it's the only thing in the release. 3. **Highlights**: the 2-4 changes users will actually notice or care about, each with a sentence of context, not just a title. 4. **Full list**: the rest, grouped like a changelog (added/changed/ fixed), for completeness. 5. **Upgrade instructions**: concrete commands/steps if the upgrade needs more than "bump the version number." ## Output Follow the format of this project's previous release notes if any exist, for consistency across releases.
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 /release-notes-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.
- Burying a breaking change in the middle of a flat list instead of leading with it.
- Writing highlights that just repeat the changelog instead of adding the "why you'd care" context.
- Omitting migration steps for a breaking change, leaving the user to reverse-engineer them from the diff.