skill-build — 造 skill 的 skill

做完六步交付一个 skill 包，外加一份能回答"它比不用它好多少"的评测报告。

定位与边界

使用者多半是产品同学，不是工程师。他知道业务、知道要什么效果，不知道 skill 该长什么样。所以这套流程的第一职责是提问，把他没想清楚的地方逼出来；写 SKILL.md 反而是最容易的一步。

不接的活：只想了解 skill 概念、一次性问答、纯翻译总结。这些直接回答，别建包——S0 就是专门用来拒绝它们的。

先分档，再动手

按复用量选，从最轻的开始，缺什么再升。升档只允许增加 references/scripts/evals，SKILL.md 本体不许跟着变大。

判断不了就问用户一句"这个 skill 大概会被用多少次、用错了有什么后果"。多数需求是轻档。yao-meta-skill 方法论正确但自身长到 400+ 文件，skill-creator 只有 19 个——后者是对的那个。

六阶段

S0 该不该做  →  S1 收料  →  S2 设计  →〔完备性门禁〕→  S3 撰写  →  S4 评测  →  S5 迭代
   ↑ 拒绝出口                                                                    └──→ S3

轻档跳过 S1 的基建盘点和 S4 的基线对照，其余照走。

每个阶段一份 reference，进到那一步再读，读完即弃：

模板在 assets/，用到哪份 S 步骤里会点名。

S0 该不该做成 skill

先做减法。满足以下至少一条才继续：会被重复使用 / 容易被路由错 / 有确定性脚本能省重复劳动 / 需要治理和跨会话统一。

一条都不占就说清楚为什么不建包，给替代方案（扩展已有 skill、加一个 tool、改 prompt、什么都不做），到此结束。业务场景里需求常常是派下来的，用户未必有权说"不做"——那就把这一步用在"扩展已有 skill 是否更划算"上，仍然有价值。

产出：一段话，为什么要独立 skill 而不是 A/B/C。

S1 收料

三块，逐块访谈，缺了当场问：

1. 需求与场景——谁、什么处境、带着什么问题来，理想情况下他拿到什么
2. 已有决策与约束——已经拍板了什么不能推翻（平台、形态、上下游、合规）；参考对象最多扫 3-5 个，并且明确记下"哪些不借鉴"
3. 基建盘点（完整档）——有哪些 tool 可调、入参出参各是什么、哪些字段本 skill 用不上

第 3 块是业务场景独有的优势，两个开源工具都没有。产品同学常常不知道有哪些 tool，引导他把 schema 贴进来，帮他逐字段标注用途和"不用"。

对话历史里已经演过这个流程的（"把刚才那套做成 skill"），先从历史里提取：用过哪些工具、步骤顺序、用户做过的纠正、观察到的输入输出格式。别从零问起。

一轮问题不超过 3 个。产品同学被一次问十条会直接放弃。

S2 设计

这一份是写给人看的——业务方、研发、评测同学要拿它对齐。八个模块（轻档只需 2.1/2.2/2.3/2.4）：

要解决的问题 · 定位与边界 · 触发与意图路由 · 输出框架 · 执行流程 · 辅助资源 · 输入输出定义 · 上下文分层规划

定位要写出人格和立场，不只是范围。"像一个当地土著朋友——把『换成是你先吃哪家』讲透"这种写法，比"负责美食推荐"有用得多，因为它能让模型在你没预料到的情况下推断出正确行为。

用 assets/design-doc-template.md 落文档。详细访谈脚本见 stage-2。

完备性门禁

六条全过才准进 S3。任何一条不合格，回 S1 继续澄清，不往下走——带着假设往下跑，产出的是一个基于猜测的 skill。

轻档豁免第 3、4 条。

S3 撰写

把设计翻译成给模型读的指令。骨架用 assets/skill-md-skeleton.md。

三件事决定成败，展开看 stage-3：

• description 写得推销一点。模型有欠触发倾向，要显式覆盖同义场景，加"哪怕用户没明说 X"。所有"何时使用"的信息都放这里，正文里不写"When to Use"——正文只在触发之后才加载，写了也没人看。执行层的禁令移回正文，因为 description 对所有会话常驻，是最贵的那段上下文。
• 少堆强调词，改成解释 why。发现自己在写全大写 ALWAYS/NEVER，或者写下第五个 最高优先级，那是黄色警告。一份文档里有七个最高优先的东西，就等于没有优先级——模型在它们冲突时无从取舍。规则不被遵守的根因通常是文档太长把规则稀释了，加更多强调词只会让它更长。
• 分层控长。metadata 常驻 → SKILL.md 正文 <500 行 → references/scripts/assets 按需。超了就外移，别压缩措辞。

