skill-router

skill-router

Your skill first, the process skill second, gates and memory on the card — before any tool fires.

A hook-driven router for Claude Code. It indexes every skill you have installed by when it applies, ranks them against each prompt in ~80 ms, asks a small model only when the ranking is unsure, and injects a route card before Claude's first action. Enforcement is tiered: hard where a wrong skill is expensive, soft everywhere else. The route follows every sub-agent you dispatch.

> my macbook restarted again last night, can you check why
[skill-router] This is a BROKEN task — 2-step chain.
[skill-router] Chain: mac-doctor → superpowers:systematic-debugging
[skill-router] Invoke step 1/2 now:
▶ mac-doctor  (inherit, in-session)
▶ superpowers:systematic-debugging  (inherit, in-session)
[skill-router] Memory: airbook_crash_root_cause  (read from ~/.claude/projects/.../memory/)
[skill-router] IRON RULE: call Skill(skill="mac-doctor") before any Edit/Write/Task.

Every line is [skill-router]-prefixed, so grep '\[skill-router\]' on a transcript shows exactly what was routed.

Why (v4, September 2026)

An audit of this machine after five months of use:

The routing table could never enumerate the domain skills — they change weekly — and hard-blocking edits on a process skill the model does not value produced workarounds, not compliance. v4 replaces the table with an index, and replaces uniform enforcement with tiers. Full evidence and design: docs/v4-design.md.

How it decides

prompt ──► project route (SKILL.personal.md)          deterministic, wins outright
       ──► enriched index rank (skill_index.json)     ~80 ms, name · use_when · keywords · project aliases
       ──► small-model tie-break (Gemini Flash-Lite)  only below 35 % margin, ~1 s, cached
       ──► path (BROKEN / BUILD / OPERATE) + process leg from the table
       ──► route card: domain skill · process skill · gates · memory · tier

• Index. build_index.py reads every invokable SKILL.md, extracts "use when" triggers and keywords, and a one-time small-model pass adds more — cached per file hash, so the bill grows only when a skill changes. Third-party skill files are never edited.
• Projects. A projects: block maps names to skills, memory files and completion gates. "push deenunlock to testflight" no longer lands on the scrollbook deploy skill because both ship to TestFlight.
• Precision. A winner needs real evidence: a project hit, or a distinctive non-generic token in its name, triggers or keywords. "flow" alone never picks ux-flow.
• Tiers. Hard (edit block until the skill loads) on the BROKEN path and on project routes with gates. Soft elsewhere: the Stop hook asks once, and the answer teaches the router.
• Sub-agents. A PreToolUse hook on Task appends the parent's route to every dispatched prompt; SubagentStart briefs the agent with its paired skills.

Pipeline detail: docs/how-it-works.md.

Install

git clone https://github.com/hussi9/skill-router ~/devpro/skill-router
ln -s ~/devpro/skill-router ~/.claude/skills/skill-router
python3 ~/.claude/skills/skill-router/scripts/install_hooks.py     # wires 6 hook events into ~/.claude/settings.json
python3 ~/.claude/skills/skill-router/scripts/build_catalog.py
python3 ~/.claude/skills/skill-router/scripts/build_index.py --enrich

Optional, for the small-model stage: put GEMINI_API_KEY (or ANTHROPIC_API_KEY) in the environment, or in Doppler (shared/prd) and let scripts/refresh_env.py cache it. Without a key the router is lexical-only and still routes.

Restart Claude Code. The catalog, index and learner rebuild in the background at every session start.

Verify

python3 ~/.claude/skills/skill-router/scripts/doctor.py

Twelve checks: hooks wired, scripts present, no route names an uninstalled skill, catalog and index fresh, model stage status, sub-agent hand-off hook, no expired demotions, agents follow the session model, learned overlay fresh, smoke prompts routed. Then type any non-trivial task in a new session and look for [skill-router] before the first tool call.

A route looked wrong? See the ranking and why:

python3 ~/.claude/skills/skill-router/scripts/index_match.py --all "the prompt"

Measured

tests/calibration.py, 109 curated prompts, lexical stage only (model stage off for determinism):

The calibration set is curated and encodes the author's expectations; read 99.1 % as "the regressions are gone", not as a field rate. The field number is the follow rate the learner computes over live sessions, baseline 17 % on writing-plans under v3.

Customize

• Project routes and projects — SKILL.personal.md: routes: (name → skill, tier, gates) and projects: (aliases, skills, memory files, gates). Prove a route fires: python3 scripts/router.py <<< "your prompt".
• Agent pairings — agent_skills.json, validated against the index at brief time.
• Synonyms and phrases — scripts/index_match.py (SYNONYMS, PHRASES, GENERIC).
• Escape hatches — the user writes [no-router]; the model runs scripts/router_override.py "<reason>".

docs/customizing.md has the long form.

It learns

scripts/learn.py regenerates ~/.claude/skill_router_learned.json every session start — never the repo, never your personal file:

Prompt keywords are logged, never prompt text. SKILL_ROUTER_NO_LEARN=1 logs nothing. Details: docs/self-improvement.md.

Common questions

Will this slow Claude Code down? The lexical stage is ~80 ms. The model stage fires on low-confidence prompts only, ~1 s, cached by prompt hash. Hook timeout is 12 s so a slow network degrades to lexical rather than to a blocked prompt.

Why Gemini inside a Claude tool? claude -p inside a hook re-enters every hook and MCP server on the machine — measured at 3.5 minutes. The classification is ~60 tokens. Provider order is Anthropic Haiku → Gemini Flash-Lite; whichever key works first answers.

Can I turn it off? For one message, write [no-router]. For good, python3 scripts/install_hooks.py --remove.

What about my custom skills? They are exactly what v4 is for. Anything under ~/.claude/skills/, ~/.claude/commands/, project .claude/skills/, and every installed plugin is indexed. Non-invokable catalogs (~/.agent/skills, ~/.composio-skills) are install candidates only.

Where does it log? ~/.claude/skill_usage.log (every Skill call) and ~/.claude/skill_router_log.jsonl (announcements, prompts as keywords, invocations, soft-skips). Both feed the learner; both are hook-mode only, so tests and probes never teach the router.

Documentation

Works with

Project

• CHANGELOG.md — version history
• CONTRIBUTING.md — how to propose changes
• LICENSE — MIT
• bash scripts/check.sh — syntax · unit tests · calibration gate (≥ 95 %) · doctor