Skills Router

Version License Author Build Status

English | Español | 简体中文 | 日本語 | Deutsch | Français

skills-router is the CLI command and PyPI package name. The npm wrapper package is @the-long-ride/skills-router.

Skills Router is an AI-agent skillset manager. It reviews, registers, discovers, indexes, compares, and routes AI-agent skills/plugins so a host agent can use the right capability without silently taking over package resources.

Skills Router is not a general package manager. It owns metadata, decisions, audit logs, and routing state. Package files, virtual environments, IDE extensions, and host-agent skill directories stay owned by the tool that installed them.

Why skills-router?

AI-agent skills are useful, but they get scattered across CLIs, IDEs, MCP servers, global folders, workspace folders, and host-specific package managers. That makes it hard to answer simple questions: which skill should this agent use, who approved it, where is it active, and what happens if another package overlaps with it?

skills-router gives agents one shared control plane for that problem. It lets you install or discover skills once, review them through trust and behavior checks, and route each agent to the right capability without copying package files or stuffing huge route tables into prompts. The package manager still owns package resources; Skills Router owns the decisions, metadata, audit trail, and routing layer.

What It Does

• Reviews complete skill/plugin manifests through trust, dependency, semantic, capability, and health checks.
• Analyzes npm and GitHub source links, builds evidence packets, and infers conservative Skills Router manifests when a repo does not provide one.
• Stores approved package metadata in a Brain Index.
• Writes skills-router.json rules that host agents can query through MCP or CLI.
• Installs a skill once for all configured AI-agent hosts with --all-agents or /skills-router install <package> for all agents.
• Supports narrowed all-agent installs with target lists such as --agent-target codex,cursor.
• Enforces target-aware routing when agents call route_task or skills-router route --target <agent>.
• Shows current metadata, routing, and configured skill-folder paths with skills-router status.
• Supports the default all-agent host set: antigravity, antigravity-cli, antigravity-ide, codex, codex-ide, claude, hermes-agent, opencode, cline, cursor, and windsurf.
• Treats partial installs as selective route activation, not partial package extraction.
• Removes Skills Router-owned metadata/routing on uninstall, then re-indexes the remaining route surface.
• Reconciles routes with /skills-router index.
• Discovers externally installed workspace/global skills with /skills-router refine.
• Scans shared and host-specific workspace/global skill directories, including nested system skill folders.
• Keeps newly discovered external routes at needs_selection until the human confirms activation.
• Publishes release descriptions from the matching CHANGELOG.md section on tag pushes, with package links appended by CI.

What It Does Not Do

• It does not delete package-owned files, repositories, virtual environments, or IDE/plugin resources.
• It does not replace pip, npm, IDE extension managers, or host-agent plugin managers.
• It does not auto-approve trust warnings, dependency conflicts, duplicate routes, or unknown behavior unless the human explicitly says to approve risk.
• It does not inject large route tables into agent prompts. Agents should query Skills Router dynamically.

Architecture

flowchart LR
    Human[Human] --> Host[AI agent host]
    Host --> Bridge[Agent Bridge]
    Host --> MCP[MCP stdio server]
    Host --> CLI[CLI]

    Bridge --> Parser[Slash parser]
    Parser --> Executor[Bridge executor]
    MCP --> Executor
    CLI --> Commands[Strict commands]

    Commands --> Install[Install pipeline]
    Executor --> Install
    Commands --> Reconcile[Index and refine]
    Executor --> Reconcile
    Commands --> Lookup[Route lookup]
    Executor --> Lookup
    Commands --> Remove[Uninstall metadata]
    Executor --> Remove

    Install --> Resolver[Registry resolver]
    Resolver --> Trust[Trust gate]
    Trust --> Deps[Dependency resolver]
    Deps --> Semantic[Semantic evaluator]
    Semantic --> Capability[Capability checker]
    Capability --> WG[Workspace/global prompt]
    WG --> Health[Health check]

    Reconcile --> Discovery[Skill discovery]
    Discovery --> SkillDirs[Workspace/global skill dirs]
    Discovery --> GlobalIndex[Global Skills Router index]
    Reconcile --> Conflict[Conflict detector]

    Install --> Store[(Brain Index)]
    Reconcile --> Store
    Conflict --> Routes[(skills-router.json)]
    Lookup --> Routes
    Remove --> Store
    Remove --> Routes
    Remove --> Lock
    Remove --> Audit
    Install --> Lock[(Lockfile)]
    Install --> Audit[(Audit log)]

Core Workflow

