Skillroute

Built on the Agent Skills open standard. Every bundle SkillRoute indexes is checked against the specification, and the standalone validator doubles as a CI gate for skill authors.

SkillRoute is a free, open-source project by JEStats. The repository is now jestatsio/skillroute; the PyPI and npm package names stay the same, so existing install commands and catalogs keep working.

Most agents choose a skill from a one-line description and hope for the best. SkillRoute treats your skill library like a real corpus: it parses complete SKILL.md bundles — headings, triggers, templates, relationships — ranks them with confidence and source evidence, returns a clarification question instead of a guess when the route is uncertain, and serves the whole thing to any agent over MCP. One SQLite file, no services to run; add the Astra DB backend when you outgrow it.

Install

For Claude Code or Codex, install the plugin. For other agents, install the CLI and run the agent setup command. Node.js 20+ and uv are required for the MCP server; an installed Python skillroute command can replace uv.

Claude Code plugin

claude plugin marketplace add jestatsio/skillroute
claude plugin install skillroute@skillroute-marketplace

Codex plugin

codex plugin marketplace add jestatsio/skillroute
codex plugin add skillroute@skillroute-marketplace

Restart your agent after installing. Both plugins include the MCP server and the same routing skill. Then index your existing skills once:

uvx skillroute dogfood index

Or choose a directory with uvx skillroute index --root ./skills. Ask your agent: “Which of my skills should I use to add pytest coverage to this project?” These are JEStats community marketplace installs; inclusion in an official plugin directory is a separate step.

One-line installer

curl -fsSL https://raw.githubusercontent.com/jestatsio/skillroute/main/scripts/install.sh | bash

Confirms each step before it runs: clones or updates SkillRoute, installs dependencies, builds the MCP server and Skill Atlas, indexes starter skills, then detects your agent clients and offers setup for each one (JSON edits are backed up first). Add -s -- --yes for unattended installs.

From PyPI or npm

uv tool install "skillroute[ui]"     # or: pipx install "skillroute[ui]"
skillroute index --root ./skills
skillroute route "Build an MCP server that exposes routing tools"

Zero-install works too — uvx --from skillroute skillroute route "…". The MCP server is published separately as @skillroute/mcp-server if you want to run it straight from npm.

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 <path> or SKILLROUTE_CATALOG_PATH.

Wire up 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:

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

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

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

dsh plugin --profile web add @skillroute/dsh-plugin

The bundle registers SkillRoute's MCP server through dsh's built-in @deepseek-ai/dsh-mcp-client, giving agents mcp__skillroute__route, mcp__skillroute__search, and mcp__skillroute__inspect_skill. The Python core is zero-install when uv is present (the bridge runs uvx --from skillroute); otherwise pipx install skillroute once. See dsh-plugin/README.md.

What you get

Zero runtime dependencies. Routing, indexing, search, and harness setup are stdlib-only. FastAPI and uvicorn live in the ui extra, so an install that never opens the Skill Atlas never fetches a Rust extension.

Spec compliance

skillroute validate examples/skills               # report
skillroute validate --strict                      # fail on warnings too
skillroute index --root examples/skills --strict  # refuse non-compliant bundles

Spec check (https://agentskills.io/specification): 4 bundles, 0 errors, 0 warnings

See Spec Compliance for the full rule set.

Trust

Spec compliance is a correctness check, not a security one — a bundle can be perfectly valid and still tell your agent to read ~/.aws/credentials. A skill's body is instructions the model obeys, so a skill library is a supply chain, and the nastiest failure is the rug-pull: a bundle you reviewed is edited later, its name and description untouched, and nothing in the index looks different.

toolprint closes that gap. It hashes each bundle — frontmatter and body — into a committed lockfile, and scans the prose for injection patterns:

npx toolprint pin  --skills ./skills     # commit toolprint.lock
npx toolprint scan --skills ./skills     # a body-only edit now fails

SkillRoute gates itself the same way: toolprint.lock pins this repo's own MCP server and example skill library, and CI verifies both on every pull request. See Security.

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.

skillroute ui

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.

skillroute traces list
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; SQLite FTS5 (BM25) for larger local libraries, Astra DB Data API and a LangChain-compatible adapter when you want more.

CLI at a glance

Docs

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

In a checkout, every skillroute … command above becomes uv run skillroute …. See CONTRIBUTING.md for the full dev setup (web UI, MCP server) and the release process, and SECURITY.md for reporting vulnerabilities.

Documentation

Read the documentation for installation, workflows, and reference guides. The documentation source is maintained in this repository.

Build locally with python -m pip install -r docs-requirements.txt and mkdocs build --strict; preview with mkdocs serve. GitHub Pages uses the GitHub Actions source and deploys after changes reach main.