changelog-writer
Generate changelogs, release notes, and migration guides from git history. Parse conventional commits. Use for releases. NOT for git ops (git-workflow) or doc sites (docs-steward).
changelog-writer
1044 words
MIT
v1.0
wyattowalsh
sonnet
Custom
Terminal window
SKILL.md
Generate changelogs, release notes, and migration guides from git history. Parse conventional commits. Use for releases. NOT for git ops (git-workflow) or doc sites (docs-steward).
Quick Start
Section titled “Quick Start”Install:
npx skills add wyattowalsh/agents/skills/changelog-writer -gUse: /changelog-writer <mode> [version]
Works with Claude Code, Gemini CLI, and other agentskills.io-compatible agents.
What It Does
Section titled “What It Does”Generate changelogs, release notes, breaking change summaries, migration guides, and version bump recommendations from git history.
| $ARGUMENTS | Mode |
|---|---|
Empty / generate | Generate changelog from recent commits |
release <version> | User-facing release notes for specific version |
breaking | Breaking change detection and summary |
migration <from> <to> | Migration guide between two versions |
bump | Semantic version recommendation based on changes |
| Unrecognized input | Ask for clarification, show mode menu |
Critical Rules
Section titled “Critical Rules”- Never modify git history or run git operations beyond
git logandgit tag— this skill reads only - Always run
commit-classifier.pybefore formatting — do not manually parse git log - Breaking changes must be prominently called out in every output format
- Rewrite commit messages into user-readable language — raw commit text is not a changelog
- Migration guides must include before/after code examples for every breaking change
- Version bump recommendations must cite specific commits as evidence
- When commits are non-conventional, classify by best-effort heuristics and flag uncertainty
- Do not generate changelogs for uncommitted changes — only committed history
- Always identify the previous tag as the baseline unless the user specifies otherwise
- Credit contributors in release notes — extract from git log author fields
| Field | Value |
|---|---|
| Name | changelog-writer |
| License | MIT |
| Version | 1.0 |
| Author | wyattowalsh |
| Field | Value |
|---|---|
| Model | sonnet |
| Argument Hint | [mode] [version] |
View Full SKILL.md
---name: changelog-writerdescription: >- Generate changelogs, release notes, and migration guides from git history. Parse conventional commits. Use for releases. NOT for git ops (git-workflow) or doc sites (docs-steward).argument-hint: "<mode> [version]"license: MITmodel: sonnetmetadata: author: wyattowalsh version: "1.0"---
# Changelog Writer
Generate changelogs, release notes, breaking change summaries, migration guides, and version bump recommendations from git history.
**Scope:** Changelog and release documentation only. NOT for git operations (git-workflow), documentation sites (docs-steward), or code review (honest-review).
## Dispatch
| $ARGUMENTS | Mode ||------------|------|| Empty / `generate` | Generate changelog from recent commits || `release <version>` | User-facing release notes for specific version || `breaking` | Breaking change detection and summary || `migration <from> <to>` | Migration guide between two versions || `bump` | Semantic version recommendation based on changes || Unrecognized input | Ask for clarification, show mode menu |
## Canonical Vocabulary
| Term | Definition ||------|-----------|| **conventional commit** | Commit following `type(scope): description` format || **change type** | Classification: feat, fix, refactor, perf, docs, chore, test, ci, build, style || **breaking change** | Backward-incompatible change, marked by `!` or `BREAKING CHANGE:` footer || **scope** | Component affected, in parentheses after type || **changelog entry** | Formatted line item in a changelog section || **release notes** | User-facing summary of changes for a version || **migration guide** | Step-by-step instructions to upgrade between versions || **semver bump** | major (breaking), minor (feat), patch (fix) recommendation || **unreleased** | Changes since the last tagged version |
## Mode 1: Generate Changelog
Default mode. Produces a Keep a Changelog formatted document.
### Step 1: Classify Commits
Run the commit classifier script:
```uv run python skills/changelog-writer/scripts/commit-classifier.py [--since <tag-or-date>] [--until <ref>] [--path <dir>]```
Parse the JSON output. The script classifies each commit by conventional type and detects breaking changes.
### Step 2: Format Changelog
Run the changelog formatter script:
```uv run python skills/changelog-writer/scripts/changelog-formatter.py --input <classified-json> [--format keepachangelog|github|simple]```
The script converts classified commits to formatted markdown. Default format: Keep a Changelog.
### Step 3: Review and Refine
- Group entries by section (Added, Changed, Deprecated, Removed, Fixed, Security)- Rewrite terse commit messages into user-readable descriptions- Merge related commits into single entries where appropriate- Ensure breaking changes are prominently called out
Format reference: read references/changelog-conventions.md
## Mode 2: Release Notes
`release <version>` produces polished, user-facing release notes.
### Step 1: Identify Scope
Determine the range: last tag to HEAD (or between two tags if version already tagged).
```bashgit log --oneline <previous-tag>..<version-or-HEAD>```
### Step 2: Classify and Group
Run `commit-classifier.py` with the appropriate `--since` and `--until` flags. Group by user impact, not commit type:
- **Highlights** — headline features (top 3-5)- **Improvements** — enhancements, performance gains- **Bug Fixes** — resolved issues- **Breaking Changes** — migration-required items (link to migration mode)- **Contributors** — credit contributors from git log
### Step 3: Write Release Notes
Rewrite technical commit messages into user-facing language. Reference: read references/changelog-conventions.md, section "Release Note Style."
## Mode 3: Breaking Changes
`breaking` scans for backward-incompatible changes.
### Step 1: Detect
Run the commit classifier with breaking-change focus:
```uv run python skills/changelog-writer/scripts/commit-classifier.py --breaking-only [--since <tag>]```
### Step 2: Enrich
For each breaking change:
1. Identify the affected API/interface2. Describe what changed and why3. Provide the before/after code pattern4. Assess blast radius (how many consumers affected)
Use patterns from `data/breaking-change-patterns.json` for language-specific detection.
### Step 3: Summarize
Output a breaking changes report with severity ranking (high/medium/low) based on blast radius and migration effort.
## Mode 4: Migration Guide
`migration <from> <to>` generates step-by-step upgrade instructions.
### Step 1: Collect Breaking Changes
Run commit classifier between the two versions:
```uv run python skills/changelog-writer/scripts/commit-classifier.py --breaking-only --since <from> --until <to>```
### Step 2: Generate Migration Steps
For each breaking change, produce:
1. **What changed** — old behavior vs new behavior2. **Action required** — exact steps to migrate3. **Code example** — before/after snippets4. **Verification** — how to confirm the migration worked
Order steps by dependency (changes that must happen first go first).
### Step 3: Compile Guide
Structure as a numbered checklist. Include a pre-migration checklist (backup, test suite green) and post-migration verification steps.
Reference: read references/changelog-conventions.md, section "Migration Guide Structure."
## Mode 5: Version Bump
`bump` recommends the next semantic version.
### Step 1: Analyze
Run the commit classifier:
```uv run python skills/changelog-writer/scripts/commit-classifier.py --since <last-tag>```
Read the `suggested_bump` field from the JSON output.
### Step 2: Report
Present the recommendation with evidence:
| Bump | Reason ||------|--------|| **major** | Breaking changes detected: list them || **minor** | New features without breaking changes || **patch** | Bug fixes and non-functional changes only |
Show the commit evidence supporting the recommendation. If commits are ambiguous (non-conventional format), flag uncertainty and ask for confirmation.
## Reference Files
Load ONE reference at a time.
| File | Content | Read When ||------|---------|-----------|| `references/changelog-conventions.md` | Keep a Changelog format, release note style, migration guide structure, semver decision tree | Formatting output in any mode || `references/commit-parsing.md` | Conventional commits parsing rules, breaking change detection heuristics | Understanding classifier output or edge cases |
| Data File | Content | Used By ||-----------|---------|---------|| `data/changelog-formats.json` | Format templates (Keep a Changelog, GitHub Releases, simple) | `changelog-formatter.py` || `data/breaking-change-patterns.json` | Language-specific breaking change detection patterns | `commit-classifier.py`, Mode 3 enrichment |
| Script | Purpose ||--------|---------|| `scripts/commit-classifier.py` | Parse git log, classify by conventional type, detect breaking changes || `scripts/changelog-formatter.py` | Convert classified commits JSON to formatted changelog markdown |
## Critical Rules
1. Never modify git history or run git operations beyond `git log` and `git tag` — this skill reads only2. Always run `commit-classifier.py` before formatting — do not manually parse git log3. Breaking changes must be prominently called out in every output format4. Rewrite commit messages into user-readable language — raw commit text is not a changelog5. Migration guides must include before/after code examples for every breaking change6. Version bump recommendations must cite specific commits as evidence7. When commits are non-conventional, classify by best-effort heuristics and flag uncertainty8. Do not generate changelogs for uncommitted changes — only committed history9. Always identify the previous tag as the baseline unless the user specifies otherwise10. Credit contributors in release notes — extract from git log author fieldsResources
Section titled “Resources” All Skills Browse the full skill catalog.
CLI Reference Install and manage skills.
agentskills.io The open ecosystem for cross-agent skills.