flowchart TD
    A[Human asks an AI agent] --> B{Request shape}
    B -->|/skills-router install pkg for me| C[Parse slash request]
    B -->|MCP structured call| D[Call MCP tool]
    B -->|Strict CLI| E[Run command]

    C --> F[Resolve package or manifest]
    D --> F
    E --> F
    F --> G[Trust and dependency checks]
    G -->|Hard reject| H[Stop and summarize]
    G -->|Review needed| I[Ask human]
    I -->|Cancel| H
    I -->|Approve| J[Semantic and capability comparison]
    G -->|Safe| J
    J -->|Overlap| K[Recommend route choice]
    K --> L[Human selects routing]
    J -->|No conflict| M[Persist metadata]
    L --> M
    M --> N[Write routing and lockfile]
    N --> O[Health check]
    O -->|Fail| P[Clean Skills Router state]
    O -->|Pass| Q[Audit and short summary]

    R[Host package manager changes files] --> S["/skills-router index"]
    T[External skill appears] --> U["/skills-router refine"]
    S --> V[Refresh routes and mark stale]
    U --> W[Discover and import metadata]
    V --> X[Recommend route decisions]
    W --> X

Install

# Core local install
pip install -e .

# Optional real embedding support
pip install -e ".[ml]"

# Optional pgvector backend
pip install -e ".[pgvector]"

# Run through npm/npx
npx @the-long-ride/skills-router --help

Note: The pgvector backend is experimental and not recommended for production use.

The default storage backend is JSON-backed local memory under ~/.skills-router. A local Node wrapper is available in skills-router-npx/ for npx and IDE workflows; see GUIDELINE.md.

Quick Start

# Review and register a local manifest
skills-router install examples/sample_manifests/weather_tool.json --scope global

# Review and register by registry package name
skills-router install writer-pack --package-type skillset --scope workspace:codex-local

# Analyze arbitrary source links without installing
skills-router analyze https://github.com/owner/repo --json
skills-router analyze https://www.npmjs.com/package/@scope/writer-pack --json

# Infer a manifest from a source link, then run the normal review pipeline
skills-router install https://github.com/owner/repo --infer --dry-run --explain --json
skills-router install https://www.npmjs.com/package/@scope/writer-pack --infer --json

# Install once and make routes visible to all configured AI-agent hosts
skills-router install writer-pack --package-type skillset --all-agents --json

# Install once but expose routes only to selected agent hosts
skills-router install writer-pack --package-type skillset --all-agents --agent-target codex,cursor --json

# Install the full package but leave routes inactive until selection
skills-router install writer-pack --package-type skillset --routing-mode selective_routes --scope workspace:codex-local --json

# Preview review decisions without writing state
skills-router install writer-pack --dry-run --explain --json

# Remove Skills Router metadata/routing only
skills-router uninstall writer-pack --json
skills-router uninstall writer-pack --dry-run --json

# Reconcile already indexed packages and routes
skills-router index --json
skills-router index --dry-run --json

# Discover workspace/global host-agent skills and refine routes
skills-router refine --json
skills-router refine writer-pack engram --json
skills-router refine --workspace-scope workspace:codex-local --json
skills-router refine --dry-run --json

# Ask Skills Router which route matches a task for the current host
skills-router route "draft article about release notes" --scope workspace:codex-local --target codex --json

# Show metadata paths, configured skill paths, and routing counts
skills-router status --json

# Let an AI-agent host execute a human slash request
skills-router chat "/skills-router install writer-pack for me" --target codex --agent-id codex-local --json
skills-router chat "/skills-router install writer-pack for all installed agents" --target codex --agent-id codex-local --json
skills-router chat "/skills-router refine writer-pack engram" --target codex --agent-id codex-local --json

# Expose Skills Router through stdio JSON-RPC
skills-router mcp

# Connect detected AI-agent hosts through global Skills Router skills
skills-router connect --dry-run
skills-router connect

# Render only bridge instructions for a host
skills-router prompt --target codex
skills-router prompt --list

Command Surface

Command	Purpose
analyze <npm-or-github-source>	Read bounded source evidence and infer a reviewable Skills Router manifest without installing.
install <manifest-or-package-or-source>	Resolve or infer, review, register, and route a package.
index	Rebuild indexed vectors/routes and detect conflicts or stale routes.
refine [skillset ...]	Discover external skills, import metadata, and reconcile routes.
route <task>	Query active or review-needed routes for a task.
activate <tool_id>	Activate routes for a tool, applying human conflict selections.
uninstall <tool_id>	Remove Skills Router-owned metadata/routing only.
list	List indexed tools.
status	Show metadata paths, configured skill paths, and route counts.
inspect <tool_id>	Print one Brain Index entry.
audit	Query audit events.
history	Show recent audit events and routing history.
conflicts	List detected routing conflicts with human-choice options.
resolve	Interactively resolve routing conflicts (--dry-run, --yes, --json).
watch	Run Registry Watch once or as a daemon.
connect	Write managed global Skills Router skills for detected AI-agent hosts.
prompt	Render host-specific bridge instructions.
chat	Parse and execute chat-shaped /skills-router requests.
mcp	Run the local stdio JSON-RPC tool server.

