Copilot CLI 自定义代理（Custom Agents）让你把"专项 AI 角色"固化成可复用的配置文件：定义一次专注于文档的代理、专注于代码审查的代理、专注于测试编写的代理，之后每次需要都可以直接调用，不再重复写相同的上下文提示。

GitHub Copilot CLI 自定义代理：打造专项 AI 助手的完整指南

什么是自定义代理

自定义代理（Custom Agents）是 Copilot CLI 的专项配置版本——你定义一次特定领域的专家角色，之后可以直接调用，无需每次重新描述要求和约束。

类比 Claude Code 的 CLAUDE.md：自定义代理相当于为不同任务类型创建不同的"专项 CLAUDE.md"，每个代理有自己的职责范围、工具权限和行为准则。

核心优势：

• 把重复的上下文提示（"你是一个专注于 README 的文档专家，不要修改代码..."）写入一次
• 限制代理的权限范围，减少误操作风险
• 团队共享，每个人用同一套专项代理配置

Agent Profile 格式

自定义代理由 Markdown 文件（Agent Profile）定义，文件包含 YAML frontmatter：

---
name: readme-creator
description: 专门创建和改进 README 文档的代理
---

你是一个专注于文档的专家，只处理 README 文件和相关文档，不修改代码文件。

工作原则：
- 创建和更新 README.md，包含清晰的项目描述
- 按逻辑结构组织各节：概述、安装、使用、贡献指南
- 使用相对链接（如 `docs/CONTRIBUTING.md`）而非绝对 URL
- 为图片添加 alt text

frontmatter 字段说明：

字段	必填	说明
name	否	显示名称，省略时使用文件名
description	是	代理的用途和能力描述（用于自动匹配和显示）
tools	否	可使用的工具列表，默认允许所有工具
mcp-servers	否	内联 MCP Server 配置

配置位置

级别	路径	适用范围
仓库级	.github/agents/AGENT-NAME.md	当前仓库
组织/企业级	.github-private/agents/AGENT-NAME.md	组织内所有仓库

同一组织的成员自动可以访问组织级代理，无需每个仓库单独配置。

调用自定义代理

在 Copilot CLI 会话中：

@readme-creator 为这个项目创建一个完整的 README，包含安装和使用说明

或者通过 /delegate 命令：

/delegate @readme-creator 写一个 README.md

内置代理（Built-in Agents）

Copilot CLI 自带以下内置代理：

代理	说明
explore	轻量级代码库探索代理，只读不写，可与其他子代理并行运行
task	执行开发命令（测试、构建等）的任务代理
general-purpose	与主代理能力相同，提供独立上下文的通用代理
code-review	只审查已暂存/未暂存的修改和分支差异，报告真正重要的问题（Bug、安全漏洞、逻辑错误），不评论代码风格，不修改文件
research	技术研究专家，通过 /research 命令调用（不可直接 @调用）

explore 和 code-review 代理因为是只读的，特别适合在 /fleet 并行任务中使用，不会产生文件冲突。

自定义代理作为子代理运行

主代理可以将任务委托给自定义代理或内置代理，以独立上下文窗口运行：

1. 子代理专注于特定子任务，不污染主会话上下文
2. 多个子代理可以并行运行（如 explore + 多个 task 代理）
3. 主代理汇总所有子代理的结果

这是 /fleet 命令底层使用的机制。

工具权限控制

通过 tools 字段限制代理可以使用的工具：

---
name: safe-reviewer
description: 只读代码审查代理，不允许任何修改操作
tools:
  - read
  - search
  - shell(git diff)
  - shell(git log)
---

你是一个只读的代码审查者，只能读取文件和查看 Git 历史，不能进行任何修改...

这对于需要在 CI 环境或受限权限场景运行的代理特别有用。

常见问题

Q: 自定义代理和 CLAUDE.md 有什么区别？

A: CLAUDE.md（Claude Code）和自定义代理（Copilot CLI）都是"始终生效的上下文指令"，但自定义代理是角色化的——你可以创建多个不同职责的代理，按任务类型选择调用。CLAUDE.md 对所有任务一视同仁。

Q: 如何测试自定义代理是否工作正确？

A: 创建一个简单的测试任务，用 @agent-name 做 X 格式调用，检查代理是否遵循了配置文件中的约束（如只操作指定类型的文件）。

Q: 可以给自定义代理配置独立的 MCP Server 吗？

A: 可以，在 Agent Profile 的 frontmatter 中用 mcp-servers 字段配置该代理独享的 MCP Server，主代理的 MCP 配置不会传递给该代理（除非显式继承）。