云端 Agent 配置参考

Agent profile 由 YAML frontmatter 和 Markdown 提示正文组成。以下按 GitHub 的 Custom agents 配置参考整理，CLI 独有模型策略等字段另见CLI Agent 配置。

Frontmatter 字段

字段	规则
description	必填字符串，说明用途和能力
name	可选显示名；默认使用文件名
target	vscode 或 github-copilot；省略时用于两类环境
tools	YAML 字符串数组或逗号分隔字符串；省略时所有工具可用
disable-model-invocation	默认 false；true 时不允许按任务上下文自动调用，需手动选择
user-invocable	默认 true；false 时不能手动选择，只能通过程序方式调用
infer	已弃用，使用上面两个调用控制字段替代
mcp-servers	此角色的 MCP 配置；IDE Custom agents 不使用
metadata	字符串键值注释；IDE Custom agents 不使用
model	参考列为模型字段，省略时继承默认模型；不同入口支持需单独核实

disable-model-invocation: true 相当于旧 infer: false；两者同时存在时，前者优先。不要把“不能由用户选择”和“不能被自动选择”混成一个开关。

创建教程只在 IDE 使用步骤中明确介绍 model，配置参考则将其列入通用字段。云端任务的可靠选择入口仍见模型选择，不能仅凭 profile 接受字符串就保证覆盖任意云端入口的模型。

云端忽略 IDE 的 argument-hint 与 handoffs。正文最多 30,000 字符。

工具列表

配置	结果
不写 tools 或写 ["*"]	所有可用工具，包括 MCP
tools: []	禁用所有工具
指定工具列表	仅提供这些工具或别名对应的工具
some-mcp-server/some-tool	指定某服务器的一个工具
some-mcp-server/*	指定某服务器全部工具

无法识别的工具名称会被忽略，不会因为保留了其他产品的工具名就自动获得该能力。

云端工具别名

别名不区分大小写。

主别名	兼容名称	云端用途
execute	shell、Bash、powershell	对应操作系统的 Shell 工具
read	Read、NotebookRead	读取文件，映射为 view
edit	Edit、MultiEdit、Write、NotebookEdit	编辑工具，具体参数随工具而异
search	Grep、Glob	搜索文件或文本
agent	custom-agent、Task	调用其他 custom agent
web	WebSearch、WebFetch	参考明确当前不适用于 cloud agent
todo	TodoWrite	当前不支持 cloud agent

内置 MCP 可以用 github/*、github/工具名、playwright/* 或 playwright/工具名 引用。工具可见性仍受到服务器配置和凭据范围约束。

去重与版本

角色按去掉 .md 或 .agent.md 后缀的文件名去重，不按显示名 name 去重。相同标识的优先顺序是仓库级高于组织级，组织级高于企业级。

版本以 profile 的 commit SHA 为基础；新任务用所选仓库和分支的最新版本，同一 PR 后续交互沿用开始时的版本。修改角色后应创建新测试任务验证，见测试与发布。