designing-workflow-skills

设计工作流技能

遵循结构模式，而非依赖散文式指令，构建能够可靠执行的工作流技能。

核心原则

<essential_principles>

**只有 `description` 字段决定技能何时激活。**

Claude 仅根据技能前置元数据中的 description 来决定是否加载技能。SKILL.md 正文——包括“何时使用”和“何时不使用”部分——只有在技能已激活后才会读取。请在描述中写明触发关键词、使用场景和排除情况。无论正文写了什么，糟糕的描述都会导致错误激活或漏掉激活。

“何时使用”和“何时不使用”部分仍然有用：技能激活后，它们可以限定 LLM 的行为。“何时不使用”部分应指出具体的替代方案，例如：“简单的模式匹配请使用 Semgrep”，而不是“不要用于简单任务”。

**阶段必须编号，并包含进入和退出条件。**

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

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

**工具必须与执行者相匹配。**

技能在前置元数据中使用 allowed-tools:。Agent 在前置元数据中使用 tools:。子 Agent 从其 subagent_type 获取工具。切勿列出组件不会使用的工具。对于有专用工具（Glob、Grep、Read、Write、Edit）的操作，切勿使用 Bash。

大多数技能和 Agent 都应在工具列表中包含 TodoRead 和 TodoWrite——它们可以在多步骤执行期间跟踪进度，即使技能不显式管理任务，也很有用。

**渐进式披露是结构要求，而非可选项。**

SKILL.md 应少于 500 行。它只包含 LLM 每次调用都需要的内容：原则、路由、快速参考和链接。详细模式放在 references/ 中。流程步骤放在 workflows/ 中。引用只允许一层深度，不要创建引用链。

**指令必须生成可扩展的工具调用模式。**

每条工作流指令在运行时都会转化为工具调用。如果工作流要针对 M 种模式搜索 N 个文件，请合并为一个正则表达式，而不是发起 N×M 次调用。如果工作流要为每个项目派生子 Agent，请使用批处理，而不是每个文件派生一个子 Agent。采用 10,000 个文件测试：在脑海中对大型代码库运行该工作流，并检查工具调用次数是否保持在有界范围内。请参阅 anti-patterns.md AP-18 和 AP-19。

**根据任务的脆弱程度调整指令的具体程度。**

并非每个步骤都需要相同程度的规定。应按步骤调整：

• 低自由度（精确命令，不得变更）：脆弱的操作——数据库迁移、加密、破坏性操作。“严格运行此脚本。”
• 中自由度（带参数的伪代码）：可接受变通的首选模式。“使用此模板，并按需自定义。”
• 高自由度（启发式方法和判断）：多变的任务——代码审查、探索、文档编写。“分析结构并提出改进建议。”

一个技能可以混合不同的自由度。例如，安全审计技能可以在发现阶段采用高自由度（“探索代码库中的身份验证模式”），并在报告阶段采用低自由度（“严格使用此严重性分类表”）。

</essential_principles>

适用场景

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

不适用场景

• 不含工作流的简单单一用途技能（仅提供指导）——直接编写 SKILL.md
• 编写技能的实际领域内容（这里讲解的是结构，而非领域专业知识）
• 插件配置（plugin.json、hooks、commands）——请使用插件开发指南
• 非 Claude Code 技能开发——本指南专门介绍技能架构

模式选择

为技能选择合适的结构模式。请阅读 workflow-patterns.md 中的完整模式说明。

How many distinct paths does the skill have?
|
+-- One path, always the same
|   +-- Does it perform destructive actions?
|       +-- YES -> Safety Gate Pattern
|       +-- NO  -> Linear Progression Pattern
|
+-- Multiple independent paths from shared setup
|   +-- Routing Pattern
|
+-- Multiple dependent steps in sequence
    +-- Do steps have complex dependencies?
        +-- YES -> Task-Driven Pattern
        +-- NO  -> Sequential Pipeline Pattern

模式摘要

模式	适用场景	主要特点
路由	从共用入口分流至多个独立任务	路由表将意图映射到工作流文件
顺序流水线	各步骤相互依赖，且每步的结果会传递给下一步	自动检测可能会从部分进度处恢复
线性推进	每次都相同的单一路径	带有进入/退出条件的编号阶段
安全关卡	破坏性或不可逆操作	执行前设置两道确认关卡
任务驱动	依赖关系复杂，且能容忍部分失败	使用 TaskCreate/TaskUpdate 跟踪依赖关系

结构剖析

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

