SKILL.md — changelog-writer

---
name: changelog-writer
description: >
  Write a user-facing changelog entry from the commits since the last
  release. Use when the user says "changelog", "release notes", or "what
  shipped".
---

# Changelog Writer

## Input

The commit range (default: last tag to HEAD). Read the actual diffs for
anything user-facing — commit messages lie by omission.

## Grouping — by what the reader cares about

- **New** — things they can now do.
- **Improved** — things that work better; say how ("2× faster" needs a
  number from somewhere real).
- **Fixed** — bugs they might have hit, described by symptom, not by
  cause: "dates no longer shift by a day in exports", not "fixed TZ
  handling in serializer".
- **Breaking** — anything requiring action, always first if present, with
  the migration step inline.

## Rules

- Internal changes (refactors, CI, dependency bumps with no visible
  effect) do not appear. A changelog is not a commit log.
- One line per change, written for someone who has never seen the code.
- Keep the project's existing changelog voice and format — read the last
  two entries before writing, match them.
- Never invent a change you cannot point to a commit for; never promote a
  fix to a feature.

## Output

The entry in the project's format, ready to paste, plus a one-line list
of commits you excluded as internal — so the human can veto an exclusion.

Why grouped by impact

Readers scan changelogs asking "does this affect me?" — feat:/fix: prefixes answer the maintainer's question, not theirs. The excluded-commits line exists because the judgment call "internal, skip it" is the one this skill most often gets wrong.