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:

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