---
name: changelog
description: Update CHANGELOG.md after a commit and amend the commit to include it. Use when the user says "/changelog", "update the changelog", "add to changelog", or when invoked automatically at the end of the commit skill.
version: 1.0.0
allowed-tools: [Bash, Read, Write, Edit]
---

# Changelog Skill

Update `CHANGELOG.md` to reflect the most recent commit, then amend the commit to bundle the changelog change in.

## Format

Use **Keep a Changelog** format (https://keepachangelog.com):

```markdown
# Changelog

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

## [Unreleased]

### Added
- ...

### Changed
- ...

### Fixed
- ...

### Removed
- ...

## [x.y.z] - YYYY-MM-DD
...
```

**Section types:** `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.

## Step 1 — Read the Last Commit

```bash
git log -1 --format="%s%n%n%b"
```

Extract:
- The commit type and scope (from conventional commit subject)
- The description and body

## Step 2 — Map Commit Type to Changelog Section

| Commit type | Changelog section |
|---|---|
| `feat` | Added |
| `fix` | Fixed |
| `refactor`, `perf` | Changed |
| `docs` | Changed |
| `chore`, `build`, `ci` | Changed (only if user-visible; skip internal-only chores) |
| `style`, `test` | Skip (not user-facing) |
| breaking change (contains `!` or `BREAKING CHANGE`) | Changed (prefix entry with **BREAKING:** ) |

## Step 3 — Write the Entry

The entry should be:
- One line (two at most for complex changes)
- Written for a user/reader, not a developer — describe the effect, not the implementation
- Start with a capital letter, no trailing period
- If the commit has a scope, mention it naturally: "Audio: add silence detection pass before VAD"

## Step 4 — Update CHANGELOG.md

**If `CHANGELOG.md` does not exist:** create it with the standard header and an `[Unreleased]` section containing the new entry.

**If it exists:** insert the entry under `## [Unreleased]` → the correct section heading. If that section heading does not exist under `[Unreleased]`, create it.

Do not create a new dated release block — only add to `[Unreleased]`.

## Step 5 — Stage and Amend

```bash
git add CHANGELOG.md
git commit --amend --no-edit
```

`--no-edit` keeps the commit message exactly as written in Step 1. Do not alter the commit message.

## Rules

- Never create a dated release block unless the user explicitly asks to cut a release.
- Never add more than one entry per commit invocation.
- If the commit type maps to "skip", exit cleanly and report that no changelog entry is needed.
- If amending fails (e.g., nothing to amend), report the error and leave `CHANGELOG.md` staged for the user to commit manually.
