hermes

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.

context

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.

task

Write the changelog entry for Only if [VERSION] is given: , released as version , for .

  1. Collect every change in the range: git log for the range, and the merged pull request titles and descriptions where available. Read the PR body or the diff when a title is unclear.
  2. If a CHANGELOG.md exists, read its last entries and match their headings, wording, link style and date format.
  3. 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.
  4. Merge commits that belong to the same change into one line.
  5. 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.
  6. 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.
constraints
  • 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.md unless asked; output the entry.
output format

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

Edit on GitHubReport a problem

use in

Hodios CLI
npx @hermes-hq/hodios install write-changelog --target claude-code
Agent Skills
npx skills add hermes-hq/hodios-dist --skill write-changelog -a claude-code
Add the Hodios marketplace (once)
claude plugin marketplace add hermes-hq/hodios-dist
Install the software-engineering plugin
claude plugin install hodios-software-engineering@hodios

The plugin brings every entry in this domain at once.

pairs well with

All of Documentation
PersonaDocumentation

Technical 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-writer
PromptDocumentation

Write 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-guide
PromptDocumentation

Document 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-api
PromptDocumentation

Write 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-readme
PromptDocumentation

Audit 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-documentation
PersonaDocumentation

Open-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