create-custom-agent

创建自定义代理

此技能帮助您创建 VS Code 自定义代理文件，为开发任务定义专用的 AI 角色。自定义代理配置可用的工具、提供专门的指令，并可通过交接进行链式协作。

使用场景

• 从头创建新的自定义代理
• 搭建带有正确 frontmatter 的 .agent.md 文件
• 为多步骤工作流设置代理间交接
• 为专用角色（如规划者、审查者等）配置工具限制
• 创建工作区共享或用户配置文件中的代理

不适用场景

• 创建指令文件（应使用 .instructions.md）
• 创建可复用提示（应使用 .prompt.md）
• 修改现有代理（直接编辑文件）

输入

输入	必填	描述
代理名称	是	代理的描述性名称（例如 planner、code-reviewer）
描述	是	在聊天中作为占位符文本显示的简短描述
目的/角色	是	代理扮演的角色及其行为方式
工具	推荐	代理可以使用的工具或工具集列表
交接	可选	完成工作后要转移到的下一步代理

工作流

步骤 1：创建代理文件

在 agents/ 目录中创建一个扩展名为 .agent.md 的文件：

agents/<agent-name>.agent.md

步骤 2：添加 YAML frontmatter

添加包含必填和可选字段的头部：

---
name: <agent-name>
description: <用于聊天占位符的简短描述>
tools:
  - <tool-name>
  - <tool-set-name>
---

可用的 frontmatter 字段：

字段	必填	描述
name	否	显示名称（默认为文件名）
description	是	在聊天输入框中显示的占位符文本
argument-hint	否	指导用户交互的提示文本
tools	否	可用工具/工具集列表
agents	否	允许的子代理列表（* 表示全部，[] 表示无）
model	否	AI 模型名称或按优先级排序的模型数组
handoffs	否	下一步代理交接列表
user-invokable	否	是否在代理下拉列表中显示（默认：true）
disable-model-invocation	否	是否禁止子代理调用（默认：false）
target	否	目标环境：vscode 或 github-copilot
mcp-servers	否	针对 GitHub Copilot 目标的 MCP 服务器配置

步骤 3：配置工具

指定代理可以使用的工具：

tools:
  - search              # 内置工具
  - fetch               # 内置工具
  - codebase            # 工具集
  - myServer/*          # MCP 服务器中的所有工具

常见工具模式：

• 只读代理：['search', 'fetch', 'codebase']
• 完全编辑代理：['*'] 或特定的编辑工具
• 专用代理：挑选特定工具

步骤 4：添加交接（可选）

配置到其他代理的转移：

handoffs:
  - label: 开始实施
    agent: implementation
    prompt: 实施上述计划。
    send: false
    model: GPT-5.2 (copilot)

交接字段：

• label：显示给用户的按钮文本
• agent：目标代理标识符
• prompt：为目标代理预填的提示
• send：自动提交提示（默认：false）
• model：交接时可选模型覆盖

步骤 5：编写代理指令（正文）

在 Markdown 中添加代理的行为指令：

您是一位专注于安全性的代码审查者。您的工作是：

1. 分析代码中的安全漏洞
2. 检查常见的安全反模式
3. 建议安全的替代方案

## 指南

- 关注 OWASP Top 10 漏洞
- 立即标记硬编码的机密信息
- 审查身份验证和授权逻辑

## 引用其他文件

参见 [安全指南](../security.md) 了解标准。

指令提示：

• 使用 Markdown 链接引用其他文件
• 使用 #tool:<tool-name> 语法引用工具
• 具体说明代理的行为和约束

步骤 6：验证代理

验证代理是否正确加载：

1. 打开命令面板（Ctrl+Shift+P）
2. 运行“聊天：新建自定义代理”或检查代理下拉列表
3. 使用“诊断”视图（在聊天视图中右键单击）检查错误

模板

---
name: <agent-name>
description: <用于聊天占位符的简短描述>
argument-hint: <用户输入的可选提示>
tools:
  - <tool-1>
  - <tool-2>
handoffs:
  - label: <按钮文本>
    agent: <目标代理>
    prompt: <预填提示>
    send: false
---

# <代理标题>

<描述代理角色和目的的一段话。>

## 角色

<描述代理的专门角色和专长。>

## 指南

- <指南 1>
- <指南 2>
- <指南 3>

## 工作流

1. <步骤 1>
2. <步骤 2>
3. <步骤 3>

## 约束

- <约束 1>
- <约束 2>

示例代理

规划代理

---
name: planner
description: 生成实施计划
tools:
  - search
  - fetch
  - codebase
handoffs:
  - label: 开始实施
    agent: implementation
    prompt: 实施上述计划。
---

# 规划代理

您是一位解决方案架构师。生成详细的实施计划。

## 指南

- 在规划前彻底分析需求
- 将工作分解为离散、可测试的步骤
- 识别依赖和风险
- 不要修改代码

代码审查代理

---
name: code-reviewer
description: 审查代码质量和安全问题
tools:
  - search
  - codebase
---

# 代码审查代理

您是一位进行代码审查的高级工程师。

## 重点领域

- 安全漏洞
- 性能问题
- 代码可维护性
- 测试覆盖缺口

## 输出格式

按以下方式提供发现：
1. **严重**：合并前必须修复
2. **警告**：应该处理
3. **建议**：最好有

验证清单

• [ ] 文件扩展名为 .agent.md
• [ ] 文件位于 agents/ 目录中
• [ ] YAML frontmatter 有效（缩进正确，无语法错误）
• [ ] 描述非空且具有描述性
• [ ] 工具列表仅包含可用工具
• [ ] 交接代理名称与现有代理匹配
• [ ] 指令清晰且可操作
• [ ] 代理出现在代理下拉列表中

常见陷阱

陷阱	解决方案
代理未出现在下拉列表中	检查文件是否位于 agents/ 目录且扩展名为 .agent.md
YAML 语法错误	验证 frontmatter 的缩进和引号
工具不工作	验证工具名称是否存在；不可用的工具会被忽略
交接不显示	目标代理必须存在；检查代理标识符
指令过于模糊	具体说明角色、约束和工作流
代理意外作为子代理被调用	设置 disable-model-invocation: true
希望代理仅作为子代理	设置 user-invokable: false

参考

• VS Code 自定义代理文档
• 聊天中的工具
• 自定义指令
• 提示文件