Skill Search Helper

---
name: skill-search-helper
description: "技能搜索——把「有没有能做某件事的技能」改写成名词搜索词，在 SkillHub 上找候选，比较匹配度、边界、作者、版本与安全报告，给出首选和备选。当用户说「有没有能…的技能」「帮我找个技能」「这几个技能哪个好」时使用。"
author: Captain
version: 0.1.1
display_name: "技能搜索"
display_name_en: "Skill Search"
description_zh: "技能搜索：把需求改写成 2–4 个名词搜索词（平台按字面匹配、不分词），用 skillhub 只读命令取候选并去掉补位条目，按匹配度、边界是否写清、作者、版本、安全报告比较，给出一个首选和一到两个备选及理由；安装命令带 namespace，用户确认后再装。"
description_en: "Turn 'is there a skill that does X' into noun search terms, pull SkillHub candidates with read-only commands, drop filler results, compare fit, stated boundaries, author, version and security reports, and recommend one pick plus one or two alternatives with a namespaced install command the user confirms."
tags:
  - "技能搜索"
  - "找技能"
  - "技能推荐"
  - "技能对比"
  - "SkillHub"
  - "技能市场"
  - "skill search"
  - "find skills"
examples_zh:
  - "有没有能帮我写请假条的技能"
  - "帮我找个技能，能把会议录音整理成纪要的"
  - "搜出来好几个请假条技能，这几个技能哪个好"
examples_en:
  - "Is there a skill that can help me write a leave request?"
  - "Find me a skill that turns meeting recordings into minutes"
  - "The search turned up several leave-request skills; which of these is best?"
---

# 技能搜索

定位一句话：**先把需求翻译成平台搜得到的词，再按「能不能解决这件事」排序；谁发布的不加分也不减分。**

## 何时使用

用户想找一个现成的技能来做某件事，或者手上有几个候选拿不准选哪个。用户通常这样说：

- 「有没有能帮我写请假条的技能」
- 「帮我找个技能，能把会议录音整理成纪要的」
- 「搜出来好几个请假条技能，这几个技能哪个好」
- 「这个技能安全吗，装之前帮我看看平台的安全报告」
- 「有没有处理 Excel 表格的技能，要中文的」

不适用（遇到时直接简答或转交）：

- **用户要的是把事直接做了**（「帮我写个请假条」），不是找技能：直接做，或先问一句「要我直接写，还是帮你找个专门的技能？」
- **安装后运行、发布、评论、打分**：本技能只用只读命令；安装只给命令，用户确认后再执行或由用户自己执行。
- **对陌生技能的文件做静态安全扫描**：交给「安装前检查」这类技能；本技能只看平台的安全报告状态。

## 先判断：用户到底要什么

从对话里确定三件事，缺哪项先问哪项：

1. 对象：要处理的东西，如请假条、会议录音、Excel 表；
2. 结果：想得到什么，如写好的文书、整理好的纪要、一张图表；
3. 约束：中文还是英文、能不能联网、有没有不能上传到外部的资料。

## 流程第 1–2 步：改写搜索词，取候选

**第 1 步：改写成名词搜索词。** 平台搜索按字面匹配、不分词。实测「写请假条」只返回与请假条无关的补位技能，「请假条」才搜得到真正的请假条技能。改写规则：去掉动词和客套（写、做、生成、帮我、好用的），保留对象名词，再补一个同义词和一个上位词，凑成 2–4 个词。

```
用户原话                    搜索词
帮我写个请假条              请假条 / 请假申请 / 请假
把会议录音整理成纪要        会议纪要 / 录音转写 / 纪要
做一份给老板看的周报        周报 / 工作汇报 / 汇报
```

更多改写对照和「换词顺序」见 [references/search-terms.md](references/search-terms.md)。

**第 2 步：取候选，去掉补位条目。** 单个词用只读命令：

```bash
skillhub --skip-self-upgrade search 请假条 --json --search-limit 10
```

返回的 results 里每条有 slug（形如 @作者/技能名）、name、description、version、namespace.handle（作者）。匹配结果不够时，平台会用一批与搜索词无关的常见技能补足条数——名字和描述都不含搜索词的，一律不算候选。所有词都只剩补位条目时，换同义词、上位词再搜一轮；仍然没有，就如实告诉用户。注意一次只搜一个词：把几个词用空格连着传给 search，会被当成一整个查询——实测「请假条 请假申请」连着搜，只剩补位条目。

