skill-smith

# 技能铸造师 铁律：每一行内容都要对得起 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` — 技能架构设计原则