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.
| File | Kind | Size |
|---|---|---|
| CHANGELOG.md | markdown | 673 B |
| LICENSE | other | 1.1 KB |
| SKILL.md | skill md | 7.1 KB |
| evals/evals.json | config | 3.9 KB |
| references/ci-integration.md | markdown | 6.6 KB |
| scripts/commit_linter.py | script | 10.6 KB |
| scripts/generate_changelog.py | script | 15.1 KB |
SKILL.md
View on GitHub---
name: changelog-generator
description: 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.
author: Alireza Rezvani (alirezarezvani), Skill Foundry
version: 0.1.0
license: MIT
platforms:
- linux
- macos
- windows
category: git-release
---
# 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](https://keepachangelog.com/en/1.1.0/) 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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
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
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: 472k | 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 |