Changelog Generator

Iron Law: Never generate a changelog without reading actual git history or diff; always base entries on verified commits, not assumptions.

Changelog Generator Skill

Transform git commit history into polished, user-friendly changelogs. Works with any tech stack by auto-detecting the project structure.

High-Level Process

1. Detect project structure - Scan repo for platform markers (Java, Node, Python, Angular, Flutter, etc.) and build a platform label map
2. Determine commit range - Use tags, dates, or commit count. Ask user if unclear
3. Extract commits - Pull structured log: git log "$LAST_TAG"..HEAD --pretty=format:"%h|%ai|%an|%s" --no-merges
4. Categorize - Map conventional commit prefixes to user-facing categories (feat -> New Features, fix -> Bug Fixes, perf -> Performance). Skip refactor/test/chore/ci/build/style
5. Rewrite - Translate technical commits to user-friendly language. Lead with user benefit, strip jargon
6. Assemble - Format changelog for the target destination
7. Output - Write to CHANGELOG.md, GitHub Release, App Store, Slack, or internal format

For detailed step-by-step workflow (project detection scripts, commit parsing, categorization table, rewriting rules, assembly format) -> Read [reference/changelog-workflow.md](reference/changelog-workflow.md)

For output format examples (App Store, Keep a Changelog, internal/technical, Slack/email) -> Read [reference/changelog-workflow.md](reference/changelog-workflow.md)

Key Rules

• Read CLAUDE.md first if it exists -- it describes the project's tech stack and conventions
• Always include: feat:, fix:, perf:, security:, BREAKING CHANGE
• Always skip: refactor:, test:, chore:, ci:, build:, style:
• Non-conventional commits: categorize by intent, include under "Improvements" if ambiguous
• Multi-platform repos: prefix entries with platform label (e.g., Mobile App, Web App, Backend)
• Single-platform repos: skip the label entirely

Output Destinations

| Destination | Action | |-------------|--------| | CHANGELOG.md | Prepend to existing file (newest on top) | | GitHub Release | Output as Markdown block ready to paste | | App Store | Shorter format, no emoji, plain language, max 4000 chars | | Slack / Email | Condensed summary with highlights only | | Internal | Include technical details and commit hashes |

Automation Tip

Suggest to the user: add a pre-release hook or CI step that runs this skill automatically when tagging a new version. Pair with the /changelog command for quick manual runs.

For tool configuration (cliff.toml, release.config.js, GitHub Actions release workflow) -> Read [reference/changelog-automation-tools.md](reference/changelog-automation-tools.md)

Anti-Patterns

> ❌ Don't invent entries. Never add changelog items that have no backing commit. Every line must map to a real commit hash.

> ❌ Don't expose internals. "Refactored UserService to use factory pattern" is not user-facing. Rewrite as the benefit, or skip it.

> ❌ Don't copy commit messages verbatim. Raw messages like fix: typo in auth handler become noise. Rewrite to user-facing language or drop it.

> ❌ Don't include chore/ci/test/build commits in user-facing changelogs. They belong in internal/technical format only.

Error Handling

Empty git log (no commits in range):

git log "$LAST_TAG"..HEAD --oneline
# returns nothing

Stop. Do not generate an empty changelog. Report: "No commits found between $LAST_TAG and HEAD. Confirm the tag name or provide a date range."

git log command fails (no tags exist):

git describe --tags --abbrev=0
# fatal: No names found, cannot describe anything.

Fall back to full history: git log --pretty=format:"%h|%ai|%an|%s" --no-merges. Warn the user that the range is unbounded (all commits since repo init).

No conventional commits found: Verify commit messages follow type: prefix format. Fall back to manual changelog if history is inconsistent.

Ambiguous scope: When a commit touches multiple features, split the changelog entry by affected area.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kumaran-is
• Source: kumaran-is/claude-code-onboarding
• License: MIT

Install and usage instructions live in the source repository linked above.