| 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，回答以下问题：
-
主文件 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：质量检查
发布前检查清单：
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 — 技能架构设计原则
