context-budget

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• what's eating my context window
• how much context overhead from my MCP servers
• audit my Claude Code setup for bloat

What it does

context-budget is the audit skill in Affaan M’s everything-claude-code — see skills/context-budget. It runs a four-phase inventory of everything loaded into a session: agents (agents/*.md), skills (skills/*/SKILL.md), rules (rules/**/*.md), MCP servers (.mcp.json or active config), and the CLAUDE.md chain (project + user). Each component gets a token estimate via the standard heuristics — prose at words × 1.3, code-heavy at chars / 4.

Phase 2 classifies each component into always-needed (referenced in CLAUDE.md or backing an active command), sometimes-needed (domain-specific, not referenced), or rarely-needed (no command reference, overlap, or no project match). Phase 3 detects six problem patterns: bloated agent descriptions (>30 words in frontmatter — these load into every Task tool invocation), heavy agent files (>200 lines), redundant skills, MCP over-subscription (>10 servers or CLI wrappers), and CLAUDE.md bloat.

Phase 4 emits a budget report: total estimated overhead, effective available context, a per-component breakdown table, ranked issues, and a top-3-optimizations list with per-action token savings. The verbose flag adds per-file token counts and a per-tool MCP schema breakdown. The biggest lever, by design, is MCP tools: a 30-tool server costs ~15K tokens of schema overhead — more than every skill in the directory combined. CLI-wrapping MCP servers (gh, git, npm, supabase, vercel) flag automatically since the underlying CLI is already available for free in Bash.

When to use it

• Session performance feels sluggish or output quality is degrading and you don’t know why
• Recently added multiple skills, agents, or MCP servers and want to know if there’s headroom for more
• Planning to add a heavy MCP server (Linear, Sentry, datadog) and want a before-snapshot
• Auditing ~/.claude/ setup for bloat before sharing with a team
• Need to know how many of your 200K context tokens are gone before the first user message

When not to reach for it:

• Compaction strategy mid-session — that’s strategic-compact
• Spend / cost reporting in dollars — that’s cost-tracking
• Choosing which agent to invoke for a task — that’s a routing question, not a budget audit

Install

From affaan-m/everything-claude-code at skills/context-budget/. Drop the folder into ~/.claude/skills/context-budget/. The skill backs a /context-budget slash command (and a --verbose flag for per-file breakdown). It scans your existing ~/.claude/agents/, ~/.claude/skills/, ~/.claude/rules/, .mcp.json, and CLAUDE.md chain — nothing to configure beyond the install.

What a session looks like

1. Run the audit. /context-budget triggers the four-phase scan.
2. Inventory phase. Counts agents (12), skills (28), rules (52), MCP tools (87 across 14 servers), CLAUDE.md files (2). Estimates ~63K tokens of overhead before the first user turn.
3. Classification phase. Sorts each component into always / sometimes / rarely. Three agents flagged as “rarely needed” — no command references, no recent invocations.
4. Issue detection. Three heavy agents (>200 lines each), 14 MCP servers (three of which wrap gh, git, vercel CLIs already available in Bash), one bloated agent description (52 words — loaded on every Task spawn).
5. Top-3 optimization output. Remove the three CLI-replaceable MCP servers → save ~27,500 tokens (47% overhead reduction). Trim the bloated agent description → save ~250 tokens per Task spawn. Lazy-load three rarely-needed skills.
6. Verbose follow-up if needed. /context-budget --verbose shows per-file token counts, the worst MCP tools by schema size, and overlapping rule lines.

The discipline that makes it work: MCP cost is invisible. A user installs five MCP servers, each adds ~15K tokens of schemas, and the user only feels it as “model seems slower.” The audit makes the invisible cost concrete enough to act on.

Receipts

TODO — to be filled in from a real session. Once the skill has been run against a real ~/.claude/ setup, this section will capture: the actual context-overhead total surfaced by the audit vs. the operator’s prior estimate, which MCP server turned out to be the single biggest line item (almost always a CLI-wrapping one), which agent description was most bloated, the top-3 optimization savings totaled in tokens, and whether the verbose flag exposed any rule-file content overlap that wasn’t obvious from the high-level scan.

Source and attribution

From Affaan M’s everything-claude-code — an MIT-licensed skill collection covering harness construction, agent ops, video, payments, and platform-specific patterns.

License: MIT.

Quoting the MCP-lever rule verbatim: “MCP is the biggest lever: each tool schema costs ~500 tokens; a 30-tool server costs more than all your skills combined.” That ratio is what makes audits worth running — skills feel expensive subjectively, but MCP servers are an order of magnitude heavier and almost invisible without an audit.