用 Meta-Agent 批量生成 Claude Code 子代理：.claude/agents/meta-agent.md 深度拆解与实战指南

本文以本仓库 .claude/agents/meta-agent.md 为绝对核心，完整拆解这个"生成子代理的子代理"：它的 frontmatter 配置、十大工作流步骤、标准输出模板，并结合仓库内 .claude/agents/ 下真实产出的 hello-world-agent、work-completion-summary、crypto 系列、team 系列等 agent 文件，讲清如何把它接入自己的 Claude Code 工作流，实现"一句话生成一个可立即委托的专用子代理"。读完本文，你将掌握 sub-agent 文件的标准结构、description 委托触发机制、工具最小化原则与系统提示词写法，并能够基于此模式自定义自己的 meta-agent。

一、Meta-Agent 是什么：为 Claude Code 编写子代理的"代理建筑师"

Claude Code 的 sub-agent 机制允许你为特定任务定义专用 AI 助手：每个子代理拥有独立的上下文窗口、自定义系统提示词、受限的工具集和独立的权限模型。官方文档将其价值概括为五点——保留主对话上下文（把探索与实现工作隔离出去）、强制约束（限制子代理可用的工具）、跨项目复用配置、按领域专注行为、以及通过将任务路由给更快更廉价的模型（如 Haiku）来控制成本。

而本仓库 .claude/agents/meta-agent.md 定义的是一个特殊角色：它本身就是一个用于"生成新子代理配置文件"的子代理。其 frontmatter 中的描述写得很直白：

"Generates a new, complete Claude Code sub-agent configuration file from a user's description. Use this to create new agents. Use this Proactively when the user asks you to create a new sub agent."

也就是说，当你在 Claude Code 中说"帮我创建一个新子代理"时，主代理会把这个任务自动委托给 meta-agent；meta-agent 依据你的描述，结合最新官方文档与可用工具清单，产出一个结构完整、立即可用的 Markdown 配置文件并写入 .claude/agents/<generated-agent-name>.md。这是 README 中所说的"agent that builds agents"，是规模化建设代理团队的"乘数器"：与其逐个手写子代理，不如让代理去生成代理。

二、Frontmatter 解剖：meta-agent 自身的配置逐字段解读

meta-agent 文件头部是标准 YAML frontmatter，我们逐字段分析其设计意图，并与官方支持的字段体系对照。

---
name: meta-agent
description: Generates a new, complete Claude Code sub-agent configuration file from a user's description. Use this to create new agents. Use this Proactively when the user asks you to create a new sub agent.
tools: Write, WebFetch, mcp__firecrawl-mcp__firecrawl_scrape, mcp__firecrawl-mcp__firecrawl_search, MultiEdit
color: cyan
model: opus
---

字段	值	作用与设计意图
name	meta-agent	唯一标识，小写字母与连字符（kebab-case）。主代理与 /agents 界面都以此引用它。
description	见上	委托触发点。主代理依据该描述判断"何时把任务交给此子代理"。这里同时使用了动作导向措辞（"Generates..."）和触发关键词（"Use this Proactively when..."），这正是官方文档推荐的让自动委托更积极的写法。
tools	Write, WebFetch, mcp__firecrawl-mcp__firecrawl_scrape, mcp__firecrawl-mcp__firecrawl_search, MultiEdit	最小工具集：Write（写新 agent 文件）、MultiEdit（编辑既有配置）、WebFetch（抓取官方文档）、两个 Firecrawl MCP 工具（网页抓取与搜索，用于获取最新文档与工具清单）。刻意不授予 Bash、Read 等非必需工具，体现"只给完成任务所需的最小权限"。
color	cyan	终端 UI 中识别该子代理的背景色。可选值：red、blue、green、yellow、purple、orange、pink、cyan。
model	opus	该子代理运行所用的模型别名。agent 架构设计属于高推理需求任务，故选用能力最强的 opus。

与官方字段体系的对照

meta-agent 只用到了基础字段。根据仓库存档的官方文档（ai_docs/claude_code_subagents_docs.md），完整 frontmatter 支持以下字段：

