JPeetz/agent-skills / skills/git-release/changelog-generator
changelog-generator
VerifiedUse this skill when cutting a release, generating CHANGELOG.md from commits, computing next semver version, or linting commit messages. Parses Conventional Commits to detect breaking changes, render Keep a Changelog sections, and enforce commit format in CI.
Changelog Generator
Overview
Turn a git history into a release document. This skill reads Conventional Commits, decides the semantic version bump they imply, and renders a Keep a Changelog entry — the same entry a consumer reads to decide whether upgrading is safe.
The work is mechanical, and that is the point: a changelog generated by rule from structured commits cannot quietly drop a breaking change, and a commit linter that runs before merge is what makes the structure reliable in the first place. Generation and enforcement are two halves of one loop.
When to Use
- Before publishing a release tag, to write the entry and pick the version
- In CI, to attach release notes to a GitHub/GitLab release automatically
- In PR checks, to block commit messages that cannot become release notes
- In a monorepo, to scope an entry to one package's commits
- When converting raw
git logoutput into user-facing notes
Do not use this skill to invent prose about a change that has no commit; a changelog entry must trace back to a commit that exists.
Core Capabilities
- Parse commit messages under Conventional Commit rules, including
type(scope)!:andBREAKING CHANGE:footers - Detect the semver bump implied by a commit stream (major / minor / patch / none)
- Group commits into Keep a Changelog sections
- Render either Markdown for
CHANGELOG.mdor machine-readable JSON for CI - Lint commit messages and exit non-zero on violations
Key Workflows
1. Generate an entry from a git range
python3 scripts/generate_changelog.py --from v1.4.0 --to HEAD
Reads git log in the current repository. Omit --from to use the most recent tag automatically; if there is no tag, the whole history is used.
2. Compute the next version without writing anything
python3 scripts/generate_changelog.py --from v1.4.0 --next --format json
Prints the bump and the resulting version. Use this in a release job to set the tag name before drafting the entry.
3. Generate an entry from a file or stdin
git log --format='%s%n%b%n---COMMIT---' v1.4.0..HEAD \
| python3 scripts/generate_changelog.py --input - --version 1.5.0
Any input where commits are separated by a blank line and a ---COMMIT--- marker works, so the script never needs to shell out when the caller already has the log.
4. Prepend the entry to CHANGELOG.md
python3 scripts/generate_changelog.py --from v1.4.0 --version 1.5.0 --update CHANGELOG.md
--update prepends under the # Changelog heading and leaves every existing section untouched. It refuses to write a version that is already present.
5. Lint commits before merge
python3 scripts/commit_linter.py --range origin/main..HEAD
Exit code 1 on any violation, with the offending message and the reason. See references/ci-integration.md for wiring this into a pipeline.
Conventional Commit Rules
Format: <type>(<scope>): <description>
| Type | Meaning | Section |
|---|---|---|
feat | New capability | Added |
fix | Bug fix | Fixed |
perf | Performance improvement | Changed |
refactor | Restructure, same behavior | Changed |
docs | Documentation only | Documentation |
test | Tests only | (omitted by default) |
build | Build system or dependencies | Changed |
ci | CI configuration | (omitted by default) |
chore | Maintenance | (omitted by default) |
security | Security fix | Security |
deprecated | Marks something for removal | Deprecated |
remove | Removes a capability | Removed |
revert | Reverts a prior commit | Changed |
Breaking changes are declared one of two ways, and both are honored:
feat(api)!: drop the v1 tasks endpoint
feat(api): drop the v1 tasks endpoint
BREAKING CHANGE: clients must migrate to GET /v2/tasks.
SemVer mapping:
any breaking change → major
any feat, no breaking → minor
anything else → patch
no releasable commits → no bump (do not cut a release)
A commit stream containing only chore and test commits produces no entry. Cutting a release for it would tell consumers something changed when, from their side, nothing did.
Commit Quality Standard
A commit message is acceptable when it can become a changelog line without being rewritten by hand:
feat(billing): add proration for mid-cycle plan changes
Not acceptable:
fixed stuff
update code
wip
WIP: almost done
The linter checks structure, not taste. It will pass feat: add thing — it cannot know whether add thing is a good description. That judgment stays with the author and the reviewer. What the linter guarantees is that every merged commit is eligible to be parsed, which is the precondition for generation being trustworthy.
Handling Breaking Changes
Every major bump needs migration guidance. A changelog that says "removed v1 endpoints" without saying what to call instead is a support ticket generator. When a BREAKING CHANGE: footer exists, include it verbatim under the Changed section as a **BREAKING:** bullet — the footer is where authors write the migration path, so it is the one piece of text that must survive generation unedited.
Common Pitfalls
- Parsing merge commits as features.
Merge pull request #42 from ...is not a Conventional Commit and must be skipped, not coerced into a changelog line. Both scripts ignore messages starting withMerge. - Vague summaries that cannot become release notes. If generation produces "fix: improve things", the failure is upstream in the commit message.
- Omitting migration guidance for breaking changes. The
!marker tells you a bump is major; only the footer tells the consumer what to do. - Overwriting historical sections. Prepend, never rewrite. History is append-only, and a changelog that loses old entries is worse than no changelog.
- Releasing on non-releasable commits. Chore-only ranges get no bump. Bumping the patch version for internal cleanup trains consumers to ignore version numbers.
- Reaching for a tag that does not exist. If
--fromnames an unknown ref, fail loudly rather than silently generating an entry from all of history.
Verification
Before publishing an entry:
- The version matches the bump the commits imply (breaking → major, feat → minor, else patch)
- No merge commits or
chorenoise leaked into the rendered sections - Every breaking change has a migration note taken from its footer
- The date is the release date, not the date of the newest commit
- Existing changelog sections are intact below the new entry
- The tag you are about to create matches the version in the heading
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |