Skill Library Hygiene

What it does for you · install · a first command that runs

What it replaces is pruning from memory. You remember which skills feel useful, but not what each one costs in tokens or when it last ran.

# 1. Official checkup (Claude Code v2.1.252+, run in the terminal)
/skill-doctor
# Interactive: opens in the /plugin manager's Stats tab; with -p it prints text

# 2. Official switch: highlight a skill, press Space to cycle states, Esc to save
/skills
# Written to .claude/settings.local.json, equivalent to:
{ "skillOverrides": { "legacy-context": "name-only", "deploy": "off" } }

# 3. Plugin skills ignore skillOverrides, so check them separately
claude plugin details <name>   # Always-on line = tokens added to every session

The /skill-doctor report lists each skill's context cost and invocation count, flags the ones that have never run, and tells you where to turn them off. The docs say to start with the most expensive ones. It also lists plugins you haven't used recently, and the Installed tab in /plugin has a Not used recently group plus a Last used line on each plugin.

Mechanism: what actually breaks when skills pile up

1. The listing budget: least-used skills go quiet first

Per the docs, the listing's character budget is 1% of the model's context window. When it overflows, Claude Code drops descriptions starting with the skills you invoke least. The name stays, but the keywords vanish, so Claude rarely matches the skill on its own. The Skills row in /context shows the size after trimming, and /doctor estimates the listing cost and its biggest contributors. You can raise skillListingBudgetFraction (for example 0.02), but that delays the problem. It doesn't fix it.

2. Name shadowing: no error

For same-name skills the order is enterprise > personal > project. With both ~/.claude/skills/deploy and the repo's .claude/skills/deploy, /deploy runs your personal copy. A teammate updates the project version, you keep running the old one, and nothing warns you. Plugin skills are namespaced as /plugin-name:skill-name, so they don't collide on names, but two similar entries can end up competing for the same requests.

3. Bodies stay resident: invoke once, it stays

Once a skill runs, its body stays in the conversation as a message, and later turns don't re-read the file. During auto-compaction each skill keeps only its first 5,000 tokens, all skills share 25,000 tokens, and the budget fills from the most recently invoked skill. Invoke too many in one session and the earlier ones can drop out entirely after compaction.

Real usage and limits: naming, dedup, deprecation, folding back

Consistent naming: let a machine find the mistakes

The Agent Skills spec allows only lowercase letters, digits and hyphens in name, caps it at 64 characters, and requires it to match the parent directory. Check with skills-ref: skills-ref validate ./my-skill. The official "Skill authoring best practices" suggests gerund names (processing-pdfs) and names what to avoid: vague names like helper, utils and tools, and inconsistent patterns within your collection.

Dedup: two layers of detection

• MindiveLabs/skill-doctor (community, MIT). Note that it shares a name with the official /skill-doctor but is unrelated. It scans SKILL.md files in personal and project directories and reports seven conflict types, including name shadow, trigger collision, semantic overlap, proactive race, state-file collision and subsumption. It is read-only by default. Only --fix moves a conflicting skill into ~/.skill-doctor/trash/. Install: /plugin marketplace add MindiveLabs/skill-doctor → /plugin install skill-doctor@skill-doctor. When to skip it: the GitHub repo page showed just 4 stars (read 2026-10), and it registers two background hooks, so read it first using the Skill 30 checklist. Don't install it with git clone, or it will shadow the official /skill-doctor (see the end of this issue).
• skill-creator's Description Optimization. When two skills compete for the same requests, write 20 trigger evals for the one you keep, about half of them near-misses that should not trigger it. scripts.run_loop splits them 60/40 into train and held-out sets, runs each query 3 times, iterates up to 5 rounds, and picks the best description by held-out score.

Deprecation: walk the state ladder instead of deleting outright

The four skillOverrides states already form a deprecation path: on → name-only (name only, frees description budget) → user-invocable-only (Claude can't see it, you can still type /name) → off (hidden everywhere). Once a while has passed and nobody missed it, delete the folder. For plugins, use /plugin disable or /plugin uninstall. For outdated sections inside a skill, the official guide suggests a collapsed "Old patterns" section instead of leaving them mixed into the body.

Libraries shared across tools: keep one source

If you use several agents, the classic failure is three copies with only one of them updated. Vercel's skills CLI (about 33.1k stars on its GitHub repo page, read 2026-10) symlinks every agent directory to one canonical copy by default. npx skills list shows what's installed, npx skills update upgrades, and npx skills remove <name> uninstalls. When to skip it: if you only use Claude Code, the built-in /skills and /plugin are enough.

Criteria: keep it, demote it, or fold it back into the prompt

• Invoked in almost every session, with a short body → it's really a standing fact, so move it into CLAUDE.md. That's my own rule of thumb. The official line is that CLAUDE.md holds context needed on every turn and skills hold discrete tasks.
• Only you ever type /name → set it to user-invocable-only so its description stops taking listing space.
• Triggers overlap with another skill → merge them into one, then run trigger evals on the survivor.
• /skill-doctor shows it has never run, and it's expensive → set it to off. If nobody misses it within a month, delete it.
• Down to one or two rules → put them back in your prompt or CLAUDE.md. If a rule must hold every time, make it a hook.

Costs and alternatives

1. "Never invoked" doesn't mean useless

Some skills run once a quarter, and that one run matters, like a release checklist. /skill-doctor counts invocations. It doesn't measure value. For skills like that, demoting to user-invocable-only is safer than deleting.

2. Demotion changes behavior

At name-only the description is gone, so anything that relied on keyword auto-triggering stops working. Verify after the change. The official method is to pick a few realistic prompts and run each in a fresh session with the skill on and again with it off. For plugin skills, claude plugin eval adds a no-plugin baseline automatically.

3. The tooling needs hygiene too

Community dedup tools and cross-agent managers are new dependencies. They register hooks, create their own directories and need updating. Before you install two tools to clean up ten skills, do the math.