agentleFS
Sign inStart free
loulanyueloulanyue/awesome-claude-notes/skills/context-budget/SKILL.md

context-budget

Skill272 starsChanged 7 months agoMITView on GitHub

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

We split this skill into the rules it gives an agent

4 rules. 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 43 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Check for duplicate copies in .agents/skills/ — skip identical copies to avoid double-counting

    line 33
  2. Very specific:

    Token estimation: use words × 1.3 for prose, chars / 4 for code-heavy files

    line 131
  3. Distinctive:

    Verbose mode for debugging: use when you need to pinpoint the exact files driving overhead, not for regular audits

    line 134
  4. Distinctive:

    Audit after changes: run after adding any agent, skill, or MCP server to catch creep early

    line 135

“Common” is measured: kept by at least 6 in 10 of the 43 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

BucketCriteriaAction
Always neededReferenced in CLAUDE.md, backs an active command, or matches current project typeKeep
Sometimes neededDomain-specific (e.g. language patterns), not referenced in CLAUDE.mdConsider on-demand activation
Rarely neededNo command reference, overlapping content, or no obvious project matchRemove 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    │
└─────────────────┴────────┴───────────┘

⚠ 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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free