chore: import zh skill skillforge

2026-07-13 21:35:31 +08:00
commit 3641661ee7
4 changed files with 450 additions and 0 deletions
@@ -0,0 +1,9 @@
+# WeHub 来源说明
+
+- Skill 名称：`skillforge`
+- 中文类目：框架约束型 skill bundle 创作
+- 上游仓库：`ngmeyer__skills`
+- 上游路径：`skills/productivity/skillforge/SKILL.md`
+- 上游链接：https://github.com/ngmeyer/skills/blob/HEAD/skills/productivity/skillforge/SKILL.md
+- 本仓库为 WeHub 中文 Skill 汉化包，基于 skill 市场筛选 Top200 清单整理
+- 原作者、版权和许可证信息以上游仓库为准
@@ -0,0 +1,171 @@
+---
+name: skillforge
+description: 打造新的 Claude Code 技能，或将现有技能优化至 V2 版本。两种模式 —— `forge` 用于搭建新技能（frontmatter、渐进式信息披露、辅助脚本、必选 Gotchas、先迭代后提取）；`optimize` 使现有技能在其**目标效果**上实现可量化的提升（而非仅改善包装）。当用户想要创建、编写、构建、搭建、改进、升级或优化技能时使用。
+license: MIT
+---
+
+# Skillforge —— 以正确方式编写和优化 Claude Code 技能
+
+如需获取 Anthropic 官方权威指南（frontmatter 字段、500 行预算限制、动态上下文注入、测试框架、反模式、9 种技能类型、5 种工作流模式），请加载：[references/anthropic-skill-best-practices.md](references/anthropic-skill-best-practices.md)。
+
+## 两种模式
+
+| 模式 | 适用场景 | 输出结果 |
+|---|---|---|
+| **forge**（默认） | 尚不存在的全新技能 | 按以下流程起草的新技能目录 |
+| **optimize** | 现有技能虽能工作但需要改进 | 该技能的 **V2** 版本 —— 在*目标效果*上实现可量化提升 |
+
+**`forge`** 遵循本文件其余部分所述的流程 + 检查清单。
+
+**`optimize <skill>`** 运行一个以指标驱动的循环：定义目标效果 + 指标 → **设置关卡（含防止作弊的审计）** → 质量审计 → 调研该领域以获取改进目标效果的技术 → 综合产出 V2 版本及变更日志 → 在**独立的保留测试基准（而非单个示例）** 上验证 V2 是否优于 V1，丢弃任何未通过关卡的后选方案。"优化"而非"整理"：未推动目标效果改善的清理工作不能算作 V2；通过玩弄评分标准获得的高分属于倒退。该循环为自包含方案；对于重负载运行（大量假设、并行实验、耗时数小时），你*可选用*外部优化器（如 `ce-optimize` 插件、`evo` 或微软的 `SkillOpt`）进行升级。完整操作手册见：[references/optimize-mode.md](references/optimize-mode.md)。
+
+## 元流程：先迭代，后提取
+
+Anthropic 推荐的创建流程：*先在单个具有挑战性的任务上反复迭代，直到 Claude 成功完成，然后将胜出的方法提取为技能。* 不要为假想的未来需求编写技能。在对话中解决真实问题，找到有效的提示词 + 上下文组合，然后将其固化。
+
+## 流程
+
+1. **收集需求** —— 询问用户：
+   - 该技能涵盖什么任务/领域？
+   - 应处理哪些具体用例？（举一个真实的近期示例。）
+   - 需要可执行脚本，还是仅需指令？
+   - 是否包含任何参考资料？
+   - 是否有任何副作用（部署、提交、发送消息）？→ 设置 `disable-model-invocation: true`
+   - 哪些工具通常会触发权限提示？→ 在 `allowed-tools:` 中列出
+
+2. **起草技能** —— 创建：
+   - SKILL.md 文件，包含简洁的指令（本地目标 ≤100 行；Anthropic 公开上限为 500 行）
+   - `references/` 目录下的文件，存放无需每次调用都加载的详细信息
+   - `scripts/` 目录下的确定性辅助脚本（排序、校验、格式转换）
+
+3. **与用户一起审查** —— 展示草稿并询问：
+   - 是否覆盖了你的用例？
+   - 是否有遗漏或不清晰之处？
+   - 是否有任何章节需要更详细或更简略？
+
+## 技能目录结构
+
+```
+skill-name/
+├── SKILL.md           # 主指令文件（必需）
+├── REFERENCE.md       # 详细文档（可选）
+├── EXAMPLES.md        # 使用示例（可选）
+└── scripts/           # 工具脚本（可选）
+    └── helper.js
+```
+
+## SKILL.md 模板
+
+```md
+---
+name: skill-name
+description: 简短描述该功能。当 [特定触发条件] 时使用。
+---
+
+# 技能名称
+
+## 快速开始
+
+[最小可行示例]
+
+## 工作流
+
+[针对复杂任务的分步流程及检查清单]
+
+## 高级功能
+
+[链接到独立文件：参见 [REFERENCE.md](REFERENCE.md)]
+```
+
+## 描述（Description）要求
+
+描述是**你的智能体在决定加载哪个技能时唯一能看到的信息**。它与其他所有已安装技能的描述一起出现在系统提示中。你的智能体读取这些描述，并根据用户的请求选择相关的技能。
+
+**目标**：让你的智能体拥有足够的信息来判断：
+
+1. 该技能提供了什么能力
+2. 何时/为什么触发它（具体关键词、上下文、文件类型）
+
+**格式**：
+
+- 最多 1,536 个字符（`description` + `when_to_use` 合计）
+- 以第三人称编写
+- 第一句：该技能的功能
+- 第二句："当 [具体触发条件] 时使用"
+- **反模式**：叙述性概括（"该技能可执行 A、B、C 三项功能"）无法通过路由测试。请编写决策规则。
+
+**好的示例**：
+
+```
+从 PDF 文件中提取文本和表格、填写表单、合并文档。当处理 PDF 文件或用户提及 PDF、表单或文档提取时使用。
+```
+
+**差的示例**：
+
+```
+帮助处理文档。
+```
+
+差的示例让你的智能体无法将这项技能与其他文档类技能区分开来。
+
+## 何时添加脚本
+
+在以下情况添加工具脚本：
+
+- 操作为确定性的（校验、格式化）
+- 同一段代码会被重复生成
+- 需要显式处理错误
+
+与生成式代码相比，脚本可节省 token 并提高可靠性。
+
+## 何时拆分文件
+
+在以下情况将内容拆分为多个文件：
+
+- SKILL.md 超过 100 行
+- 内容涉及不同领域（如财务与销售模式）
+- 高级功能很少使用
+
+## Gotchas 部分（生产级技能必选）
+
+Anthropic 指出：*"这是任何技能中信号价值最高的内容 —— 是 60% 可靠性到 95% 可靠性的差距所在。"* 应从真实失败中构建，而非靠预判。一条失败模式 + 一条解决方法。每次重复出现失误时更新。没有 Gotchas 部分的生产级技能等于白白放弃了可靠性提升的机会。
+
+## 测试技能
+
+按 Anthropic 的建议分为三个阶段：
+
+1. **触发测试** —— 它是否在应该触发时触发？在不应触发时*不*触发？（在触发条件内和条件外分别测试提示词。）
+2. **功能测试** —— 给定已知输入，是否产生预期输出？是否处理了边界情况？
+3. **性能测试** —— 有技能与无技能情况下执行相同任务的结果对比。如果使用技能未能优于不使用技能，则该技能不值得占据槽位。
+
+## 审查检查清单
+
+起草完成后，请验证：
+
+- [ ] 描述中包含触发条件（"当……时使用"），且不超过 1,536 个字符
+- [ ] SKILL.md 在 100 行以内（本地目标；Anthropic 公开上限为 500 行）
+- [ ] 如果技能需要特定工具，frontmatter 中声明了 `allowed-tools`
+- [ ] 如果技能有副作用，已设置 `disable-model-invocation: true`
+- [ ] Gotchas 部分已存在（或标注为 TODO 及首次失败记录）
+- [ ] 不包含时效性信息
+- [ ] 术语一致
+- [ ] 包含具体示例
+- [ ] 引用深度为一层
+- [ ] 技能名称中不含 `claude` 或 `anthropic`；目录中不含 `README.md`
+
+## 变更日志
+
+### V2.2（2026-05-29）—— 新增 SkillOpt + 训练/验证集划分
+- 新增 **Microsoft SkillOpt**（[MIT 协议，arXiv 2605.23904](https://arxiv.org/abs/2605.23904)）作为第三个可选的外部升级方案，与 `ce-optimize` 和 `evo` 并列。SkillOpt 以神经网络风格（轮次 / 小批量 / 验证关卡）在标准化基准（SearchQA、ALFWorld、DocVQA、SpreadsheetBench、OfficeQA）上训练 Markdown 技能。最适用于基准驱动的严谨场景；ce-optimize 适用于会话内工作流；evo 适用于并行/树搜索架构。
+- **强化了验证步骤（#6）的训练/验证集划分** —— 将保留测试基准分为调优子集（迭代可能过拟合于此）和验证子集（变更过程从未见过）。如果验证效果下降而调优效果提升，说明变更已过拟合；予以丢弃。借鉴自 SkillOpt 的规范方法。
+- 诚实地将手工循环重新定义为："一轮、批次大小为 1" —— 小型、快速，适用于单技能 V2 版本；需要真正的训练时请升级。
+
+### V2.1（2026-05-28）—— 融合 ce-optimize 规范
+通过融合 **`ce-optimize`**（CE 插件）和 **`evo`**（[alokbishoyi97](https://x.com/alokbishoyi97/status/2059610305408462898)，evo-hq.com）的指标驱动严谨性，对 `optimize` 模式进行了演进：
+- 新增**关卡**步骤（退化关卡 + **防作弊审计** + 保留测试检查）—— 丢弃任何未通过关卡的后选方案，即使其得分最高。堵住了之前循环中"评分可被利用"的漏洞。
+- 验证现在使用**独立的保留测试基准（约 10–20 个任务），而非单个示例** —— 修复了委员会审查 A/B 对比中 N=1 的弱点。
+- 新增**可选的外部升级方案**：对于重负载运行（大量假设 / 并行实验 / 耗时数小时），可选用外部优化器（`ce-optimize` 插件或 `evo`，evo-hq.com）进行升级（如果已安装）；skillforge 保持自包含，并保留独有的目标效果调研 + 技能质量审计前端。
+
+### V2（2026-05-27）
+- 新增 **`optimize` 模式**（新建技能 vs 将现有技能优化至 V2）。优化模式运行一个以指标驱动的循环 —— 定义目标效果 + 指标、质量审计、领域目标效果调研、综合产出 V2 版本 + 变更日志、验证 V2 优于 V1 —— 因此"V2"必须在*目标效果*上实现可量化提升，而非仅改善包装。操作手册：`references/optimize-mode.md`。
+- 在 7 个技能上进行了自验证（委员会审查试点 + 6 技能批次），这也正是 skillforge 从 `in-progress/` 目录晋升的原因。
@@ -0,0 +1,184 @@
+# Anthropic Skill 最佳实践 — 参考手册
+
+源自 Anthropic 官方文档、工程博客以及 [github.com/anthropics/skills](https://github.com/anthropics/skills) 中 17 个参考技能的权威技能编写指南。在编写或改进技能时加载本文档。
+
+## 来源
+
+- **Anthropic 官方文档** — [Claude Code Skills](https://code.claude.com/docs/en/skills.md)
+- **Anthropic 工程博客** — [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
+- **Anthropic 完整指南** — [The Complete Guide to Building Skills for Claude（33 页 PDF）](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf)
+- **Anthropic 参考技能** — [github.com/anthropics/skills](https://github.com/anthropics/skills)
+- **Anthropic 实践者讨论帖** — [@trq212 2026 年 3 月](https://x.com/trq212/status/2033949937936085378)
+
+## 三级渐进式披露（核心原则）
+
+| 层级 | 内容 | 加载时机 | Token 开销 |
+|---|---|---|---|
+| 1. Frontmatter | `name` + `description` | 始终加载——Claude 扫描以判断相关性 | ~100 tokens |
+| 2. SKILL.md 正文 | 完整指令 | 当 Claude 判定技能与任务匹配时 | 最多约 5K tokens |
+| 3. 链接文件 | `references/`、`scripts/`、`assets/` | 执行期间按需加载 | 仅读取的部分 |
+
+这就是"技能数量对上下文影响极小"的原因——只有 frontmatter 是始终加载的。**将参考文档塞入 SKILL.md 会增加每次调用的 token 开销。** 将详细内容移至 `references/`。
+
+## Frontmatter 字段
+
+### 必填 / 强烈推荐
+
+```yaml
+---
+name: skill-name              # 小写、连字符、≤64 字符；必须与文件夹名一致
+description: |                # 与 `when_to_use` 合计 ≤1,536 字符；路由信号
+  What it does. Use when [specific trigger phrases].
+---
+```
+
+**Description 必须是路由规则，而非摘要。** Anthropic 的反模式提醒：不要写 *"This skill helps with X."* 而要写 *"Use when the user asks for X, or when working with Y file types."* 包含用户自然会说出的关键词。第一句：做什么。第二句：何时用。
+
+### 高价值可选字段
+
+| 字段 | 使用场景 | 效果 |
+|---|---|---|
+| `allowed-tools:` | 技能需要特定工具，否则会触发权限提示 | 预批准所列工具（如 `[Read, Edit, Bash]`）；消除操作摩擦 |
+| `disable-model-invocation: true` | 技能有副作用（部署、提交、发送消息、发布到 Slack） | 阻止 Claude 自动调用——用户必须显式调用 |
+| `context: fork` | 技能应在隔离环境中运行（研究、探索、任何会污染历史记录的操作） | 在子代理中执行，主对话保持干净 |
+| `version: x.y.z` | 技能有版本管理且希望历史可见 | 在技能列表中显示版本 |
+| `license: MIT` | 开源技能 | 在列表中显示许可证 |
+
+`allowed-tools` 是大多数本地技能遗漏的字段。添加它可以消除本会反复触发的逐个工具权限提示。
+
+## SKILL.md 大小预算
+
+Anthropic 的公开指南：SKILL.md **≤500 行**。超出预算时将参考资料移至独立文件。
+
+我们的本地约定更严格：**≤100 行**。更严格的目标是有意为之的自我约束——大多数技能不需要 500 行，更短的 SKILL.md 在调用时加载更快。超出本地预算时，拆分为 `references/` 文件。
+
+无论哪种方式，判断标准是逐行检验：*删除这一行是否会改变 Claude 的行为？* 如果不会，删掉。如果会，保留。
+
+## 技能文件夹结构
+
+```
+skill-name/
+├── SKILL.md            # 入口文件（必需，文件名严格区分大小写）
+├── references/         # 按需加载的详细文档
+│   ├── api.md
+│   └── examples.md
+├── assets/             # 模板、夹具、模式
+│   └── template.md
+├── scripts/            # Claude 可调用的确定性辅助脚本
+│   └── helper.py
+└── config.json         # 技能持久状态（可选）
+```
+
+硬性规则：
+- 文件夹名使用 kebab-case（`brand-voice` ✓ — `Brand_Voice` ✗）
+- `SKILL.md` 文件名精确且区分大小写
+- **技能文件夹内不能有 `README.md`**——会混淆 Claude 的加载器
+- 技能名称中不能包含 `claude` 或 `anthropic`（保留字段）
+- Frontmatter 中不能有 XML 标签（安全原因）
+- 引用最多一层深度——不要嵌套 `references/sub/file.md`
+
+## 动态上下文注入
+
+Anthropic 的 `summarize-changes` 参考技能演示了该模式：
+
+```yaml
+---
+description: Summarizes uncommitted changes and flags anything risky.
+  Use when the user asks what changed, wants a commit message, or asks to review their diff.
+---
+
+Run this command to see the current diff: !`git diff HEAD`
+
+[then your instructions reference the inlined diff]
+```
+
+`` !`command` `` 语法在技能调用时执行 shell 命令并将输出内联进来。结果是：SKILL.md 正文保持短小，但 Claude 看到的却是最新的运行时状态。对于任何涉及 git、文件列表、进程状态、环境变量或其他运行时可查询数据的技能，都应使用此方法。既保持常驻开销低廉，又保证调用时上下文新鲜。
+
+## 必填章节：Gotchas
+
+Anthropic 实践者指南：*"Gotchas 章节是所有技能中信号密度最高的内容——从真实的失败案例中构建，并持续更新。这是从 60% 可靠性到 95% 可靠性的差距所在。"*
+
+在技能实际遇到边界情况后再构建该章节。不要试图提前预判。每条记录：一行失败模式 + 一行解决方案。每次遇到重复的失误时更新。
+
+示例：
+```markdown
+## Gotchas
+
+- **符号链接的 vault 路径** — vault 可能位于外部驱动器上。如果 `os.path.realpath` 返回 `/Volumes/...`，路径本身没问题，但 `git -C` 会失败，因为符号链接的目录不受跟踪。文件系统操作使用解析后的路径，其他操作使用符号链接路径。
+- **ChatGPT 来源文本中的弯引号与直引号** — 来自 ChatGPT 的文本通常包含"智能"引号，这会破坏 grep 和下游字符串匹配。先运行一次规范化处理。
+```
+
+如果一个技能已在生产环境中使用却没有 Gotchas 章节，那它就是不完整的。当它第一次让你意外时，记录下来。
+
+## 辅助脚本：何时捆绑代码
+
+在以下情况下捆绑脚本（`scripts/helper.py` 或 `.sh`）：
+- 操作是**确定性的**——排序、求和、验证、格式转换
+- 同样的代码本应每次由 Claude 重新生成
+- 错误需要显式处理，而单纯遵循提示无法可靠完成
+- 任务涉及以结构化方式遍历文件系统
+
+"代码执行远比简单地运行排序算法昂贵得多"（Anthropic 工程博客）。用代码处理流程性工作，用提示处理组合性工作。
+
+## 测试框架（3 个阶段）
+
+Anthropic 的官方测试建议：
+
+1. **触发测试**——技能是否在应触发时触发？是否在不应触发时*不*触发？（更难的方向）用触发条件内外两方面的提示进行测试。
+2. **功能测试**——给定已知输入，技能是否产生预期输出？边界情况是否处理？错误是否清晰呈现？
+3. **性能对比**——同一任务，有技能 vs. 无技能。测量指标：token 数量、工具调用次数、来回交互轮数。如果带技能的版本不比不带技能的版本好，那这个技能不值得占据一个槽位。
+
+对于未通过以上任何一项测试的技能，要么修复，要么删除。一个已安装但失效的技能的开销，就是它占用的那个始终加载的 frontmatter 槽位。
+
+## 9 种技能类型（Anthropic 内部分类法）
+
+| 类型 | 功能 |
+|---|---|
+| 库 / API 参考 | 内部工具、CLI、SDK——特别是边界情况和陷阱 |
+| 产品验证 | 端到端驱动产品，在每一步断言状态 |
+| 数据获取与分析 | 连接监控/数据服务，包含凭据、仪表盘、常用查询 |
+| 业务流程自动化 | 一条命令完成工作流，结果记录到文件 |
+| 代码脚手架 | 针对代码库特定模式的框架样板 |
+| 代码质量 / 审查 | 执行标准；生成对抗性审查者 |
+| CI/CD 与部署 | 拉取、推送、部署、监控、回滚、照看脆弱的 CI |
+| 操作手册 | 症状 → 调查 → 结构化报告 |
+| 基础设施运维 | 带破坏性操作防护的日常维护 |
+
+不符合某一类型的技能，通常是想做的事情太多。请拆分。
+
+## 5 种经典工作流模式
+
+| 模式 | 形态 |
+|---|---|
+| 顺序工作流编排 | 固定顺序的多步骤流程；每阶段验证；失败时回滚 |
+| 多 MCP 协调 | 跨越多个服务的工作流；阶段分离；集中式错误处理 |
+| 迭代优化 | 通过循环提升输出质量；质量标准；"知道何时停止" |
+| 上下文感知的工具选择 | 相同结果，根据上下文使用不同工具；决策树；回退选项 |
+| 领域特定智能 | 超出工具访问范围的专业知识；行动前合规检查 |
+
+如果某个技能的行为无法映射到以上任何一种模式，其设计可能不够清晰。
+
+## 元流程："先迭代，再提取"
+
+Anthropic 推荐的技能创建流程：*"在单个有挑战性的任务上反复迭代，直到 Claude 成功完成，然后将获胜方案提取为技能。"*
+
+换句话说：不要提前编写技能。先在对话中解决问题。当你找到有效的提示 + 上下文形态后，将其冻结为一个技能。效果最好的技能，是那些捕获了真实成功运行过程的技能，而不是预判未来需求的技能。
+
+## Anthropic 明确指出的反模式
+
+- **指令过于僵化**——用严格规则锁定 Claude，而不是提供有助于判断的上下文
+- **类别模糊**——在一个 SKILL.md 中混合不同领域（"部署 + 数据库 + 监控"）
+- **Description 写成叙述文**——*"This skill does A, B, and C"* 未能通过路由测试
+- **所有内容内联**——将参考文档塞入 SKILL.md 会增加每次调用的开销
+- **没有 Gotchas 章节**——生产环境中的技能缺少该章节，等于把 60%→95% 的可靠性提升拱手放弃
+- **提前编写**——为假设的未来需求编写技能，而非从成功的运行中提取
+- **技能名称包含 `claude` 或 `anthropic`**——保留字段
+- **技能文件夹中有 README.md**——会混淆加载器；只使用 SKILL.md
+
+## 值得阅读的参考技能
+
+[github.com/anthropics/skills](https://github.com/anthropics/skills) 中的 17 个技能是典型范例。在编写新技能之前值得通览一遍，特别是当它属于上述 9 种类型之一时。它们大多不超过 300 行，远低于 500 行的门槛。
+
+---
+
+*最后更新于 2026-05-06，依据 Anthropic 官方文档及 2026 年 4 月的 vault 研究笔记。当 Anthropic 发布更新后的指南时，请更新本文档，而不是将修改分散到多个 SKILL.md 文件中。*
@@ -0,0 +1,86 @@
+# 优化模式 —— 将已有技能升级至 V2
+
+让一个可用的技能在其**存在的目标结果上变得可测量地更好** —— 而不仅仅是包装得更精美。一个不改变结果输出的整洁重构不是 V2。这是指标驱动的优化 —— 定义可测量的"更好"，进行实验，只保留有效改动 —— 将其应用于技能的*输出*。
+
+## 何时使用
+
+技能已存在并能正确触发，但你怀疑其*输出*可以更强 —— 更好的决策、更少的遗漏、更精准的写作、更可靠的结果。不适合修复一个失效的触发器（那属于质量修复）或创建全新的东西（那是 `forge` 的职责）。
+
+## 优化循环
+
+### 1. 定义结果 + 如何衡量它
+
+用一句话说明该技能的*优秀*输出应该是什么样子 —— 指实际世界的结果，而非"结构良好"。然后选择一个你确实能运行的衡量方式：
+- **LLM 作为裁判的评分标准**（3–5 个加权维度，1–5 分评分）—— 主观输出的默认选择（备忘录、评审、研究）。判断是否使用裁判的硬性标准：如果一个人类必须*阅读*输出才能判断它是否更好，那就使用裁判。
+- **硬性指标**（一个有明确方向性的数字）—— 适用于有客观目标的输出。
+
+没有指标 → 没有优化。"感觉更好"不是结果。在改变任何东西之前先把评分标准写下来。
+
+### 2. 设置关卡（防止作弊的步骤）
+
+仅有指标会被钻空子 —— 优化循环会找到一种方法来获得高分，而输出却变得更差。定义**关卡**：通过/不通过检查，用于淘汰一个候选方案，*即使它得分最高*。（这是从 evo/`ce-optimize` 中学到的教训："没有关卡，优化循环会找到钻指标空子的方法。"）
+- **退化关卡** —— 捕获明显有问题的结果（输出为空、技能删掉了自己一半的流程、输出只有一行）。成本低；优先运行。
+- **防作弊审查** —— 验证 V2 没有把评分标准的答案偷偷塞进技能、硬编码测试用例，或通过缩小范围来取胜。一个仅靠"应试"才通过的改动属于失败。
+- **留出集检查** —— 保留你的基准测试的一部分（见步骤 5），这些用例是改动*未曾*针对调优的。
+
+任何未通过任一关卡的改动，无论得分多高，均予丢弃。
+
+### 3. 质量审计（必要但不充分）
+
+对当前技能运行 `forge` 的评审清单：描述即路由器、行数预算、渐进式披露、**基于真实失败构建的注意事项**、反模式、三阶段测试。记录修复项 —— 但请记住，这些改进的是*可靠性/包装*，而不是*结果天花板*。不要止步于此；这正是此模式要摆脱的陷阱。
+
+### 4. 结果研究（提升天花板的部分）
+
+研究技能的**领域**，寻找能提升步骤 1 中结果指标的最新技术和证据。进行多来源的网页搜索（并且，如果你碰巧运行了一个集成了知识库的研究技能，可以让它在那里进行叠加 —— 可选，非强制）。
+
+- 围绕*结果*来构建查询，而非技能：对于一个评审技能，问"哪些技术能捕获最多的真实缺陷"；对于一个备忘录技能，问"是什么让决策备忘录改变了决策"；对于一个辩论技能，问"最新的超越单轮输出的多智能体讨论方法"。
+- 只提取**具体的、有证据支持的改动**：一个新的流程步骤、一个启发式规则、一个更好的默认值、一个需要防范的失败模式。每个候选改动应注明来源及其针对的结果维度。
+- 跳过那些有趣但不会改变指标的发现。
+
+### 5. 合成 V2
+
+将获胜的候选改动与质量修复整合进技能。然后：
+- 添加一个 `## Changelog` 章节：`## V2 (YYYY-MM-DD)`，每项改动占一行 —— *改了什么、为什么改、以及证据/来源*。读者必须能够将每一个 V2 的改动追溯到某条质量规则或某项研究发现。
+- 保持行数预算；将新细节推入 `references/`，而不是膨胀 SKILL.md（更多上下文并不一定更好 —— 自动膨胀会降低智能体的表现）。
+- 保留技能的语调和触发器；优化流程，而不是重写其身份。
+
+### 6. 验证 —— 在基准测试上（使用训练/验证集划分）衡量 V2 与 V1 的对比
+
+在**基准测试**上对 **V1 和 V2 都进行评分** —— 使用一小批留出的真实任务，而非单个示例。目标约 10–20 个代表性任务，覆盖技能实际面临的各种形态（evo 的 SealQA 运行使用了 20 个）。尽可能进行盲评（一个不知道哪个输出是 V1 哪个是 V2 的裁判）。
+
+**划分数据集。** 将基准测试分为两部分：**调优子集**（你的改动在迭代过程中可能已隐含过拟合的用例）和**验证子集**（从未被改动过程见过 —— 真正的胜利条件）。在验证集上对 V2 评分。如果验证集表现退步而调优集改进，说明改动过拟合了；丢弃它。这是 SkillOpt 的纪律应用于手动运行循环的体现，它捕获了最常见的虚假胜利：一个"更好"的技能实际上学会了测试用例而不是任务本身。
+- **首先应用关卡**（步骤 2）：丢弃任何未通过关卡或防作弊审查的 V2，即使它得分更高。
+- 只保留那些在留出任务上确实改变了指标的改动。如果一个受研究启发的改动得分更差，丢弃它并在变更日志中注明原因。
+- 如果 V2 整体上未能击败 V1，那它就不是真正的 V2 —— 要么迭代（回到步骤 4），要么回退。发布一个并未带来可测量改进的"V2"正是此模式要防止的失败。
+- 在变更日志中记录 V1→V2 的差值（例如："裁判评分 3.8 → 4.8，跨越 20 个任务；最大提升：风险暴露"）。
+
+## 深入优化 —— 可选的外部升级工具
+
+以上步骤是自包含的：一个 V2，手动运行，快速，无需其他工具。老实说，手动运行相当于"一个周期，批次大小为 1"。当您需要进行认真的优化 —— 多个假设、并行实验、持续数小时的基准测试、论文级别的验证 —— 并且您已安装了专门的优化工具时，可升级到该工具。以下三个工具均适用，且均**独立于此技能**（需单独安装）：
+- **`ce-optimize`**（Compound Engineering 插件）—— 将其 spec 指向技能文件作为 `scope.mutable`，将您的基准测试作为指标，将您的关卡作为 `degenerate_gates`；它在 Claude Code 内运行并行工作树实验，只保留通过关卡的优胜者，然后收敛。最适合会话内的工作流集成。
+- **`evo`**（开源，evo-hq.com）—— 针对基准测试优化整个技能*目录*，采用并行探索、树搜索（保留并合并专家）、以及防作弊审计器。最适合跨技能集的优雅架构。
+- **SkillOpt**（微软，MIT 许可，[arxiv 2605.23904](https://arxiv.org/abs/2605.23904))—— 以神经网络风格训练 Markdown 技能：**周期、小批量、学习率、验证关卡**，以 `best_skill.md` 作为当前冠军。附带标准化基准测试（SearchQA、ALFWorld、DocVQA、SpreadsheetBench、OfficeQA）并发表过论文。最适合基准驱动型的严谨性要求。
+
+如果您没有安装以上任何一个工具，上述循环本身是完整的。此技能独特提供的（而通用优化器不具备的）是：**结果研究**假设来源（步骤 4）和**技能质量审计**（步骤 3）。
+
+## 输出
+
+- V2 技能（同一目录；旧版本可通过 git 恢复）。
+- 一个包含证据链和实测差值的 `## Changelog` 条目。
+- 研究简报保存在技能旁（或您的知识库中），在变更日志中关联引用。
+
+## 注意事项
+
+- **整理 ≠ 优化。** 如果你的 V2 差异全是格式化和 frontmatter 改动，那你跳过了步骤 4（结果研究）。
+- **未测量的"改进"会导致倒退。** 没有步骤 6，你就无法区分真正的提升和听起来合理的提升 —— 而源自研究的想法恰恰是那种听起来合理的类型。在基准测试上测量。
+- **没有关卡 → 指标被钻空子。** 步骤 2 的防作弊审查不是可选项。一个裁判评分突然提高，只是因为技能学会了奉承评分标准（或悄悄缩小了自己的范围），这实际上是穿着胜利外衣的倒退。
+- **只有一个用例的基准测试就是一则轶事。** 单个测试用例会过拟合。使用留出集；这是委员会评审 A/B 测试（一个问题 —— 具暗示性）与真实验证（evo 的 20 个用例）之间的区别。
+- **不要批量添加研究内容。** 只纳入那 2–4 个真正改变指标的改动，而非所有发现。更长的技能通常是更差的技能。
+- **手动运行路径一次只处理一个技能。** 对于多个技能或长时间运行，那是升级到 ce-optimize/evo 的信号，而不是手动硬干。
+
+## 血统
+
+此模式借鉴了三条汇聚工作线的指标驱动优化纪律 —— 将其范围限定于单个技能，并前置了一个其他方案不具备的结果研究假设来源：
+- **Compound Engineering `ce-optimize`** —— spec + 关卡 + 并行工作树实验 + 持久化。
+- **`evo`**（[alokbishoyi97](https://x.com/alokbishoyi97/status/2059610305408462898)、evo-hq.com）—— 并行探索、树搜索、关卡、防作弊审计器。
+- **Microsoft SkillOpt**（[arxiv 2605.23904](https://arxiv.org/abs/2605.23904))—— 神经网络风格训练（周期/批次/验证关卡）基于标准化基准测试；步骤 6 中训练/验证集划分纪律的来源。