AI 摘要：本文分析了超过 2500 个公开仓库中的 agents.md 文件，归纳出优秀自定义代理（Custom Agent）的关键写法：让每个代理具备明确角色、具体命令、严格边界与真实示例。成功的代理不是“通用助手”，而是专职专家，如 @docs-agent 负责文档、 @test-agent 负责测试。掌握六个核心领域（命令、测试、项目结构、代码风格、Git 工作流、边界）即可写出高效 agent 文件。

1. 背景与概念
• GitHub 推出新特性：以 agents.md 文件定义自定义代理（Custom Agent），让 Copilot 从通用助手变成具备明确角色的团队成员。
• 每个代理文件定义 persona（角色设定）、技能栈 (tech stack)、可操作命令、代码风格、及禁止行为。

2. 从 2500+ 文件分析得到的经验
• 成功的 agents 明确任务（如 documentation、testing、security），而失败的往往太模糊。
• 要点总结：
• 早放命令：在文件开头就定义可执行命令（含参数/flag）。
• 示例优于解释：展示代码风格比写长篇说明更有效。
• 明确边界：清楚列出“能做”“需确认”“禁止”的操作。
• 标注技术栈：注明版本与依赖，如 “React 18 + TypeScript + Vite + Tailwind CSS”。
• 六大领域覆盖：commands、testing、project structure、code style、git workflow、boundaries。

3. 优秀 agents.md 示例解构 (@docs-agent)
• 文件结构：YAML frontmatter 描述 → 角色与任务 → 项目知识 → 可用命令 → 写作准则 → 三层边界（Always / Ask first / Never）
• 成功原因：具体 persona、可执行命令在前、展示项目知识、有实例代码、边界分层清晰。

4. 构建你的第一个 agent
• 建议从小而具体的任务开始，如编写函数文档、添加单元测试、修复 linter 报错。
• 组成要素：名称、描述、persona 定义。
• Copilot 可辅助生成初稿，用 IDE 编辑 .github/agents/test-agent.md 并微调。

5. 实用代理类型推荐（六类）

• @docs-agent：生成文档，读 src/ 写 docs/。
• @test-agent：编写测试，永不删除失败测试。
• @lint-agent：执行格式修复，仅限风格层面修改。
• @api-agent：搭建 API 接口，修改数据结构需批准。
• @dev-deploy-agent：仅部署到开发环境，操作需批准。
• @security-agent（隐含）：执行安全分析或代码扫描。

6. 模板与最佳实践
• Starter template 提供完整结构：frontmatter、persona、project knowledge、tools、standards、boundaries。
• 强调命名规范、风格示例与边界设置的重要性。

7. 结论与启示
• 优秀 agent ≠ 冗长 prompt，而是清晰角色手册 (operating manual)。
• 核心在于：明确 persona、具体命令、真实样例、明确定义边界。
• 通过迭代完善 agent，让 Copilot 团队协作更像真实开发团队。

The GitHub Blog

How to write a great agents.md: Lessons from over 2,500 repositories

Learn how to write effective agents.md files for GitHub Copilot with practical tips, real examples, and templates from analyzing 2,500+ repositories.