30—AI Skill 怎么写才可测：Skill 编写规范与设计方法论

从本文开始，系列进入规范与实操专题。

前面我们已经讲过 SkillSentry 怎么评估价值、怎么做盲测、怎么对照外部框架、怎么把线上失败回流成 regression。接下来这组文章回到发布前最具体的工作：Skill 应该怎么写、环境怎么配、完整测评怎么跑、CI 门禁怎么落地。

这一组会依次讲四件事：

写法规范 → 环境 → 操作全景 → CI

核心结论 ：SKILL.md 有两个完全不同的读者------AI 模型 （决定是否触发）和测评系统（决定怎么验证）。为 AI 写的是 description，为测评写的是规则。这两件事混在一起写是大多数 Skill 质量问题的根源。

---

先区分两件事：让 Skill 触发，和让 Skill 做对

写 SKILL.md 的核心挑战是：它同时服务于两个目的：

1. 让 AI 正确触发：当用户说了对的话，这个 Skill 应该生效
2. 让测评系统正确验证：测评用例能够精确地验证 Skill 的每条规则

这两件事需要不同的写法，也有不同的失败模式。本篇围绕 5 条核心原则展开，每条原则对应一类常见的写法问题。

---

原则一：description 是触发的生死线

description 做什么

description 是 AI 判断「是否应该加载或使用这个 Skill」的最关键前置信号。用户发来的消息会先和 Skill 的元数据做语义匹配，description 写得越清楚，模型越容易在正确场景中选择它，也越不容易误触发。

description 必须回答 4 件事：

1. 这个 Skill 解决什么问题（一句话，动词 + 宾语）
2. 什么情况下触发（触发词/场景，越具体越好）
3. 什么情况下不触发（明确的排除条件，防止误触发）
4. 用户输入的典型形态（用户会怎么说这件事）

差的 description vs 好的 description

差的写法：

description: 企业报销助手，帮助员工处理报销相关事务。

问题：

• 「报销相关事务」太宽泛，AI 不知道什么时候该用
• 没有触发词，匹配度低
• 没有排除条件，容易误触发「查一下我上次报销记录」这种非提交场景

好的写法：

description: |
  用于员工发起差旅或日常资源用量报销申请。

  触发场景：
  - 用户说「帮我报销」「提交报销」「我要报差旅费」
  - 用户提到发票、资源用量单、出差资源用量并要求提交或处理

  不触发场景：
  - 仅查询历史报销状态（用 expense-query Skill）
  - 催促审批（用 approval-reminder Skill）
  - 只问资源用量政策（直接回答，不触发 Skill）

触发率与 description 的关系

sentry-static 会评估你的 description 能否被正确触发。旧的 sentry-trigger 现在只是兼容入口，不再作为正式入口建议。下面是 SkillSentry 当前建议的触发率阈值。它是工程门禁口径，不是行业通用标准：

触发率	含义	处理
TP ≥ 80%	正常，description 清晰	标注参考值
TP 70%-79%	description 可能不够清晰	黄色警告，建议优化
TP < 70%	description 有严重问题	自动降级为 CONDITIONAL PASS

最常见的 description 问题：

• 用「管理」「处理」「助手」这类泛词，没有具体动作
• 没写触发词，全靠 AI 猜测语义
• 没写排除条件，导致其他场景的消息也误触发

---

原则二：主文件 200 行警戒线

为什么是 200 行

这个数字不是论文给出的通用阈值，而是 SkillSentry 基于长上下文研究和本地测评经验设定的工程警戒线 。Liu et al.（2023）「Lost in the Middle」研究说明：当上下文变长时，语言模型对中间部分信息的利用能力会下降。

具体表现：

• 放在开头和结尾的规则，AI 遵守率高
• 放在中间的规则，随着文件变长，遵守率会系统性下降
• 上下文越长，中间规则被忽略的风险越高，具体阈值会随模型和任务变化

SKILL.md 的 200 行警戒线，是对这个现象的工程化防护：普通 Skill 的规则密度下，200 行通常已经足够承载核心触发、规则和步骤；超过这个规模，就应该检查是否需要拆分 Skill、提取 include 文件或合并冗余规则。

超过 200 行时怎么办

方案一：规则拆分（建议）

把一个大 Skill 拆成多个职责单一的小 Skill：

expense-reimbursement/    ← 只负责发起报销
  SKILL.md
expense-query/            ← 只负责查询状态
  SKILL.md
expense-policy/           ← 只负责回答政策
  SKILL.md

每个 Skill 的主文件保持 ≤ 200 行，规则聚焦，触发条件清晰。

