day3-如何写出一个高质量的 Skill（组内分享）
高质量 Skill 不是“一个调得很顺的巨型 Prompt”，而是一个可验证、可回归、可维护的能力包。
先定义“什么算好”，再实现“怎么做好”。评估体系先于 Skill 本身成型。
下面用“故障诊断 Markdown 转 YAML”作为例子，但方法是通用的。
---
一、先想清楚：Skill 到底是什么
一个 Skill 至少包含四部分：
部分 作用
接口 输入什么、输出什么、边界在哪
流程 分几步做，每步的产物是什么
规则 硬约束、经验规则、失败模式
降级策略 不确定时怎么办，而不是硬编一个看似合理的结果
高质量 Skill 的共同点：职责单一、接口清晰、规则可定位、输出可验证。
反例：把几十条经验全塞进一个主 Prompt，改一条规则要重调整个 Prompt，评估时也不知道是哪条规则退化。
---
二、核心方法：先建评估，再写 Skill
不要先写转换器再补测试。正确顺序是：
1. 定义输出契约：什么算合法、什么算合格；
2. 建金标准集：一小批人工认可“可放行”的样本；
3. 先写评估 Skill：让它在金标准集上跑出基线；
4. 再迭代生成 Skill：每次修改跑同一套评估，无退化且目标维度提升才算正向。
这就是评估驱动开发：评估是 Skill 的单元测试，金标准集是回归锚点。
---
三、评估 Skill：三层门禁，逐层递进
前一层不过，后一层不跑。每层留可追溯证据。
第 1 层：确定性硬门禁
用解析器、Schema、校验器完成，不消耗模型成本。
· 输出可解析；
· 必填字段齐全，类型/枚举合法；
· 引用目标存在，无悬空引用、无不可达节点；
· 关键路径至少有一条能到达预期出口。
不通过直接打回。
第 2 层：语义断言
用脚本 + 结构遍历检查“逻辑对不对”，仍然保持确定性。
通用检查项：
· 覆盖率：源材料里的关键步骤、分支、条件，输出里是否都有对应？
· 完整性：每个判断节点是否都有明确出口？有没有死胡同？
· 可达性：每条路径是否都能到达预期终点？有没有无出口循环？
· 顺序与依赖：有先后依赖的操作，是否保留了顺序？有没有被拍平成无序列表？
例子：故障诊断转换中，检查“每个判断项是否有是/否/异常出口”“每条路径是否能到根因”。
第 3 层：LLM-as-Judge
只处理解析器表达不了的维度：忠实度、完整性、可执行性。
但 Judge 会漂移，不能单独放行，必须建立在第 1、2 层之上。Judge 的 Prompt、rubric、模型版本都要版本化，换模型必须用金标准集重新校准。
通用 Judge 维度：
维度 问什么
忠实度 输出是否忠实源材料意图？有没有自行发明内容？
完整性 关键步骤、条件、证据是否保留？隐式知识有没有被压成空话？
收敛性 输出是否仍指向原目标，而不是发散？
可执行性 下游不依赖源材料能否直接使用？
---
四、金标准集：回归测试的锚点
不需要一开始就标注几百份。用已认可的样本当种子，扩到 15～30 份，覆盖失败模式而非随机抽样：
· 完整正例：典型流程；
· 边界/异常分支：异常路径、循环、前置失败回退；
· 已知易错模式：实际踩过的坑；
· 留出集：不参与调优，只用于最终验收，防过拟合。
金标准不需要完美，只需要当前标准下认可可放行。
回归指标：关键路径用 pass^k（k 次全过），稳定性用 pass@k。
---
五、工程约束：让批量产出可重放
· 幂等：同输入 + 同 Skill 版本 + 同规则 → 输出一致，否则无法判断变好是 Skill 改了还是随机波动；
· 隔离不阻断：单份失败进隔离队列，记录失败层和原因，不阻塞其余；
· 版本绑定：规则、rubric、金标准集进 Git；每份报告绑定“源版本 + 生成 Skill 版本 + 评估 Skill 版本 + Judge 模型版本”；
· 抽样人工复核：Judge 临界样本 + 易错模式，人工抽检结果反过来校准 rubric。
---
六、Skill 本身怎么写
· SKILL.md 控制篇幅，写清：输入约定、输出契约、分步流程、硬规则、降级策略；
· 经验规则放 references/ 或 rules/，按失败模式分类，不要全塞进主 Prompt；
· 不确定时标 needs_review: true，不要硬编看似合理的结果；
· 迭代由评估报告驱动：报告告诉你哪层挂了、哪类失败模式，你改对应规则文件，而不是漫无目的调 Prompt。
---
七、落地顺序（不要反过来）
1. 固化输出契约：Schema + 结构约束；
2. 建金标准集：从已认可的 + 最易出错的样本开始；
3. 先写评估 Skill：跑出基线报告；
4. 再迭代生成 Skill：每次修改对比逐项通过率，无退化且目标提升才算正向；
5. 批量运行 + 隔离回放：失败进队列，结束后人工抽检；
6. 评估 Skill 自身版本化：换 Judge 模型必须重新校准。
---
八、给组员的三条硬要求
1. 不许凭感觉说“变好了”：每次修改必须附评估报告对比，逐项通过率说话。
2. 不许跳过确定性门禁直接看 Judge 分数：前两层挂了，Judge 分数没有意义。
3. 不许把规则堆进主 Prompt：规则按失败模式分文件，评估报告要能定位到具体文件。
---
一句话收尾
生成 Skill 决定“能不能做”，评估 Skill 决定“敢不敢用”。
先让评估体系站稳，再让生成器迭代。这样交付的不是一堆“看起来还行”的产出，而是一套可证明、可回归、可交接的 Skill 质量体系。
