skill-optimize

Find the Claude Code skills & plugins that are quietly bloating your input context — and trim them.

Every skill and enabled plugin you install loads its name + description into your system prompt on every single turn, whether you use it or not. Install enough of them "just in case" and you can be burning tens of thousands of input tokens before you type a word — hitting your limits far faster than you need to.

skill-optimize reads your real usage logs, shows you exactly what's dead weight, and trims it safely.

$ python3 skill-optimize.py --demo

── Loaded skills ─────────────────────────────────────────
  DEAD          0 use  ~194tok  math-olympiad        plugin:math-olympiad
  DEAD          0 use  ~153tok  changelog-gen        plugin:workflow-tools
  ...
  situational   2 use  ~ 88tok  skill-creator        user
  kept         14 use  ~ 68tok  commit-helper        user

  loaded skill footprint : ~1712 tokens/turn
  reclaimable (dead+situational): ~1307 tokens/turn

── Plugins ───────────────────────────────────────────────
  enabled plugins: 9   5 with zero usage in 60 days

  before: ~34,800 input tokens/turn
  after : ~24,100 input tokens/turn   (-10,700, ~31% leaner)

What it does

1. Figures out which skills are actually loaded into your context — your ~/.claude/skills/, any project .claude/skills/, and skills from enabled plugins only. (A cloned marketplace catalog costs you 0 tokens until you enable a plugin — those aren't counted.)
2. Measures each loaded skill's real footprint = the size of its SKILL.md frontmatter, which is what gets injected each turn.
3. Scans ~/.claude/projects/**/*.jsonl over the last N days and counts how many times each skill was actually invoked.
4. Buckets each skill: dead (0 uses) / situational (1–2) / kept (3+), and estimates the tokens you'd reclaim.
5. With --apply, safely trims the dead weight.

Install

No dependencies — just Python 3.

mkdir -p ~/.claude/scripts
curl -o ~/.claude/scripts/skill-optimize.py \
  https://raw.githubusercontent.com/maverick0545/skill-optimize/main/skill-optimize.py

Usage

python3 ~/.claude/scripts/skill-optimize.py            # report (default, last 60 days)
python3 ~/.claude/scripts/skill-optimize.py --days 30  # different window
python3 ~/.claude/scripts/skill-optimize.py --cwd .    # also count this project's skills
python3 ~/.claude/scripts/skill-optimize.py --apply    # interactively trim (with backups)
python3 ~/.claude/scripts/skill-optimize.py --demo     # print a sample populated report

Optional: run it as a /skill-optimize slash command

Create ~/.claude/skills/skill-optimize/SKILL.md:

---
name: skill-optimize
description: Audit which Claude Code skills/plugins are loaded but unused and trim them to cut input-token bloat.
---
Run `python3 ~/.claude/scripts/skill-optimize.py`, show the user the buckets and
reclaimable token estimate, then run with `--apply` if they want to trim. Remind
them to restart Claude Code afterward.

Safety

--apply only touches real, reversible levers:

• Plugins → sets enabledPlugins[<plugin>] = false in settings.json. Your settings.json is backed up with a timestamp first.
• Dead user skills → moved (not deleted) to ~/.claude/skills-disabled/.

Nothing is ever deleted. Restart Claude Code afterward to apply the leaner context.

How the token estimate works

Token cost ≈ characters / 4 (a standard heuristic) applied to each skill's SKILL.md frontmatter. It's an estimate, not an exact count — directionally accurate for deciding what to cut.

License

MIT © AUSBOTICS

---

Built by @ausbotics — AI infra tools, in public.