自定义 Agent 是通过 Markdown 文件定义的专精版 Copilot，可以针对团队的开发流程和代码规范进行定制。在仓库的 .github/agents/ 目录中创建 .md 文件，定义 Agent 的名称、描述和行为提示，即可在 GitHub 网站、IDE 和 Copilot CLI 中调用。

GitHub Copilot 自定义 Agent：用 Markdown 定义专精助手

什么是自定义 Agent

自定义 Agent 是你根据团队需求定制的 Copilot 助手变体。与通用 Copilot 不同，自定义 Agent：

• 有专注的领域（如"只做代码审查"、"只生成 README"）
• 携带你定义的上下文和规则
• 可以限定使用特定工具
• 在团队中共享，所有成员都能调用

Agent Profile 文件格式

在仓库的 .github/agents/ 目录中创建 .md 文件：

---
name: readme-creator
description: 专门创建和改进 README 文档的 Agent
---
你是一个文档专家，专注于编写清晰、完整的 README 文件。

遵循以下原则：
- 始终包含：项目简介、安装方法、使用示例、贡献指南
- 使用中文（除非代码库主要是英文项目）
- 为命令行工具提供完整的命令示例
- 对 API 项目提供接口文档结构

回答时先了解项目类型，再生成适合该类型的 README 模板。

Frontmatter 字段说明

字段	必填	说明
name	是	Agent 的唯一标识符，用于在 CLI 中调用
description	是	Agent 的用途描述，帮助用户选择正确的 Agent
tools	否	限定 Agent 可使用的工具列表

指定可用工具

---
name: code-reviewer
description: 专注于安全审查的 Agent
tools:
  - read_file
  - list_directory
  # 不包含 write_file，确保 Agent 只读不写
---
你是一个安全专家，专门审查代码中的安全漏洞...

存放位置

目录	适用范围
.github/agents/	该仓库的所有协作者
组织 .github-private 仓库的 agents/	整个组织的成员

在哪里使用自定义 Agent

创建后，自定义 Agent 可以在以下地方使用：

• GitHub 网站：在 GitHub Copilot Chat 中选择 Agent
• VS Code：在 Copilot Chat 中通过 @agent-name 调用
• JetBrains IDE：同上（公开预览阶段）
• Copilot CLI：copilot chat --agent readme-creator "帮我改进这个 README"

最佳实践

一个 Agent 做一件事：专精 Agent 比通用 Agent 效果好。与其创建一个"能做所有事"的 Agent，不如创建多个各有侧重的 Agent。

描述要清晰：description 字段是用户选择 Agent 的依据，要直接说明"这个 Agent 解决什么问题"。

提示中写规则不写流程：告诉 Agent"遵守什么标准"，而不是"按什么步骤做"——前者更灵活，适应不同输入。

常见问题

Q: 自定义 Agent 和仓库的 custom instructions（.github/copilot-instructions.md）有什么区别？

A: Custom instructions 对所有 Copilot 对话全局生效，影响所有请求；自定义 Agent 是按需调用的专用助手，只有明确指定时才会应用。两者可以配合使用——custom instructions 设定全局规范，Agent 提供专项能力。

Q: 一个仓库可以有多少个自定义 Agent？

A: 目前没有明确限制。实践中建议控制在 5-10 个，太多会让团队成员不知道该用哪个。

Q: 能不能在 Agent prompt 中引用其他文件内容？

A: 目前 Agent profile 文件本身不支持 @include 等文件引用语法。如果需要共享提示片段，可以在多个 Agent 文件中手动维护相同的内容。