changelog-generator

Getting Started

1. Install the skill using the command above
2. Open your AI coding agent (Claude Code, Codex, Gemini CLI, or Cursor)
3. Reference the skill in your prompt
4. The AI will use the skill's capabilities automatically

Example Prompts

• "Review the open pull requests and summarize what needs attention"
• "Generate a changelog from the last 20 commits on the main branch"

Overview

Generate structured changelogs and release notes from git commit history, merge commits, or manually provided feature lists. Produces well-organized, categorized output following the Keep a Changelog convention. Handles both technical changelogs for developers and user-facing release notes.

Instructions

When a user asks you to generate a changelog or release notes, follow this process:

Step 1: Determine the scope

Identify what range of changes to include:

# List recent tags to find version boundaries
git tag --sort=-creatordate | head -10

# Get commits since the last tag
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
echo "Last tag: $LAST_TAG"

# If no tags exist, ask the user for a date range or commit range

Get the raw commit data:

# Commits since last tag
git log "$LAST_TAG"..HEAD --oneline --no-merges

# Commits between two tags
git log v1.1.0..v1.2.0 --oneline --no-merges

# Commits in the last 2 weeks
git log --since="2 weeks ago" --oneline --no-merges

# With more detail (author, date, body)
git log "$LAST_TAG"..HEAD --format="%h %s (%an, %ad)" --date=short --no-merges

Step 2: Categorize the commits

Sort each commit into one of these categories based on the commit message and changed files:

• Added - New features or capabilities
• Changed - Changes to existing functionality
• Deprecated - Features that will be removed in a future version
• Removed - Features that have been removed
• Fixed - Bug fixes
• Security - Vulnerability fixes

Use commit message prefixes as hints:

• feat:, feature: -> Added
• fix:, bugfix: -> Fixed
• refactor:, perf: -> Changed
• docs: -> Changed (if user-facing) or skip
• chore:, ci:, build: -> Skip unless significant
• security:, vuln: -> Security
• deprecate: -> Deprecated
• remove:, breaking: -> Removed

If commits lack conventional prefixes, read the diff to classify:

# See what files changed in a commit
git show --stat <commit-hash>

# See the actual diff for ambiguous commits
git show <commit-hash>

Step 3: Write the changelog entry

Format following Keep a Changelog:

## [X.Y.Z] - YYYY-MM-DD

### Added
- Feature description in user-understandable language (#PR)

### Changed
- What changed and why it matters (#PR)

### Fixed
- Bug description and what was corrected (#PR)

Rules for writing entries:

• Write from the user's perspective, not the developer's
• Start each item with a verb (Add, Fix, Update, Remove)
• Include PR or issue numbers when available
• Group related changes into a single entry
• Skip internal refactors unless they affect behavior
• Mention breaking changes prominently

Step 4: Output the result

• If a CHANGELOG.md exists, prepend the new entry below the header
• If creating release notes (e.g., for GitHub), use a more narrative style
• Always show the user the generated content before writing to a file

Examples

Example 1: Generate changelog from git history

User request: "Generate a changelog for the v2.3.0 release"

Actions:

git log v2.2.0..v2.3.0 --oneline --no-merges

Output:

## [2.3.0] - 2025-04-15

### Added
- Add dark mode support across all pages (#234)
- Add CSV export for dashboard reports (#241)
- Add keyboard shortcuts for navigation (#238)

### Changed
- Improve search performance by 3x with debounced queries (#236)
- Update authentication flow to support SSO providers (#240)

### Fixed
- Fix pagination losing filters on page change (#235)
- Fix timezone display in event scheduler (#237)
- Fix memory leak in WebSocket connection handler (#242)

Example 2: Create user-facing release notes

User request: "Write release notes for our users about this update"

Output:

# What's New in v2.3.0

We're excited to ship dark mode, faster search, and SSO support!

## Highlights

**Dark Mode** - The app now supports dark mode across all pages.
Toggle it from Settings > Appearance or let it follow your system
preference.

**3x Faster Search** - Search results now appear instantly as you
type, thanks to a complete rewrite of the search engine.

**SSO Login** - You can now sign in with your company's identity
provider (Okta, Azure AD, Google Workspace).

## Bug Fixes
- Filters now persist correctly when navigating between pages
- Event times display in your local timezone
- Resolved a connectivity issue with real-time updates

## Full Changelog
See the [complete changelog](./CHANGELOG.md) for all details.

Example 3: Changelog from a branch diff

User request: "What changed on the feature branch compared to main?"

Actions:

git log main..feature/payments --oneline --no-merges
git diff main..feature/payments --stat

Output: A summary of all changes on the branch, categorized and formatted, suitable for including in a PR description or release planning document.

Guidelines

• Always read the existing CHANGELOG.md format before generating a new entry to match the style.
• Use semantic versioning: breaking changes = major, new features = minor, fixes = patch.
• For conventional commits repos, leverage the prefixes for automatic categorization.
• Skip trivial commits (typo fixes, whitespace changes) unless the user wants everything.
• When in doubt about whether a change is user-facing, include it with a note.
• For monorepos, group changes by package or service.
• Always include the date in ISO 8601 format (YYYY-MM-DD).
• If the user provides a list of features instead of git history, format them into the same structure.