Back to Details

create-workflow-command

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create Workflow Command

创建工作流命令

Create a command that orchestrates multi-step workflows by dispatching sub-agents with task-specific instructions stored in separate files.
创建一个命令，通过调用存储在独立文件中的特定任务指令的子代理，来编排多步骤工作流。

User Input

用户输入

text
Workflow Name: $1
Description: $2
text
Workflow Name: $1
Description: $2

Architecture Overview

架构概述

Workflow commands solve the context bloat problem: instead of embedding detailed step instructions in the main command (polluting orchestrator context), store them in separate task files that sub-agents read on-demand.
plugins/<plugin-name>/
├── commands/
│   └── <workflow>.md          # Lean orchestrator (~50-100 tokens per step)
├── agents/                     # Optional: reusable executor agents
│   └── step-executor.md       # Custom agent with specific tools/behavior
└── tasks/                      # All task instructions directly here
    ├── step-1-<name>.md       # Full instructions (~500+ tokens each)
    ├── step-2-<name>.md
    ├── step-3-<name>.md
    └── common-context.md      # Shared context across workflows
工作流命令解决了上下文膨胀问题：无需将详细步骤指令嵌入主命令（避免污染编排器上下文），而是将其存储在子代理可按需读取的独立任务文件中。
plugins/<plugin-name>/
├── commands/
│   └── <workflow>.md          # 轻量化编排器（每步约50-100 tokens）
├── agents/                     # 可选：可复用的执行器代理
│   └── step-executor.md       # 具备特定工具/行为的自定义代理
└── tasks/                      # 所有任务指令直接存放于此
    ├── step-1-<name>.md       # 完整指令（每个约500+ tokens）
    ├── step-2-<name>.md
    ├── step-3-<name>.md
    └── common-context.md      # 工作流间共享的上下文

Key Principles

核心原则

1. Context Isolation

1. 上下文隔离

Each sub-agent gets its own isolated context window. The main orchestrator stays lean while sub-agents load detailed instructions from files.
ComponentContext CostPurpose
Orchestrator command~50-100 tokens/stepDispatch and coordinate
Task file~500+ tokensDetailed step instructions
Sub-agent base~294 tokensSystem prompt overhead
每个子代理拥有独立的上下文窗口。主编排器保持轻量化，子代理则从文件中加载详细指令。
组件上下文成本用途
编排器命令每步约50-100 tokens调度与协调
任务文件约500+ tokens详细步骤指令
子代理基础约294 tokens系统提示开销

2. Sub-Agent Capabilities

2. 子代理能力

Sub-agents spawned via Task tool:
CapabilityAvailableNotes
Read tool✅ YesCan read any file
Write tool✅ YesIf not restricted
Grep/Glob✅ YesFor code search
Skills loading❌ NoSkills don't auto-load in sub-agents
Spawn sub-agents❌ NoCannot nest Task tool
Resume context✅ YesVia 
resume
parameter
通过Task工具生成的子代理具备以下能力：
能力是否可用说明
Read工具✅ 是可读取任意文件
Write工具✅ 是无限制时可用
Grep/Glob✅ 是用于代码搜索
Skills加载❌ 否子代理不会自动加载Skills
生成子代理❌ 否无法嵌套使用Task工具
恢复上下文✅ 是通过
resume
参数实现

3. File Reference Pattern

3. 文件引用模式

Use 
${CLAUDE_PLUGIN_ROOT}
for portable paths within plugin:
markdown
Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1-workflow-name.md and execute.
Sub-agent will use Read tool to fetch the file content.
使用
${CLAUDE_PLUGIN_ROOT}
实现插件内的可移植路径：
markdown
Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1-workflow-name.md and execute.
子代理将使用Read工具获取文件内容。

Implementation Process

实现流程

Step 1: Gather Requirements

步骤1：收集需求

Ask user (if not provided):
  1. Workflow name: kebab-case identifier (e.g., 
    feature-implementation
    )
  2. Description: What the workflow accomplishes
  3. Steps: List of discrete steps with:
    • Step name
    • Step goal
    • Required tools
    • Expected output
  4. Execution mode: Sequential or parallel steps
  5. Agent type: 
    general-purpose
    or custom agent
