LeMetaSkill v1.1.0：跨 runtime（ZCode/Claude Code/Codex）的 Agent Skill 创建与迭代工坊

- SKILL.md 双工作流（创建/迭代）+ 两道门（验料/通用化）+ 三档位 - 7 篇方法论 references + 3 个纯标准库脚本（scaffold/validate/trigger_eval） - 自身触发用例 16 条 + 先例研究/创建/迭代证据报告 - 方法论吸收自 qiaomu-meta-skill 与 luban-skill，取舍见 reports/prior-art.md
2026-10-05 12:09:22 +08:00
commit d3e9bd45bd
21 changed files with 1827 additions and 0 deletions
@@ -0,0 +1,74 @@
+# 迭代工坊——改进已有 Skill
+
+改一个 skill，比新建一个更容易翻车：它已经有用户（哪怕用户只有 Leroy 自己），改坏了触发就断了。迭代的核心纪律是**可回退、可比较、单面推进**。
+
+## 第一步：冻结基线
+
+动任何刨子之前：
+
+- 有 git：开分支或记录当前 commit；
+- 没 git：`cp -r <skill> <项目根>/.baseline/<skill>-<日期>/`。
+
+两条纪律（实战教训）：
+
+1. **基线必须放在发现路径之外。** 放进 `.agents/skills/` 或 `~/.claude/skills/` 里的基线副本会被 runtime 当成另一个 skill 发现，制造幽灵触发。
+2. **复制完立即验证。** `head` 一下基线的 SKILL.md 确认是旧版本——有些执行环境里文件写入跨调用不可靠，没验证过的基线等于没有基线。
+
+之后所有候选改动都与基线比。基线是裁判，不是怀旧品。
+
+## 第二步：诊断三把尺
+
+| 尺 | 量什么 | 怎么量 |
+|---|---|---|
+| 结构尺 | 写得清不清楚 | `python3 scripts/validate_skill.py <目录>`，FAIL/WARN 直接转差距条目 |
+| 触发尺 | 该触发时触不触发、不该触发时误不误伤 | `python3 scripts/trigger_eval.py <目录>` + 真实对话原话抽测 |
+| 活体尺 | 真实任务里跑不跑得出结果 | 拿 2–3 个真实任务实际用一遍。"看起来能触发"不等于"跑得出结果"——静默失败比文档烂致命 |
+
+**活体尺最常被跳过，也最值钱。** 大部分真问题（输出格式其实不稳定、某个步骤总卡住、引用的脚本跑不通）只有真实运行才暴露。
+
+## 第三步：六维评分，定位最该刨的面
+
+每维 0–10 分，**每个分数必须给证据**（哪条用例、哪次运行、哪行源码），凭手感打分作废：
+
+| 维度 | 权重 | 量什么 |
+|---|---:|---|
+| 触发与边界 | 25 | description 覆盖、负触发、误伤/漏触发记录 |
+| 可执行具体性 | 20 | 步骤是否可直接照做、示例是否字面可用 |
+| 工作流清晰度 | 15 | 分步结构、何时读哪个 reference |
+| 失败模式与停手点 | 15 | 出错怎么办、何时问用户，有没有编码 |
+| 实测表现 | 15 | 活体尺结果 |
+| 资源纪律 | 10 | 有没有不承重的文件、悬空引用、超长正文 |
+
+总分不是用来攀比的，是用来**排序**的：最低分且权重高的维度，就是本轮唯一要刨的面。
+
+## 第四步：单面慢刨
+
+- 一轮只改一个面（只修触发、或只重构工作流、或只补失败模式）。
+- 用户批量授权（"都修了吧"）后，升级为**单面单提交**——每个改动独立过验证门，绝不把两个面塞进一次改动。
+- 改动前先写下：本轮只刨 X；改动边界：只改 X，不动 Y；预期提升是什么。
+
+## 第五步：验证门
+
+候选改动**全部满足**才保留，否则回刀（恢复基线，重新想）：
+
+1. 比基线**多通过**至少 2 条测试原话（触发用例或真实任务）；
+2. 没有把 skill 写得更长但更难用——行数增加必须换来可执行性；
+3. 没有引入私有路径、密钥、不可复现依赖；
+4. 没有破坏原有通过项——基线能过而现在过不了的，是退化；
+5. 通过 `validate_skill.py` 全绿。
+
+验收时换**独立验收视角**：假装是第一次见到这个 skill 的陌生模型，只读交付物，不知道改动过程。刨子和尺子不能握在同一只手里。
+
+## 第六步：交付与回炉
+
+交付改动报告（改了哪个面、验证证据、行数变化），并留**回炉清单**：
+
+- 本轮"不做"的事和理由（下一轮入口）；
+- 已知边界损耗（哪些用例还是过不了）；
+- 沉淀机会：这次手写的验证手段，值得固化成 `scripts/` 工具或 `evals/` 用例吗？值得就顺手沉淀——验证不是脚手架，是交付物的一部分。
+
+## 迭代时机
+
+- 用户带着"它又翻车了"的原话回来 → 先把原话收编成用例，再修。
+- 隔了一个月没动 → 先跑三把尺再决定刨哪里，不要凭上次印象。
+- 多次小修仍不稳 → 怀疑是定位问题（验料没做对），回到第一道门重新定位，而不是继续打补丁。