技能铸造师

铁律：每一行内容都要对得起 token 消耗。不写 Claude 已经知道的东西，只写它不知道的领域知识、流程规范和决策框架。

什么是技能

技能是给 AI Agent 的"专项培训手册"——把它从通用助手变成领域专家。好的技能应该：

提供 Claude 不具备的领域知识或流程约束
让输出更一致、更可预测
减少用户每次都要重复解释的上下文

工作流

Step 1：理解需求（必须完成，不可跳过）

至少收集 3 个具体的使用示例：

询问用户：
"请给我 3 个你会如何使用这个技能的具体例子，
包括你会说什么，以及你期望得到什么输出。"

没有 3 个具体例子，不进入下一步。

同时了解：

"现在没有这个技能时，你是怎么做的？"（理解 Gap）
"这个技能最重要的限制/铁律是什么？"
"输出格式有特殊要求吗？"

Step 2：架构规划

加载 references/architecture-guide.md，回答以下问题：

主文件 SKILL.md：
- 核心工作流是什么？（步骤清单）
- 有哪些铁律（必须遵守的规则）？
- 需要哪些用户确认门控？
参考文档 references/：
- 哪些内容是重型参考资料（检查清单、模板、规范）？
- 按需加载哪些文档（在工作流的哪个步骤加载）？
- 每个 reference 文件聚焦一个主题
资源文件 assets/（可选）：
- 用于输出但不用于推理的文件（图片、固定模板）

架构决策原则：

SKILL.md 控制在 500 行以内
超出 500 行的内容移到 references/
每个 reference 文件聚焦单一主题

Step 3：编写 SKILL.md

3.1 Frontmatter（决定触发时机）

加载 references/description-guide.md。

---
name: skill-name
description: "核心描述。触发词：[关键词 1]、[关键词 2]、[关键词 3]..."
---

描述要求：

前 50 字说明解决什么问题
列出 10-20 个触发关键词（中英文都要包含）
包含触发场景的动词（创建、分析、优化、生成...）

3.2 铁律（Iron Law）

在标题下方立即写出最重要的约束：

# 技能名称

铁律：[最重要的行为约束，用户最需要知道的一条规则]

3.3 工作流（核心内容）

加载 references/workflow-patterns.md。

使用勾选清单格式，让 AI 可以追踪进度：

## 工作流

- [ ] 第一步：[描述]（标注是否必须）
  - [子步骤 1]
  - [子步骤 2]
- [ ] 第二步：[描述]
  - 用户确认门控：[在继续前必须获得用户批准]

确认门控示例：

**将以上内容展示给用户确认，批准后才继续。**

3.4 参考资源

文件末尾列出所有 references 及加载时机：

## 参考资源

- `references/checklist.md` — 在第 3 步加载，用于[目的]
- `references/template.md` — 在输出阶段加载，用于[目的]

Step 4：编写 References

每个 reference 文件：

聚焦单一主题（不要"大杂烩"）
以表格、清单、代码示例为主（减少叙述性文字）
文件名描述内容（security-checklist.md 而非 ref1.md）

Step 5：质量检查

发布前检查清单：

SKILL.md 是否 < 500 行？
每段内容是否都对得起 token（删掉 Claude 已经知道的废话）？
description 是否包含了足够的触发关键词？
铁律是否明确（最重要的约束）？
工作流中是否有合适的用户确认门控？
是否在第一步就要求了 3 个具体例子？
references 是否按需加载而非一次性全加载？
是否有反模式清单（告诉 AI 不该做什么）？

Step 6：README.md

编写简短的安装和使用说明：

安装命令（npx skills add ...）
触发方式
主要功能和使用场景
简单的使用示例

技能目录结构

skill-name/
├── SKILL.md          # 主文件（<500行）
├── README.md         # 安装和使用说明
└── references/       # 按需加载的参考文档
    ├── checklist.md
    └── template.md

反模式警告

反模式	识别特征	处理方式
废话文学	解释 Claude 已知的基础概念	删除
一次性全加载	所有 references 在开头全部加载	改为按步骤按需加载
没有铁律	缺少明确的行为约束	识别最重要的约束写到最前面
没有确认门控	自作主张连续执行	在关键决策前增加用户确认
超大单文件	SKILL.md > 1000 行	将重型内容移到 references
触发词不足	description 太短，只有 1-2 句	增加 10-20 个触发关键词

警告：当你想跳过需求收集或质量检查时

遇到以下想法，立刻停下——未经验证的技能比没有技能更有害（会给 Agent 错误指导）：

借口	现实
"需求很清楚，不需要 3 个例子"	例子的作用是暴露你的假设，不是重复已知信息。没有例子就没有边界检验。
"description 有几个触发词就够了"	触发词不足导致技能无法被发现。10-20 个关键词是最低要求，不是上限。
"SKILL.md 长一点没关系，内容更全面"	超过 500 行的 SKILL.md 会消耗过多 context。把重型内容移到 references。
"这个技能很简单，不需要反模式清单"	简单技能的边界更容易被 Agent 误解。反模式清单是防止误用的护栏。
"用户要的快，先发布再完善"	未完善的技能会被 Agent 错误遵循，修复成本远高于一开始做好。

参考资源

references/description-guide.md — Frontmatter description 编写指南
references/workflow-patterns.md — 工作流设计模式
references/architecture-guide.md — 技能架构设计原则

skill-smith