Context Budget Skill

Audits the token overhead of every component loaded into a Claude Code session and reports prioritized savings.

Inventory is deterministic (pure shell, zero Claude tokens). Claude is only used for classification and the final recommendation synthesis.

Step 1: Inventory (Shell Only, Zero Claude Tokens)

Scan every component directory and emit raw counts. Always check user-level (~/.claude/) and project-level (./.claude/ if present). Missing directories are fine — skip silently.

# Token estimation helper — words × 1.3 for prose, chars / 4 for JSON/code
est_tokens() {
  local f="$1"
  local words chars
  read -r words < <(wc -w < "$f")
  read -r chars < <(wc -c < "$f")
  # pick the larger of the two estimates
  local w=$(( words * 13 / 10 ))
  local c=$(( chars / 4 ))
  echo $(( w > c ? w : c ))
}

scan_dir() {
  local label="$1" pattern="$2"
  shift 2
  local total=0 count=0
  for root in "$@"; do
    [ -d "$root" ] || continue
    while IFS= read -r -d '' f; do
      local t
      t=$(est_tokens "$f")
      total=$(( total + t ))
      count=$(( count + 1 ))
      echo "$label | $t | $(wc -l < "$f") | $f"
    done < <(find "$root" -type f -name "$pattern" -print0)
  done
  echo "TOTAL | $label | count=$count tokens=$total"
}

echo "=== Agents ==="
scan_dir agents '*.md' ~/.claude/agents ./.claude/agents

echo "=== Skills ==="
scan_dir skills 'SKILL.md' ~/.claude/skills ./.claude/skills

echo "=== Rules ==="
scan_dir rules '*.md' ~/.claude/rules ./rules ./.claude/rules

echo "=== CLAUDE.md chain ==="
for f in ~/.claude/CLAUDE.md ./CLAUDE.md; do
  [ -f "$f" ] || continue
  echo "CLAUDE.md | $(est_tokens "$f") | $(wc -l < "$f") | $f"
done

Step 2: MCP Inventory (Shell Only)

MCP tool schemas are a major context driver (~500 tokens per tool). Detect configured servers from every source Claude Code reads.

Tool Search caveat. When the harness defers tool definitions (only name + description load up front; the JSON schema loads on demand at first call), the ~500 tokens/tool figure is an upper bound, not the steady-state cost. With deferral active, the always-loaded cost per tool is just its name+description; only schemas of tools actually invoked in the session add their full weight. Report MCP overhead as a range — name+description floor vs. all-schemas-loaded ceiling — rather than assuming every schema is resident.

# Project-level .mcp.json
for f in ./.mcp.json ~/.claude/mcp.json; do
  [ -f "$f" ] || continue
  echo "=== MCP config: $f ==="
  # Show server names and tool counts if jq is available
  if command -v jq >/dev/null; then
    jq -r '.mcpServers // {} | keys[]' "$f" 2>/dev/null
  else
    grep -E '^\s*"[^"]+"\s*:\s*\{' "$f" | head -20
  fi
done

# Claude CLI-registered servers (authoritative if present)
if command -v claude >/dev/null; then
  claude mcp list 2>/dev/null || true
fi

For each connected server, record the number of tools it exposes. If the server is not currently connected (e.g. Ollama is down), note it as "inactive" rather than counting tools as zero.

Step 3: Hooks Note (Not Context Overhead)

Hooks in ~/.claude/hooks/ do not load into the prompt. They execute out-of-band. Report their count for completeness but do not include their tokens in the overhead total.

ls ~/.claude/hooks/*.sh 2>/dev/null | wc -l

Step 4: Classification

For each component surfaced by Step 1, place it in one of three buckets using the criteria below. Use the component's description frontmatter when present — that is the only part guaranteed to load into every Task tool invocation.

Step 5: Detect Bloat Patterns

Flag each of the following if present:

• Bloated descriptions — any frontmatter description longer than 30 words. Descriptions load into every Task invocation, so verbosity compounds.
• Heavy skill files — SKILL.md over 400 lines.
• Heavy agents — agent *.md over 200 lines.
• Heavy rule files — single rule file over 100 lines (split into smaller overlays).
• Redundant components — skills that duplicate an agent's role, rule files that restate CLAUDE.md, agent descriptions that restate their own system prompt.
• MCP oversubscription — more than 10 active servers, or any server that wraps a CLI tool already allowed in settings.json (e.g. a git / gh / npm MCP is pure overhead when those commands are in the allow list).
• CLAUDE.md bloat — combined CLAUDE.md chain over 300 lines; extract detailed guidance into rules/ instead.

Step 6: Report

Emit the report in Japanese (per Language Policy). Use this shape:

Context Budget Report
=====================

推定オーバーヘッド合計: 約 XX,XXX tokens
コンテキストウィンドウ: {{context_window}}
実効残量: 約 XXX,XXX tokens (XX%)   ← {{context_window}} が不明なら省略

内訳:
| 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  |

検出された問題 (N 件):
  [savings 降順]

Top 3 最適化:
  1. [action] → 約 X,XXX tokens 削減
  2. [action] → 約 X,XXX tokens 削減
  3. [action] → 約 X,XXX tokens 削減

潜在削減量: 約 XX,XXX tokens (現オーバーヘッドの XX%)

Replace {{context_window}} with the running session's own window. Opus 4.6+, Sonnet 4.6+, Fable 5, and Mythos 5 are 1M; Sonnet 4.5 and earlier, and Haiku, are 200K — so the tier alone does not tell you, and neither does the model family. Nothing in the shell can report it either: settings.json carries no model key. It comes from your session context, not a command. When you cannot establish it, write 不明 and omit the 実効残量 line rather than dividing by a guessed denominator: that percentage is the number the user acts on.

Verbose mode (--verbose or "詳細" requested): additionally print the per-file table from Step 1, the full MCP tool list with per-tool schema size estimates, and side-by-side overlap between redundant components.

Best Practices

• MCP is the biggest lever — each tool schema costs ~500 tokens. A 30-tool server alone exceeds most skill collections. With Tool Search deferral active (see Step 2), that ~500/tool is a ceiling, not the resident cost — but a large server still inflates the name+description floor that always loads, so trimming unused servers still pays off.
• Agent descriptions always load — even agents never invoked in a session contribute their description to every Task call.
• Hooks are free — they execute but do not consume context. Prefer hooks over skills when the work is deterministic shell logic.
• Audit after each additive change — run this skill after adding a skill, rule, agent, or MCP server to catch creep early.
• The window is not usable space — reserve at least 40% for conversation and tool output. Overhead above 30% of the window starts degrading quality.