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

Files1

1 files · 1.0 KB

Select a file to preview

Overall Score

87/100

Grade

A

Excellent

Safety

95

Quality

88

Clarity

87

Completeness

82

Summary

This skill audits token consumption across Claude Code components (agents, skills, MCP servers, rules, CLAUDE.md) and identifies optimization opportunities. It performs a four-phase analysis: inventorying components with token estimates, classifying by necessity, detecting bloat patterns, and producing a prioritized recommendations report.

Detected Capabilities

Scan and inventory agent, skill, rule, and MCP server filesEstimate token consumption using word/character-based heuristicsDetect bloat patterns (oversized files, verbose descriptions, redundancy)Classify components by necessity (always/sometimes/rarely needed)Generate prioritized optimization recommendationsVerbose mode with per-file breakdown and side-by-side redundancy detection

Trigger Keywords

Phrases that MCP clients use to match this skill to user intent.

context budget audittoken overhead analysisreclaim context spacemcp optimizationagent bloat detection

Use Cases

Reclaim context space when session performance degrades
Assess token overhead before adding new components
Identify and remove redundant or bloated agents and skills
Optimize MCP server configuration to reduce schema overhead
Plan context budget allocation for multi-agent projects

Quality Notes

Skill clearly documents its four-phase workflow with specific heuristics (words × 1.3, chars / 4, ~500 tokens per MCP tool)
Excellent scoping: skill is read-only (no file writes or destructive operations), operates only on project metadata
Strong examples provided for three use cases (basic audit, verbose mode, pre-expansion check) that demonstrate real-world scenarios
Well-structured classification table (Always/Sometimes/Rarely needed) provides clear decision criteria
Best practices section includes actionable guidance on token estimation, MCP leverage points, and when to use verbose mode
Sample report format uses clear ASCII tables and warning sections, making output easy to parse
Skill correctly identifies MCP tools as the 'biggest lever' and provides quantified examples (30-tool server costs more than all skills combined)
Minor: 'Context model: Claude Sonnet (200K window)' is hardcoded in example; should acknowledge model-agnostic approach or document assumptions about supported models
Minor: Verbose mode output description could specify exact formatting (JSON, markdown table, etc.) for consistent parsing by agents

Model: claude-haiku-4-5-20251001Analyzed: Apr 20, 2026

Reviews

Add this skill to your library to leave a review.

No reviews yet

Be the first to share your experience.

Version History

v1.1

Content updated

2026-04-20

Latest

v1.0

No changelog

2026-04-12

context-budget