Skill Route

🧭 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.

[](https://github.com/erichare/skill-route/actions/workflows/ci.yml) [](LICENSE) [](pyproject.toml) [](docs/mcp-server.md)

[Quick start](#quick-start) · [Skill Atlas](#skill-atlas) · [Agent setup](#plug-it-into-your-agent) · [How it works](#how-it-works) · [Docs](#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"

Actual text output

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 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["Indexerparser + metadata review"]
    B --> C[("SQLite catalogskills · excerpts · graph · traces")]
    C --> D["Routerlexical + 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

| Command | What it does | | --- | --- | | skillroute index --root | Parse and index SKILL.md bundles | | skillroute route "" | Ranked skills with confidence and evidence | | skillroute search "" | Hybrid search across the catalog | | skillroute inspect | Metadata, relationships, excerpts, sources | | skillroute traces list | Inspect past routing decisions | | skillroute eval run | Golden-route evals against expected outcomes | | skillroute backend status | Retrieval backend health | | skillroute mcp config --client | Configure your agent client | | skillroute ui | Launch the Skill Atlas |

Docs

| Guide | | | --- | --- | | [Getting Started](docs/getting-started.md) | Index, route, and inspect in five minutes | | [Agent Setup](docs/agent-setup.md) | Wire SkillRoute into your agent clients | | [MCP Server](docs/mcp-server.md) | Tools, transport, and configuration | | [Skill Atlas UI](docs/skill-atlas.md) | The graph explorer in depth | | [Route Observability](docs/route-observability.md) | Traces and debugging routes | | [Golden Route Evals](docs/evals.md) | Keep routing quality measurable | | [Metadata Overlays](docs/metadata-overlays.md) | Curate tags without editing sources | | [Astra Data API Backend](docs/astra-backend.md) | Remote vector retrieval | | [Changelog](CHANGELOG.md) | Release history |

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](CONTRIBUTING.md) for the full dev setup (web UI, MCP server) and the release process.

---

MIT © Eric Hare — for people who take their skill libraries seriously.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: erichare
• Source: erichare/skill-route
• License: MIT

Install and usage instructions live in the source repository linked above.