---
name: skill-smith
description: "Use when 需要创建新的 AI Agent 技能、改进已有 SKILL.md 文件、设计技能工作流或不确定技能该如何组织时。触发场景：创建技能、新建技能、写技能、技能开发、skill-smith、设计技能、编写SKILL.md、制作技能、开发skill、如何写一个好技能、技能质量不好怎么改进。"
---

# 技能铸造师

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

## 什么是技能

技能是给 AI Agent 的"专项培训手册"——把它从通用助手变成领域专家。好的技能应该：
- 提供 Claude 不具备的领域知识或流程约束
- 让输出更一致、更可预测
- 减少用户每次都要重复解释的上下文

---

## 工作流

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

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

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

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

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

### Step 2：架构规划

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

1. **主文件** `SKILL.md`：
   - 核心工作流是什么？（步骤清单）
   - 有哪些铁律（必须遵守的规则）？
   - 需要哪些用户确认门控？

2. **参考文档** `references/`：
   - 哪些内容是重型参考资料（检查清单、模板、规范）？
   - 按需加载哪些文档（在工作流的哪个步骤加载）？
   - 每个 reference 文件聚焦一个主题

3. **资源文件** `assets/`（可选）：
   - 用于输出但不用于推理的文件（图片、固定模板）

**架构决策原则**：
- `SKILL.md` 控制在 500 行以内
- 超出 500 行的内容移到 `references/`
- 每个 reference 文件聚焦单一主题

### Step 3：编写 SKILL.md

#### 3.1 Frontmatter（决定触发时机）

加载 `references/description-guide.md`。

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

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

#### 3.2 铁律（Iron Law）

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

```markdown
# 技能名称

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

#### 3.3 工作流（核心内容）

加载 `references/workflow-patterns.md`。

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

```markdown
## 工作流

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

**确认门控示例**：
```markdown
**将以上内容展示给用户确认，批准后才继续。**
```

#### 3.4 参考资源

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

```markdown
## 参考资源

- `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` — 技能架构设计原则