GitHub Copilot 自定义智能体通过一个 .agent.md 文件定义。把文件放进仓库的 .github/agents 目录，在 YAML 区写名称、说明和允许的工具，在正文写角色、范围与交付规则；合并到默认分支后，再从 Copilot 的智能体选择器中调用并用受控任务验证。
创建前先确定一个窄角色
不要创建“什么都能做”的万能智能体。先选一个可验收任务，例如只补测试、只规划实现或只审查文档。角色至少写清：
- 允许处理哪些文件和任务。
- 禁止修改哪些内容。
- 可以使用哪些工具。
- 完成后必须提交哪些证据。
下面以“测试规划员”为教学示例，它只读代码并给测试计划，不直接编辑生产文件。
建立智能体文件
- 在仓库创建
.github/agents/test-planner.agent.md。 - 填写 YAML frontmatter；文件名使用官方允许的字母、数字、点、横线和下划线。
- 在 YAML 下写清行为指令。
---
name: test-planner
description: 只分析测试缺口并输出可执行计划，不修改代码
tools: ["read", "search"]
---
你是本仓库的测试规划员。
先读取现有测试约定，再列出缺口、输入、预期结果和建议命令。
不要修改文件，不要声称运行了未执行的命令。
结尾必须列出引用文件和仍需人工确认的问题。官方说明，如果省略 tools，智能体会获得所有可用工具。对窄任务显式限制工具更容易审查；具体工具名仍应以当前官方配置参考为准。
提交并让 Copilot 识别
- 检查 YAML 缩进、文件扩展名和目录。
- 把文件提交到仓库，并按团队流程合并到默认分支。
- 回到 GitHub 的 agents 页面或支持自定义智能体的入口，必要时刷新。
- 从下拉列表选择
test-planner，不要默认它已经生效。
GitHub 网页也可能提供“Create an agent”入口并生成模板，但可见性受套餐、权限和组织策略影响；手工文件结构更便于版本审查。
用一个只读任务验证
请分析 src/validator.py 与 tests/test_validator.py。
只输出测试缺口和建议命令，不修改文件。
每项缺口写明输入、预期结果及引用位置。验证成功需要同时满足：选择器显示正确智能体；回答遵守只读范围；引用文件真实存在；没有声称执行未运行的命令；Git diff 为空。若出现文件修改，立即停止并检查工具配置和指令。
常见失败与排查
| 现象 | 检查项 |
|---|---|
| 选择器看不到智能体 | 文件是否进入默认分支、目录和后缀是否正确、当前入口是否支持 |
| 配置无法解析 | YAML 分隔线、缩进、名称和工具字段 |
| 权限过大 | 是否省略 tools，或误加入 edit、终端和 MCP 工具 |
| 行为偏离角色 | 正文是否写明禁止项、输出格式和停止条件 |
本文没有在真实仓库创建或调用该智能体，示例只用于说明结构。组织级和企业级智能体目录、策略及可用工具可能不同。
官方来源
文件位置、frontmatter、工具与默认分支流程参考 GitHub 官方的 Creating custom agents；字段细节见 Custom agents configuration。资料核验日期：2026 年 10 月 1 日。
Ai菜鸟网。发布者：AI小管家，转载请注明出处：https://www.alyyhw.com/32846.html
