Generate user-facing release notes from technical change information (commits, PRs, diffs, branch comparisons, or raw text). Goes deep — follows commit references to PRs, issues, and bug reports to understand the full story behind each change, then produces narrative prose that communicates what changed and why it matters. Works with GitHub, GitLab, and Jira. Use this skill whenever the user asks for release notes, changelogs, "what's new" summaries, or wants to communicate changes to users, stakeholders, or customers — even if they just say "write up what changed" or "summarize the release."
From cata-helpersnpx claudepluginhub niekcandaele/claude-helpers --plugin cata-helpersThis skill uses the workspace's default tool permissions.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Guides idea refinement into designs: explores context, asks questions one-by-one, proposes approaches, presents sections for approval, writes/review specs before coding.
Generate user-facing release notes from: $ARGUMENTS
Release notes are for humans, not machines. The goal is to communicate what changed and why it matters — at the level your audience cares about. A commit documents code evolution; a release note documents significance to the user.
Detect what the user provided and gather the raw change data accordingly.
Version/tag range (matches v1.2.0..v1.3.0 or 1.2..1.3):
git log --format='%H %s' $RANGE
git log --format='%B---COMMIT_BOUNDARY---' $RANGE
git diff --stat $RANGE
Branch comparison (matches main..feature or origin/main..HEAD):
git log --format='%H %s' $RANGE
git log --format='%B---COMMIT_BOUNDARY---' $RANGE
git diff --stat $RANGE
PR numbers (matches #42, #43, etc.):
gh pr view <num> --json title,body,commits,labels
Raw text: If the input doesn't match any pattern above, treat it as a direct description of changes. Skip git commands and work from the text. Also skip Steps 2 and 3 — go straight to Step 4.
No arguments: Compare current branch against base:
CURRENT_BRANCH=$(git branch --show-current)
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
# Fallback: try main, master, develop
git log --format='%H %s' $DEFAULT_BRANCH..$CURRENT_BRANCH
git log --format='%B---COMMIT_BOUNDARY---' $DEFAULT_BRANCH..$CURRENT_BRANCH
git diff --stat $DEFAULT_BRANCH..$CURRENT_BRANCH
Figure out where this project lives and where its issues are tracked. These can be different — a project might host code on GitHub but track issues in Jira.
Parse the git remote to detect the platform:
git remote get-url origin
github.com → GitHub, use gh CLIgitlab.com (or a custom GitLab domain) → GitLab, use glab CLIScan the commit messages gathered in Step 1 for reference patterns:
#123 style references → issues live on the code host (GitHub or GitLab)PROJ-123 style references (uppercase letters, dash, number) → Jira. Use the Atlassian MCP tools if available (mcp__claude_ai_Atlassian__getJiraIssue)If the platform tools aren't available or authentication fails, fall back gracefully to git-only mode. Don't block on this.
This is what turns a commit log paraphrase into real release notes. Commits tell you what changed in code. PRs tell you why it was done. Issues tell you who asked for it and what problem they had. All three are important.
Scan every commit message from Step 1 for:
#123 (GitHub), !123 (GitLab)#456 (GitHub/GitLab), PROJ-789 (Jira)Deduplicate — many commits reference the same PR. Build a unique list of PRs and issues to fetch.
For each unique PR reference:
GitHub:
gh pr view <num> --json title,body,closingIssuesReferences,labels,commits
GitLab:
glab mr view <num> --output json
Read the PR description carefully — this is where developers explain:
For each issue referenced by PRs (via closingIssuesReferences on GitHub, or mentioned in PR/commit text):
GitHub:
gh issue view <num> --json title,body,labels
GitLab:
glab issue view <num> --output json
Jira:
Use mcp__claude_ai_Atlassian__getJiraIssue with the issue key (e.g., PROJ-789).
Issue bodies are where the real context lives — user stories, bug reports with reproduction steps, feature requests explaining what users need and why. This is gold for writing release notes that speak to users.
For each logical change, you now have up to three layers of context:
Not every change will have all three. Some commits won't reference a PR. Some PRs won't link to issues. Use whatever is available — even one layer deeper than the commit message dramatically improves the release notes.
For releases with many commits (50+), focus your lookups on unique PRs — most commits map back to a small number of PRs. If there are too many to fetch individually, prioritize:
breaking, security, or feature labelsBefore writing anything, understand who will read these notes. Scan the repo quickly:
package.json, Cargo.toml, pyproject.toml, go.mod, or README.md to determine if this is a library, CLI tool, web app, API, framework, or pluginCHANGELOG.md, CHANGES.md, or HISTORY.md. If one exists, read its most recent entry and match its conventions (heading style, entry format, tone)This context shapes every decision in the next steps — a library's notes can mention API changes directly, while an end-user app's notes should describe outcomes, not implementation.
This is the core transformation — turning code changes into user-facing communication. Use the full context map from Step 3, not just commit messages.
Skip changes that don't affect users:
Multiple commits that implement one feature or fix become one entry. Look for:
Scan for these signals — breaking changes must never be buried:
BREAKING CHANGE: or BREAKING: in commit bodies! after the type in conventional commits (e.g., feat!:)breaking, breaking-change on PRsThis is where the deep dive pays off. Instead of just rephrasing commit messages, use the richer context:
Examples of the transformation:
The release notes should read as short narrative prose — a few paragraphs that tell the story of the release. Not a bullet list, not a categorized changelog. The raw commit/PR list already exists; the point of this skill is to produce something different: a human summary that someone can read in 30 seconds and understand what changed and why it matters.
Group related changes into short paragraphs by theme. A natural flow is:
Not every release needs all four sections. A small patch release might be a single paragraph. A major release might need five or six. Let the content dictate the shape.
If the release has breaking changes, lead with them before everything else. Be direct about what changed and what the user needs to do. This is the one place where a short bullet list is appropriate — breaking changes need to be scannable and unmissable.
Here's what good narrative release notes look like:
**v0.5.0** introduces Shop Actions, a new module component type that lets you
create automated actions triggered by shop purchases — opening up new
possibilities for your in-game economy. You can now also react to player
inventory changes through hook events, enabling modules for loot tracking,
item-based triggers, and more.
On the infrastructure side, events are now stored in ClickHouse, which means
faster queries and better scalability as your player count grows. If you're
migrating from CSMM, you can now import your shop listings directly.
This release also fixes several reliability issues — database connection pool
exhaustion that could occur around midnight, cronjob failures under high load,
and a handful of UI bugs including the version number incorrectly showing as
"0.0.0".
Notice: no bullet lists, no category headers, no "Added/Fixed/Changed" taxonomy. Just clear prose that a user can read and understand.
Present the release notes directly in the conversation. Do not write to a file unless the user explicitly asks — and if they do, ask where they want it (CHANGELOG.md, RELEASE_NOTES.md, etc.).
When writing to a GitHub release or file, structure it as:
---)