write-changelog
Skill22 starsChanged 2 months agoMITView on GitHub
Write or edit agent-top's CHANGELOG.md in a short, public-facing release-notes style, with a Highlights paragraph for major features and a PR link on every entry. Use whenever a user-visible change lands (add a line under Unreleased), when cutting a release (turn Unreleased into a version), or when asked to "update the changelog", "write release notes" or "what changed in vX". Do not copy PR descriptions or commit messages into it.
13 other projects use a version of this.
Adopted by
Most recently taken up by
- Donchitos/Claude-Code-Game-Studiostheir own version, first seen Nov 15, 2026
- pahlevikun/levistacktheir own version, first seen Nov 1, 2026
- DataDog/dd-trace-rbtheir own version, first seen Oct 9, 2026
- jamiebrynes7/obsidian-todoist-plugintheir own version, first seen Oct 9, 2026
- petera2c/simple-tabletheir own version, first seen Oct 8, 2026
- classroomio/classroomiotheir own version, first seen Oct 8, 2026
Other versions13 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 13
- Donchitos/Claude-Code-Game-Studios★ 39ksame name
- zulip/zulip★ 26ksame name
- microsoft/vscode-pull-request-github★ 2.6ksame name
- classroomio/classroomio★ 1.7ksame name
- jamiebrynes7/obsidian-todoist-plugin★ 1.2ksame name
- DataDog/dd-trace-rb★ 417same name
- petera2c/simple-table★ 235same name
- plugyawn/armada★ 2same name
- wsm94/gi-claude-skills★ 2same name
- fabianmagrini/skills★ 1same name
3 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/llms.txtllms.txt
- agent-topSkill
- rust-best-practicesSkill
- tuff-capabilitiesSkill
- tuff-cli-guideSkill
- add-harness-adapterSkill
- agent-topSkill
- tuff-cli-guideSkill
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 3 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 13 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 47
Only for a release with a feature a one-liner undersells: a new panel, a new command, a new harness, a new kind of number.
- Very specific: line 53
No links, no bullets, no implementation detail.
- Very specific: line 65
Start with what the user can now do or see: the key, flag, command, panel or harness.
- Distinctive: line 67
Put keys, flags, commands, JSON fields and model names in backticks.
- Distinctive: line 70
No bold, no nested bullets.
- Very specific: line 122
Check the section with the same logic the release workflow uses: awk -v v=x.y.z '$0 ~ "^## \\[" v "\\]" {s=1.
“Common” is measured: kept by at least 6 in 10 of the 13 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Writing the agent-top changelog
CHANGELOG.md is read by people deciding whether to upgrade. An engineer should
take in a whole release in under a minute, see which change matters most, and
click through to the PR when a line is not enough. PR descriptions, DEC records
and docs/ hold the reasoning; the changelog says what changed for the user
and links to where the detail lives.
Format
The file follows Keep a Changelog 1.1. Three things read it, so the heading shapes are fixed:
.github/workflows/release.ymlpublishes the lines under## [x.y.z]as the GitHub release notes, and fails the release if that section is empty. Links must be inline and absolute; reference-style definitions at the bottom of the file would not travel with the section.agent-top --whats-newprints the first four## [sections,[Unreleased]included, from the copy compiled in bycrates/agent-top/build.rs.docs/hooks/changelog_links.pyputs the file on the docs site, drops the# ChangelogH1 and strips thedocs/prefix from links.
## [0.19.0] - 2026-09-20
### Highlights
`agent-top --status` prints one line per live agent, sized for a shell prompt or a tmux status bar. It reads the same data as the table, so the numbers match the live view.
### Added
- `agent-top --status` prints one line per live agent. ([#41](https://github.com/kannandreams/agent-top/pull/41))
### Fixed
- Codex sessions resumed with `--resume` keep their cost after a restart. ([#42](https://github.com/kannandreams/agent-top/pull/42))Sections, in this order, and only the ones that have entries: Highlights,
Added, Changed, Deprecated, Removed, Fixed, Security. One blank line
between sections and before each ## [.
Highlights
- Only for a release with a feature a one-liner undersells: a new panel, a new command, a new harness, a new kind of number. Patch releases and releases of small changes have none.
- One short paragraph per highlighted feature, two or three sentences: what it is, and the question it answers or the problem it catches. At most two paragraphs per release.
- No links, no bullets, no implementation detail. The feature still gets its
own entries under
AddedorChanged, with the links.
One entry
- One line, one change, about 25 words before the link. If it needs a second sentence, the detail belongs in the Highlights paragraph or the docs.
- End with the link in parentheses:
([#36](https://github.com/kannandreams/agent-top/pull/36)). Several PRs:([#36](…), [#37](…)). A change committed straight tomainlinks the commit:([4afbce5](https://github.com/kannandreams/agent-top/commit/4afbce5)). Find them withgit log --format='%h %s' vPREV..HEAD; squash-merged PRs end their subject with(#N). - Start with what the user can now do or see: the key, flag, command, panel or
harness.
`m` opens the MCP servers panel., not "Added a new Panel variant". - Put keys, flags, commands, JSON fields and model names in backticks.
- Name the harness when the change applies to only some of them.
- Mention a new
--jsonfield when one is added. Scripts depend on it. - No bold, no nested bullets.
- Present tense, plain statements. Follow [[user-prefers-plain-prose]]: no reassurance, no justification for the design.
Leave out
- How it works: parsing rules, file formats, heuristics, crate internals.
- How it was verified: live checks, fixture names, "found when".
- Internal references in the text: RFC and DEC numbers. PR and commit numbers appear only as the trailing link.
- Changes with no user effect: refactors, tests, CI, fixture updates, price
table date bumps, docs-site styling. If a release has nothing else, write one
entry:
- No change to the binary; <what did change, e.g. README updates>. - Public
agent-top-coreAPI changes are the exception. List them underChanged, since library users see them.
Examples
Too long (a PR description pasted in):
- MCP call counts for OpenCode. OpenCode rows now get per-server MCP rows with calls, errors and the last call... OpenCode writes an MCP call as an ordinary tool part named
<server>_<tool>, with no prefix... Verified against a live OpenCode 1.18.15 session.
Right length:
- OpenCode: MCP call counts per server, matched against the server names in OpenCode's config. (#36)
Too internal:
- The scanner now uses
refresh_processes_specificswithwith_cmd.
User-visible:
- MCP servers were labelled
tooland--resumesessions went unmatched, because process command lines were never read.
Workflow
- With each change. In the same PR as the change, add its entry under
## [Unreleased], in the right section. Write it from the diff and the user-facing result, not from the PR body. The PR number is known once the PR is open; add the link in a follow-up commit on the branch. - At release (only after the user confirms the release, see
[[release-only-on-confirmation]]):
- Reread the Unreleased entries together. Merge entries about the same feature (keeping all their links), drop any that no longer apply, and put the most important first.
- Decide whether the release has a feature worth a Highlights paragraph, and write it.
- Rename
## [Unreleased]to## [x.y.z] - YYYY-MM-DDand add a fresh, empty## [Unreleased]above it. - Check the section with the same logic the release workflow uses:
awk -v v=x.y.z '$0 ~ "^## \\[" v "\\]" {s=1; next} s && /^## / {exit} s' CHANGELOG.md
- Fixing a published entry. Edit
CHANGELOG.md, then update the release page withgh release edit vX.Y.Z --notes-file <the section>so both say the same thing, and republish the docs site withmise run docs:publish. Both are outward-facing; ask before running them.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

