🧭 SkillRoute

Local-first skill routing for agent builders

Index full SKILL.md bundles into a local catalog, route any request to ranked
skills with confidence and evidence, and serve it all to your agents over MCP.

Quick start · Skill Atlas · Agent setup · How it works · Docs

_{Skill Atlas — every skill in your library on one interactive map, with live route previews.}

Why

Most agents choose skills from a one-line description and hope for the best.
SkillRoute treats your skill library like a real corpus:

• Full-bundle indexing — parses complete SKILL.md bundles (headings,
  triggers, templates, relationships), not just frontmatter.
• Explainable routes — every ranked skill carries confidence, reasons, and
  source evidence. Uncertain routes return clarification questions instead of
  guesses.
• Local first — one SQLite file, no services to run. Add the Astra DB
  backend when you outgrow it.

Quick start

One guided line (confirms each step, sets up detected agent clients with
backups):

curl -fsSL https://raw.githubusercontent.com/erichare/skill-route/main/scripts/install.sh | bash

Or hands-on, in a checkout:

uv run skillroute index --root examples/skills
uv run skillroute route "Build an MCP server that exposes routing tools"

Ranked skills:
1. mcp-server-patterns (mcp-server-patterns-99fdd0b3d944c32a) confidence=0.3563
   Build MCP servers with Node and TypeScript using tools, resources, Zod schemas, and stdio transport.
   reason: Matched request terms against skill name, description, tags, or excerpts.
   reason: local-token retrieval returned this skill as a candidate.
   reason: Skill graph relationships provide supporting context.
   evidence[description]: Build MCP servers with Node and TypeScript using tools, resources, Zod schemas, and stdio transport.
   evidence[headings]: MCP Server Patterns; When to Use
2. python-testing (python-testing-19ef6ae9ced445b2) confidence=0.1373
   Test Python applications with pytest fixtures, parametrization, temporary paths, and regression coverage.
   ...

The default catalog lives at .skillroute/catalog.db; point elsewhere with
--catalog <path> or SKILLROUTE_CATALOG_PATH.

Skill Atlas

Your whole library, mapped. Facet nebula, skill graph, and matrix views;
filters for domains, relationship types, orphans, and conflicts; a detail panel
with excerpts and source references; and a route preview bar that highlights
the chosen path through the graph.

uv run skillroute ui

Plug it into your agent

The bundled MCP server exposes three tools over stdio — skillroute.route,
skillroute.search, and skillroute.inspect_skill. One command writes the
config for your client (JSON edits are backed up first):

uv run skillroute mcp config --client claude-code

Supported clients: claude-code · claude-desktop · codex · cursor ·
ibm-bob · vscode · windsurf

Route observability

Every route is a trace you can replay: inputs, candidates, scores, and the
evidence behind each decision. Golden-route evals keep your catalog honest as
it grows.

uv run skillroute traces list
uv run skillroute eval run --fresh --index-root examples/skills --cases examples/evals/golden_routes.json

How it works

flowchart LR
    A["SKILL.md bundles"] --> B["Indexer<br/>parser + metadata review"]
    B --> C[("SQLite catalog<br/>skills · excerpts · graph · traces")]
    C --> D["Router<br/>lexical + retrieval + graph signals"]
    D --> E["CLI"]
    D --> F["Skill Atlas UI"]
    D --> G["MCP server"]
    G --> H["Your agent"]

• Python core — parsing, catalog persistence, hybrid routing, evals, CLI.
• Skill Atlas — FastAPI server + React Flow frontend, bundled into the
  Python wheel.
• MCP server — TypeScript stdio transport around the Python bridge.
• Backends — local token retrieval by default; Astra DB Data API and a
  LangChain-compatible adapter when you want more.

CLI at a glance

Docs

Development

uv sync --extra dev
uv run --extra dev pytest --cov=skillroute
uv run --extra dev ruff check . && uv run --extra dev mypy

See CONTRIBUTING.md for the full dev setup (web UI, MCP
server) and the release process.