designing-workflow-skills

设计工作流技能

通过遵循结构模式而非散文，构建可靠执行的工作流技能。

核心原则

<essential_principles>

<principle name="description-is-the-trigger">
description 字段是唯一控制技能何时激活的因素。

Claude 仅根据其 frontmatter 中的 description 决定是否加载技能。SKILL.md 的主体——包括“何时使用”和“何时不使用”部分——只有在技能激活后才会被读取。将触发关键词、用例和排除条件放在 description 中。糟糕的描述会导致错误的激活或遗漏激活，无论主体内容如何。

“何时使用”和“何时不使用”部分仍然有其用途：它们限定了 LLM 在激活后的行为范围。“何时不使用”应明确指定替代方案：使用“Semgrep 进行简单模式匹配”，而不是“不用于简单任务”。
</principle>

<principle name="numbered-phases">
阶段必须编号，并包含进入和退出条件。

未编号的散文式指令会导致不可靠的执行顺序。每个阶段需要：

• 一个编号（阶段 1、阶段 2、……）
• 进入条件（开始前必须满足的条件）
• 编号的操作（要执行的操作）
• 退出条件（如何知道完成）
  </principle>

<principle name="tools-match-executor">
工具必须与执行者匹配。

技能使用 frontmatter 中的 allowed-tools:。代理使用 frontmatter 中的 tools:。子代理从其 subagent_type 获取工具。永远不要列出组件不使用的工具。永远不要对有专用工具（Glob、Grep、Read、Write、Edit）的操作使用 Bash。

大多数技能和代理应在工具列表中包含 TodoRead 和 TodoWrite——这些工具支持多步骤执行期间的进度跟踪，即使对于不显式管理任务的技能也很有用。
</principle>

<principle name="progressive-disclosure">
渐进式披露是结构性的，而非可选的。

SKILL.md 保持在 500 行以内。它只包含 LLM 每次调用所需的内容：原则、路由、快速参考和链接。详细模式放在 references/ 中。逐步过程放在 workflows/ 中。仅一层深度——没有引用链。
</principle>

<principle name="scalable-tool-patterns">
指令必须产生可扩展的工具调用模式。

每个工作流指令在运行时都会变成工具调用。如果工作流搜索 N 个文件中的 M 个模式，应合并为一个正则表达式——而不是 N×M 次调用。如果工作流为每个项目生成子代理，应使用批处理——而不是每个文件一个子代理。应用 10,000 文件测试：在脑海中针对大型仓库运行工作流，并检查工具调用次数是否保持有界。参见 anti-patterns.md 中的 AP-18 和 AP-19。
</principle>

<principle name="degrees-of-freedom">
将指令的详细程度与任务的脆弱性匹配。

并非每个步骤都需要相同的规范程度。根据步骤进行调整：

• 低自由度（精确命令，无变化）：脆弱操作——数据库迁移、加密、破坏性操作。“精确运行此脚本。”
• 中自由度（带参数的伪代码）：允许变化的优选模式。“使用此模板并根据需要自定义。”
• 高自由度（启发式和判断）：可变任务——代码审查、探索、文档。“分析结构并提出改进建议。”

一个技能可以混合不同的自由度级别。安全审计技能可能在发现阶段使用高自由度（“探索代码库中的认证模式”），在报告阶段使用低自由度（“精确使用此严重性分类表”）。
</principle>

</essential_principles>

何时使用

• 设计具有多步骤工作流或分阶段执行的新技能
• 创建在多个独立任务之间路由的技能
• 构建具有安全门（需要确认的破坏性操作）的技能
• 结构化使用子代理或任务跟踪的技能
• 审查或重构现有工作流技能以提高质量
• 决定如何在 SKILL.md、references/ 和 workflows/ 之间拆分内容

何时不使用

