skill-router

Right Skill, right Agent, right Model, right Thinking depth — before any tool fires.

One SKILL.md (~300 lines). Auto-loaded by Claude Code. Zero UX. 80% composite routing accuracy / 90% path-only on 20 real prompts (3-run average). Every announcement line is [skill-router]-prefixed so grep can audit your transcript.

$ > add a settings page that writes to the db and emails the user

[skill-router] This touches 3 domains: UI/Frontend, DB schema, Edge function.
[skill-router] Chain: superpowers:writing-plans → frontend-design:frontend-design + db-expert
[skill-router] Models: sonnet · sonnet+sonnet  ·  Thinking: think
[skill-router] Invoke step 1/2 now:

▶ superpowers:writing-plans  (sonnet, in-session)
▶ frontend-design:frontend-design + db-expert  (sonnet, parallel via Agent)

The router announces what it will do before any tool fires. [skill-router] on every line is the testable contract — grep '\[skill-router\]' your transcript and verify what fired matches what was announced.

Every step also writes to ~/.claude/skill_router_log.jsonl. Run python3 scripts/audit-dispatch.py after a week to score whether the router is actually following its own protocol.

Why you'll want this

Claude Code has a skills ecosystem with 2,700+ skills. There's no built-in routing layer.

Claude guesses which skill to use — or ignores them entirely. On a 20-prompt test harness, it picks the wrong skill ~20% of the time, skips skills it decides are "too simple," and makes no attempt to match model cost to task complexity. skill-router replaces that implicit guessing with a deterministic 3-question triage that runs before every non-trivial task.

Three things make the wrong-skill problem worse as you install more skills:

No routing. Claude has no deterministic layer that decides: what is this task? what skill fits? what model is right? Without a routing layer, more skills = more ambiguity.

No catalog maintenance. Your installed skills drift. Ghost entries pile up. The router validates skill existence before blocking on iron-rule enforcement — deadlocks are caught automatically.

No chaining. Multi-domain work needs skills to fan out. "Add Stripe checkout that saves to DB and emails the user" is 4 domains — the router builds and dispatches the chain.

What it actually outputs

Multi-domain BUILD — skills fan out in parallel:

> add stripe checkout — saves order to db, emails confirmation

[skill-router] This touches 4 domains: 3rd-party, DB schema, Edge function, UI/Frontend.
[skill-router] Chain: superpowers:writing-plans → connect-apps + db-expert + frontend-design:frontend-design
[skill-router] Models: sonnet · sonnet+sonnet+sonnet  ·  Thinking: think
[skill-router] Invoke step 1/2 now:

▶ superpowers:writing-plans  (sonnet, in-session)
▶ connect-apps + db-expert + frontend-design:frontend-design  (sonnet, parallel via Agent)

Research → plan → steering meeting — the idea-to-feature pipeline:

> want to add AI spending coach — weekly check-ins, pattern detection,
> personalized nudges. is this worth building? if yes, plan it out.

[skill-router] This touches 3 domains: Research/Strategy, Product planning, Architecture.
[skill-router] Chain: superpowers:brainstorming → superpowers:writing-plans → product-manager + tech-lead
[skill-router] Models: sonnet · sonnet · opus+opus  ·  Thinking: ultrathink
[skill-router] Invoke step 1/3 now:

▶ superpowers:brainstorming    (sonnet, in-session)
▶ superpowers:writing-plans    (sonnet, in-session)
▶ product-manager + tech-lead  (opus, parallel via Agent)

Step 1 researches the idea — prior art, risks, what similar products got wrong.
Step 2 converts that into a structured plan with tasks and open questions.
Step 3 runs a steering meeting: product-manager and tech-lead both read the plan simultaneously on opus — heaviest thinking, before a line of code is touched.

Single-domain OPERATE — safety gate before deploy:

> deploy to production

[skill-router] This is a OPERATE task — 2-step chain.
[skill-router] Chain: superpowers:verification-before-completion → vercel:deploy
[skill-router] Models: sonnet · sonnet
[skill-router] Invoke step 1/2 now:

▶ superpowers:verification-before-completion  (sonnet, in-session)
▶ vercel:deploy  (sonnet, in-session)

The verification gate runs every time before deploy fires — without you remembering to ask.

Install — one curl, 10 seconds

mkdir -p ~/.claude/skills/skill-router
curl -sL https://raw.githubusercontent.com/hussi9/skill-router/main/SKILL.md \
  > ~/.claude/skills/skill-router/SKILL.md

