skillforge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skillforge — write and optimize Claude Code skills the right way

Skillforge — 正确编写与优化Claude Code技能

For full Anthropic-authoritative guidance (frontmatter fields, 500-line budget, dynamic context injection, testing framework, anti-patterns, the 9 skill types, the 5 workflow patterns), load: references/anthropic-skill-best-practices.md.

如需获取Anthropic官方权威指导（前置元数据字段、500行篇幅限制、动态上下文注入、测试框架、反模式、9种技能类型、5种工作流模式），请加载：references/anthropic-skill-best-practices.md。

Two modes

两种模式

Mode	Use for	Output
forge (default)	A new skill that doesn't exist yet	A new skill dir, drafted per the process below
optimize	An existing skill that works but should be better	A V2 of that skill — measurably better at its outcome

forge
follows the process + checklist in the rest of this file.

optimize <skill>
runs a metric-driven loop: define the outcome + metric → set gates (incl. a no-cheating audit) → quality audit → research the domain for outcome-improving techniques → synthesize V2 with a changelog → verify V2 beats V1 on a held-out benchmark, not a single example, discarding any candidate that fails a gate. "Optimize," not "tidy": a cleanup that doesn't move the outcome is not a V2, and a score that jumped by gaming the rubric is a regression. The loop is self-contained; for a heavy run (many hypotheses, parallel experiments, hours) you can optionally escalate to an external optimizer if you have one (

ce-optimize

plugin,

evo

, or Microsoft's

SkillOpt

). Full playbook: references/optimize-mode.md.

模式	适用场景	输出结果
forge（默认）	用于创建全新技能	按照下方流程生成的新技能目录
optimize	用于优化已有但仍有提升空间的技能	该技能的V2版本——实际效果得到可量化提升

forge
模式遵循本文档剩余部分的流程与检查清单。

optimize <skill>
模式运行一个指标驱动的循环：定义效果与指标 → 设置准入门槛（含反作弊审计） → 质量审计 → 研究领域内提升效果的技术 → 生成带变更日志的V2版本 → 通过预留基准测试验证V2优于V1（而非单一示例），淘汰未通过准入门槛的候选版本。重点是「优化效果」而非「整理包装」：未提升实际效果的清理不能称为V2，通过投机取巧提高评分的属于退化。该循环可独立运行；如需深度优化（多假设验证、并行实验、耗时数小时），若已安装外部优化器（

ce-optimize

插件、

evo

或微软的

SkillOpt

），可选择将任务转交。完整操作手册：references/optimize-mode.md。

Meta-process: iterate first, extract second

元流程：先迭代，再提取

Anthropic's recommended creation flow: iterate on a single challenging task until Claude succeeds, then extract the winning approach into a skill. Don't write skills for hypothetical future needs. Solve the real problem in conversation, find the prompt + context shape that works, freeze it.

Anthropic推荐的创建流程：针对单个具有挑战性的任务进行迭代，直到Claude成功完成，再将有效的方法提炼为技能。不要为假设的未来需求编写技能。先在对话中解决实际问题，找到有效的提示词与上下文结构，再将其固化为技能。

Process

操作流程

Gather requirements - ask user about:
- What task/domain does the skill cover?
- What specific use cases should it handle? (Surface a real recent example.)
- Does it need executable scripts or just instructions?
- Any reference materials to include?
- Any side effects (deploy, commit, send-message)? → set
```
disable-model-invocation: true
```
- Tools that would otherwise prompt? → list in
```
allowed-tools:
```
Draft the skill - create:
- SKILL.md with concise instructions (target ≤100 lines locally; Anthropic's public bar is 500)
- ```
references/
```
  files for detail that doesn't need to load on every invoke
- ```
scripts/
```
  for deterministic helpers (sorting, validation, format conversion)
Review with user - present draft and ask:
- Does this cover your use cases?
- Anything missing or unclear?
- Should any section be more/less detailed?

收集需求 - 向用户确认：
- 技能覆盖的任务/领域？
- 需要处理哪些具体用例？（提供一个真实的近期示例）
- 是否需要可执行脚本，还是仅需操作说明？
- 需要包含哪些参考资料？
- 是否存在副作用（部署、提交、发送消息）？→ 设置
```
disable-model-invocation: true
```
- 是否需要特定工具？→ 在
```
allowed-tools:
```
  中列出
起草技能 - 创建：
- SKILL.md文件，包含简洁的操作说明（本地目标≤100行；Anthropic公开标准为500行）
- ```
references/
```
  目录下存放无需每次调用都加载的详细内容
- ```
scripts/
```
  目录下存放确定性辅助脚本（排序、验证、格式转换等）
与用户评审 - 展示草稿并询问：
- 是否覆盖所有用例？
- 是否有遗漏或表述不清的部分？
- 哪些部分需要更详细/简化？

Skill Structure

技能结构

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-name/
├── SKILL.md           # 主操作说明（必填）
├── REFERENCE.md       # 详细文档（按需添加）
├── EXAMPLES.md        # 使用示例（按需添加）
└── scripts/           # 实用脚本（按需添加）
    └── helper.js

SKILL.md Template

SKILL.md模板

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

---
name: skill-name
description: 能力简要描述。在[特定触发场景]下使用。
---

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]

