让 SkillCorpus 检索到你的技能:写好 SKILL.md 描述的 5 个实用技巧
让 SkillCorpus 检索到你的技能:写好 SKILL.md 描述的 5 个实用技巧
SkillCorpus 是一套开源的技能语料基础设施,负责把散落在各处的 SKILL.md 文件整理成可被检索的智能体(Agent)技能语料。你的技能在用户提问时能不能被检索模型准确地找出来,很大程度上取决于 SKILL.md 里的 description 写得好不好。本文结合 SkillCorpus 的质量评分源码,分享 5 个立即可用的写作技巧,帮你把技能"写进"检索结果里。
为什么 SKILL.md 描述决定检索命中率
SkillCorpus 的检索链路是:用户任务 → 微调过的 Qwen3-Embedding-0.6B 双编码器召回候选 → Qwen3-Reranker-0.6B 重排序(配方见 skillcorpus/match/README.md)。参与编码的核心文本就是技能的 name、description 和正文——训练数据也是由"真实任务描述 ↔ 技能"配对构建的(skillcorpus/match/generate_queries.py)。
与此同时,cli build 会用 LLM 评审官给每个技能打分,公式很直观(skillcorpus/curate/quality.py):
| 维度 | 含义 | 权重 |
|---|---|---|
| utility(效用) | 这个点子值不值得做:任务是否具体、触发条件是否独特 | 50% |
| robustness(稳健性) | 正文是否真的兑现了描述承诺的能力 | 35% |
| safety(安全性) | 使用它会不会造成危害(破坏性操作、泄密、注入等) | 15% |
一句话:描述写得越像"用户的真实提问",且正文接得住,质量分和检索排名就越高。 下面 5 个技巧正是围绕这三点展开。
技巧一:写清"何时触发",而不是只说"能干什么"
LLM 评审的打分标准里有一条明确的规则:只点出技术栈的描述默认只能拿 5–6 分,而"具体任务 + 独特触发条件"才能拿 8–10 分。评审官的原始示例是:
- ❌ "React 开发专家,精通 Vite、TypeScript 与现代工具链" → 通用智能体不用你的技能也能做,效用分上不去。
- ✅ "Stripe 支付 SDK 集成:发起收款、处理 Webhook、管理订阅。当用户想收款、退款或管理 Stripe 客户数据时使用" → 触发场景独一无二,9 分档。
所以,在你的 description 里加一句 "Use when …"(当用户……时使用),告诉检索系统:什么样的用户请求应该命中我。
技巧二:用用户的口吻描述具体任务,带上输入输出关键词
检索模型的查询侧是"用户的真实任务描述",比如"把扫描版 PDF 发票里的表格提取出来"。你的描述里出现的词,越接近用户会说的话,向量相似度越高。写作时可以问自己:
- 用户会怎么在对话框里描述这个需求?
- 这个任务的输入是什么(PDF、CSV、仓库)?输出是什么(表格、报告、部署)?
把这两类词自然写进描述。注意反过来也别犯"堆砌术语"的错——评审标准明确指出,光提技术栈名字("Python 工具""React 专家")不会加分,独特的触发场景才加分。
技巧三:正文必须兑现描述里的承诺(utility 与 robustness 分开考)
SkillCorpus 的质量评审把"点子"(utility)和"交付"(robustness)严格分开打分,并且内置了一个专门的对齐检查:如果描述承诺了能力 X,正文却只实现了 Y,会被打上 inconsistent_doc_code 标记,robustness 上限直接压到 5 分。
两个典型反例(来自评审官的校准样例):
- 描述说"验证 CSV 是否符合 JSON Schema",正文只是
pd.read_csv()看一眼 → 名不副实。 - 正文全是
## Setup TODO占位符 → 被标记placeholder,robustness 上限 4 分。
写法建议:描述里承诺的每一件事,正文里都要有对应的步骤、命令或代码;做不到的,就别写进描述。
技巧四:控制篇幅——描述 60–1000 字符,正文 1k–10k 字符最理想
即使不用 LLM 评审,SkillCorpus 也有一套结构化的长度评分(skillcorpus/curate/quality.py 中的 _desc_len_score / _body_len_score):
| 部分 | 长度 | 得分 |
|---|---|---|
| description | < 20 字符 | 0(基本不合格) |
| description | 20–60 字符 | 0.5 |
| description | 60–1024 字符 | 1.0(最佳区间) |
| description | > 1024 字符 | 0.8(过长略扣分) |
| 正文 | < 300 字符 | 0(直接不达标) |
| 正文 | 1000–10000 字符 | 1.0(最佳区间) |
| 正文 | > 50000 字符 | 0(不达标) |
另外两个小要求:
name必须是小写字母、数字、连字符,长度 ≤ 64(skillcorpus/curate/parse.py);name和description是必填字段,缺失会导致解析校验失败。
一个规范的 frontmatter 大致长这样:
---
name: stripe-payment-sdk
description: >
Stripe API 集成:发起收款、处理 Webhook、管理订阅。
当用户想收款、退款或管理 Stripe 客户数据时使用。
tags: [payments, saas-api]
license: MIT
version: 1.0.0
---
顺带一提,frontmatter 里补齐 license、version、tags、category 等字段(任意 4 个即满分),也会让结构分更漂亮。
技巧五:补上 scripts/ 和 references/,同时守住安全底线
加分项:技能目录里带上 scripts/ 质量分 +0.05,带上 references/ +0.02。把可执行的脚本、参考文档和 SKILL.md 放在同一个技能目录里,既提高质量分,也提升正文的交付力。语料导出时这些附件会完整打包(列定义见 docs/corpus-schema.md)。
安全红线:safety 子分低于 3,或触发 5 个硬性安全标记之一(prompt_injection、cmd_injection、unsafe_exec、auth_bypass、csam_risk),质量分直接归零。常见踩坑点:
- 破坏性操作默认不确认(
rm -rf、DROP TABLE直接执行)→destructive_no_confirm; - 把用户输入直接拼进 shell 命令(
os.system(f"... {user_input}"))→cmd_injection; - 把真实密钥写死在技能里 →
secret_leak(占位符如<YOUR_API_KEY>不算)。
写法建议:涉及写操作、删除、外发数据的步骤,明确写出"先向用户确认";引用脚本时用相对路径指向技能自带的 scripts/ 文件。
发布前自查清单
写完 SKILL.md,可以用这 6 个问题快速过一遍:
- [ ]
description里有没有一句"当用户……时使用"的触发条件? - [ ] 描述里是否包含用户会说的任务词、输入/输出词,而不是纯技术栈堆砌?
- [ ] 描述承诺的每个能力,正文里都有对应的步骤或代码吗?
- [ ] 描述在 60–1024 字符、正文在 1k–10k 字符区间吗?
- [ ] 有可执行内容时,是否放进了
scripts/或references/? - [ ] 所有破坏性操作都要求确认吗?有没有把用户输入拼进 shell 的写法?
最后可以拿真实查询验证一下:SkillHub 的 API 支持直接按自然语言查询(示例脚本见 examples/skillhub_demo.py),用"用户视角"的提问搜一搜,你的技能排不排在前面,一目了然。
小结
SkillCorpus 的检索是"描述驱动"的:utility 看触发条件是否独特,robustness 看正文是否兑现承诺,safety 看有没有硬性风险,篇幅落在推荐区间,再配上 scripts/ 和 references/。把本文 5 个技巧套进你的 SKILL.md,技能的检索命中率和质量分都会实打实地提高。