Lobster Context Budget

Audits Claude Code context window consumption across agents, skills, MCP servers, and rules. Identifies bloat, redundant components, and produces prioritized...

Security Scan

The skill's instructions, required resources, and behavior match its stated purpose of scanning a Claude Code workspace for token overhead; it does not request unrelated credentials or install external code, but it will read many project files so you should be aware of what it may access.

Purpose & Capability

Name and description claim an audit of context/window usage across agents, skills, MCP servers, rules and CLAUDE.md; the SKILL.md explicitly lists exactly those repository paths and components to scan (agents/*.md, skills/*/SKILL.md, rules/**/*.md, .mcp.json, CLAUDE.md). No unrelated env vars, binaries, or installs are requested, so the required footprint is proportionate to the stated purpose.

Instruction Scope

The runtime instructions require scanning many workspace files and producing per-file token estimates and overlap detection (including line-by-line diffs in verbose mode). This is coherent with an auditing tool, but it means the agent will read potentially sensitive project files (configs, rules, agent descriptions, MCP configs). The skill does not instruct any external exfiltration, but the scope of file access is broad — review whether you want an automated agent to read all those paths.

Install Mechanism

No install spec and no code files are present (instruction-only). This minimizes risk because nothing new is written to disk or downloaded; the skill relies only on workspace file access and internal processing.

Credentials

The skill requires no environment variables, credentials, or config paths beyond reading repository files it documents. There are no unexplained secret requests. Note: some of the files it scans (e.g., .mcp.json or other config files) may themselves contain sensitive endpoints or tokens in some setups — that is a consequence of scanning project files, not an explicit credential demand.

Persistence & Privilege

The skill is not always:true, does not install or modify agent/system configuration, and is user-invocable only. Autonomous invocation remains possible (default platform behavior) but is not combined with elevated persistence or broad credential access in this skill.

Assessment

This skill appears to do what it claims: it reads repository files to estimate token usage and recommend removals. Before enabling or running it, consider: 1) It will access many project files (agents/*.md, skills/*/SKILL.md, rules/**/*.md, .mcp.json, CLAUDE.md). If those files contain secrets or private data, run the audit in a controlled environment or remove/rotate sensitive values first. 2) Run in non-verbose mode first to get a high-level view, then verbose only if needed. 3) If you want to limit its scope, temporarily move or git-ignore sensitive files or run the agent with restricted workspace permissions. 4) Because it's instruction-only, no external code is installed, but the agent will have read access to your repo — confirm you are comfortable with that access before invoking the skill.

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