skill-forge

Skill Forge

铁律：Skill 中的每一行代码和文字都必须证明自己的 Token 价值。如果它不能让模型的输出质量更高、更稳定或更可靠——直接砍掉。

什么是 Skill

Skill 是 Claude 的“入职指南”——把它从一个通用型 Agent 转化为具备流程化知识、领域专家经验并随身携带工具箱的专项 Agent。

skill-name/
├── SKILL.md           # 必需：工作流 + 指令（<500 行）
├── scripts/           # 可选：确定性、可重复的操作
├── references/        # 可选：按需加载到上下文
└── assets/            # 可选：仅用于输出结果，绝不加载到上下文

默认前提：Claude 本身就已经非常聪明。 只补充 Claude 不知道的信息。质疑每一段文字：“它真的配消耗这些 Token 吗？”

工作流

复制这份 Checklist，在完成对应步骤时打勾：

Skill Forge 进度：

- [ ] 步骤 1：梳理 Skill 需求 ⚠️ 必需
  - [ ] 1.1 明确核心目的与具体使用场景
  - [ ] 1.2 收集 3 个以上的具体使用示例
  - [ ] 1.3 识别触发场景与关键词
- [ ] 步骤 2：规划架构
  - [ ] 2.1 明确可复用的资源（脚本、参考文档、资产）
  - [ ] 2.2 设计渐进式加载策略
  - [ ] 2.3 设计参数体系（如适用）
- [ ] 步骤 3：初始化 ⛔ 阻塞性（若 Skill 已存在则跳过）
  - [ ] 运行 init_skill.py
- [ ] 步骤 4：撰写 Description
  - [ ] 加载 references/description-guide.md
  - [ ] 运用关键词轰炸法
- [ ] 步骤 5：撰写 SKILL.md 正文
  - [ ] 5.1 设定铁律
  - [ ] 5.2 设计工作流 Checklist
  - [ ] 5.3 添加确认关卡
  - [ ] 5.4 添加参数体系（如适用）
  - [ ] 5.5 运用写作技巧
  - [ ] 5.6 添加反模式列表
  - [ ] 5.7 添加交付前 Checklist
- [ ] 步骤 6：构建资源文件
  - [ ] 6.1 实现并测试脚本
  - [ ] 6.2 编写参考文档
  - [ ] 6.3 准备资产文件
- [ ] 步骤 7：评审 ⚠️ 必需
  - [ ] 执行交付前 Checklist（步骤 9）
  - [ ] 向用户展示总结以供确认
- [ ] 步骤 8：打包
  - [ ] 运行 package_skill.py
- [ ] 步骤 9：基于实际使用不断迭代

步骤 1：梳理 Skill 需求 ⚠️ 必需

自问以下问题：

• 这个 Skill 到底解决了哪些 Claude 自己搞不好的特定痛点？
• 用户想要触发这个 Skill 时，字面上会输入什么？
• 3-5 个带有真实输入和预期输出的具体使用示例是什么？

如果需求模糊，向用户提问（不要一次性全砸过去——先问最关键的）：

• “能给我 3 个你打算怎么用这个 Skill 的具体例子吗？”
• “你会怎么在对话里触发它？”
• “你心目中理想的输出结果长什么样？”

在拿到至少 3 个具体示例之前，严禁直接开始写代码或文档。

步骤 2：规划架构

针对每个具体示例，问自己：

1. 哪些操作是确定性、可重复的？ → 放进 scripts/
2. Claude 在特定步骤需要哪些专业知识？ → 放进 references/
3. 哪些文件只会在输出结果中使用，不需要参与推理？ → 放进 assets/

核心约束：

• SKILL.md 必须控制在 500 行以内 — 其余内容全部抽离到 references/
• 参考文档按领域分类组织，嵌套层级严禁超过一级
• 加载 references/architecture-guide.md 以获取渐进式加载模式与组织策略

步骤 3：初始化 ⛔ 阻塞性

如果是在修改现有 Skill，请跳过此步。否则运行：

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

该脚本会自动生成包含铁律占位符、工作流 Checklist 和标准目录结构的模板。

步骤 4：撰写 Description

这是 Skill 中最容易被低估的部分。Description 直接决定了：

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

加载 references/description-guide.md 了解关键词轰炸技术以及优劣案例。

铁律：绝对不要把“使用时机”写在 SKILL.md 正文中。因为正文是在触发之后才加载的——到时候就太晚了。

步骤 5：撰写 SKILL.md 正文

根据每个子步骤按需加载参考文件：

5.1 设定铁律

问自己：“模型在执行这个 Skill 时，最容易犯的一个错误是什么？”
写一条硬性规则封死这个漏洞。把它放在 SKILL.md 最顶部，紧跟在 Frontmatter 之后。

→ 加载 references/writing-techniques.md 查看铁律范式与危险信号警示。

