From 3641661ee76d6ea3e2b7f77fe01f59e40413a6eb Mon Sep 17 00:00:00 2001 From: wehub-skill-sync Date: Mon, 13 Jul 2026 21:35:31 +0800 Subject: [PATCH] chore: import zh skill skillforge --- README.wehub.md | 9 + SKILL.md | 171 +++++++++++++++++ references/anthropic-skill-best-practices.md | 184 +++++++++++++++++++ references/optimize-mode.md | 86 +++++++++ 4 files changed, 450 insertions(+) create mode 100644 README.wehub.md create mode 100644 SKILL.md create mode 100644 references/anthropic-skill-best-practices.md create mode 100644 references/optimize-mode.md diff --git a/README.wehub.md b/README.wehub.md new file mode 100644 index 0000000..da599e8 --- /dev/null +++ b/README.wehub.md @@ -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 清单整理 +- 原作者、版权和许可证信息以上游仓库为准 diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..f1dbeb9 --- /dev/null +++ b/SKILL.md @@ -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 `** 运行一个以指标驱动的循环：定义目标效果 + 指标 → **设置关卡（含防止作弊的审计）** → 质量审计 → 调研该领域以获取改进目标效果的技术 → 综合产出 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/` 目录晋升的原因。 diff --git a/references/anthropic-skill-best-practices.md b/references/anthropic-skill-best-practices.md new file mode 100644 index 0000000..ebb106b --- /dev/null +++ b/references/anthropic-skill-best-practices.md @@ -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 文件中。* diff --git a/references/optimize-mode.md b/references/optimize-mode.md new file mode 100644 index 0000000..f7c35fa --- /dev/null +++ b/references/optimize-mode.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 中训练/验证集划分纪律的来源。