Changelog Generator

A Claude Code skill that transforms raw git commit history into polished, user-friendly changelogs organized by semantic versioning, categorized by change type, and formatted for your audience.

When to Use This Skill

Choose this skill when:

• Preparing release notes for a new software version
• Creating weekly or monthly product update summaries
• Generating changelogs for open-source project releases
• Automating CHANGELOG.md maintenance in CI/CD pipelines
• Communicating technical changes to non-technical stakeholders

Consider alternatives when:

• You need a full release management system (use semantic-release or release-please)
• You need real-time commit notifications (use a CI webhook instead)
• Your project uses conventional commits with an existing changelog tool already configured

Quick Start

Copy
# Add to your Claude Code project
claude mcp add changelog-generator

# Generate changelog for the latest release
claude "generate changelog from v1.2.0 to HEAD"

# Generate user-friendly release notes
claude "create release notes for version 2.0 targeting end users"

Copy
# .claude/skills/changelog-generator.yml
name: changelog-generator
description: Transform git commits into polished changelogs
triggers:
  - "generate changelog"
  - "release notes"
  - "what changed"
config:
  format: keep-a-changelog
  audience: developers
  group_by: type

Core Concepts

Change Categories

Category	Commit Prefixes	Description
Added	feat:, add:	New features and capabilities
Changed	change:, update:, refactor:	Modifications to existing features
Deprecated	deprecate:	Features marked for future removal
Removed	remove:, delete:	Removed features or capabilities
Fixed	fix:, bugfix:	Bug fixes and corrections
Security	security:, vuln:	Security patches and vulnerability fixes
Performance	perf:	Performance improvements
Documentation	docs:	Documentation updates

Output Example

Copy
# Changelog

## [2.1.0] - 2026-03-13

### Added
- User profile avatars with automatic image optimization (#234)
- Dark mode support across all dashboard pages (#251)
- Export data to CSV and PDF formats (#267)

### Fixed
- Search results no longer return duplicate entries (#289)
- Password reset emails now work with custom domains (#293)

### Changed
- Upgraded authentication flow to OAuth 2.1 standard (#278)
- Improved table loading performance by 40% with virtual scrolling (#281)

### Security
- Patched XSS vulnerability in comment rendering (#301)

Configuration

Parameter	Type	Default	Description
format	string	"keep-a-changelog"	Output format: keep-a-changelog, conventional, custom
audience	string	"developers"	Target audience: developers, users, stakeholders
group_by	string	"type"	Group entries by: type, scope, component
include_commits	boolean	false	Include raw commit hashes in entries
include_authors	boolean	false	Include commit author names
include_prs	boolean	true	Link to pull request numbers
exclude_types	array	["chore", "ci", "test"]	Commit types to exclude from output
date_format	string	"YYYY-MM-DD"	Date format for version headers
max_entries	number	100	Maximum entries per release

Best Practices

1. Use conventional commit format consistently — the skill works best when commits follow patterns like feat: add search or fix: resolve login bug; inconsistent messages produce noisy changelogs.

2. Write changelogs for your audience, not yourself — if the audience is end users, translate "refactored UserService dependency injection" into "improved account page loading speed."

3. Group related changes under a single entry — five commits fixing the same feature should become one changelog entry, not five separate lines that obscure the bigger picture.

4. Tag releases in git before generating — the skill uses git tags as version boundaries; without tags, it cannot determine which commits belong to which release.

5. Review and edit generated changelogs — automated generation provides a strong starting point but human judgment is needed to highlight the most important changes and add context.

Common Issues

Non-conventional commits produce "Uncategorized" entries — If your team doesn't follow conventional commit format, configure custom prefix mappings or use the audience: users mode which uses AI to categorize commits by content rather than prefix.

Merge commits create duplicate entries — The skill may count both the merge commit and the individual commits. Set exclude_merges: true or use squash merging in your workflow to avoid duplicates.

Missing version tags cause single massive changelog — Without git tags marking releases, all commits appear under one version. Run git tag v1.0.0 <commit-hash> on historical release points before generating, or use --from and --to flags to specify commit ranges manually.