skill-workflow-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<objective> Subagents are specialized Claude instances that run in isolated contexts with focused roles and limited tool access. This skill teaches you how to create effective subagents, write strong system prompts, configure tool access, and orchestrate multi-agent workflows using the Task tool.

Subagents enable delegation of complex tasks to specialized agents that operate autonomously without user interaction, returning their final output to the main conversation. </objective>

<quick_start> <workflow>

Run
```
/agents
```
command
Select "Create New Agent"
Choose project-level (
```
.claude/agents/
```
) or user-level (
```
~/.claude/agents/
```
)
Define the subagent:
- name: lowercase-with-hyphens
- description: When should this subagent be used?
- tools: Optional comma-separated list (inherits all if omitted)
- model: Optional (
```
sonnet
```
  ,
```
opus
```
  ,
```
haiku
```
  , or
```
inherit
```
  )
Write the system prompt (the subagent's instructions) </workflow>

<example> ```markdown --- name: code-reviewer description: Expert code reviewer. Use proactively after code changes to review for quality, security, and best practices. tools: Read, Grep, Glob, Bash model: sonnet --- <role> You are a senior code reviewer focused on quality, security, and best practices. </role>

<focus_areas>

Code quality and maintainability
Security vulnerabilities
Performance issues
Best practices adherence </focus_areas>

<output_format> Provide specific, actionable feedback with file:line references. </output_format>

</example>
</quick_start>

<file_structure>
| Type | Location | Scope | Priority |
|------|----------|-------|----------|
| **Project** | `.claude/agents/` | Current project only | Highest |
| **User** | `~/.claude/agents/` | All projects | Lower |
| **Plugin** | Plugin's `agents/` dir | All projects | Lowest |

Project-level subagents override user-level when names conflict.
</file_structure>

<configuration>
<field name="name">
- Lowercase letters and hyphens only
- Must be unique
</field>

<field name="description">
- Natural language description of purpose
- Include when Claude should invoke this subagent
- Used for automatic subagent selection
</field>

<field name="tools">
- Comma-separated list: `Read, Write, Edit, Bash, Grep`
- If omitted: inherits all tools from main thread
- Use `/agents` interface to see all available tools
</field>

<field name="model">
- `sonnet`, `opus`, `haiku`, or `inherit`
- `inherit`: uses same model as main conversation
- If omitted: defaults to configured subagent model (usually sonnet)
</field>
</configuration>

<execution_model>
<critical_constraint>
**Subagents are black boxes that cannot interact with users.**

Subagents run in isolated contexts and return their final output to the main conversation. They:
- ✅ Can use tools like Read, Write, Edit, Bash, Grep, Glob
- ✅ Can access MCP servers and other non-interactive tools
- ❌ **Cannot use AskUserQuestion** or any tool requiring user interaction
- ❌ **Cannot present options or wait for user input**
- ❌ **User never sees subagent's intermediate steps**

The main conversation sees only the subagent's final report/output.
</critical_constraint>

<workflow_design>
**Designing workflows with subagents:**

Use **main chat** for:
- Gathering requirements from user (AskUserQuestion)
- Presenting options or decisions to user
- Any task requiring user confirmation/input
- Work where user needs visibility into progress

Use **subagents** for:
- Research tasks (API documentation lookup, code analysis)
- Code generation based on pre-defined requirements
- Analysis and reporting (security review, test coverage)
- Context-heavy operations that don't need user interaction

**Example workflow pattern:**

Main Chat: Ask user for requirements (AskUserQuestion) ↓ Subagent: Research API and create documentation (no user interaction) ↓ Main Chat: Review research with user, confirm approach ↓ Subagent: Generate code based on confirmed plan ↓ Main Chat: Present results, handle testing/deployment

</workflow_design>
</execution_model>

<system_prompt_guidelines>
<principle name="be_specific">
Clearly define the subagent's role, capabilities, and constraints.
</principle>

<principle name="use_pure_xml_structure">
Structure the system prompt with pure XML tags. Remove ALL markdown headings from the body.

```markdown
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: sonnet
---

<role>
You are a senior code reviewer specializing in security.
</role>

<focus_areas>
- SQL injection vulnerabilities
- XSS attack vectors
- Authentication/authorization issues
- Sensitive data exposure
</focus_areas>

<workflow>
1. Read the modified files
2. Identify security risks
3. Provide specific remediation steps
4. Rate severity (Critical/High/Medium/Low)
</workflow>

</principle> <principle name="task_specific"> Tailor instructions to the specific task domain. Don't create generic "helper" subagents.

❌ Bad: "You are a helpful assistant that helps with code" ✅ Good: "You are a React component refactoring specialist. Analyze components for hooks best practices, performance anti-patterns, and accessibility issues." </principle> </system_prompt_guidelines>

<subagent_xml_structure> Subagent.md files are system prompts consumed only by Claude. Like skills and slash commands, they should use pure XML structure for optimal parsing and token efficiency.

<recommended_tags> Common tags for subagent structure:

```
<role>
```
- Who the subagent is and what it does
```
<constraints>
```
- Hard rules (NEVER/MUST/ALWAYS)
```
<focus_areas>
```
- What to prioritize
```
<workflow>
```
- Step-by-step process
```
<output_format>
```
- How to structure deliverables
```
<success_criteria>
```
- Completion criteria
```
<validation>
```
- How to verify work </recommended_tags>

<intelligence_rules> Simple subagents (single focused task):

Use role + constraints + workflow minimum
Example: code-reviewer, test-runner

Medium subagents (multi-step process):

Add workflow steps, output_format, success_criteria
Example: api-researcher, documentation-generator

Complex subagents (research + generation + validation):

Add all tags as appropriate including validation, examples
Example: mcp-api-researcher, comprehensive-auditor </intelligence_rules>

<critical_rule> Remove ALL markdown headings (##, ###) from subagent body. Use semantic XML tags instead.

Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).

For XML structure principles and token efficiency details, see @skills/create-agent-skills/references/use-xml-tags.md - the same principles apply to subagents. </critical_rule> </subagent_xml_structure>

<invocation> <automatic> Claude automatically selects subagents based on the `description` field when it matches the current task. </automatic> <explicit> You can explicitly invoke a subagent:

> Use the code-reviewer subagent to check my recent changes

> Have the test-writer subagent create tests for the new API endpoints

</explicit> </invocation>

<background_execution> Subagents can run in the background using the

run_in_background

parameter, allowing parallel execution while the main conversation continues.

<how_it_works> Starting a background subagent: The Task tool accepts

run_in_background: true

to launch agents asynchronously:

Task tool call:
- description: "Analyze security vulnerabilities"
- prompt: "Review all authentication code for security issues..."
- subagent_type: "security-reviewer"
- run_in_background: true

The agent starts immediately and returns an

agent_id

for tracking. </how_it_works>

<retrieving_results> Getting results with TaskOutput: Use the

TaskOutput

tool to retrieve results from background agents:

TaskOutput tool call:
- task_id: "agent-12345"  # The agent_id from the Task call
- block: true            # Wait for completion (default)
- timeout: 30000         # Max wait time in ms

Parameters:

Parameter	Default	Description
`task_id`	Required	The agent ID returned from Task tool
`block`	`true`	Wait for completion or check current status
`timeout`	`30000`	Max wait time in milliseconds (up to 600000)

Non-blocking check: Set

block: false

to check status without waiting:

TaskOutput tool call:
- task_id: "agent-12345"
- block: false

Returns current status: running, completed, or the final result. </retrieving_results>

<parallel_agents> Launching multiple agents in parallel:

To maximize performance, launch multiple independent agents simultaneously:

Single message with multiple Task tool calls:

Task 1:
- description: "Review code quality"
- prompt: "Check code quality..."
- subagent_type: "code-reviewer"
- run_in_background: true

Task 2:
- description: "Run security scan"
- prompt: "Scan for vulnerabilities..."
- subagent_type: "security-scanner"
- run_in_background: true

Task 3:
- description: "Check test coverage"
- prompt: "Analyze test coverage..."
- subagent_type: "test-analyzer"
- run_in_background: true

Then retrieve all results:

TaskOutput calls for each agent_id

</parallel_agents>

<when_to_use_background> Use background agents for:

Long-running analysis (security review, comprehensive code analysis)
Multiple independent tasks that can run in parallel
Tasks where you want to continue working while waiting
Research tasks that may take significant time

Don't use background for:

Quick operations (< 10 seconds)
Tasks that depend on each other sequentially
Tasks where immediate results are needed for next step
Simple single-file operations

Pattern: Parallel Analysis Pipeline

1. Launch multiple analysis agents in background
2. Continue with other work or wait
3. Collect all results
4. Synthesize findings in main conversation

</when_to_use_background>

<resuming_agents> Resuming agents: Agents can be resumed using the

resume

parameter with their agent ID:

Task tool call:
- description: "Continue security review"
- prompt: "Please continue with the remaining files..."
- subagent_type: "security-reviewer"
- resume: "agent-12345"  # Previous agent ID

The agent continues with its full previous context preserved. </resuming_agents> </background_execution>

<management> <using_agents_command> Run `/agents` for an interactive interface to: - View all available subagents - Create new subagents - Edit existing subagents - Delete custom subagents </using_agents_command>

<manual_editing> You can also edit subagent files directly:

Project:
```
.claude/agents/subagent-name.md
```
User:
```
~/.claude/agents/subagent-name.md
```
</manual_editing> </management>

<reference> **Core references**:

Subagent usage and configuration: references/subagents.md

File format and configuration
Model selection (Sonnet 4.5 + Haiku 4.5 orchestration)
Tool security and least privilege
Prompt caching optimization
Background execution (run_in_background, TaskOutput, parallel agents)
Complete examples

Writing effective prompts: references/writing-subagent-prompts.md

Core principles and XML structure
Description field optimization for routing
Extended thinking for complex reasoning
Security constraints and strong modal verbs
Success criteria definition

Advanced topics:

Evaluation and testing: references/evaluation-and-testing.md

Evaluation metrics (task completion, tool correctness, robustness)
Testing strategies (offline, simulation, online monitoring)
Evaluation-driven development
G-Eval for custom criteria

Error handling and recovery: references/error-handling-and-recovery.md

Common failure modes and causes
Recovery strategies (graceful degradation, retry, circuit breakers)
Structured communication and observability
Anti-patterns to avoid

Context management: references/context-management.md

Memory architecture (STM, LTM, working memory)
Context strategies (summarization, sliding window, scratchpads)
Managing long-running tasks
Prompt caching interaction

Orchestration patterns: references/orchestration-patterns.md

Sequential, parallel, hierarchical, coordinator patterns
Sonnet + Haiku orchestration for cost/performance
Multi-agent coordination
Pattern selection guidance

Debugging and troubleshooting: references/debugging-agents.md

Logging, tracing, and correlation IDs
Common failure types (hallucinations, format errors, tool misuse)
Diagnostic procedures
Continuous monitoring </reference>

<success_criteria> A well-configured subagent has:

Valid YAML frontmatter (name matches file, description includes triggers)
Clear role definition in system prompt
Appropriate tool restrictions (least privilege)
XML-structured system prompt with role, approach, and constraints
Description field optimized for automatic routing
Successfully tested on representative tasks
Model selection appropriate for task complexity (Sonnet for reasoning, Haiku for simple tasks) </success_criteria>

<objective> 子代理（Subagents）是运行在独立环境中的专用Claude实例，具备明确的角色和受限的工具访问权限。本技能将教你如何创建高效的子代理、编写优质的系统提示词、配置工具访问权限，以及使用Task工具编排多代理工作流。

子代理支持将复杂任务委托给专业代理自主处理，无需用户交互，最终将结果返回至主对话中。 </objective>

<quick_start> <workflow>

运行
```
/agents
```
命令
选择“创建新代理（Create New Agent）”
选择项目级（
```
.claude/agents/
```
）或用户级（
```
~/.claude/agents/
```
）
定义子代理：
- name：小写字母加连字符格式
- description：说明该子代理的适用场景
- tools：可选，逗号分隔的工具列表（若省略则继承所有工具）
- model：可选（
```
sonnet
```
  、
```
opus
```
  、
```
haiku
```
  或
```
inherit
```
  ）
编写系统提示词（子代理的指令） </workflow>

<focus_areas>

Code quality and maintainability
Security vulnerabilities
Performance issues
Best practices adherence </focus_areas>

<output_format> Provide specific, actionable feedback with file:line references. </output_format>

</example>
</quick_start>

<file_structure>
| 类型 | 位置 | 作用范围 | 优先级 |
|------|----------|-------|----------|
| **项目级** | `.claude/agents/` | 仅当前项目 | 最高 |
| **用户级** | `~/.claude/agents/` | 所有项目 | 较低 |
| **插件级** | 插件的`agents/`目录 | 所有项目 | 最低 |

当名称冲突时，项目级子代理会覆盖用户级子代理。
</file_structure>

<configuration>
<field name="name">
- 仅允许小写字母和连字符
- 必须唯一
</field>

<field name="description">
- 用自然语言描述用途
- 需包含Claude应调用该子代理的场景
- 用于自动选择子代理
</field>

<field name="tools">
- 逗号分隔的列表：`Read, Write, Edit, Bash, Grep`
- 若省略：继承主线程的所有工具
- 使用`/agents`界面查看所有可用工具
</field>

<field name="model">
- 可选值：`sonnet`、`opus`、`haiku`或`inherit`
- `inherit`：使用与主对话相同的模型
- 若省略：默认使用配置的子代理模型（通常为sonnet）
</field>
</configuration>

<execution_model>
<critical_constraint>
**子代理是无法与用户交互的黑盒。**

子代理运行在独立环境中，仅将最终结果返回至主对话。它们：
- ✅ 可使用Read、Write、Edit、Bash、Grep、Glob等工具
- ✅ 可访问MCP服务器及其他非交互式工具
- ❌ **无法使用AskUserQuestion或任何需要用户交互的工具**
- ❌ **无法展示选项或等待用户输入**
- ❌ **用户永远无法看到子代理的中间步骤**

主对话仅能看到子代理的最终报告/输出。
</critical_constraint>

<workflow_design>
**设计子代理工作流：**

**主对话**适用于：
- 收集用户需求（使用AskUserQuestion）
- 向用户展示选项或决策
- 任何需要用户确认/输入的任务
- 用户需要了解进度的工作

**子代理**适用于：
- 研究类任务（API文档查阅、代码分析）
- 基于预定义需求的代码生成
- 分析与报告（安全审查、测试覆盖率分析）
- 无需用户交互的重上下文操作

**示例工作流模式：**

主对话：向用户收集需求（AskUserQuestion） ↓ 子代理：研究API并创建文档（无需用户交互） ↓ 主对话：与用户复核研究结果，确认方案 ↓ 子代理：基于确认的方案生成代码 ↓ 主对话：展示结果，处理测试/部署

</workflow_design>
</execution_model>

<system_prompt_guidelines>
<principle name="be_specific">
明确定义子代理的角色、能力和约束条件。
</principle>

<principle name="use_pure_xml_structure">
使用纯XML标签构建系统提示词。移除正文中所有的Markdown标题。

```markdown
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: sonnet
---

<role>
You are a senior code reviewer specializing in security.
</role>

<focus_areas>
- SQL injection vulnerabilities
- XSS attack vectors
- Authentication/authorization issues
- Sensitive data exposure
</focus_areas>

<workflow>
1. Read the modified files
2. Identify security risks
3. Provide specific remediation steps
4. Rate severity (Critical/High/Medium/Low)
</workflow>

</principle> <principle name="task_specific"> 根据特定任务领域调整指令。不要创建通用的“助手”子代理。

❌ 错误示例："你是一个帮助处理代码的助手" ✅ 正确示例："你是React组件重构专家。分析组件的钩子最佳实践、性能反模式及可访问性问题。" </principle> </system_prompt_guidelines>

<subagent_xml_structure> Subagent.md文件是仅由Claude读取的系统提示词。与技能和斜杠命令类似，为了优化解析效率和Token使用，应采用纯XML结构。

<recommended_tags> 子代理结构的常用标签：

```
<role>
```
- 子代理的身份和职责
```
<constraints>
```
- 硬性规则（禁止/必须/始终）
```
<focus_areas>
```
- 优先处理事项
```
<workflow>
```
- 分步流程
```
<output_format>
```
- 交付成果的结构要求
```
<success_criteria>
```
- 完成标准
```
<validation>
```
- 工作成果的验证方式 </recommended_tags>

<intelligence_rules> 简单子代理（单一聚焦任务）：

至少包含role + constraints + workflow
示例：code-reviewer、test-runner

中等复杂度子代理（多步骤流程）：

增加workflow步骤、output_format、success_criteria
示例：api-researcher、documentation-generator

复杂子代理（研究+生成+验证）：

根据需要添加所有标签，包括validation和示例
示例：mcp-api-researcher、comprehensive-auditor </intelligence_rules>

<critical_rule> 移除子代理正文中所有的Markdown标题（##、###），改用语义化XML标签替代。

内容内部可保留Markdown格式（粗体、斜体、列表、代码块、链接）。

关于XML结构原则和Token效率的详细信息，请参考@skills/create-agent-skills/references/use-xml-tags.md - 相同原则适用于子代理。 </critical_rule> </subagent_xml_structure>

<invocation> <automatic> 当任务与`description`字段匹配时，Claude会自动选择对应的子代理。 </automatic> <explicit> 你也可以显式调用子代理：

> 使用code-reviewer子代理检查我最近的代码变更

> 让test-writer子代理为新API端点创建测试用例

</explicit> </invocation>

<background_execution> 子代理可通过

run_in_background

参数在后台运行，支持并行执行，同时主对话可继续进行。

<how_it_works> 启动后台子代理： Task工具支持

run_in_background: true

参数，用于异步启动代理：

Task工具调用：
- description: "分析安全漏洞"
- prompt: "审查所有认证代码中的安全问题..."
- subagent_type: "security-reviewer"
- run_in_background: true

代理会立即启动，并返回一个

agent_id

用于跟踪。 </how_it_works>

<retrieving_results> 使用TaskOutput获取结果： 使用

TaskOutput

工具从后台代理中获取结果：

TaskOutput工具调用：
- task_id: "agent-12345"  # Task调用返回的agent_id
- block: true            # 等待完成（默认值）
- timeout: 30000         # 最大等待时间（毫秒）

参数说明：

参数	默认值	描述
`task_id`	必填	Task工具返回的代理ID
`block`	`true`	是否等待任务完成或仅检查当前状态
`timeout`	`30000`	最大等待时间（毫秒，最高600000）

非阻塞检查： 设置

block: false

可检查状态而无需等待：

TaskOutput工具调用：
- task_id: "agent-12345"
- block: false

返回当前状态：运行中、已完成或最终结果。 </retrieving_results>

<parallel_agents> 并行启动多个代理：

为了最大化性能，可同时启动多个独立的代理：

单条消息中包含多个Task工具调用：

Task 1:
- description: "审查代码质量"
- prompt: "检查代码质量..."
- subagent_type: "code-reviewer"
- run_in_background: true

Task 2:
- description: "运行安全扫描"
- prompt: "扫描漏洞..."
- subagent_type: "security-scanner"
- run_in_background: true

Task 3:
- description: "检查测试覆盖率"
- prompt: "分析测试覆盖率..."
- subagent_type: "test-analyzer"
- run_in_background: true

然后获取所有结果：

为每个agent_id调用TaskOutput

</parallel_agents>

<when_to_use_background> 适合使用后台代理的场景：

长时间运行的分析任务（安全审查、全面代码分析）
可并行执行的多个独立任务
希望在等待期间继续处理其他工作的任务
耗时较长的研究任务

不适合使用后台代理的场景：

快速操作（<10秒）
需按顺序执行的依赖任务
下一步操作需要立即获取结果的任务
简单的单文件操作

模式：并行分析流水线

1. 启动多个分析代理在后台运行
2. 继续处理其他工作或等待
3. 收集所有结果
4. 在主对话中整合发现的问题

</when_to_use_background>

<resuming_agents> 恢复代理： 可使用

resume

参数结合代理ID恢复之前的代理：

Task工具调用：
- description: "继续安全审查"
- prompt: "请继续处理剩余文件..."
- subagent_type: "security-reviewer"
- resume: "agent-12345"  # 之前的代理ID

代理会保留之前的完整上下文并继续工作。 </resuming_agents> </background_execution>

<management> <using_agents_command> 运行`/agents`命令可打开交互界面，用于： - 查看所有可用子代理 - 创建新子代理 - 编辑现有子代理 - 删除自定义子代理 </using_agents_command>

<manual_editing> 你也可以直接编辑子代理文件：

项目级：
```
.claude/agents/subagent-name.md
```
用户级：
```
~/.claude/agents/subagent-name.md
```
</manual_editing> </management>

<reference> **核心参考资料**:

子代理使用与配置：references/subagents.md

文件格式与配置
模型选择（Sonnet 4.5 + Haiku 4.5编排）
工具安全与最小权限原则
提示词缓存优化
后台执行（run_in_background、TaskOutput、并行代理）
完整示例

编写高效提示词：references/writing-subagent-prompts.md

核心原则与XML结构
优化description字段以实现自动路由
复杂推理的扩展思考
安全约束与强模态动词
成功标准定义

高级主题:

评估与测试：references/evaluation-and-testing.md

评估指标（任务完成度、工具使用正确性、鲁棒性）
测试策略（离线、模拟、在线监控）
评估驱动开发
自定义标准的G-Eval

错误处理与恢复：references/error-handling-and-recovery.md

常见故障模式与原因
恢复策略（优雅降级、重试、断路器）
结构化通信与可观测性
需避免的反模式

上下文管理：references/context-management.md

内存架构（STM、LTM、工作内存）
上下文策略（摘要、滑动窗口、草稿本）
长时间运行任务的管理
提示词缓存交互

编排模式：references/orchestration-patterns.md

顺序、并行、分层、协调器模式
Sonnet + Haiku编排以平衡成本与性能
多代理协作
模式选择指南

调试与故障排除：references/debugging-agents.md

日志、追踪与关联ID
常见故障类型（幻觉、格式错误、工具误用）
诊断流程
持续监控 </reference>

<success_criteria> 配置良好的子代理需满足：

有效的YAML前置元数据（名称与文件匹配，description包含触发场景）
系统提示词中有明确的角色定义
合理的工具限制（最小权限原则）
采用XML结构的系统提示词，包含角色、方法和约束
优化description字段以支持自动路由
在代表性任务上测试通过
根据任务复杂度选择合适的模型（Sonnet用于推理任务，Haiku用于简单任务） </success_criteria>