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.

Component	Context Cost	Purpose
Orchestrator command	~50-100 tokens/step	Dispatch and coordinate
Task file	~500+ tokens	Detailed step instructions
Sub-agent base	~294 tokens	System prompt overhead

每个子代理拥有独立的上下文窗口。主编排器保持轻量化，子代理则从文件中加载详细指令。

组件	上下文成本	用途
编排器命令	每步约50-100 tokens	调度与协调
任务文件	约500+ tokens	详细步骤指令
子代理基础	约294 tokens	系统提示开销

2. Sub-Agent Capabilities

2. 子代理能力

Sub-agents spawned via Task tool:

Capability	Available	Notes
Read tool	✅ Yes	Can read any file
Write tool	✅ Yes	If not restricted
Grep/Glob	✅ Yes	For code search
Skills loading	❌ No	Skills don't auto-load in sub-agents
Spawn sub-agents	❌ No	Cannot nest Task tool
Resume context	✅ Yes	Via `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):

Workflow name: kebab-case identifier (e.g.,
```
feature-implementation
```
)
Description: What the workflow accomplishes
Steps: List of discrete steps with:
- Step name
- Step goal
- Required tools
- Expected output
Execution mode: Sequential or parallel steps
Agent type:
```
general-purpose
```
or custom agent

若用户未提供，需询问以下信息：

工作流名称：短横线命名格式（如
```
feature-implementation
```
）
描述：工作流的目标
步骤：离散步骤列表，包含：
- 步骤名称
- 步骤目标
- 所需工具
- 预期输出
执行模式：顺序执行或并行执行
代理类型：
```
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

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

输入

<此步骤从之前步骤或用户处接收的内容>

Instructions

指令

<Specific action>
<Specific action>
<Specific action>

<具体操作>
<具体操作>
<具体操作>

Constraints

约束

<Limitation or boundary>
<What NOT to do>

<限制或边界>
<禁止操作>

Expected Output

预期输出

<需返回给编排器的内容>

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 ```

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:

<What was accomplished>
<Key outputs>
<Next steps if any>

undefined

总结工作流结果：

<完成的内容>
<关键输出>
<后续步骤（如有）>

undefined

Frontmatter Options

前置配置选项

Field	Purpose	Default
`description`	Brief description of workflow purpose	Required
`argument-hint`	Expected arguments description	None
`allowed-tools`	Tools the command can use	Inherits 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:

Agent 1: Security analysis → Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1a-security.md
Agent 2: Performance analysis → Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1b-performance.md
Agent 3: Code quality analysis → Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1c-quality.md

Wait for all, then consolidate results.

同时启动3个代理：

代理1：安全分析 → Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1a-security.md
代理2：性能分析 → Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1b-performance.md
代理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:

Files created/modified
Tests added
Remaining work

undefined

标记待办事项为已完成。报告内容：

创建/修改的文件
添加的测试
剩余工作

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

指令

Parse Feature Request
- Extract core requirements
- Identify acceptance criteria
- Note any constraints mentioned
Codebase Analysis
- Search for similar existing features
- Identify relevant patterns and conventions
- Find reusable components/utilities
Dependency Check
- What existing code will this feature interact with?
- Are there breaking change risks?
- What tests exist for related functionality?
Gap Analysis
- What's missing from the request?
- What clarifications might be needed?
- What edge cases should be considered?

解析功能请求
- 提取核心需求
- 识别验收标准
- 记录提到的约束
代码库分析
- 搜索类似的现有功能
- 识别相关模式和规范
- 找到可复用的组件/工具
依赖检查
- 此功能将与哪些现有代码交互？
- 是否存在破坏性变更风险？
- 相关功能有哪些测试？
差距分析
- 请求中缺少什么内容？
- 需要哪些澄清？
- 应考虑哪些边缘情况？

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

已知限制

Limitation	Impact	Workaround
No nested sub-agents	Sub-agents can't spawn Task tool	Keep all orchestration in main command
No skill auto-loading	Sub-agents don't trigger skills	Pass explicit file paths or inline context
Fresh context per agent	Each dispatch starts empty	Use resume pattern OR pass summaries
File read latency	Extra tool call per step	Acceptable 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:

Directories:
- ```
${CLAUDE_PLUGIN_ROOT}/tasks/
```
  - All task files directly here
- ```
${CLAUDE_PLUGIN_ROOT}/agents/
```
  - (Optional) Custom agent definitions

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/
```

Orchestrator command: Lean dispatch logic in
```
commands/<workflow-name>.md
```
Custom agents (Optional): If workflow needs specialized agent behavior in
```
agents/
```
Update plugin.json: Add command to plugin manifest if needed

After creation, suggest testing with

/customaize-agent:test-prompt

command.

基于用户输入，创建以下内容：

目录:
- ```
${CLAUDE_PLUGIN_ROOT}/tasks/
```
  - 所有任务文件直接存放于此
- ```
${CLAUDE_PLUGIN_ROOT}/agents/
```
  - （可选）自定义代理定义

任务文件：在

tasks/

目录下创建，命名模式为

step-N-<workflow>-<name>.md

示例：
```
step-1-feature-impl-research.md
```
示例：
```
step-2-feature-impl-architecture.md
```
共享上下文：
```
common-context.md
```
直接放在
```
tasks/
```
中

编排器命令：轻量化调度逻辑放在
```
commands/<workflow-name>.md
```
自定义代理（可选）：若工作流需要特定代理行为，放在
```
agents/
```
中
更新plugin.json：必要时在插件清单中添加命令

创建完成后，建议使用

/customaize-agent:test-prompt

命令进行测试。