• 简单的单用途技能，无工作流（仅指导）——直接编写 SKILL.md
• 编写技能的实际领域内容（本技能教授结构，而非领域专业知识）
• 插件配置（plugin.json、hooks、commands）——使用插件开发指南
• 非技能的 Claude Code 开发——本技能专门针对技能架构

模式选择

为你的技能结构选择正确的模式。阅读 workflow-patterns.md 中的完整模式描述。

技能有多少条不同的路径？
|
+-- 一条路径，始终相同
|   +-- 是否执行破坏性操作？
|       +-- 是 -> 安全门模式
|       +-- 否 -> 线性推进模式
|
+-- 从共享设置出发的多条独立路径
|   +-- 路由模式
|
+-- 顺序中的多个依赖步骤
    +-- 步骤是否有复杂依赖？
        +-- 是 -> 任务驱动模式
        +-- 否 -> 顺序管道模式

模式总结

模式	使用时机	关键特征
路由	从共享输入出发的多个独立任务	路由表将意图映射到工作流文件
顺序管道	依赖步骤，每个步骤输入给下一步	自动检测可从部分进度恢复
线性推进	单一路径，每次都相同	带进入/退出条件的编号阶段
安全门	破坏性/不可逆操作	执行前两个确认门
任务驱动	复杂依赖，部分失败容忍	带依赖跟踪的 TaskCreate/TaskUpdate

结构解剖

每个工作流技能都需要这个骨架，无论采用何种模式：

---
name: kebab-case-name
description: "第三人称描述，包含触发关键词——这是 Claude 决定激活技能的依据"
allowed-tools: Tool1 Tool2 Tool3  # 空格分隔的工具名称列表
# 可选字段——完整参考见 tool-assignment-guide.md：
# disable-model-invocation: true    # 仅用户可调用（Claude 不可）
# user-invocable: false             # 仅 Claude 可调用（从 / 菜单隐藏）
# context: fork                     # 在隔离的子代理上下文中运行
# agent: Explore                    # 子代理类型（需要 context: fork）
# model: [model-name]               # 技能激活时切换模型
# argument-hint: "[filename]"       # 自动完成时显示的提示
---

# 标题

## 核心原则
[3-5 条不可协商的规则，附 WHY 解释]

## 何时使用
[4-6 个具体场景——限定激活后的行为]

## 何时不使用
[3-5 个场景，附命名替代方案——限定激活后的行为]

## [模式特定部分]
[路由表 / 管道步骤 / 阶段列表 / 门]

## 快速参考
[常用信息的紧凑表格]

## 参考索引
[所有支持文件的链接]

## 成功标准
[输出验证的检查清单]

技能支持三种类型的字符串替换：以美元符号为前缀的变量用于参数和会话 ID，以及感叹号反引号语法用于 shell 预处理。技能加载器在 Claude 看到文件之前处理这些——即使在代码块内部也是如此——因此永远不要在文档文本中使用原始语法。参见 tool-assignment-guide.md 获取完整的变量参考和使用指南。

反模式快速参考

最常见的错误。完整目录及前后修复见 anti-patterns.md。

AP	反模式	一行修复
AP-1	缺少目标/反目标	添加“何时使用”和“何时不使用”部分
AP-2	庞大的 SKILL.md（超过 500 行）	拆分为 references/ 和 workflows/
AP-3	引用链（A -> B -> C）	所有文件距离 SKILL.md 一跳
AP-4	硬编码路径	对所有内部路径使用 {baseDir}
AP-5	损坏的文件引用	提交前验证每个路径可解析
AP-6	未编号的阶段	为每个阶段编号并附进入/退出条件
AP-7	缺少退出条件	为每个阶段定义“完成”的含义
AP-8	无验证步骤	在每个工作流末尾添加验证
AP-9	模糊的路由关键词	为每个工作流路由使用独特的关键词
AP-11	工具使用不当	使用 Glob/Grep/Read，而非 Bash 等价物
AP-12	过度授权的工具	移除未实际使用的工具
AP-13	模糊的子代理提示	指定要分析、查找和返回的内容
AP-15	参考转储	教授判断力，而非原始文档
AP-16	缺少合理化拒绝	为审计技能添加“应拒绝的合理化”
AP-17	无具体示例	为关键指令展示输入 -> 输出
AP-18	笛卡尔积工具调用	将模式合并为单个正则表达式，grep 一次，然后过滤
AP-19	无限制的子代理生成	将项目分批，每批一个子代理
AP-20	描述总结了工作流	描述 = 仅触发条件，绝不包含工作流步骤

