本页目录5
要点速览
- 子代理在独立上下文窗口里干活,只把摘要带回主会话——把搜索/日志/大文件挡在主对话之外。
- 内置 Explore(只读探索)、Plan(plan 模式调研)、general-purpose(探索+修改)三种,Claude 按需自动委托。
- 自定义:在 .claude/agents/(项目,入库共享)或 ~/.claude/agents/(个人)放 Markdown + YAML frontmatter,或用 /agents 命令管理。
- frontmatter:name、description(何时委托,必填)、tools(白名单)/disallowedTools(黑名单)、model、skills、isolation: worktree。
- 调用:按 description 自动委托;或显式 @agent-<name>(插件用 @agent-<plugin:name>);手动改文件后需重启会话生效。
本文是对官方文档 Create custom subagents 的中文要点整理,字段与语法以原文为准。
子代理解决什么问题
当一个支线任务会用搜索结果、日志、文件内容淹没你的主对话(而这些你之后又不会再看),就该用子代理:它在自己的上下文窗口里完成这部分工作,只返回摘要。每个子代理有独立的系统提示、特定的工具权限和独立权限。
它能帮你:保护上下文(把探索/实现挡在主对话外)、约束工具(限定能用哪些工具)、复用配置(用户级子代理跨项目)、专精行为(聚焦的系统提示)、控成本(把任务路由到更快更便宜的模型如 Haiku)。
内置子代理
Claude 会在合适时自动调用,无需手动指定:
- Explore:只读地搜索/理解代码库,不做改动,把探索结果挡在主上下文外。
- Plan:plan 模式下做代码调研,让探索输出留在独立窗口,主对话保持只读。
- general-purpose:任务既要探索又要改动、或需多步依赖推理时委托它。
自定义子代理:文件与位置
子代理是带 YAML frontmatter 的 Markdown 文件。可手写,或用 /agents 命令的可视化界面创建(创建后立即生效,无需重启)。位置:
.claude/agents/—— 项目级,适合特定代码库;入版本控制即可团队共享。从当前目录向上逐级扫描。~/.claude/agents/—— 用户级,你所有项目都可用。
直接在磁盘新增/编辑子代理文件后,需重启会话才加载;通过
/agents界面创建的则立即生效。
frontmatter 字段
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide…
- name(必填):唯一标识,决定如何被调用(与子目录路径无关)。
- description(必填):何时该委托给它——写清楚 Claude 才知道何时用;加"use proactively"鼓励主动委托。
- tools(白名单)/ disallowedTools(黑名单):二选一限定工具。例如只给
Read, Grep, Glob, Bash,它就无法编辑/写文件或用 MCP。 - model:指定模型(可路由到便宜模型控成本)。
- skills:启动时预加载进子代理上下文的 Skill(注入全文)。
- isolation: worktree:在临时 git worktree 里跑,给它一份隔离的仓库副本;无改动则自动清理。
怎么调用
- 自动委托:Claude 根据你的请求、子代理的
description和当前上下文决定是否委托。 - 显式调用:本地子代理用
@agent-<name>;插件子代理用作用域名,如@agent-my-plugin:code-reviewer。也可在/agents的 typeahead 里选。 - 多步串联:让 Claude 按顺序使用多个子代理,每个完成后把结果交回,再传给下一个。