几个词一起查、去掉补位条目、附上平台安全报告状态，用只读脚本（只调用 search 与 skill reports 两个只读子命令；每次调用 60 秒超时、失败最多重试 2 次；只用 Python 标准库）：

```bash
python3 {baseDir}/scripts/skill_candidates.py 请假条 请假申请 请假
python3 {baseDir}/scripts/skill_candidates.py 会议纪要 录音转写 --no-reports   # 不查安全报告，更快
```

脚本输出每个候选的 slug、名称、版本、命中了哪些词（在名字里还是只在描述里）、两项安全报告状态和截短的描述；同一作者有多个候选、某个词只剩补位条目、某个词没搜成功时，在末尾「提示」里列出。单独查某个技能的平台安全报告：

```bash
skillhub --skip-self-upgrade skill reports <slug> --namespace <作者> --json
```

报告含两家实验室的结果，status 为 benign 表示平台扫描未发现问题；其他状态或查不到报告的，不进首选。

## 第 3 步：比较并推荐

| 维度 | 看什么 | 怎么判断 |
|---|---|---|
| 匹配度 | 名字和描述是否正好是用户要的对象和结果 | 专做这件事 > 顺带覆盖 > 描述里只提到一次 |
| 边界 | 描述是否写了适用范围、不做什么 | 写清的优先，只堆功能的降一档 |
| 作者 | namespace.handle，描述自称的出品方与之是否对得上 | 只用来区分同名技能，不因作者是谁加减分 |
| 版本 | version（搜索结果不带更新时间） | 只作参考：版本号高说明迭代过，不等于最近更新 |
| 安全报告 | skill reports 的两项 status | 两项都是 benign 才能做首选 |

排序以匹配度为准；匹配度相近时，再看边界是否写清、版本是否迭代过。安全报告不满足的，不做首选。同一作者用不同 slug 发的几乎相同的技能，只取一个比较。用户的需求本身是两步（如先把录音转文字、再整理纪要）时，每一步各给一个首选。

推荐写法：

```
首选：<展示名>（@作者/slug，v版本）——理由：专门做什么；描述写清了什么边界；两项安全报告为 benign
备选：<展示名>（@作者/slug）——什么情况下选它更合适
没选：<展示名>——原因，如通用写作技能，请假条只是顺带
```

## 第 4 步：安装带 namespace，用户确认后再装

```bash
# 会下载并安装到本机，用户确认后再执行
skillhub install <slug> --namespace <作者>
```

为什么带 `--namespace`：slug 不是全平台唯一的，实测同一个 slug 下有两个不同作者各发的技能；不带作者，装到的未必是你比较过、看过安全报告的那一个。给出命令时提醒用户：装之前先看安全报告；陌生技能在第一次使用前，可以再用「安装前检查」对它的文件做一次静态扫描。

## 信息不全或出错时

