/changelog-generator

name: changelog-generator
description: >
  Parse git history and produce or update a CHANGELOG.md following the Keep a Changelog
  convention. Supports Conventional Commits, basic prefix conventions, and unstructured
  commit messages. Intelligently categorizes changes, detects breaking changes, links
  to PRs/issues, and handles both initial generation and incremental updates.

  **Triggers — use this skill when:**
  - User asks to "generate", "create", "update", or "write" a changelog
  - User mentions "CHANGELOG", "changelog", "release notes"
  - User says "document changes", "what changed since last release"
  - User wants to "prepare a release" and needs a changelog entry
  - User asks to "clean up" or "reformat" an existing changelog

  **Covers:** Any git-based project. Handles Conventional Commits (feat/fix/chore),
  Angular convention, basic prefixes (Add/Fix/Remove), and freeform commit messages.
  Outputs Keep a Changelog format with optional Common Changelog enhancements.

Changelog Generator

Parse a project's git history and produce a high-quality CHANGELOG.md following the [Keep a Changelog](https://keepachangelog.com/) convention.

Philosophy

A changelog is for **humans**, not machines. It answers: "What meaningful changes happened between version X and version Y?" Raw commit logs fail at this because they contain noise — typo fixes, merge commits, CI tweaks, and refactors that don't affect users. This skill filters signal from noise and writes entries that a user or contributor can actually understand.

---

Workflow

Phase 1 — Repository Analysis

Before generating anything, understand the project's commit and versioning patterns.

# 1. Check if we're in a git repo
git rev-parse --is-inside-work-tree 2>/dev/null

# 2. Get all tags (versions) sorted by date
git tag --sort=-creatordate | head -30

# 3. Detect versioning scheme
# SemVer: v1.2.3 or 1.2.3
# CalVer: 2025.01, 2025-01-15
# Other: named releases, build numbers
git tag --sort=-creatordate | head -10

# 4. Detect commit convention
# Sample recent commits to identify the pattern
git log --oneline -30

# 5. Check for existing changelog
cat CHANGELOG.md 2>/dev/null
cat HISTORY.md 2>/dev/null
cat CHANGES.md 2>/dev/null

# 6. Check for existing config that hints at convention
cat .commitlintrc* commitlint.config.* 2>/dev/null  # Commitlint
cat .czrc .cz.toml 2>/dev/null                       # Commitizen
cat cliff.toml 2>/dev/null                            # git-cliff
cat .versionrc* 2>/dev/null                           # standard-version

# 7. Get remote URL for PR/issue links
git remote get-url origin 2>/dev/null

# 8. Package manifest for current version
cat package.json 2>/dev/null | grep '"version"'
cat pyproject.toml 2>/dev/null | grep 'version'
cat Cargo.toml 2>/dev/null | grep '^version'

**Extract from the analysis:**

| Fact | How to determine | |------|-----------------| | Commit convention | Pattern match on recent commits (see detection rules below) | | Versioning scheme | Tag format analysis | | Latest version/tag | Most recent tag | | Remote URL | `git remote get-url origin` — needed for PR/issue links | | Existing changelog | Check for CHANGELOG.md or variants | | Unreleased commits | Commits since the latest tag |

Phase 2 — Commit Convention Detection

Analyze the last 30–50 commits to detect which convention is in use. Apply these rules in order:

**Conventional Commits / Angular**

Pattern: ^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?:
Example: feat(auth): add OAuth2 support
Example: fix!: resolve race condition in queue

→ If >50% of commits match this pattern, use Conventional Commits parsing.

**Basic Prefix**

Pattern: ^(Add|Fix|Remove|Update|Change|Deprecate|Security)[: ]
Example: Add user export feature
Example: Fix login redirect loop

→ If >50% of commits match this pattern, use basic prefix parsing.

**Freeform / No Convention** → If neither pattern dominates, use AI-assisted categorization (see Phase 3).

Report the detected convention to the user before proceeding.

Phase 3 — Commit Extraction & Categorization

Extract commits for the target range and categorize them.

# All commits since last tag (for Unreleased section)
git log $(git describe --tags --abbrev=0 2>/dev/null)..HEAD \
  --pretty=format:"%H|%s|%b|%an|%ae|%aI" 2>/dev/null

# Commits between two tags (for a specific version)
git log v1.1.0..v1.2.0 \
  --pretty=format:"%H|%s|%b|%an|%ae|%aI"

# If no tags exist, get all commits
git log --pretty=format:"%H|%s|%b|%an|%ae|%aI"

# Get PR/merge info if available
git log --merges --oneline -20

Category Mapping

Map commits to Keep a Changelog categories:

| Keep a Changelog Category | Conventional Commits types | Basic prefixes | Description | |---------------------------|---------------------------|----------------|-------------| | **Added** | `feat` | Add, Create, Implement | New features | | **Changed** | `refactor`, `perf`, `style` | Change, Update, Refactor, Improve | Changes to existing functionality | | **Deprecated** | — (detect from message) | Deprecate | Soon-to-be removed features | | **Removed** | — (detect from message) | Remove, Delete, Drop | Removed features | | **Fixed** | `fix` | Fix, Resolve, Correct | Bug fixes | | **Security** | — (detect from message) | Security | Vulnerability fixes |

Entries to SKIP (noise filtering)

Do NOT include these in the changelog unless they have user-facing impact:

• Merge commits (`Merge branch...`, `Merge pull request...`) — extract the PR title instead
• CI/CD changes (`ci:`, `build:`, changes only to `.github/workflows/`)
• Chore commits (`chore:`, dependency bumps without breaking changes)
• Typo fixes in code comments
• Formatting/linting-only changes (`style:` that don't affect behavior)
• Version bump commits (`chore: bump version to...`)
• Commits that only touch test files (unless adding test coverage is noteworthy)