skill-search

# Skill Search V1.1

Find skills using keyword, semantic, or AI-powered task matching.

## Overview

This skill provides three search modes:
1. **Keyword Search** (Fast BM25) — Match skill names and descriptions
2. **Semantic Search** (Embeddings) — Find skills by meaning/concept similarity
3. **LLM Task Matching** (AI-powered) — Describe your task, get skill recommendations

## When to Use

- **Before starting a new task** — check if a relevant skill exists
- **When user asks for capabilities** — "what can you do with PDFs?"
- **To avoid context bloat** — find the right skill first, then load only that one
- **When unsure which skill applies** — use semantic or LLM matching for fuzzy matches

## Search Modes

### 1. Keyword Search (Fast)
```bash
./scripts/skill_search.py keyword "weather"
./scripts/skill_search.py keyword "pdf"
./scripts/skill_search.py keyword "image generation"
```

### 2. Semantic Search (Meaning-based)
```bash
./scripts/skill_search.py semantic "automate web browsing"
./scripts/skill_search.py semantic "create images with AI"
./scripts/skill_search.py semantic "search my past conversations"
```

### 3. LLM Task Matching (AI-powered)
```bash
./scripts/skill_search.py suggest "I need to transcribe a podcast episode"
./scripts/skill_search.py suggest "Help me generate product photos"
./scripts/skill_search.py suggest "Search through my old emails"
```

### 4. List All Skills
```bash
./scripts/skill_search.py list
```

## Usage Pattern

1. **Search**: Find skills matching your need (keyword/semantic/LLM)
2. **Preview**: Read SKILL.md metadata (description, triggers)
3. **Load**: If it's the right skill, read full body and execute

## Example Workflows

**User**: "I need to generate some images"

**Agent**: *Uses semantic search*
```bash
./scripts/skill_search.py semantic "generate images AI"
```

**Output**:
```
Top matches (semantic):
1. openai-image-gen (0.87) — Batch-generate images via OpenAI Images API
2. browser (0.65) — Control web browser v...

# skill-search

Find and discover available skills without loading them all into context.

## The Problem

Every skill you load into an agent's context consumes tokens and attention. Loading 10+ skills at once clutters the prompt and degrades performance.

## The Solution

Keep only `skill-search` loaded. When you need a specific capability, search first, then load just that skill.

## Installation

Copy this folder into your agent's skills directory:

```bash
# For OpenClaw agents
cp -r skill-search ~/.openclaw/workspace/skills/

# Or wherever your agent loads skills from
```

## Usage

### From the Agent

When the agent receives a task, have it run:

```bash
./scripts/skill_search.py "weather"
```

This finds relevant skills without loading them into context.

### From Command Line

```bash
# Search for skills matching a keyword
./scripts/skill_search.py "pdf"

# List all available skills
./scripts/skill_search.py --list-all

# Output as JSON (for scripting)
./scripts/skill_search.py "image" --json
```

## Workflow

1. **User asks**: "I need to generate some images"
2. **Agent runs**: `skill_search.py "image"`
3. **Agent sees**: `openai-image-gen` — Batch-generate images via OpenAI Images API
4. **Agent loads**: Only `openai-image-gen/SKILL.md` and uses it

Result: One skill in context instead of ten.

## How It Works

The script searches:
- System skills: `/usr/local/lib/node_modules/openclaw/skills/`
- User skills: `~/.openclaw/workspace/skills/`

It parses `SKILL.md` frontmatter (name, description) to build an index without loading file contents.

## Files

- `SKILL.md` — Skill definition (loaded by agent)
- `scripts/skill_search.py` — Search executable
- `README.md` — This file

## License

MIT (or wherever this ends up)