changelog-generator

name	changelog-generator
description	Generate a CHANGELOG.md from Conventional Commit history with grouped sections and version headers. Use when the user asks to create or update a changelog.

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"