| name | changelog-generation |
| description | Changelog generation skill for ZeroClaw releases. Use this skill when the user wants to generate a changelog, prepare release notes, or summarize what changed between versions. Trigger on: 'generate changelog', 'changelog for v0.7.x', 'prepare release notes', 'what changed since <tag>', 'write the changelog', 'CHANGELOG-next', 'release notes for the next release'. |
ZeroClaw Changelog Generation
You are generating a human-friendly CHANGELOG-next.md for a ZeroClaw release.
The GitHub CLI (gh) is available and authenticated. The local repository is
checked out and up to date.
Before You Start
This SKILL.md is the full, self-contained procedure. Follow the workflow below
exactly on every run; do not rely on memory of a prior run.
Invocation
Default — last stable tag to HEAD:
generate changelog
write the changelog
CHANGELOG-next
prepare release notes
Explicit range:
changelog for v0.7.2
changelog v0.7.1..v0.7.2
what changed since v0.7.1
release notes v0.7.1 to v0.7.2
Workflow
Phase 1 — Establish the range
- If the user provided a range, normalise to
<from>..<to>: vX → vX..HEAD;
vX..vY → as given; vX vY → vX..vY.
- If no range was given, resolve the last stable tag automatically. Both
-beta.N (older) and -beta-N (current) pre-release formats exist, so anchor
on a plain version shape rather than excluding a -beta separator:
git tag --sort=-creatordate | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1
- Verify both refs exist (
git rev-parse --verify). If either is missing, stop
and tell the user what was not found.
- Report the resolved range to the user before continuing.
Phase 2 — Collect and categorise commits
Run all fetches in a single parallel batch — do not wait for one before starting
the next:
git log <from>..<to> --pretty=format:"%H %h %s" --no-merges
git log <from>..<to> --pretty=format:"%H" --no-merges
Map each commit to a section by its conventional-commit prefix. Read and
categorise prefix-less commits by content; never drop one silently.
| Prefix | Section |
|---|
feat | What's New |
fix | Bug Fixes |
refactor, perf | What's New (as "Improvements") |
security, security-scoped fix | What's New → Security |
docs | What's New → Documentation (omit trivial typos) |
chore, ci, build | Omit unless user-visible (install path, dropped platform) |
! suffix / BREAKING CHANGE | Breaking Changes (always surface) |
Phase 3 — Resolve contributors
Use the GitHub GraphQL commit authors field (returns author + co-authors). Do
not use git log --pretty=format:"%an" alone — it misses Co-Authored-By
contributors.
gh api graphql -f query='
{ repository(owner:"zeroclaw-labs", name:"zeroclaw") {
ref(qualifiedName:"refs/heads/master") { target { ... on Commit {
history(first:100) {
pageInfo { hasNextPage endCursor }
nodes { oid authors(first:10) { nodes { user { login } email } } }
} } } } } }'
Page by adding after:"<endCursor>" while hasNextPage is true. Cross-reference
each oid against the Phase 2 SHA list to stay in range, collect unique logins,
then exclude:
- logins ending in
[bot], plus web-flow, dependabot, github-actions,
blacksmith
- emails matching
*noreply*
- AI model names as author names:
Claude, Copilot, ChatGPT, Codex,
Gemini, and anything matching ^(gpt|claude|gemini|copilot)-
Sort case-insensitively and prefix each with @.
Phase 4 — Write the changelog
Write these sections in order; omit any with no content:
- Preamble (2–3 sentences — release theme, scale, reader context)
- Highlights (4–6 user-visible bullet points)
- What's New (grouped by area, human-readable sentences, PR references)
- Bug Fixes (summary table: Area | Fix)
- Breaking Changes (omit section entirely if none)
- Contributors (
@login handles, case-insensitive sort, one per line)
- Footer (full diff reference)
Write to two locations:
tmp/CHANGELOG-next.md — for in-session review before committingCHANGELOG-next.md in the repository root — the path the release workflows read
Phase 5 — Review and confirm
Present a summary to the user:
- Range covered
- Commit count by category
- Contributor count
- Any commits that had no conventional prefix (so the user can sanity-check
categorisation)
Ask the user to review tmp/CHANGELOG-next.md before committing. Do not
proceed to Phase 6 without explicit confirmation.
Phase 6 — Commit and push
Only after the user confirms the content:
git add CHANGELOG-next.md
git commit -m "chore(release): add CHANGELOG-next.md for vX.Y.Z"
git push upstream <branch>
Replace vX.Y.Z with the next release version — ask the user if unsure.
Push to the open release PR branch on zeroclaw-labs/zeroclaw. Do not push
to master directly.
Execution rules
- This SKILL.md is self-contained and authoritative. Follow the phases
above; do not look for a separate protocol file.
- Always report the resolved range before doing any work. The user should
confirm the range is correct before you collect commits.
- Never drop commits silently. Every commit in the range must be accounted for
in the output — either surfaced in a section or explicitly noted as omitted (e.g.
trivial typo fix in docs).
- Always use the GraphQL contributor path.
git log --format="%an" alone is
not acceptable — it produces an incomplete contributor list.
- Always apply the full filter list. Bots, noreply addresses, and AI model
names must be excluded from the contributor section.
- Always write to
tmp/CHANGELOG-next.md first. The user reviews before the
file is committed to the repository root.
- Always confirm before committing. Show the user the exact commit message
and ask for an explicit yes. Do not infer consent from prior steps.
- Never push to
master directly. Always push to the open release PR branch.
- Do not delete
CHANGELOG-next.md manually. The file is intentionally left on
master between releases and is overwritten at the start of the next release cycle.
No cleanup is needed after a release ships.
