Context Budget Audit
Estimates token consumption per component in your Claude Code setup and identifies
optimization targets. Inspired by everything-claude-code's context budget system.
How to use
/context-budget-audit
Run a full audit of all agents, skills, MCP servers, hooks, and CLAUDE.md files.
/context-budget-audit <component>
Audit a specific component (agents, skills, mcp, hooks, claude-md).
When to use
- Context window feels constrained or sessions compact early
- After adding new agents, skills, or MCP servers
- When troubleshooting slow response times
- Periodic maintenance (monthly recommended)
When NOT to use
- During active development (audit after changes stabilize)
- For code-level token optimization (use tokenizers directly)
Token Estimation Rules
| Content Type |
Formula |
Notes |
| Prose/Markdown |
words x 1.3 |
CLAUDE.md, SKILL.md, agent descriptions |
| Code blocks |
chars / 4 |
Python, YAML, JSON in skills |
| MCP tool schema |
~500 tokens/tool |
Each declared tool in an MCP server |
| Agent YAML frontmatter |
~100 tokens |
Metadata overhead per agent |
Audit Process
1. Scan Components
For each category:
- Read all files matching the pattern
- Calculate token estimate per file
- Sum category total
2. Component Categories
| Category |
Path Pattern |
Expected Count |
| Agents |
~/.claude/agents/*.md |
~61 core |
| Skills |
~/.claude/skills/*/SKILL.md |
~116 |
| MCP Servers |
~/.claude.json mcpServers |
21 servers |
| Hooks |
~/.claude/settings.json hooks |
7 hooks |
| Global CLAUDE.md |
~/.claude/CLAUDE.md |
1 file |
| Project CLAUDE.md |
<project>/.claude/CLAUDE.md |
Per-project |
| Memory |
~/.claude/projects/*/memory/MEMORY.md |
1 file |
| Docs |
~/.claude/docs/*.md |
~15 files |
3. Budget Thresholds
| Level |
Token Range |
Action |
| Green |
< 50K total |
Healthy, no action needed |
| Yellow |
50K-100K |
Review largest components |
| Red |
> 100K |
Active optimization required |
4. Key Insights
- Each MCP server with 30+ tools costs ~15,000 tokens in schema alone
- A single verbose SKILL.md can cost more than 10 lean agents combined
- CLAUDE.md files load on EVERY conversation start — keep them lean
- Agent descriptions in REGISTRY.md multiply: loaded once for routing, again per dispatch
- Progressive loading (load skills on demand, not all at once) saves the most
5. Report Format
## Context Budget Report
### Summary
| Category | Files | Est. Tokens | % of Budget |
|----------|-------|-------------|-------------|
| Agents | 61 | XX,XXX | XX% |
| Skills | 116 | XX,XXX | XX% |
| MCP Schemas | 21 | XX,XXX | XX% |
| CLAUDE.md | 2 | XX,XXX | XX% |
| Memory | 1 | XX,XXX | XX% |
| Docs | 15 | XX,XXX | XX% |
| Hooks | 7 | XX,XXX | XX% |
| **TOTAL** | | **XXX,XXX** | **100%** |
### Top 10 Heaviest Components
[ranked list with file path, token estimate, and savings potential]
### Optimization Recommendations
[prioritized by token savings, easiest first]
Optimization Strategies
| Strategy |
Savings |
Effort |
| Trim verbose SKILL.md preambles |
10-30% per file |
Low |
| Use progressive skill loading |
40-60% of skill budget |
Medium |
| Consolidate similar agents |
5-15% of agent budget |
Medium |
| Reduce MCP server declarations to actually-used ones |
20-50% of MCP budget |
Low |
| Move reference docs to on-demand loading |
80-90% of docs budget |
Low |
| Compress MEMORY.md (remove stale entries) |
Variable |
Low |
Cross-references
- operating-framework skill: maintenance cadence for budget reviews
- prompt-reliability-engine skill: Mode 8 (Language Pruning) for content trimming
- setup-audit skill: broader setup health checks
1---2name: context-budget-audit3description: Measure and optimize token overhead across agents, skills, MCP servers, and CLAUDE.md. Identifies bloated components and produces prioritized savings recommendations.4---56# Context Budget Audit78Estimates token consumption per component in your Claude Code setup and identifies9optimization targets. Inspired by everything-claude-code's context budget system.1011## How to use1213- `/context-budget-audit`14 Run a full audit of all agents, skills, MCP servers, hooks, and CLAUDE.md files.1516- `/context-budget-audit <component>`17 Audit a specific component (agents, skills, mcp, hooks, claude-md).1819## When to use2021- Context window feels constrained or sessions compact early22- After adding new agents, skills, or MCP servers23- When troubleshooting slow response times24- Periodic maintenance (monthly recommended)2526## When NOT to use2728- During active development (audit after changes stabilize)29- For code-level token optimization (use tokenizers directly)3031## Token Estimation Rules3233| Content Type | Formula | Notes |34|-------------|---------|-------|35| Prose/Markdown | words x 1.3 | CLAUDE.md, SKILL.md, agent descriptions |36| Code blocks | chars / 4 | Python, YAML, JSON in skills |37| MCP tool schema | ~500 tokens/tool | Each declared tool in an MCP server |38| Agent YAML frontmatter | ~100 tokens | Metadata overhead per agent |3940## Audit Process4142### 1. Scan Components43```44For each category:45 - Read all files matching the pattern46 - Calculate token estimate per file47 - Sum category total48```4950### 2. Component Categories5152| Category | Path Pattern | Expected Count |53|----------|-------------|----------------|54| Agents | `~/.claude/agents/*.md` | ~61 core |55| Skills | `~/.claude/skills/*/SKILL.md` | ~116 |56| MCP Servers | `~/.claude.json` mcpServers | 21 servers |57| Hooks | `~/.claude/settings.json` hooks | 7 hooks |58| Global CLAUDE.md | `~/.claude/CLAUDE.md` | 1 file |59| Project CLAUDE.md | `<project>/.claude/CLAUDE.md` | Per-project |60| Memory | `~/.claude/projects/*/memory/MEMORY.md` | 1 file |61| Docs | `~/.claude/docs/*.md` | ~15 files |6263### 3. Budget Thresholds6465| Level | Token Range | Action |66|-------|------------|--------|67| Green | < 50K total | Healthy, no action needed |68| Yellow | 50K-100K | Review largest components |69| Red | > 100K | Active optimization required |7071### 4. Key Insights7273- Each MCP server with 30+ tools costs ~15,000 tokens in schema alone74- A single verbose SKILL.md can cost more than 10 lean agents combined75- CLAUDE.md files load on EVERY conversation start — keep them lean76- Agent descriptions in REGISTRY.md multiply: loaded once for routing, again per dispatch77- Progressive loading (load skills on demand, not all at once) saves the most7879### 5. Report Format8081```82## Context Budget Report8384### Summary85| Category | Files | Est. Tokens | % of Budget |86|----------|-------|-------------|-------------|87| Agents | 61 | XX,XXX | XX% |88| Skills | 116 | XX,XXX | XX% |89| MCP Schemas | 21 | XX,XXX | XX% |90| CLAUDE.md | 2 | XX,XXX | XX% |91| Memory | 1 | XX,XXX | XX% |92| Docs | 15 | XX,XXX | XX% |93| Hooks | 7 | XX,XXX | XX% |94| **TOTAL** | | **XXX,XXX** | **100%** |9596### Top 10 Heaviest Components97[ranked list with file path, token estimate, and savings potential]9899### Optimization Recommendations100[prioritized by token savings, easiest first]101```102103## Optimization Strategies104105| Strategy | Savings | Effort |106|----------|---------|--------|107| Trim verbose SKILL.md preambles | 10-30% per file | Low |108| Use progressive skill loading | 40-60% of skill budget | Medium |109| Consolidate similar agents | 5-15% of agent budget | Medium |110| Reduce MCP server declarations to actually-used ones | 20-50% of MCP budget | Low |111| Move reference docs to on-demand loading | 80-90% of docs budget | Low |112| Compress MEMORY.md (remove stale entries) | Variable | Low |113114## Cross-references115116- **operating-framework** skill: maintenance cadence for budget reviews117- **prompt-reliability-engine** skill: Mode 8 (Language Pruning) for content trimming118- **setup-audit** skill: broader setup health checks
kmshihab7878