skill-search

使用关键字搜索、语义搜索或法学硕士支持的任务匹配来查找和检索可用技能。当代理需要发现、搜索技能或将技能与任务智能匹配时使用。支持混合搜索（BM25+语义）、自然语言任务描述、智能技能推荐。

# 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 via Playwright
```

**Agent**: *Reads SKILL.md, confirms fit, executes*

---

**User**: "What skill should I use for transcribing audio?"

**Agent**: *Uses LLM suggest*
```bash
./scripts/skill_search.py suggest "transcribe audio"
```

**Output**:
```
Recommended skills for "transcribe audio":

1. openai-whisper-api — Transcribe audio via OpenAI Audio Transcriptions API (Whisper)
   Confidence: High
   Reason: Task explicitly matches skill purpose

2. sag — ElevenLabs text-to-speech (inverse operation, may be related)
   Confidence: Low
   Reason: Related to audio processing but output not input
```

## Search Index

The skill maintains a local search index at:
- `~/.openclaw/workspace/skills/skill-search/index/skills_index.json` — Skill metadata
- `~/.openclaw/workspace/skills/skill-search/index/embeddings.json` — Semantic embeddings (lazy-loaded)

**Indexing happens automatically** on first semantic search if no index exists.

**Force reindex:**
```bash
./scripts/skill_search.py index
```

## Resources

### scripts/
- `skill_search.py` — Main search interface (keyword/semantic/LLM)
- `indexer.py` — Build/update search index
- `embeddings.py` — Embedding generation (local miniLM)

### index/
- `skills_index.json` — Searchable skill metadata
- `embeddings_cache.json` — Pre-computed embeddings for semantic search

---

## 中文说明

# Skill Search V1.1

使用关键字、语义或 AI 驱动的任务匹配来查找技能。

## 概述

本技能提供三种搜索模式：
1. **关键字搜索**（快速 BM25） — 匹配技能名称与描述
2. **语义搜索**（嵌入向量） — 按含义/概念相似度查找技能
3. **LLM 任务匹配**（AI 驱动） — 描述你的任务，获得技能推荐

## 何时使用

- **开始新任务之前** — 检查是否存在相关技能
- **当用户询问能力时** — 例如"你能用 PDF 做什么？"
- **避免上下文膨胀** — 先找到正确的技能，再仅加载那一个
- **不确定适用哪个技能时** — 使用语义或 LLM 匹配进行模糊匹配

## 搜索模式

### 1. 关键字搜索（快速）
```bash
./scripts/skill_search.py keyword "weather"
./scripts/skill_search.py keyword "pdf"
./scripts/skill_search.py keyword "image generation"
```

### 2. 语义搜索（基于含义）
```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 任务匹配（AI 驱动）
```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. 列出所有技能
```bash
./scripts/skill_search.py list
```

## 使用模式

1. **搜索**：查找符合你需求的技能（关键字/语义/LLM）
2. **预览**：阅读 SKILL.md 元数据（description、triggers）
3. **加载**：如果是正确的技能，阅读完整正文并执行

## 示例工作流

**用户**："我需要生成一些图片"

**代理**：*使用语义搜索*
```bash
./scripts/skill_search.py semantic "generate images AI"
```

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

**代理**：*阅读 SKILL.md，确认契合，执行*

---

**用户**："转录音频应该用什么技能？"

**代理**：*使用 LLM suggest*
```bash
./scripts/skill_search.py suggest "transcribe audio"
```

**输出**：
```
Recommended skills for "transcribe audio":

1. openai-whisper-api — Transcribe audio via OpenAI Audio Transcriptions API (Whisper)
   Confidence: High
   Reason: Task explicitly matches skill purpose

2. sag — ElevenLabs text-to-speech (inverse operation, may be related)
   Confidence: Low
   Reason: Related to audio processing but output not input
```

## 搜索索引

本技能在以下位置维护本地搜索索引：
- `~/.openclaw/workspace/skills/skill-search/index/skills_index.json` — 技能元数据
- `~/.openclaw/workspace/skills/skill-search/index/embeddings.json` — 语义嵌入（惰性加载）

**索引会自动构建** — 若不存在索引，则在首次语义搜索时构建。

**强制重新索引：**
```bash
./scripts/skill_search.py index
```

## 资源

### scripts/
- `skill_search.py` — 主搜索接口（关键字/语义/LLM）
- `indexer.py` — 构建/更新搜索索引
- `embeddings.py` — 嵌入生成（本地 miniLM）

### index/
- `skills_index.json` — 可搜索的技能元数据
- `embeddings_cache.json` — 用于语义搜索的预计算嵌入