Back to Details

designing-workflow-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Designing Workflow Skills

设计工作流技能

Build workflow-based skills that execute reliably by following structural patterns, not prose.
遵循结构化模式而非纯文本描述，构建可可靠执行的基于工作流的技能。

Essential Principles

核心原则

<essential_principles>
<principle name="description-is-the-trigger"> **The `description` field is the only thing that controls when a skill activates.**
Claude decides whether to load a skill based solely on its frontmatter 
description
. The body of SKILL.md — including "When to Use" and "When NOT to Use" sections — is only read AFTER the skill is already active. Put your trigger keywords, use cases, and exclusions in the description. A bad description means wrong activations or missed activations regardless of what the body says.
"When to Use" and "When NOT to Use" sections still serve a purpose: they scope the LLM's behavior once active. "When NOT to Use" should name specific alternatives: "use Semgrep for simple pattern matching" not "not for simple tasks." </principle>
<principle name="numbered-phases"> **Phases must be numbered with entry and exit criteria.**
Unnumbered prose instructions produce unreliable execution order. Every phase needs:
  • A number (Phase 1, Phase 2, ...)
  • Entry criteria (what must be true before starting)
  • Numbered actions (what to do)
  • Exit criteria (how to know it's done) </principle>
<principle name="tools-match-executor"> **Tools must match the executor.**
Skills use 
allowed-tools:
in frontmatter. Agents use 
tools:
in frontmatter. Subagents get tools from their 
subagent_type
. Never list tools the component doesn't use. Never use Bash for operations that have dedicated tools (Glob, Grep, Read, Write, Edit).
Most skills and agents should include 
TodoRead
and 
TodoWrite
in their tool list — these enable progress tracking during multi-step execution and are useful even for skills that don't explicitly manage tasks. </principle>
<principle name="progressive-disclosure"> **Progressive disclosure is structural, not optional.**
SKILL.md stays under 500 lines. It contains only what the LLM needs for every invocation: principles, routing, quick references, and links. Detailed patterns go in 
references/
. Step-by-step processes go in 
workflows/
. One level deep — no reference chains. </principle>
<principle name="scalable-tool-patterns"> **Instructions must produce tool-calling patterns that scale.**
Every workflow instruction becomes tool calls at runtime. If a workflow searches N files for M patterns, combine into one regex — not N×M calls. If a workflow spawns subagents per item, use batching — not one subagent per file. Apply the 10,000-file test: mentally run the workflow against a large repo and check that tool call count stays bounded. See anti-patterns.md AP-18 and AP-19. </principle>
<principle name="degrees-of-freedom"> **Match instruction specificity to task fragility.**
Not every step needs the same level of prescription. Calibrate per step:
  • Low freedom (exact commands, no variation): Fragile operations — database migrations, crypto, destructive actions. "Run exactly this script."
  • Medium freedom (pseudocode with parameters): Preferred patterns where variation is acceptable. "Use this template and customize as needed."
  • High freedom (heuristics and judgment): Variable tasks — code review, exploration, documentation. "Analyze the structure and suggest improvements."
A skill can mix freedom levels. A security audit skill might use high freedom for the discovery phase ("explore the codebase for auth patterns") and low freedom for the reporting phase ("use exactly this severity classification table"). </principle>
</essential_principles>
<essential_principles>
<principle name="description-is-the-trigger"> **`description`字段是控制技能何时激活的唯一因素。**
Claude仅根据技能前置元数据中的
description
决定是否加载该技能。SKILL.md的正文内容——包括“适用场景”和“不适用场景”部分——只有在技能激活后才会被读取。请将触发关键词、使用场景和排除条件都放在description中。无论正文内容如何，糟糕的description都会导致技能被错误激活或错过激活时机。
“适用场景”和“不适用场景”仍有其作用：它们会在技能激活后约束大语言模型（LLM）的行为。“不适用场景”应明确指定替代方案：例如“使用Semgrep进行简单模式匹配”，而非“不适用于简单任务”。 </principle>
<principle name="numbered-phases"> **阶段必须编号，并明确进入和退出标准。**
无编号的纯文本指令会导致执行顺序不可靠。每个阶段都需要：
  • 编号（Phase 1、Phase 2……）
  • 进入标准（开始前必须满足的条件）
  • 编号的操作步骤（具体要执行的内容）
  • 退出标准（如何判断该阶段已完成） </principle>
<principle name="tools-match-executor"> **工具必须与执行主体匹配。**
技能在前置元数据中使用
allowed-tools:
，Agent在前置元数据中使用
tools:
，子Agent的工具由其
subagent_type
决定。切勿列出组件不会使用的工具。对于已有专用工具的操作（如Glob、Grep、Read、Write、Edit），切勿使用Bash。
大多数技能和Agent应在工具列表中包含
TodoRead
和
TodoWrite
——它们支持多步骤执行过程中的进度跟踪，即使对于不明确管理任务的技能也很有用。 </principle>
<principle name="progressive-disclosure"> **渐进式披露是结构化要求，而非可选项。**
SKILL.md的内容应控制在500行以内，仅包含LLM每次调用都需要的内容：原则、路由规则、快速参考和链接。详细模式放在
references/
目录下，分步流程放在
workflows/
目录下。所有引用仅允许一级深度——禁止链式引用。 </principle>
<principle name="scalable-tool-patterns"> **指令必须生成可扩展的工具调用模式。**
每个工作流指令最终都会在运行时转化为工具调用。如果某个工作流要在N个文件中搜索M个模式，请将模式合并为单个正则表达式——而非执行N×M次调用。如果某个工作流要为每个项目生成子Agent，请使用批处理方式——而非为每个文件生成一个子Agent。请进行“10000文件测试”：在脑中模拟工作流在大型代码仓库中的执行情况，确保工具调用次数可控。详情请见anti-patterns.md中的AP-18和AP-19。 </principle>
<principle name="degrees-of-freedom"> **指令的具体程度应与任务的脆弱性相匹配。**
并非每个步骤都需要相同程度的约束。请根据步骤调整：
  • 低自由度（精确命令，无变通空间）：适用于脆弱操作——如数据库迁移、加密操作、破坏性操作。例如“严格执行此脚本”。
  • 中等自由度（带参数的伪代码）：是首选模式，适用于允许一定变通的场景。例如“使用此模板并根据需要自定义”。
  • 高自由度（启发式判断）：适用于多变任务——如代码审查、探索性分析、文档编写。例如“分析结构并提出改进建议”。
一个技能可以混合使用不同自由度的步骤。例如，安全审计技能在发现阶段可能使用高自由度（“探索代码库中的认证模式”），而在报告阶段使用低自由度（“严格使用此严重性分类表”）。 </principle>
</essential_principles>

When to Use

适用场景

  • Designing a new skill with multi-step workflows or phased execution
  • Creating a skill that routes between multiple independent tasks
  • Building a skill with safety gates (destructive actions requiring confirmation)
  • Structuring a skill that uses subagents or task tracking
  • Reviewing or refactoring an existing workflow skill for quality
  • Deciding how to split content between SKILL.md, references/, and workflows/
  • 设计包含多步骤工作流或分阶段执行的新技能
  • 创建需要在多个独立任务间路由的技能
  • 构建包含安全门（执行破坏性操作前需确认）的技能
  • 构建使用子Agent或任务跟踪的技能
  • 审查或重构现有工作流技能以提升质量
  • 决定如何在SKILL.md、references/和workflows/之间拆分内容

When NOT to Use

不适用场景

  • Simple single-purpose skills with no workflow (just guidance) — write the SKILL.md directly
  • Writing the actual domain content of a skill (this teaches structure, not domain expertise)
  • Plugin configuration (plugin.json, hooks, commands) — use plugin development guides
  • Non-skill Claude Code development — this is specifically for skill architecture
  • 无工作流的简单单用途技能（仅提供指导）——直接编写SKILL.md即可
  • 编写技能的实际领域内容（本指南仅教授结构，不涉及领域专业知识）
  • 插件配置（plugin.json、钩子、命令）——请使用插件开发指南
  • 非技能类Claude Code开发——本指南专门针对技能架构

Pattern Selection

模式选择

Choose the right pattern for your skill's structure. Read the full pattern description in 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
为你的技能结构选择合适的模式。请查看workflow-patterns.md中的完整模式说明。
你的技能有多少条不同的执行路径？
|
+-- 只有一条固定路径
|   +-- 是否执行破坏性操作？
|       +-- 是 -> 安全门模式
|       +-- 否 -> 线性递进模式
|
+-- 从共享初始化步骤分支到多个独立路径
|   +-- 路由模式
|
+-- 多个相互依赖的步骤按顺序执行
    +-- 步骤是否有复杂依赖关系？
        +-- 是 -> 任务驱动模式
        +-- 否 -> 顺序流水线模式

Pattern Summary

模式摘要

PatternUse WhenKey Feature
RoutingMultiple independent tasks from shared intakeRouting table maps intent to workflow files
Sequential PipelineDependent steps, each feeding the nextAuto-detection may resume from partial progress
Linear ProgressionSingle path, same every timeNumbered phases with entry/exit criteria
Safety GateDestructive/irreversible actionsTwo confirmation gates before execution
Task-DrivenComplex dependencies, partial failure toleranceTaskCreate/TaskUpdate with dependency tracking
模式适用场景核心特性
路由模式从共享输入分支到多个独立任务路由表将意图映射到工作流文件
顺序流水线模式步骤相互依赖，前一步的输出作为后一步的输入可自动检测并从部分进度恢复执行
线性递进模式只有一条固定执行路径带进入/退出标准的编号阶段
安全门模式执行破坏性/不可逆操作执行前需经过两次确认门
任务驱动模式复杂依赖关系、可容忍部分失败使用TaskCreate/TaskUpdate进行依赖跟踪

Structural Anatomy

结构框架

Every workflow skill needs this skeleton, regardless of pattern:
markdown
---
name: kebab-case-name
description: "Third-person description with trigger keywords — this is how Claude decides to activate the skill"
allowed-tools:
  - [minimum tools needed]
无论选择哪种模式，每个工作流技能都需要以下骨架：
markdown
---
name: kebab-case-name
description: "包含触发关键词的第三人称描述——Claude将据此决定是否激活技能"
allowed-tools:
  - [所需的最少工具列表]

Optional fields — see tool-assignment-guide.md for full reference:

可选字段——请查看tool-assignment-guide.md获取完整参考：

disable-model-invocation: true # Only user can invoke (not Claude)

disable-model-invocation: true # 仅允许用户调用（Claude无法调用）

user-invocable: false # Only Claude can invoke (hidden from / menu)

user-invocable: false # 仅允许Claude调用（在/菜单中隐藏）

context: fork # Run in isolated subagent context

context: fork # 在独立子Agent上下文中运行

agent: Explore # Subagent type (requires context: fork)

agent: Explore # 子Agent类型（需要context: fork）

model: [model-name] # Switch model when skill is active

model: [model-name] # 激活技能时切换模型

argument-hint: "[filename]" # Hint shown during autocomplete

argument-hint: "[filename]" # 自动补全时显示的提示

Title

标题

Essential Principles

核心原则

[3-5 non-negotiable rules with WHY explanations]
[3-5条带有原因说明的不可协商规则]

When to Use

适用场景

[4-6 specific scenarios — scopes behavior after activation]
[4-6个具体场景——激活后约束行为]

When NOT to Use

不适用场景

[3-5 scenarios with named alternatives — scopes behavior after activation]
[3-5个带有明确替代方案的场景——激活后约束行为]

[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]

Skills support three types of string substitutions: dollar-prefixed variables for arguments and session ID, and exclamation-backtick syntax for shell preprocessing. The skill loader processes these before Claude sees the file — even inside code fences — so never use the raw syntax in documentation text. See [tool-assignment-guide.md](references/tool-assignment-guide.md) for the full variable reference and usage guidance.
[输出验证的检查清单]

技能支持三种字符串替换：以美元符号为前缀的参数和会话ID变量，以及感叹号加反引号的Shell预处理语法。技能加载器会在Claude看到文件前处理这些语法——即使在代码块内也是如此，因此切勿在文档文本中使用原始语法。请查看[tool-assignment-guide.md](references/tool-assignment-guide.md)获取完整的变量参考和使用指南。

Anti-Pattern Quick Reference

反模式快速参考

The most common mistakes. Full catalog with before/after fixes in anti-patterns.md.
APAnti-PatternOne-Line Fix
AP-1Missing goals/anti-goalsAdd When to Use AND When NOT to Use sections
AP-2Monolithic SKILL.md (>500 lines)Split into references/ and workflows/
AP-3Reference chains (A -> B -> C)All files one hop from SKILL.md
AP-4Hardcoded pathsUse 
{baseDir}
for all internal paths
AP-5Broken file referencesVerify every path resolves before submitting
AP-6Unnumbered phasesNumber every phase with entry/exit criteria
AP-7Missing exit criteriaDefine what "done" means for every phase
AP-8No verification stepAdd validation at the end of every workflow
AP-9Vague routing keywordsUse distinctive keywords per workflow route
AP-11Wrong tool for the jobUse Glob/Grep/Read, not Bash equivalents
AP-12Overprivileged toolsRemove tools not actually used
AP-13Vague subagent promptsSpecify what to analyze, look for, and return
AP-15Reference dumpsTeach judgment, not raw documentation
AP-16Missing rationalizationsAdd "Rationalizations to Reject" for audit skills
AP-17No concrete examplesShow input -> output for key instructions
AP-18Cartesian product tool callsCombine patterns into single regex, grep once, then filter
AP-19Unbounded subagent spawningBatch items into groups, one subagent per batch
AP-20Description summarizes workflowDescription = triggering conditions only, never workflow steps
AP-10 (No Default/Fallback Route), AP-14 (Missing Tool Justification in Agents), and AP-20 (Description Summarizes Workflow) are in the full catalog. AP-20 is included in the quick reference above due to its high impact.
以下是最常见的错误。包含前后对比修复方案的完整目录请见anti-patterns.md。
反模式编号反模式内容一行修复方案
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-20Description总结工作流Description仅包含触发条件，切勿包含工作流步骤
AP-10（无默认/回退路由）、AP-14（Agent中缺少工具使用理由）和AP-20（Description总结工作流）请见完整目录。由于AP-20影响重大，已纳入上述快速参考。

Tool Assignment Quick Reference

工具分配快速参考

Map your component type to the right tool set. Full guide in tool-assignment-guide.md.
Component TypeTypical Tools
Read-only analysis skillRead, Glob, Grep, TodoRead, TodoWrite
Interactive analysis skillRead, Glob, Grep, AskUserQuestion, TodoRead, TodoWrite
Code generation skillRead, Glob, Grep, Write, Bash, TodoRead, TodoWrite
Pipeline skillRead, Write, Glob, Grep, Bash, AskUserQuestion, Task, TaskCreate, TaskList, TaskUpdate, TodoRead, TodoWrite
Read-only agentRead, Grep, Glob, TodoRead, TodoWrite
Action agentRead, Grep, Glob, Write, Bash, TodoRead, TodoWrite
Key rules:
  • Use Glob (not 
    find
    ), Grep (not 
    grep
    ), Read (not 
    cat
    ) — always prefer dedicated tools
  • Skills use 
    allowed-tools:
    — agents use 
    tools:
  • List only tools that instructions actually reference
  • Read-only components should never have Write or Bash
根据组件类型选择合适的工具集。完整指南请见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
只读AgentRead, Grep, Glob, TodoRead, TodoWrite
操作型AgentRead, Grep, Glob, Write, Bash, TodoRead, TodoWrite
核心规则：
  • 使用Glob（而非
    find
    ）、Grep（而非
    grep
    ）、Read（而非
    cat
    ）——始终优先使用专用工具
  • 技能使用
    allowed-tools:
    ——Agent使用
    tools:
  • 仅列出指令实际引用的工具
  • 只读组件绝不能包含Write或Bash

Rationalizations to Reject

需拒绝的合理化理由

When designing workflow skills, reject these shortcuts:
RationalizationWhy It's Wrong
"It's obvious which phase comes next"LLMs don't infer ordering from prose. Number the phases.
"Exit criteria are implied"Implied criteria are skipped criteria. Write them explicitly.
"One big SKILL.md is simpler"Simpler to write, worse to execute. The LLM loses focus past 500 lines.
"The description doesn't matter much"The description is how the skill gets triggered. A bad description means wrong activations or missed activations.
"Bash can do everything"Bash file operations are fragile. Dedicated tools handle encoding, permissions, and formatting better.
"The LLM will figure out the tools"It will guess wrong. Specify exactly which tool for each operation.
"I'll add details later"Incomplete skills ship incomplete. Design fully before writing.
设计工作流技能时，请拒绝以下捷径：
合理化理由错误原因
“下一个阶段是什么很明显”LLM无法从纯文本中推断顺序。请为阶段编号。
“退出标准是隐含的”隐含的标准等于被跳过的标准。请明确写出。
“一个大的SKILL.md更简单”编写起来简单，但执行效果差。LLM在超过500行后会失去焦点。
“Description不重要”Description是技能被触发的依据。糟糕的Description会导致错误激活或错过激活时机。
“Bash可以做所有事情”Bash文件操作很脆弱。专用工具在编码、权限和格式处理上表现更好。
“LLM会自己搞清楚工具的用法”它会猜错。请为每个操作明确指定工具。
“我之后再添加细节”不完整的技能交付后也是不完整的。请先完整设计再编写。

Reference Index

参考索引

FileContent
workflow-patterns.md5 patterns with structural skeletons and examples
anti-patterns.md20 anti-patterns with before/after fixes
tool-assignment-guide.mdTool selection matrix, component comparison, subagent guidance
progressive-disclosure-guide.mdContent splitting rules, the 500-line rule, sizing guidelines
WorkflowPurpose
design-a-workflow-skill.md6-phase creation process from scope to self-review
review-checklist.mdStructured self-review checklist for submission readiness
文件内容
workflow-patterns.md5种模式，包含结构骨架和示例
anti-patterns.md20种反模式，包含前后对比修复方案
tool-assignment-guide.md工具选择矩阵、组件对比、子Agent指南
progressive-disclosure-guide.md内容拆分规则、500行限制、大小调整指南
工作流用途
design-a-workflow-skill.md从范围定义到自我审查的6阶段创建流程
review-checklist.md用于提交准备的结构化自我审查清单

Success Criteria

成功标准

A well-designed workflow skill:
  • Has When to Use AND When NOT to Use sections
  • Uses a recognizable pattern (routing, pipeline, linear, safety gate, or task-driven)
  • Numbers all phases with entry and exit criteria
  • Lists only the tools it actually uses (least privilege)
  • Keeps SKILL.md under 500 lines with details in references/workflows
  • Has no hardcoded paths (uses 
    {baseDir}
    )
  • Has no broken file references
  • Has no reference chains (all links one hop from SKILL.md)
  • Includes a verification step at the end of the workflow
  • Has a description that triggers correctly (third-person, specific keywords)
  • Includes concrete examples for key instructions
  • Explains WHY, not just WHAT, for essential principles
设计良好的工作流技能应满足：
  • 包含“适用场景”和“不适用场景”部分
  • 使用可识别的模式（路由、流水线、线性、安全门或任务驱动）
  • 所有阶段都有编号，并明确进入和退出标准
  • 仅列出实际使用的工具（最小权限原则）
  • SKILL.md控制在500行以内，细节放在references/workflows中
  • 无硬编码路径（使用
    {baseDir}
    ）
  • 无无效文件引用
  • 无链式引用（所有链接均从SKILL.md一级跳转）
  • 工作流末尾包含验证步骤
  • Description可正确触发（第三人称，包含具体关键词）
  • 关键指令包含具体示例
  • 核心原则不仅说明“做什么”，还解释“为什么”