Dry Run

Every write-capable command supports a no-write path:

skills-router install writer-pack --dry-run --json
skills-router uninstall writer-pack --dry-run --json
skills-router index --dry-run --json
skills-router refine --dry-run --json
skills-router watch --once --dry-run --json
skills-router connect --dry-run

Dry-run responses include dry_run: true. For MCP, pass dry_run: true to write-capable tools such as install_tool, uninstall_tool, index_routes, refine_routes, and watch_once.

One-Time All-Agent Installs

All-agent installs are a core workflow:

skills-router install writer-pack --package-type skillset --all-agents --json

The package is still registered once in Skills Router. The generated routes are global, and each configured host reaches them through MCP or the CLI bridge. Skills Router owns metadata and routing only; package resources remain owned by the host package manager or skill installer.

Default all-agent targets:

antigravity, antigravity-cli, antigravity-ide, codex, codex-ide, claude,
hermes-agent, opencode, cline, cursor, windsurf

Use --agent-target when a skill should apply to only part of that set:

skills-router install writer-pack \
  --package-type skillset \
  --all-agents \
  --agent-target codex,cursor \
  --json

When a target list is stored, route lookup respects it only when the caller identifies the current host:

skills-router route "draft release notes" --target codex --json
skills-router route "draft release notes" --target cursor --json

For chat-shaped requests, agents can use:

/skills-router install <package> for all installed agents

Routing Model

Skills Router separates package presence from agent activation:

• Package presence: the host package manager installs or updates the full package.
• Brain Index: Skills Router stores manifest, trust, dependency, vector, behavior, and scope metadata.
• Routing: Skills Router writes skills-router.json packages and rules.
• Selection: route conflicts and externally discovered skills use needs_selection until the human confirms activation.
• Lookup: agents call MCP route_task or skills-router route with their target instead of reading route files directly.
• Stale routes: index marks missing packages missing_from_index; it does not delete package files.

Refine And Discovery

skills-router refine closes the gap where a human installs skills outside the workspace, for example through npx, a host-agent skill installer, or a global Codex skill directory.

Discovery sources:

• Workspace skill dirs: .agents/skills plus host-specific dirs such as .codex/skills, .claude/skills, .cline/skills, .cursor/skills, .windsurf/skills, .opencode/skills, .agent/skills, .antigravity/skills, .hermes/skills, and .kiro/skills
• Global skill dirs: $CODEX_HOME/skills, ~/.codex/skills, and the matching host-specific global skill dirs
• Nested skill folders, including .system/.../SKILL.md
• Global Skills Router state from global_data_dir

Blank refine discovers all visible installed skills. Named refine discovers and reports only matching skillsets while comparing them against the visible route surface. Chat-shaped /skills-router refine assigns workspace-discovered routes to workspace:<agent-id> while still comparing against all visible scopes.

Slash Commands For Agents

The Agent Bridge accepts natural human requests and turns them into strict operations:

/skills-router install <package> for me
/skills-router install <package> for all agents
/skills-router install <package> globally dry run
/skills-router analyze <npm-or-github-link>
/skills-router install <npm-or-github-link> for me
/skills-router install <package> skillset only needed skills for me
/skills-router uninstall <tool_id>
/skills-router index
/skills-router refine
/skills-router refine <skillset> <skillset>
/skills-router route <task>
/skills-router list
/skills-router status
/skills-router inspect <tool_id>
/skills-router audit --tool <tool_id>
/skills-router watch --once
/skills-router activate <tool_id>
/skills-router history
/skills-router conflicts
/skills-router resolve --dry-run --json

The bridge defaults install scope to workspace:<agent-id> unless the human says global. for all agents means one global install for the default all-agent target set; custom --agent-target lists are enforced by target-aware route lookup. The parser removes filler words such as for me and returns human_summary for short agent replies.

MCP Tool Surface

skills-router mcp exposes:

