为什么要这张表
一个 agent 文件顶部的 frontmatter 写什么、怎么写，决定了这个 agent 能干什么、会不会乱跑。官方文档把 16 个字段分散在多处，这里集中成一张表，方便你对着自己的 .md 文件逐行核对。用不上的字段不填即可，只有 name 和 description 是必填的。
字段全集表（16 个）
| 字段 | 是否必填 | 类型 | 含义 | 举例 |
|---|---|---|---|---|
name | 必填 | string | agent 唯一标识，只用小写字母和连字符 | my-reviewer |
description | 必填 | string | 什么时候交给它——这是 Claude 判断”该不该派它”的主要依据；写 "PROACTIVELY" 可触发 Claude 主动调用 | Review code after edits. PROACTIVELY suggest when files change. |
tools | 选填 | string / list | 允许使用的工具白名单，逗号分隔；不填则继承所有工具；支持 Agent(agent_type) 语法限制可派生的子 agent | Read, Grep, Glob |
disallowedTools | 选填 | string / list | 禁止使用的工具黑名单，从已继承或已指定的列表里移除 | Bash, Write |
model | 选填 | string | 使用哪个模型：sonnet / opus / haiku / 完整模型 ID / inherit（默认） | haiku |
permissionMode | 选填 | string | 权限模式：default / acceptEdits / auto / dontAsk / bypassPermissions / plan | acceptEdits |
maxTurns | 选填 | integer | 最多跑几轮 agentic turn，超过后自动停 | 5 |
skills | 选填 | list | 启动时预加载的 skill 名称列表（完整内容注入，不是只让它”知道”） | [kb-compile, kb-lint] |
mcpServers | 选填 | list | 该 agent 专用的 MCP 服务器，写服务器名字符串或内联 {name: config} 对象 | [context7] |
hooks | 选填 | object | 该 agent 作用域内的生命周期钩子，支持所有 hook 事件，最常用的是 PreToolUse / PostToolUse / Stop | {Stop: [{type: command, command: echo done}]} |
memory | 选填 | string | 持久记忆范围：user / project / local | project |
background | 选填 | boolean | 设为 true 则始终以后台任务方式运行（默认 false） | true |
effort | 选填 | string | 覆盖当前 session 的算力档位：low / medium / high / max（仅 Opus 4.6 支持）；默认继承 session | low |
isolation | 选填 | string | 设为 "worktree" 则在临时 git worktree 里跑，没有变更时自动清理 | "worktree" |
initialPrompt | 选填 | string | 当 agent 以主 session 身份启动（--agent 或 agent 设置）时，自动作为第一个用户 turn 提交，会处理其中的 commands 和 skills，并前置于用户输入 | "先读 CLAUDE.md，再等待任务。" |
color | 选填 | string | 该 agent 在任务列表和对话记录里显示的颜色：red / blue / green / yellow / purple / orange / pink / cyan | blue |
常用 3 个字段的深讲
model — 省钱最直接的一个字段
“Model to use:
sonnet,opus,haiku, a full model ID (e.g.,claude-opus-4-6), orinherit(default:inherit)” — CCBP 原文
人话：不填就跟主 session 用同一个模型。但如果某个 agent 只做搜索和读文件，写 model: haiku 能明显省 token。反过来，负责最终决策的 agent 可以单独升到 opus。这个字段是”按需定级”最简单的入口。
permissionMode — 控制它能不能直接改文件
“Permission mode:
default,acceptEdits,auto,dontAsk,bypassPermissions, orplan” — CCBP 原文
人话：default 每次改文件都问你确认；acceptEdits 静默接受所有文件编辑但其他操作还问；bypassPermissions 完全跳过确认（危险，谨慎用）；plan 只出计划不动文件。如果你让一个 agent 做评审，设成 plan 最稳——它物理上就写不了东西。
tools — 角色边界最具体的一环
“Comma-separated allowlist of tools (e.g.,
Read, Write, Edit, Bash). Inherits all tools if omitted. SupportsAgent(agent_type)syntax to restrict spawnable subagents” — CCBP 原文
人话：不填等于什么工具都能用，风险最大。一个只做代码审查的 agent，填 Read, Grep, Glob 就够了——它连 Write 都没有，物理上改不了文件，边界最清晰。Agent(agent_type) 是进阶写法，限制这个 agent 只能派特定类型的子 agent，防止它随便开分支。
容易踩坑的字段
坑 1：description 写太模糊
description 是 Claude 判断”现在该派哪个 agent”的主要依据。写”帮我处理任务”这种话，Claude 不知道什么时候该触发它。应该写具体场景，比如”审查改完的代码，找可读性问题和潜在风险”。如果想让 Claude 主动调用，在 description 里写上 PROACTIVELY。
坑 2：tools 不填以为”没关系”
不填 tools 等于继承所有工具，包括 Bash（可以跑任意命令）。如果你的 agent 只是一个”读-分析-输出”角色，给它 Bash 权限等于留了一个后门。最小权限原则：只填它真正需要的工具。
坑 3：skills 和”让 agent 知道有哪些 skill”是两回事
skills 字段设计是”预加载”——把 skill 的完整内容直接注入 agent 的 context，不是告诉它”有这个 skill 可以调”。所以列越多，context 越重。只加真正每次都要用的 skill，其余的按需调用。
关联
- 基础定义见 02-agent（agent 是什么、三件事、常见误解）
- 被派出去独立跑时的机制见 04-subagent
- 这 16 个字段与具体运行环境的关系，见正本”技术机制”一节
来源：/Users/chenbin/Documents/Personal Kingdom/知识库/素材_AI使用/项目样本/claude-code-best-practice/github-mirror/claude-code-best-practice/best-practice/claude-subagents.md（CCBP v2.1.101 · 原版 Frontmatter Fields 表，字段数 = 16）