# Claude Md Audit > Audit the CLAUDE.md hierarchy in a repo for drift between what each CLAUDE.md claims and what's actually on disk. Validates that referenced file paths still exist, flags voice violations (em dashes, "ask" as a noun), and checks the ground-truth facts block for stale tokens (MCP spec date, transports, model lineup). Use when the user asks to audit, validate, check, or verify CLAUDE.md files, says "is my CLAUDE.md still accurate", flags possible doc drift, or wants to sanity-check the docs before a course recording or release. Use when this capability is needed. - Skill: `tomevault-io/claude-md-audit` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/claude-md-audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/claude-md-audit/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/claude-md-audit --- # CLAUDE.md hierarchy audit This skill validates the five-scope CLAUDE.md teaching artifact that Segment 2 of this course centers on. The Python audit script does the heavy lifting; this prompt orchestrates and interprets. ## Run the audit ```! python "${CLAUDE_SKILL_DIR}/scripts/audit_claude_md.py" $ARGUMENTS ``` ## How to interpret results The script outputs JSON. Read the `status` field first: - **`clean`** (exit 0): every CLAUDE.md file exists, every referenced path resolves, ground-truth facts block matches expected values. Report a one-line "all clean" and stop. - **`drift`** (exit 1): one or more findings. Read each entry in the `findings` array. Each has `file`, `severity` (`high`/`medium`/`low`), `category`, and `message`. - **`error`** (exit 2): hard failure (missing repo root, script bug). Report the error and stop. ## When drift is found 1. **Load `references/CLAUDE_MD_PATTERNS.md`** — it documents the five canonical patterns and the common drift modes. Read it only when needed (progressive disclosure). 2. **Group findings by severity**. Address `high` first. 3. **For each finding**, propose the minimal correction. Cite the file and line. 4. **If the user passed `--fix`**, the script already corrected obvious path typos. Re-run without `--fix` to confirm. ## Voice rules for any rewrites you propose This is a Tim Warner course repo. Match the voice in `segment_4_hero/CLAUDE.md`: - **Bold** key terms. - No em dashes. Hyphens with spaces, commas, or periods only. - Never use "ask" as a noun. - Sentence-case headings. - First-principles, plain-spoken, mildly irreverent. No corporate-speak. ## What the script does NOT check - Whether the lesson prose in each CLAUDE.md is pedagogically sound. That's a human judgment. - Whether new files added to the repo should be mentioned in a CLAUDE.md. Suggest additions only when the diff is obvious. --- > Source: [timothywarner-org/claude-code](https://github.com/timothywarner-org/claude-code) — distributed by [TomeVault](https://tomevault.io).