字段	必填	说明
name	是	小写字母与连字符的唯一标识
description	是	描述主代理应在何时委托给该子代理
tools	否	允许使用的工具白名单；省略则继承主对话全部工具（含 MCP 工具）
disallowedTools	否	黑名单，从继承或指定的列表中移除的工具
model	否	sonnet、opus、haiku 或 inherit（默认 inherit，跟随主对话模型）
permissionMode	否	default、acceptEdits、dontAsk、bypassPermissions、plan
skills	否	启动时注入子代理上下文的技能（完整内容注入，而非仅可调用）
hooks	否	作用于该子代理生命周期的事件钩子

仓库内 team/builder.md 就示范了 hooks 字段的用法：它在 PostToolUse 匹配 Write|Edit 事件，触发 ruff_validator.py 与 ty_validator.py 做代码质量校验。这意味着你让 meta-agent 生成的子代理，同样可以带上 hooks 来获得"写完即校验"的确定性能力。

三、十大工作流步骤：meta-agent 生成新子代理的完整管线

meta-agent 的正文 Instructions 定义了十个编号步骤，这是它区别于普通 prompt 的核心——它不是让 Claude"随便写写"，而是规定了一条可复现的流水线。

步骤 0：先获取最新官方文档

Scrape the Claude Code sub-agent feature to get the latest documentation（抓取子代理功能最新文档）以及可用工具清单。

meta-agent 被授予了 WebFetch 与 Firecrawl MCP 工具，正是为此。这一设计让它"活在当下"：Claude Code 的功能在持续演进，直接抓取最新文档能避免生成过时的 frontmatter 字段或工具名。仓库中的 ai_docs/claude_code_subagents_docs.md 与 ai_docs/legacy/anthropic_docs_subagents.md 是此类文档的本地快照，可视为该步骤的离线参照物。

步骤 1：分析输入

仔细分析用户 prompt，理解新代理的目的（purpose）、主要任务（primary tasks）与领域（domain）。这是后续所有决策的依据。

步骤 2：设计名称

为代理设计一个简洁、有描述性的 kebab-case 名称，例如 dependency-manager、api-tester。命名规范与 name 字段要求一致。

步骤 3：选择颜色

在 red、blue、green、yellow、purple、orange、pink、cyan 中选择一个，写入 frontmatter 的 color 字段。颜色用于在终端 UI 中快速区分正在运行的子代理。

步骤 4：编写委托描述

为 frontmatter 的 description 撰写清晰、动作导向的描述。这一步被明确标注为"critical for Claude's automatic delegation"（对自动委托至关重要）。推荐使用"Use proactively for..."或"Specialist for reviewing..."这类句式。仓库内两个真实例子：

• hello-world-agent.md："Simple greeting agent, use proactively when greeting the user. If they say 'hi claude' or 'hi cc' or 'hi claude code' use this agent."——同时给出了具体触发词。
• work-completion-summary.md："Proactively triggered when work is completed... If they say 'tts' or 'tts summary' or 'audio summary' use this agent."——用"如果他们说 X 就使用本代理"的方式精确锁定触发场景。

步骤 5：推断必要工具

根据任务描述确定最小工具集。文档给出的对照示例：代码审查者需要 Read, Grep, Glob，调试者可能需要 Read, Edit, Bash；如果要写新文件，就必须包含 Write。原则是"够用就好"——工具越少，越安全、越聚焦。meta-agent 自身的 tools 字段就是该原则的自证。

步骤 6：构建系统提示词

撰写新代理的主体内容（即系统提示词）。注意这里有一个贯穿整个仓库的关键认知：agent 文件正文是"系统提示词"而非"用户提示词"（详见 README 中 "Understanding Sub-Agents: System Prompts, Not User Prompts" 一节）。子代理只接收这份系统提示词加上工作目录等基本环境信息，不会收到 Claude Code 的完整系统提示词，所以必须把角色、职责、行为边界全部写清楚。

步骤 7：提供编号动作清单

为代理在被调用时提供一份编号列表或检查清单。例如 team/builder.md 的 Workflow：① 理解任务 → ② 执行 → ③ 验证 → ④ 完成（用 TaskUpdate 标记 completed）。

步骤 8：融入领域最佳实践

加入与代理所在领域相关的最佳实践。例如 llm-ai-agents-and-eng-research.md 要求丢弃一周前的旧内容、按分类组织调研结果；work-completion-summary.md 要求"每个词都必须有价值、禁止寒暄"。

步骤 9：定义输出结构