| 情况 | 怎么处理 | 对用户说的话（一句模板） |
|---|---|---|
| E1 缺关键信息：只说「找个好用的技能」，对象和结果都不清楚 | 最多问三个：要处理什么、想得到什么、有没有不能上传的资料；其余默认中文、可联网，默认值标 [待确认] | 「你想处理的是什么（请假条、Excel、录音……）？想得到什么结果？我先按中文、可联网来找。」 |
| E2 输入不对或自相矛盾：给的是动词短语或一整句；说「资料不能外传」却要找在线处理的技能；只给了 slug 没给作者 | 改写成名词再搜，并说明原因；矛盾处指出，给两种理解让用户选；slug 不带作者时列出同 slug 的各个作者请用户认 | 「资料不能外传的话，在线处理类的技能要排除：是只找本地处理的，还是能接受脱敏后上传？」 |
| E3 超出范围：直接替你安装、帮发布、刷评论或下载、评价某个作者 | 只做只读查询；安装给命令、等确认；不发布、不评论、不评价人 | 「安装我先不动，命令给你：你确认后我再执行，或你自己执行。」 |
| E4 时间紧，只要一个能用的 | 最小版：只搜一个最准的名词，给一个两项安全报告都是 benign 的首选和安装命令；省略比较表；标题写「状态：最小版」 | 「最小版：首选这一个，两项安全报告都是 benign，命令在这里；要比较其他的再说。」 |
| E5 用户坚持越界：要求优先推荐某个作者（包括本技能作者自己的账号）；安全报告没过也要做首选；要我不经确认直接装 | 守住：排序只看匹配度；安全报告不满足的不做首选，可以列为「没选」并写明原因，装不装由用户决定；安装一定等确认 | 「推荐只按和你需求的匹配度排，不看是谁发的；这个技能的安全报告还在排队，我不把它放首选。」 |
| 平台出错：搜索超时、返回异常，或所有词都只剩补位条目 | 脚本已自动重试 2 次；仍失败就如实说明、稍后再试；全是补位就按「同义词 → 上位词 → 相邻任务词」换词，三轮没有就说没找到 | 「这几个词都只搜到无关的补位技能，我换了『请假申请』『办公文书』也没有，目前没找到匹配的技能。」 |

脚本出错时：

| 退出码 / 报错 | 原因 | 修正办法 |
|---|---|---|
| 0 | 正常输出候选；也包括「没找到匹配的技能」 | 按比较表推荐；没找到就换词 |
| 1「参数错误」 | 没给搜索词、超过 6 个词、`--limit` 不在 1–50 | 给 2–4 个名词搜索词重跑 |
| 2「找不到 skillhub 命令 / 写不了输出文件」 | 没装 SkillHub CLI 或不在 PATH 里；`--out` 目录不可写 | 按平台官方说明安装 CLI；`--out` 换个目录 |
| 3「搜索失败（已重试 2 次）」 | 所有词的搜索都超时或请求失败 | 检查网络，稍后再试；可先加 `--no-reports` 减少请求 |
| 130「已中断」 | 按了 Ctrl+C | 直接重跑；脚本不安装、不改动任何东西 |

## 输出契约

交付物按固定顺序输出，某部分没有内容写「无」：

```
0 标题行：技能搜索结果｜需求一句话｜状态：完整版 / 最小版 / 没找到｜[待确认] N 项
1 搜索词与候选数：用了哪几个词，去掉补位条目后剩几个
2 比较表：候选｜匹配度｜边界｜作者｜版本｜安全报告
3 推荐：一个首选（两步的需求每步一个）+ 一到两个备选，各附理由；没选的写原因
4 安装命令：带 --namespace，写明「你确认后我再安装，或你自己执行」
5 没找到时：换过哪些词、建议的下一步
```

没有合适的就直说「没找到匹配的技能」，给出换词建议，不硬推不相关的技能。

占位符：[待确认]——安全报告查不到、描述自称的出品方与作者对不上、默认的约束（中文、可联网）等需要用户或平台再确认的项，数量写进标题行。

交付前自检（每条答「是」才交）：

- [ ] 搜索词都是名词，2–4 个，一个词搜一次？
- [ ] 名字和描述都不含搜索词的补位条目都去掉了？
- [ ] 首选的两项安全报告都是 benign？
- [ ] 推荐理由只讲匹配度和边界，没有因为作者是谁加减分？
- [ ] 安装命令带 --namespace，而且没有未经确认就执行？
- [ ] 没找到时如实说了，并写了换过哪些词？

## 示例

> 示例：候选的名称、作者、版本与安全报告状态都是占位数据，只演示格式，不对应平台上的真实技能。

用户：「有没有能帮我写请假条的技能？」

对象（请假条）和结果（写好的请假条）都清楚，不用再问。改写搜索词后运行 `python3 scripts/skill_candidates.py 请假条 请假申请 请假`，交付：

