Skill Craft

Skill Craft — Skill 全生命周期操作

依据《Skill 完整实操指南》对 skill 做创建、修改、审查、合并、退役。本文件只做 路由；方法细节全部在 references/（渐进式披露——这正是指南的要求，本 skill 以身作则）。

> 用用户的语言交流与产出；本 skill 的方法论内核是中文的，保持中文。

意图路由表

| 用户想做什么 | Task | 按需加载 | |---|---|---| | "帮我写/创建一个 skill" | A 创建 | decide-and-design → writing → templates → evals → launch-checklist | | "改/优化/加固这个 skill" | B 修改 | evals（回归先行）→ writing → lifecycle（版本） | | "为什么没触发/误触发/不按步骤走" | C 诊断 | troubleshooting → writing §L1 | | "这两个 skill 要不要合并 / 这个太大了拆一下" | D 合并/拆分 | lifecycle → decide-and-design §粒度 | | "这个 skill 没人用了/过时了，删了吧" | E 退役 | lifecycle §退役 |

Task A：创建

输入：用户的场景描述（最好有 3–5 个真实 case）。产出：完整 skill 目录 （SKILL.md + 按需 references/scripts/examples + evals/evals.json）。 沉淀通道入口：请求来自 loop-retro 的沉淀提案时，三判据证据已现成（重复=会 再跑、跑偏=retro findings、交付物=harness 产出），素材即 harness/SPEC/gotchas—— 直接从第 2 步开始；薄壳 skill（description + 指向 LOOP-PROMPT 的一页路由）常已足够。

1. 三判据闸门（references/decide-and-design.md §1）：重复出现≥3次 / 每次跑偏

或要重复解释 / 有可验收交付物。任一不满足 → 明确劝退，不写。没有真实 case 就先让用户裸跑收集，Baseline 先行。过闸后固定问一句参考物："有没有现成的 好例子——满意的产出/喜欢的同类 skill/类似实现？"（一个参考物顶几百字需求描述， 直接读原件反推规范）；用户对该领域不熟时，先做一轮盲点扫描（列出这类 skill 的经典坑与行家问题）再进设计。

1. 选骨架（4 选 1）+ 叠加工作流模式（6+1），走 §2 的两棵决策树。
2. 评测先行：先写 evals/evals.json（core/edge/gotcha 三类，见

references/evals.md）；纪律型 skill 另加压力场景基线（先裸跑记录借口 原话，见 references/pressure-testing.md），再写"让评测通过的最小 skill"。

1. 按 references/templates.md 对应模板填空；正文写法遵守

references/writing.md（祈使句、为什么、检查点、防偷懒四武器）。

1. 交付前过 references/launch-checklist.md 全表（Description 四原则 + 20 问测试

• 反模式 11 条 + 四维自测），任一红项不交付。

检查点（可直接运行）：python scripts/check-limits.py → 预期 "status": "ok"（core≥5 / description≤1024 / 正文≤500 行 全部达标才 ok）。

Task B：修改

铁规：改动之前先确认 evals 存在（没有就先按 Task A 第 3 步补建），改动之后 必须回归——在 evals/iteration-N+1/ 重跑、不覆盖旧结果、对比通过率（目标问题 改善 + 其他用例无退步）。版本号按 references/lifecycle.md §版本控制升级，改动 原因记入 CHANGELOG。遇到的每个真实失败追加为 gotcha 用例，而不是重写 skill。

检查点：iteration-N+1 结果落盘且无回归；版本号已升。

Task C：诊断

按 references/troubleshooting.md 的排查顺序走（70% 的问题在前两步：加载了吗、 description 对得上用户原话吗）。触发类问题优先动 description（补触发词/加排除 边界）；执行类问题定位跑偏的那一步（加祈使句/借口反驳表/负面指令/为什么）； 多 skill 抢单按"给其中一方加排除说明"处理。修完按 Task B 回归。

Task D：合并 / 拆分

