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

• 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