如适用，定义代理最终输出或反馈的结构。team/validator.md 给出了完整模板：Validation Report 包含任务、PASS/FAIL 状态、检查清单、审查文件、执行命令、摘要与发现的问题。

步骤 10：组装并输出

将以上所有组件组合成单个 Markdown 文件，严格遵守下方 Output Format，最终回复只能包含新 agent 文件的内容，并写入 .claude/agents/<generated-agent-name>.md 目录。

四、输出格式模板：每一行都值得注释

meta-agent 要求自身以严格的模板产出新代理文件，保证所有产物结构一致、可直接解析。模板原文：

---
name: <generated-agent-name>
description: <generated-action-oriented-description>
tools: <inferred-tool-1>, <inferred-tool-2>
model: haiku | sonnet | opus <default to sonnet unless otherwise specified>
---

# Purpose

You are a <role-definition-for-new-agent>.

## Instructions

When invoked, you must follow these steps:
1. <Step-by-step instructions for the new agent.>
2. <...>
3. <...>

**Best Practices:**
- <List of best practices relevant to the new agent's domain.>
- <...>

## Report / Response

Provide your final response in a clear and organized manner.

各占位符的语义与填充建议：

• name：步骤 2 生成的 kebab-case 名称。
• description：步骤 4 的动作导向委托描述。
• tools：步骤 5 推断的最小工具集，逗号分隔。
• model：三选一，默认 sonnet 除非有特殊理由（高难度任务选 opus，追求低成本低延迟选 haiku）。
• # Purpose：一句话角色定义（"You are a ..."），如 hello-world-agent.md 的 "You are a simple greeting agent."。
• ## Instructions：编号步骤清单 + Best Practices 列表，对应工作流步骤 7、8。
• ## Report / Response：输出结构说明，对应步骤 9。

仓库中 crypto/ 目录展示了该模板被规模化套用的结果：同一分析角色（如 crypto-coin-analyzer）被实例化为 -haiku、-sonnet、-opus 三个变体，仅模型不同——这正是"模板 + 参数化"批量生产代理的典型模式。

五、如何在你的项目中启用与使用 meta-agent

1. 放置位置与优先级

子代理按存储位置区分作用域与优先级（依据 ai_docs/claude_code_subagents_docs.md）：

位置	作用域	优先级
--agents CLI 标志（JSON）	当前会话	1（最高）
.claude/agents/（项目级）	当前项目	2
~/.claude/agents/（用户级）	所有项目	3
插件 agents/ 目录	启用插件的项目	4（最低）

meta-agent 放在项目级 .claude/agents/，仅当前项目可见；若要全局可用，复制到用户级目录即可。同名冲突时高优先级位置生效。子代理在会话启动时加载，手工新增文件后需重启会话或用 /agents 命令立即加载。

2. 两种调用方式

• 显式调用：直接对主代理说"用 meta-agent 创建一个新子代理"。
• 自动委托：由于 description 中含 "Use this Proactively when the user asks you to create a new sub agent"，主代理会在你表达"创建子代理"意图时自动委派。

使用示例（来自 README）：

"Build a new sub-agent that runs tests and fixes failures"

主代理识别该意图后交给 meta-agent，meta-agent 完成十大步骤并产出 test-runner 之类的完整配置文件。

3. 验证产物

生成后立即验证：在 Claude Code 中直接请求调用新代理（如 "Use the code-improver agent to suggest improvements in this project"），确认委托生效、工具权限符合预期、输出结构符合模板。也可以打开 /agents 界面检查新代理是否已加载、工具列表是否正确。

六、从源码看真实产物：meta-agent 工作流在仓库中的落地证据

仓库 .claude/agents/ 目录下的文件是 meta-agent 输出模板的活样本，可作为生成效果的验收基准：

