SkillPilot

Universal Agent Skill Router — Route agent skills before LLM inference

Your agent has 1,000 skills. SkillPilot makes sure it uses the right one.

---

Quick Start (3 Steps)

# 1. Clone
git clone https://github.com/RealTapeL/SkillPilot.git && cd SkillPilot

# 2. Setup (install + build + global link)
nvm use && pnpm setup

# 3. Run Demo
pnpm demo

After setup, use globally:

skillpilot index ~/.openclaw/skills
skillpilot route "create a GitHub issue"

---

Overview

The Problem

Current agent frameworks (OpenClaw, Claude Code, Codex, etc.) handle skill selection by putting all skill descriptions into the system prompt and letting the LLM decide. This causes three issues:

Problem	Impact
Slow	Wait 1-5 seconds for LLM to reason about which skill to use
Expensive	Every request includes thousands of tokens of skill descriptions
Inaccurate	More skills = more confusion for the LLM

The Solution

SkillPilot routes skills before LLM inference using fast keyword matching + semantic fallback:

User Query
    ↓
SkillPilot Router (Fast Path: 1-5ms)
    ↓
Semantic Matching (optional, ~20ms with ONNX)
    ↓
Conflict Resolution (tie-breaker for similar skills)
    ↓
Execute Skill OR Inject Context

Total routing time: 1-5ms (library) — vs. 1-5 seconds waiting for LLM.

Note: CLI latency (~200ms) includes Node.js startup. Use as a library for production.

---

Installation

Method 1: Global Install (Recommended)

# Using pnpm (recommended)
pnpm add -g @realtapel/skillpilot

# Or using npm
npm install -g @realtapel/skillpilot

Method 2: Local Development

# Clone repository
git clone https://github.com/RealTapeL/SkillPilot.git
cd SkillPilot

# One-command setup
pnpm setup

# Use local CLI
pnpm cli route "create GitHub issue"

---

Usage

CLI Commands

# Index skills (first time setup)
skillpilot index ~/.openclaw/skills ~/.claude/skills

# Route a query
skillpilot route "create a GitHub issue"
# Output: ✓ github (confidence: 1.00, method: fast, 2ms)

# Explain routing decision
skillpilot explain "send a slack message"

# View statistics
skillpilot stats

# Record feedback
skillpilot feedback correct --wrong slack --right slack-advanced --query "bulk send"

Programmatic Usage

import { SkillRouter, SkillIndex, LocalEmbedProvider } from '@realtapel/skillpilot-core';

const index = new SkillIndex('./index');
const embed = new LocalEmbedProvider();
await embed.initialize();

const router = new SkillRouter(index, embed);
const result = await router.route("create a GitHub issue");

console.log(result.skill?.name);  // "github"
console.log(result.confidence);   // 1.0
console.log(result.latencyMs);    // 2

---

Benchmark Results

Real Results (Raspberry Pi 5, 10 skills, 58 test cases)

============================================================
SkillPilot Test Results
============================================================
Total Tests: 58
Correct: 52
Accuracy: 89.7%
Avg Latency: ~4ms (library) / ~200ms (CLI with Node startup)

Test Coverage:

• 10 skills: github, git, slack, file-read, file-write, docker, npm, python, aws, database
• 58 test cases: exact triggers, semantic matches, and fuzzy queries
• Fast path matches: ~90% of queries

Key improvements:

• Fixed fuzzy matching for queries like "show me the README" → file-read
• Fixed "create a GitHub issue" correctly routes to github (not git)
• Handles partial trigger matches (e.g., "show" matches "show content")

Known limitations:

• "deploy to production" still fails without better semantic model (ONNX)
• File extension handling (e.g., "README.md") needs improvement

Performance Comparison

Metric	LLM-only	SkillPilot
Latency	1000-5000ms	~200ms (CLI) / ~1-5ms (library)
Accuracy	~78%	~90%

---

Architecture

┌─────────────────────────────────────────────┐
│              User Message                    │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│           Platform Adapter                   │
│  OpenClaw | Claude Code | LangChain | CLI   │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│         SkillPilot Core Engine               │
│  ┌──────────┐ ┌──────────┐ ┌──────────────┐│
│  │  Fast    │ │ Semantic │ │   Conflict   ││
│  │  Router  │ │  Router  │ │   Resolver   ││
│  └──────────┘ └──────────┘ └──────────────┘│
│                                              │
│  ┌──────────────────────────────────────┐   │
│  │      Skill Index (SQLite + Vectors)   │   │
│  └──────────────────────────────────────┘   │
└─────────────────────────────────────────────┘

Key Features

Three-Stage Routing

Stage	Time	Purpose
Fast Path	1-5ms	Keyword + trigger phrase matching
Semantic Path	~20ms	Vector similarity (requires ONNX model)
Conflict Resolution	< 1ms	Resolve overlapping skill conflicts

Routing Examples:

"create a GitHub issue" → github (fast path, 2ms)
"show me the README" → file-read (fuzzy match, 3ms)
"deploy to production" → aws (semantic match, 5ms)

⚠️ Configuration Notice: The 89.7% accuracy was achieved with hardRouteThreshold: 0.30 (lower than design value 0.80) to boost match rate. This increases false positive risk. For production, consider using 0.70+ and monitoring feedback.

Conflict-Aware Routing

Automatically detects and resolves conflicts between similar skills (e.g., github vs github-advanced):

$ skillpilot conflicts
Conflict Group A (similarity 0.91):
  github · github-advanced · github-enterprise
  Tip: Add route.prefer_when to disambiguate

Self-Learning

Records routing feedback and automatically adjusts weights:

# Record a correction
skillpilot feedback correct --wrong slack --right slack-advanced --query "bulk send"

---

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build:all

# Run tests
pnpm test

# Run benchmarks
cd benchmarks/python
python test_skillpilot.py

---

Packages

Package	Description	npm
@realtapel/skillpilot-core	Core routing engine	🔗
@realtapel/skillpilot	CLI tool	🔗
@realtapel/skillpilot-claude-code	Claude Code adapter	🔗
@realtapel/skillpilot-langchain	LangChain adapter	🔗

---

License

MIT

---

SkillPilot — Route smarter, not harder.