skill-forge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Forge

Skill 锻造工坊

IRON LAW: Every line in a skill must justify its token cost. If it doesn't make the model's output better, more consistent, or more reliable — cut it.

铁律：Skill中的每一行内容都必须对得起它消耗的token成本。如果它不能让模型的输出更优质、更一致、更可靠——就删掉它。

What is a Skill

什么是Skill

A skill is an "onboarding guide" for Claude — transforming it from a general-purpose agent into a specialized one with procedural knowledge, domain expertise, and bundled tools.

skill-name/
├── SKILL.md           # Required: workflow + instructions (<500 lines)
├── scripts/           # Optional: deterministic, repeatable operations
├── references/        # Optional: loaded into context on demand
└── assets/            # Optional: used in output, never loaded into context

Default assumption: Claude is already very smart. Only add what Claude doesn't already know. Challenge every paragraph: "Does this justify its token cost?"

Skill是Claude的「入职指南」——它能将通用型Agent转化为具备流程知识、领域专业能力和配套工具的专用Agent。

skill-name/
├── SKILL.md           # 必备：工作流 + 指令说明（<500行）
├── scripts/           # 可选：确定性、可重复执行的操作脚本
├── references/        # 可选：按需加载到上下文的参考资料
└── assets/            # 可选：用于输出的资源，不会加载到上下文

默认前提：Claude本身已经足够智能。 仅添加Claude不知道的内容，对每一段内容都要拷问：「它对得起消耗的token成本吗？」

Workflow

工作流

Copy this checklist and check off items as you complete them:

Skill Forge Progress:

- [ ] Step 1: Understand the Skill ⚠️ REQUIRED
  - [ ] 1.1 Clarify purpose and concrete use cases
  - [ ] 1.2 Collect 3+ concrete usage examples
  - [ ] 1.3 Identify trigger scenarios and keywords
- [ ] Step 2: Plan Architecture
  - [ ] 2.1 Identify reusable resources (scripts, references, assets)
  - [ ] 2.2 Design progressive loading strategy
  - [ ] 2.3 Design parameter system (if applicable)
- [ ] Step 3: Initialize ⛔ BLOCKING (skip if skill already exists)
  - [ ] Run init_skill.py
- [ ] Step 4: Write Description
  - [ ] Load references/description-guide.md
  - [ ] Apply keyword bombing technique
- [ ] Step 5: Write SKILL.md Body
  - [ ] 5.1 Set Iron Law
  - [ ] 5.2 Design workflow checklist
  - [ ] 5.3 Add confirmation gates
  - [ ] 5.4 Add parameter system (if applicable)
  - [ ] 5.5 Apply writing techniques
  - [ ] 5.6 Add anti-patterns list
  - [ ] 5.7 Add pre-delivery checklist
- [ ] Step 6: Build Resources
  - [ ] 6.1 Implement and test scripts
  - [ ] 6.2 Write reference files
  - [ ] 6.3 Prepare assets
- [ ] Step 7: Review ⚠️ REQUIRED
  - [ ] Run pre-delivery checklist (Step 9)
  - [ ] Present summary to user for confirmation
- [ ] Step 8: Package
  - [ ] Run package_skill.py
- [ ] Step 9: Iterate based on real usage

复制以下检查清单，完成对应步骤后勾选：

Skill 锻造进度：

- [ ] 第1步：理解Skill需求 ⚠️ 必填
  - [ ] 1.1 明确用途和具体使用场景
  - [ ] 1.2 收集3个以上的具体使用示例
  - [ ] 1.3 确定触发场景和关键词
- [ ] 第2步：规划架构
  - [ ] 2.1 识别可复用资源（脚本、参考资料、素材）
  - [ ] 2.2 设计渐进式加载策略
  - [ ] 2.3 设计参数系统（如适用）
- [ ] 第3步：初始化 ⛔ 前置阻断（已有Skill可跳过）
  - [ ] 运行 init_skill.py
- [ ] 第4步：编写描述
  - [ ] 加载 references/description-guide.md
  - [ ] 应用关键词覆盖技巧