Done. Claude Code auto-loads it on session start. You never invoke it manually. Start a new Claude Code session and type any non-trivial task — the chain announcement fires before any tool runs.

Verify it's working

In a new Claude Code session, type something obviously multi-domain like:

"add user profile page that saves to the database"

You should see Claude announce a chain before reading any files:

[skill-router] This touches 2 domains: UI/Frontend, DB schema.
[skill-router] Chain: superpowers:writing-plans → frontend-design:frontend-design + db-expert
[skill-router] Models: sonnet · sonnet+sonnet  ·  Thinking: think
[skill-router] Invoke step 1/2 now:

▶ superpowers:writing-plans  (sonnet, in-session)
▶ frontend-design:frontend-design + db-expert  (sonnet, parallel via Agent)

If Claude jumps straight into reading files with no [skill-router] lines, the skill didn't load — verify ~/.claude/skills/skill-router/SKILL.md exists and starts with name: skill-router.

Optional — statusline shows live activity

Add the statusline + hook (5 minutes — see docs/customizing.md) to surface routing in real time:

◆ sonnet · ~/myproject · ⎇ main · 🔀 router · ▶ ship-feature 2/4 ✦saved · 🧠 hard · ⚙ frontend-design ✓ · ▓▓░░ 18% · $0.04

Measured

20 real prompts through claude -p (test harness in run_routing_test.sh). 3-run average on Sonnet 4.6, 2026-04-29:

Known stable misroute (same case fails every run):

• Ambiguous "fix X AND add Y" → routes to OPERATE instead of defaulting to BUILD per the ambiguity rule

This is a systematic gap in how Claude follows the routing table — not random variance.

Common questions

Will this slow Claude Code down?
~5 seconds of routing thought before tool calls fire. Saves time overall by avoiding wrong-skill rabbit holes.

Do I need other skills installed first?
No, but the router is most useful with superpowers + a catalog like Antigravity installed. The router still routes correctly on a bare install — it just has fewer specialists to dispatch to.

Can I turn it off temporarily?
Yes — mv ~/.claude/skills/skill-router/SKILL.md ~/.claude/skills/skill-router/SKILL.md.off and restart Claude Code. Move it back to re-enable. There's no global toggle by design (zero UX).

Does this work on claude.ai or only Claude Code?
Claude Code (CLI) is production. The Codex flavor in codex-skill/ is a working draft. Web claude.ai doesn't load skills the same way — not supported.

What about my custom skills?
The router checks ~/.claude/skills/, ~/.agent/skills/, and ~/.composio-skills/ on every task — your custom skills get used automatically when their name or description matches the task signature. See references/catalog-check.md.

How do I add my own routing rules?
Copy SKILL.personal.md to ~/.claude/skills/skill-router/SKILL.personal.md and edit. Project-specific rules layer on top of the universal core (CSS-cascade model). See docs/customizing.md.

Where does it log activity?
~/.claude/skill_usage.log (every Skill fire) and ~/.claude/skill_router_log.jsonl (chain announcements + thinking events). Useful for debugging and for the statusline.

Does it get smarter over time?
Yes — run bash scripts/weekly-analysis.sh (or automate it via launchd/crontab) to surface routing gaps and promote repeated chains to named chains. Named chains bypass LLM triage entirely — faster and 100% consistent. See docs/self-improvement.md.

Self-improvement — the router learns your patterns

Three analysis scripts ship with the repo. Run them weekly and the router improves automatically:

Run all three at once:

bash scripts/weekly-analysis.sh           # report only
bash scripts/weekly-analysis.sh --apply   # also promote repeated chains

Automate it (macOS launchd — runs every Monday at 9am):

REPO="$HOME/path/to/skill-router"
sed -e "s|{{SKILL_ROUTER_PATH}}|$REPO|g" -e "s|{{HOME}}|$HOME|g" \
    "$REPO/setup/launchd-weekly.plist" \
    > ~/Library/LaunchAgents/com.skill-router.weekly-analysis.plist
launchctl load ~/Library/LaunchAgents/com.skill-router.weekly-analysis.plist

Full details, Linux crontab instructions, and what to do when each metric is bad: docs/self-improvement.md.

Documentation

Reference (router consults these at runtime): references/.

Works with

Two flavors

Project

• CHANGELOG.md — version history
• CONTRIBUTING.md — how to propose changes (TL;DR: routing-table corrections welcome, lifecycle features go to a different repo)
• LICENSE — MIT