写完跑一次体检：

python3 scripts/validate_skill.py <skill目录>

它查结构、frontmatter、行数、强调词密度、红线条数、装饰性目录（建了但 SKILL.md 从没引用）。

新写或改过检查脚本时，先拿已知健康的 skill 跑一遍再信它的输出。 脚本报出来的是嫌疑不是结论，把嫌疑当结论报给用户，比不检查更糟——它带着"我查过了"的可信度。判据很简单：健康样本上出现的告警，先怀疑脚本。

S4 评测

回答两个问题：它好不好，以及不用它会差多少。

1. 造 query 集——真实用户会打的字，带文件路径、工作背景、口语和错别字，聚焦边缘情况。负例必须是 near-miss（共享关键词但实际需要别的东西）；"写个斐波那契函数"当 PDF skill 的负例什么都测不出来。模板 assets/trigger-eval-template.json
2. 触发评测——每条跑 3 次取触发率，60% train / 40% test，按 test 分数选 description
3. 基线对照（完整档）——同一批 query 跑 with-skill 和 without-skill；改进已有 skill 时 baseline 用旧版快照
4. 考点评测——客观考点走脚本，主观考点交 LLM 多次采样取中位数，10% 人工抽检。模板 assets/rubric-template.md
5. 性能——token 和耗时，每个 run 结束立刻记，过了就没了
6. 考点自身审计——找出"有没有 skill 都拿满分"的考点，淘汰。在弱考点上通过比没测更糟，它制造虚假信心

聚合和区分度审计用：

python3 scripts/score_rubric.py --with with.json --without without.json

query 必须够有分量。模型只在自己搞不定的任务上才去查 skill，"读一下这个文件"这种一步就能干完的 query，description 写得再好也不触发，拿它当测试用例是浪费。

S5 迭代

先归因，再动手——不是所有失分都该改 skill。三分：skill 指令的问题 / query 集的问题 / 考点本身的问题。

改的时候守两条：泛化不过拟合（这个 skill 要被用无数次，只对这几条测试 query 有效等于没用），每轮必须有删减动作，只做加法的迭代是在把 skill 推向失效。

读 transcript 而不只读最终输出。模型在哪浪费了步骤，那段指令就是候选删减对象；多个用例都各自造了同一个轮子，那个轮子该进 scripts/。

停止条件：用户满意 / 反馈全空 / 不再有实质进展。

红线

只有四条，都是违反了就收不回来的：

1. 改动已有 skill 前先 cp -r 快照。没有旧版就跑不了对照，也回滚不了。
2. 没实际跑过的评测不写进报告。跑了几条说几条，没跑基线对照就别下"有效果"的结论——伪造证据比没有证据更糟。
3. 已发布的 skill 不改 name。改名会让所有引用和 symlink 静默指空，路由全部失效。要改内容就改内容，别出 -v2。
4. 凭证和内部 URL 不写进 skill 文件。skill 会被打包、被 symlink、被同步到 GitHub。

目录与产出物

<skill-name>/
├── SKILL.md          # 定位边界、触发、流程骨架、红线、输出骨架
├── references/       # 按需读入上下文的文档
├── scripts/          # 确定性的重复任务
└── assets/           # 用在输出里的模板、图标、字体

不要建 README.md / INSTALLATION.md / CHANGELOG.md。skill 目录只装模型干活需要的东西，建包过程的说明放外面。

完整档每阶段落一份产出物，用户拿去和上下游对齐：S0 一页纸决策 → S1 需求与基建清单（给研发确认 tool）→ S2 设计文档（给业务方确认边界）→ S3 SKILL.md → S4 query 集 + 考点表 + 评测报告 → S5 迭代记录。

装进 Claude Code：把包放进 Skill/ 下的某个 skill 仓库的 skills/，跑那个仓库的 ./install.sh --target claude 建 symlink。别复制真文件副本，版本会漂。

说话尺度

用户技术水平跨度很大。"评测""基线"可以直接用；"JSON""断言""holdout"要先确认他懂，否则换成"测试用例""判分标准""优化时不给看的那批题"。

他答不上来的时候，那多半说明这个地方本来就没想清楚——把问题拆细再问一遍，比替他填一个假设强。