agentleFS
fortunto2fortunto2/solo-factory/skills/skill-shelf/SKILL.md

solo-skill-shelf

Skill18 starsChanged 4 months agoMITView on GitHub

Keep rarely used skills off the session's skill list and bring them back on demand — usage stats from transcripts, shelve, list, restore, plugin and claude.ai sync switches. Use when user says "skill usage", "which skills do I use", "archive skills", "too many skills", "bring back the X skill", "is there an archived skill for", "статистика скилов", "убери скилы", "достань скил", or a task needs a capability no loaded skill covers. Do NOT use for scoring one skill's quality (use /skill-audit) or creating a skill (make new-skill).

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every visible skill costs its description in every session, and tool choice gets worse as the list grows (Anthropic reports selection …

    line 16
  2. Very specific:

    Before writing the procedure from scratch, run shelf list <keyword>.

    line 34
  3. Very specific:

    Verify with a headless count, never by assumption: claude -p 'How many skills are available via the Skill tool?

    line 48
  4. Distinctive:

    Don't shelve a plugin's skill by moving files inside the plugin cache.

    line 61
  5. Very specific:

    Don't rm a skill to prune it.

    line 63
  6. Very specific:

    Don't call a skill unused from a run that read zero transcripts: stats exits 2 with UNKNOWN in that case, on purpose.

    line 64

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/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

  1. stats. Zero is a candidate, not a verdict: a skill read by path instead of invoked is not counted, and transcripts older than cleanupPeriodDays are gone.
  2. 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).
  3. Scope by folder where use is local: <project>/.claude/skills/. Claude Code does NOT read .claude/skills from parent directories (measured: a skill in ~/projects/.claude/skills is invisible to a session in ~/projects/app), so the scope is one project, not a tree.
  4. 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

SourceSwitch (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 rm a skill to prune it. The shelf is the undo.
  • Don't call a skill unused from a run that read zero transcripts: stats exits 2 with UNKNOWN in that case, on purpose.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.