Context Budget Audit

Instruction files only ever grow. Every incident adds a rule, every correction adds a paragraph, and nobody ever deletes. The result is a file that costs tokens on every single message and, past a certain size, is followed less reliably rather than more — because the important rule is now buried among forty unimportant ones.

Almost nobody has measured this. That is the entire value of the audit.

The contract

This skill reports. It does not edit — not even the changes that look obviously safe. The output is a ranked list; acting on it is a separate, deliberate decision by a human. An audit that quietly rewrites the file it is auditing cannot be trusted to have been honest about it.

1. Enumerate what is actually always loaded

Find every file that enters context on every turn, not the ones you assume:

• Project and user instruction files: CLAUDE.md, AGENTS.md, .cursorrules, .github/copilot-instructions.md, GEMINI.md, and anything they @-import — follow the imports, they count too.
• Skill and command descriptions that load eagerly rather than on demand.
• MCP server tool schemas. These are routinely the largest single item and the least visible; a server with thirty tools can outweigh every instruction file combined.
• SessionStart hook output, which is injected on every session and often forgotten entirely.
• System prompt additions from the harness config.

Measure each deterministically — wc -c divided by four is close enough and is reproducible. Do not ask a model to estimate token counts; the number needs to be the same on two consecutive runs or the delta between audits is meaningless.

2. Analyse, in this order

Order matters. Run the checks in the sequence below, because the first one is a correctness problem and the rest are only cost problems.

1. Contradictions. Two files, or two sections, giving incompatible instructions. This is the finding that actually changes behaviour: an agent facing a contradiction picks one arbitrarily, and which one it picks looks like a bug in the agent. Quote both sides.
2. Redundancy. The same rule stated in two places, or a rule that restates the harness default. Duplication is not just cost — when one copy is later edited, you have manufactured a contradiction.
3. Staleness. Rules naming a file, script, flag or service that no longer exists. Verify by looking, not by recognition. A stale rule is worse than no rule: it teaches the reader that the file is unreliable.
4. Extraction candidates. Content that applies to one workflow rather than every turn — a deployment runbook, a release checklist. This belongs in an on-demand skill, where it costs nothing until it is needed. Usually the largest single saving available.
5. Vagueness. Rules with no observable trigger ("write clean code", "be careful with the database"). They consume tokens and change nothing. Either make them checkable or cut them.
6. Ordering. Whether the rules that matter most sit where attention is strongest — the top and the bottom — rather than in the middle of a wall.

3. Report

One ranked table, highest saving first:

| # | File · section | Finding | Type | Est. tokens | Evidence |

Every row carries a quoted line from the source. A finding without a quote is an opinion. Close with the total always-loaded budget, the total recoverable, and — if a previous audit report exists — the drift since it ran.

Then list the top three actions in priority order, each phrased as a concrete edit the reader could make in under five minutes.

Judgement calls

• A long file is not automatically a problem. A 400-line instruction file whose rules are all load-bearing is fine. Rank by cost and value, never by size alone.
• Never recommend deleting a safety rule to save tokens. Guards against destructive operations, secrets handling and production access are exempt from this audit. Say so explicitly in the report so nobody has to wonder.
• Generated or rendered files — anything a tool rewrites — must be fixed at the template, not the output. Flag which files those are; editing them directly is work that gets erased.

Verification gate

• Every always-loaded source enumerated, including MCP schemas and hook output.
• @-imports followed one level and counted.
• Counts produced by a deterministic command, and the command is shown in the report.
• Every finding carries a quote from the source file.
• Contradictions listed above redundancy.
• Nothing was edited.