agentleFS
junhjangjunhjang/claude-harness/.claude/skills/audit-docs/SKILL.md

audit-docs

Skill0 starsChanged 6 months agoMITView on GitHub

Audit docs/ for drift — index reachability, doc-pattern conformance, dead markdown links, frontmatter validity, ADR id density, staleness, in-prose citation resolution, cross-doc duplication. Run when about to edit anything under docs/, when asked to review docs, when asked if docs are healthy, when asked to check for stale frontmatter / dead links / index drift / doc-pattern violations. Deterministic ($0, no LLM calls), read-only against docs/, writes AUDIT-typed report to .claude/audits/.

17 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use diagnose and skill-creator.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    diagnose

    Use to systematically diagnose why scenarios fail — identifies root causes by analyzing agent traces, codebase, and behavioral patterns

    Also in 3 projects that use this

  • SentrySkill

    skill-creator

    Create new agent skills following the Agent Skills specification. Use when asked to "create a skill", "add a new skill", "write a skill", "make a skill", "build a skill", or scaffold a new skill with SKILL.md. Guides through requirements, writing, registration, and verification.

    Also in 4 projects that use this

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 3 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 16 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Index consistency: every file under docs/ is reachable from CLAUDE.md (transitively).

    line 12
  2. Distinctive:

    Run the implementation in manual mode:

    line 20
  3. Very specific:

    D1 — Index reachability: every doc under docs/ is transitively reachable from CLAUDE.md.

    line 32
  4. Distinctive:

    D3 — Dead links: every relative markdown link resolves.

    line 34
  5. Very specific:

    D5 — ADR id density: if docs/decisions/ exists, ids are dense (no gaps).

    line 35
  6. Distinctive:

    After the script returns, report to operator: blockers count, warnings count, infos count, audit file path.

    line 38
  7. Very specific:

    Read-only against docs/: Never auto-fix doc text. Audits report.

    line 44
  8. Very specific:

    Deterministic-only: No LLM calls under any flag.

    line 45

“Common” is measured: kept by at least 6 in 10 of the 16 edited versions of this file we could read. “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

/audit-docs

Note: Ships with a foundation stub at scripts/cron/c1_docs_audit.py covering D1–D3 + D5 (index reachability, frontmatter, dead links, ADR id density). The full SPEC defines D1–D11 — extend the stub in your consuming repo as you adopt the remaining checks. Contract: cron-c1-docs-audit/SPEC.md.

Trigger the docs-auditor cron in manual mode to scan docs/ and CLAUDE.md for:

  1. Index consistency: every file under docs/ is reachable from CLAUDE.md (transitively); every entry in CLAUDE.md resolves to a real file.
  2. Doc-pattern conformance (docs/harness/doc-pattern.md): every doc has the required frontmatter, status / type values are valid, ADR ids are unique and dense.
  3. Dead links: relative markdown links resolve.
  4. Drift between SPECs and code: e.g., a SPEC mentions a function that does not exist; a SPEC's referenced file path is missing.
  5. Doc-pattern violations: a "PRD" file that talks like a SPEC, an ADR with no "Decision" section, a POSTMORTEM written without an incident, etc.

When invoked

  1. Run the implementation in manual mode:

    python3 scripts/cron/c1_docs_audit.py --source manual
    • --source manual makes the script exit 1 on any BLOCKER (CI-gate behavior). Cron mode (--source cron) always exits 0 and surfaces blockers via the run-record only.
    • Same-day idempotency: if a same-day audit exists AND no audited file mtime is newer, the script exits 0 with cached audit at <path> is current; skipping run. Pass --force to bypass and run anyway. This makes auto-fire from the SessionStart trigger hook safe under repeated sessions: if nothing changed, the cached audit is reused.
    • The script writes the AUDIT-typed report to .claude/audits/<YYYY-MM-DD>-docs-audit.md (suffixing -N if --force is used or the cache is invalidated mid-day) and appends one record to var/<env>/cron-c1-runs.jsonl.
    • Deterministic-only: this cron makes zero LLM calls. For semantic doc/code review, use operator-triggered /review-doc <path> or /audit-docs-semantic <subtree> — those use subagent dispatch on the operator's Claude Code subscription.
  2. The SPEC at cron-c1-docs-audit/SPEC.md §3.1 declares D1–D11. The foundation stub implements D1–D3 + D5 only:
    • D1 — Index reachability: every doc under docs/ is transitively reachable from CLAUDE.md. BLOCKER on orphan.
    • D2 — Frontmatter conformance: required keys (type, status, last-reviewed), valid status and type values, navigation-file carve-out. BLOCKER on missing key / invalid value. WARNING on stale (last-reviewed >180d).
    • D3 — Dead links: every relative markdown link resolves. BLOCKER on dead link.
    • D5 — ADR id density: if docs/decisions/ exists, ids are dense (no gaps). WARNING on gap.
    • D4 / D6–D11 are described in the SPEC but not implemented in the foundation stub (e.g., disabled-hook orphans, in-prose citation resolution, cross-doc duplication detection). Consuming repos extend the stub as they adopt the remaining checks.
  3. After the script returns, report to operator: blockers count, warnings count, infos count, audit file path.
  4. For each BLOCKER, optionally open a GitHub Issue with label docs-audit. Operator confirms before opening — never auto-create tickets.

Rules

  • Read-only against docs/. Never auto-fix doc text. Audits report; humans edit.
  • Deterministic-only. No LLM calls under any flag. Semantic review is a different surface (/review-doc / /audit-docs-semantic).
  • Honour doc-pattern skill — auto-loaded on docs/**, encodes the same rules this skill enforces.

Forbidden

  • Modifying any file under docs/ (audits report; do not patch).
  • Skipping a category if it produced no output — list zero counts explicitly.
  • Auto-creating tickets without operator confirmation.
  • Running anything destructive (rm, mv) under docs/.

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.