Context Budget

1---2name: context-budget3description: Audits Claude Code context window consumption across agents, skills, MCP servers, and rules. Identifies bloat, redundant components, and produces prioritized token-savings recommendations.4origin: ECC5---6 7# Context Budget8 9Analyze token overhead across every loaded component in a Claude Code session and surface actionable optimizations to reclaim context space.10 11## When to Use12 13- Session performance feels sluggish or output quality is degrading14- You've recently added many skills, agents, or MCP servers15- You want to know how much context headroom you actually have16- Planning to add more components and need to know if there's room17- Running `/context-budget` command (this skill backs it)18 19## How It Works20 21### Phase 1: Inventory22 23Scan all component directories and estimate token consumption:24 25**Agents** (`agents/*.md`)26- Count lines and tokens per file (words × 1.3)27- Extract `description` frontmatter length28- Flag: files >200 lines (heavy), description >30 words (bloated frontmatter)29 30**Skills** (`skills/*/SKILL.md`)31- Count tokens per SKILL.md32- Flag: files >400 lines33- Check for duplicate copies in `.agents/skills/` — skip identical copies to avoid double-counting34 35**Rules** (`rules/**/*.md`)36- Count tokens per file37- Flag: files >100 lines38- Detect content overlap between rule files in the same language module39 40**MCP Servers** (`.mcp.json` or active MCP config)41- Count configured servers and total tool count42- Estimate schema overhead at ~500 tokens per tool43- Flag: servers with >20 tools, servers that wrap simple CLI commands (`gh`, `git`, `npm`, `supabase`, `vercel`)44 45**CLAUDE.md** (project + user-level)46- Count tokens per file in the CLAUDE.md chain47- Flag: combined total >300 lines48 49### Phase 2: Classify50 51Sort every component into a bucket:52 53| Bucket | Criteria | Action |54|--------|----------|--------|55| **Always needed** | Referenced in CLAUDE.md, backs an active command, or matches current project type | Keep |56| **Sometimes needed** | Domain-specific (e.g. language patterns), not referenced in CLAUDE.md | Consider on-demand activation |57| **Rarely needed** | No command reference, overlapping content, or no obvious project match | Remove or lazy-load |58 59### Phase 3: Detect Issues60 61Identify the following problem patterns:62 63- **Bloated agent descriptions** — description >30 words in frontmatter loads into every Task tool invocation64- **Heavy agents** — files >200 lines inflate Task tool context on every spawn65- **Redundant components** — skills that duplicate agent logic, rules that duplicate CLAUDE.md66- **MCP over-subscription** — >10 servers, or servers wrapping CLI tools available for free67- **CLAUDE.md bloat** — verbose explanations, outdated sections, instructions that should be rules68 69### Phase 4: Report70 71Produce the context budget report:72 73```74Context Budget Report75═══════════════════════════════════════76 77Total estimated overhead: ~XX,XXX tokens78Context model: Claude Sonnet (200K window)79Effective available context: ~XXX,XXX tokens (XX%)80 81Component Breakdown:82┌─────────────────┬────────┬───────────┐83│ Component       │ Count  │ Tokens    │84├─────────────────┼────────┼───────────┤85│ Agents          │ N      │ ~X,XXX    │86│ Skills          │ N      │ ~X,XXX    │87│ Rules           │ N      │ ~X,XXX    │88│ MCP tools       │ N      │ ~XX,XXX   │89│ CLAUDE.md       │ N      │ ~X,XXX    │90└─────────────────┴────────┴───────────┘91 92WARNING: Issues Found (N):93[ranked by token savings]94 95Top 3 Optimizations:961. [action] → save ~X,XXX tokens972. [action] → save ~X,XXX tokens983. [action] → save ~X,XXX tokens99 100Potential savings: ~XX,XXX tokens (XX% of current overhead)101```102 103In verbose mode, additionally output per-file token counts, line-by-line breakdown of the heaviest files, specific redundant lines between overlapping components, and MCP tool list with per-tool schema size estimates.104 105## Examples106 107**Basic audit**108```109User: /context-budget110Skill: Scans setup → 16 agents (12,400 tokens), 28 skills (6,200), 87 MCP tools (43,500), 2 CLAUDE.md (1,200)111       Flags: 3 heavy agents, 14 MCP servers (3 CLI-replaceable)112       Top saving: remove 3 MCP servers → -27,500 tokens (47% overhead reduction)113```114 115**Verbose mode**116```117User: /context-budget --verbose118Skill: Full report + per-file breakdown showing planner.md (213 lines, 1,840 tokens),119       MCP tool list with per-tool sizes, duplicated rule lines side by side120```121 122**Pre-expansion check**123```124User: I want to add 5 more MCP servers, do I have room?125Skill: Current overhead 33% → adding 5 servers (~50 tools) would add ~25,000 tokens → pushes to 45% overhead126       Recommendation: remove 2 CLI-replaceable servers first to stay under 40%127```128 129## Best Practices130 131- **Token estimation**: use `words × 1.3` for prose, `chars / 4` for code-heavy files132- **MCP is the biggest lever**: each tool schema costs ~500 tokens; a 30-tool server costs more than all your skills combined133- **Agent descriptions are loaded always**: even if the agent is never invoked, its description field is present in every Task tool context134- **Verbose mode for debugging**: use when you need to pinpoint the exact files driving overhead, not for regular audits135- **Audit after changes**: run after adding any agent, skill, or MCP server to catch creep early