一、什么是 Custom Agent对于刚接触 AI 工具的程序员来说首先要理解一个核心概念Custom Agent自定义代理是什么。简单来说Custom Agent 是 GitHub Copilot 的一个“角色切换”功能。想象一下你有一个全能助理他什么都能做一点但不够专业。Custom Agent 则允许你为 Copilot 创建多个“专业角色”——比如专门写文档的docs-agent、专门写测试的test-agent、专门做安全审查的security-agent。每个 Agent 都有自己的“性格”、专业领域、允许使用的工具以及绝对不能碰的边界。每个 Custom Agent 用一个*.agent.md文件来定义存放在.github/agents/目录下。当你在 Copilot Chat 中通过下拉菜单选择一个 Agent或者通过/agent命令调用它时Copilot 就会按照这个文件的配置来“扮演”那个角色为你工作。 对于程序员来说Custom Agent 就是为 AI 助手配置一个“函数签名”——你定义输入提示词、输出行为规范以及权限可用工具。区别在于这个“函数”是由 LLM 执行的你是在用自然语言编程。配置层级说明自定义代理可以在多个层级进行配置Repository 级别.github/agents/*.agent.md仅对该仓库生效Organization 级别agents/*.agent.md配合 GitHub.com coding agent 使用对整个组织生效Personal 级别~/.copilot/agents/*.agent.md对当前用户本地生效二、agent.md 的文件结构一个标准的*.agent.md文件由两部分组成--- [YAML Frontmatter 区域] --- [Markdown 指令内容区域]具体来说YAML Frontmatter用三个短横线---包裹的结构化元数据定义 Agent 的基本属性比如名称、描述、权限等Markdown 内容普通的 Markdown 格式用自然语言详细描述 Agent 的行为、专业领域、操作指南和约束三、Frontmatter 字段详解Frontmatter 是每个agent.md文件的开头部分用 YAML 格式编写。下面逐一解释每个字段的用途和配置方法。3.1 name可选推荐配置属性说明类型string用途Agent 在界面中显示的名称默认值如果省略使用文件名不含 .agent.md作为标识和显示名称示例name:Documentation Agent 实践建议为了在编程调用时方便建议使用小写字母和连字符命名文件例如test-agent.agent.md。name字段则可以使用更易读的显示名称。3.2 description必需属性说明类型string用途描述 Agent 的目的和能力长度建议10-1024 字符这是最重要的字段之一。Copilot 根据这个描述来判断是否应该使用这个 Agent。描述应当清晰说明Agent 的核心职责是什么何时应该使用它它擅长什么示例description:Security expert specializing in code review. Use me when you need to check code for vulnerabilities including secret exposure, XSS, SQL injection, and authentication bypass issues.为什么要写清楚这个字段Copilot 的运行时runtime会根据用户请求的描述自动判断是否与某个 Agent 的专业领域匹配然后选择是否把这个任务委托给该 Agent。如果你的描述太模糊Copilot 可能不会“认出”你的 Agent 适合某项任务。 对于程序员来说可以把description理解为一个“路由标签”——Copilot 用它来做意图匹配和任务分发。写得太模糊就像函数命名不清晰导致别人不会调用它。3.3 infer可选属性说明类型boolean用途控制 Copilot 是否可以根据任务上下文自动使用这个 Agent默认值true如果不设置设为trueCopilot 会自动判断任务是否适合这个 Agent如果适合就自动调用它设为false用户必须手动从下拉菜单中选择这个 AgentCopilot 不会自动选择它示例infer:false何时用false如果你创建了一个专门用于某个特殊流程的 Agent例如“把旧的 API 调用迁移到新版本”你可能不希望 Copilot 在其他“看起来类似”的场景中自动使用它——因为那个 Agent 包含的 prompt 可能对普通任务来说过于庞大或具有破坏性。这时候就可以设置infer: false让用户手动选择使用。3.4 tools可选属性说明类型string 或 string[]用途指定该 Agent 可以使用的工具列表默认值如果不设置默认允许使用所有可用工具配置方式使用所有工具省略tools属性或使用tools: [*]指定特定工具提供一个工具名称列表例如tools: [read, edit, search]常见工具别名read读取文件内容edit编辑/修改文件search搜索代码库shell执行 Shell 命令grep、glob、view代码搜索和查看示例# 只允许读取和搜索不允许修改tools:[read,search,grep,glob]或者作为 YAML 数组格式tools:-read-search-view⚠️ 重要建议对于只负责审查和评估的 Agent如安全审查器、代码审查器应当限制 tools 为只读工具如read、search、grep绝对不要包含edit或shell以避免意外修改代码。3.5 target可选属性说明类型string用途指定 Agent 的目标环境可选值vscode、github-copilot默认值两者都支持如果不设置这个字段让一个 Agent 在不同环境下有不同的行为表现。例如你可能希望在 VS Code 中这个 Agent 的行为和在 GitHub.com 上的行为略有不同。3.6 mcp-servers可选属性说明类型object用途配置 Agent 可以使用的外部 MCP 服务器工具MCPModel Context Protocol是一种扩展协议允许 Agent 访问额外的外部工具和数据源比如数据库、CI/CD 系统、代码审查工具等。示例mcp-servers:terraform:type:localcommand:dockerargs:[run,-i,--rm,hashicorp/terraform-mcp-server:latest]tools:[*]这个字段对大多数新手来说可以先放在一边等需要接入外部系统时再深入了解。四、Markdown 指令内容Frontmatter 下方的 Markdown 内容是 Agent 的核心——这是你用自然语言“编程” AI 行为的地方。从大量实际案例的研究来看好的 Agent 指令应该包含以下几个方面4.1 明确角色和职责不要说“你是一个乐于助人的助手”这样空泛的话而要具体说明 Agent 的角色“你是一位专门负责测试的工程师。你的职责是阅读代码并为 React 组件编写单元测试。”4.2 提供具体命令把相关的可执行命令放在显眼的位置写明具体参数npm test --coveragepytest -v -m not slowruff check .4.3 用代码示例代替文字描述一段真实的代码示例胜过三段的解释文字好的代码风格示例// 使用语义化变量名constisLoadingref(false);constuserProfilecomputed(()...);4.4 明确边界告诉 Agent 绝对不能碰什么绝对不能修改secrets/目录绝对不能访问.env文件绝对不能向生产环境配置文件写入内容⚠️ 安全提示“Never commit secrets” 是分析超过 2,500 个仓库后发现的最常见且最有用的约束。务必让 Agent 明确这一点4.5 覆盖六大核心领域一个完整的 Agent 指令应该覆盖命令如何构建、测试等测试测试框架和运行方式项目结构代码、文档、测试等目录的用途代码风格命名约定、格式化要求等Git 工作流分支策略、提交信息格式等边界绝对不能操作的内容五、完整的 ask.agent.md 示例假设我们要创建一个专门用于回答代码问题的 Agent类似“问答助手”它的职责是读取代码并回答问题但绝不能修改任何文件。--- name: Code QA Assistant description: Specialist in answering questions about codebases. Use me when you have questions about how code works, need to understand implementation details, or want to explore the codebase. tools: [read, grep, glob, search] infer: true target: github-copilot --- ## Your Role You are a code understanding specialist. Your job is to read and analyze code, then answer questions clearly and accurately. - You are fluent in TypeScript, Python, Go, and Java - You explain concepts for developers of all levels - You focus on clarity and actionable insights ## Project Knowledge - **Tech Stack:** React 18 with TypeScript, Node.js 20, PostgreSQL - **Key Dependencies:** Next.js 14, Prisma ORM, Tailwind CSS - **Test Framework:** Jest React Testing Library ## File Structure - src/ – Application source code (you READ from here) - tests/ – Unit and integration tests (reference for expected behavior) - docs/ – Documentation (you can read but not edit) ## Commands for Context - Build: npm run build - Type check: npm run type-check - Run tests: npm test - Lint: npm run lint ## Rules ✅ **You SHOULD:** - Read files from src/ to understand implementation - Search for patterns using grep - Explain what the code does and why - Cite specific file paths and line numbers when answering ❌ **You MUST NOT:** - Edit, create, or delete any files - Run any shell commands - Access .env or secrets files - Commit any changes ## Answer Format When answering, always include: 1. A direct answer to the question 2. Relevant code snippets (with paths) 3. Explanation of how the code works 4. Links to related files if applicable六、补充说明AGENTS.md vs. agent.md在阅读相关资料时你会遇到两个容易混淆的概念概念文件位置用途Custom Agent.agent.md.github/agents/*.agent.md创建专门的 AI“角色”需要在界面中手动选择或自动推断调用AGENTS.md项目根目录为 AI 提供通用项目上下文类似项目 README所有AI 工具Copilot、Claude、Gemini都会自动读取简而言之Custom Agent 专业的“员工角色”AGENTS.md 给员工的“通用工作指南”两者功能不同但可以配合使用。七、动手实践现在你已经了解了agent.md的基本结构可以尝试以下步骤在你的项目根目录创建.github/agents/文件夹创建一个ask.agent.md文件根据你的项目技术栈填充 content在 VS Code 的 Copilot Chat 中选择你的 Agent尝试提问观察 Agent 的行为是否符合预期下一节我们将介绍instructions.md的配置——它们为 AI 提供按文件类型应用的具体编码规范与这里讲解的 Agent 概念形成互补。 参考资料GitHub Docs: About custom agentsGitHub Docs: Configuración de agentes personalizadosGitHub Blog: How to write a great agents.md: Lessons from over 2,500 repositories