• hello-world-agent.md：最简实现——frontmatter 仅 name、description、tools: WebSearch、color: green，正文含 Purpose 与 Report/Response 格式说明，与模板结构完全吻合。
• work-completion-summary.md：进阶形态——tools 直接引用了 ElevenLabs MCP 工具（mcp__ElevenLabs__text_to_speech、mcp__ElevenLabs__play_audio），正文有变量区（USER_NAME）、编号 Instructions、Best Practices 与 Report 结构。它证明了"生成代理"时可以精确挂载 MCP 工具。
• llm-ai-agents-and-eng-research.md：展示了"先跑 date 建立时间上下文"这类工程化步骤，以及结构化的 Report 输出（按 Major Developments / Language Models / Agents / Engineering Insights 分节）。
• crypto/ 系列：同一任务模板 × 三档模型的批量生产范例；其正文甚至是"Read and Execute: 某个 prompt 文件"这种间接引用模式，将提示词抽离到 .claude/commands/agent_prompts/ 复用。
• team/builder.md 与 team/validator.md：分别示范 hooks（PostToolUse 触发 Ruff/Ty 校验）与 disallowedTools（禁止 Write/Edit/NotebookEdit 的只读校验者）——这是"最小权限"原则在实践中的两极。

此外，README 中"Agent Storage & Organization"一节明确把 meta-agent 列为仓库 agent 目录的一员，并给出其使用示例，印证了该文件在项目中的定位是"生产代理的代理"。

七、设计高质量子代理的实践要点（meta-agent 应遵循的原则）

结合 meta-agent 的 Instructions 与官方文档的 best practices，以下是评估一个生成结果是否合格的核心标准：

1. 单一职责：每个子代理只擅长一件具体任务（如 code reviewer、debugger、data scientist），不要试图做一个"全能代理"。
2. 描述即委托契约：description 是主代理选择代理的依据，要写清"何时用、用于什么、怎么触发"；加入 "use proactively"、具体触发词（"if they say TTS"）能显著提升自动委托命中率。
3. 工具最小化：只授予任务必需的工具。审查用只读工具（Read/Grep/Glob），修复才加 Edit/Bash；要用 disallowedTools 明确禁止危险工具。meta-agent 自身不给 Bash 就是范例。
4. 系统提示词思维：记住子代理收到的是系统提示词，且每次调用都是全新上下文、无历史记忆。因此指令要自包含、显式给出背景，不要依赖用户原始对话。
5. 明确的输出契约：规定最终回复的结构（如 team/validator.md 的 Validation Report 模板），让结果可解析、可复核。
6. 模型按需选择：高推理任务（agent 架构设计）用 opus，均衡场景默认 sonnet，高频低成本场景用 haiku。
7. 版本控制与团队共享：项目级 agent 文件应纳入版本控制（本仓库即如此），让团队协作改进。

八、使用边界与注意事项

• 子代理无法再生成子代理：官方文档明确 subagents cannot spawn other subagents。meta-agent 之所以能"生成代理"，本质是它用 Write 工具写出配置文件并依赖用户/主代理在会话重启或 /agents 后加载，而非运行时动态创建子代理实例。
• 外部文档依赖：meta-agent 的步骤 0 依赖抓取官方文档获取最新字段；离线环境下该步骤会退化，此时可改用仓库内 ai_docs/claude_code_subagents_docs.md 这类本地快照作为替代信息源。
• 模型成本：meta-agent 固定 model: opus，每个生成任务都会消耗高阶模型额度；若生成需求频繁且简单，可考虑改为 sonnet 平衡成本。
• 手动校验产物：自动生成不等于自动正确。建议在真实任务中试运行新代理，检查工具权限与输出格式是否符合预期（参考 team/validator.md 的"builder 产出 → validator 校验"模式）。

九、延伸：把 meta-agent 接入更大的自动化体系

meta-agent 不是孤立的。在本仓库的体系中，它可以与三类机制协同：

• 与 Hooks 协同：生成的代理可携带 hooks 字段（如 builder 的 PostToolUse 校验），让质量保障从"prompt 软约束"升级为"确定性硬校验"。
• 与团队工作流协同：README 展示的 /plan_w_team 模式中，builder 实现、validator 校验、任务系统协调，meta-agent 可充当"按需扩充团队编制"的入口——需要新角色时就生成一个新代理文件。
• 与任务系统协同：builder/validator 都依赖 TaskGet/TaskUpdate 读取与回写任务状态，这说明 meta-agent 生成的代理也应考虑与 Task 工具的集成点，以融入多代理编排。

一句话总结：meta-agent 把"编写子代理配置"这一元工程能力交给了代理本身，配合标准模板与最小权限原则，它让你从"手写每个代理"进化为"描述即生产"，这正是 README 所强调的"Build the thing that builds the thing"的工程理念。