---
name: context-budget
description: Audit agent context window overhead across skills, agent instructions, MCP tool schemas, and rules, then produce ranked token-savings recommendations. Use when the user says "context budget", "token overhead", "session feels sluggish", "do I have room for more MCP servers", or after adding many components. Not for improving one skill's content quality: use a skill-authoring skill. Not for runtime cost/billing analysis.
license: MIT
metadata:
  author: TechTide AI (Alex Cinovoj)
  provenance: rewritten from patterns in affaan-m/everything-claude-code (MIT)
  category: Agent Ops & Meta
---

# Context Budget

Every loaded component taxes every request before work starts. MCP tool schemas are almost always the biggest line item, so measure before trimming, and trim the big rocks first.

## Workflow

1. **Inventory.** Estimate tokens per component: prose at words x 1.3, code-heavy files at chars / 4.

   | Component | Where | Flag when |
   |-----------|-------|-----------|
   | Agent definitions | `agents/*.md` | >200 lines, or frontmatter description >30 words |
   | Skills | `skills/*/SKILL.md` | >400 lines; skip duplicate copies to avoid double-counting |
   | Rules | `rules/**/*.md` | >100 lines, or overlap with sibling rule files |
   | MCP servers | `.mcp.json` or active config | ~500 tokens per tool schema; >20 tools per server; servers wrapping plain CLIs (`gh`, `git`, `npm`) |
   | Project instructions | CLAUDE.md chain | combined >300 lines |

2. **Classify** every component into a bucket:
   - Always needed: referenced by project instructions, backs an active command, matches the project type. Keep.
   - Sometimes needed: domain-specific, unreferenced. Candidate for on-demand loading.
   - Rarely needed: no references, overlapping content, no project match. Remove or lazy-load.
3. **Detect issue patterns.** Bloated agent descriptions (loaded into every spawn even if unused), heavy agent files, skills duplicating agent logic, rules duplicating project instructions, MCP over-subscription (>10 servers, or CLI-wrappers), instruction-file bloat.
4. **Report.** Total estimated overhead, percent of the context window, per-component breakdown table, issues ranked by token savings, and a top-3 optimization list with estimated savings each. In verbose mode add per-file counts and the specific overlapping lines.
5. **Trim on approval.** Stop for confirmation before deleting skills, disconnecting MCP servers, or editing shared agent instructions. Apply approved trims largest-first.

## Verification

Re-run the inventory after trims. Expect the new total to match the predicted savings within roughly 10%. Then spot-check routing on 2-3 representative requests (one per removed or lazy-loaded component's domain). Expect each to still route to a working capability. If a request now dead-ends, restore that component and mark it "sometimes needed" instead of removed.

## Good vs Bad

**Bad:** "Your setup is heavy. Delete some skills and shorten CLAUDE.md." No numbers, no ranking, and skills are rarely the biggest cost.

**Good:** "Total overhead ~63k tokens (31% of window). Largest item: 87 MCP tool schemas at ~43k. Three servers wrap CLIs you already shell out to, removing them saves ~27k (43%). Second: 3 agent files over 200 lines, ~4k. Skills total only 6k, leave them."

## Footguns

- **Trimming skills first because they are visible.** Skill bodies load on demand in most setups, tool schemas load always. Fix: rank by measured savings, MCP is usually the lever.
- **Forgetting agent descriptions load everywhere.** A never-invoked agent still pays its description into every spawn context. Fix: cap descriptions near 30 words.
- **Double-counting mirrored files.** Duplicate skill copies inflate the inventory and the panic. Fix: detect and skip identical copies.
- **Deleting instead of lazy-loading.** A "rarely needed" component someone needs monthly is not garbage. Fix: prefer on-demand activation for anything with a real, infrequent use.

## Completion checklist

- [ ] All five component classes inventoried with token estimates
- [ ] Every component bucketed (always / sometimes / rarely)
- [ ] Issues ranked by savings, top-3 list delivered
- [ ] No destructive trim without explicit approval
- [ ] Post-trim re-estimate and routing spot-check done

Any box unchecked: not done. Fix or say so.