按 references/decide-and-design.md §2.3 粒度信号 判断：正文超 300/500 行、多个 独立工作流、改动频率差异大 → 拆（主 SKILL.md 只留路由表）；两个 skill 触发准确率都 <80% 且 description 语义重叠 → 先试排除边界，仍打架再合并（保留更清晰的那个）。合并/拆分 后 evals 两边都要迁移并回归。

Task E：退役

对照 references/lifecycle.md §退役信号（模型原生已覆盖 / 维护成本超收益 / 场景 已消失 / 与新 skill 大量重叠）。默认归档而非直接删除（移出 skills 目录保留 副本），删除前向用户复述该 skill 现状并确认。退役不是失败——是清理路由噪声、 省上下文税。

全局安全红线（所有 Task 适用）

1. 没过三判据不写 skill——写出来就是路由噪声，负收益。
2. 无回归不改 skill——改了 A 坏了 B 是最常见事故。
3. 不删未归档的 skill；删除/覆盖第三方 skill 前必须用户确认。
4. description ≤1024 字符，必含触发词与排除边界；正文 ≤500 行，超了下沉。
5. gotcha 只记真实发生过的失败，不猜。
6. 本 skill 产出的是 skill 工件本身；除非用户明确要求，不代跑目标 skill 的业务。

借口反驳表

| 可能的偷懒 | 为什么不行 | |---|---| | "场景很清楚，跳过三判据直接写" | 三判据挡掉的是"万能助手 Skill"这种最常见的失败开局。两分钟自查，换一个不进坟场的 skill。 | | "先写 skill，评测以后补" | 评测先行是写法顺序的根本：skill 是"让评测通过的最小实现"。后补的评测只会迁就已写的实现。 | | "小改一行，不用跑回归" | 改了 A 坏了 B 恰恰都发生在"小改"上。iteration-N 对比就是为此存在的。 | | "description 差不多就行" | Description 写好等于成功一半；20 问测试 <85% 的 skill 上线就是误触发制造机。 | | "直接把这个没用的 skill 删了" | 先归档、先确认。删除不可逆，而"没用"的判断可能来自不完整的观察。 |

References（引用契约：触发条件 → 预期产出 → 检查点）

| 文件 | 触发条件 | 预期产出 | 检查点 | |---|---|---|---| | references/decide-and-design.md | Task A 起步 / Task D 粒度判断 | 三判据结论 + 骨架与模式选型（各带理由） | 三判据表已填且全勾才继续 | | references/writing.md | 写/改 description 或正文时 | 符合四原则的 description + 六写法正文 | 20 问测试 ≥85%（新会话跑） | | references/templates.md | 骨架选定后 | 按模板填空的 SKILL.md 初稿 | 无残留 [...] 占位符 | | references/evals.md | Task A 第 3 步 / Task B 改前 | evals/evals.json（core/edge/gotcha） | python scripts/check-limits.py → core≥5 | | references/launch-checklist.md | 交付前 | 全表勾选记录 | 任一红项不交付 | | references/troubleshooting.md | Task C | 定位到的故障层 + 修复动作 | 修后按 Task B 回归 | | references/pressure-testing.md | 纪律型 skill 的测试/加固；写改 description 时 | 压力场景基线（借口原话）+ 防弹三件套；CSO 合规的 description | 纪律型：最大压力下仍守规；description 无工作流摘要 | | references/lifecycle.md | Task B 版本 / Task D/E | 版本号变更 / 合并方案 / 退役流程记录 | 归档副本存在才可删 |

Scripts & Examples

• scripts/check-limits.py — 确定性核对（description 字数 / 正文行数 / core 用例

数），输出 JSON。数数的事不让 LLM 干。

• examples/weekly-report-standard/ — 用本方法论产出的完整小示例（骨架 C 规范型

skill + evals），写新 skill 时对照它的完成形态。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: VioletScar-Hui
• Source: VioletScar-Hui/BuildGreat_Loop
• License: MIT

Install and usage instructions live in the source repository linked above.