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's resident cost is roughly constant (only the category descriptions
stay in context); a flat skill library's resident cost grows with the number of
skills. So the router pays off in proportion to library size and to how the host
loads skills. Benchmarked on the Claude Code CLI (see bench/):

• Use the router for large libraries (hundreds to thousands of skills), long
  multi-turn sessions, or hosts that load full skill bodies into context. In
  those cases the constant-cost router clearly beats a linearly-growing flat list.
• For a small library on a host that already lazy-loads skill bodies (like
  Claude Code), the native skill system is usually enough — below a few hundred
  short-description skills the per-turn saving (~8%) is offset by the extra
  routing step (invoke router, then read the leaf). The router is then mostly a
  curation/disambiguation aid, not a token win.

See docs/benchmark-findings.md for the full methodology and the accuracy/token 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:

{
  "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:

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:

/skill-router:organize-skills

For local development:

claude plugin validate plugins/skill-router
claude plugin details skill-router@skill-router

Codex

Codex can install the plugin through the repo marketplace:

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:

$skill-router

The skill runs the shared script:

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:

gemini extensions install <repo-url-or-local-path>

Restart Gemini CLI, then run:

/organize-skills

For development without reinstalling:

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:

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

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.