directives_audit — validate AI-agent guidance files

Before an agent works on a repo, it should know which directives exist, whether they are healthy, and — most importantly — whether they exist at all. Inspired by shadcn/improve's "recon" step (ingest intent docs so decided tradeoffs aren't re-flagged).

When to use

• Checking if a project has any agent instructions (CLAUDE.md / AGENTS.md / …).
• Auditing existing directives for staleness, size, format or conflicts.
• Onboarding to an unfamiliar repo — map its instructions, intent docs and specs.
• The user mentions CLAUDE.md, AGENTS.md, agent rules, specs, or "directives".

Run it

python -m skills.directives_audit.cli <project_dir>          # readable report
python -m skills.directives_audit.cli <project_dir> --json   # machine-readable

from skills.directives_audit import audit
report = audit("/path/to/project")
report["has_instructions"]   # bool — the big one
report["score"]              # 0-100 directive health
report["findings"]           # severity, path, message, fix_hint

What it detects

Formats: markdown, text, HTML, .mdc, json/yaml — some teams keep instructions in HTML; the audit reads HTML too and flags it as a parse-friendliness issue.

Checks

• Missing — no instruction file anywhere → recommends creating CLAUDE.md / AGENTS.md.
• Oversized — always-on instructions over ~2000 tok (warn) / ~5000 (err); re-sent every turn.
• HTML instead of markdown for instruction docs.
• Broken references — paths cited in prose docs that don't exist in the repo.
• Empty / unreadable directive files.
• Multiple sources — several instruction files that can drift apart.

Related: [[llm_backends]], skill_project_optimizer (per-project skill filtering).