@the-long-ride/skills-router

v0.0.12

Published

18 hours ago

NPM wrapper for Skills Router, the Python-based AI-agent skillset manager

0High
0Medium
0Low

the-long-ride-1406

ai-agent agents agent-skills skills-router skillset mcp codex claude cursor windsurf cline opencode

@the-long-ride/skills-router

NPM/npx wrapper for the Python skills-router CLI.

This package exists so JavaScript-first tools, IDEs, and agent workflows can run Skills Router through npm without vendoring the Python source into the npm package. On first run, the wrapper checks the installed Python package version and installs the matching PyPI release for the wrapper version.

npx @the-long-ride/skills-router --help
npx @the-long-ride/skills-router install ./my-skill.json --all-agents

What This Package Does

Provides the skills-router command through npm/npx.
Uses your local repository source during development when ../src is present.
In published npm usage, installs the matching PyPI package version before launching the Python CLI.
Keeps the npm package small: the real implementation lives in the skills-router Python package.

Requirements

Node.js 16 or newer.
Python 3.10 or newer available as python3, python, or py.
pip available for the selected Python interpreter.

Package Links

npm package: https://www.npmjs.com/package/@the-long-ride/skills-router
PyPI package: https://pypi.org/project/skills-router/
Source repository: https://github.com/the-long-ride/skills-router

Full Skills Router README

The rest of this README mirrors the root project documentation for skills-router.

Skills Router

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.
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>.
Supports the default all-agent host set: antigravity, antigravity-cli, antigravity-ide, codex, 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

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

# 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

# Reconcile already indexed packages and routes
skills-router index --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

# 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

# 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

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

Command Surface

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, 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 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 inspect <tool_id>
/skills-router audit --tool <tool_id>
/skills-router watch --once

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
parse_slash_command
run_slash_command
install_tool
uninstall_tool
index_routes
refine_routes
route_task
list_tools
inspect_tool
watch_once

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

Render target-specific bridge text with:

skills-router prompt --target codex
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"
}

Release Automation

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

[x] Core install review pipeline.
[x] Agent Bridge for popular AI-agent hosts.
[x] Full-package install with generated route plans.
[x] One-time all-agent installs with target-aware routing.
[x] /skills-router index reconciliation and conflict recommendations.
[x] /skills-router refine discovery and route refinement.
[x] Dynamic route lookup through MCP and CLI.
[x] Registry Watch daemon with trust degradation alerts.
[ ] Route-choice persistence API for applying human selections.
[ ] pgvector-native production migration.
[ ] Dashboard for routing history, audit logs, and conflict decisions.

License

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

Developed by the-long-ride.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@the-long-ride/skills-router

What This Package Does

Requirements

Package Links

Full Skills Router README

Skills Router

Why skills-router?

What It Does

What It Does Not Do

Architecture

Core Workflow

Install

Quick Start

Command Surface

One-Time All-Agent Installs

Routing Model

Refine And Discovery

Slash Commands For Agents

MCP Tool Surface

Supported Agent Hosts

Configuration

Release Automation

Roadmap

License