---
name: kebab-case-name
description: "Third-person description with trigger keywords — this is how Claude decides to activate the skill"
allowed-tools: Tool1 Tool2 Tool3  # space-delimited list of tool names
# Optional fields — see tool-assignment-guide.md for full reference:
# disable-model-invocation: true    # Only user can invoke (not Claude)
# user-invocable: false             # Only Claude can invoke (hidden from / menu)
# context: fork                     # Run in isolated subagent context
# agent: Explore                    # Subagent type (requires context: fork)
# model: [model-name]               # Switch model when skill is active
# argument-hint: "[filename]"       # Hint shown during autocomplete
---

# Title

## Essential Principles
[3-5 non-negotiable rules with WHY explanations]

## When to Use
[4-6 specific scenarios — scopes behavior after activation]

## When NOT to Use
[3-5 scenarios with named alternatives — scopes behavior after activation]

## [Pattern-Specific Section]
[Routing table / Pipeline steps / Phase list / Gates]

## Quick Reference
[Compact tables for frequently-needed info]

## Reference Index
[Links to all supporting files]

## Success Criteria
[Checklist for output validation]

技能支持三种字符串替换：用于参数和会话 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	子 Agent 提示词含糊	明确指定要分析什么、查找什么以及返回什么
AP-15	倾倒参考资料	教会判断，而不是原样复制文档
AP-16	缺少合理化说辞	为审计技能添加“应拒绝的合理化说辞”
AP-17	缺少具体示例	为关键说明展示输入 -> 输出
AP-18	笛卡尔积式工具调用	将多个模式合并为单个正则表达式，只 grep 一次，然后筛选
AP-19	无限制地生成子 Agent	将项目分批，每批使用一个子 Agent
AP-20	描述总结工作流	描述只写触发条件，绝不写工作流步骤

AP-10（缺少默认／回退路由）、AP-14（Agent 中缺少工具选择理由）和 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
只读 Agent	Read、Grep、Glob、TodoRead、TodoWrite
操作型 Agent	Read、Grep、Glob、Write、Bash、TodoRead、TodoWrite

关键规则：

• 使用 Glob（而非 find）、Grep（而非 grep）、Read（而非 cat）——始终优先使用专用工具
• 技能使用 allowed-tools:——Agent 使用 tools:
• 只列出说明中实际引用的工具
• 只读组件绝不能使用 Write 或 Bash

应拒绝的合理化说辞

设计工作流技能时，应拒绝以下捷径：

合理化说辞	错误原因
“下一阶段显而易见。”	大模型不会从散文中推断顺序。为阶段编号。
“退出标准是隐含的。”	隐含的标准就会被跳过。要明确写出。
“一个大型 SKILL.md 更简单。”	写起来更简单，执行起来更糟。超过 500 行后，大模型会难以集中注意力。
“描述没那么重要。”	描述决定技能如何触发。描述不佳会导致错误触发或漏触发。
“Bash 什么都能做。”	Bash 文件操作很脆弱。专用工具在处理编码、权限和格式方面更可靠。
“大模型会自行判断要用哪些工具。”	它会猜错。要明确指定每项操作使用的工具。
“我之后再补充细节。”	不完整的技能发布后依然不完整。写作前先完成设计。

参考索引

文件	内容
workflow-patterns.md	5 种模式，包含结构骨架和示例
anti-patterns.md	20 种反模式，包含修正前后对比
tool-assignment-guide.md	工具选择矩阵、组件对比和子 Agent 指南
progressive-disclosure-guide.md	内容拆分规则、500 行规则和篇幅指南

工作流	用途
design-a-workflow-skill.md	从确定范围到自我审查的 6 阶段创建流程
review-checklist.md	用于检查是否已准备好提交的结构化自我审查清单

成功标准

设计良好的工作流技能应：

• 包含“何时使用”和“何时不使用”两部分
• 使用清晰可辨的模式（路由、流水线、线性、安全门控或任务驱动）
• 为所有阶段编号，并列出进入和退出标准
• 仅列出实际使用的工具（遵循最小权限原则）
• 将 SKILL.md 控制在 500 行以内，详细内容放在 references/workflows 中
• 不含硬编码路径（使用 {baseDir}）
• 不含失效的文件引用
• 不含引用链（所有链接均从 SKILL.md 一跳可达）
• 在工作流末尾包含验证步骤
• 描述能正确触发（使用第三人称和具体关键词）
• 为关键指令提供具体示例
• 说明基本原则背后的原因，而不只是说明做什么