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
| Tool / purpose |
Files |
| Claude Code |
CLAUDE.md, CLAUDE.local.md, .claude/, .mcp.json |
| Codex / OpenCode / generic |
AGENTS.md, .agents/** |
| Cursor |
.cursorrules, .cursor/rules/**.mdc |
| GitHub Copilot |
.github/copilot-instructions.md, .github/instructions/** |
| Gemini / Antigravity |
GEMINI.md, .gemini/** |
| Windsurf / Cline / Roo / Aider |
.windsurfrules, .clinerules, .roo/**, CONVENTIONS.md |
| Intent (improve recon set) |
CONTEXT.md, DESIGN.md, PRODUCT.md, ARCHITECTURE.md, docs/adr/** |
| Specs |
PRD.md, specs/**, spec/** |
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).
1---2name: directives-audit3description: Audit a project's AI-agent guidance files — CLAUDE.md, AGENTS.md, .cursorrules, copilot-instructions.md, GEMINI.md, intent docs and specs, in markdown, text or HTML. Use when checking whether a repo has agent instructions, whether they are healthy/consistent, or before an agent starts work on an unfamiliar codebase. Also use when the user mentions CLAUDE.md, AGENTS.md, agent rules, "does this project have instructions", or stale/oversized directive files.4---56# directives_audit — validate AI-agent guidance files78Before an agent works on a repo, it should know which directives exist, whether9they are healthy, and — most importantly — whether they exist at all. Inspired by10shadcn/improve's "recon" step (ingest intent docs so decided tradeoffs aren't11re-flagged).1213## When to use1415- Checking if a project has **any** agent instructions (CLAUDE.md / AGENTS.md / …).16- Auditing existing directives for **staleness, size, format or conflicts**.17- Onboarding to an unfamiliar repo — map its instructions, intent docs and specs.18- The user mentions CLAUDE.md, AGENTS.md, agent rules, specs, or "directives".1920## Run it2122```bash23python -m skills.directives_audit.cli <project_dir> # readable report24python -m skills.directives_audit.cli <project_dir> --json # machine-readable25```2627```python28from skills.directives_audit import audit29report = audit("/path/to/project")30report["has_instructions"] # bool — the big one31report["score"] # 0-100 directive health32report["findings"] # severity, path, message, fix_hint33```3435## What it detects3637| Tool / purpose | Files |38|----------------|-------|39| Claude Code | `CLAUDE.md`, `CLAUDE.local.md`, `.claude/`, `.mcp.json` |40| Codex / OpenCode / generic | `AGENTS.md`, `.agents/**` |41| Cursor | `.cursorrules`, `.cursor/rules/**.mdc` |42| GitHub Copilot | `.github/copilot-instructions.md`, `.github/instructions/**` |43| Gemini / Antigravity | `GEMINI.md`, `.gemini/**` |44| Windsurf / Cline / Roo / Aider | `.windsurfrules`, `.clinerules`, `.roo/**`, `CONVENTIONS.md` |45| Intent (improve recon set) | `CONTEXT.md`, `DESIGN.md`, `PRODUCT.md`, `ARCHITECTURE.md`, `docs/adr/**` |46| Specs | `PRD.md`, `specs/**`, `spec/**` |4748Formats: **markdown, text, HTML, .mdc, json/yaml** — some teams keep instructions49in HTML; the audit reads HTML too and flags it as a parse-friendliness issue.5051## Checks5253- **Missing** — no instruction file anywhere → recommends creating CLAUDE.md / AGENTS.md.54- **Oversized** — always-on instructions over ~2000 tok (warn) / ~5000 (err); re-sent every turn.55- **HTML instead of markdown** for instruction docs.56- **Broken references** — paths cited in prose docs that don't exist in the repo.57- **Empty / unreadable** directive files.58- **Multiple sources** — several instruction files that can drift apart.5960Related: [[llm_backends]], `skill_project_optimizer` (per-project skill filtering).
zedarvates