```
技能搜索结果｜需求：写请假条｜状态：完整版｜[待确认] 0 项
搜索词：请假条 / 请假申请 / 请假（去掉补位条目后 3 个候选）

比较
候选                        匹配度                      边界                    版本    安全报告
@author-a/leave-note       专做请假条，含学校与公司两套   写了不涉及劳动法定性      1.0.0   两项 benign
@author-b/office-writer    通用办公写作，请假条是顺带     没写                     2.1.0   两项 benign
@author-c/leave-lite       只有一个模板                  没写                     0.1.0   一项 queued

首选：请假条（@author-a/leave-note，v1.0.0）——专门写请假条；描述写清了不涉及劳动法定性；两项安全报告为 benign
备选：办公写作助手（@author-b/office-writer）——如果还要写周报、邮件，一个技能都能顺带
没选：请假模板（@author-c/leave-lite）——只有一个模板，安全报告还有一项在排队

安装命令（会下载并安装到本机；你确认后我再执行，或你自己执行）：
skillhub install leave-note --namespace author-a
```

更完整的示例（录音还没转文字、需求拆成两步、每步一个首选，含脚本输出）见 [examples/meeting-minutes-search.md](examples/meeting-minutes-search.md)。

## 常见问题（FAQ）

**问：为什么不能直接用我的原话搜？**
答：平台按字面匹配、不分词，「写请假条」这种动词短语只会搜出无关的补位技能；改成「请假条」这样的名词才搜得到。

**问：能直接帮我装上吗？**
答：我给出带作者的安装命令，你确认后我再执行，或你自己执行；装之前先看一眼两项安全报告。

**问：安全报告两项都是 benign，就一定安全吗？**
答：不是绝对安全，只表示平台扫描没发现问题。陌生技能第一次用之前，可以再用「安装前检查」对它的文件做一次静态扫描。

**问：为什么安装命令一定要带 --namespace？**
答：slug 不是全平台唯一的，同一个 slug 可能有不同作者各发一个；不带作者，装到的未必是你比较过的那一个。

**问：能按下载量或评分排吗？**
答：搜索结果不带下载量和更新时间，版本号也只说明迭代过；我按和你需求的匹配度、边界是否写清来排。

**问：同一个作者发了好几个差不多的技能，怎么选？**
答：只取一个进比较，一般留描述写得最清楚、版本迭代过的那个。

**问：公司电脑能装第三方技能吗？**
答：按单位对第三方插件的规定执行；需要审批的先走审批，拿不准就问单位 IT。

**问：搜了几轮都没有合适的怎么办？**
答：我会如实说「没找到匹配的技能」，并列出换过的词；这件事也可以不靠技能，直接让我帮你做。

## 常见错误（反模式）

最佳实践先记三条：先改写成名词再搜；补位条目一律去掉；安装等用户确认、命令带作者。

| 错误做法 | 为什么错 | 正确做法 |
|---|---|---|
| 拿用户原话直接搜 | 动词短语搜不到，只剩补位条目 | 去掉动词和客套，改成 2–4 个名词 |
| 把几个词用空格连着一次搜 | 平台把它们当成一整个查询，实测只剩补位条目 | 一个词搜一次，或用脚本合并几个词的结果 |
| 把补位条目当候选推荐 | 名字和描述都和需求无关 | 名字和描述都不含搜索词的一律去掉 |
| 只看名字不读描述 | 容易推荐顺带提一句的通用技能 | 读描述，按「专做 > 顺带 > 只提一次」判断 |
| 安全报告查不到或没过，也做首选 | 用户可能装上有问题的技能 | 两项都是 benign 才做首选，其余写进「没选」 |
| 安装命令不带 namespace，或者没问用户就直接安装 | 可能装错作者的技能，也越过了用户的决定 | 命令带 --namespace，等用户确认 |
| 按作者名气或自家账号加分 | 推荐失去中立 | 只按匹配度和边界排序 |
| 同一作者的近似技能都放进比较表 | 表格被灌水，真正的对比被淹没 | 同一作者几乎相同的只取一个 |
| 没找到也硬推一个 | 用户装了用不上，浪费时间 | 如实说没找到，给换词建议 |

## 边界与不做什么

- 只用只读命令（search、skill reports），不自动安装、不发布、不评论。
- 推荐依据是与需求的匹配度，不偏向任何作者，包括本技能作者自己的账号 indiv-captain 发布的技能。
- 平台报告与本地扫描都只是参考，不等于绝对安全；装不装由用户决定。
- 单位电脑按单位对第三方插件的规定执行，需要审批的先走审批，拿不准的问单位 IT。