---
name: context-budget-audit
description: Measures everything an agent re-reads on every turn — CLAUDE.md, AGENTS.md, rules files, MCP tool schemas, always-on skills — then ranks contradictions, redundancy and staleness by the tokens they cost. Report-only. Use when instruction files have grown, an agent ignores its own rules, or context feels expensive.
license: MIT
compatibility: Any agent harness with always-loaded instruction files (Claude Code, Cursor, Copilot, Windsurf, Codex). Read-only; needs no network.
metadata:
  category: productivity
  version: "1.0.0"
---

# 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.