Changelog Generator Partner

Your agent for transforming raw git commit history into polished, user-friendly changelogs that communicate the value of releases to both technical and non-technical audiences.

When to Use This Agent

Choose Changelog Generator Partner when:

• Preparing release notes for a new version or sprint
• Transforming git log output into categorized, readable changelogs
• Writing weekly or monthly product update summaries
• Maintaining a CHANGELOG.md file following Keep a Changelog conventions
• Creating customer-facing release announcements from technical commits

Consider alternatives when:

• You need automated changelog generation integrated into CI — use standard-version or semantic-release
• You need technical documentation — use a documentation engineer agent
• You need commit message enforcement — use a commit lint configuration

Quick Start

Copy
# .claude/agents/changelog-generator.yml
name: Changelog Generator Partner
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Changelog generation agent that transforms git commits into polished, user-facing release notes

Example invocation:

claude "Generate a changelog for v2.5.0 based on all commits since the v2.4.0 tag, organized by category with user-friendly descriptions"

Core Concepts

Changelog Categories

Category	Description	Commit Prefixes
Added	New features and capabilities	feat:, feature:
Changed	Modifications to existing features	change:, update:, enhance:
Fixed	Bug fixes and corrections	fix:, bugfix:, hotfix:
Deprecated	Features marked for removal	deprecate:
Removed	Removed features or capabilities	remove:, delete:
Security	Security patches and updates	security:, vuln:
Performance	Speed and efficiency improvements	perf:, optimize:

Changelog Format (Keep a Changelog)

Copy
# Changelog

## [2.5.0] - 2025-03-15

### Added
- User dashboard with real-time activity feed and customizable widgets
- Export functionality for reports in CSV, PDF, and Excel formats

### Changed
- Improved search performance by 3x with indexed full-text search
- Updated onboarding flow with progressive disclosure pattern

### Fixed
- Resolved issue where notifications were sent twice on webhook retry
- Fixed pagination displaying incorrect total count on filtered views

### Security
- Upgraded authentication library to patch CVE-2025-1234

Configuration

Parameter	Description	Default
format	Output format (keepachangelog, conventional, custom)	keepachangelog
audience	Target readers (developers, users, stakeholders)	users
since	Start point (tag, commit, date)	last tag
group_by	Categorization method (type, scope, component)	type
include_authors	Show commit authors	false

Best Practices

1. Write for your audience, not for git log readers. "Fixed race condition in UserSessionManager#handleReconnect" becomes "Fixed an issue where users were occasionally logged out during brief network interruptions." Translate implementation details into user impact.

2. Lead each entry with the user benefit. Start changelog items with what changed from the user's perspective, not what code was modified. "Dashboard loads 3x faster" is better than "Implemented Redis caching for dashboard API endpoint."

3. Group related commits into single changelog entries. Five commits that fix a pagination bug should appear as one changelog entry, not five. Squash related technical changes into a single, meaningful description of what changed.

4. Include breaking changes prominently at the top. If a release contains breaking changes, flag them with a clear warning and migration instructions. Users need to know what will break before upgrading, not discover it in production.

5. Use consistent tense and formatting. Write in past tense ("Added", "Fixed", "Improved") or imperative mood ("Add", "Fix", "Improve") — pick one and stick with it. Consistency makes changelogs scannable and professional.

Common Issues

Commits don't follow conventional format, making categorization difficult. Without commit prefixes like feat: or fix:, auto-categorization fails. Fall back to analyzing the diff and PR description for context. For future releases, enforce conventional commits with commitlint and a pre-commit hook.

Changelog entries are either too technical or too vague. Finding the right abstraction level is hard. Target a technical user who knows the product but not the codebase. They care about "faster search" but not "B-tree index on the search column." Include specific numbers where possible.

Minor internal changes inflate the changelog. Dependency bumps, CI config changes, and code refactors don't belong in user-facing changelogs. Filter out commits that don't affect user experience — limit the changelog to features, fixes, and breaking changes that users will actually notice.