---
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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
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

```bash
# 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