Docs Checker
Audit the repository's context files — CLAUDE.md at any depth, the .claude/ tree (skills, rules, commands), READMEs, and the docs tree — for correctness. This is a conservative audit: report findings with evidence, do not rewrite anything unless the user asks. Style, tone, and level of detail are the author's choices and are out of scope.
Prerequisites
- Node.js >= 22 (the bundled script uses
fs.globSync)
Workflow
1. Deterministic pass
Run the bundled checker from the repo root:
node ${CLAUDE_SKILL_DIR}/scripts/docs-check.mjs $ARGUMENTS
It needs no config and no dependencies. What it does:
- Checks relative/absolute markdown links and image assets against the working tree
- Checks backticked source paths in prose (
src/foo.ts, @alias/bar) against the codebase, resolving tsconfig/package.json aliases
- Scans the paths you name (or the repo's docs tree by default), plus every
CLAUDE.md and the whole .claude/ tree automatically
- Cross-repo docs: pass
--repo=NAME:DIR for each sibling checkout the docs reference
Exit 0 is clean, 1 means findings (printed as line:col rule message with did-you-mean hints), 2 is bad invocation. Its findings are ground truth — do not second-guess them.
2. Semantic pass
Read the context files the script scanned — but keep this pass on a scoped diet: CLAUDE.md files, the .claude/ tree, and top-level READMEs. Do not crawl the whole docs tree unless the user asked; the script already covered the wide surface.
Look only for claims you can verify against the repo right now:
- Commands or scripts quoted in docs that don't exist (check
package.json scripts, Makefile, bundled scripts)
- Described behavior that contradicts the code it points at (read the code before claiming this)
- Instructions that contradict each other across context files
- Sections duplicated between files (e.g. README and CLAUDE.md drifting apart)
- References to tools, versions, or structures the repo no longer uses
Rules that keep this pass honest:
- Every finding must cite its evidence — the file and line that proves the claim stale. If you cannot point at proof, it is not a finding.
- No style or wording opinions. "Could be clearer" is not a finding.
- When unsure whether something is stale or intentional, list it under "unverified" rather than asserting it.
3. Report
Present one combined report:
- Deterministic findings — the script output, summarized by file
- Semantic findings — each as: claim, evidence (file:line on both sides), suggested resolution
- Unverified observations — only if any; clearly separated
End with the totals. Do not edit any file. If findings exist, offer to fix them — deterministic findings (broken links, moved paths) are safe to fix mechanically once the user agrees; semantic findings need the user to decide the correct current truth first.
Suppressions
The script honors inline suppressions the user may already have in place:
<!-- docs-check-ignore --> at the end of a line<!-- docs-check-disable --> … <!-- docs-check-enable --> around a region--no-agent-docs flag to skip CLAUDE.md/.claude/ scanning