context-budget

SKILL.md

Context Budget

Analyze token overhead across every loaded component in a Claude Code session and surface actionable optimizations to reclaim context space.

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

Scan all component directories and estimate token consumption:
Agents (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 (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 (rules/**/*.md)

Count tokens per file

Flag: files >100 lines

Detect content overlap between rule files in the same language module

MCP Servers (.mcp.json or active MCP config)

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)

CLAUDE.md (project + user-level)

Count tokens per file in the CLAUDE.md chain

Flag: combined total >300 lines

Phase 2: Classify

Sort every component into a bucket:

Bucket
Criteria
Action

Always needed
Referenced in CLAUDE.md, backs an active command, or matches current project type
Keep

Sometimes needed
Domain-specific (e.g. language patterns), not referenced in CLAUDE.md
Consider on-demand activation

Rarely needed
No command reference, overlapping content, or no obvious project match
Remove or lazy-load

Phase 3: Detect Issues

Identify the following problem patterns:

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

Produce the context budget 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    │
└─────────────────┴────────┴───────────┘

WARNING: 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)

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

Examples

Basic audit

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)

Verbose mode

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

Pre-expansion check

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