# Skill Router
Skill Router organizes large local agent skill libraries into category router
skills. It keeps leaf skills in a hidden library, exposes only high-level router
skills, and asks the agent to read lower-level skill bodies only when compact
metadata is ambiguous.
The core classifier is not rule-based. The script creates a compact inventory
and body-review queue; the coding agent writes the final category routing plan.
BM25 and token overlap are used only to decide which skill bodies deserve a
closer read.
## When this helps
The router is a **resident-context optimization**: its cost is roughly constant
(only the category descriptions stay in context), while a flat skill library's
resident cost grows ~10 tokens per skill. So it pays off in proportion to library
size and to how the host loads skills. Benchmarked on the Claude Code CLI:
| flat library | resident tokens | router saving / turn |
| --- | --- | --- |
| ~170 skills | ~14.4k | ~8% |
| ~350 skills | ~16.7k | ~21% |
| ~700 skills | ~21.2k | ~38% |
- **Use the router for large libraries (hundreds to thousands of skills), long
multi-turn sessions, or hosts that load full skill bodies into context.** There
the constant-cost router clearly beats a linearly-growing flat list on tokens.
- **It is a token trade, not an accuracy win.** In testing, flat selection
matched or beat routing (100% vs 85% at 600 distinct skills; a capable model
finds the right skill in a large flat list, and the router's extra
category-mapping step can mis-route). Below a few hundred skills on a
lazy-loading host (Claude Code) the native skill system is usually enough.
See `docs/benchmark-findings.md` for the full methodology and results.
## Repository Layout
- `scripts/skill-router.mjs`: shared CLI entrypoint.
- `plugins/skill-router/`: Claude Code plugin package.
- `.agents/plugins/marketplace.json`: Codex plugin marketplace.
- `.agents/skills/skill-router/`: Codex repository skill adapter.
- `gemini-extension.json`, `GEMINI.md`, `commands/`: Gemini CLI extension.
- `.cursor/rules/skill-router.mdc`: Cursor rule adapter.
- `.claude/`: local test workspace data, not required for distribution.
## Config
Copy `skill-router.config.example.json` to `skill-router.config.json` in the
workspace where skills should be organized:
```json
{
"leafRoots": [".claude/skill-leaves"],
"exposedSkillRoot": ".claude/skills",
"routingRoot": ".claude/skill-router/routing"
}
```
For non-Claude layouts, use the same fields with different paths. You can also
set:
- `SKILL_ROUTER_LEAF_ROOTS`
- `SKILL_ROUTER_EXPOSED_ROOT`
- `SKILL_ROUTER_ROUTING_ROOT`
- `SKILL_ROUTER_CONFIG`
- `SKILL_ROUTER_WORKSPACE`
## Claude Code
Install from this repository as a Claude Code marketplace:
```bash
claude plugin marketplace add <repo-url-or-local-path> --scope local
claude plugin install skill-router@skill-router --scope local
```
Restart Claude Code, then run:
```text
/skill-router:organize-skills
```
For local development:
```bash
claude plugin validate plugins/skill-router
claude plugin details skill-router@skill-router
```
## Codex
Codex can install the plugin through the repo marketplace:
```bash
codex plugin marketplace add <repo-url-or-local-path>
codex plugin add skill-router@skill-router
```
Codex can also use the repository skill adapter in
`.agents/skills/skill-router` when this repo is checked into a project. Invoke
the skill explicitly:
```text
$skill-router
```
The skill runs the shared script:
```bash
node scripts/skill-router.mjs scan
node scripts/skill-router.mjs apply
node scripts/skill-router.mjs validate
```
## Gemini CLI
Install the repository as a Gemini CLI extension:
```bash
gemini extensions install <repo-url-or-local-path>
```
Restart Gemini CLI, then run:
```text
/organize-skills
```
For development without reinstalling:
```bash
gemini extensions link <local-repo-path>
```
## Cursor
Cursor reads the project rule at `.cursor/rules/skill-router.mdc`. Add this
repository's rule and script to the project where skills should be organized,
then ask Cursor to use Skill Router or run:
```bash
node scripts/skill-router.mjs scan
node scripts/skill-router.mjs apply
node scripts/skill-router.mjs validate
```
## Workflow
1. Put leaf skills under the configured `leafRoots`.
2. Run `node scripts/skill-router.mjs scan`.
3. Read `routing-review.md` and `skill-inventory.json`.
4. Read leaf bodies only for `Needs Body Review` or category-boundary changes.
5. Write `routing-plan.json`.
6. Run `apply`, `scan`, and `validate`.
## Release Checks
```bash
node --check scripts/skill-router.mjs
node plugins/skill-router/scripts/skill-router.mjs validate
claude plugin validate plugins/skill-router
```
The local test workspace currently contains synthetic skills under `.claude/`
for validating routing behavior. Do not publish those as a user's installed
skill library.