skillforge

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 或 Microsoft 的 SkillOpt。完整操作手册：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           # Main instructions (required)
├── REFERENCE.md       # Detailed docs (if needed)
├── EXAMPLES.md        # Usage examples (if needed)
└── scripts/           # Utility scripts (if needed)
    └── helper.js

SKILL.md 模板

---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Step-by-step processes with checklists for complex tasks]

## Advanced features

[Link to separate files: See [REFERENCE.md](REFERENCE.md)]

描述要求

当 Agent 决定加载哪个技能时，唯一能看到的就是描述。它会与所有其他已安装技能一同显示在系统提示词中。Agent 会阅读这些描述，并根据用户的请求选择相关技能。

目标：提供恰到好处的信息，让 Agent 知道：

1. 该技能提供什么能力
2. 何时/为何触发（具体关键词、上下文、文件类型）

格式：

• 最多 1,536 个字符（description + when_to_use 的总和）
• 使用第三人称
• 第一句：说明该技能的作用
• 第二句：“在[具体触发条件]时使用”
• 反模式： 叙述式摘要（“此技能会执行 A、B 和 C”）无法通过路由测试。应编写决策规则。

好示例：

Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.

坏示例：

Helps with documents.

坏示例无法让 Agent 区分此技能与其他文档技能。

何时添加脚本

在以下情况下添加实用脚本：

• 操作具有确定性（验证、格式化）
• 需要反复生成相同代码
• 错误需要显式处理

与生成代码相比，脚本可以节省令牌并提高可靠性。

何时拆分文件

在以下情况下拆分为多个文件：

• 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) 作为第三种可选的外部升级方案加入，与 ce-optimize 和 evo 并列。SkillOpt 采用类似神经网络的方式训练 Markdown 技能（轮次 / 小批次 / 验证门控），并使用标准化基准（SearchQA、ALFWorld、DocVQA、SpreadsheetBench、OfficeQA）。它最适合追求基准测试驱动的严谨性；ce-optimize 适合会话内工作流；evo 适合并行 / 树搜索架构。
• 通过训练集 / 验证集拆分强化了验证步骤（#6）——将留出基准拆分为调优子集（迭代过程可能会对其过拟合）和验证子集（更改过程从未接触过）。如果验证集表现退步而调优集表现提升，则说明更改过拟合了；应弃用该更改。此做法借鉴了 SkillOpt 的严谨方法。
• 如实地重新描述了手动执行的循环：“一个轮次，一个批次”——规模小、速度快，适用于单个技能的 V2；需要真正的训练时再升级。

V2.1 (2026-05-28) — 融合 ce-optimize 的严谨做法

通过融合 ce-optimize（CE 插件）和 evo（alokbishoyi97，evo-hq.com）以指标驱动的严谨做法，改进了 optimize 模式：

• 新增 门控 步骤（退化门控 + 防作弊审计 + 留出检查）——即使某个候选方案得分最高，只要未通过门控，也应将其丢弃。由此弥补了此前循环中“指标被操纵”的漏洞。
• 验证环节现在使用留出基准（约 10–20 个任务），而非单次测试——解决 council-review A/B 测试中 N=1 的弱点。
• 新增可选的外部升级方案：对于大型运行（大量假设 / 并行实验 / 耗时数小时），如果已安装外部优化器，可选择交由其处理（ce-optimize 插件或 evo，evo-hq.com）；skillforge 仍可独立运行，并保留其独特的成果研究 + 技能质量审计前端。

V2 (2026-05-27)

• 新增 optimize 模式（新建技能与将现有技能优化到 V2）。Optimize 会运行一个指标驱动的循环——定义成果 + 指标、质量审计、领域成果研究、合成 V2 + 更新日志、验证 V2 是否优于 V1——确保所谓的“V2”必须在成果方面实现可衡量的改进，而不只是改进包装。操作指南：references/optimize-mode.md。
• 在 7 个技能上进行了自用测试（council-review 试点 + 一批 6 个技能），因此 skillforge 从 in-progress/ 中晋级。