子代理（Subagents）是Claude Code的核心扩展机制，允许用户将复杂任务委托给专用代理执行。通过在 .claude/agents/ 目录下创建YAML frontmatter配置的Markdown文件，可以定义具备独立工具权限、模型、内存和技能的代理。Claude Code内置了5种通用代理类型，并提供了用户级、项目级和本地级三种持久化内存作用域，使代理能够跨会话积累知识。
Claude Code Subagents 指南：16 个 Frontmatter 字段、5 个内置 Agent、内存系统
子代理是构建 Agentic Engineering 工作流 的基石。与主会话不同，子代理拥有独立的上下文和专注的职责，可以用于代码探索、方案规划、自动化任务执行等场景，显著提升 Claude Code 处理复杂工程任务的可控性与协作性。
1. 子代理的核心：16 个 Frontmatter 字段
每个子代理通过一个 Markdown 文件定义，文件头部是 YAML 格式的 frontmatter。以下是所有 16 个可配置字段：
| 字段 | 类型 | 必需 | 说明与示例 |
|---|---|---|---|
name |
string | 是 | 唯一标识符，使用小写字母和连字符。例如：weather-agent |
description |
string | 是 | 描述代理用途。若设置为 "PROACTIVELY"，Claude 会在匹配时自动调用。 |
tools |
string/list | 否 | 允许使用的工具白名单，如 Read, Write, Edit, Bash。省略则继承全部工具。支持 Agent(agent_type) 语法限制可生成的子代理。 |
disallowedTools |
string/list | 否 | 明确禁止的工具，会从继承或指定的列表中移除。 |
model |
string | 否 | 使用的模型：sonnet、opus、haiku、完整模型ID或 inherit（默认）。 |
permissionMode |
string | 否 | 权限模式：default、acceptEdits、auto、dontAsk、bypassPermissions、plan。 |
maxTurns |
integer | 否 | 代理执行的最大回合数。 |
skills |
list | 否 | 启动时预加载的技能名称列表，技能内容会直接注入代理上下文。 |
mcpServers |
list | 否 | 此子代理专用的 MCP 服务器列表。 |
hooks |
object | 否 | 作用于此子代理的生命周期钩子，支持所有钩子事件。 |
memory |
string | 否 | 持久化内存作用域：user、project 或 local。 |
background |
boolean | 否 | 设为 true 则始终作为后台任务运行。 |
effort |
string | 否 | 努力程度覆盖：low、medium、high、xhigh、max（仅Opus 4.6）。 |
isolation |
string | 否 | 设为 "worktree" 可在临时的 git worktree 中运行，无更改则自动清理。 |
initialPrompt |
string | 否 | 当通过 --agent 或 agent 设置将此代理作为主会话代理时，自动提交为第一轮用户消息。 |
color |
string | 否 | 在任务列表和会话记录中的显示颜色，如 red、blue、green。 |
关键点：name 和 description 是必需的。description 的描述直接影响 Claude 的路由决策，编写清晰的描述是确保代理被正确触发的前提。关于 skills 字段的更多组合模式，可以参考 Skills 深度解析。
2. Claude Code 内置的 5 个代理类型
除了自定义代理，Claude Code 还提供了 5 个开箱即用的内置代理，它们适用于常见场景：
general-purpose：默认代理类型，用于复杂的多步骤任务，如研究、代码搜索和自主工作。继承所有工具。Explore：使用haiku模型，拥有只读工具（无 Write, Edit）。专为快速、低成本地搜索代码库、寻找文件和回答代码库问题而优化。Plan：在规划模式（Plan Mode）下用于前期研究。探索代码库并设计实现方案，但不编写代码。拥有只读工具。statusline-setup：使用sonnet模型，仅有 Read 和 Edit 权限。专门用于配置用户的状态栏（Status Line）设置。claude-code-guide：使用haiku模型，配备 Glob, Grep, Read, WebFetch, WebSearch 工具。用于回答关于 Claude Code 功能、Agent SDK 和 Claude API 的问题。
你可以在 tools 字段中使用 Agent(Explore) 这样的语法来限制一个自定义代理只能调用 Explore 内置代理，从而控制其能力范围。
3. 代理内存系统：跨会话的知识积累
代理内存（Agent Memory）是子代理持久化存储知识的核心功能。通过设置 memory 字段，代理可以在多次执行间保留和更新其学习到的模式、约定和决策。
三种内存作用域（Scope）
| 作用域 | 存储路径 | 是否版本控制 | 是否共享 | 最佳适用场景 |
|---|---|---|---|---|
user |
~/.claude/agent-memory/<agent-name>/ |
否 | 否 | 跨项目的个人知识，推荐作为默认选项。 |
project |
.claude/agent-memory/<agent-name>/ |
是（Git） | 是 | 团队共享的项目特定知识。 |
local |
.claude/agent-memory-local/<agent-name>/ |
否（Git忽略） | 否 | 个人特定的项目知识，不纳入版本控制。 |
这些作用域的层级与设置文件（~/.claude/settings.json → .claude/settings.json → .claude/settings.local.json）的设计理念一致。
内存工作机制
- 加载：代理启动时，其
MEMORY.md文件的前 200 行会被注入到代理的系统提示中。 - 工具：为了读写内存，
Read、Write、Edit工具会自动为该代理启用。 - 管理：代理在执行过程中可以自由读写其内存目录下的文件。如果
MEMORY.md超过 200 行，代理会将细节移至主题文件中（如react-patterns.md）。 - 互补性：代理内存与
CLAUDE.md（项目上下文）互补。代理会同时读取两者。
示例：一个设置了 memory: project 的 code-reviewer 代理，其内存可能存储在 .claude/agent-memory/code-reviewer/ 目录下，并包含 coding-standards.md 等文件。
4. 实战示例：weather-agent
weather-agent 是一个演示“命令（Command）→ 代理（Agent）→ 技能（Skill）”编排工作流 的完整示例。
文件路径：.claude/agents/weather-agent.md
---
name: weather-agent
description: Use this agent PROACTIVELY when you need to fetch weather data for
Dubai, UAE. This agent fetches real-time temperature from Open-Meteo
using its preloaded weather-fetcher skill.
allowedTools:
- "Read"
- "Skill"
model: sonnet
color: green
maxTurns: 5
permissionMode: acceptEdits
memory: project
skills:
- weather-fetcher
---
# Weather Agent
You are a specialized weather agent that fetches weather data for Dubai, UAE.
## Your Task
Execute the weather workflow by following the instructions from your preloaded skill:
1. **Fetch**: Follow the `weather-fetcher` skill instructions to fetch the current temperature.
2. **Report**: Return the temperature value and unit to the caller.
3. **Memory**: Update your agent memory with the reading details for historical tracking.使用方式：在 Claude Code 主会话中输入与天气相关的问题，如 “what is the weather in dubai?”，由于描述中包含 "PROACTIVELY"，Claude 会自动识别并调用此代理。代理会使用预加载的 weather-fetcher 技能获取数据，并将结果返回。由于设置了 memory: project，它还可以将天气记录保存在项目内存中供未来参考。
如何创建自定义代理
- 使用命令：在 Claude Code 中执行
/agents命令，然后按照提示创建。 - 自然语言创建：直接要求 Claude 帮你创建一个代理，例如：“创建一个用于检查代码中安全漏洞的子代理，需要读取和编辑文件，并使用 sonnet 模型。” Claude 会在
.claude/agents/目录下生成对应的 Markdown 文件。
FAQ
Q: 如何创建我的第一个子代理？
A: 最简单的方式是在 Claude Code 中运行 /agents 命令，然后选择“Create new agent”。或者直接用自然语言告诉 Claude 你想创建什么功能的代理，它会帮你生成文件。
Q: user、project 和 local 三种内存作用域应该如何选择？
A: 如果你希望代理积累的知识在所有项目中通用且只有你能看到，选 user。如果知识是针对当前项目且希望团队成员共享（通过 Git），选 project。如果知识是针对当前项目但属于个人笔记（如调试记录），选 local。
Q: 子代理（Subagent）和技能（Skill）有什么区别？ A: 技能（Skill）是静态的、可复用的指令和知识模块，可以被代理或命令在启动时加载。子代理是具有独立执行能力的“智能体”，它可以调用技能，但自身拥有会话、工具和内存。简单说，技能是“说明书”，子代理是“工人”。