Changelog Generator

Skill: Changelog Generator

Parse git commit history and produce a structured CHANGELOG following Keep a Changelog format and Conventional Commits.

Trigger

When the user asks to generate, update, or create a changelog — or before a release.

Prerequisites

• [ ] Git repository with Conventional Commit messages
• [ ] Previous version tag known (or first release)

Quick Usage

For a quick changelog from recent commits, run the bundled script:

scripts/generate-changelog.sh [output-file] [since-tag]

Examples:

scripts/generate-changelog.sh                    # Last 20 commits → CHANGELOG.md
scripts/generate-changelog.sh CHANGELOG.md v1.0  # Commits since v1.0

For a fully structured Keep a Changelog output, follow the detailed steps below.

Steps

Step 1: Determine Version Range

• [ ] Get the latest tag: git describe --tags --abbrev=0 2>/dev/null || echo "none"
• [ ] Get all tags sorted: git tag --sort=-v:refname | head -10
• [ ] Determine range: {last-tag}..HEAD (or all commits if no tag)
• [ ] Ask user for the new version number or suggest based on changes:
• Has feat → minor bump
• Has fix only → patch bump
• Has BREAKING CHANGE or ! → major bump

Step 2: Collect Commits

• [ ] Run: git log {range} --pretty=format:"%H|%s|%an|%ad" --date=short
• [ ] Parse each commit into: hash, type, scope, description, author, date
• [ ] Identify breaking changes (footer or ! in type)

Step 3: Categorize Changes

| Section | Commit Types | Emoji (optional) | |---------|-------------|-------------------| | Added | feat | | | Fixed | fix | | | Changed | refactor, perf | | | Deprecated | Commits mentioning deprecation | | | Removed | Commits removing features | | | Security | fix with security scope | | | Documentation | docs | | | Internal | chore, ci, test, style, build | |

Step 4: Generate Changelog Entry

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

### Added
- **scope:** description ([hash](commit-url)) — @author

### Fixed
- **scope:** description ([hash](commit-url)) — @author

### Changed
- **scope:** description ([hash](commit-url)) — @author

### Breaking Changes
- **scope:** description of what broke and migration path

Step 5: Handle Edge Cases

• [ ] Commits with no type prefix → categorize as Internal
• [ ] Merge commits → skip (use --no-merges flag)
• [ ] Multiple scopes → list under primary scope
• [ ] Very long descriptions → truncate to first sentence

Step 6: Assemble Full Changelog

• [ ] If CHANGELOG.md exists, prepend new entry after the header
• [ ] If new file, add header:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

• [ ] Include comparison link: [X.Y.Z]: https://github.com/org/repo/compare/vPREV...vX.Y.Z

Step 7: Validate & Output

• [ ] Verify no PII, secrets, or internal URLs in entries
• [ ] Verify markdown renders correctly
• [ ] Present as copyable output or write to CHANGELOG.md

Rules

• ALWAYS follow Keep a Changelog format
• ALWAYS group by change type, not by date or author
• NEVER include merge commits or version bump commits
• NEVER include secrets, internal URLs, or PII
• Skip chore/ci/style commits by default (include if user requests)
• Most recent version goes at the top

Completion

CHANGELOG.md entry ready to paste or written to file. Includes version header, grouped changes, and comparison links.

If a Step Fails

• No tags exist: Treat all commits as the first release (v0.1.0 or v1.0.0)
• Non-conventional commits: Group under "Other" with the raw message
• Too many commits: Summarize by scope, list top 20, note "and N more"
• No new commits since last tag: Report "No changes since vX.Y.Z"

Source & license

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

• Author: girijashankarj
• Source: girijashankarj/cursor-handbook
• License: MIT

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