Skip to content

JPeetz/agent-skills / skills/git-release/changelog-generator

changelog-generator

Verified

Use 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 log output 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)!: and BREAKING 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.md or 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>

TypeMeaningSection
featNew capabilityAdded
fixBug fixFixed
perfPerformance improvementChanged
refactorRestructure, same behaviorChanged
docsDocumentation onlyDocumentation
testTests only(omitted by default)
buildBuild system or dependenciesChanged
ciCI configuration(omitted by default)
choreMaintenance(omitted by default)
securitySecurity fixSecurity
deprecatedMarks something for removalDeprecated
removeRemoves a capabilityRemoved
revertReverts a prior commitChanged

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

  1. 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 with Merge .
  2. Vague summaries that cannot become release notes. If generation produces "fix: improve things", the failure is upstream in the commit message.
  3. Omitting migration guidance for breaking changes. The ! marker tells you a bump is major; only the footer tells the consumer what to do.
  4. Overwriting historical sections. Prepend, never rewrite. History is append-only, and a changelog that loses old entries is worse than no changelog.
  5. Releasing on non-releasable commits. Chore-only ranges get no bump. Bumping the patch version for internal cleanup trains consumers to ignore version numbers.
  6. Reaching for a tag that does not exist. If --from names 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 chore noise 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
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexUnverifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall