skillhub-004-skillforge
wehub-skill-sync
172 行
9.5 KiB
Markdown
172 行
9.5 KiB
Markdown
---
|
||
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/` 目录晋升的原因。
|