5.2 设计工作流 Checklist

创建一个可追踪的 Checklist，包含：

• 绝不能跳过的步骤标记为 ⚠️ 必需
• 前置依赖条件标记为 ⛔ 阻塞性
• 复杂步骤使用嵌套子步骤
• 依赖前面选择的步骤使用 (条件性)

→ 加载 references/workflow-patterns.md 查看 Checklist 范式与示例。

5.3 添加确认关卡

在进行以下操作前，强制模型停下来向用户确认：

• 破坏性操作（删除、覆盖、修改）
• 成本高昂的生成式操作
• 基于分析结果直接应用变更

→ 加载 references/workflow-patterns.md 查看确认关卡范式。

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

如果这个 Skill 能受益于 --quick、--style、--regenerate N 等 Flag：

→ 加载 references/parameter-system.md 了解 $ARGUMENTS、Flag 标记、argument-hint 参数提示以及部分执行范式。

5.5 运用写作技巧

能显著提升输出质量的三大技巧：

1. 提问式指令：给出启发性问题，而不是含糊的指令
2. 反模式文档：明确列出“绝对不能怎么做”
3. 铁律 + 危险信号：防止模型投机取巧偷懒

→ 加载 references/writing-techniques.md 获取三大技巧及具体示例。

5.6 添加反模式列表

问自己：“Claude 在处理这项任务时，最偷懒的默认行为会是什么样？” 然后明确禁止它。

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

5.7 添加交付前 Checklist

添加具体、可验证的检查项。每个检查项必须足够明确，以便模型通过观察输出结果就能自查。不要写“保证高质量”这种废话，而是写“不得残留占位符文本（如 TODO、FIXME、xxx）”。

→ 加载 references/output-patterns.md 查看 Checklist 范式与基于优先级的输出模式。

写作原则

• 精炼：只写 Claude 不知道的信息
• 祈使句式：使用“分析输入”，而不是“你应该分析输入”
• 自由度要与脆弱度匹配：独木桥 → 严格防撞栏；大草原 → 多条路径自由发挥
  • 高自由度（文本）：多种有效实现路线均可
  • 中自由度（伪代码/参数）：有推荐范式，允许合理变通
  • 低自由度（特定脚本）：脆弱易错操作，一致性至关重要

步骤 6：构建资源文件

脚本（Scripts）

• 封装确定性、可重复的操作
• 脚本无需加载到上下文即可直接执行 — 大幅节省 Token
• 在打包前测试每个脚本
• 在 SKILL.md 中只记录命令和参数，严禁贴入源代码

参考文档（References）

• 按业务领域组织，不要按文件类型组织
• 目录嵌套严禁超过一级
• SKILL.md 中的每个文件引用都必须附带明确的“何时加载”说明
• 大文件（>100 行）顶部必须包含目录导航

静态资产（Assets）

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

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

步骤 7：评审 ⚠️ 必需

在打包前，向用户展示 Skill 汇总并确认。

交付前 Checklist

结构检查

• [ ] SKILL.md 控制在 500 行以内
• [ ] Frontmatter 仅包含 name 和 description（以及可选的 allowed-tools、license、metadata）
• [ ] Description 包含了触发关键词和使用场景
• [ ] 无 README.md、CHANGELOG.md 等无关文件
• [ ] 未残留初始化时生成的示例/占位符文件

质量检查

• [ ] 顶部包含铁律或核心约束
• [ ] 包含带有 ⚠️/⛔ 标记的可追踪工作流 Checklist
• [ ] 破坏性/高消耗操作前设置了确认关卡
• [ ] 使用提问式指令，而非含糊的口令
• [ ] 列出了反模式（明确禁止事项）
• [ ] 参考文档采用渐进式加载，而非一次性全盘塞入

资源检查

• [ ] 脚本已通过测试且具备可执行权限
• [ ] 参考文档按领域分类，且仅有一级嵌套
• [ ] 大型参考文档包含了顶部目录导航
• [ ] 静态资产仅在输出中使用，未被加载进上下文

需避开的反模式

• 把所有内容强行塞进单个超长 SKILL.md（>500 行）
• 撰写形如“用于 X 的工具”这种含糊不清的 Description
• 缺乏工作流 —— 放任模型自由发挥
• 缺乏确认关卡 —— 模型未经审核直接一路狂奔到结束
• 包含“确保高质量”等含糊指令，而非具体可查的指标
• 混入 README.md、INSTALLATION_GUIDE.md 等说明文档
• 把“使用时机”写在 SKILL.md 正文里而非 description 字段中

步骤 8：打包

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

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

步骤 9：基于实际使用不断迭代

在实际投产使用后：

1. 观察模型在哪些地方容易挣扎或表现不稳定
2. 找出需要改进的工作流步骤
3. 补充更具体的指令、示例或反模式
4. 重新测试并重新打包