⚡

设计工作流技能指南Skill designing-workflow-skills

这个技能用于指导和结构化基于工作流的Claude Code技能设计，包括多阶段流程、决策树、子代理委派、渐进式披露等模式。适用于开发涉及序列管道、路由模式、安全门、任务跟踪、分阶段执行的工作流技能，并提升技能质量和可靠性。关键词：工作流设计、技能开发、Claude Code、结构模式、多步流程、AI技能架构、工具优化、反模式避免。

架构设计 0 次安装 0 次浏览 更新于 3/14/2026

name: designing-workflow-skills description: >- 指导基于工作流的Claude Code技能的设计和结构化，包括多阶段流程、决策树、子代理委派和渐进式披露。适用于创建涉及序列管道、路由模式、安全门、任务跟踪、分阶段执行或任何多步工作流的技能。也适用于审查或重构现有工作流技能以提升质量。 allowed-tools:

  • Read
  • Glob
  • Grep
  • TodoRead
  • TodoWrite

设计工作流技能

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

基本原则

<essential_principles>

<principle name=“描述即触发器”> description字段是唯一控制技能激活的因素。

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

“何时使用”和“何时不使用”部分仍有其用途：它们在技能激活后界定LLM的行为。“何时不使用”应指定具体替代方案：例如“使用Semgrep进行简单模式匹配”，而不是“不用于简单任务”。 </principle>

<principle name=“编号阶段”> 阶段必须编号，并包含进入和退出标准。

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

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

<principle name=“工具匹配执行器”> 工具必须与执行器匹配。

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

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

<principle name=“渐进式披露”> 渐进式披露是结构性的，而非可选的。

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

<principle name=“可扩展工具模式”> 指令必须产生可扩展的工具调用模式。

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

<principle name=“自由度”> 将指令特异性与任务脆弱性匹配。

并非每个步骤都需要相同程度的规范。根据步骤校准：

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

一个技能可以混合自由度级别。例如，安全审计技能可能在发现阶段使用高自由度（“探索代码库以查找认证模式”），在报告阶段使用低自由度（“准确使用此严重性分类表”）。 </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:
  - [所需最少工具]
# 可选字段——参见tool-assignment-guide.md获取完整参考：
# disable-model-invocation: true    # 仅用户可调用（非Claude）
# user-invocable: false             # 仅Claude可调用（从/菜单隐藏）
# context: fork                     # 在隔离子代理上下文中运行
# agent: Explore                    # 子代理类型（需要context: fork）
# model: [模型名称]               # 技能激活时切换模型
# argument-hint: "[文件名]"       # 自动完成期间显示的提示
---

# 标题

## 基本原则
[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，对于基本原则