# Skill Route

> Local-first skill routing for agent builders — index SKILL.md bundles, get ranked skill plans with confidence and evidence, and serve them to any agent over MCP.

- **Type:** MCP server
- **Install:** `agentstack add mcp-erichare-skill-route`
- **Verified:** Pending review
- **Seller:** [erichare](https://agentstack.voostack.com/s/erichare)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [erichare](https://github.com/erichare)
- **Source:** https://github.com/erichare/skill-route

## Install

```sh
agentstack add mcp-erichare-skill-route
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🧭 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):

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

Or hands-on, in a checkout:

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

Actual text output

```text
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.

```bash
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):

```bash
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.

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

## How it works

```mermaid
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

```bash
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](https://github.com/erichare)
- **Source:** [erichare/skill-route](https://github.com/erichare/skill-route)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-erichare-skill-route
- Seller: https://agentstack.voostack.com/s/erichare
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.