Write a changelog entry
Turns the commits and pull requests in a release range into a user-facing changelog entry in Keep a Changelog format, with breaking changes first. Use when cutting a release.
A changelog is for people deciding whether to upgrade and what will change for them. Commit messages are written for maintainers, so pasting them in produces a list of refactors, CI tweaks and jargon that hides the two changes that matter. Each line should describe an outcome the reader will notice.
Write the changelog entry for Only if [VERSION] is given: , released as version , for .
- Collect every change in the range:
git logfor the range, and the merged pull request titles and descriptions where available. Read the PR body or the diff when a title is unclear. - If a
CHANGELOG.mdexists, read its last entries and match their headings, wording, link style and date format. - Drop changes with no effect on the audience: refactors, tests, CI, formatting, dependency bumps without user impact. Keep security fixes and dependency updates that change behaviour or fix a vulnerability.
- Merge commits that belong to the same change into one line.
- Sort the remaining lines into the Keep a Changelog groups, in their standard order: Added, Changed, Deprecated, Removed, Fixed, Security. Put each breaking change at the top of its group with a
**Breaking:**prefix and what users must do, and if there are any, open the entry with one line saying the release is breaking. - Write each line as one sentence about the outcome: "Uploads larger than 2 GB no longer fail", not "Fix chunk overflow in uploader". Add the PR or issue reference only if it appears in the source.
- Never invent a change, a version number, a release date or an issue reference. Use today's date only when a version is given and no date is supplied, and say that you did.
- No internal names (classes, files, functions) unless the audience is developers and the name is part of the public API.
- If you are unsure whether a change is user-visible, keep it and list it under "Check" in your reply.
- Do not edit
CHANGELOG.mdunless asked; output the entry.
The entry as Markdown: ## [version] - YYYY-MM-DD (or ## [Unreleased]), then ### Group headings with bullet lines. Omit empty groups.
Then a short section Left out listing the commits you dropped, grouped by reason, so the maintainer can check nothing important was hidden.
Then Check, listing lines you were unsure about, or "None".
1 required value still a placeholder; the assistant will ask for it.
details
- kind
- Prompt: a task you run by name to get one finished thing back
- domain
- Software engineering
- category
- Documentation
- level
- Beginner
- made for
- Open-source maintainer, Software engineer
- needs
- repo-read, git
- risk
- read-only
- version
- v1.0.0 · experimental
- reviewed
- 2026-10-02
- works in
- Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md
use in
npx @hermes-hq/hodios install write-changelog --target claude-codenpx skills add hermes-hq/hodios-dist --skill write-changelog -a claude-codeclaude plugin marketplace add hermes-hq/hodios-distclaude plugin install hodios-software-engineering@hodiosThe plugin brings every entry in this domain at once.
pairs well with
All of DocumentationTechnical writer
Writes and edits developer documentation that is accurate to the code, task-oriented and easy to scan. Use as the voice for READMEs, API references, guides and changelogs.
technical-writerWrite a migration guide
Writes an upgrade guide for a breaking release that lists each breaking change with how to find affected code, before-and-after examples and a way to verify. Use when shipping a major version.
write-migration-guideDocument a public API
Writes reference docs for a module's exported functions, classes or endpoints in the native doc-comment format, covering real behaviour, errors and edge cases. Use before a release.
document-public-apiWrite a README
Writes or improves a project README from what the code actually does, with an install and quick start that work when copied. Use for a new project or a README that has drifted.
write-readmeAudit a documentation set
Audits documentation for accuracy against the code, gaps in the user journey, stale pages, duplication and findability, and returns a prioritised fix list. Use before a docs overhaul or release.
audit-documentationOpen-source maintainer
Acts as an experienced open-source maintainer who protects project scope, writes welcoming but firm replies, reviews contributions and keeps releases sustainable.
open-source-maintainer