wehub-skill-sync
9.5 KiB
name, description, license
| name | description | license |
|---|---|---|
| skillforge | 打造新的 Claude Code 技能，或将现有技能优化至 V2 版本。两种模式 —— `forge` 用于搭建新技能（frontmatter、渐进式信息披露、辅助脚本、必选 Gotchas、先迭代后提取）；`optimize` 使现有技能在其**目标效果**上实现可量化的提升（而非仅改善包装）。当用户想要创建、编写、构建、搭建、改进、升级或优化技能时使用。 | MIT |
Skillforge —— 以正确方式编写和优化 Claude Code 技能
如需获取 Anthropic 官方权威指南（frontmatter 字段、500 行预算限制、动态上下文注入、测试框架、反模式、9 种技能类型、5 种工作流模式），请加载：references/anthropic-skill-best-practices.md。
两种模式
| 模式 | 适用场景 | 输出结果 |
|---|---|---|
| forge（默认） | 尚不存在的全新技能 | 按以下流程起草的新技能目录 |
| optimize | 现有技能虽能工作但需要改进 | 该技能的 V2 版本 —— 在目标效果上实现可量化提升 |
forge 遵循本文件其余部分所述的流程 + 检查清单。
optimize <skill> 运行一个以指标驱动的循环：定义目标效果 + 指标 → 设置关卡（含防止作弊的审计） → 质量审计 → 调研该领域以获取改进目标效果的技术 → 综合产出 V2 版本及变更日志 → 在独立的保留测试基准（而非单个示例） 上验证 V2 是否优于 V1，丢弃任何未通过关卡的后选方案。"优化"而非"整理"：未推动目标效果改善的清理工作不能算作 V2；通过玩弄评分标准获得的高分属于倒退。该循环为自包含方案；对于重负载运行（大量假设、并行实验、耗时数小时），你可选用外部优化器（如 ce-optimize 插件、evo 或微软的 SkillOpt）进行升级。完整操作手册见：references/optimize-mode.md。
元流程：先迭代，后提取
Anthropic 推荐的创建流程：先在单个具有挑战性的任务上反复迭代，直到 Claude 成功完成，然后将胜出的方法提取为技能。 不要为假想的未来需求编写技能。在对话中解决真实问题，找到有效的提示词 + 上下文组合，然后将其固化。
流程
-
收集需求 —— 询问用户：
- 该技能涵盖什么任务/领域？
- 应处理哪些具体用例？（举一个真实的近期示例。）
- 需要可执行脚本，还是仅需指令？
- 是否包含任何参考资料？
- 是否有任何副作用（部署、提交、发送消息）？→ 设置
disable-model-invocation: true - 哪些工具通常会触发权限提示？→ 在
allowed-tools:中列出
-
起草技能 —— 创建：
- SKILL.md 文件，包含简洁的指令（本地目标 ≤100 行；Anthropic 公开上限为 500 行）
references/目录下的文件，存放无需每次调用都加载的详细信息scripts/目录下的确定性辅助脚本（排序、校验、格式转换）
-
与用户一起审查 —— 展示草稿并询问：
- 是否覆盖了你的用例？
- 是否有遗漏或不清晰之处？
- 是否有任何章节需要更详细或更简略？
技能目录结构
skill-name/
├── SKILL.md # 主指令文件（必需）
├── REFERENCE.md # 详细文档（可选）
├── EXAMPLES.md # 使用示例（可选）
└── scripts/ # 工具脚本（可选）
└── helper.js
SKILL.md 模板
---
name: skill-name
description: 简短描述该功能。当 [特定触发条件] 时使用。
---
# 技能名称
## 快速开始
[最小可行示例]
## 工作流
[针对复杂任务的分步流程及检查清单]
## 高级功能
[链接到独立文件：参见 [REFERENCE.md](REFERENCE.md)]
描述（Description）要求
描述是你的智能体在决定加载哪个技能时唯一能看到的信息。它与其他所有已安装技能的描述一起出现在系统提示中。你的智能体读取这些描述，并根据用户的请求选择相关的技能。
目标：让你的智能体拥有足够的信息来判断：
- 该技能提供了什么能力
- 何时/为什么触发它（具体关键词、上下文、文件类型）
格式：
- 最多 1,536 个字符（
description+when_to_use合计） - 以第三人称编写
- 第一句：该技能的功能
- 第二句："当 [具体触发条件] 时使用"
- 反模式：叙述性概括（"该技能可执行 A、B、C 三项功能"）无法通过路由测试。请编写决策规则。
好的示例：
从 PDF 文件中提取文本和表格、填写表单、合并文档。当处理 PDF 文件或用户提及 PDF、表单或文档提取时使用。
差的示例：
帮助处理文档。
差的示例让你的智能体无法将这项技能与其他文档类技能区分开来。
何时添加脚本
在以下情况添加工具脚本：
- 操作为确定性的（校验、格式化）
- 同一段代码会被重复生成
- 需要显式处理错误
与生成式代码相比，脚本可节省 token 并提高可靠性。
何时拆分文件
在以下情况将内容拆分为多个文件：
- SKILL.md 超过 100 行
- 内容涉及不同领域（如财务与销售模式）
- 高级功能很少使用
Gotchas 部分（生产级技能必选）
Anthropic 指出："这是任何技能中信号价值最高的内容 —— 是 60% 可靠性到 95% 可靠性的差距所在。" 应从真实失败中构建，而非靠预判。一条失败模式 + 一条解决方法。每次重复出现失误时更新。没有 Gotchas 部分的生产级技能等于白白放弃了可靠性提升的机会。
测试技能
按 Anthropic 的建议分为三个阶段：
- 触发测试 —— 它是否在应该触发时触发？在不应触发时不触发？（在触发条件内和条件外分别测试提示词。）
- 功能测试 —— 给定已知输入，是否产生预期输出？是否处理了边界情况？
- 性能测试 —— 有技能与无技能情况下执行相同任务的结果对比。如果使用技能未能优于不使用技能，则该技能不值得占据槽位。
审查检查清单
起草完成后，请验证：
- 描述中包含触发条件（"当……时使用"），且不超过 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）作为第三个可选的外部升级方案，与
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，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/目录晋升的原因。