Es Skill Router

Name: Es Skill Router
Rating: 3.5 (1 reviews)
Author: oldcodeoberyn

By oldcodeoberyn 👁 9 views ▲ 0 votes

OpenClaw plugin: RAG-based skill routing via Elasticsearch semantic search. Reduces token usage by 90%.

GitHub

Install

openclaw plugins install -l

Configuration Example

{
  "plugins": {
    "entries": {
      "es-skill-router": {
        "enabled": true,
        "config": {
          "esUrl": "https://your-cluster.es.cloud.com:9243",
          "esUser": "elastic",
          "esPassword": "your-password",
          "index": "openclaw-skills",
          "topK": 5,
          "minScore": 0.5
        }
      }
    }
  }
}

README

# ES Skill Router

OpenClaw plugin that dynamically filters skills using Elasticsearch semantic search. Reduces token usage by ~90% by only injecting relevant skills into the system prompt.

## How It Works

```
User message → before_prompt_build hook → ES semantic search → Top-K skills → system prompt
```

Instead of loading all 95+ skills into every conversation (costing ~5000 tokens), this plugin searches for the most relevant skills and only injects those. The LLM sees fewer skills, makes better decisions, and costs less.

## Architecture

- **Plugin** (`index.ts`): Registers a `before_prompt_build` hook that intercepts each message, searches ES for relevant skills, and overrides the system prompt with only the matched skills
- **Skill** (`skills/es-vector-skill/`): ES CRUD scripts for managing the skill index, included automatically when the plugin is installed

## Prerequisites

- Elasticsearch cluster with the `.jina-embeddings-v5-text-small` inference endpoint (available on Elastic Cloud)
- Python 3 + `elasticsearch` + `pyyaml` packages (for index management scripts)

```bash
pip3 install elasticsearch pyyaml
```

## Installation

```bash
# 1. Clone this repo
git clone https://github.com/LiJieY/es-skill-router.git
cd es-skill-router

# 2. Install the plugin
openclaw plugins install -l .

# 3. Configure (add to ~/.openclaw/openclaw.json → plugins.entries)
```

### Config

Add to `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "entries": {
      "es-skill-router": {
        "enabled": true,
        "config": {
          "esUrl": "https://your-cluster.es.cloud.com:9243",
          "esUser": "elastic",
          "esPassword": "your-password",
          "index": "openclaw-skills",
          "topK": 5,
          "minScore": 0.5
        }
      }
    }
  }
}
```

Or use environment variables:

```bash
export ES_URL="https://your-cluster:9243"
export ES_USER="elastic"
export ES_PASSWORD="your-password"
```

### Restart

```bash
openclaw gateway restart
```

## Setup: Index Your Skills

After installation, index all installed skills into Elasticsearch:

```bash
# Set connection
export ES_URL="https://your-cluster:9243"
export ES_USER="elastic"
export ES_PASSWORD="your-password"

# Index all skills (auto-discovers from OpenClaw skill directories)
python3 skills/es-vector-skill/scripts/index_skills.py --index openclaw-skills --recreate
```

Output:
```
Found 95 skills
Created index: openclaw-skills
{"success": true, "indexed": 95, "errors": 0}
```

## Verify

Send any message to your agent. Check the gateway logs:

```bash
grep "es-skill-router\|ready.*index" /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log
```

You should see:
```
ready: index=openclaw-skills topK=5 minScore=0.5
"your message..." → [skill1, skill2, skill3, skill4, skill5]
```

## Config Options

| Option | Default | Description |
|--------|---------|-------------|
| `esUrl` | `ES_URL` env | Elasticsearch URL |
| `esUser` | `ES_USER` env | ES username |
| `esPassword` | `ES_PASSWORD` env | ES password |
| `esApiKey` | `ES_API_KEY` env | ES API key (alternative to user/pass) |
| `index` | `openclaw-skills` | ES index name for skill vectors |
| `topK` | `5` | Number of skills to keep |
| `minScore` | `0.5` | Minimum relevance score |
| `enabled` | `true` | Enable/disable the router |

## Re-index After Installing New Skills

```bash
python3 skills/es-vector-skill/scripts/index_skills.py --index openclaw-skills
```

New skills are added incrementally (existing ones are updated).

## Comparison with COS Vectors Approach

| | COS Vectors (Hook) | ES Skill Router (Plugin) |
|---|---|---|
| Hook type | `message:received` (async) | `before_prompt_build` (sync) |
| Timing | 1 message lag | **Same message** |
| Embedding | External API (OpenAI/Ollama) | **ES built-in (jina v5)** |
| Token savings | ~92% | **~92%** |
| Setup | Hook + scripts + COS bucket | **One plugin install** |

## License

MIT

tools