release-docs
Skill3 starsChanged 48 days agoMITView on GitHub
Bring every doc surface (site pages, the root and plugin READMEs, the root CLAUDE.md tree and cross-plugin references) in line with what a release ships. It runs the docs detector over origin/main..HEAD, applies the mechanical fixes, edits the rest in place from the sources, declares every new CHANGELOG entry in the coverage ledger, and verifies the result (re-detect, render-check, the docs-verifier agent, belts and guards). Use before a develop→main release, or when the "Docs Obligations" check is red. It runs locally or as the CI docs bot (mode=ci).
- Deletes or force-pushes
- Commits and pushes
8 other projects use a version of this.
Adopted by
Most recently taken up by
- caipe-io/ai-platform-engineeringtheir own version, first seen Nov 12, 2026
- AztecProtocol/aztec-packagestheir own version, first seen Nov 1, 2026
- greglas75/zuvotheir own version, first seen Oct 16, 2026
- turantekin/Parrottheir own version, first seen Oct 9, 2026
- rjdellecese/confecttheir own version, first seen Oct 8, 2026
- fastrepl/anarlogtheir own version, first seen Oct 8, 2026
Other versions8 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 8
- fastrepl/hyprnote★ 9.9ksame name
- fastrepl/anarlog★ 9.8ksame name
- AztecProtocol/aztec-packages★ 459same name
- cnoe-io/ai-platform-engineering★ 445same name
- caipe-io/ai-platform-engineering★ 444same name
- rjdellecese/confect★ 381same name
- turantekin/Parrot★ 130same name
- greglas75/zuvo★ 7same name
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 repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- doc-auditSkill
- feature-doneSkill
- progressive-disclosureSkill
- test-plugins-locallySkill
- validateSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. 0 are common, 2 are distinctive, and 13 are very specific to this project.
0
Common
Most of the 8 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 18
run directory: .release-docs/run/ (gitignored).
- Very specific: line 45
Read the report. If open is 0, reply "nothing to sync" and stop.
- Distinctive: line 67
Never state a capability, count, path or behaviour that no source states.
- Very specific: line 70
site/og.png: when site/og-card.html changes, regenerate the card with bash .claude/skills/release-docs/scripts/og-regen.sh, never by hand. - Very specific: line 71
Follow references/page-style.md on every page edit.
- Very specific: line 79
Never write waived: that disposition is the owner's.
- Very specific: line 91
Write the JSON array it returns to .release-docs/run/verifier.json yourself (the agent is read-only).
- Distinctive: line 97
Run the deterministic checks:
- Very specific: line 107
1: read post-checks.md. Fix only what is inside the doc surfaces, and run it again, at most 2 more times.
- Very specific: line 132
Commit on the branch when post-checks.sh exited 0, or when it exited 1 and the owner, shown what still fails, says to commit anyway.
- Very specific: line 135
Ask before pushing or opening a PR.
- Very specific: line 141
Doc surfaces only: Never edit CHANGELOGs, SKILL.md, agents, scripts, manifests or workflows.
- Very specific: line 144
Sources, not memory: Every new claim traces to a source Step 3 lists: a CHANGELOG entry, the README, the code (scripts/, skills/ and …
- Very specific: line 145
The snapshot is the fence's record: Never write .release-docs/run/before.snap after Step 0, and never commit after post-checks.sh exits 2.
- Very specific: line 147
mode=ci: no questions, no branch changes, no commits, no pushes.
“Common” is measured: kept by at least 6 in 10 of the 8 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
Release Docs — Sync the Docs With What a Release Ships
You are running the release docs sync. A script has already decided what must change (the obligations). Your job has three parts: make those changes truthfully from the sources, declare coverage in the ledger, and prove the result with the checks. Read references/obligations.md (what each obligation means and how to resolve it) and references/page-style.md (rules for every page edit) before editing anything.
Arguments: mode=local (the default) or mode=ci. In mode=ci, nobody will answer a question, so never ask one. Anything that needs a person goes into the report.
Paths used below:
- scripts:
.claude/skills/release-docs/scripts/docs-detect.sh,.claude/skills/release-docs/scripts/post-checks.sh,.claude/skills/release-docs/scripts/render-check.shand.claude/skills/release-docs/scripts/og-regen.sh - surfaces:
.github/docs-surfaces.json(at the repo root, not under this skill) - ledger:
.github/docs-ledger.json - run directory:
.release-docs/run/(gitignored). It holdsbefore.snap,obligations.before.json,verifier.json,post-checks.md,pr-body.mdandshots/.
Guard
.claude-plugin/marketplace.jsonmust exist in the working directory. If it doesn't, you're not at the claude-plugins root: stop.- Tracked files must be clean (
git diff --quiet HEAD). If they aren't, stop and say which files are dirty. Untracked files belong to the owner: never touch them. mode=local: if the current branch ismainordevelop, rungit switch -c docs/release-sync-<YYYYMMDD>first. Never commit onmainordevelop.mode=ci: the workflow has already created the branch and written the snapshot to.release-docs/run/before.snap. Never create or switch branches, commit, or push. Never runpost-checks.sh --snapshot: the workflow owns the snapshot, and--snapshotrefuses to overwrite an existing file.
Step 0: Snapshot
mode=local only (CI has already done this). Start from an empty run directory, so no file from an earlier run is read as this run's:
rm -rf .release-docs/run && mkdir -p .release-docs/run
git fetch -q origin main
bash .claude/skills/release-docs/scripts/post-checks.sh --snapshot .release-docs/run/before.snapThe snapshot is JSON: HEAD, plus every path dirty before the run with a digest of its content. The write fence in Step 5 compares against it. Never write to before.snap after this step.
Step 1: Detect
bash .claude/skills/release-docs/scripts/docs-detect.sh --out .release-docs/run/obligations.before.jsonRead the report. If open is 0, reply "nothing to sync" and stop.
Step 2: Mechanical fixes
bash .claude/skills/release-docs/scripts/docs-detect.sh --fix-mechanicalThe fixer rewrites the version badges and the landing grid cards from plugin.json, which closes those obligations. It never reads the page a card links to, and nothing re-detects what a new card text makes false there. So this step owns it: for each card-description obligation in .release-docs/run/obligations.before.json, read that plugin's own page, site/<plugin>/index.html, and fix any narrative the new card text contradicts. Use Step 3's sources and rules.
Step 3: Content edits
Resolve every open obligation whose resolver is model, in this order: plugin pages, then the landing page, then READMEs and the root CLAUDE.md, then plugin references (<plugin>/references/** and <plugin>/skills/*/references/**) that an obligation names.
Sources, in order of authority:
- The plugin's CHANGELOG. The entries in the range come first. Each
changelog-entryobligation carries itstext, cut at 200 characters, so read the whole bullet in the CHANGELOG. Older entries for the same plugin are valid sources too, for debt from before the range: astale-mentionof aretired[]token has no entry in the range by construction. - The plugin's README.
- SKILL.md frontmatter.
- The range diff:
git diff <base>..HEAD -- <plugin>/, wherebaseis the report'srange.base.
- Behaviour: the code wins. For what a plugin does, its code (
scripts/, theSKILL.mdbodies andagents/) is authoritative. When the README contradicts it, follow the code and citefile:line. If that README is a doc surface, fix it from the code too. - Sources that disagree. When a lower source contradicts a higher one (say, frontmatter against the README or a CHANGELOG entry), follow the higher one and report the stale lower one for the owner. Frontmatter, SKILL.md bodies, scripts and CHANGELOGs are outside the fence: never edit them.
- Never state a capability, count, path or behaviour that no source states.
- The plugin's CHANGELOG. The entries in the range come first. Each
- Plugin references are plugin behaviour.
<plugin>/references/**and<plugin>/skills/*/references/**are doc surfaces, but they are also the instructions a skill or agent runs on. Touch one only to resolve an obligation that names it, and then change only the stale name or claim: never its instructions. page-missingfor a site page: invoke the walkthrough document skill (Skilltool,walkthrough:document, arguments<plugin> site/<plugin>/index.html) from this main session. It can't be dispatched to a subagent. Then follow thepage-missingrow ofreferences/obligations.md.site/og.png: whensite/og-card.htmlchanges, regenerate the card withbash .claude/skills/release-docs/scripts/og-regen.sh, never by hand. If it printsog.png NOT regenerated,site/og.pngis untouched; put that in the report for the owner.- Follow
references/page-style.mdon every page edit. - A
stale-mentionof a live name is a false positive. The detector reads retirement sentences in the range's CHANGELOG entries, and one that names a live thing ("Removed the--xflag from<name>") can make that name a candidate. When the token is a range candidate (listed by--candidates, not inretired[]) and a plugin source still has it as a live name, never rewrite the line: the docs are right. Add the token tolive[]in.github/docs-surfaces.json, and name the plugin source in the report. A plugin source that has it only as a legacy, fallback or migrated-from name does not make it live: treat it as retired. When no plugin source has it and it still looks live, leave the obligation open, and list it in the report for the owner.
Step 4: Ledger
- For each
changelog-entryobligation, add itsidto.github/docs-ledger.jsonentries:{"disposition": "covered", "at": ["<file>#<anchor>", …]}, pointing at the text that documents it;- or
{"disposition": "not-user-facing", "reason": "…"}.
- Never write
waived: that disposition is the owner's. - For a
stale-mentionyou decide is deliberately historical, add anintentionalentry:file,token(the obligation's owntoken),context(a phrase on that exact line) andreason. - List the range candidates with
bash .claude/skills/release-docs/scripts/docs-detect.sh --candidates origin/main..HEAD. Append each one you confirmed as retired toretired[]in.github/docs-surfaces.json. Append each one that is still a live name tolive[], and only when a plugin source still has it: the write fence fails an entry that no plugin source has. - In
.github/docs-surfaces.json, change only theog,retiredandlivekeys. The write fence fails the run ifsurfaces,frozen,pagesorlandingchange.
Step 5: Verify
- Re-detect with
bash .claude/skills/release-docs/scripts/docs-detect.sh --gate. If obligations are still open, fix what can be fixed inside the doc surfaces and re-detect, at most 2 more times. Then list every obligation still open, and why, in the report and go on. Some are the owner's by rule, such as a manifestinventory-row(references/obligations.mdnote 1) or astale-mentionof a name that still looks live when no plugin source has it (Step 3). Dispatch the
docs-verifieragent. Its prompt is two things:- the output of
git diff HEADover the changed doc files. A new file (such as a generated page) is untracked, sogit diff HEADleaves it out: addgit diff --no-index -- /dev/null <file>for each one; - the source paths: each changed plugin's
CHANGELOG.md,README.md,skills/,agents/andscripts/.
Write the JSON array it returns to
.release-docs/run/verifier.jsonyourself (the agent is read-only).- Fix each
refutedclaim everywhere it appears on that page, including lines you didn't change (the verifier also judges claims carried over on a changed line). Fix it as well in the page's own source doc when that is a doc surface (the plugin's README, for its site page). Anywhere else it appears, don't fix it: list each place in the report. - Cut each
unsupportedclaim, or rewrite it to what a source states. - Dispatch the verifier once more on the new diff (at most 2 rounds). Keep the final array in
verifier.json; any non-okitems left are reported, not hidden.
If the verifier can't be dispatched, or returns no JSON array, don't write
verifier.jsonand say so in the report. The PR body is still built with that path (by Step 6 locally, by the workflow in CI), so it shows "verifier output missing" rather than leaving the section out.- the output of
Run the deterministic checks:
bash .claude/skills/release-docs/scripts/post-checks.sh --before .release-docs/run/before.snap \ --report .release-docs/run/post-checks.md --shots .release-docs/run/shotspost-checks.shruns the write fence, the no-waiver check, the gate,render-check.shon the changed pages (against HEAD's copy of each), and every belt and guard. A failing belt or guard is named inpost-checks.mdwith itsFAILlines. Its exit code decides what happens next:- 0: everything passed, unless the report has a
- SKIPPED:line. That line meansRELEASE_DOCS_SKIPis set and a step never ran: unset it and run again. Never commit on a report with one. 1: read
post-checks.md. Fix only what is inside the doc surfaces, and run it again, at most 2 more times. Then list every failure that can't be fixed inside the fence in the report, and go on to Step 6. Those include:- obligations that are the owner's by rule;
- belts and guards that fail outside the surfaces;
- a fence failure on a path the owner had dirty before the run.
An overflow at 500px that HEAD's copy of the page already had, and that didn't grow, is not a failure: the report lists it as a note (
references/page-style.mdrule 11).In
mode=ci, anote:under the write fence naming the Bash sandbox's /dev/null mount (.vscode,.claude/commands,.bashrc, …) is not a failure either: the sandbox makes that file for each command and removes it afterwards. Leave it alone.- 2: bad input. The fence didn't run, so the tree is unchecked. Stop, and never commit it.
- 0: everything passed, unless the report has a
Step 6: Report
mode=local:Build the PR body, with the post-checks report first (its
<and>escaped, so no file name in it can hide what follows). Always pass--verifier, even when the verifier didn't run:{ printf '### Post-checks\n\n' sed -e 's/&/\&/g' -e 's/</\</g' -e 's/>/\>/g' .release-docs/run/post-checks.md printf '\n' bash .claude/skills/release-docs/scripts/docs-detect.sh --pr-body \ --before .release-docs/run/obligations.before.json \ --verifier .release-docs/run/verifier.json; } > .release-docs/run/pr-body.md- Show the owner every section: post-checks, resolved, still open, other edits, ledger and config changes, and verifier disagreements. Point them at
.release-docs/run/shots/. A file under "Other edits" marked plugin-internal needs a version bump and a CHANGELOG entry if the owner keeps it. - Commit on the branch when
post-checks.shexited 0, or when it exited 1 and the owner, shown what still fails, says to commit anyway. Never commit after exit 2.git addeach file this run changed, by name: the doc surfaces,.github/docs-ledger.json,.github/docs-surfaces.json,site/og.pngand any newsite/<plugin>/index.html. Nevergit add -Aorgit add ..git commitasdocs(release): sync docs for <base7>..<head7>(the 7-character SHAs of the report'srange), with the repo'sCo-Authored-Bytrailer.
- Ask before pushing or opening a PR. A docs PR targets
develop:gh pr create --base develop.
mode=ci: don't run the--pr-bodycommand. Reply with one line of counts (resolved / still open / verifier disagreements). The workflow builds the PR body itself, re-runs post-checks independently, then commits, pushes and opens the PR.
Key Rules
- Truth over green. A badge-only edit, a
coveredpointer at an unrelated anchor, or anintentionalon a genuinely stale line makes the gate pass without making the docs true. That's the exact failure this skill exists to prevent. - Doc surfaces only. Never edit CHANGELOGs, SKILL.md, agents, scripts, manifests or workflows.
post-checks.shrestores anything outside the surfaces and fails the run. A plugin reference is a surface, but touch one only for an obligation that names it, and never change its instructions. .github/docs-surfaces.json:og,retiredandliveonly. A change tosurfaces,frozen,pagesorlandingfails the write fence.- Never
waived, never<head>exceptog-copy(or a new page's head block underpage-missing), never frozen docs. - Sources, not memory. Every new claim traces to a source Step 3 lists: a CHANGELOG entry, the README, the code (
scripts/,skills/andagents/), frontmatter or the range diff. Those are the paths Step 5.2 gives the verifier, which checks every claim against them. - The snapshot is the fence's record. Never write
.release-docs/run/before.snapafter Step 0, and never commit afterpost-checks.shexits 2. Inmode=ci, never runpost-checks.sh --snapshotat all: the workflow owns the snapshot. - Bounded loops. The re-detect and post-checks loops each get at most 2 more runs. After that, report what is left instead of retrying.
mode=ci: no questions, no branch changes, no commits, no pushes.
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.

