custom-agent-definitions

自定义 Agent 定义

在 Claude Code 中定义和配置自定义 Agent 的专业知识。

完整的 YAML 示例（独立研究 Agent、只读探索器、完整安全审计员、插件布局、常见模式），请参阅 REFERENCE.md。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 agent-teams……
在 .claude/agents/ 中编写新的 .md Agent 定义文件	启动多个已定义的 Agent，让它们作为团队协作
配置单个 Agent 的 model、allowed-tools 或 context: fork	设置具有共享任务列表的负责人／队友架构
限制专用只读或写入受限 Agent 的工具访问权限	按顺序安排跨工作树的并行工作（参见 parallel-agent-dispatch）
编写定义单个 Agent 工作内容的系统提示词	审计现有 Agent 定义的安全性（参见 meta-audit）

核心概念

自定义 Agent 让你可以定义内置 Agent 类型（Explore、Plan、Bash 等）之外的专用 Agent 类型。每种类型都可以拥有自己的模型、工具和上下文配置。它们定义在 .claude/agents/ 或插件的 agents/ 目录中，采用 YAML 前置元数据和 Markdown 系统提示词：

---
name: my-custom-agent
description: What this agent does
model: sonnet
allowed-tools: Bash, Read, Grep, Glob
---

# Agent System Prompt

Instructions and context for the agent...

关键字段

上下文分叉

值	行为
fork	独立的上下文副本——Agent 可以看到父级历史记录，但更改不会影响父级
（默认）	Agent 与父级共享上下文，可以查看／修改对话状态

在探索性研究、并行调查和隔离实验中使用 fork。参见 REFERENCE.md → 独立研究 Agent。

工具访问权限（允许与禁止）

字段	用途	行为
allowed-tools	允许使用的工具白名单	Agent 只能使用这些工具
disallowedTools	禁止使用的工具黑名单	Agent 可以使用除这些工具以外的所有工具

只读 Agent、限制危险能力和进行沙箱隔离时，可使用 disallowedTools。两者可以组合使用——显式白名单加安全黑名单。 参见 REFERENCE.md → 只读探索器。

用于委派的 Agent 字段

agent 字段指定通过 Agent 工具委派时要使用的 Agent 类型，让命令和技能可以指定首选的 Agent 类型：

agent: security-auditor

Agent 配置字段参考

字段	类型	描述
name	string	Agent 标识符
description	string	Agent 的工作内容
model	string	要使用的模型（sonnet、opus）
context	string	上下文模式：fork 或默认模式
permissionMode	string	default、acceptEdits、dontAsk、bypassPermissions 或 plan
maxTurns	number	Agent 停止前可执行的 Agent 回合数上限
background	bool	设为 true 可始终在后台任务中运行
memory	string	持久记忆范围：user、project 或 local
skills	list	启动时预加载到 Agent 上下文中的技能名称
mcpServers	list	此 Agent 可用的 MCP 服务名称
tools	list	Agent 可使用的工具（位于 agents/ 目录时；技能中使用 allowed-tools）
disallowedTools	list	Agent 不可使用的工具
created / modified / reviewed	date	生命周期日期

最佳实践

1. 最小权限原则 — 仅授予 Agent 所需的工具。

2. 使用 context: fork 实现隔离 — 探索性工作不应污染主上下文。

3. 结合允许项和禁止项 — 明确的允许列表加上安全黑名单。

4. 清晰的描述 — 说明 Agent 的职责及其边界。

5. 模型选择 — 开发工作流使用 sonnet，深入推理和分析使用 opus。（关于在子 Agent 中使用 Opus 的指导，请参阅 .claude/rules/agent-and-tool-selection.md。）

6. 明确报告失败 — 被派遣的 Agent 遇到障碍时，必须在最终消息中说明，绝不能只用 Terminal. / Done. / Stopped. 这样的一词总结。遇到阻碍时，它应提交并推送进行中的工作、创建草稿 PR，并准确说明是什么阻止了它，以及哪些工具被拒绝。一词放弃与编排器眼中的成功无法区分，因此工作会被悄悄清理并丢失（issue #1422）。关于每份任务说明都必须包含的派遣提示词格式，请参阅 parallel-agent-dispatch →“大声报告失败约定”。

7. 只读扇出时优先选择不带 Skill 的 agentType — 只读取文件并输出结构化结果的 Agent 不应携带 Skill 工具。每个携带 Skill 的 Agent 在首次调用工具前都会承担约 25k 个 token 的 skill_listing + deferred_tools_delta 上下文开销，这可能导致以读取为主的扇出子 Agent 超出上下文窗口。改用精简的只读 Agent（例如 agents-plugin:review）。请参阅 parallel-agent-dispatch →“只读扇出使用不带 Skill 的 agentType” （issues #1549 / #1550）。

每项实践对应的完整 YAML 示例见 REFERENCE.md → 最佳实践片段。

快速参考

上下文模式

模式	隔离	用例
（默认）	共享	常规工作流
fork	隔离	研究、实验

工具限制模式

模式	字段
仅允许列表	allowed-tools: Tool1, Tool2
仅禁止列表	disallowedTools: Tool1, Tool2
组合使用	同时指定两个字段

相关内容

• REFERENCE.md — 完整的 YAML 示例和片段
• agent-teams — 通过隐式团队进行多 Agent 协调
• parallel-agent-dispatch — 工作树预检、范围预算、大声报告失败约定
• meta-audit — 审计现有 Agent 定义的安全性和完整性
• .claude/rules/agent-development.md — Agent 生命周期和字段语义