方案二：规则提取到 include 文件

把枚举类内容（资源用量类型列表、城市补贴标准等）提取到独立文件，主文件保持简洁：

<!-- SKILL.md -->
资源用量类型请参考：`./expense-types.md`

方案三：审查冗余规则

超长往往意味着规则重复。用 sentry-static 的静态检查能力检查冗余，合并表述相同的规则。

sentry-static 的静态检查项

sentry-static 会在以下情况发出警告：

• 主文件 > 200 行：触发「中间遗忘效应风险」警告
• 存在重复规则：标出语义相近的规则对
• HiL（Human-in-the-Loop）设计缺失：涉及写操作但没有确认步骤

---

原则三：两种规则，两种写法

SKILL.md 中的规则分为两类，混用会造成 AI 执行困难：

类型一：强制型规则（硬约束）

定义：无论任何情况都必须遵守，不能根据上下文变通。

写法：直接、命令式、无歧义。

✅ 好的写法：
- 提交前必须调用 validateExpense 验证金额
- 发票金额超过 5000 元时，必须请用户上传原件

❌ 差的写法：
- 通常情况下应该先验证金额（「通常」给了 AI 变通空间）
- 如有必要，请上传发票原件（「如有必要」让 AI 自行判断）

类型二：解释型规则（软建议）

定义：提供背景和判断依据，让 AI 在特定情况下做出合适的决策。

写法：提供 Why + What，允许 AI 根据上下文灵活处理。

✅ 好的写法：
- 如果用户提交的金额明显低于市场价（如出租车 10 分钟但只报 5 元），
  说明可能是金额填写有误，应提示用户核查。

❌ 差的写法：
- 检查金额是否合理（「合理」是主观词，AI 不知道标准是什么）

混用的代价

强制型规则用了解释型写法：AI 把「通常」当成真的可以变通，导致在某些场景下跳过了必要步骤。

解释型规则用了强制型写法：AI 把每个细节都当作不可违反的约束，导致过于僵化，无法处理真实用户的自然语言变体。

最简判断方法：问自己------「这条规则允许 AI 根据上下文不执行吗？」

• 答案是「不允许」→ 强制型，用命令式写法
• 答案是「要看情况」→ 解释型，提供判断依据

---

原则四：步骤优先于目标

这个原则来自 Agent / workflow prompt 的工程实践：对需要稳定复现的业务流程，明确步骤通常比只给目标更可测、更可回归。

为什么步骤优于目标

给目标：帮用户完成报销流程

AI 会自己设计流程。这听起来灵活，实际上：

• AI 每次想出的步骤可能不一样（随机性）
• AI 可能跳过某些在业务上必要但看起来「可选」的步骤
• 测评用例无法精确验证步骤顺序

给步骤：

## 执行步骤
1. 收集用户信息：姓名、出行日期、目的地、资源用量类型
2. 调用 uploadExpenseDoc 上传凭证
3. 调用 validateExpense 验证合规性
4. 确认后调用 submitExpense 提交
5. 返回提交单号和详情链接

AI 按步骤执行，行为可预测，测评断言可以精确覆盖每一步。

步骤式写法的 5 个要素

1. 有序编号：步骤之间有明确顺序
2. 每步可验证：测评可以检查「步骤 N 是否执行了」
3. 异常处理内嵌：每步的失败情况紧跟在该步下方，不单独列「异常处理」章节
4. 工具调用明确：哪步调用什么工具，直接写工具名
5. 终止条件清晰：流程什么时候结束，结束时返回什么

---

原则五：HiL（人在回路）设计规范

对会产生外部副作用的写操作、数据提交、不可逆操作 ，Skill 必须有人工确认步骤。这不是泛化建议，而是 SkillSentry 在 sentry-static 中设置的高风险静态检查项。

什么时候需要 HiL

操作类型	是否需要确认	原因
提交表单、申请、订单	✅ 必须	提交后通常不可撤回
修改数据库记录	✅ 必须	数据变更影响下游
发送邮件/消息	✅ 必须	发出后无法收回
查询操作	❌ 不需要	只读，无副作用
文本生成	❌ 不需要	输出给用户看，用户自己决定是否用

HiL 的标准写法

## 步骤 4：提交确认（HiL 检查点）

在调用 submitExpense 之前，必须向用户展示以下信息并等待确认：

- 资源用量类型：[类型]
- 总金额：[金额]元
- 报销周期：[起止日期]
- 凭证数量：[N] 张

**确认话术**（不能省略）**：
「以上信息是否正确？确认后将提交审批，提交后无法修改。」

