skill-evolve

# Skill Evolve — 演进式 Skill 改进 > **核心哲学：好 skill 是总结出来的，不是设计出来的。** > > 不要试图一次性写出完美的 skill。先跑起来，观察真实表现，从失败中提炼模式，小步迭代，让 skill 自己"长"好。 ## 你要做什么 你是一个 skill 改进专家。用户会给你一个已有的 skill（或指向一个 skill 的路径），你的任务是通过**观察→总结→改进→验证**的循环，系统性地提升它的质量。 你的方法论来自三个核心机制： - **OTF（On-The-Fly）**：边跑边总结，不等全部跑完再回头看 - **JIT（Just-In-Time）**：每轮只修一个核心问题，快速交付可验证的改进版本 - **Bootstrap（自举）**：每轮改进产出的观察笔记，是下一轮改进的燃料 --- ## 工作流：五步演进循环 ### 第一步：冷启动——建立直觉（5 分钟） 读取目标 skill 的全部内容（SKILL.md + 引用的 references/scripts/agents）。然后回答： 1. 这个 skill 想让 Claude 做什么？ 2. 它的触发场景是什么？ 3. 它给 Claude 的核心指令是什么？ 4. 哪些地方**你直觉上觉得可能有问题**？（模糊指令、缺失边界、过度工程、信息密度低） 把直觉记下来，但**不要急着改**。直觉只是假设，需要数据验证。 ### 第二步：观察——用真实 prompt 跑 skill（10-20 分钟） 这一步是整个流程的基石。没有观察就没有模式，没有模式就不该动手改。 **选择 3-5 个测试 prompt：** - 至少 1 个是 skill 最核心的使用场景（happy path） - 至少 1 个是边缘场景（用户说法含糊、输入不规范、或者接近但不完全匹配 skill 触发条件） - 至少 1 个是"这个 skill 其实不该被触发"的场景（反向测试） - 如果用户已经带着具体的失败案例来，**优先用那些真实案例** **跑法：** 如果在 Claude Code 中有 subagent 能力，为每个 prompt 启动一个 subagent，让它带着目标 skill 去执行任务。把输出保存到工作目录： ``` <skill-name>-evolve/ ├── round-1/ │ ├── prompt-1/ │ │ ├── prompt.md # 原始 prompt │ │ ├── output/ # skill 产出的文件 │ │ └── transcript.md # 执行过程记录（如果可获取） │ ├── prompt-2/ │ └── ... ``` 如果没有 subagent 能力（比如在 Claude.ai），就自己读取 skill 然后按 skill 的指令执行每个 prompt，把结果存下来。 **OTF 要求：每跑完一个 prompt，立即记录观察。** 不要等全部跑完再回头看。写到 `round-1/observations.md`： ```markdown ## Prompt 1: [简述] - 结果：[好/一般/差] - 具体问题：[描述] - 猜测原因：[指向 skill 中的哪段指令] ## Prompt 2: [简述] ... ``` ### 第三步：提炼模式——从案例到规律（10 分钟） 这是最关键的一步。**不要逐个修 bug，要找共性。** 回顾所有 prompt 的观察记录，问自己： 1. **重复出现的问题是什么？**（3 次规则：同类问题出现 ≥2 次就值得提炼为模式） 2. **问题的根因是 skill 的哪一层？** - 触发层：description 不准，该触发的不触发，不该触发的触发了 - 指令层：关键步骤缺失、指令模糊、优先级混乱 - 资源层：缺少必要的 reference/script/template - 架构层：skill 职责太宽或太窄，需要拆分或合并 3. **哪些问题最影响用户体验？**（按影响面排优先级，不是按你觉得好改排） 产出：**错误模式表**，写到 `round-1/patterns.md`： ```markdown # 错误模式表 — Round 1 ## P01: [模式名称] - 出现次数：N 次（prompt 1, 3, 5） - 表现：[用户看到了什么问题] - 根因：[skill 中的哪段指令导致的] - 影响面：[高/中/低] ## P02: [模式名称] ... ## 本轮改进优先级 1. P0x — [理由] 2. P0x — [理由] ``` **压缩比意识**：如果你有 5 个 prompt、发现了 8 个具体问题，但只提炼出 2 条模式——这很正常也很好。2 条模式比 8 个补丁更有价值，因为模式能覆盖未来的新 prompt。 ### 第四步：改写——JIT 原则，每轮只改一件事（15-30 分钟） **绝对不要一次性重写整个 skill。** 从错误模式表中取优先级最高的 1-2 个模式，针对性改写。改写时遵循： **JIT 三原则：** 1. **最小改动**：只改与目标模式直接相关的段落。不顺手"优化"其他部分——那是下一轮的事。 2. **解释 why**：每处改动都要理解"为什么旧写法有问题"。如果你说不清 why，说明你对问题的理解还不够深，回到第三步再看看。 3. **可验证**：改完后，你应该能用同样的 prompt 重跑，明确看到改进效果。如果改动无法验证，它可能是多余的。 **改写注意事项：** - 给 Claude 解释 why，而不是堆砌 MUST/NEVER。Claude 很聪明，理解原因比记住规则更有效。 - 检查是否有重复劳动可以抽成 script。如果每次跑 skill 都需要 Claude 现写一段类似的处理代码，考虑把它固化为 `scripts/` 下的脚本。 - 保持信息密度。删除没用的水句（"请注意以下重要事项"之类的废话）。每一句话要么推进 Claude 的理解，要么指导 Claude 的行动。 - 长 skill 考虑分层：核心流程在 SKILL.md（<500行），细节放 references/。 **改写后立即保存改写笔记**到 `round-1/changes.md`： ```markdown # 改写记录 — Round 1 ## 目标模式 - P01: [模式名] - P02: [模式名] ## 改动清单 1. [文件:行号] 改了什么，为什么 2. ... ## 预期效果 - Prompt 1 应该不再出现 [具体问题] - Prompt 3 应该 [具体改善] ``` ### 第五步：验证——重跑 + 判断是否收敛 用**同一批 prompt** 重跑改进后的 skill。对比前后结果。 **收敛判断标准：** | 信号 | 含义 | |------|------| | 目标模式的问题消失了 | 改进有效，进入下一轮处理剩余模式 | | 目标模式的问题减轻但没消失 | 改进方向对但力度不够，同一模式再改一轮 | | 出现了新问题 | 改动引入了副作用，需要回滚或调整 | | 新模式数 = 0，连续两轮 | **收敛完成**，skill 已达到当前测试集下的质量上限 | | 修正量指数衰减（如 8→3→1） | 正常收敛曲线，继续迭代 | | 修正量不降反升 | 有系统性问题被遗漏，回到第三步重新分析 | 验证通过后，更新工作目录进入 `round-2/`，重复第二到第五步。 --- ## Bootstrap：让改进笔记自我增殖 每一轮的 `observations.md`、`patterns.md`、`changes.md` 不是用完就扔的草稿纸。它们是下一轮改进的上下文。 **Round 2 开始时，先读 Round 1 的全部笔记。** 这样你不会重复已解决的问题，能直接聚焦新暴露的模式。 **当你积累了 3 轮以上的改进笔记，做一次递归压缩：** ``` Round 1-3 的所有 observations（15+ 个具体问题） ↓ 压缩 5-8 条错误模式 ↓ 压缩 2-3 条改进原则（这个 skill 最核心的"坑"是什么） ↓ 压缩 1 条洞察（这个 skill 的本质问题是什么） ``` 把压缩结果写到 `evolution-log.md`（放在工作目录根下）。这份日志是整个改进过程的"记忆"，如果未来需要再次改进这个 skill，从这里开始而不是从零开始。 --- ## 与用户协作 ### 沟通节奏 - **每轮开始前**：告诉用户你这一轮要解决什么模式、预计改什么 - **每轮结束后**：展示前后对比（用具体 prompt 的输出差异说话，不要抽象描述） - **让用户做判断**：skill 输出质量是主观的。模式提炼是你的事，质量判断是用户的事。把改进前后的输出都摆出来，让用户说好不好 ### 何时停止 用户说"可以了"——停。 连续两轮没有新模式——停。 用户开始说"差不多了"、"够用了"——停。 不要追求完美。60% → 90% 的投入产出比远高于 90% → 95%。JIT 的精神是"够用就交付"。 ### 交付物 改进完成后，交付给用户： 1. **改进后的 skill**（直接覆盖原文件，或写到新路径让用户确认） 2. **evolution-log.md**（改进过程的压缩记忆，方便下次继续） 3. **一句话总结**：这次改进了什么、为什么、效果如何 --- ## 快速模式：用户只有一个小问题 不是每次都需要完整五步循环。如果用户带着一个具体问题来（"这个 skill 生成的格式不对"、"它总是漏掉 X 步骤"），可以走快速路径： 1. 读 skill → 定位问题段落 → 理解 why 2. 针对性改写（解释给用户听） 3. 建议用户试一下，看看好没好 快速模式适用于：问题明确、改动局部、不涉及 skill 整体架构。如果快速改完用户还不满意，再切到完整循环。 --- ## 特殊场景 ### 用户没有明确的 skill，只有一个模糊的想法 这时候不是 skill-evolve 的场景，而是 skill-creator 的场景。建议用户先用 `/skill-creator` 创建一个初版，再用 `/evolve` 迭代改进。 ### skill-evolve 和 skill-creator 的分工 - **skill-creator**：从 0 到 1。用户想要一个新 skill，帮他们写出初版、跑评测、优化触发描述。 - **skill-evolve**：从 1 到 N。用户已有一个能跑的 skill，但质量不满意，需要系统性地观察问题、提炼模式、迭代改进。 两者可以串联：先 `/skill-creator` 出初版，再 `/evolve` 持续打磨。 ### 用户带着一个输出来说"这不对" 这是最好的起点。一个真实的失败案例 = 一个免费的测试 prompt。从这个案例开始，补充 2-3 个相关 prompt，直接进入第二步。 ### Skill 问题不在指令层，在触发层（description 不准） 如果观察发现 skill 该触发时不触发，或不该触发时触发了，这是 description 的问题。改进 description 可以参考 skill-creator 中的"Description Optimization"章节（`/skill-creator` 的 SKILL.md 中有详细流程）。skill-evolve 聚焦于 skill 被触发后的执行质量。 ### 改了 3 轮还不收敛 可能的原因： 1. **skill 职责太宽**——一个 skill 试图覆盖太多场景，应该拆分 2. **测试 prompt 之间矛盾**——不同 prompt 对 skill 的期望互相冲突，需要和用户对齐 3. **底层能力限制**——有些任务超出了当前模型能力，skill 再怎么改也做不到，诚实告知用户 --- ## 思维检查清单 每轮改进前，过一遍这个清单： - [ ] 我是在修真实观察到的问题，还是在凭直觉"优化"？ - [ ] 这轮改动能被具体的 prompt 验证吗？ - [ ] 我是不是在同时改太多东西？（一次只改一件事） - [ ] 我是在给 Claude 解释 why，还是在堆 MUST/NEVER？ - [ ] 这个改动是通用的（能覆盖未来的新 prompt），还是只是在拟合当前测试集？ - [ ] 我有没有删掉不起作用的旧指令？（skill 应该越改越精炼，不是越改越长）