| name | ln-014-agent-instructions-auditor |
| description | Audits CLAUDE.md, AGENTS.md, GEMINI.md for token budget, prompt cache safety, compact instructions, and cross-agent consistency. Use after editing instruction files or before release. |
| license | MIT |
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.md
Definition of Done
Version: 1.0.0
Last Updated: 2026-03-20
