Context Budget

When to Use

• Session performance feels sluggish or output quality is degrading
• You've recently added many skills, agents, or MCP servers
• You want to know how much context headroom you actually have
• Planning to add more components and need to know if there's room
• Running

  /context-budget

  command (this skill backs it)

How It Works

Phase 1: Inventory

agents/*.md

• Count lines and tokens per file (words × 1.3)
• Extract

  description

  frontmatter length
• Flag: files >200 lines (heavy), description >30 words (bloated frontmatter)

skills/*/SKILL.md

• Count tokens per SKILL.md
• Flag: files >400 lines
• Check for duplicate copies in

  .agents/skills/

  — skip identical copies to avoid double-counting

rules/**/*.md

• Count tokens per file
• Flag: files >100 lines
• Detect content overlap between rule files in the same language module

.mcp.json

• Count configured servers and total tool count
• Estimate schema overhead at ~500 tokens per tool
• Flag: servers with >20 tools, servers that wrap simple CLI commands (

  gh

  ,

  git

  ,

  npm

  ,

  supabase

  ,

  vercel

  )

• Count tokens per file in the CLAUDE.md chain
• Flag: combined total >300 lines

Phase 2: Classify

Phase 3: Detect Issues

• Bloated agent descriptions — description >30 words in frontmatter loads into every Task tool invocation
• Heavy agents — files >200 lines inflate Task tool context on every spawn
• Redundant components — skills that duplicate agent logic, rules that duplicate CLAUDE.md
• MCP over-subscription — >10 servers, or servers wrapping CLI tools available for free
• CLAUDE.md bloat — verbose explanations, outdated sections, instructions that should be rules

Phase 4: Report

Context Budget Report
═══════════════════════════════════════

Total estimated overhead: ~XX,XXX tokens
Context model: Claude Sonnet (200K window)
Effective available context: ~XXX,XXX tokens (XX%)

Component Breakdown:
┌─────────────────┬────────┬───────────┐
│ Component       │ Count  │ Tokens    │
├─────────────────┼────────┼───────────┤
│ Agents          │ N      │ ~X,XXX    │
│ Skills          │ N      │ ~X,XXX    │
│ Rules           │ N      │ ~X,XXX    │
│ MCP tools       │ N      │ ~XX,XXX   │
│ CLAUDE.md       │ N      │ ~X,XXX    │
└─────────────────┴────────┴───────────┘

⚠ Issues Found (N):
[ranked by token savings]

Top 3 Optimizations:
1. [action] → save ~X,XXX tokens
2. [action] → save ~X,XXX tokens
3. [action] → save ~X,XXX tokens

Potential savings: ~XX,XXX tokens (XX% of current overhead)

Examples

User: /context-budget
Skill: Scans setup → 16 agents (12,400 tokens), 28 skills (6,200), 87 MCP tools (43,500), 2 CLAUDE.md (1,200)
       Flags: 3 heavy agents, 14 MCP servers (3 CLI-replaceable)
       Top saving: remove 3 MCP servers → -27,500 tokens (47% overhead reduction)

User: /context-budget --verbose
Skill: Full report + per-file breakdown showing planner.md (213 lines, 1,840 tokens),
       MCP tool list with per-tool sizes, duplicated rule lines side by side

User: I want to add 5 more MCP servers, do I have room?
Skill: Current overhead 33% → adding 5 servers (~50 tools) would add ~25,000 tokens → pushes to 45% overhead
       Recommendation: remove 2 CLI-replaceable servers first to stay under 40%

Best Practices

• Token estimation: use

  words × 1.3

  for prose,

  chars / 4

  for code-heavy files
• MCP is the biggest lever: each tool schema costs ~500 tokens; a 30-tool server costs more than all your skills combined
• Agent descriptions are loaded always: even if the agent is never invoked, its description field is present in every Task tool context
• Verbose mode for debugging: use when you need to pinpoint the exact files driving overhead, not for regular audits
• Audit after changes: run after adding any agent, skill, or MCP server to catch creep early