Write changelog

Skill kevinxo328/agent-skills/skills/write-changelog

This repository is a collection of high-quality AI agent skills.

Install

npx -y skills add kevinxo328/agent-skills --skill write-changelog

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Generate a user-facing changelog entry from git commits since the last tag. Use when releasing a new version and writing CHANGELOG.md.

SKILL.md

5.6 KB, as published. Nobody here has run it

You are writing a user-facing changelog entry for a macOS manga translation app. Your job is to turn git commit messages into plain-language release notes that tell users what's new, what's fixed, and what's improved — without any technical details.

Step 1: Ask for version number

Ask the user: "What version number is this release? (e.g. v1.2.0)"

If the user provides an increment like 0.0.1 or +0.0.1, compute the next version by applying it to the latest tag. For example: latest tag v1.1.7 + increment 0.0.1 = v1.1.8.

Step 2: Gather commits

Run the following to find commits since the last tag:

git log $(git describe --tags --abbrev=0)..HEAD --oneline

If no tag exists yet, use:

git log --oneline

Step 3: Categorize commits

Ignore these commit types entirely — they are not user-facing:

docs: — documentation, changelogs, specs, openspec artifacts
refactor: — internal code restructuring
chore: / ci: / test: — maintenance

Map the remaining commits to changelog sections. Do not map by commit prefix alone — feat: commits often describe enhancements to existing features, which belong under Improvements, not New Features.

Decide by user perception:

New Features — The user could not do this at all before. A standalone new capability you could headline in release notes. Test: can you say "you can now X" where X is genuinely new? Examples: Glossary, batch translation, update checker.
Improvements — An existing flow is now faster, more accurate, smoother, or clearer. The user was already doing this; the experience got better. Test: you can only say "X is now faster / better / clearer." Examples: OCR accuracy gains, speed-ups, shortcut tweaks, clearer error messages, layout polish.
Bug Fixes — Something was broken and now works.

Quick mapping:

Commit prefix	Default section	Override when...
`feat:`	New Features	…it enhances an existing feature → Improvements
`fix:`	Bug Fixes	—
`perf:`	Improvements	—

Step 4: Write user-facing descriptions

For each relevant commit, rewrite it from the user's perspective. Follow these rules:

Tone and language:

Write for a non-technical user
Use plain, friendly, conversational English
Describe what the user can now do, or what problem is solved
Never mention code, APIs, refactors, data models, placeholders, or internal system names
Never use jargon like "UUID", "model", "service", "handler", "tag preservation", etc.

Format rules:

New Features: Use **Feature Name** — one sentence describing the user benefit
Bug Fixes: Use - Fixed [what was broken] [in what situation]
Improvements: Use - [What changed] so that [user benefit]

Examples of good rewrites:

Raw commit	User-facing text
`feat: add glossary system and cross-page context`	`Glossary — Pin your preferred translations for character names, places, and terms. The translator will follow your glossary consistently across every page.`
`fix: use UUID for bubble highlight tracking`	`Fixed bubble numbering showing duplicate numbers in some cases`
`feat: check for updates on app focus with 1-hour cooldown`	`App now checks for updates when you switch back to it, so you'll discover new versions faster`
`fix: make ⌘O work when an image is already open`	`Fixed ⌘O not working when an image is already open`

Multiple commits about the same feature should be merged into one entry.

Step 5: Format the changelog block

Use today's date. Format:

## v<VERSION> (<YYYY-MM-DD>)

### New Features

- **Feature Name** — Description of user benefit.
- **Another Feature** — Description.

### Bug Fixes

- Fixed something that was broken.

### Improvements

- Some improvement so users get a benefit.

Only include sections that have entries. If there are no bug fixes, omit the ### Bug Fixes section entirely.

Step 6: Prepend to CHANGELOG.md

Insert the new block at the top of CHANGELOG.md, just below the # Changelog heading, with a blank line before the next existing entry.

Show the user the new entry and say: "Added to CHANGELOG.md. Review and edit if needed."

Step 7: Commit and tag

Run in this exact order:

git add CHANGELOG.md && git commit -m "docs: add changelog entry for v<VERSION>"
git tag v<VERSION>

Then ask the user: "Push to remote? (git push && git push origin v<VERSION>)"

Gives 1 of the 12 instructions most readme changelog skills give

Counted across 471 of the 478 authors here whose files we hold, read 2026-08-06

follow the Keep a Changelog formatin 31 of 471, across 26 files
omit empty sectionshere, and in 21 of 471
Run from the git repository rootin 20 of 471, across 7 files
save output directly to CHANGELOG.mdin 20 of 471, across 7 files
Group commits into logical categoriesin 19 of 471, across 6 files
Review the generated changelog before publishingin 19 of 471, across 6 files
Apply changelog guidelines and brand voicein 18 of 471, across 5 files
Exclude internal commits like refactoring and testsin 18 of 471, across 5 files
Specify date ranges for focused changelogsin 17 of 471, across 4 files
Convert technical commits into customer languagein 17 of 471, across 4 files
group commits by conventional commit typein 14 of 471
insert new entry below unreleased sectionin 14 of 471

Said here and by no other author read

calculate the next version from the latest tag
ignore documentation, refactoring, and maintenance commits
categorize commits by user perception
merge multiple commits about the same feature
tag the version

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.