Agent-Skills.md

Agent Skills: Docs Checker

Audit context files (CLAUDE.md, .claude/ tree, READMEs, docs) for broken references and verifiably stale content. Runs a deterministic offline link/path checker first, then a bounded semantic review where every finding must cite evidence. Reports findings; fixes only on request.

UncategorizedID: lttr/claude-marketplace/docs-checker

Repository

lttr/claude-marketplace
lttrLicense: MIT
21

Install this agent skill to your local

pnpm dlx add-skill https://github.com/lttr/claude-marketplace/tree/HEAD/plugins/cc/skills/docs-checker

Skill Files

Browse the full folder contents for docs-checker.

Download Skill

Loading file tree…

plugins/cc/skills/docs-checker/SKILL.md

Skill Metadata

Name
docs-checker
Description
Audit context files (CLAUDE.md, .claude/ tree, READMEs, docs) for broken references and verifiably stale content. Runs a deterministic offline link/path checker first, then a bounded semantic review where every finding must cite evidence. Reports findings; fixes only on request.

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:

  1. Deterministic findings — the script output, summarized by file
  2. Semantic findings — each as: claim, evidence (file:line on both sides), suggested resolution
  3. 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