sub-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sub-Agents Reference

子代理参考文档

Create specialized AI agents with isolated contexts for specific tasks.

创建具有独立上下文的专业AI代理，用于完成特定任务。

When to Use

使用场景

"How do I create a sub-agent?"
"Configure agent tools"
"What built-in agents exist?"
"Agent model selection"
"Agent chaining patterns"

"如何创建子代理？"
"配置代理工具"
"有哪些内置代理？"
"代理模型选择"
"代理链式调用模式"

Quick Start

快速开始

Interactive (Recommended)

交互式方式（推荐）

bash

/agents

Opens menu to create, edit, and manage agents.

bash

/agents

打开菜单以创建、编辑和管理代理。

Manual Creation

手动创建

bash

mkdir -p .claude/agents
cat > .claude/agents/reviewer.md << 'EOF'
---
name: reviewer
description: Code review specialist. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer focusing on quality and security.

bash

mkdir -p .claude/agents
cat > .claude/agents/reviewer.md << 'EOF'
---
name: reviewer
description: Code review specialist. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer focusing on quality and security.

Review Checklist

Code clarity and naming
Error handling
Security vulnerabilities
Test coverage EOF

undefined

Code clarity and naming
Error handling
Security vulnerabilities
Test coverage EOF

undefined

CLI-Based

基于CLI的方式

bash

claude --agents '{
  "reviewer": {
    "description": "Code reviewer",
    "prompt": "Review for quality and security",
    "tools": ["Read", "Bash"],
    "model": "sonnet"
  }
}'

bash

claude --agents '{
  "reviewer": {
    "description": "Code reviewer",
    "prompt": "Review for quality and security",
    "tools": ["Read", "Bash"],
    "model": "sonnet"
  }
}'

Agent File Format

代理文件格式

yaml

---
name: agent-name
description: When/why to use this agent
tools: Read, Edit, Bash      # Optional, inherits all if omitted
model: sonnet                 # sonnet, haiku, claude-opus-4-5-20251101, inherit
---

System prompt content here...

yaml

---
name: agent-name
description: When/why to use this agent
tools: Read, Edit, Bash      # Optional, inherits all if omitted
model: sonnet                 # sonnet, haiku, claude-opus-4-5-20251101, inherit
---

System prompt content here...

Configuration Fields

配置字段

Field	Required	Options
`name`	Yes	lowercase, hyphens
`description`	Yes	When to use
`tools`	No	Tool list (inherits all if omitted)
`model`	No	`sonnet` , `haiku` , `claude-opus-4-5-20251101` , `inherit`

字段	是否必填	可选值
`name`	是	小写字母、连字符
`description`	是	使用场景说明
`tools`	否	工具列表（若省略则继承所有工具）
`model`	否	`sonnet` , `haiku` , `claude-opus-4-5-20251101` , `inherit`

Built-In Agents

内置代理

Agent	Model	Tools	Purpose
General-purpose	Sonnet	All	Complex multi-step tasks
Plan	Sonnet	Read-only	Plan mode research
Explore	Haiku	Read-only	Fast codebase search

代理	模型	工具	用途
通用型	Sonnet	全部	复杂多步骤任务
规划型	Sonnet	只读	规划模式研究
探索型	Haiku	只读	快速代码库搜索

Model Selection

模型选择

Model	Speed	Best For
Haiku	Fastest	Search, quick lookups
Sonnet	Fast	Most tasks (default)
Opus	Slower	Complex reasoning

模型	速度	最佳适用场景
Haiku	最快	搜索、快速查询
Sonnet	快	大多数任务（默认）
Opus	较慢	复杂推理

Tool Combinations

工具组合

yaml

undefined

yaml

undefined

Code Reviewer (read-only)

tools: Read, Grep, Glob, Bash

Debugger

tools: Read, Edit, Bash, Grep, Glob

Implementer

tools: Read, Write, Edit, Bash, Glob

undefined

tools: Read, Write, Edit, Bash, Glob

undefined

Example Agents

示例代理

Code Reviewer

代码审查代理

yaml

---
name: code-reviewer
description: Reviews code for quality and security. Use after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Review code for:
- Security vulnerabilities
- Code quality issues
- Missing error handling
- Test coverage gaps

Output findings by priority: Critical > Warning > Suggestion

yaml

---
name: code-reviewer
description: Reviews code for quality and security. Use after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Review code for:
- Security vulnerabilities
- Code quality issues
- Missing error handling
- Test coverage gaps

Output findings by priority: Critical > Warning > Suggestion

Debugger

调试代理

yaml

---
name: debugger
description: Debug errors and test failures.
tools: Read, Edit, Bash, Grep, Glob
model: inherit
---

Debugging process:
1. Capture error details
2. Identify failure location
3. Form hypotheses
4. Test and verify
5. Implement fix

yaml

---
name: debugger
description: Debug errors and test failures.
tools: Read, Edit, Bash, Grep, Glob
model: inherit
---

Debugging process:
1. Capture error details
2. Identify failure location
3. Form hypotheses
4. Test and verify
5. Implement fix

File Locations

文件位置

Type	Location	Priority
Project	`.claude/agents/`	Highest
User	`~/.claude/agents/`	Lower

类型	位置	优先级
项目级	`.claude/agents/`	最高
用户级	`~/.claude/agents/`	较低

Advanced Patterns

高级模式

Resumable Agents

可恢复代理

[Agent returns agentId: "abc123"]

[Agent returns agentId: "abc123"]

Later: resume with context

claude -r "abc123" "Continue analysis"

undefined

claude -r "abc123" "Continue analysis"

undefined

Agent Chaining

代理链式调用

Use code-analyzer to find issues,
then use optimizer to fix them

Use code-analyzer to find issues,
then use optimizer to fix them

Best Practices

最佳实践

Single responsibility - One clear purpose per agent
Restrict tools - Only grant what's needed
Clear descriptions - Action-oriented, include "proactively"
Version control - Check
```
.claude/agents/
```
into git

单一职责 - 每个代理只有一个明确的用途
限制工具权限 - 仅授予必要的工具访问权
清晰的描述 - 面向操作，包含“主动”等词汇
版本控制 - 将
```
.claude/agents/
```
目录纳入git管理