---
name: audit-budget
description: Reports per-plugin skill description token contributions to help reduce session startup budget. Use when /doctor shows skill descriptions dropped.
allowed-tools:
- Bash
---

<purpose>
Audit the user's installed-and-enabled CC plugins to identify the biggest
contributors to the session-startup skill description budget. Output a
prioritized table + actionable recommendations (which plugins to disable,
which settings to tweak).
</purpose>

<core_principle>
Per CC docs the skill description budget defaults to 1% of context window
(`skillListingBudgetFraction: 0.01`). When the listing exceeds the budget,
descriptions for the least-used skills are collapsed to bare names — `/doctor`
shows "N skill descriptions dropped". This skill helps user decide which
plugins to disable or which settings to adjust to reduce N.
</core_principle>

## Steps

### 1. Run the audit script

```bash
set -euo pipefail
# Forward args verbatim. "$@" expands to zero elements when invoked with no
# args (the documented default path); "${@:-}" would expand to a single
# empty string which the argparse layer rejects as an unknown positional.
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/audit_budget.py" "$@"
```

Script output:
- Top N plugins ranked by descriptive-chars contribution (default top 15)
- Per-plugin invocable skill count + estimated tokens
- Enabled flag (YES vs disabled)
- Recommendations: disable candidates, settings tweaks, bug awareness

### 2. Pass-through arguments

`$ARGUMENTS` may include:
- `--top N` — show top N (default 15)
- `--json` — machine-readable output for piping

### 3. Interpret recommendations

The script identifies "disable candidates" as plugins with >10 invocable
skills that are currently enabled. These are the highest-leverage disables
if the user isn't actively using that plugin.

Settings tweaks listed are official CC settings (no gambiarras):
- `skillListingBudgetFraction: 0.02` — doubles the budget (more context cost)
- `skillOverrides` — per-skill visibility states without editing SKILL.md
- `ENABLE_TOOL_SEARCH=auto` (or `auto:5`) — defers MCP tool schemas

### 4. Bug awareness reminders

The script warns about two upstream CC bugs that affect interpretation:
- `#49835` — `paths:` frontmatter breaks skill discovery (no fix as of v2.1.143)
- `#40314` — HTTP MCP servers ignore `ENABLE_TOOL_SEARCH` (closed not-planned)

## Output contract

Default human-readable table. With `--json`, structured JSON for tooling.

```
plugin@marketplace                                       inv   tot  tokens  on?
--------------------------------------------------------------------------------
marketing-skills@coreyhaines-marketingskills              41    41    1230  YES
data@claude-plugins-official                              21    21     630  YES
caveman@caveman                                           11    11     330  YES
...
--------------------------------------------------------------------------------
ENABLED invocable total: 140 skills, ~4200 tokens

Recommendations:
  Disable candidates (>10 invocable skills, consider /plugin disable):
    - marketing-skills@coreyhaines-marketingskills  (41 invocable, ~1230 tokens)
    - data@claude-plugins-official  (21 invocable, ~630 tokens)
    - caveman@caveman  (11 invocable, ~330 tokens)
  ...
```

## Error handling

| Condition | Action |
|---|---|
| `installed_plugins.json` missing | Print warning, exit 0 (informative) |
| `settings.json` missing | Treat all as not-enabled |
| Plugin install path missing on disk | Skip, log to stderr |
| Frontmatter unparseable | Skip skill, count as total but not invocable |

## Notes

- This skill is `disable-model-invocation: true` — user invokes via
  `/maxvision:audit-budget`
- Token estimates use the documented ~4 chars/token approximation; actual
  count varies per model tokenizer
- See `.maxvision/specs/2026-05-17-startup-context-optimization.md` for the
  full lever inventory this skill supports