directives-audit — validate AI-agent guidance files

Package scope and prerequisites

This catalog ships instructions, not the executable runtime. Python modules, scripts, local services and optional tools named below must be installed separately from the upstream project. Check their availability before running commands; if they are missing, explain the prerequisite instead of claiming execution or results. The host agent may use model tokens while following these instructions.

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).