Agent Skills 触发描述与范围边界
本节目标
写出可发现且不过度宽泛的 description，并用正负触发查询检验它。
description 承担什么
采用渐进披露的 client 在发现阶段通常只看到 name 和 description，所以描述是自动选择 Skill 的主要线索。它至少回答：
- 做什么：能完成的任务和产物。
- 何时用：用户意图、输入类型、典型上下文或关键词。
弱描述：
description: Helps with text. # 反例：范围过宽，可能让客户端把无关翻译、改写或 RAG 请求也错误路由到本 Skill较好描述：
description: Count words, characters, and lines with deterministic JSON output. Use when a user asks for text-size statistics, word counts, or a machine-readable text summary. # 正例：说明具体能力、典型触发语句和确定性输出，不承诺翻译/总结等无关任务第二个版本既有能力，也有触发情境；同时没有声称翻译、改写或语义总结等不在范围内的能力。
从用户意图而非实现细节写
用户通常不会说“请运行 scripts/text_stats.py”。描述应覆盖用户要达成的目标，而非内部文件名。官方指南建议用明确的行动式措辞、保持几句到短段落，并遵守 1024 字符上限。
正负触发集
为每个 Skill 写两类真实请求：
- should-trigger：明确请求、隐式需求、口语、不同详细程度和多步骤任务中的子需求。
- should-not-trigger：与领域有关键词重叠、但目标属于相邻能力的“近似负例”。
以 text-statistics 为例：
| 查询 | 标签 | 理由 |
|---|---|---|
| “统计这段说明的字数并给 JSON” | 应触发 | 目标和输出都匹配 |
| “我的报告有多少行和英文单词？” | 应触发 | 未说 Skill 名，但意图匹配 |
| “把这段英文润色得更简洁” | 不应触发 | 是改写，不是计数 |
| “按词频画柱状图” | 不应触发 | 需要频率分析与可视化，超出范围 |
负例不能全是“今天天气如何”这类显然无关请求，它们无法检验边界。
触发不是确定性函数
模型行为可能非确定。同一查询应运行多次，记录触发率而非凭一次结果下结论。官方优化指南建议从约 20 条查询开始，正反各 8～10 条，并把每条运行多次；3 次是合理起点，约 5 轮修改通常足以判断方向。这些都是工程起点，不是任何模型的性能保证。
评测自动触发时，应把显式 /skill-name 调用、将 Skill 固定预加载到 custom agent、或人工选择 Skill单独记录，不要把它们混入 description 的自动选择分数。判定证据应来自目标 client 的可观察事件（日志、trace、上下文或官方诊断），而不是仅根据最终答案猜测“它大概读过 Skill”。
把用例拆成“调试集”和“验证集”：只能根据调试集修改 description，验证集在定稿时才使用。若持续把失败的验证例加入描述关键词，得到的是记住测试题的描述，而不是能泛化到真实用户意图的边界。
练习与自测
- 给“从 CSV 生成质量报告”写 3 条 should-trigger 与 3 条近似负例。
- 修改描述前后各跑相同查询多次，记录触发/不触发，不要只挑成功样本。
- 自测：描述加入所有热门关键词是否会更好？不会；会增加误触发、上下文成本和冲突。
下一步
学习 脚本、资源与安全。
参考资料
- Optimizing skill descriptions（核验日期：2026-07-22）
- Agent Skills Specification（核验日期：2026-07-22）
- GitHub Copilot CLI reference: Skills（显式调用与 client 字段示例；核验日期：2026-07-22）