undefined

[链接至独立文件：详见REFERENCE.md]

undefined

Description Requirements

描述要求

The description is the only thing your agent sees when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.

Goal: Give your agent just enough info to know:

What capability this skill provides
When/why to trigger it (specific keywords, contexts, file types)

Format:

Max 1,536 chars (combined
```
description
```
+
```
when_to_use
```
)
Write in third person
First sentence: what it does
Second sentence: "Use when [specific triggers]"
Anti-pattern: narrative summary ("This skill does A, B, and C") fails the routing test. Write decision rules.

Good example:

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.

Bad example:

Helps with documents.

The bad example gives your agent no way to distinguish this from other document skills.

描述是Agent选择加载技能时唯一可见的内容，会与其他已安装技能一同显示在系统提示中。Agent会读取这些描述，根据用户请求选择相关技能。

目标：为Agent提供足够信息，使其明确：

该技能提供什么能力
何时/为何触发它（特定关键词、场景、文件类型）

格式：

```
description
```
+
```
when_to_use
```
总字符数不超过1536
使用第三人称撰写
第一句：说明技能功能
第二句："在[特定触发场景]下使用"
反模式：叙事性总结（"该技能可完成A、B、C"）无法通过路由测试，请编写明确的决策规则。

优秀示例：

提取PDF文件中的文本与表格，填写表单，合并文档。在处理PDF文件或用户提及PDF、表单、文档提取时使用。

糟糕示例：

帮助处理文档。

糟糕示例无法让Agent区分该技能与其他文档类技能。

When to Add Scripts

何时添加脚本

Add utility scripts when:

Operation is deterministic (validation, formatting)
Same code would be generated repeatedly
Errors need explicit handling

Scripts save tokens and improve reliability vs generated code.

在以下场景添加实用脚本：

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

与生成代码相比，脚本可节省token并提升可靠性。

When to Split Files

何时拆分文件

Split into separate files when:

SKILL.md exceeds 100 lines
Content has distinct domains (finance vs sales schemas)
Advanced features are rarely needed

在以下场景拆分文件：

SKILL.md超过100行
内容涉及不同领域（如财务与销售架构）
高级功能很少被用到

Gotchas section (mandatory for production skills)

注意事项部分（生产级技能必填）

Anthropic: "the highest-signal content in any skill — the diff between 60% reliability and 95% reliability." Build it from real failures, not anticipation. One-line failure mode + one-line workaround. Update on every recurring miss. A production skill without a Gotchas section is leaving the reliability win on the table.

Anthropic指出："这是所有技能中最有价值的内容——是60%可靠性与95%可靠性的差距所在"。需基于实际失败案例构建，而非预判。每条内容包含一行失败场景描述 + 一行解决方案。每次出现重复失败时更新。没有注意事项部分的生产级技能会错失提升可靠性的机会。

Testing the skill

技能测试

Three stages, per Anthropic:

Triggering — does it fire when it should? Does it not fire when it shouldn't? (Test prompts both inside and outside the trigger condition.)
Functional — given a known input, does it produce the expected output? Edge cases handled?
Performance — same task with vs. without the skill. If with-skill doesn't beat without, the skill isn't earning its slot.

按照Anthropic要求，分为三个阶段：

触发测试 — 是否在应触发时触发？是否在不应触发时不触发？（测试符合与不符合触发条件的提示词）
功能测试 — 给定已知输入，是否产生预期输出？是否处理了边缘情况？
性能测试 — 使用技能与不使用技能完成相同任务的对比。如果使用技能的效果未超过不使用技能，则该技能没有存在的价值。

Review Checklist

评审检查清单

After drafting, verify:

Description includes triggers ("Use when...") and is ≤1,536 chars
SKILL.md under 100 lines (local target; Anthropic's public bar is 500)
Frontmatter declares
```
allowed-tools
```
if the skill needs specific ones
```
disable-model-invocation: true
```
set if the skill has side effects
Gotchas section present (or marked as TODO with first failure)
No time-sensitive info
Consistent terminology
Concrete examples included
References one level deep
No
```
claude
```
or
```
anthropic
```
in skill name; no
```
README.md
```
in folder

起草完成后，验证以下内容：

描述包含触发条件（"在...时使用"）且总字符数≤1536
SKILL.md不超过100行（本地目标；Anthropic公开标准为500行）
若技能需要特定工具，前置元数据中已声明
```
allowed-tools
```
若技能存在副作用，已设置
```
disable-model-invocation: true
```
包含注意事项部分（或标记为TODO，待首次失败后补充）
无时效性信息
术语一致
包含具体示例
引用内容仅嵌套一层
技能名称中不含
```
claude
```
或
```
anthropic
```
；目录中不含
```
README.md
```

Changelog

变更日志

V2.2 (2026-05-29) — added SkillOpt + train/val split

V2.2（2026-05-29）—— 添加SkillOpt + 训练/验证拆分

Added Microsoft SkillOpt (MIT, arxiv 2605.23904) as a third optional external escalation alongside
```
ce-optimize
```
and
```
evo
```
. SkillOpt trains markdown skills NN-style (epochs / mini-batches / validation gates) against standardized benchmarks (SearchQA, ALFWorld, DocVQA, SpreadsheetBench, OfficeQA). Best fit for benchmark-driven rigor; ce-optimize for in-session workflow; evo for parallel/tree-search architecture.
Sharpened the verify step (#6) with a train/validation split — divide the held-out benchmark into a tuning subset (which iterating may overfit to) and a validation subset (never seen by the change process). If validation regresses while tuning improves, the change overfit; drop it. Borrowed from SkillOpt's discipline.
Reframed the hand-run loop honestly: "one epoch, batch of one" — small, fast, useful for one-skill V2s; escalate when you want real training.

添加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) — merged ce-optimize discipline

V2.1（2026-05-28）—— 整合ce-optimize规范

Evolved

optimize

mode by merging the metric-driven rigor of ce-optimize
(CE plugin) and evo
(alokbishoyi97, evo-hq.com):

Added a gates step (degenerate gates + no-cheating audit + held-out check) — discard any candidate that fails a gate even if it scored best. Closes the "gamed metric" hole the prior loop had.
Verify now uses a held-out benchmark (~10–20 tasks), not a one-off — fixes the N=1 weakness in the council-review A/B.
Added optional external escalation: for heavy runs (many hypotheses / parallel experiments / hours), optionally hand off to an external optimizer (
```
ce-optimize
```
plugin or
```
evo
```
, evo-hq.com) if installed; skillforge stays self-contained and keeps the unique outcome-research + skill-quality-audit front end.

通过整合**

ce-optimize

（CE插件）和

evo

**（alokbishoyi97，evo-hq.com）的指标驱动规范，升级

optimize

模式：

添加准入门槛步骤（退化门槛 + 反作弊审计 + 预留测试）——即使得分最高，未通过门槛的候选版本也会被淘汰。填补了此前循环中「指标投机」的漏洞。
验证环节现在使用预留基准测试（约10–20个任务），而非单一示例——解决了评审A/B测试中样本量为1的缺陷。
添加可选外部转交：如需深度优化（多假设验证/并行实验/耗时数小时），若已安装外部优化器（
```
ce-optimize
```
插件或
```
evo
```
，evo-hq.com），可选择将任务转交；Skillforge保持独立运行，并保留独特的效果研究 + 技能质量审计前端。

V2 (2026-05-27)

V2（2026-05-27）

Added optimize
mode (forge new vs optimize existing-to-V2). Optimize runs a metric-driven loop — define outcome + metric, quality audit, domain outcome-research, synthesize V2 + changelog, verify V2 beats V1 — so a "V2" must measurably improve the outcome, not just the packaging. Playbook:
```
references/optimize-mode.md
```
.
Dogfooded across 7 skills (council-review pilot + a 6-skill batch), which is what promoted skillforge out of
```
in-progress/
```
.

添加**
```
optimize
```
模式**（打造新技能 vs 将现有技能优化至V2）。Optimize模式运行指标驱动循环——定义效果与指标、质量审计、领域效果研究、生成V2版本+变更日志、验证V2优于V1——因此「V2版本」必须实现实际效果的可量化提升，而非仅优化包装。操作手册：
```
references/optimize-mode.md
```
。
在7个技能中进行内部测试（评审试点 + 6个技能批量测试），这也是Skillforge从
```
in-progress/
```
目录移出的原因。