skill-seo

优化您的 ClawHub 技能以获得最大的可发现性。分析和重写矢量搜索排名的 SKILL.md 描述、建议关键字覆盖范围、检查竞争对手的定位并计划更新节奏。当您想要“提高技能 SEO”、“获得更多下载”、“优化技能描述”、“在搜索中不显示技能”、“提高技能可见性”、“clawhub 排名”、“技能营销”、“技能发现”、“为什么没有人找到我的技能”、“技能描述优化”、“发布策略”、“技能元数据”、“在 clawhub 上获得推荐”时使用。适用于任何技能文件夹 - 只需将其指向您的 SKILL.md 即可。

# Skill SEO Optimizer 🔍

Get your ClawHub skill found. This skill analyzes your SKILL.md and optimizes it for ClawHub's vector search, explore rankings, and agent auto-discovery.

## Quick Start

```
Optimize my skill for ClawHub: [path/to/skill/SKILL.md]
```

The agent will audit your skill and output an optimized version.

## How ClawHub Discovery Works

Skills are found through three channels. Each needs different optimization:

### Channel 1: `clawhub search` (Vector Search) — 70% of discovery

ClawHub uses **semantic vector search** on the `description` field in YAML frontmatter. This is NOT keyword matching — it's meaning matching.

**What gets indexed:** Only the `description` field.
**What does NOT get indexed:** The markdown body, scripts, references, filenames.

**Optimization rules:**

1. **Cover synonyms and variations**
   ```yaml
   # ❌ Bad: narrow description
   description: Generate weekly reports from Reddit data.
   
   # ✅ Good: covers how users actually search
   description: "Generate weekly trend reports from Reddit, Twitter/X, and 
     YouTube. Social media monitoring, content research, competitive analysis, 
     trend tracking. Use when asked to 'monitor trends', 'weekly report', 
     'what's trending', 'social listening', 'content ideas from social media',
     'track competitors', 'find viral topics'."
   ```

2. **Include trigger phrases** — Write the exact phrases users say:
   - "how do I..."
   - "is there a skill that..."  
   - "I want to..."
   - "can my agent..."

3. **Name the problem, not just the solution**
   ```yaml
   # ❌ Solution only
   description: Agent journaling and mood tracking.
   
   # ✅ Problem + solution
   description: "Reduce repetitive AI output and pattern rigidity. Agent 
     journaling, mood tracking, creative refresh. Fix agent burnout, boring 
     responses, lack of personality."
   ```

4. **Optimal description length:** 150-300 words. Too short = misses search terms. Too long = dilutes relevance.

### Channel 2: `clawhub explore` (Rankings) — 20% of discovery

Users browse by: `newest`, `trending`, `downloads`, `rating`.

**Optimization rules:**

1. **Update frequently** — Each version bump puts you in `newest`
   - Ship v0.1.0, then v0.1.1 next week, v0.1.2 the week after
   - Even small improvements (typo fix, example added) justify a patch
   
2. **Version strategically** — Big features = minor bump (0.2.0), polish = patch (0.1.1)

3. **Seed initial downloads** — Install your own skill across your agents to get off zero

### Channel 3: Agent Auto-Discovery (find-skills) — 10% of discovery

Some agents have `find-skills` installed, which searches ClawHub when users ask for capabilities.

**Optimization rules:**
- Description must match natural language questions
- Include the phrase patterns from Channel 1

## Audit Checklist

Run this against any SKILL.md:

```markdown
## Description Audit
- [ ] Length: 150-300 words?
- [ ] Contains 10+ synonym/variation phrases?
- [ ] Contains 5+ "trigger phrases" (user natural language)?
- [ ] Names the PROBLEM, not just the solution?
- [ ] Mentions target audience/use case?
- [ ] Includes negative triggers ("not showing", "can't find", "no results")?

## Competitive Audit  
- [ ] Searched ClawHub for your top 5 keywords — where do you rank?
- [ ] Identified top 3 competing skills?
- [ ] Description differentiates from competitors?

## Freshness Audit
- [ ] Updated in the last 2 weeks?
- [ ] Changelog or version history maintained?
- [ ] Plan for next 3 patch releases?
```

## Workflow: Optimize an Existing Skill

### Step 1: Extract current state
```bash
# Read the current description
head -20 path/to/SKILL.md

# Check current search ranking
clawhub search "your main keyword" --limit 10
clawhub search "alternate keyword" --limit 10
```

### Step 2: Competitor analysis
```bash
# Find competing skills
clawhub search "your niche" --limit 10
# Inspect top results
clawhub inspect competitor-skill-name
```

### Step 3: Generate optimized description

**Formula:**
```
[Core capability in 1 sentence]
[3-4 specific features/modules]
[5+ trigger phrases in natural language]
[Target audience]
[Differentiator from competitors]
[Token/resource cost if relevant]
```

