名称： skill-search-optimizer
描述： 优化智能体技能在 ClawdHub/MoltHub 上的可发现性。适用于改进搜索排名、为语义搜索编写描述、理解注册表如何索引技能、测试搜索可见性或分析技能未被找到的原因。
元数据： {"clawdbot":{"emoji":"🔎","requires":{"anyBins":["npx"]},"os":["linux","darwin","win32"]}}
优化技能在 ClawdHub 注册表中的可发现性。涵盖搜索工作原理、如何编写高排名描述、语义匹配的内容策略、测试可见性以及竞争定位。
ClawdHub 使用基于向量的语义搜索，而非关键词匹配：
用户查询 → OpenAI 嵌入 → 向量相似性搜索 → 排序结果
(text-embedding-*) (Convex 向量索引)
关键影响：
1. 含义比精确关键词更重要 — “容器调试” 会匹配 “Docker 故障排除”
2. 但关键词仍有帮助 — 嵌入模型会为特定术语编码高信号
3. 描述是主要的索引字段 — 内容可能有所贡献，但描述占主导地位
4. 简短查询匹配宽泛描述 — “docker” 会匹配关于容器的通用技能
5. 具体查询匹配具体描述 — “调试崩溃的 Docker 容器” 偏向于提及调试和崩溃的技能
主要： 描述字段 (frontmatter)
次要： 名称/别名 (slug) 字段
第三级： 技能内容 (正文 markdown) — 可能在嵌入前被总结或截断
描述字段是你的搜索排名关键。其他都是次要的。
# 内部如何调用搜索
# POST https://clawdhub.com/api/cli/search
# 请求体: { "query": "用户搜索词", "limit": 10 }
# 返回：带相似度分数的技能排序列表
# CLI 搜索
npx molthub@latest search "你的查询"
# 模式：
# [动作动词] + [具体范围]。适用于 [场景 1]、[场景 2]、[场景 3]。
# 也涵盖 [相关主题]。
# 示例 (强)：
**描述：** >-
使用 cron 和 systemd 定时器安排和管理周期性任务。
适用于设置 cron 任务、编写 systemd 定时器单元、
处理时区感知的调度、监控失败的任务、
实现重试模式，或调试计划任务未运行的原因。
# 为何有效：
# - "安排和管理周期性任务" → 匹配调度类查询的宽泛表述
# - "cron 和 systemd 定时器" → 匹配特定工具查询的精确表述
# - "适用于..." 场景 → 匹配自然语言问题
# - "调试计划任务未运行的原因" → 匹配故障排除查询
**描述：** >-
使用 [工具/技术] 进行 [动词]。适用于 [任务 1]、[任务 2]、[任务 3]。
涵盖 [子主题 1]、[子主题 2] 和 [子主题 3]。
示例：
**描述：** >-
调试 Docker 容器和 Compose 堆栈。适用于检查
容器日志、诊断网络问题、故障排除
构建失败，或调查资源使用情况。涵盖 exec、
健康检查、多阶段构建和无发行版容器。
**描述：** >-
[主题] 模式，适用于 [范围]。用于 [任务 1]、[任务 2]、[任务 3]。
也涵盖 [相关范围]。
示例：
**描述：** >-
适用于 JavaScript、Python、Go 和 grep 的验证、解析和文本提取的正则表达式模式。
用于编写电子邮件、URL、IP、日期或自定义格式的正则表达式。
也涵盖前瞻、后顾以及用于代码重构的搜索替换。
**描述：** >-
从 [开始] 到 [结束] 的 [流程描述]。适用于 [场景 1]、
[场景 2]、[场景 3]。
示例：
**描述：** >-
从提交到部署的 CI/CD 流水线配置。适用于
设置 GitHub Actions、创建矩阵构建、缓存
依赖项、构建 Docker 镜像或管理部署密钥。
语义搜索理解同义词，但明确表述更有帮助：
# 同时包含正式术语和常见同义词
**描述：** >-
用于远程访问的 SSH 隧道和端口转发。
适用于创建 SSH 隧道、设置端口转发、
通过跳板机（堡垒主机）连接、管理
SSH 密钥，或使用 scp 和 rsync 传输文件。
# "隧道" 和 "端口转发" 相关但不同查询
# "跳板机" 和 "堡垒主机" 是同义词 — 两者都包含
# "scp 和 rsync" 捕获文件传输查询
应包含的术语：
- 主要工具名称：docker、git、curl、make
- 动作动词：debug、test、deploy、monitor、parse
- 常见同义词：container / Docker、CI/CD / pipeline / GitHub Actions
- 问题描述：debugging why X doesn't work、troubleshooting Y
过短 (< 50 字符)：
"使用 Makefile 构建"
→ 嵌入模型的语义表面不足
理想长度 (80-200 字符)：
"为任何项目类型编写 Makefile。适用于设置构建
自动化、定义多目标构建，或将 Make 用于 Go、
Python、Docker 和 Node.js。也涵盖 Just 和 Task。"
→ 丰富的语义内容，多个匹配角度
过长 (> 250 字符)：
[试图列出所有内容的长段落]
→ 在搜索结果展示中被截断
→ 用低信号词稀释了嵌入向量
→ 在列表中难以阅读
技能正文（frontmatter 之后的 markdown 内容）可能通过两种方式影响搜索：
优化策略：
- 在标题后的第一段前置重要术语
- 使用与搜索查询匹配的标题 — "## 编码和解码" 比 "## 第 2 节" 匹配得更好
- 自然地重复关键术语贯穿全文（不要堆砌，但也不要刻意回避）
# 良好：标题匹配可能的搜索查询
## 端口转发
## 密钥管理
## 连接调试
# 不佳：通用标题，无搜索价值
## 入门指南
## 高级用法
## 杂项
标题后的第一段是搜索的黄金地段：
# 良好
# SSH 隧道
创建和管理用于安全远程访问的 SSH 隧道。涵盖本地、
远程和动态端口转发、跳板机、密钥管理、
代理转发，以及使用 scp 和 rsync 的文件传输。
# 不佳
# SSH 隧道
此技能提供有关 SSH 的信息。
# 使用用户可能输入的确切查询进行测试
# 宽泛查询 (你的技能应该出现吗？)
npx molthub@latest search "docker"
npx molthub@latest search "testing"
npx molthub@latest search "build automation"
# 具体查询 (你的技能应该排名第一吗？)
npx molthub@latest search "debug docker container"
npx molthub@latest search "write makefile for go project"
npx molthub@latest search "cron job not running"
# 问题导向查询 (你的技能匹配故障排除吗？)
npx molthub@latest search "container networking not working"
npx molthub@latest search "why is my cron job not executing"
# 同义词查询 (你的技能匹配替代术语吗？)
npx molthub@latest search "bastion host" # 应匹配 ssh-tunnel
npx molthub@latest search "scheduled task" # 应匹配 cron-scheduling
为你的技能构建测试矩阵：
搜索可见性矩阵
技能：[你的技能别名]
查询 | 出现？ | 排名 | 竞争对手
─────────────────────────────────────────────────────────────────
[宽泛术语] | 是/否 | #__ | [谁排名更高]
[具体用例] | 是/否 | #__ | [谁排名更高]
[问题/故障排除查询] | 是/否 | #__ | [谁排名更高]
[主要主题的同义词] | 是/否 | #__ | [谁排名更高]
[相关但不同的主题] | 是/否 | #__ | [预期？]
目标：在具体查询中排名前 3，在宽泛查询中排名前 10
# 1. 发布初始版本
npx molthub@latest publish ./skills/my-skill \
--slug my-skill --name "My Skill" --version 1.0.0
# 2. 测试搜索可见性
npx molthub@latest search "主要查询"
npx molthub@latest search "次要查询"
# 3. 如果排名不佳，更新描述
# 编辑 SKILL.md 的 frontmatter
# 4. 发布更新版本
npx molthub@latest publish ./skills/my-skill \
--slug my-skill --name "My Skill" --version 1.0.1 \
--changelog "改进描述以提升搜索可见性"
# 5. 重新测试 (嵌入向量在发布时更新)
npx molthub@latest search "主要查询"
# 在你的类别中查找技能
npx molthub@latest search "你的主题"
# 对于每个竞争技能：
# 1. 安装它
npx molthub@latest install competitor-skill
# 2. 阅读描述
head -10 skills/competitor-skill/SKILL.md
# 3. 比较：
# - 他们的描述是否涵盖了你没有覆盖的查询？
# - 他们是否使用了你应该添加的术语？
# - 他们的内容深度与你的相比如何？
策略 1：更广的范围
竞争对手涵盖 Docker。你涵盖 Docker + Podman + containerd。
你的描述提及所有三者 → 匹配更多查询。
策略 2：更深的特异性
竞争对手涵盖 "git 命令"。你涵盖 "git 工作流"，包含
特定场景，如 bisect、worktree 和 reflog 恢复。
你的描述匹配特定的故障排除查询。
策略 3：问题导向的框架
竞争对手："Docker 容器管理"
你："调试 Docker 容器 — 日志、网络、崩溃、资源问题"
问题导向的描述匹配人们实际搜索的方式。
策略 4：跨工具覆盖
竞争对手仅涵盖 Make。你涵盖 Make + Just + Task。
你的描述提及所有三者 → 更广的匹配面。
市场分析：
1. 搜索你预期的主题
2. 统计结果：
0 个结果 → 蓝海。任何合理的技能都将排名第一。
1-2 个结果 → 低竞争。更好的技能轻松胜出。
3+ 个结果 → 竞争激烈。需要明确的差异化。
对于竞争激烈的类别，检查现有技能的质量：
- 他们的描述是否优化？ (许多没有)
- 他们的示例是否有效？ (测试几个)
- 他们是否覆盖了完整范围？ (通常很窄)
即使在竞争激烈的类别中，一个描述优化、编写精良的技能
也能超越平庸的技能。
常见搜索模式：
1. 工具名称："docker"、"git"、"terraform"
→ 在描述中明确提及工具名称以匹配
2. 任务描述："部署到生产环境"、"解析 CSV"
→ 使用动作动词和任务短语匹配
3. 问题陈述："容器无法启动"、"cron 任务失败"
→ 在描述中使用故障排除语言匹配
4. 比较："jest vs vitest"、"make vs just"
→ 在描述中提及多个工具以匹配
5. 操作指南："如何设置 CI/CD"、"如何转发端口"
→ 使用 "适用于设置..." 模式匹配
- 新技能在发布时立即被索引
- 更新技能在版本升级时重新索引
- 没有已知的新鲜度偏差 (旧技能不会排名更低)
- 注册表尚年轻 — 早期发布者具有先发优势
- 别名所有权是永久的 — 尽早抢占好的别名
发布前搜索优化：
[ ] 描述遵循 [动作] + [范围] + [适用于] 模式
[ ] 描述长度为 80-200 字符
[ ] 主要工具/主题名称在描述中明确提及
[ ] 包含常见同义词 (跳板机 / 堡垒主机)
[ ] 包含故障排除/问题语言
[ ] 动作动词匹配用户搜索方式 (debug、test、deploy、parse)
[ ] 标题后的第一段强化了关键术语
[ ] 章节标题使用可搜索的短语，而非通用标签
[ ] 别名具有描述性并与主要搜索词匹配
[ ] 没有竞争技能对相同查询有明显更好的描述
发布后验证：
[ ] 技能在其主要具体查询中排名前 3
[ ] 技能在其宽泛类别查询中排名前 10
[ ] 技能至少出现在一个同义词/替代查询中
[ ] 技能至少出现在一个问题导向查询中
container-debug 比 cd-tool 更好，因为别名本身包含可搜索的术语。