| name | skill-selector |
| description | Use before a multi-step task when it is not obvious which skills apply, or when you catch yourself about to read the 243-skill README to decide. Dispatches a throwaway sub-agent that reads ONLY the router (index.md) and returns the MINIMAL set of skills to load for this task — never the whole library. Anti-bloat: pull the few skills the task earns, use them, let them fall out of context (check-in). Maximise capability per token, not skill count. |
skill-selector — just-in-time, minimal skill loading
The problem this solves. The library is 243 skills. Reading the full README.md to decide
which apply is itself a context-bloat event — it can cost more tokens than the task. And loading
skills "just in case" poisons the working context with instructions the task never needed. The
founder's directive (2026-07-25): sub-agents determine which skills a task requires so we are
not pulling all skills and bloating the system; once used and no longer required, they fall out
of context until required again. Maximise, do not minimise — capability per token.
The rule. Never scan the whole catalog in the main context to pick skills. Either match the
router directly (cheap), or — when the fit is unclear or the task spans domains — dispatch a
throwaway selector sub-agent that does the scanning in ITS context and returns only names.
When to use
- A multi-step / multi-domain task where the right skills aren't obvious from the router alone.
- You notice yourself about to
Read the 243-skill README.md in the main thread — stop, use this.
- Before a
/nexus fan-out, to hand each specialist ONLY its needed skills.
Skip it for a task the always-loaded index.md router already routes in one hop (that IS the
fast path — the router exists so most tasks need no selector).
How it works (three moves)
-
Cheap match first (no sub-agent). Try the always-loaded router ~/.claude/skills/index.md
(≤60 lines, already in context). If one entry-point clearly owns the task, load THAT via the
Skill tool and stop. Done — zero extra cost.
-
Selector sub-agent (only if step 1 is ambiguous or multi-domain). Dispatch a throwaway
agent (general-purpose) with this brief — it reads in ITS context, not yours:
Read ~/.claude/skills/index.md first; only if the task isn't covered there, grep
~/.claude/skills/README.md for the specific domain lines. Return STRICTLY JSON:
{"skills":[{"name":"<canonical-skill>","why":"<one line>","load":"now|on-demand"}], "note":"<anything the caller must know, e.g. a gate that fires first>"}
Rules: return the CANONICAL entry-point skill, never its sub-skills (the entry dispatches
its own). Cap at 5. If >5 seem needed, the task should be DECOMPOSED — say so in note
instead of listing more. Prefer on-demand over now: mark now only for skills needed
before the first action. Never invent skill names; if nothing fits, return an empty list.
-
Load minimal, use, check in. Load only the now skills via the Skill tool; keep the
on-demand list as a note and load each the moment its step arrives. When a skill has served
its purpose, do not re-read or restate it — it falls out of context naturally (the check-in
rule, CLAUDE.md §6). Never hold a skill body in context "in case".
Anti-bloat invariants (do not violate)
- The main context never holds the full catalog. Scanning happens in the router (cheap) or a
sub-agent (isolated) — never by reading
README.md in the working thread.
- Load-on-earn, not load-on-maybe. A skill enters context only when its step is next.
- ≤5 skills per task; more = decompose. A task wanting 6+ skills is two tasks.
- Canonical entry-points only. Never load a sub-skill directly; the entry-point routes it.
- Check in when done. Served skills are not re-read; they leave context until required again.
Output contract
Return: the minimal skill list (name + why + now/on-demand), any gate that must fire first
(e.g. proof-discipline, pr-release-gate), and — if the task is too big for ≤5 skills — the
decomposition instead of a bloated list.
Relates to: nexus (calls this before a fan-out), context-cockpit (session-level context audit),
[[feedback-tight-code]] (delete more than you add), CLAUDE.md §6 (check-out / check-in).
