create-subagents

子 Agent 是在隔离上下文中运行、职责明确且工具访问权限有限的专用 Claude 实例。本技能将教你如何创建高效的子 Agent、编写优质的系统提示词、配置工具访问权限，以及使用 Task 工具编排多 Agent 工作流。

子 Agent 可以将复杂任务委派给专用 Agent，由它们自主执行，无需与用户交互，并将最终输出返回到主对话。

<quick_start>

1. 运行 /agents 命令
2. 选择“Create New Agent”
3. 选择项目级（.claude/agents/）或用户级（~/.claude/agents/）
4. 定义子 Agent：
   • name：仅使用小写字母和连字符
   • description：何时应使用此子 Agent？
   • tools：可选的逗号分隔列表（省略时继承所有工具）
   • model：可选（sonnet、opus、haiku 或 inherit）
5. 编写系统提示词（子 Agent 的指令）

```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 --- You are a senior code reviewer focused on quality, security, and best practices.

<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/` 目录 | 所有项目 | 最低 |

名称冲突时，项目级子 Agent 优先于用户级子 Agent。
</file_structure>

<configuration>
<field name="name">
- 只能使用小写字母和连字符
- 必须唯一
</field>

<field name="description">
- 使用自然语言描述用途
- 说明 Claude 应在何时调用此子 Agent
- 用于自动选择子 Agent
</field>

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

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

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

子 Agent 在隔离上下文中运行，并将最终输出返回到主对话。它们：
- ✅ 可以使用 Read、Write、Edit、Bash、Grep、Glob 等工具
- ✅ 可以访问 MCP 服务和其他非交互式工具
- ❌ **不能使用 AskUserQuestion 或任何需要用户交互的工具**
- ❌ **不能提供选项或等待用户输入**
- ❌ **用户看不到子 Agent 的中间步骤**

主对话只能看到子 Agent 的最终报告／输出。
</critical_constraint>

<workflow_design>
**使用子 Agent 设计工作流：**

以下情况使用**主对话**：
- 向用户收集需求（AskUserQuestion）
- 向用户提供选项或决策
- 任何需要用户确认／输入的任务
- 用户需要了解进度的工作

以下情况使用**子 Agent**：
- 研究任务（查找 API 文档、分析代码）
- 根据预先定义的需求生成代码
- 分析和报告（安全审查、测试覆盖率）
- 不需要用户交互、但上下文占用较多的操作

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

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">
明确界定子 Agent 的角色、能力和约束。
</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>

根据具体任务领域定制指令。不要创建通用的“助手”子 Agent。

❌ 不佳：“你是一个乐于助人的助手，负责帮助编写代码” ✅ 良好：“你是 React 组件重构专家。分析组件是否遵循 hooks 最佳实践，是否存在性能反模式及无障碍问题。” </system_prompt_guidelines> <subagent_xml_structure> Subagent.md 文件是仅由 Claude 使用的系统提示词。与技能和斜杠命令一样，为了获得最佳解析效果和令牌效率，应采用纯 XML 结构。

<recommended_tags> Subagent 结构中常用的标签：

• <role> - 说明 subagent 的身份和职责
• <constraints> - 硬性规则（绝不／必须／始终）
• <focus_areas> - 需要优先关注的方面
• <workflow> - 分步流程
• <output_format> - 交付内容的结构
• <success_criteria> - 完成标准
• <validation> - 如何验证工作 </recommended_tags>

<intelligence_rules> 简单的 subagent（单一专注任务）：

• 至少使用 role + constraints + workflow
• 示例：代码审查员、测试运行器

中等复杂度的 subagent（多步骤流程）：

• 增加 workflow 步骤、output_format、success_criteria
• 示例：API 研究员、文档生成器

复杂的 subagent（研究 + 生成 + 验证）：

• 根据需要添加所有标签，包括 validation、示例
• 示例：MCP API 研究员、综合审计员 </intelligence_rules>

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

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

有关 XML 结构原则和令牌效率的详细信息，请参阅 @skills/create-agent-skills/references/use-xml-tags.md——同样的原则也适用于 subagent。 </critical_rule> </subagent_xml_structure>

当当前任务与 `description` 字段匹配时，Claude 会自动选择 subagent。 你也可以显式调用 subagent：

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

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

运行 `/agents`，即可通过交互界面执行以下操作： - 查看所有可用的 subagent - 创建新的 subagent - 编辑现有的 subagent - 删除自定义 subagent

<manual_editing> 你也可以直接编辑 subagent 文件：

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

**核心参考资料**：

Subagent 的使用和配置：references/subagents.md

• 文件格式和配置
• 模型选择（Sonnet 4.5 + Haiku 4.5 编排）
• 工具安全和最小权限
• 提示词缓存优化
• 完整示例

编写有效的提示词：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 编排，兼顾成本与性能
• 多 Agent 协调
• 模式选择指南

**调试与故障排查**：[references/debugging-agents.md](references/debugging-agents.md) - 日志记录、追踪和关联 ID - 常见故障类型（幻觉、格式错误、工具误用） - 诊断流程 - 持续监控

<success_criteria> 配置良好的子 Agent 具备以下特征：

• 有效的 YAML 前置元数据（名称与文件匹配，描述包含触发条件）
• 系统提示词中有清晰的角色定义
• 适当的工具限制（遵循最小权限原则）
• 采用 XML 结构的系统提示词，包含角色、方法和约束
• 针对自动路由优化的描述字段
• 已在有代表性的任务上成功测试
• 模型选择适合任务复杂度（推理任务使用 Sonnet，简单任务使用 Haiku） </success_criteria>