skill-budget-audit

name	skill-budget-audit
description	Diagnose and fix Claude Code's skill context budget overflow — identify heavy plugin bundles that exceed the 2% budget, remove domain-specific ones, deactivate rarely-used skill sets, and validate the warning clears. Use when Claude Code shows "Exceeded skills context budget" or skill descriptions are stripped.
license	MIT
allowed-tools	Bash, Read, Write, Edit
compatibility	Claude Code only. Requires access to ~/.claude/ and ~/.claude/plugins/
metadata	{"targets":["_source-only"],"author":"Oleg Koval","tags":["claude-code","skills","plugins","context-budget","token-economy","performance"]}

🤖 Auto-generated by weekly-pattern-learner · Skill context budget overflow appeared in 2 sessions this week (Jun 2026): initial investigation (7 turns, 742 skills hidden) and cleanup followup (14 turns)

Skill Context Budget Audit

Overview

Claude Code allocates 2% of its context window for skill descriptions. With too many plugins installed, descriptions get stripped and skills become invisible. This skill audits plugin bundles, removes unused domain-specific ones, and restores skill discoverability.

When to Use

• Claude Code shows: ⚠ Exceeded skills context budget of 2%. All skill descriptions were removed and N additional skills hidden.
• Skill invocations fail silently or Claude cannot find a skill by name
• After installing multiple plugin bundles, noticing slowdown or skill lookup failures
• Periodically as a maintenance step when adding new skill collections

Workflow

1. Confirm the Symptom

# Check Claude Code logs for context budget warning
cat ~/.claude/logs/claude-code.log 2>/dev/null | grep -i "skill" | tail -20

# Or count installed plugins
ls ~/.claude/plugins/cache/ | wc -l

If you see Exceeded skills context budget or more than ~20 plugin bundles, proceed.

2. Inventory Installed Plugins

# List all installed plugins with size
du -sh ~/.claude/plugins/cache/*/ 2>/dev/null | sort -rh | head -30

# Count skills per bundle
for dir in ~/.claude/plugins/cache/*/; do
  count=$(find "$dir" -name "*.md" -path "*/skills/*" 2>/dev/null | wc -l | tr -d ' ')
  echo "$count  $dir"
done | sort -rn | head -20

3. Identify Removal Candidates

Remove bundles that match any of these criteria:

Criterion	Example bundles
Domain not active in current projects	claude-for-financial-services, bitwize-music
Duplicate superpowers installations	Multiple superpowers-* versions
Language-specific bundles for inactive languages	cc-skills-golang when not working in Go
Bundles with 30+ skills you never invoke	Large catch-all collections

Keep: core workflow skills (superpowers, agent-skills), project-specific skills, personal skill collections.

4. Remove Heavy Bundles

# List Claude Code plugins (check settings.json for registered ones)
cat ~/.claude/settings.json | grep -A 50 '"plugins"'
# or
cat ~/.claude/settings.local.json 2>/dev/null | grep -A 50 '"plugins"'

Remove via Claude Code settings or by editing the plugins list directly:

# Backup first
cp ~/.claude/settings.json ~/.claude/settings.json.bak

# Then edit ~/.claude/settings.json to remove plugin entries
# Remove entries like:
#   "claude-for-financial-services"
#   "bitwize-music"
#   duplicate superpowers entries

Remove cached plugin directories:

cache_dir="$HOME/.claude/plugins/cache/<bundle-name>"
if [ -d "$cache_dir" ]; then
  rm -rf "$cache_dir"
fi

5. Conditionally Load Heavy Skill Sets

For language-specific bundles (e.g., cc-skills-golang):

• Only install when actively working in that language
• Uninstall when switching projects

For security-focused skills (secskills):

• Configure as manually invocable only (not auto-loaded)
• In plugin settings: set autoLoad: false if supported

6. Validate the Fix

# Restart Claude Code and check:
# 1. No "Exceeded skills context budget" warning on startup
# 2. /find-skills or skill listing shows descriptions (not empty)
# 3. rtk gain shows reasonable context usage
rtk gain 2>/dev/null || echo "rtk not available"

Open a new Claude Code session and run a skill that was previously failing — verify it activates correctly.

7. Prevent Recurrence

Budget targets:

• Keep installed skills under ~200 total (rough safe limit)
• Prefer curated skill sets over catch-all bundles
• Review and prune quarterly

Useful heuristics:

• If you haven't invoked a skill in 30 days, the bundle is a candidate for removal
• Language packs → install per-project, not globally
• Duplicate superpowers/agent-skills versions → keep exactly one

Verification

• No "Exceeded skills context budget" warning in new session
• Skill descriptions visible in /find-skills output
• Previously failing skill invocations succeed
• Plugin count reduced to below ~20 bundles
• ~/.claude/settings.json backed up before changes