skill-smith

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。

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