Skill: wangxiaofei860208-source/lobster-context-budget (version 1.0.0)

--- name: lobster-context-budget description: Audits Claude Code context window consumption across agents, skills, MCP servers, and rules. Identifies bloat, redundant components, and produces prioritized token-savings recommendations. origin: ECC --- # 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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)