laurigateslaurigates/claude-plugins/.claude/skills/docs-refresh/SKILL.md

docs-refresh

Skill59 starsChanged 8 days agoMITView on GitHub

Refresh plugin catalog docs (README, PLUGIN-MAP, d2 diagram) so per-plugin skill/agent counts match disk. Use when fixing count drift or after adding skills.

Pipes a download into a shell

3 other projects use a version of this.

Adopted by

Most recently taken up by

MichinaoShimizu/kirokutheir own version, first seen Oct 11, 2026
genlayerlabs/skillstheir own version, first seen Jul 29, 2026
dadwadw233/team-collab-skillstheir own version, first seen May 6, 2026

Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
genlayerlabs/skills★ 19same name
dadwadw233/team-collab-skills★ 4same name
MichinaoShimizu/kiroku★ 2same 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 repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- marketplace-authoringSkill

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific
could be automatic: a setting could enforce it

Very specific:
Run bash scripts/check-docs-index.sh (shown in Context).
line 37
Very specific:
Update the rounded total in README's intro line (NNN+ skills) to the next round number at or below TOTAL_SKILLS from the audit.
line 68
Very specific:
If the d2 changed: d2 docs/diagrams/plugin-relationships.d2 docs/diagrams/plugin-relationships.svg, or just render-diagrams, which refuses …
line 73
Very specific:
Commit the .d2 and .svg together — always in the same commit.
line 76
Very specific:
If d2 is not installed, install it rather than hand-editing the .svg.
line 81
Distinctive:
Use the official installer, download-review-run:
line 123
Very specific:
Commit as docs: refresh plugin catalog counts (the docs: type triggers no release bump).
line 140

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “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

/docs-refresh

Refresh this repo's top-level catalog docs so the stated plugin/skill/agent counts and the plugin set match what is actually on disk. The detector is scripts/check-docs-index.sh; this skill is the fixer that consumes its report.

When to Use This Skill

Use this skill when...	Use something else when...
Per-plugin counts in the README headline / PLUGIN-MAP / the d2 diagram drifted	A plugin needs adding/removing — follow `/marketplace-authoring` § Plugin Lifecycle first, then run this
`check-docs-index.sh` reports `doc_count_drift` / `diagram_count_drift` / `diagram_svg_stale` / `readme_row_dangling`	You need a generic project's docs synced — that's `documentation-plugin:docs-sync` (wrong layout for this repo)
The PR gate `Check docs-index drift` failed in CI	Editing rule-index or marketplace set — the audit reports those, but fix them at their source

Context

Audit: !bash scripts/check-docs-index.sh
README last touched: !git log --max-count=1 --format='%h %ci' -- README.md

Execution

Execute this refresh:

Step 1: Read the drift

Run bash scripts/check-docs-index.sh (shown in Context). Each ISSUES: line names the exact file, line, and the disk-vs-stated count. STATUS=OK with ISSUE_COUNT=0 means nothing to do — stop and report clean.

Step 2: Apply count fixes

For every doc_count_drift / diagram_count_drift issue, Edit the stated count to the disk count:

docs/CATALOG.md — never hand-edited; just catalog regenerates it from marketplace.json and the plugin dirs (CI: Check catalog is current).
docs/PLUGIN-MAP.md — the | <plugin> | N | ... | tier-table rows.
docs/diagrams/plugin-relationships.d2 — the label: "<name>\nN skills" node labels. The .svg is generated and never hand-edited; re-render it in Step 4.

Step 2b: Apply name-level fixes

Two ERROR-severity issue types are name drift, not count drift — no /docs-refresh arithmetic repairs them:

Issue type	What it means	Fix
`diagram_svg_stale` / `diagram_svg_node_missing`	The committed `.svg` renders a per-plugin label the `.d2` no longer states	Re-render (Step 4). Never hand-edit the `.svg` to agree — Check 6 compares label text only and cannot tell a hand-patch from a render
`readme_row_dangling`	A plugin README row advertises `/<ns>:<name>` with no matching skill directory	Delete the row if the skill never existed, or correct it to the real invocation path. Resolution is exact, so a row that is a shorthand for a longer directory is a real finding — fix the row, not the check