### Step 4: Publish and verify
```bash
clawhub publish ./your-skill --version X.Y.Z

# Wait 2-3 minutes for indexing, then verify
clawhub search "your keyword 1" --limit 5
clawhub search "your keyword 2" --limit 5
clawhub search "natural language question" --limit 5
```

### Step 5: Track and iterate
- Check ranking weekly for your top 5 keywords
- If dropping, update description and bump version
- Monitor competitors for new entrants

## Anti-Patterns

- ❌ **Keyword stuffing with irrelevant terms** — Vector search penalizes semantic mismatch
- ❌ **Description longer than 400 words** — Dilutes relevance signal
- ❌ **Generic descriptions** — "A useful skill for various tasks" matches nothing
- ❌ **Never updating** — Falls off newest, loses freshness signal
- ❌ **Ignoring competitors** — If 3 skills match the same query, differentiation matters

---

## 中文说明

# 技能 SEO 优化器 🔍

让你的 ClawHub 技能被发现。本技能会分析你的 SKILL.md，并针对 ClawHub 的向量搜索、explore 排名和 Agent 自动发现进行优化。

## 快速开始

```
Optimize my skill for ClawHub: [path/to/skill/SKILL.md]
```

Agent 会审计你的技能并输出优化后的版本。

## ClawHub 发现机制的工作原理

技能通过三个渠道被发现，每个渠道需要不同的优化方式：

### 渠道 1：`clawhub search`（向量搜索）— 占发现量的 70%

ClawHub 对 YAML frontmatter 中的 `description` 字段使用**语义向量搜索**。这不是关键词匹配，而是语义匹配。

**会被索引的内容：** 仅 `description` 字段。
**不会被索引的内容：** markdown 正文、脚本、参考资料、文件名。

**优化规则：**

1. **覆盖同义词和变体**
   ```yaml
   # ❌ Bad: narrow description
   description: Generate weekly reports from Reddit data.
   
   # ✅ Good: covers how users actually search
   description: "Generate weekly trend reports from Reddit, Twitter/X, and 
     YouTube. Social media monitoring, content research, competitive analysis, 
     trend tracking. Use when asked to 'monitor trends', 'weekly report', 
     'what's trending', 'social listening', 'content ideas from social media',
     'track competitors', 'find viral topics'."
   ```

2. **包含触发短语** — 写下用户实际会说的确切短语：
   - "how do I..."
   - "is there a skill that..."  
   - "I want to..."
   - "can my agent..."

3. **点明问题，而不仅是解决方案**
   ```yaml
   # ❌ Solution only
   description: Agent journaling and mood tracking.
   
   # ✅ Problem + solution
   description: "Reduce repetitive AI output and pattern rigidity. Agent 
     journaling, mood tracking, creative refresh. Fix agent burnout, boring 
     responses, lack of personality."
   ```

4. **最佳描述长度：** 150-300 词。太短 = 漏掉搜索词。太长 = 稀释相关性。

### 渠道 2：`clawhub explore`（排名）— 占发现量的 20%

用户通过以下方式浏览：`newest`、`trending`、`downloads`、`rating`。

**优化规则：**

1. **频繁更新** — 每次版本号提升都会让你出现在 `newest` 中
   - 发布 v0.1.0，下周发布 v0.1.1，再下周 v0.1.2
   - 即便是小改进（修正拼写、新增示例）也足以发布一个 patch 版本
   
2. **有策略地版本化** — 大功能 = 次版本号提升（0.2.0），打磨 = patch（0.1.1）

3. **播种初始下载量** — 在你的各个 Agent 中安装自己的技能，让下载量摆脱零起点

### 渠道 3：Agent 自动发现（find-skills）— 占发现量的 10%

部分 Agent 安装了 `find-skills`，当用户请求某项能力时会搜索 ClawHub。

**优化规则：**
- 描述必须匹配自然语言提问
- 包含渠道 1 中的短语模式

## 审计清单

针对任意 SKILL.md 运行此清单：

```markdown
## Description Audit
- [ ] Length: 150-300 words?
- [ ] Contains 10+ synonym/variation phrases?
- [ ] Contains 5+ "trigger phrases" (user natural language)?
- [ ] Names the PROBLEM, not just the solution?
- [ ] Mentions target audience/use case?
- [ ] Includes negative triggers ("not showing", "can't find", "no results")?

## Competitive Audit  
- [ ] Searched ClawHub for your top 5 keywords — where do you rank?
- [ ] Identified top 3 competing skills?
- [ ] Description differentiates from competitors?

## Freshness Audit
- [ ] Updated in the last 2 weeks?
- [ ] Changelog or version history maintained?
- [ ] Plan for next 3 patch releases?
```

## 工作流程：优化现有技能

### 第 1 步：提取当前状态
```bash
# Read the current description
head -20 path/to/SKILL.md

# Check current search ranking
clawhub search "your main keyword" --limit 10
clawhub search "alternate keyword" --limit 10
```

##