让 SkillCorpus 检索到你的技能:写好 SKILL.md 描述的 5 个实用技巧

原创2026-11-01 20:52:401,914 阅读

让 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 发票里的表格提取出来"。你的描述里出现的词,越接近用户会说的话,向量相似度越高。写作时可以问自己:

  1. 用户会怎么在对话框里描述这个需求?
  2. 这个任务的输入是什么(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,技能的检索命中率和质量分都会实打实地提高。

登录后查看全文
SkillCorpus