context-budget

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Context Budget

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

分析Claude Code会话中每个已加载组件的Token开销，提出可落地的优化方案以回收上下文空间。

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)

会话性能变慢或输出质量下降时
最近添加了大量Skill、Agent或MCP服务器后
想了解实际剩余的上下文空间
计划添加更多组件，需要确认是否有足够空间
执行
```
/context-budget
```
命令时（本Skill为该命令提供支持）

How It Works

工作原理

Phase 1: Inventory

阶段1：组件盘点

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

扫描所有组件目录并估算Token消耗：

Agent (

agents/*.md

)

统计每个文件的行数与Token数（单词数 × 1.3）
提取
```
description
```
前置元数据的长度
标记：文件超过200行（过重）、描述超过30个单词（元数据冗余）

Skill (

skills/*/SKILL.md

)

统计每个SKILL.md的Token数
标记：文件超过400行
检查
```
.agents/skills/
```
中的重复副本——跳过完全相同的副本以避免重复统计

规则 (

rules/**/*.md

)

统计每个文件的Token数
标记：文件超过100行
检测同一语言模块下规则文件之间的内容重叠

MCP服务器（

.mcp.json

或活跃MCP配置）

统计已配置的服务器数量与工具总数
估算每个工具的Schema开销约为500 Token
标记：工具数量超过20的服务器、封装了简单CLI命令（
```
gh
```
、
```
git
```
、
```
npm
```
、
```
supabase
```
、
```
vercel
```
）的服务器

CLAUDE.md（项目级与用户级）

统计CLAUDE.md链中每个文件的Token数
标记：总长度超过300行

Phase 2: Classify

阶段2：分类排序

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

将每个组件归入对应类别：

类别	判定标准	处理建议
必需组件	被CLAUDE.md引用、为活跃命令提供支持、或匹配当前项目类型	保留
按需组件	特定领域专用（如语言模式）、未被CLAUDE.md引用	考虑按需激活
极少使用组件	无命令引用、内容重叠、或与当前项目无明显匹配	删除或懒加载

Phase 3: Detect Issues

阶段3：问题检测

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

识别以下问题模式：

Agent描述冗余——前置元数据中的描述超过30个单词，会加载到每一次Task工具调用的上下文中
Agent过重——文件超过200行，会在每次生成Task时膨胀上下文
组件冗余——Skill与Agent逻辑重复、规则与CLAUDE.md内容重复
MCP过度订阅——服务器数量超过10个，或服务器封装了可免费使用的CLI工具
CLAUDE.md冗余——冗长的说明、过时的章节、应归入规则的操作说明

Phase 4: Report

阶段4：生成报告

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    │
└─────────────────┴────────┴───────────┘

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

生成上下文预算报告：

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)

在 verbose 模式下，还会输出每个文件的Token统计、最占空间文件的逐行分解、重叠组件间的具体重复行、以及包含每个工具Schema大小估算的MCP工具列表。

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%

基础审计

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模式

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

Token估算：散文内容用
```
单词数 × 1.3
```
，代码密集型文件用
```
字符数 / 4
```
MCP是关键优化点：每个工具Schema约消耗500 Token；一个30工具的服务器消耗的Token超过所有Skill的总和
Agent描述始终加载：即使Agent从未被调用，其描述字段也会出现在每一次Task工具的上下文中
Verbose模式用于调试：需要精确定位导致开销的具体文件时使用，不适合常规审计
变更后审计：添加任何Agent、Skill或MCP服务器后运行审计，尽早发现冗余膨胀