AP-10（无默认/回退路由）、AP-14（代理中缺少工具理由）和 AP-20（描述总结了工作流）在完整目录中。AP-20 因其高影响而包含在上述快速参考中。

工具分配快速参考

将你的组件类型映射到正确的工具集。完整指南见 tool-assignment-guide.md。

组件类型	典型工具
只读分析技能	Read, Glob, Grep, TodoRead, TodoWrite
交互式分析技能	Read, Glob, Grep, AskUserQuestion, TodoRead, TodoWrite
代码生成技能	Read, Glob, Grep, Write, Bash, TodoRead, TodoWrite
管道技能	Read, Write, Glob, Grep, Bash, AskUserQuestion, Task, TaskCreate, TaskList, TaskUpdate, TodoRead, TodoWrite
只读代理	Read, Grep, Glob, TodoRead, TodoWrite
操作代理	Read, Grep, Glob, Write, Bash, TodoRead, TodoWrite

关键规则：

• 使用 Glob（而非 find）、Grep（而非 grep）、Read（而非 cat）——始终优先使用专用工具
• 技能使用 allowed-tools:——代理使用 tools:
• 仅列出指令实际引用的工具
• 只读组件绝不应包含 Write 或 Bash

应拒绝的合理化

在设计工作流技能时，拒绝这些捷径：

合理化	为什么错误
“下一个阶段很明显”	LLM 不会从散文中推断顺序。给阶段编号。
“退出条件是隐含的”	隐含的条件就是被跳过的条件。显式写出它们。
“一个大的 SKILL.md 更简单”	编写更简单，执行更糟糕。LLM 在超过 500 行后会失去焦点。
“描述不太重要”	描述是技能被触发的方式。糟糕的描述会导致错误的激活或遗漏激活。
“Bash 可以做所有事情”	Bash 文件操作很脆弱。专用工具能更好地处理编码、权限和格式化。
“LLM 会自己找出工具”	它会猜错。为每个操作指定确切的工具。
“我稍后再添加细节”	不完整的技能发布时就是不完整的。在编写之前完全设计好。

参考索引

文件	内容
workflow-patterns.md	5 种模式，附结构骨架和示例
anti-patterns.md	20 种反模式，附前后修复
tool-assignment-guide.md	工具选择矩阵、组件比较、子代理指导
progressive-disclosure-guide.md	内容拆分规则、500 行规则、大小指南

工作流	目的
design-a-workflow-skill.md	从范围到自我审查的 6 阶段创建过程
review-checklist.md	用于提交准备的结构化自我审查清单

成功标准

一个设计良好的工作流技能：

• [ ] 包含“何时使用”和“何时不使用”部分
• [ ] 使用可识别的模式（路由、管道、线性、安全门或任务驱动）
• [ ] 所有阶段都编号并附进入和退出条件
• [ ] 仅列出实际使用的工具（最小权限）
• [ ] 保持 SKILL.md 在 500 行以内，详细信息放在 references/workflows 中
• [ ] 没有硬编码路径（使用 {baseDir}）
• [ ] 没有损坏的文件引用
• [ ] 没有引用链（所有链接距离 SKILL.md 一跳）
• [ ] 在工作流末尾包含验证步骤
• [ ] 描述能正确触发（第三人称、特定关键词）
• [ ] 为关键指令包含具体示例
• [ ] 解释核心原则的 WHY，而不仅仅是 WHAT