skill-forge

Skill Forge

铁律：技能中的每一行都必须物有所值。如果它不能让模型的输出更好、更一致或更可靠，就删掉。

什么是技能

技能是为 Claude 编写的“入门指南”——通过提供程序性知识、领域专业知识和打包工具，将其从通用 Agent 转变为专业 Agent。

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

默认假设：Claude 已经非常聪明。 只添加 Claude 尚不了解的内容。逐段审视：“这段内容值得占用这些 token 吗？”

工作流

复制此清单，并在完成项目后勾选：

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

第 1 步：了解技能 ⚠️ REQUIRED

问问自己：

• 这项技能能解决什么 Claude 无法独立妥善解决的具体问题？
• 用户会实际输入什么内容来触发这项技能？
• 有哪些 3-5 个具体使用示例，包含真实输入和预期输出？

如果不清楚，就询问用户（不要一次问完所有问题——先问最关键的）：

• “能给我 3 个你会如何使用这项技能的示例吗？”
• “你会实际说什么来触发它？”
• “什么样的输出才算好？”

至少获得 3 个具体示例后才能继续。

第 2 步：规划架构

针对每个具体示例，询问：

1. 哪些操作是确定且可重复的？→ scripts/
2. Claude 在特定步骤需要哪些领域知识？→ references/
3. 输出中会用到、但推理时不会用到哪些文件？→ assets/

关键约束：

• SKILL.md 必须少于 500 行——其他所有内容都放到 references/
• 参考资料按领域组织，只允许一层嵌套
• 加载 references/architecture-guide.md，了解渐进式加载模式和组织策略

第 3 步：初始化 ⛔ BLOCKING

如果正在处理现有技能，则跳过。否则运行：

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

该脚本会创建一个模板，其中包含铁律占位符、工作流清单和规范的目录结构。

第 4 步：编写描述

这是技能中最容易被低估的部分。描述决定：

1. 技能是否会自动触发
2. 用户能否通过搜索找到它

加载 references/description-guide.md，了解关键词轰炸技巧以及正反示例。

关键规则：绝不要在 SKILL.md 正文中写“何时使用”信息。正文只会在触发后加载——为时已晚。

第 5 步：编写 SKILL.md 正文

根据各个子步骤的需要加载参考文件：

5.1 设定铁律

问：“使用这项技能时，模型最可能犯的一个错误是什么？” 编写一条规则来避免该错误。将它放在 SKILL.md 顶部、frontmatter 之后。

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

5.2 设计工作流清单

创建可跟踪的清单，其中包含：

• 对于不可跳过的步骤，标注 ⚠️ REQUIRED
• 对于前置条件，标注 ⛔ BLOCKING
• 对于复杂步骤，使用子步骤嵌套
• 对于依赖先前选择的步骤，标注 (conditional)

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

5.3 添加确认关卡

在以下操作之前，必须要求模型停下来询问用户：

• 破坏性操作（删除、覆盖、修改）
• 成本显著的生成操作
• 根据分析结果应用更改

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

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

如果技能可以受益于 --quick、--style、--regenerate N 等标志：

→ 加载 references/parameter-system.md，了解 $ARGUMENTS、标志、argument-hint 和部分执行模式。

5.5 运用写作技巧

以下三种技巧能显著提升输出质量：

1. 问题式指令：提出问题，而不是给出含糊的指示
2. 反模式文档：列出不要做的事
3. 铁律 + 危险信号：防止模型走捷径

→ 加载 references/writing-techniques.md，查看这三种技巧及其示例。

5.6 添加反模式列表

询问：“对于这项任务，Claude 会采用什么偷懒的默认做法？”然后明确禁止这种做法。

→ 加载 references/writing-techniques.md，查看反模式示例。

5.7 添加交付前检查清单

添加具体、可验证的检查项。每项都必须足够具体，以便模型查看输出就能检查。不要写“确保质量良好”，而要写“没有残留占位文本（TODO、FIXME、xxx）”。

→ 加载 references/output-patterns.md，查看检查清单模式和基于优先级的输出。

写作原则

• 简洁：只添加 Claude 尚不了解的内容
• 使用祈使句：“分析输入”，而不是“你应该分析输入”
• 自由度与脆弱性相匹配：狭窄的桥梁 → 具体的防护措施；广阔的空间 → 多种可行路径
  • 高自由度（文本）：多种有效方法
  • 中等自由度（伪代码/参数）：提供首选模式，允许一定变化
  • 低自由度（具体脚本）：操作脆弱，一致性至关重要

第 6 步：构建资源

脚本

• 封装确定且可重复的操作
• 脚本无需加载到上下文中即可执行，可大幅节省令牌
• 打包前测试每个脚本
• 在 SKILL.md 中只记录命令和参数，不要记录源代码

参考资料

• 按领域组织，而不是按类型组织
• 只嵌套一层
• 在 SKILL.md 中引用每个文件，并明确说明“何时加载”
• 大型文件（>100 行）应在开头添加目录

资源文件

• 输出中使用的模板、图像、字体
• 不加载到上下文中，只通过路径引用

→ 加载 references/architecture-guide.md，查看详细模式。

第 7 步：审核 ⚠️ 必需

向用户展示技能摘要，并在打包前确认。

交付前检查清单

结构

• SKILL.md 少于 500 行
• Frontmatter 仅包含 name 和 description（以及可选的 allowed-tools、license、metadata）
• Description 包含触发关键词和使用场景
• 不包含 README.md、CHANGELOG.md 或其他不必要的文件
• 不保留初始化时遗留的示例文件/占位文件

质量

• 顶部包含一条铁律或核心约束
• 包含带有 ⚠️/⛔ 标记、可跟踪的工作流检查清单
• 在破坏性/生成性操作前设置确认关卡
• 使用问句式指引，而不是含糊的指令
• 列出反模式（哪些事情不能做）
• 逐步加载参考资料，而不是一开始全部加载

资源

• 脚本已测试且可执行
• 参考资料按领域组织，嵌套一层
• 大型参考资料包含目录
• 输出中使用资源文件，而不是将其加载到上下文中

应避免的反模式

• 把所有内容塞进一个超大的 SKILL.md（>500 行）
• 使用“A tool for X”这类含糊的描述
• 没有工作流，让模型自由发挥
• 没有确认关卡，让模型不受检查地执行到底
• 使用“确保质量良好”这类含糊指令，而不是具体检查项
• 包含 README.md、INSTALLATION_GUIDE.md 或其他文档文件
• 将“何时使用”信息写在正文中，而不是 description 字段中

第 8 步：打包

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

打包前会自动验证。修复错误后重新运行。

第 9 步：迭代

实际使用后：

1. 留意模型在哪些地方遇到困难或表现不一致
2. 确定需要改进哪个工作流步骤
3. 添加更具体的指令、示例或反模式
4. 重新测试并打包