Paths: All file refs relative to skills repo root.
Agent Instructions Auditor
Type: L3 Worker Category: 0XX Shared
Audits instruction files (CLAUDE.md, AGENTS.md, GEMINI.md) across all three agents for quality, consistency, and best practices.
When to Use
- After editing any instruction file
- After adding/removing MCP servers or hooks
- Before release or publishing
- When sessions degrade (context bloat symptoms)
Phase 1: Discover Files
Locate instruction files in target project:
| Agent | Primary | Fallback |
|---|---|---|
| Claude | CLAUDE.md | .claude/settings.local.json |
| Codex | AGENTS.md | .codex/instructions.md |
| Gemini | GEMINI.md | AGENTS.md (shared with Codex) |
Report: which files exist, which agents share files.
Phase 2: Token Budget Audit
For each instruction file:
| Check | Pass | Warn | Fail |
|---|---|---|---|
| Line count | ≤100 lines | 101-150 lines | >150 lines |
| Estimated tokens | ≤2,500 tokens | 2,501-3,500 | >3,500 |
| Sections count | ≤8 sections | 9-12 | >12 |
Token estimation: wc -w {file} × 1.3 (English average tokens/word ratio).
Report table per file with line count, word count, estimated tokens.
Phase 3: Prompt Cache Safety
Check each file for content that breaks prefix-based prompt caching:
| # | Check | Pattern | Severity | ||
|---|---|---|---|---|---|
| 1 | No timestamps | grep -E '\d{4}-\d{2}-\d{2}.\d{2}:\d{2}' | WARN | ||
| 2 | No dates in content | `grep -E '(January | February | ||
| 3 | No dynamic counts | `grep -E '\d+ skills\ | \d+ tools\ | \d+ servers'` (hardcoded counts change) | WARN |
| 4 | No absolute paths | `grep -E '[A-Z]:\ | /home/ | ||
| 5 | Stable structure | No conditional sections (if X then include Y) | INFO |
Phase 4: Content Quality
| # | Check | Pass | Fail | |||
|---|---|---|---|---|---|---|
| 1 | Has build/test commands | Found `npm\ | cargo\ | pytest\ | dotnet` commands | Missing — add essential commands |
| 2 | No abstract principles | No "write quality code", "follow best practices" | Found vague instructions | |||
| 3 | No redundant docs | No API docs, no full architecture description | Found content discoverable from code | |||
| 4 | Has hard boundaries | Found `NEVER\ | ALWAYS\ | MUST\ | DO NOT` rules | Missing explicit prohibitions |
| 5 | Compact Instructions section | ## Compact Instructions present with preservation priorities | Missing — sessions lose decisions on /compact | |||
| 6 | MCP Tool Preferences | Table mapping built-in → MCP tools | Missing — agents use suboptimal tools | |||
| 7 | No tool output examples | No large code blocks or command outputs | Found — bloats every turn |
Phase 5: Cross-Agent Consistency
Compare content across all found instruction files:
| Check | Pass | Fail |
|---|---|---|
| MCP Tool Preferences | Same table in all files | Missing in some files |
| Critical Rules | Same core rules | Divergent rules |
| Build/test commands | Same commands | Different or missing |
| Structural sections | Same section order | Inconsistent structure |
Sync action: For each inconsistency, show diff and suggest which file is source of truth (usually CLAUDE.md).
Phase 6: Report
Agent Instructions Audit:
| File | Lines | ~Tokens | Cache-safe | Quality | Issues |
|------------|-------|---------|------------|---------|--------|
| CLAUDE.md | 80 | 2,100 | ✅ | 6/7 | Missing Compact Instructions |
| AGENTS.md | 77 | 2,000 | ✅ | 7/7 | OK |
| GEMINI.md | — | — | — | — | File not found |
Cross-agent: 1 inconsistency (GEMINI.md missing)
Recommendations:
1. Create GEMINI.md (copy from AGENTS.md, adjust agent-specific sections)
2. Add ## Compact Instructions to CLAUDE.mdDefinition of Done
- All instruction files discovered and audited
- Token budget within limits (≤2,500 tokens each)
- No prompt cache breakers found (or reported as WARN)
- Content quality checks passed (or issues reported)
- Cross-agent consistency verified
- Report generated with actionable recommendations
Version: 1.0.0 Last Updated: 2026-03-20