当一个项目中有高度专业化的任务类型——安全审计、数据库迁移、文档生成——可以为每种任务创建专属 Custom Agent，给它独立的指令集和工具权限。主代理按需调用，保持上下文干净。用 /agent-name 触发，或在 Prompt 中描述任务类型让 Copilot 自动选择。

GitHub Copilot CLI 自定义代理：为专项任务创建专属 AI 角色

什么是自定义代理

自定义代理（Custom Agents）是 Copilot CLI 中的专项 AI 角色：你定义一个代理的名称、专长领域、行为指令，Copilot 在处理相关任务时会激活对应的代理，以它的"视角"来工作。

为什么需要自定义代理：

• 主代理的上下文会随任务积累变得臃肿
• 专项任务（安全审计、测试生成）有独特的规范和工具需求
• 不同代理可以有不同的工具权限（安全审计代理只允许读文件，不允许写文件）

创建自定义代理

方法一：交互式创建

在 Copilot CLI 中使用 /agent 命令，按提示填写：

1. 代理名称（如 security-auditor）
2. 代理的专长描述（何时使用这个代理）
3. 具体的行为指令（代理应该怎么工作）

方法二：手动创建文件

在以下位置创建 .agent.md 文件：

项目级（可提交到 Git，团队共享）：

.github/agents/security-auditor.agent.md

个人级（本机所有项目可用）：

~/.copilot/agents/security-auditor.agent.md

如果两个位置都有同名代理，个人目录中的优先。

代理文件格式

---
name: security-auditor
description: 专注于代码安全审查的代理。当用户提到安全审计、漏洞检测、OWASP 检查时使用。
---

# Security Auditor

你是一位专注于 Web 应用安全的代码审查专家。

## 职责范围

- 检查 SQL 注入、XSS、CSRF 等 OWASP Top 10 漏洞
- 分析认证和授权逻辑的安全性
- 检查密钥和敏感信息的处理方式
- 评估输入验证和输出编码

## 工作原则

- 只读取文件，不修改任何代码（由用户决定是否采纳建议）
- 对每个发现的问题，说明：风险等级（HIGH/MEDIUM/LOW）、问题位置、修复建议
- 不误报——只报告有明确风险证据的问题

frontmatter 字段说明：

字段	必须	说明
name	✅	代理标识符，小写 + 连字符
description	✅	描述代理的专长和触发时机

使用自定义代理

方式一：显式调用

/security-auditor 检查 src/auth/ 目录下的所有认证逻辑

方式二：命令行参数

copilot --agent security-auditor --prompt "Check src/app/validator.go for security issues"

方式三：自动匹配

在 Prompt 中包含代理专长相关的关键词，Copilot 自动选择最合适的代理：

帮我做一个安全审计，看看登录模块有没有漏洞

如果 security-auditor 的 description 写得够清晰，Copilot 会自动使用它。

典型使用场景

代理名称	专长	典型触发
security-auditor	OWASP 安全审查	"检查这里有没有漏洞"
db-migrator	数据库 Schema 迁移	"帮我写迁移脚本"
test-generator	测试用例生成	"给这个函数写测试"
api-documenter	API 文档生成	"生成 OpenAPI 文档"

与 Skills 的区别

	Custom Agents	Skills
独立程度	有独立的指令集和身份	注入到主代理的上下文中
适合内容	有明确任务边界的专项工作	特定框架/工作流的知识
上下文隔离	是（主代理委托给子代理）	否（合并到主代理）

常见问题

Q: 一个 Copilot CLI 会话中可以使用多个自定义代理吗？

A: 可以。主代理可以在同一个会话中先后调用不同的代理处理不同类型的任务。每个代理只处理自己专长范围内的部分。

Q: 代理文件中能限制工具权限吗？

A: 可以在代理的 instructions 中说明不允许使用的操作（如"不修改任何文件"），但更底层的工具权限控制需要通过 CLI 参数（--allow-tool）实现。

Q: 如何测试新创建的代理？

A: 创建后，在 Prompt 中直接用 /agent-name 调用，看代理是否按预期的方式响应。如果没有激活，检查 description 字段是否包含足够清晰的触发关键词。