# SkillRoute

> Local-first semantic skill routing for AI agents that indexes SKILL.md bundles, stores metadata in SQLite, and returns ranked skill plans with confidence scores and routing traces.

SkillRoute is an open-source, local-first skill routing library for AI agent builders, created by Eric Hare and released under the MIT License. It indexes full `SKILL.md` bundles, persists reviewed metadata in a local SQLite catalog, and returns ranked skill plans complete with confidence scores, evidence, score breakdowns, and clarification prompts when routing is uncertain. The project was created in June 2026 and is actively maintained on GitHub.

## What It Is

SkillRoute addresses a gap in how agents select capabilities: most agents pick skills from a short description, while SkillRoute provides a real catalog with parsed skill bundles, facets, graph relationships, backend retrieval, golden-route evaluations, and inspectable routing traces. It is a Python-core tool with a TypeScript MCP server, a local web UI called Skill Atlas, and retrieval adapters for both local and remote backends.

## Architecture

SkillRoute is composed of several layers working together:

- **Python core** — parsing, catalog persistence, routing logic, retrieval adapters, evals, and CLI
- **Skill Atlas UI** — a local FastAPI server paired with a React Flow/Vite frontend for exploring the skill graph, facets, relationships, route previews, and source evidence
- **TypeScript MCP server** — local stdio transport wrapping the Python bridge, exposing `skillroute.route`, `skillroute.search`, and `skillroute.inspect_skill` tools
- **Retrieval adapters** — local token backend by default, with optional Astra DB Data API and LangChain-compatible adapter contracts
- **SQLite catalog** — stores skills, excerpts, relationships, backend refs, and route traces at `.skillroute/catalog.db`

## Routing Capabilities

The hybrid routing engine combines lexical metadata, local/remote retrieval, repository context, and skill graph signals to select the best skill for a given task. Key capabilities include:

- Ranked skill plans with confidence scores and evidence breakdowns
- Clarification prompts when the route is ambiguous
- Trace inspection for full observability into routing decisions
- Golden-route evaluations for testing routing quality against known-good cases
- CLI commands for indexing, routing, search, metadata review, backend status, and trace inspection

## Agent Client Integration

SkillRoute ships with a one-line installer and MCP configuration support for multiple agent clients. The `skillroute mcp config` command supports IBM Bob, Codex, Claude Code, VS Code, Windsurf, and Cursor, automatically detecting installed clients and offering to configure each with config file backups.

## Current Status

The repository was created on June 25, 2026, and last updated June 30, 2026, indicating very recent and active development. The project is MIT-licensed, free to use, and hosted publicly on GitHub. Documentation covers getting started, agent setup, the Astra Data API backend, metadata overlays, route observability, the Skill Atlas UI, the MCP server, golden route evals, and a roadmap for future development.

## Features
- Local-first SQLite skill catalog
- Hybrid routing over lexical metadata, retrieval, repo context, and graph signals
- Ranked skill plans with confidence scores and evidence
- Clarification prompts for uncertain routes
- Inspectable routing traces
- Golden-route evaluations
- Skill Atlas local graph UI (React Flow/Vite)
- TypeScript MCP server with route, search, and inspect_skill tools
- Optional Astra DB Data API retrieval backend
- LangChain-compatible adapter contracts
- CLI for indexing, routing, search, metadata review, and evals
- MCP config support for Claude Code, Cursor, VS Code, Windsurf, Codex, IBM Bob
- One-line installer with agent client auto-detection

## Integrations
Astra DB Data API, LangChain, Claude Code, Cursor, VS Code, Windsurf, Codex, IBM Bob, FastAPI, React Flow, Vite

## Platforms
WEB, API, VSC_EXTENSION, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/erichare/skill-route
- Documentation: https://github.com/erichare/skill-route/blob/main/docs/getting-started.md
- Repository: https://github.com/erichare/skill-route
- EveryDev.ai: https://www.everydev.ai/tools/skillroute