在 Claude Code 里创建 subagent，其实就是在写一个包含 YAML frontmatter 的标准 Markdown 文件。它最核心的配置信息，都定义在文件开头的 --- 块里。
这里是所有可用字段的对照表，我为你做了分类：
| 字段 (Field) | 是否必须 (Required) | 作用与解释 (Purpose & Explanation) |
|---|---|---|
name | ✅ 必须 | 子代理的唯一标识。需使用小写字母和连字符，如 code-reviewer，是调用它的ID。 |
description | ✅ 必须 | 自动调度的“触发器”。用自然语言清晰描述代理的用途和何时使用，这是Claude Code决定是否委派任务的关键信息。 |
tools | ⚪️ 可选 | 允许代理调用的工具白名单。不填则默认继承所有可用工具。 |
model | ⚪️ 可选 | 指定代理使用的模型。可从 sonnet, opus, haiku 中选择，或填 inherit 继承主会话模型。 |
permissionMode | ⚪️ 可选 | 代理的权限模式。控制代理在调用工具时的权限级别，可选 default, acceptEdits, bypassPermissions, plan。 |
skills | ⚪️ 可选 | 代理启动时自动加载的“技能”列表。将特定技能（如skill-name）注入代理，增强其能力。 |
color | ⚪️ 可选 | UI视觉标识。为代理在用户界面中指定一个颜色（如red, blue）。 |
System Prompt (正文) | ✅ 必须 | 核心行为指令。定义了代理的角色、职责和工作流程，是整个subagent的大脑。 |
🔧 tools 字段详解
tools 字段是控制subagent能力的核心，通过限制工具能有效防止意外操作。
- 作用：限制工具可有效防止意外写操作。
- 常用工具有：
- Read：读取文件
- Write：写入/创建文件
- Edit：编辑文件
- Bash：执行Shell命令
- Glob：模式匹配搜索文件
- Grep：文件内搜索代码
⚙️ permissionMode 字段详解
当你想精细控制subagent的操作权限时，可以通过设置 permissionMode 来实现。主要有以下几种模式：
default：需要主对话审批每个操作。acceptEdits：自动接受文件修改，无需逐一确认。bypassPermissions：完全自主，跳过所有权限检查。plan：仅允许只读和浏览，用于规划和探索。
✍️ System Prompt（正文）编写
一个好的系统提示词通常包含：
- 身份定义：
你是一名专注于XX领域的专家。 - 核心职责：列出代理需要执行的任务清单。
- 工作流程：描述代理被调用后应遵循的步骤。
- 输出格式：指定报告或响应的结构，确保一致性。
实战模板
下面是一个功能齐全的代码审查代理模板：
---
name: code-reviewer
description: 审查提交的代码，主动评估代码质量、潜在问题和安全性。用于代码审查、安全审计和性能分析。
tools: Read, Grep, Glob
model: sonnet
permissionMode: default
---
# Code Reviewer Agent
## 角色
你是一位资深的代码审查专家，专注于确保代码的高质量、安全性和可维护性。
## 工作流程
1. 使用 `Glob` 工具定位目标文件。
2. 使用 `Read` 工具读取完整的代码内容。
3. 分析代码逻辑、性能瓶颈和安全隐患。
4. 生成一份结构化的审查报告。
## 报告格式
- **概要**：整体评价和主要发现。
- **问题列表**：按严重程度（高/中/低）列出具体问题、代码位置及修复建议。
这个模板中，我刻意使用了推荐的 Glob 和 Grep 工具来定位和分析代码，你可以把它放在 .claude/agents/ 目录下（项目级）或 ~/.claude/agents/ 目录（用户级），Claude Code 就能自动识别了。
补充 skill 的字段做对比
在 Claude Code 中定义一个技能（Skill），核心文件是 SKILL.md。它的配置信息都写在文件开头的 YAML 前置元数据（Frontmatter）部分，下方是其可用且最新的字段清单：
| 字段 | 必须 | 说明 |
|---|---|---|
name | 否 | 技能的显示名称。如果省略，则使用目录名。只能使用小写字母、数字和连字符（最多64个字符）。 |
description | 推荐 | 技能的功能及其使用时机。Claude 使用此来决定何时应用该技能。如果省略，则使用 Markdown 内容的第一段。请将关键用例放在前面：合并后的 description 和 when_to_use 文本在技能列表中会被截断至 1,536 个字符，以减少上下文占用。 |
when_to_use | 否 | 为 Claude 提供何时应调用技能的额外上下文，例如触发短语或示例请求。该内容会被附加到技能列表中的 description 后，并计入 1,536 个字符的限制。 |
argument-hint | 否 | 在自动补全过程中显示的提示，用于指示预期的参数。示例：[issue-number] 或 [filename] [format]。 |
arguments | 否 | 用于技能内容中 $name 替换的命名位置参数。接受以空格分隔的字符串或 YAML 列表。名称按顺序映射到参数位置。 |
disable-model-invocation | 否 | 设置为 true 以防止 Claude 自动加载此技能。用于希望使用 /name 手动触发的操作流程。同时可防止该技能被预加载到子代理中。默认值：false。 |
user-invocable | 否 | 设置为 false 以从 / 菜单中隐藏。用于用户不应直接调用的背景知识。默认值：true。 |
allowed-tools | 否 | 当此技能激活时，Claude 无需询问许可即可使用的工具。接受以空格分隔的字符串或 YAML 列表。 |
model | 否 | 此技能激活时使用的模型。该覆盖设置仅对当前轮次的剩余部分有效，不会被保存到设置中；会话模型会在您的下一个提示词时恢复。接受与 /model 相同的值，或使用 inherit 保持当前激活的模型。 |
effort | 否 | 此技能激活时的努力程度。会覆盖会话的努力程度设置。默认值：继承自会话。可选值：low， medium， high， xhigh， max；可用级别取决于所使用的模型。 |
context | 否 | 设置为 fork 以在分叉的子代理上下文中运行。 |
agent | 否 | 当设置了 context: fork 时，指定要使用的子代理类型。 |
hooks | 否 | 限定于此技能生命周期的钩子。配置格式请参见 技能和代理中的钩子。 |
paths | 否 | 限制该技能激活条件的 Glob 模式。接受以逗号分隔的字符串或 YAML 列表。设置后，Claude 仅当处理的文件与模式匹配时才会自动加载该技能。使用与路径特定规则相同的格式。 |
shell | 否 | 在此技能中用于 !command 和 ! 块的 Shell。接受 bash（默认）或 powershell。设置 powershell 会在 Windows 上通过 PowerShell 运行内联 Shell 命令。需要设置 CLAUDE_CODE_USE_POWERSHELL_TOOL=1。 |
🧐 字段详解与最佳实践
技能的设计精髓在于简洁和明确，下面是编写这些字段的一些核心思路：
-
description：准确性比长度更重要。 这是整个技能中最重要的字段，Claude 会根据它来判断是否调用你的技能。一个好的描述应该包含具体的触发词和使用场景，例如，"Apply Acme brand voice, colors, and structure to docs and slides; use this for branding, presentation, or style enforcement requests."就比"Brand guidelines"有效得多。 -
user-invocablevsdisable-model-invocation：控制两种调用入口。 这两个字段共同控制了技能的两个使用入口。通常，为了最灵活的使用，你会将user-invocable设为true，disable-model-invocation设为false。
✍️ 一个 代码审查 技能配置示例
---
name: code-reviewer
description: 审查提交的代码，主动评估代码质量、潜在问题和安全性。用于代码审查、安全审计和性能分析。
user-invocable: true
disable-model-invocation: false
allowed-tools: ["Read", "Grep", "Glob"]
argument-hint: [代码路径或变更]
---
# Code Reviewer Skill
## 角色
你是一位资深的代码审查专家...
