Skillroute

🧭 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/skillroute/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/skillroute/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. A .skillroute/catalog.db in the working directory is used instead when one already exists, so existing project catalogs keep working; 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 harness (JSON edits are backed up first):

uv run skillroute harness install claude-code
uv run skillroute harness detect        # what is installed here
uv run skillroute harness list          # everything SkillRoute knows about

Supported harnesses: amp · claude-code · claude-desktop · codex · cursor · gemini-cli · goose · hermes · ibm-bob · opencode · pi · vscode · windsurf · zed

Each one is a single declarative manifest in [harnesses/](harnesses), so adding a new tool is usually a data change with no Python — see [Harness Packs](docs/harnesses.md).

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; SQLite FTS5 (BM25) for

larger local libraries, 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 harness list | Every harness SkillRoute supports, and its modes | | skillroute harness install | Configure a harness to use SkillRoute | | skillroute ui | Launch the Skill Atlas |

Docs

| Guide | | | --- | --- | | [Getting Started](docs/getting-started.md) | Index, route, and inspect in five minutes | | [Harness Packs](docs/harnesses.md) | Supported harnesses, install modes, and how to add one | | [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   # dev includes the `ui` extra
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/skillroute
• License: MIT

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