/skill-shelf
Every visible skill costs its description in every session, and tool choice gets
worse as the list grows (Anthropic reports selection degrading past 30–50
definitions). The shelf is a directory no skill loader reads. A skill on it costs
nothing, and restore makes it visible again from the next session.
SHELF="${CLAUDE_PLUGIN_ROOT}/skills/skill-shelf/scripts/shelf.py"
python3 "$SHELF" stats [--days 56] # who was invoked, how often, last date; unused in ~/.claude/skills
python3 "$SHELF" list [query] # what is on the shelf, with description and why it went there
python3 "$SHELF" shelve a b --reason "0 uses in 8 weeks" # [--from <project>/.claude/skills]
python3 "$SHELF" restore a # back where it came from; [--to <project>/.claude/skills]
Shelf: $SKILL_SHELF_DIR, default ~/.claude/skills-archive/, with .shelf.json
recording origin, date and reason per skill.
When a task needs a skill you do not have
Before writing the procedure from scratch, run shelf list <keyword>. If one
fits, restore it, tell the user it is back, and read its SKILL.md by path for
this session (a restored skill is listed only from the next session).
Pruning pass
stats. Zero is a candidate, not a verdict: a skill read by path instead of invoked is not counted, and transcripts older thancleanupPeriodDaysare gone.- Shelve third-party skills with zero uses. Own skills with zero uses: ask, or
move them into the one project that needs them (
restore --to). - Scope by folder where use is local:
<project>/.claude/skills/. Claude Code does NOT read.claude/skillsfrom parent directories (measured: a skill in~/projects/.claude/skillsis invisible to a session in~/projects/app), so the scope is one project, not a tree. - Verify with a headless count, never by assumption:
claude -p 'How many skills are available via the Skill tool? total=N'.
Skills that are not files
| Source | Switch (in ~/.claude/settings.json) |
|---|---|
| Plugin | "enabledPlugins": {"name@marketplace": false} (per project in .claude/settings.json) |
Plugins synced from claude.ai (Cowork: marketing:, design: …) |
"syncClaudeAiPlugins": false. enabledPlugins does not reach them |
Skills synced from claude.ai (anthropic-skills:*) |
"syncClaudeAiSkills": false |
Don't
- Don't shelve a plugin's skill by moving files inside the plugin cache; the next update restores it. Disable the plugin, or split it.
- Don't
rma skill to prune it. The shelf is the undo. - Don't call a skill unused from a run that read zero transcripts:
statsexits 2 with UNKNOWN in that case, on purpose.