用户说「确认」「对」「提交」「没问题」→ 执行提交
用户说「修改」「不对」「等等」→ 返回步骤 2 重新收集
用户说其他内容 → 询问「请问您是要确认提交，还是需要修改某项信息？」

sentry-static 对 HiL 的检查

sentry-static 会扫描以下模式，判断是否缺少 HiL：

• SKILL.md 中出现了 submit、create、update、delete、send 类工具调用
• 但没有对应的确认步骤

触发告警后，不影响测评继续，但报告中标注「HiL 缺失风险」。

---

综合示例：一个满足 5 条原则的 SKILL.md 片段

---
name: expense-reimbursement
description: |
  用于员工发起差旅或日常资源用量报销申请。

  触发场景：
  - 用户说「帮我报销」「提交报销」「我要报差旅费」
  - 用户提到发票、资源用量单、出差资源用量并要求提交

  不触发场景：
  - 仅查询历史报销状态 → 使用 expense-query
  - 催促审批 → 使用 approval-reminder
---

## 核心规则

- 提交前必须调用 validateExpense，验证通过才能提交（强制）
- 发票金额超过 5000 元，必须请用户上传原件（强制）
- 如用户提供的金额明显偏低，应提示核查（解释型）

## 执行步骤

1. 收集信息：出行日期、目的地、资源用量类型、金额
2. 调用 uploadExpenseDoc 上传凭证（失败则告知用户重传）
3. 调用 validateExpense 验证（失败则告知用户具体问题）
4. [HiL] 展示汇总信息，等待用户确认
5. 调用 submitExpense 提交，返回单号和详情链接

这个片段满足：

• 原则一：description 有触发词、排除条件、用户话术
• 原则二：主文件 < 200 行
• 原则三：强制规则用命令式，解释型规则提供判断依据
• 原则四：步骤编号清晰，每步有工具调用和失败处理
• 原则五：步骤 4 有明确 HiL 确认

---

常见问题与诊断

症状	可能原因	检查方法
Skill 从不触发	description 太宽泛，或触发词不匹配	运行 sentry-static 触发率检查，看 TP 率
Skill 乱触发（误触发）	description 没有排除条件	在 description 中明确 不触发场景
测评中步骤顺序不稳定	规则是目标式而非步骤式	改为有序步骤编号
AI 跳过某个必要步骤	规则写成「通常」「如有必要」	改为强制型命令式写法
sentry-static 报 HiL 缺失	有写操作但没有确认步骤	在提交前添加确认环节
主文件超过 200 行	规则混杂、枚举内容未提取	拆分 Skill 或提取 include 文件

---

本文依据说明

本文中的规范来自三类来源：

1. 官方 Skill 机制 ：Skill 的 name / description / 元数据是模型判断是否加载和使用 Skill 的关键前置信号；正文规则则用于约束 Skill 被加载后的具体行为。
2. 长上下文研究 ：Liu et al.（2023）的 Lost in the Middle 说明，长上下文中间位置的信息更容易被模型忽略。因此，本文建议控制 SKILL.md 主文件长度，并把关键规则放在更稳定、更容易检索的位置。
3. SkillSentry 工程实践：200 行警戒线、触发率阈值、HiL 静态检查，是 SkillSentry 为了让 Skill 更可测、更可回归而设定的工程规则，不是所有平台的行业统一标准。

因此，本文不是说"所有 AI Skill 都必须小于 200 行"，而是给出一套面向 SkillSentry 测评体系的可测性规范：让 Skill 更容易触发、更容易执行正确，也更容易被测评系统验证。

参考来源

• Liu et al. (2023), Lost in the Middle: How Language Models Use Long Contexts ：arxiv.org/abs/2307.03...
• Anthropic Claude Skills 文档：用于理解 Skill 元数据、description 与渐进式加载机制。
• SkillSentry 当前口径与本地工程实践：sentry-static、触发率检查、HiL 风险检查、PASS / CONDITIONAL PASS / FAIL 发布口径。

---

总结

写 SKILL.md 的核心判断框架：

对每条规则问两个问题：

1. 这是强制的还是建议的？→ 决定写法（命令式 vs 解释型）
2. 测评怎么验证这条规则执行了？→ 决定断言能否写精确

对整个文件问一个问题： 如果一个从未见过这个 Skill 的 AI 读了这个 SKILL.md，它能精确复现你期望的行为吗？如果答案是「也许」，说明还有规则需要写得更具体。

---

真正的判断标准不是写得是否完整，而是第一次读这个 Skill 的模型能不能稳定复现你的意图。