agentleFS
ApurvBazariApurvBazari/claude-plugins/.claude/skills/release-docs/SKILL.md

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

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
  1. Very specific:

    run directory: .release-docs/run/ (gitignored).

    line 18
  2. Very specific:

    Read the report. If open is 0, reply "nothing to sync" and stop.

    line 45
  3. Distinctive:

    Never state a capability, count, path or behaviour that no source states.

    line 67
  4. Very specific:

    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.

    line 70
  5. Very specific:

    Follow references/page-style.md on every page edit.

    line 71
  6. Very specific:

    Never write waived: that disposition is the owner's.

    line 79
  7. Very specific:

    Write the JSON array it returns to .release-docs/run/verifier.json yourself (the agent is read-only).

    line 91
  8. Distinctive:

    Run the deterministic checks:

    line 97
  9. Very specific:

    1: read post-checks.md. Fix only what is inside the doc surfaces, and run it again, at most 2 more times.

    line 107
  10. Very specific:

    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.

    line 132
  11. Very specific:

    Ask before pushing or opening a PR.

    line 135
  12. Very specific:

    Doc surfaces only: Never edit CHANGELOGs, SKILL.md, agents, scripts, manifests or workflows.

    line 141
  13. Very specific:

    Sources, not memory: Every new claim traces to a source Step 3 lists: a CHANGELOG entry, the README, the code (scripts/, skills/ and …

    line 144
  14. Very specific:

    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.

    line 145
  15. Very specific:

    mode=ci: no questions, no branch changes, no commits, no pushes.

    line 147

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.sh and .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 holds before.snap, obligations.before.json, verifier.json, post-checks.md, pr-body.md and shots/.

Guard

  • .claude-plugin/marketplace.json must 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 is main or develop, run git switch -c docs/release-sync-<YYYYMMDD> first. Never commit on main or develop.
  • 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 run post-checks.sh --snapshot: the workflow owns the snapshot, and --snapshot refuses 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.snap

The 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.json

Read 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-mechanical

The 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:

    1. The plugin's CHANGELOG. The entries in the range come first. Each changelog-entry obligation carries its text, 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: a stale-mention of a retired[] token has no entry in the range by construction.
    2. The plugin's README.
    3. SKILL.md frontmatter.
    4. The range diff: git diff <base>..HEAD -- <plugin>/, where base is the report's range.base.
    • Behaviour: the code wins. For what a plugin does, its code (scripts/, the SKILL.md bodies and agents/) is authoritative. When the README contradicts it, follow the code and cite file: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.
  • 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-missing for a site page: invoke the walkthrough document skill (Skill tool, walkthrough:document, arguments <plugin> site/<plugin>/index.html) from this main session. It can't be dispatched to a subagent. Then follow the page-missing row of references/obligations.md.
  • 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. If it prints og.png NOT regenerated, site/og.png is untouched; put that in the report for the owner.
  • Follow references/page-style.md on every page edit.
  • A stale-mention of 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 --x flag from <name>") can make that name a candidate. When the token is a range candidate (listed by --candidates, not in retired[]) and a plugin source still has it as a live name, never rewrite the line: the docs are right. Add the token to live[] 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-entry obligation, add its id to .github/docs-ledger.json entries:
    • {"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-mention you decide is deliberately historical, add an intentional entry: file, token (the obligation's own token), context (a phrase on that exact line) and reason.
  • 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 to retired[] in .github/docs-surfaces.json. Append each one that is still a live name to live[], 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 the og, retired and live keys. The write fence fails the run if surfaces, frozen, pages or landing change.

Step 5: Verify

  1. 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 manifest inventory-row (references/obligations.md note 1) or a stale-mention of a name that still looks live when no plugin source has it (Step 3).
  2. Dispatch the docs-verifier agent. Its prompt is two things:

    • the output of git diff HEAD over the changed doc files. A new file (such as a generated page) is untracked, so git diff HEAD leaves it out: add git diff --no-index -- /dev/null <file> for each one;
    • the source paths: each changed plugin's CHANGELOG.md, README.md, skills/, agents/ and scripts/.

    Write the JSON array it returns to .release-docs/run/verifier.json yourself (the agent is read-only).

    • Fix each refuted claim 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 unsupported claim, 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-ok items left are reported, not hidden.

    If the verifier can't be dispatched, or returns no JSON array, don't write verifier.json and 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.

  3. 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/shots

    post-checks.sh runs the write fence, the no-waiver check, the gate, render-check.sh on the changed pages (against HEAD's copy of each), and every belt and guard. A failing belt or guard is named in post-checks.md with its FAIL lines. Its exit code decides what happens next:

    • 0: everything passed, unless the report has a - SKIPPED: line. That line means RELEASE_DOCS_SKIP is 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.md rule 11).

      In mode=ci, a note: 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.

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/&/\&amp;/g' -e 's/</\&lt;/g' -e 's/>/\&gt;/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.sh exited 0, or when it exited 1 and the owner, shown what still fails, says to commit anyway. Never commit after exit 2.
      • git add each file this run changed, by name: the doc surfaces, .github/docs-ledger.json, .github/docs-surfaces.json, site/og.png and any new site/<plugin>/index.html. Never git add -A or git add ..
      • git commit as docs(release): sync docs for <base7>..<head7> (the 7-character SHAs of the report's range), with the repo's Co-Authored-By trailer.
    • Ask before pushing or opening a PR. A docs PR targets develop: gh pr create --base develop.
  • mode=ci: don't run the --pr-body command. 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 covered pointer at an unrelated anchor, or an intentional on 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.sh restores 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, retired and live only. A change to surfaces, frozen, pages or landing fails the write fence.
  • Never waived, never <head> except og-copy (or a new page's head block under page-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/ and agents/), 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.snap after Step 0, and never commit after post-checks.sh exits 2. In mode=ci, never run post-checks.sh --snapshot at 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.