- [ ] 第5步：编写SKILL.md正文
  - [ ] 5.1 设置铁律
  - [ ] 5.2 设计工作流检查清单
  - [ ] 5.3 添加确认关卡
  - [ ] 5.4 添加参数系统（如适用）
  - [ ] 5.5 应用写作技巧
  - [ ] 5.6 添加反模式清单
  - [ ] 5.7 添加交付前检查清单
- [ ] 第6步：构建资源
  - [ ] 6.1 实现并测试脚本
  - [ ] 6.2 编写参考文件
  - [ ] 6.3 准备素材资源
- [ ] 第7步：审核 ⚠️ 必填
  - [ ] 运行交付前检查清单（第9步）
  - [ ] 向用户展示摘要请求确认
- [ ] 第8步：打包
  - [ ] 运行 package_skill.py
- [ ] 第9步：基于实际使用迭代优化

Step 1: Understand the Skill ⚠️ REQUIRED

第1步：理解Skill需求 ⚠️ 必填

Ask yourself:

What specific problem does this skill solve that Claude can't do well on its own?
What would a user literally type to trigger this skill?
What are 3-5 concrete usage examples with realistic inputs and expected outputs?

If unclear, ask the user (don't ask everything at once — start with the most critical):

"Can you give me 3 examples of how you'd use this skill?"
"What would you literally say to trigger it?"
"What does a good output look like?"

Do NOT proceed until you have at least 3 concrete examples.

先问自己这些问题：

这个Skill解决了Claude单独处理时效果不好的什么具体问题？
用户实际触发这个Skill时会输入什么内容？
3-5个包含真实输入和预期输出的具体使用示例是什么？

如果信息不明确，向用户询问（不要一次性问所有问题，从最核心的开始）：

「可以给我3个你会使用这个Skill的场景示例吗？」
「你触发这个Skill时实际会输入什么内容？」
「什么样的输出算是合格的输出？」

至少拿到3个具体示例后再继续后续步骤。

Step 2: Plan Architecture

第2步：规划架构

For each concrete example, ask:

What operations are deterministic and repeatable? →
```
scripts/
```
What domain knowledge does Claude need at specific steps? →
```
references/
```
What files are used in output but not in reasoning? →
```
assets/
```

Key constraints:

SKILL.md must stay under 500 lines — everything else goes to
```
references/
```
References organized by domain, one level of nesting only
Load references/architecture-guide.md for progressive loading patterns and organization strategies

针对每个具体示例，思考：

哪些操作是确定性、可重复执行的？ → 放入
```
scripts/
```
Claude在特定步骤需要哪些领域知识？ → 放入
```
references/
```
哪些文件仅用于输出、不需要参与推理？ → 放入
```
assets/
```

核心约束：

SKILL.md 必须控制在500行以内，其余内容全部放入
```
references/
```
参考资料按领域分类，仅支持一级嵌套
加载 references/architecture-guide.md 了解渐进式加载模式和组织策略

Step 3: Initialize ⛔ BLOCKING

第3步：初始化 ⛔ 前置阻断

Skip if working on an existing skill. Otherwise run:

bash

python3 scripts/init_skill.py <skill-name> --path <output-directory>

The script creates a template with Iron Law placeholder, workflow checklist, and proper directory structure.

如果是迭代现有Skill可跳过，否则运行：

bash

python3 scripts/init_skill.py <skill-name> --path <output-directory>

该脚本会生成包含铁律占位符、工作流检查清单和规范目录结构的模板。

Step 4: Write Description

第4步：编写描述

This is the most underestimated part of a skill. The description determines:

Whether the skill triggers automatically
Whether users find it by search

Load references/description-guide.md for the keyword bombing technique and good/bad examples.

Key rule: NEVER put "When to Use" info in the SKILL.md body. The body loads AFTER triggering — too late.

这是Skill最容易被低估的部分，描述决定了：

Skill是否能被自动触发
用户是否能通过搜索找到它

加载 references/description-guide.md 了解关键词覆盖技巧和正反示例。

核心规则：绝对不要把「适用场景」信息写在SKILL.md正文中，正文是触发后才会加载的内容，放这里太晚了。

Step 5: Write SKILL.md Body

第5步：编写SKILL.md正文

Load reference files as needed for each sub-step:

根据子步骤需要加载对应的参考文件：

5.1 Set Iron Law

5.1 设置铁律

Ask: "What is the ONE mistake the model will most likely make with this skill?" Write a rule that prevents it. Place it at the top of SKILL.md, right after the frontmatter.

→ Load references/writing-techniques.md for Iron Law patterns and red flag signals.

思考：「模型使用这个Skill时最可能犯的一个错误是什么？」写一条规则来避免这个问题，放在SKILL.md最顶部，紧接在元数据之后。

→ 加载 references/writing-techniques.md 了解铁律设计模式和风险信号。

5.2 Design Workflow Checklist

5.2 设计工作流检查清单

Create a trackable checklist with:

⚠️ REQUIRED for steps that must not be skipped
⛔ BLOCKING for prerequisites
Sub-step nesting for complex steps
(conditional) for steps that depend on earlier choices

→ Load references/workflow-patterns.md for checklist patterns and examples.

创建可追踪的检查清单，标注：

⚠️ 必填：不可跳过的步骤
⛔ 前置阻断：必须先完成的前提步骤
子步骤嵌套：用于复杂步骤拆分
(条件触发)：依赖前置选择的步骤

→ 加载 references/workflow-patterns.md 了解检查清单设计模式和示例。

5.3 Add Confirmation Gates

5.3 添加确认关卡

Force the model to stop and ask the user before:

Destructive operations (delete, overwrite, modify)
Generative operations with significant cost
Applying changes based on analysis

→ Load references/workflow-patterns.md for confirmation gate patterns.

强制模型在执行以下操作前暂停并询问用户：

破坏性操作（删除、覆盖、修改）
会产生大量token消耗的生成操作
基于分析结果应用变更

→ 加载 references/workflow-patterns.md 了解确认关卡设计模式。

5.4 Add Parameter System (if applicable)

5.4 添加参数系统（如适用）

If the skill benefits from flags like

--quick

--style

--regenerate N

→ Load references/parameter-system.md for $ARGUMENTS, flags, argument-hint, and partial execution patterns.

如果Skill适合用

--quick

、

--style

、

--regenerate N

这类参数：

→ 加载 references/parameter-system.md 了解$ARGUMENTS、参数标志、参数提示和部分执行模式。

5.5 Apply Writing Techniques

5.5 应用写作技巧

Three techniques that dramatically improve output quality:

Question-style instructions: Give questions, not vague directives
Anti-pattern documentation: List what NOT to do
Iron Law + Red Flags: Prevent the model from taking shortcuts

→ Load references/writing-techniques.md for all three with examples.

三个能大幅提升输出质量的技巧：

提问式指令：给出问题，而非模糊的指令
反模式说明：明确列出不应该做的事
铁律+风险信号：避免模型走捷径

→ 加载 references/writing-techniques.md 了解三个技巧的具体用法和示例。

5.6 Add Anti-Patterns List

5.6 添加反模式清单

Ask: "What would Claude's lazy default look like for this task?" Then explicitly forbid it.

→ Load references/writing-techniques.md for anti-pattern examples.

思考：「Claude处理这个任务时的偷懒默认行为是什么？」然后明确禁止这类行为。

→ 加载 references/writing-techniques.md 了解反模式示例。

5.7 Add Pre-Delivery Checklist

5.7 添加交付前检查清单

Add concrete, verifiable checks. Each item must be specific enough that the model can check it by looking at the output. Not "ensure good quality" but "no placeholder text remaining (TODO, FIXME, xxx)."

→ Load references/output-patterns.md for checklist patterns and priority-based output.

添加具体可验证的检查项，每个条目必须足够明确，模型可以通过查看输出自行检查。不要写「确保质量良好」，要写「没有残留占位符文本（TODO、FIXME、xxx）」。

→ 加载 references/output-patterns.md 了解检查清单模式和优先级输出规则。

Writing Principles

写作原则

Concise: Only add what Claude doesn't already know
Imperative form: "Analyze the input" not "You should analyze the input"
Match freedom to fragility: Narrow bridge → specific guardrails; open field → many routes
- High freedom (text): multiple valid approaches
- Medium (pseudocode/params): preferred pattern, some variation OK
- Low (specific scripts): fragile operations, consistency critical

简洁：仅添加Claude不知道的内容
祈使句式：用「分析输入」而非「你应该分析输入」
自由度匹配约束强度：窄场景 → 严格的规则；开放场景 → 允许多种路径
- 高自由度（文本类）：存在多种有效实现方式
- 中自由度（伪代码/参数类）：有推荐模式，允许少量变体
- 低自由度（特定脚本类）：操作脆弱，一致性要求极高

Step 6: Build Resources

第6步：构建资源

Scripts

脚本

Encapsulate deterministic, repeatable operations
Scripts execute without loading into context — major token savings
Test every script before packaging
In SKILL.md, document only the command and arguments, not the source code

封装确定性、可重复执行的操作
脚本运行时不会加载到上下文，能大幅节省token
打包前测试所有脚本
在SKILL.md中仅说明命令和参数，不要贴源代码

References

参考资料

Organize by domain, not by type
One level of nesting only
Each file referenced from SKILL.md with clear "when to load" instructions
Large files (>100 lines) should have a table of contents at the top

按领域组织，而非按类型组织
仅支持一级嵌套
每个文件都要在SKILL.md中明确标注「何时加载」的说明
超过100行的大文件顶部需要加目录

Assets

素材

Templates, images, fonts used in output
Not loaded into context, just referenced by path

→ Load references/architecture-guide.md for detailed patterns.

用于输出的模板、图片、字体等
不会加载到上下文，仅通过路径引用

→ 加载 references/architecture-guide.md 了解详细设计模式。

Step 7: Review ⚠️ REQUIRED

第7步：审核 ⚠️ 必填

Present the skill summary to the user and confirm before packaging.

打包前向用户展示Skill摘要并确认。

Pre-Delivery Checklist

交付前检查清单

Structure

结构

SKILL.md under 500 lines

Frontmatter has

name

and

description

only (plus optional

allowed-tools

license

metadata

)

Description includes trigger keywords and usage scenarios
No README.md, CHANGELOG.md, or other unnecessary files
No example/placeholder files left from initialization

SKILL.md 少于500行
元数据仅包含
```
name
```
和
```
description
```
（可选添加
```
allowed-tools
```
、
```
license
```
、
```
metadata
```
）
描述包含触发关键词和使用场景
没有README.md、CHANGELOG.md等不必要的文件
没有初始化时残留的示例/占位符文件

Quality

质量

Resources

资源

Scripts tested and executable
References organized by domain, one level deep
Large references have table of contents
Assets used in output, not loaded into context

脚本已测试且可执行
参考资料按领域组织，仅一级嵌套
大参考文件有目录
素材仅用于输出，不会加载到上下文

Anti-Patterns to Avoid

需要避免的反模式

Stuffing everything into one massive SKILL.md (>500 lines)
Vague description like "A tool for X"
No workflow — letting the model freestyle
No confirmation gates — model runs unchecked to completion
Vague instructions like "ensure good quality" instead of specific checks
Including README.md, INSTALLATION_GUIDE.md, or other documentation files
"When to Use" info in the body instead of the description field

把所有内容塞到一个超过500行的超大SKILL.md里
模糊的描述比如「一个用于X的工具」
没有工作流，让模型自由发挥
没有确认关卡，模型直接运行到结束
模糊的指令比如「确保质量良好」，而非具体检查项
包含README.md、INSTALLATION_GUIDE.md等额外文档文件
把「适用场景」信息写在正文而非描述字段里

Step 8: Package

第8步：打包

bash

python3 scripts/package_skill.py <path/to/skill-folder> [output-directory]

Validates automatically before packaging. Fix errors and re-run.

bash

python3 scripts/package_skill.py <path/to/skill-folder> [output-directory]

打包前会自动校验，修复错误后重新运行即可。

Step 9: Iterate

第9步：迭代优化

After real usage:

Notice where the model struggles or is inconsistent
Identify which workflow step needs improvement
Add more specific instructions, examples, or anti-patterns
Re-test and re-package

实际投入使用后：

注意模型表现不好或输出不一致的地方
定位需要优化的工作流步骤
添加更具体的指令、示例或反模式
重新测试并打包