---
name: changelog-writer
description: Produces a user-facing changelog or release notes from the commits and PRs since the last tag, grouped into Added, Changed, Fixed and Removed, skipping internal noise. Use when the user asks for release notes, a changelog entry or what changed since the last release.
---

# Changelog Writer

A changelog is for people who use the software, not for the people who wrote it. Translate the history into what they will notice.

## 1. Find the range

```bash
git fetch --tags origin
git describe --tags --abbrev=0                 # latest tag
git tag --sort=-creatordate | head
git log --oneline <last-tag>..HEAD
git log --format='%h %s%n%b---' <last-tag>..HEAD
```

If the user names two versions, use `v1.2.0..v1.3.0`. If there are no tags, ask the user where the release starts (a date, a commit, a branch point). For squash-merged repos the PR titles are the units; for others, merge commits and commit subjects are.

```bash
gh pr list --state merged --search "merged:>=2026-01-01" --limit 500 --json number,title,labels,url
```

Use `gh` only if it is available; otherwise rely on the git log.

## 2. Learn the existing format

Open `CHANGELOG.md` or the previous release notes first and match them: heading style, date format, version link style, whether entries mention PR numbers or authors. If the repo follows Keep a Changelog, use its sections. If there is no history, use the structure below.

## 3. Classify each change

For every commit or PR decide:

- Added: new features, new options, new endpoints, new supported platforms.
- Changed: behavior differences, performance improvements users notice, updated defaults, deprecations.
- Fixed: bugs users could hit; describe the symptom that is gone.
- Removed: deleted features or options, dropped platform support.
- Security: vulnerability fixes, described without exploit details until disclosure is OK.
- Breaking changes: always call them out first, with migration instructions.

Skip internal noise: refactors with no behavior change, CI and build tweaks, test-only changes, formatting, dependency bumps with no user effect, merge commits, reverts that cancel each other. When unsure whether a change is visible to users, read the diff or ask the user.

## 4. Write the entries

- One line per change, user-facing language, present or past tense consistently (match the repo).
- Describe the effect, not the implementation: "Fixed a crash when uploading files over 2 GB", not "fix integer overflow in chunk loop".
- Merge related commits into one entry; split a commit that contains two user-visible changes.
- Add the PR or issue reference in the repo's style (`(#482)`).
- For breaking changes, say what to do: "Rename `apiKey` to `api_key` in your config."
- Never invent features, numbers or dates. If a commit message is too vague to understand, read its diff; if still unclear, list it under a question for the user.

## 5. Output format

```
## [1.4.0] - 2026-11-11

### Breaking changes
- <what changed and how to migrate>

### Added
- <entry> (#101)

### Changed
- <entry>

### Fixed
- <entry>

### Removed
- <entry>

### Security
- <entry>
```

Omit empty sections. Add a one or two sentence summary on top for a major release if asked. Offer a shorter variant (three to five bullets) for announcements or app-store text when relevant.

If the user wants the file updated, insert the new section above the previous release in `CHANGELOG.md` and keep the existing text unchanged. Do not create a tag, bump the version or publish a release unless asked.

## Pitfalls

- Do not paste the raw `git log`; it is not a changelog.
- Do not list every dependency bump or typo fix.
- Do not hide breaking changes inside "Changed".
- Do not credit or blame individuals unless the repo's format includes authors.
- Do not include secrets, internal hostnames or private ticket details in public notes.
- Do not guess the release version number; ask, or follow the repo's versioning rule (semver: breaking means major, features mean minor, fixes mean patch) and say what you assumed.

Source: [AnyModel skills catalog](https://anymodel.org/en/skills) · License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
