---
name: changelog-entry-writer
description: "Turns a list of commits into a changelog entry grouped by added, changed and fixed, with a version bump that matches the impact. Use when a release is ready and its commit history must become a reader-friendly changelog entry with the right version bump. Do not use for writing marketing release announcements or generating release notes for a single pull request. Related topics: coding, writing."
---

# Changelog Entry Writer

Turns a list of commits into a changelog entry grouped by added, changed and fixed, with a version bump that matches the impact.

## When to use

Use this skill when a release is ready and its commit history must become a reader-friendly changelog entry with the right version bump. Do not use it for writing marketing release announcements or generating release notes for a single pull request.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Filter out commits that change nothing visible to the reader, such as merges, formatting and internal refactors.
3. Rewrite each remaining commit as one past-tense line stating the effect for the chosen audience.
4. Group lines under Added, Changed, Fixed, and Removed or Deprecated, and put a Breaking section first with migration steps when needed.
5. Choose the version bump from the highest-impact change and give the reason.
6. Format the entry with version, date and groups, and list the commits that were hard to classify.

## Inputs

- **Commit messages or diff summary** (longer free text)
- **Previous version** (free text, e.g. "2.4.1")
- **Release date** (free text, e.g. "Date of this release")
- **Audience** (choose one: End users, Developers using the API, Internal team)
- **Versioning scheme** (choose one: Semantic versioning, Calendar versioning, Build numbers)
- **Breaking changes known** (longer free text)

## Output

A paste-ready changelog entry with version, date, a Breaking section if needed and grouped bullet lines, then the bump reason and any commits needing a human decision.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Changelog Entry Writer

Write the changelog entry for this release.

- Commit messages or diff summary: {{Commit messages or diff summary}}
- Previous version: {{Previous version}}
- Release date: {{Release date}}
- Audience: {{Audience}}
- Versioning scheme: {{Versioning scheme}}
- Breaking changes known: {{Breaking changes known}}

Read every commit and drop the noise: merge commits, formatting, test-only and internal refactors that change nothing a reader can see. Rewrite what remains from the reader's point of view, in the past tense, one line each, naming the effect rather than the code. Group lines under Added, Changed, Fixed, and Removed or Deprecated when present, and add a Breaking section at the top when users must act, with a short migration instruction. Choose the version bump by impact: breaking means major, new capability means minor, fixes only means patch, and say why. Credit the issue or pull request number when the commit contains it. Output the entry with the new version, the date and the groups, in a format ready to paste above the previous entry, and list any commits you were unsure how to classify.

## Pitfalls

- Copying commit messages verbatim, which fills the changelog with fix typo and wip.
- Choosing a patch bump for a change that alters existing behaviour, which surprises users who auto-update.
- Burying a breaking change in the middle of the Changed list where nobody reads it.