update-changelog
Skill32 starsChanged 29 days agoMITView on GitHub
Draft a CHANGELOG.md entry (and matching semver bump) for the work just finished on this branch, and update the relevant README if the change is worth surfacing there. Use when the user says "update changelog", "changelog this", "prepare release notes", "bump version", or "/update-changelog" — typically once a feature or fix is done and about to merge, not mid-development.
36 other projects use a version of this.
Adopted by
Most recently taken up by
- harshitsinghbhandari/domain-expansiontheir own version, first seen Nov 8, 2026
- Raicuparta/rai-paltheir own version, first seen Nov 2, 2026
- dotnet/vscode-csharptheir own version, first seen Nov 1, 2026
- a2ui-project/a2uitheir own version, first seen Nov 1, 2026
- raine/skillstheir own version, first seen Nov 1, 2026
- AcKeskin/contexturetheir own version, first seen Nov 1, 2026
Used with
Projects with it also use clack-cli-patterns, drag-to-reorder and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
openchamberSkillclack-cli-patterns
Use when creating or modifying OpenChamber CLI commands, prompts, terminal output, non-TTY behavior, `--quiet`, or `--json` behavior.
Also in 3 projects that use this
openchamberSkilldrag-to-reorder
Use when implementing or modifying OpenChamber sortable or drag-to-reorder behavior, especially `@dnd-kit`, touch/mobile interactions, variable-width items, or wrapping layouts.
Also in 3 projects that use this
mitsuhikoSkilloebb-scotty
Austrian rail travel planner (ÖBB Scotty). Use when planning train journeys in Austria, checking departures/arrivals at stations, or looking for service disruptions. Covers ÖBB trains, S-Bahn, regional trains, and connections to neighboring countries.
Also in 3 projects that use this
- +9 more from openchamber
Other versions36 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 36
- penpot/penpot★ 62ksame name
- alibaba/page-agent★ 29ksame name
- joke2k/faker★ 19ksame name
- a2ui-project/a2ui★ 17ksame name
- google/A2UI★ 17ksame name
- quickwit-oss/tantivy★ 16ksame name
- btriapitsyn/openchamber★ 13ksame name
- openchamber/openchamber★ 13ksame name
- mitsuhiko/agent-commands★ 3.2ksame name
- mitsuhiko/agent-stuff★ 3.2ksame name
26 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 repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- bump-npm-depsSkill
- create-github-issueSkill
- create-gitlab-taskSkill
- debug-production-runSkill
- sync-architectureSkill
- update-server-depsSkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 2 are distinctive, and 7 are very specific to this project.
0
Common
Most of the 35 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 24
If unsure where the last bump landed, grep -n "^## \[" CHANGELOG.md | head -1 gives the current top version.
- Distinctive: line 46
Do this before writing the entry, not after the user has to point out a violation.
- Very specific: line 64
If offering to commit it, suggest both a message (50/72-char rule above) and a branch name (<type>/<short-kebab-description>, same …
- Very specific: line 70
Only user-facing changes belong in the log: something a person using langgraph-harness (reviewer, admin, developer running the app) would …
- Very specific: line 89
Read the top 2-3 entries in CHANGELOG.md before writing — the format is consistent across 30+ releases:
- Very specific: line 95
No internal file paths, function names, or variable names in the prose.
- Very specific: line 98
Only three section headers ever appear, in this order when present: ### Features, then ### Fixes, then ### Breaking Changes.
- Very specific: line 133
Check all three, independently — a backend-only change might warrant updating backend/README.md but not the root one, and vice versa.
- Distinctive: line 166
Don't fold in unrelated uncommitted changes — stage only the files this skill touched.
“Common” is measured: kept by at least 6 in 10 of the 35 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
Root CHANGELOG.md and root package.json's version are the source of
truth. Every entry corresponds 1:1 with a version bump — never add one without
the other.
1. Scope the change
Diff against the last version bump, not just the latest commit:
git log --oneline <last-tag-or-commit-before-bump>..HEAD
git diff <last-tag-or-commit-before-bump>..HEADIf unsure where the last bump landed, grep -n "^## \[" CHANGELOG.md | head -1
gives the current top version; find the commit that added it.
While you have that commit list, audit subject-line length and body presence
against this repo's standard (see CLAUDE.md): 50 chars target, 72 hard
limit, subject-only with no body — it applies to every commit, no
exceptions. Fixing a commit already in history means a rebase, which is
destructive, so get the user's explicit go-ahead before doing that; but
don't downplay a violation as optional just because fixing it takes an extra
step. Any commit this skill creates itself (step 5) must simply never
violate either rule in the first place.
Also check the current branch name (git branch --show-current) against
this repo's standard (see CLAUDE.md): <type>/<short-kebab-description>,
type from the same Conventional Commits vocabulary as commit subjects
(feat, fix, chore, refactor, docs, style, perf, test).
Renaming a branch that's already pushed/tracked upstream affects a shared
ref, so flag a violation to the user rather than renaming it yourself.
Also read CLAUDE.md's full "Code style" section (not just the commit/branch
rules above) and check it against the diff being documented — most commonly
its comment rules (one line, glued to the line it explains, WHY not WHAT).
Do this before writing the entry, not after the user has to point out a
violation. Fix violations in the diff itself if the underlying change is
still uncommitted; if it's already committed, flag it the same way as a
subject-line violation above rather than silently ignoring it.
Also check whether this diff changes anything docs/architecture.md describes — a component
added or removed, a harness's tool surface or data flow changed, or something moving between
Built/Partial/Pipeline status. If so, invoke the sync-architecture skill, passing it this
same diff range so it doesn't recompute it — that skill stays scoped to the architecture doc,
this one stays scoped to CHANGELOG.md/README/version.
Then run git status --short. A changelog entry documents committed history,
not the working tree — if uncommitted changes to source files are what the
entry is actually about, the version bump would land describing work that
isn't in the repo yet. Stop and ask the user whether to commit the underlying
change first, or whether this entry should wait. Don't bump the version over
unfinished/uncommitted work just because it exists in the working tree.
If offering to commit it, suggest both a message (50/72-char rule above) and
a branch name (<type>/<short-kebab-description>, same convention as the
branch-name check above) — this repo's fixes land on their own branch, not
committed straight onto dev/main. A message alone leaves the branch
question unanswered.
Only user-facing changes belong in the log: something a person using langgraph-harness (reviewer, admin, developer running the app) would notice or benefit from knowing about. Skip pure internal refactors, test-only changes, dependency bumps with no behavior change, formatting. A backend bug fix still counts as user-facing if it changes what the user observes (a crash stops happening, a run completes instead of hanging) — judge by observable effect, not by which files changed.
Two categories look plausible but aren't: dev/demo tooling (a seed-demo
script, fixture data, a debug-only flag) is for people developing the harness,
not people using it — skip it even when the commit says feat:. And
docs-site-only changes (content edits, landing-page copy, a docs-only script)
document the product but aren't the product — skip those too, unless the
change fixes something that breaks the site's actual function for a reader
(e.g. broken links/images from a wrong base path), which is a real bug, not
content.
2. Write entries in the existing style
Read the top 2-3 entries in CHANGELOG.md before writing — the format is
consistent across 30+ releases:
- One bullet per distinct change.
**Bold one-line hook naming the symptom or capability**— em dash — plain- prose explanation of the fix/behavior in user terms.- No internal file paths, function names, or variable names in the prose.
Describe outcomes ("the run now retries once before giving up"), not
implementation ("wrapped the call in
retryWithBackoff"). - Only three section headers ever appear, in this order when present:
### Features, then### Fixes, then### Breaking Changes. Don't invent new section names (no "Chores", "Internal", etc.) — if it doesn't fit one of these three, it probably doesn't belong in the log at all. ### Breaking Changesholds only entries where an existing user/config must change something to keep working — the header itself says "breaking", so don't also prefix the bullet with "Breaking:". Everything else that ships alongside it (the new capability the breaking change enables, unrelated fixes) still goes in### Features/### Fixesas normal.- Entries separate with a
---horizontal rule between version blocks.
3. Pick the version bump
This repo has only ever done patch and minor bumps (still on major 1) — but
apply real semver:
- Patch (
x.y.Z+1): only### Fixesin this release. - Minor (
x.Y+1.0): any### Featurespresent, even alongside fixes. - Major (
X+1.0.0): a breaking change — something existing users/configs must change to keep working (removed capability, incompatible data/config format, changed default that alters existing behavior) — goes in its own### Breaking Changessection at the end of the entry (see step 2), which is what actually triggers the major bump. Flag this explicitly to the user before bumping major; don't do it silently, since a major bump is an unusual call in this repo's history.
Insert the new block at the top of CHANGELOG.md, dated with today's actual
date (never fabricate — get it from the environment), then bump
package.json's version field to match. Run npm i right after so
package-lock.json's version field stays in sync — don't edit the lockfile
by hand or leave it stale.
4. Decide if a README needs updating
There are three: root README.md, backend/README.md, frontend/README.md.
Check all three, independently — a backend-only change might warrant updating
backend/README.md but not the root one, and vice versa.
A change is "worthy" of a README update if a developer or user would need to discover it to actually use that part of the app: a new script, a new required env var, a changed setup/prerequisite step, a new top-level capability the README already describes at a high level. It's not worthy if it's purely internal (a bug fix invisible to setup/usage, a refactor, a robustness improvement with no new surface).
For each of the three, if worthy: find the relevant existing section and update it in place, matching its existing tone and structure — don't add new sections speculatively. If not worthy: say so explicitly ("no README update needed — this is an internal fix with no new surface") rather than skipping the check silently.
5. Commit
Re-check git status --short right before committing — if the change being
documented still isn't committed (someone may have started editing again
mid-skill-run), stop instead of bumping the version ahead of it.
Stage the changed CHANGELOG.md, package.json, package-lock.json (from
the npm i in step 3), and any README files touched, and commit with the
repo's standard message:
chore: bump version and update changelogCount this subject line against the same 50/72-char limit before committing (step 1).
Don't fold in unrelated uncommitted changes — stage only the files this skill touched.
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.

