# Changelogator

> Generate a changelog from git commits. Use when the user asks to generate a changelog, prepare release notes, summarize commits, prepare a release, suggest a version bump, or review changes since last tag. Also use when the user mentions "changelog", "release notes", "what changed", "version bump", or "semver".

- Skill: `benjaminhaeberli/changelogator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add benjaminhaeberli/changelogator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/benjaminhaeberli/changelogator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: benjaminhaeberli (https://skillmd.com/u/benjaminhaeberli)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/benjaminhaeberli/changelogator

---


# Changelogator

Generate a structured changelog from git commits following [Keep a Changelog](https://keepachangelog.com/) format.

**By default**, output the changelog in chat for the user to review — do **not** write to `CHANGELOG.md` unless the user explicitly asks.

## Workflow

1. **Find the last tag**: `git tag --sort=-v:refname | head -1`
2. **Retrieve commits**: `git log <tag>..HEAD --format="---COMMIT---%n%H%n%s%n%b" --reverse` (if no tag, use `git log --format="---COMMIT---%n%H%n%s%n%b" --reverse`)
3. **Parse** each commit subject using the format below
4. **Classify** into changelog categories using the mapping table
5. **Detect breaking changes**: `!` after type (e.g., `feat!`) or `BREAKING CHANGE` in body
6. **Suggest semver bump** based on the rules below
7. **Write a summary paragraph**: 2–3 sentences, plain language, user-focused — highlight the most impactful changes, skip internal/technical ones
8. **Build GitHub compare URL**: `git remote get-url origin` + strip `.git` + append `/compare/<prev-tag>...<new-tag>` (only if remote is a GitHub URL)
9. **Generate** the markdown changelog
10. **Output in chat** for validation

## Commit Format

Expected format (from commitor):

```
<emoji> <type>(<scope>): <description> (<TASK-XXX>)
```

Parse using these parts:
- **Emoji**: leading Unicode emoji
- **Type**: word after emoji (`feat`, `fix`, `patch`, etc.)
- **Scope**: optional, inside parentheses after type
- **Breaking**: `!` between type/scope and `:`
- **Description**: text after `: `
- **Task number**: optional, inside parentheses at end of subject

## Category Mapping

Map commit types to changelog categories (consistent with commitor):

| Changelog Category | Emoji | Commit Types                     |
| ------------------ | ----- | -------------------------------- |
| Breaking           | ⚠️    | any type with `!`                |
| Added              | ✨    | feat                             |
| Changed            | 🔨    | patch, style, perf, data         |
| Fixed              | 🐛    | fix, security                    |
| Removed            | 🔥    | remove                           |
| Technical          | ⚙️    | docs, refactor, test, ai, config, build |

> `wip` commits are excluded from changelogs — they don't represent releasable changes.

## Localization

When generating in French, use these category names:

| English   | French    |
| --------- | --------- |
| Breaking  | Critique  |
| Added     | Ajouté    |
| Changed   | Changé    |
| Fixed     | Corrigé   |
| Removed   | Supprimé  |
| Technical      | Technique           |
| Contributors   | Contributeurs       |
| GitHub compare | Comparer sur GitHub |

## Semver Rules

Suggest a version bump based on the most significant change:

| Condition                           | Bump  |
| ----------------------------------- | ----- |
| Any breaking change (`!` or body)   | Major |
| Any `feat` commit                   | Minor |
| Everything else (fix, patch, etc.)  | Patch |

Apply to the last tag version. If no tag exists, suggest `v0.1.0`.

## Output Template

```markdown
## vX.Y.Z - YYYY-MM-DD

<2–3 sentence summary of release highlights>

**GitHub compare:** https://github.com/{owner}/{repo}/compare/{prev-tag}...vX.Y.Z

### ✨ Added
- **scope**: description
- description without scope

### 🔨 Changed
- **scope**: description

### 🐛 Fixed
- description

### 🔥 Removed
- description

### ⚙️ Technical
- description
```

## Output Rules

- **Rewrite descriptions** — do not copy commit subjects verbatim. Rephrase into clear, human-readable sentences. Use backticks for code references (skill names, commands, files, config keys). Capitalize the first word.
- **Omit empty categories** — only show categories that have commits
- **Scope as bold prefix** when present: `- **scope**: description`
- **No scope**: just `- description`
- **Skip merge commits** — ignore subjects starting with `Merge`
- **Include task numbers** when present: `- **scope**: description (TASK-123)`
- **Language**: English by default; if the existing `CHANGELOG.md` or commits are in another language, match that language
- **Summary paragraph**: 2–3 sentences, plain language, user-focused. Highlight the most impactful user-facing changes; skip `wip`, `build`, `refactor`, `test`, `docs`. End with a short transition if there are minor fixes (e.g., "Plus, a set of fixes.")

## Edge Cases

- **No tag found**: use all commits and suggest `v0.1.0`
- **No commits since tag**: output "No changes since `<tag>`."
- **Unrecognized format**: classify under "Other" with the full subject as description
- **Multiple breaking changes**: still one major bump, list all in a `### ⚠️ Breaking Changes` section at the top

## Example

**Input commits** (from `git log v1.2.0..HEAD`):

```
✨ feat(auth): add OAuth2 login with Google (NTT-128)
🐛 fix(exports): prevent duplicate rows in CSV export
🔨 patch(ui): improve loading spinner animation
♻️ refactor: simplify database connection pooling
🔥 remove(api): drop deprecated v1 endpoints
```

**Output**:

```markdown
## v1.3.0 - 2026-02-12

This release brings Google OAuth2 login, making it easier to get started without a password. The deprecated v1 API endpoints have been removed — make sure to migrate to v2 before upgrading. Plus, a set of fixes and UI polish.

**GitHub compare:** https://github.com/owner/repo/compare/v1.2.0...v1.3.0

### ✨ Added
- **auth**: `OAuth2` login with Google provider (NTT-128)

### 🔨 Changed
- **ui**: Improve the loading spinner animation

### 🐛 Fixed
- **exports**: Fix duplicate rows appearing in CSV exports

### 🔥 Removed
- **api**: Drop deprecated `v1` API endpoints

### ⚙️ Technical
- Simplify database connection pooling
```

Suggested version: **v1.3.0** (minor bump — contains new feature)