Skill 创建与封装
先判断该不该封
改变｜做成可复用的能力包，三个变量各管一段：触发靠 description 双句（做什么 + 什么时候用），上下文靠三层渐进披露（元数据常驻 / 正文按需 / 资源按需），质量靠评测驱动、失败优先——先建无 Skill 基线，再从 3–5 个失败用例长出最小规则集。
角色｜规范整理与本地化（2026-08-21 起草，2026-10-28 更新）。
01 · 误区三个误区，先破掉
| 误区 | 实际 |
|---|---|
| Skill 等同于一段 Prompt | Prompt 是临时、探索性的；Skill 是可长期复用、输入输出明确、可维护的能力模块。工程要求完全不同。 |
| Skill 是写给人看的文档 | 它不下达解释，只下达指令。要明确约束行为边界，精确描述 When / How / What。 |
| Skill 越复杂越强 | 复杂度与能力强度无关，反而降低命中率。职责单一、边界清晰的更容易在正确时机被选中。 |
Skill 的存储位置是团队共享库、按需自动加载、版本化可回滚。这三点把它和普通提示词分开：靠个人经验才有的做法被编码进执行路径，任何人任何时候调用都得到一致结果。
02 · 第一关该不该封：TEV 三必要条件
这一关的方法论来自外部（代俊隆的 Skill 封装五关链路），我用它当资格线：三条必须同时满足，缺一条就不该封。
过了 TEV 还要看封到哪一层。封装颗粒度跟着「工作对象」走，不跟着行业走：文书型（固定格式文档）最容易封，分析型（数据+结论）要先固定分析口径，决策型能封规则与例外、封不了权衡取舍，创意型只封规范与流程、封不了品味，操作型基本不封。落地顺序建议从文书型 → 分析型 → 决策型，不要从最难的人工复核类起步。
还有一层现实判断：真实任务几乎都是「半稳定」——一半重复、一半灵活。标准答案是分层切，而不是一个 Skill 包打天下：最稳定的交给脚本和表格规则（凡是能数的，绝不靠 AI 感觉），半稳定的交给 Skill，最不稳定的留给人拍板。
03 · 第二关怎么写：description 决定它会不会被加载
模型启动时只看 (name, description)，不看正文。description 写不好，Skill 永远不会被加载，或者被错误加载。有效的写法几乎都收敛成同一个双句结构：
反例很典型：「A powerful PDF skill.」——没人知道何时该用；「Handles documents.」——范围过宽，大量误触发。命名同理，用小写字母、数字、连字符，优先动名词，与父目录同名，不带版本号。
正文的五个核心标准
| 标准 | 要点 |
|---|---|
| 边界明确 | 正向与负向触发都写：Use when / Do NOT use when。模型最易犯的错不是「不知道怎么做」，而是「不知道何时该做」。 |
| 输入输出结构化 | 用类函数签名的共同语言，明确 Input 类型与 Output 结构，避免不可解析的模糊描述。 |
| 步骤明确可执行 | 写「运行 validate.py --input x，校验失败时排查缺失字段/日期格式」，而不是「验证数据」。 |
| 失败策略完备 | 显式写失败路径，避免失败时自由发挥、不可预期。 |
| 职责单一 | 一 Skill 一事一动作动词，不把「跑测试 + 更新状态 + 发通知 + lint」捆在一起。 |
结构上是三层加载：元数据常驻 → 正文按需 → references / scripts 再按需。一个完整 SKILL.md 平均约 3000 token，装 200 个全量加载就是 60 万 token——所以「把几百行全塞进正文」是最大反模式，不是勤奋。
04 · 第三关怎么迭代：评测驱动、失败优先
高质量 Skill 是迭代出来的，不是一次写成的。六步里最容易被跳过的是第一步：
- 建「无 Skill」基线——先让模型直接做，记录哪里不稳定、哪些输入引发歧义、何时错误地「主动帮忙」。这些失败点就是评测用例的来源。
- 失败优先定义评测——先写 3–5 个可复现用例，每个有明确的通过/失败判据，优先覆盖最易误用的场景。
- 写最小化 Skill——只写能通过当前评测的最小规则集，把失败场景写进第一层防护（防误触发）。
- 补边界与示例——最短路径稳定后再扩，新增规则必须对应一个评测用例。
- 回归与迭代——改一次跑一遍已有评测；评测不过优先简化，而不是叠加规则。
- 用真实使用路径校准——观察误触发、漏读参考文件、隐性重复读取，回到第 2 步闭环。
05 · 反模式评审时逐条打勾
| 反模式 | 后果与正确做法 |
|---|---|
| 几百行全塞进 SKILL.md 正文 | 破坏渐进披露、污染上下文。正文只留核心逻辑，细节进 references，脚本进 scripts。 |
| 提供过多选择（PG / MySQL / SQLite…） | 增加模型决策成本与不确定性。指明默认路径，特殊需求才切替代。 |
| 正文写易过期的信息 | 版本号、价格、日期一旦过期，Skill 就不可用。 |
| 引用文件深度嵌套（A→B→C） | 模型可能只读到一部分。引用尽量由 SKILL.md 一层直达，长文件顶部加目录。 |
| Windows 风格路径 configs\deploy.yaml | 跨平台不兼容。统一用正斜杠。 |
| 正文写「帮助处理数据」这类模糊描述 | 无触发信号、无边界。写具体关键词与触发短语。 |
| 把判断标准写成打分表 | 模型能刷满分数，产出依然不可用——这和 Skill 无关，是验收装置坏了。 |
06 · 边界什么不该做成 Skill
三类：只发生一次的（封装成本收不回来）、好坏说不清的（没有判据，等于把判断权交给运气）、需要拍板的（Skill 只摆事实与选项，不替你决策）。另外半稳定的任务不要硬塞进一个 Skill，按稳定性切成脚本 / Skill / 人三段。
- ① 过 TEV——讲得清、判得了好坏、说得清边界。三条缺一条就先别封。
- ② 先写 description——WHAT + WHEN 双句，写完先问「模型看到这句会不会在该用的时候想起我」。
- ③ 先建基线再写正文——不用 Skill 跑一遍记失败点，再写最小规则集；评测不过就简化，不要叠加。