• get_agent_prompt
• get_router_status
• parse_slash_command
• run_slash_command
• analyze_package_source
• install_tool
• uninstall_tool
• index_routes
• refine_routes
• route_task
• list_tools
• inspect_tool
• watch_once
• resolve_conflict

Use run_slash_command for human chat text. Use the structured tools only when the host already has clean arguments. MCP content text is intentionally compact; full machine-readable data stays in structuredContent.

Structured MCP install calls can pass all_agents: true and optional target_agents. Structured route calls can pass target so stored target lists are enforced for the calling host.

Supported Agent Hosts

Target	Instruction locations
antigravity	.agent/rules/skills-router.md, AGENTS.md
antigravity-cli	.agent/rules/skills-router.md, AGENTS.md
antigravity-ide	.agent/rules/skills-router.md, .antigravity/rules/skills-router.md, AGENTS.md
codex	AGENTS.md
codex-ide	AGENTS.md
cline	.clinerules/skills-router.md, AGENTS.md
cursor	.cursor/rules/skills-router.md, AGENTS.md
kiro	.kiro/steering/skills-router.md, AGENTS.md
claude	CLAUDE.md, .claude/commands/skills-router.md
github-copilot	.github/copilot-instructions.md, AGENTS.md
opencode	AGENTS.md, .opencode/agent/skills-router.md
hermes-agent	SOUL.md, AGENTS.md
windsurf	.windsurf/rules/skills-router.md, AGENTS.md

Connect detected AI-agent hosts with:

skills-router connect --dry-run
skills-router connect

connect --dry-run scans supported AI-agent global skill folders and agent home folders, then previews the managed skills-router/SKILL.md files it would write. connect writes one managed global skill per detected folder and updates the same managed block on later runs, so new agents can be detected without duplicating existing bridge files. If no supported global agent folder is found, the command fails with the candidate folders it checked.

Render only target-specific bridge text with:

skills-router prompt --target codex
skills-router prompt --target codex-ide
skills-router prompt --target cursor
skills-router prompt --target windsurf
skills-router prompt --target codex --detail full

The default prompt is compact so persistent agent instructions cost fewer tokens. Use --detail full only when generating docs or debugging an integration.

Configuration

~/.skills-router/config.json can override SkillsRouterConfig fields such as:

{
  "storage_backend": "memory",
  "workspace_root": "/path/to/workspace",
  "workspace_skill_dirs": [".agents/skills", ".codex/skills", ".cursor/skills"],
  "global_skill_dirs": ["$CODEX_HOME/skills", "~/.codex/skills", "~/.cursor/skills"],
  "pgvector_dsn": "postgresql://user:pass@localhost:5432/skills_router"
}

Note: The pgvector backend is experimental and not recommended for production use.

The repository CI validates Python, the Node wrapper, and package builds. On tag pushes, the workflow can publish the npm wrapper and then create or update the GitHub release. The release description is generated from the matching CHANGELOG.md entry and appends links to:

• the tag-specific changelog
• the PyPI package: https://pypi.org/project/skills-router/
• the npm package: https://www.npmjs.com/package/@the-long-ride/skills-router

Roadmap

• Rollback & Undo — Revert a skill to its previous version with audit-trail support. The rollback/ module scaffold exists; wire it to the Brain Index and audit log.
• Skill Health Monitoring — Continuous monitoring of installed skills (missing files, broken imports, crashed MCP servers). Auto-quarantine unhealthy skills and surface status through skills-router status --health. Builds on the existing health_check layer and live_signal_fetcher daemon.
• Permission Enforcement — Enforce declared permissions (filesystem: read_workspace, arbitrary_code_execution, etc.) at invocation time through a sandbox layer in the MCP server. Currently permissions are declared but not enforced.
• Semantic Skill Search — skills-router search <query> to discover skills by semantic similarity using existing Brain Index embeddings. Enables discovery beyond exact routing-rule matches.
• Skill Signing & Verification — Sigstore/cosign-based manifest signing with verification on install. Extends trust scoring with cryptographic provenance for supply-chain security.
• HTTP API Mode — skills-router serve --http to expose the same tool surface over HTTP alongside the existing stdio MCP server. Enables remote agent access, web dashboards, and non-MCP integrations.
• Skill Scoring Transparency — skills-router inspect <tool_id> --explain to show the trust-score breakdown: contributing factors, evidence sources, and scoring weights. Builds confidence in automated routing decisions.
• Audit Log Retention & Rotation — Configurable retention (audit_retention_days) with automatic rotation. The audit log currently grows unbounded.
• pgvector-native production migration.

License

This project is licensed under the GNU General Public License (GPLv3).

Developed by the-long-ride.