Agent Skill Router — Intelligent Skill Routing for AI Agents

# Agent Skill Router — Intelligent Skill Routing for AI Agents

<<<<<<< HEAD
**An AI skill routing system that automatically selects and injects the right expertise into your AI's context.** With 978 skills across 10 domains and built-in compression, the router delivers expert knowledge without manual commands.
=======
**An AI skill routing system that automatically selects and injects the right expertise into your AI's context.** With 978 skills across 10 domains and built-in compression, the router delivers expert knowledge without manual commands.
>>>>>>> abcf3580f (feat: add new skill - dry-principle)

```
You → "review this Python code for security issues"
      ↓
skill-router auto-fires → hybrid retrieval (vector + BM25) → archetype/trigger scoring → MMR diversify → LLM ranks (opt) → loads skills
      ↓
Full expert skills injected into context — AI answers as expert reviewer
```

**Key Features:**
<<<<<<< HEAD
- 🎯 **978 Skills** across 10 domains (Agent, CNCF, Coding, Electrical Engineering, Go, Linux, Maker, Programming, Trading, Writing)
=======
- 🎯 **978 Skills** across 10 domains (Agent, CNCF, Coding, Electrical Engineering, Go, Linux, Maker, Programming, Trading, Writing)
>>>>>>> abcf3580f (feat: add new skill - dry-principle)
- 🔄 **Auto-Routing** — tasks automatically match the most relevant skills via hybrid scoring (vector similarity + BM25 + archetype alignment + MMR diversification)
- 🗜️ **SkillCompressor** — reduce token overhead by 28-65%
- ⚡ **Fast** — ~10ms warm, ~3.5s cold responses
- 🔌 **MCP Integration** — works with OpenCode's `route_to_skill` tool
- 🤖 **LLM-Powered Generation** — generate new skills programmatically using local LLMs
- 🛠️ **Quality Fixer** — detect and fix placeholder code in existing skills

---

## Quick Start

### Installation (Interactive Mode - Recommended)

```bash
git clone https://github.com/paulpas/agent-skill-router
cd agent-skill-router
./install-skill-router.sh
```

**What happens:**
- Interactive prompts guide you through API key configuration
- Automatically builds and starts the skill router Docker container
- Optionally integrates with OpenCode or Claude
- Full configuration summary before installation begins

**Full installation instructions:** [Routing System Docs](./agent-skill-routing-system/README.md)

---

## How It Works

The skill router is an **MCP (Model Context Protocol) server** that routes tasks to the most relevant skills using:

1. **Hybrid Retrieval** — Vector similarity + BM25 exact-term matching for candidate retrieval
2. **Archetype & Trigger Scoring** — Query intent alignment and keyword matching boost relevance
3. **MMR Diversification** — Maximum Marginal Relevance ensures diverse, non-redundant results
4. **LLM Ranking (optional)** — Configurable LLM re-ranks top candidates for final selection
5. **Caching & Compression** — Multi-layer cache + SkillCompressor reduces token overhead by 28-65%

**Result:** Only the top 1-3 most relevant skills are loaded per request, saving tokens and improving response quality.

---

## Documentation

| File | Purpose |
|------|---------|
| **[Routing System Docs](./agent-skill-routing-system/README.md)** | Installation, architecture, provider configuration, and request flow |
| **[API Reference](./agent-skill-routing-system/skill-router-api.md)** | Complete API documentation with curl examples for all endpoints |
| **[SKILL_FORMAT_SPEC.md](./SKILL_FORMAT_SPEC.md)** | Formal skill file specification for creating new skills |

---

## Skill Creation

**New to skill creation?** Start here:

**[AGENTS.md](./AGENTS.md)** — Complete guide for creating new skills with:
- Frontmatter requirements
- Content structure templates
- Trigger engineering best practices
- Quality checklist and common pitfalls

---

## Common Questions

**Have questions?** See the **[AGENTS.md](./AGENTS.md)** for skill documentation guidelines.

---

## Domains

| Domain | Count | Focus |
|--------|-------|-------|
| Agent | 262 | AI orchestration, routing, task decomposition |
| CNCF | 173 | Kubernetes, cloud-native, DevOps, service mesh |
| Coding | 410 | Software patterns, security, testing, data science |
| Electrical Engineering | 2 | Hardware design, embedded systems, circuit analysis |
| Go | 12 | Go idioms, concurrency patterns, error handling |
| Linux | 16 | System administration, kernel tuning, security, networking |
| Maker | 3 | DIY projects, IoT, home automation, 3D printing |
| Programming | 7 | Algorithms, frameworks, language references |
| Trading | 89 | Execution, risk management, ML models |
| Writing | 4 | Technical writing, style guidance |
<<<<<<< HEAD
| Coding | 404 | Software patterns, security, testing, data science |
=======
| Coding | 405 | Software patterns, security, testing, data science |
>>>>>>> abcf3580f (feat: add new skill - dry-principle)
| Electrical Engineering | 2 | Hardware design, embedded systems, circuit analysis |
| Go | 12 | Go idioms, concurrency patterns, error handling |
|

... (truncated)