Step 3: Light content pass

git log --oneline <README-last-touched-sha>..HEAD -- '*/.claude-plugin/plugin.json' — if any new *-plugin directory landed, it must be added to PLUGIN-MAP, marketplace.json (which just catalog reads), and release config (see /marketplace-authoring § Plugin Lifecycle). Surface this rather than guessing a category.
Update the rounded total in README's intro line (NNN+ skills) to the next round number at or below TOTAL_SKILLS from the audit.

Step 4: Re-render the diagram

If the d2 changed: d2 docs/diagrams/plugin-relationships.d2 docs/diagrams/plugin-relationships.svg, or just render-diagrams, which refuses a d2 whose version differs from the one the .svg records and falls back to the cloud-session install under tmp/d2/. Commit the .d2 and .svg together — always in the same commit. Check 6 is ERROR severity, so a .d2 edit pushed without its re-rendered .svg fails the always-on Check docs-index drift gate; that is deliberate (#2453, where the .svg sat stale behind STATUS=OK).

If d2 is not installed, install it rather than hand-editing the .svg. The .svg is only ever re-rendered by d2; Check 6 compares label text and cannot tell a hand-patch from a render, so a hand-edit passes the gate while leaving the file out of step with what d2 would produce.

Install the version the committed .svg was rendered with, read off its own data-d2-version="..." attribute (v0.9.0 as of #3487), so the diff is the label change and not whole-file renderer churn:

grep -o 'data-d2-version="[^"]*"' docs/diagrams/plugin-relationships.svg

Cloud sessions

Claude Code cloud sessions do not ship d2, and both mise/aqua and https://d2lang.com/install.sh resolve the release through api.github.com, which answers 403 there. Download the release asset from github.com instead and run the binary from the extracted tree (substitute the version from the .svg):

mkdir -p tmp/d2
curl -fsSL -o tmp/d2/d2-v0.9.0-linux-amd64.tar.gz https://github.com/terrastruct/d2/releases/download/v0.9.0/d2-v0.9.0-linux-amd64.tar.gz
curl -fsSL -o tmp/d2/SHA256SUMS https://github.com/terrastruct/d2/releases/download/v0.9.0/SHA256SUMS
(cd tmp/d2 && sha256sum --ignore-missing -c SHA256SUMS)
tar -xzf tmp/d2/d2-v0.9.0-linux-amd64.tar.gz -C tmp/d2
tmp/d2/d2-v0.9.0/bin/d2 --version
tmp/d2/d2-v0.9.0/bin/d2 docs/diagrams/plugin-relationships.d2 docs/diagrams/plugin-relationships.svg

tmp/ is git-ignored. SHA256SUMS comes from the same release page as the tarball, so the check catches a corrupt or truncated download, not a tampered release. The independent digest GitHub reports for each asset is served only by api.github.com, which may not be reachable from the session; when it is not, say in the PR that the digest was checked against SHA256SUMS only.

On 2026-11-07 a cloud session rendered the then-current .d2 with this binary and the output was byte-identical to the committed .svg.

Local sessions

Use the official installer, download-review-run:

curl -fsSL https://d2lang.com/install.sh -o /tmp/d2-install.sh
# read /tmp/d2-install.sh, then:
sh /tmp/d2-install.sh

Not curl … | sh: the piped form is blocked by this repo's own hooks-plugin/hooks/bash-antipatterns.sh safety rule, so a skill that prescribed it would dead-end the agent it was guiding.

Step 5: Verify and commit

bash scripts/check-docs-index.sh --strict must exit 0 (STATUS=OK). DIAGRAM_SVG_NODES should equal DIAGRAM_NODES — a smaller number means the .svg is missing nodes the .d2 declares.
Commit as docs: refresh plugin catalog counts (the docs: type triggers no release bump). Stage only the catalog files you touched — never git add -A.

Post-actions

Report the before/after counts and confirm the audit is clean. The PR gate (Check docs-index drift in plugin-pr-checks.yml) will re-verify on push.

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.

Check your setup, free