若用户未提供，需询问以下信息：
  1. 工作流名称：短横线命名格式（如
    feature-implementation
    ）
  2. 描述：工作流的目标
  3. 步骤：离散步骤列表，包含：
    • 步骤名称
    • 步骤目标
    • 所需工具
    • 预期输出
  4. 执行模式：顺序执行或并行执行
  5. 代理类型：
    general-purpose
    （通用型）或自定义代理

Step 2: Create Directory Structure

步骤2：创建目录结构

bash
undefined
bash
undefined

Create tasks directory (if it doesn't exist)

创建tasks目录（若不存在）

mkdir -p ${CLAUDE_PLUGIN_ROOT}/tasks
mkdir -p ${CLAUDE_PLUGIN_ROOT}/tasks

Optional: Create agents directory (if using custom agents)

可选：创建agents目录（若使用自定义代理）

mkdir -p ${CLAUDE_PLUGIN_ROOT}/agents

**Note**: All task files (both workflow-specific steps and shared context) are placed directly in `tasks/` without subdirectories.
mkdir -p ${CLAUDE_PLUGIN_ROOT}/agents

**注意**：所有任务文件（包括工作流专属步骤和共享上下文）直接放在`tasks/`目录下，无需子目录。

Step 3: Create Task Files

步骤3：创建任务文件

For each step, create a task file with this structure:
markdown
undefined
为每个步骤创建任务文件，结构如下：
markdown
undefined

Step N: <Step Name>

步骤N：<步骤名称>

Context

上下文

You are executing step N of the <workflow-name> workflow.
你正在执行<workflow-name>工作流的第N步。

Goal

目标

<Clear, specific goal for this step>
<清晰、具体的步骤目标>

Input

输入

<What this step receives from previous steps or user>
<此步骤从之前步骤或用户处接收的内容>

Instructions

指令

  1. <Specific action>
  2. <Specific action>
  3. <Specific action>
  1. <具体操作>
  2. <具体操作>
  3. <具体操作>

Constraints

约束

  • <Limitation or boundary>
  • <What NOT to do>
  • <限制或边界>
  • <禁止操作>

Expected Output

预期输出

<What to return to orchestrator>
<需返回给编排器的内容>

Success Criteria

成功标准

  • <Measurable outcome>
  • <Measurable outcome>
undefined
  • <可衡量的结果>
  • <可衡量的结果>
undefined

Step 4: Create Orchestrator Command

步骤4：创建编排器命令

Create the main command file with this pattern:
markdown
---
description: <Workflow description>
argument-hint: <Required arguments>
allowed-tools: Task, Read
model: sonnet
---
创建主命令文件，遵循以下模板：
markdown
---
description: <工作流描述>
argument-hint: <必填参数>
allowed-tools: Task, Read
model: sonnet
---

<Workflow Name>

<工作流名称>

User Input

用户输入

```text $ARGUMENTS ```
```text $ARGUMENTS ```

Workflow Execution

工作流执行

Step 1: <Step Name>

步骤1：<步骤名称>

Launch general-purpose agent:
  • Description: "<3-5 word summary>"
  • Prompt: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1-<workflow>-<name>.md and execute.
    Context:
    • TARGET: $1
    • MODE: $2 ```
Capture: <What to extract from result>
启动通用型代理：
  • 描述："3-5字摘要"
  • Prompt: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1-<workflow>-<name>.md and execute.
    Context:
    • TARGET: $1
    • MODE: $2 ```
捕获：<需从结果中提取的内容>

Step 2: <Step Name>

步骤2：<步骤名称>

Launch general-purpose agent:
  • Description: "<3-5 word summary>"
  • Prompt: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-2-<workflow>-<name>.md and execute.
    Context from Step 1:
    • <Key data from previous step>
    ```
启动通用型代理：
  • 描述："3-5字摘要"
  • Prompt: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-2-<workflow>-<name>.md and execute.
    Context from Step 1:
    • <来自上一步的关键数据> ```

Step 3: <Step Name>

步骤3：<步骤名称>

[Continue pattern...]
[继续此模式...]

Completion

完成

Summarize workflow results:
  1. <What was accomplished>
  2. <Key outputs>
  3. <Next steps if any> 
undefined
总结工作流结果：
  1. <完成的内容>
  2. <关键输出>
  3. <后续步骤（如有）>
undefined

Frontmatter Options

前置配置选项

FieldPurposeDefault
description
Brief description of workflow purposeRequired
argument-hint
Expected arguments descriptionNone
allowed-tools
Tools the command can useInherits from conversation
model
Specific Claude model (sonnet, opus, haiku)Inherits from conversation
Model selection:
  • haiku
    - Fast, efficient for simple workflows
  • sonnet
    - Balanced performance (recommended default)
  • opus
    - Maximum capability for complex orchestration
字段用途默认值
description
工作流用途的简要描述必填
argument-hint
预期参数描述无
allowed-tools
命令可使用的工具继承自对话设置
model
指定Claude模型（sonnet, opus, haiku）继承自对话设置
模型选择:
  • haiku
    - 快速高效，适用于简单工作流
  • sonnet
    - 性能均衡（推荐默认）
  • opus
    - 能力最强，适用于复杂编排

Execution Patterns

执行模式

Pattern A: Sequential Steps (Default)

模式A：顺序步骤（默认）

Each step depends on previous step's output:
markdown
undefined
每个步骤依赖上一步的输出：
markdown
undefined

Step 1: Analyze

步骤1：分析

Launch agent → Get analysis result
启动代理 → 获取分析结果

Step 2: Plan (uses Step 1 result)

步骤2：规划（使用步骤1结果）

Launch agent with Step 1 context → Get plan
携带步骤1上下文启动代理 → 获取规划方案

Step 3: Execute (uses Step 2 result)

步骤3：执行（使用步骤2结果）

Launch agent with Step 2 context → Complete
undefined
携带步骤2上下文启动代理 → 完成任务
undefined

Pattern B: Parallel Independent Steps

模式B：并行独立步骤

Steps can run concurrently:
markdown
undefined
步骤可同时运行：
markdown
undefined

Analysis Phase (Parallel)

分析阶段（并行）

Launch 3 agents simultaneously:
  1. Agent 1: Security analysis → Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1a-security.md
  2. Agent 2: Performance analysis → Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1b-performance.md
  3. Agent 3: Code quality analysis → Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1c-quality.md
Wait for all, then consolidate results.
同时启动3个代理：
  1. 代理1：安全分析 → Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1a-security.md
  2. 代理2：性能分析 → Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1b-performance.md
  3. 代理3：代码质量分析 → Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1c-quality.md
等待所有完成，然后整合结果。

Synthesis Phase

合成阶段

Launch agent with all analysis results...
undefined
携带所有分析结果启动代理...
undefined

Pattern C: Stateful Multi-Step (Resume)

模式C：有状态多步骤（恢复）

When steps need shared context:
markdown
undefined
当步骤需要共享上下文时：
markdown
undefined

Step 1: Initialize

步骤1：初始化

Launch agent, capture agent_id
启动代理，捕获agent_id

Step 2: Continue (same context)

步骤2：继续（相同上下文）

Resume agent using agent_id:
  • resume: <agent_id from Step 1>
  • prompt: "Proceed to phase 2: <additional instructions>"
undefined
使用agent_id恢复代理：
  • resume: <来自步骤1的agent_id>
  • prompt: "进入第二阶段：<附加指令>"
undefined

Example: Feature Implementation Workflow

示例：功能实现工作流

Orchestrator Command

编排器命令

markdown
---
description: Execute feature implementation through research, planning, and coding phases
argument-hint: [feature-description]
allowed-tools: Task, Read, TodoWrite
model: sonnet
---
markdown
---
description: 通过调研、规划和编码阶段执行功能实现
argument-hint: [feature-description]
allowed-tools: Task, Read, TodoWrite
model: sonnet
---

Implement Feature

实现功能

User Input

用户输入

```text $ARGUMENTS ```
Create TodoWrite with workflow steps.
```text $ARGUMENTS ```
使用TodoWrite创建工作流步骤。

Phase 1: Research

阶段1：调研

Launch general-purpose agent:
  • Description: "Research feature requirements"
  • Prompt: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1-feature-impl-research.md
    Feature: $ARGUMENTS ```
Extract: Key findings, constraints, existing patterns
启动通用型代理：
  • 描述："调研功能需求"
  • Prompt: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1-feature-impl-research.md
    Feature: $ARGUMENTS ```
提取：关键发现、约束、现有模式

Phase 2: Architecture

阶段2：架构设计

Launch general-purpose agent:
  • Description: "Design feature architecture"
  • Prompt: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-2-feature-impl-architecture.md
    Feature: $ARGUMENTS Research findings: <summary from Phase 1> ```
Extract: File structure, components, interfaces
启动通用型代理：
  • 描述："设计功能架构"
  • Prompt: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-2-feature-impl-architecture.md
    Feature: $ARGUMENTS Research findings: <来自阶段1的摘要> ```
提取：文件结构、组件、接口

Phase 3: Implementation

阶段3：实现

Launch developer agent:
  • Description: "Implement feature code"
  • Prompt: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-3-feature-impl-implement.md
    Architecture: <summary from Phase 2> ```
启动开发者代理：
  • 描述："实现功能代码"
  • Prompt: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-3-feature-impl-implement.md
    Architecture: <来自阶段2的摘要> ```

Completion

完成

Mark todos complete. Report:
  1. Files created/modified
  2. Tests added
  3. Remaining work
undefined
标记待办事项为已完成。报告内容：
  1. 创建/修改的文件
  2. 添加的测试
  3. 剩余工作
undefined

Task File Example (step-1-feature-impl-research.md)

任务文件示例（step-1-feature-impl-research.md）

markdown
undefined
markdown
undefined

Step 1: Feature Research

步骤1：功能调研

Context

上下文

You are the research phase of a feature implementation workflow.
你处于功能实现工作流的调研阶段。

Goal

目标

Thoroughly understand the feature requirements and existing codebase context before any implementation begins.
在开始任何实现工作前，全面理解功能需求和现有代码库上下文。

Instructions

指令

  1. Parse Feature Request
    • Extract core requirements
    • Identify acceptance criteria
    • Note any constraints mentioned
  2. Codebase Analysis
    • Search for similar existing features
    • Identify relevant patterns and conventions
    • Find reusable components/utilities
  3. Dependency Check
    • What existing code will this feature interact with?
    • Are there breaking change risks?
    • What tests exist for related functionality?
  4. Gap Analysis
    • What's missing from the request?
    • What clarifications might be needed?
    • What edge cases should be considered?
  1. 解析功能请求
    • 提取核心需求
    • 识别验收标准
    • 记录提到的约束
  2. 代码库分析
    • 搜索类似的现有功能
    • 识别相关模式和规范
    • 找到可复用的组件/工具
  3. 依赖检查
    • 此功能将与哪些现有代码交互？
    • 是否存在破坏性变更风险？
    • 相关功能有哪些测试？
  4. 差距分析
    • 请求中缺少什么内容？
    • 需要哪些澄清？
    • 应考虑哪些边缘情况？

Constraints

约束

  • Do NOT write any implementation code
  • Do NOT modify any files
  • Focus purely on research and analysis
  • 不得编写任何实现代码
  • 不得修改任何文件
  • 仅专注于调研和分析

Expected Output

预期输出

Return a structured research summary:
```markdown
返回结构化的调研摘要：
```markdown

Feature Understanding

功能理解

  • Core requirement: <summary>
  • Acceptance criteria: <list>
  • 核心需求：<摘要>
  • 验收标准：<列表>

Codebase Context

代码库上下文

  • Similar features: <list with file paths>
  • Patterns to follow: <list>
  • Reusable code: <list with file paths>
  • 类似功能：<带文件路径的列表>
  • 需遵循的模式：<列表>
  • 可复用代码：<带文件路径的列表>

Dependencies

依赖项

  • Files affected: <list>
  • Tests to consider: <list>
  • 受影响文件：<列表>
  • 需考虑的测试：<列表>

Open Questions

待澄清问题

  • <Question 1>
  • <Question 2>
  • <问题1>
  • <问题2>

Recommendation

建议

<Brief recommendation for architecture phase> \`\`\`
<给架构设计阶段的简要建议> ```

Success Criteria

成功标准

  • Feature requirements clearly articulated
  • Relevant existing code identified
  • No implementation attempted
  • Clear handoff to architecture phase
undefined
  • 功能需求清晰明确
  • 已识别相关现有代码
  • 未尝试任何实现
  • 为架构设计阶段做好清晰的交接
undefined

Known Limitations

已知限制

LimitationImpactWorkaround
No nested sub-agentsSub-agents can't spawn Task toolKeep all orchestration in main command
No skill auto-loadingSub-agents don't trigger skillsPass explicit file paths or inline context
Fresh context per agentEach dispatch starts emptyUse resume pattern OR pass summaries
File read latencyExtra tool call per stepAcceptable trade-off for context savings
限制影响解决方法
不支持嵌套子代理子代理无法生成Task工具所有编排逻辑放在主命令中
不自动加载Skills子代理不会触发Skills传递明确的文件路径或内联上下文
每个代理上下文全新每次调度都从空开始使用恢复模式或传递摘要
文件读取延迟每步额外调用一次工具为节省上下文，此开销可接受

Validation Checklist

验证 checklist

Before finalizing workflow command:
  • Each step has clear, specific goal
  • Task files are self-contained (sub-agent doesn't need external context)
  • File paths use 
    ${CLAUDE_PLUGIN_ROOT}
    for portability
  • Context passed between steps is minimal (summaries, not full data)
  • Orchestrator command stays lean (<100 tokens per step dispatch)
  • Error handling defined for step failures
  • Success criteria measurable for each step
在最终确定工作流命令前：
  • 每个步骤有清晰、具体的目标
  • 任务文件独立完整（子代理无需外部上下文）
  • 文件路径使用
    ${CLAUDE_PLUGIN_ROOT}
    保证可移植性
  • 步骤间传递的上下文最少（仅摘要，非完整数据）
  • 编排器命令保持轻量化（每步调度<100 tokens）
  • 定义了步骤失败的错误处理逻辑
  • 每个步骤的成功标准可衡量

Create the Workflow

创建工作流

Based on user input, create:
  1. Directories:
    • ${CLAUDE_PLUGIN_ROOT}/tasks/
      - All task files directly here
    • ${CLAUDE_PLUGIN_ROOT}/agents/
      - (Optional) Custom agent definitions
  2. Task files: Create in 
    tasks/
    directory with naming pattern 
    step-N-<workflow>-<name>.md
    • Example: 
      step-1-feature-impl-research.md
    • Example: 
      step-2-feature-impl-architecture.md
    • Shared context: 
      common-context.md
      directly in 
      tasks/
  3. Orchestrator command: Lean dispatch logic in 
    commands/<workflow-name>.md
  4. Custom agents (Optional): If workflow needs specialized agent behavior in 
    agents/
  5. Update plugin.json: Add command to plugin manifest if needed
After creation, suggest testing with 
/customaize-agent:test-prompt
command.
基于用户输入，创建以下内容：
  1. 目录:
    • ${CLAUDE_PLUGIN_ROOT}/tasks/
      - 所有任务文件直接存放于此
    • ${CLAUDE_PLUGIN_ROOT}/agents/
      - （可选）自定义代理定义
  2. 任务文件：在
    tasks/
    目录下创建，命名模式为
    step-N-<workflow>-<name>.md
    • 示例：
      step-1-feature-impl-research.md
    • 示例：
      step-2-feature-impl-architecture.md
    • 共享上下文：
      common-context.md
      直接放在
      tasks/
      中
  3. 编排器命令：轻量化调度逻辑放在
    commands/<workflow-name>.md
  4. 自定义代理（可选）：若工作流需要特定代理行为，放在
    agents/
    中
  5. 更新plugin.json：必要时在插件清单中添加命令
创建完成后，建议使用
/customaize-agent:test-prompt
命令进行测试。