laurigates /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 README / PLUGIN-MAP / the d2 diagram drifted | A plugin needs adding/removing — follow CLAUDE.md § 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:
README.md— the| **<plugin>** | N | ... |category-table rows. Preserve any+ M agentssuffix.docs/PLUGIN-MAP.md— the| <plugin> | N | ... |tier-table rows.docs/diagrams/plugin-relationships.d2— thelabel: "<name>\nN skills"node labels. The.svgis 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*-plugindirectory landed, it must be added to README's category tables, PLUGIN-MAP, marketplace.json, and release config (see CLAUDE.md § 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 belowTOTAL_SKILLSfrom the audit.
Step 4: Re-render the diagram
If the d2 changed: d2 docs/diagrams/plugin-relationships.d2 docs/diagrams/plugin-relationships.svg.
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:
curl -fsSL https://d2lang.com/install.sh -o /tmp/d2-install.sh
# read /tmp/d2-install.sh, then:
sh /tmp/d2-install.sh
Download-review-run, 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.
Pin the version the committed .svg was rendered with — read it off the file's
own data-d2-version="..." attribute — so the diff is the label change and not a
whole-file renderer churn.
Step 5: Verify and commit
bash scripts/check-docs-index.sh --strictmust exit 0 (STATUS=OK).DIAGRAM_SVG_NODESshould equalDIAGRAM_NODES— a smaller number means the.svgis missing nodes the.d2declares.- Commit as
docs: refresh plugin catalog counts(thedocs:type triggers no release bump). Stage only the catalog files you touched — nevergit 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.