agentsclimarketplace

Docs refresh

Skill laurigates/claude-plugins/.claude/skills/docs-refresh

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.From its SKILL.md

Install
npx -y skills add laurigates/claude-plugins --skill docs-refresh

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

5.0 KB, as published. Nobody here has run it

/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 driftedA 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_danglingYou 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 CIEditing 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 agents suffix.
  • 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 typeWhat it meansFix
diagram_svg_stale / diagram_svg_node_missingThe committed .svg renders a per-plugin label the .d2 no longer statesRe-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_danglingA plugin README row advertises /<ns>:<name> with no matching skill directoryDelete 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

  1. git log --oneline <README-last-touched-sha>..HEAD -- '*/.claude-plugin/plugin.json' — if any new *-plugin directory 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.
  2. 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. 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

  1. 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.
  2. 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.

Keep looking

Skills are one crate of 613,297. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.