7.3 帮我们判断一句话是否值得保留。现在进一步考虑：这些值得保留的步骤，是否应该属于同一份 Skill？
一份 Skill 适合负责一个能独立交付结果的任务。 围绕这个结果需要的步骤可以放在一起；各自服务不同目标的工作应分别处理。先说清楚“从什么输入开始、交付什么结果”，再决定哪些步骤属于它。
本节对应 Best practices 的 Design coherent units。原文用数据库任务说明边界：查询数据并整理结果可以构成一个工作单元，而再加入数据库管理，就可能包含过多职责。
这里先区分两个问题：任务范围决定这份 Skill 负责什么；description 的表达帮助 Agent 判断什么时候加载它。写得具体本身没有问题，需要验证的是相关任务是否遗漏、无关任务是否混入，以及执行能否完成预期结果。
下面沿用 7.2 的 write-learning-unit 教学稿，以本站学习小节编写为例。本节的范围过宽与过窄版本用于教学对照，并非已经记录的 Agent 执行失败。
7.4.1 先说清楚，做到哪里算完成
面对“编写一个技术学习小节”，先填写三项内容：
| 项目 | 本例的回答 |
|---|---|
| 输入 | 用户指定的学习目标、来源资料、目标页面 |
| 交付结果 | 该小节的正文与完整最小示例，以及可查看的预览链接 |
| 完成条件 | 说明与示例一致，相关页面和导航可以正常访问 |
接着回看每个步骤：它是否服务这次交付？
阅读指定资料帮助确定讲什么；写示例与解释形成正文；检查页面和必要的导航关联，让读者能够找到并阅读它。这几个动作不同，但共同完成同一个任务。
因此，Skill 的范围可以包含多个步骤。边界取决于共同的任务结果。
7.4.2 范围过宽：加入了另一个目标
下面在 7.2 的教学稿上，扩大描述并加入第 6 步，构造一个范围过宽的版本：
---
name: write-learning-unit
description: 为本站编写或修改技术学习小节，并处理网站的其他维护工作。
---
## 输入
确认本节学习目标、用户指定的来源，以及要修改的页面。
阅读项目已有的写作约定，确认本地预览可以访问。
## 工作步骤
1. 阅读指定资料，核对要讲解的例子和本节范围。
2. 先展示一份完整的最小示例，再按组成部分解释。
3. 英文原例附上中文对照，保留相同的程序名称与命令。
4. 解释理解当前示例必需的术语，每次只展开当前学习点。
5. 检查说明与代码是否一致，并验证相关页面和导航。
6. 检查整个网站的所有文章，并统一修改全站样式。
## 交付
给出可查看的页面链接，说明本节完成了什么。
第 6 步引入了另外两个目标：全站文章检查与全站样式调整。它们各自需要确定范围和完成条件；编写当前小节并不总是需要它们。
区别可以这样判断：
| 工作 | 与当前交付的关系 |
|---|---|
| 修正指向本节的失效导航链接 | 让当前小节可访问，属于相关检查 |
| 全面检查其他主题的文章内容 | 有独立的检查范围，适合单独安排 |
| 重新设计全站配色 | 有独立的设计目标，适合单独安排 |
范围过宽还会影响描述：如果“网站维护”都算匹配，这份 Skill 就更难对应明确的任务。先限定工作单元，描述才能清楚说明何时使用。
7.4.3 范围过窄：同一个任务被拆散
另一个极端是把当前流程中的每个动作都拆成一份 Skill：
| 假设单独拆出的 Skill | 只负责什么 |
|---|---|
| 资料阅读 | 读指定资料 |
| 示例编写 | 写代码示例 |
| 术语解释 | 解释例子中的术语 |
| 页面检查 | 检查预览与导航 |
如果每次编写一个小节都需要这四项工作，就要反复交接学习目标、来源和完成条件，还可能分别出现不一致的指令。这时把它们作为一份 Skill 的步骤更连贯。
这张表用于检查是否拆得过细。若其中某项工作确实经常被独立请求、具有独立输入和交付结果，仍然可以考虑整理为单独的 Skill。
判断重点是：它是独立复用的任务，还是完成当前任务时总要经过的一步？
7.4.4 把合适的边界写回完整 Skill
现在去掉全站维护职责，收窄描述，并把范围与完成条件写清楚。其余写作步骤沿用 7.2：
---
name: write-learning-unit
description: 为本站编写或修改一个技术学习小节时使用。依据用户指定的资料，用完整最小示例解释当前知识点。
---
## 输入与范围
确认本节学习目标、用户指定的来源，以及要修改的页面。
本流程覆盖该小节的正文、示例，以及使该页可访问所必需的导航关联。
阅读项目已有的写作约定，确认本地预览可以访问。
## 工作步骤
1. 阅读指定资料，核对要讲解的例子和本节范围。
2. 先展示一份完整的最小示例，再按组成部分解释。
3. 英文原例附上中文对照，保留相同的程序名称与命令。
4. 解释理解当前示例必需的术语，每次只展开当前学习点。
5. 检查说明与代码是否一致，并验证相关页面和导航。
## 完成与交付
说明与示例一致，相关页面和导航验证通过后，给出预览链接并说明本节完成了什么。
这次改写的关键有三处：描述指向一个学习小节；范围说明包含相关导航；完成条件把正文、示例和可访问页面连在一起。
下面用检查表和实际请求验证这些边界。用户请求包含多个目标时，Agent 仍可以组合不同流程完成；这份 Skill 负责其中的小节编写部分。
7.4.5 判断标准：把“合适”变成可检查的问题
下面是将本节原则用于 write-learning-unit 的教学检查表，不是官网规定的统一评分表。
| 检查项 | 怎样判断 | 本例的判断依据 |
|---|---|---|
| 交付可验证 | 能否指出具体产物与完成条件？ | 有目标页面、完整示例和可访问的预览链接 |
| 步骤服务同一结果 | 去掉某一步，会缺少哪项交付要求？ | 页面检查支持“可访问”；全站配色服务另一个目标 |
| 拆分有独立用途 | 被拆出的部分是否经常被单独请求，有自己的输入与结果？ | 若每次写小节都要重新拼接四份 Skill，需检查是否拆得过碎 |
| 同类任务可复用 | 换一个主题或资料来源，方法是否仍然成立？ | 能写其他技术小节，不强制继续使用 d20 或固定章节号 |
检查时应写出对应的例子。遇到疑点，先明确任务边界，再通过下面两种测试观察实际行为；不要仅凭文件长短判断。
7.4.6 检查描述：用该触发与不该触发的请求测试
Agent Skills 的描述优化指南 建议用标注好的正反例检查描述；反例应优先选择用词相近、实际目标不同的请求。下面先做六条入门用例，测试的是本节的 write-learning-unit：
| 测试请求 | 预期是否加载 | 检查的边界 |
|---|---|---|
| “根据指定的 Agent Skills 文档，为本站新增一个带完整例子的学习小节。” | 是 | 典型写作任务 |
| “这页教程太抽象，请按指定资料补一个完整例子和中文解释。” | 是 | 换一种说法，仍是同类任务 |
| “补好这个学习小节的例子，并修复目录中指向它的链接。” | 是 | 写作任务包含必要关联工作 |
| “把全站的标题字体和配色统一一下。” | 否 | 同一网站中的样式设计 |
| “检查整个网站是否存在失效链接，正文不用修改。” | 否 | 独立的全站链接检查 |
| “解释一下 d20 是什么意思，直接回答即可。” | 否 | 仅回答术语，没有本站小节交付 |
这里的预期来自本例预先声明的范围。先固定预期，再运行测试。
- 确认客户端能发现这份 Skill，并允许自动调用。
- 每条请求使用新会话，模型、工具和项目初始状态保持一致；请求里不点名强制调用 Skill。
- 查看执行记录，确认是否实际加载了目标
SKILL.md，记录结果与证据。 - 对同一请求重复运行，观察是否稳定。不要仅凭 Agent 声称“使用了技能”判断。
应加载却未加载是漏触发；不应加载却加载是误触发。先排除发现路径、配置等问题，再考虑修改描述。Claude Code 的 Skill not triggering 也要求先核对技能是否可用，并区分自然语言匹配与直接调用。
这六条只用于起步。官方描述优化指南建议约 20 条正反例、每条重复 3 次，并统计触发率：实际加载次数 ÷ 运行次数。指南给出的 0.5 是示例阈值，不是所有任务的统一合格线。扩充测试时还要保留未参与改写的新请求，避免描述只适合已经见过的措辞。
7.4.7 检查执行：用可验证结果比较有无 Skill
触发正确之后，还要检查它是否改善执行。Claude Code 的评估说明 明确把触发与结果分开，并建议用新会话比较有无 Skill 的表现。
选择前面应加载的写作任务，在相同模型、输入和项目初始状态下分别运行：一组使用当前 Skill；另一组禁用它，或使用修改前的版本。保存产物、修改差异和执行记录；先确认使用组确实加载了目标 Skill。
再把“完成得好”写成能核对的检查项。本例可以从以下几项开始：
| 检查项 | 查看什么证据 |
|---|---|
| 目标页面包含完整示例 | 检查实际文件中的代码及必要组成部分 |
| 有英文原例时，中文对照保持名称与命令一致 | 对照两份示例的具体内容 |
| 预览页面与相关导航可访问 | 查看 HTTP 响应、页面与链接 |
| 完成了要求的页面检查 | 查看执行记录中的检查及结果 |
| 没有自行加入全站样式调整等无关工作 | 检查文件差异与执行记录 |
Agent Skills 的结果评估指南 将这种可验证的条件称为 assertions：每项记录通过或失败，并附具体证据。先跑少量任务，再依据实际产物细化检查项；语言是否清楚、讲解是否有帮助等质量仍需人工阅读。
比较后，按问题修改对应位置：
| 观察到的问题 | 优先检查什么 |
|---|---|
| 相关任务漏触发 | 可用性与描述是否覆盖这类用户意图 |
| 相近但无关的任务误触发 | 描述是否混入其他职责，边界是否清楚 |
| 已加载，但漏步骤或做了无关工作 | 正文步骤与范围说明 |
| 有无 Skill 都完成得一样好 | 这份 Skill 是否提供了额外价值；必要时比较稳定性、时间与用量 |
以上用例和检查表尚未作为真实 Agent 评测运行。它们提供的是验证方法；对范围是否合适的结论，应来自后续的实际记录。
学完本节，可以用一句话检查自己的 Skill：给定这些输入，它是否能完成一个明确的结果，而每个步骤都服务于这个结果？