Changelog Generator

Generate CHANGELOG.md entries by analyzing code changes, PRs, and issues — not just commit messages.

Gathering Context

When asked to generate a changelog entry (e.g., for a version or tag range), collect context from multiple sources. Commit messages are often vague or useless, so prioritize richer signals.

Step 1: Determine the version range

# Get the two most recent tags
CURRENT_TAG=$(git describe --tags --abbrev=0)
PREVIOUS_TAG=$(git describe --tags --abbrev=0 "$CURRENT_TAG^")

# Or if the user specifies a version:
# CURRENT_TAG="v2.4.0"
# PREVIOUS_TAG=$(git describe --tags --abbrev=0 "$CURRENT_TAG^")

# Get the date of the previous tag for filtering PRs/issues
SINCE_DATE=$(git log -1 --format=%aI "$PREVIOUS_TAG")

Step 2: Gather signals (in order of usefulness)

PRs merged since last release:

gh pr list --state merged --search "merged:>=$SINCE_DATE" --json number,title,body,labels --limit 100

Issues closed since last release:

gh issue list --state closed --search "closed:>=$SINCE_DATE" --json number,title,body,labels --limit 100

Diff between tags:

git diff "$PREVIOUS_TAG".."$CURRENT_TAG" -- '*.ts' '*.js' '*.tsx' '*.jsx' '*.py' '*.go' '*.rs' ':!*.lock' ':!*.min.*'

Files changed:

git diff --name-only "$PREVIOUS_TAG".."$CURRENT_TAG"

New or changed test descriptions (reveal intent):

git diff "$PREVIOUS_TAG".."$CURRENT_TAG" -- '**/*.test.*' '**/*.spec.*' '**/test_*' '**/*_test.*'

Config and dependency changes:

git diff "$PREVIOUS_TAG".."$CURRENT_TAG" -- 'package.json' '*.toml' '*.yaml' '*.yml' '*.env.example' '*.config.*'

Commit messages (last resort):

git log --oneline "$PREVIOUS_TAG".."$CURRENT_TAG"

Categorizing Changes

Classify every change into one of these Keep a Changelog categories:

• Added — new features or capabilities
• Changed — changes to existing functionality
• Deprecated — features that will be removed
• Removed — features that were removed
• Fixed — bug fixes
• Security — vulnerability fixes

Filtering rules

• Skip refactors, test-only changes, CI config, and code style changes unless they have user-facing impact
• Group minor internal improvements under a single "Internal improvements" bullet if worth mentioning at all
• Prioritize user-facing changes over developer-facing ones
• If you can't determine the user impact of a change, omit it or group it under internal improvements

Writing Rules

• Lead with user benefit: "Add bulk CSV export for reports" not "Implement exportToCsv utility function"
• Never mention file names, function names, or technical internals in the output
• Use active voice: "Add dark mode" not "Dark mode has been added"
• Be specific: "Fix crash when opening files larger than 2GB" not "Fix file handling bug"
• Each entry should be one line. No paragraphs.

Output Format

Write entries in Keep a Changelog format:

## [2.4.0] - 2025-01-15

### Added
- Add bulk CSV export for all report types
- Add keyboard shortcuts for common actions (Ctrl+K to search, Ctrl+N for new)

### Changed
- Improve search performance for large datasets

### Fixed
- Fix crash when opening files larger than 2GB
- Fix incorrect totals on the billing summary page

Example: Bad Commits → Good Changelog

Typical commit messages:

fix stuff
wip
update deps
refactor handler
PR #142: misc changes

What the skill produces by analyzing PRs, issues, diffs, and test descriptions:

## [1.8.0] - 2025-01-10

### Added
- Add real-time collaboration for shared documents
- Add Slack notifications for failed deployments

### Fixed
- Fix duplicate entries appearing in search results
- Fix password reset emails not sending for SSO users

Final Steps

• If a CHANGELOG.md already exists, prepend the new entry below the header
• If no CHANGELOG.md exists, create one with a header and the new entry
• Show the user what was generated and ask if they want to adjust anything before writing