create-custom-agent

创建自定义 Agent

此技能可帮助你创建 VS Code 自定义 Agent 文件，为开发任务定义专用 AI 人设。自定义 Agent 可配置可用工具、提供专用指令，并通过交接串联起来。

适用场景

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

不适用场景

• 创建指令文件（请改用 .instructions.md）
• 创建可重复使用的提示词（请改用 .prompt.md）
• 修改现有 Agent（直接编辑文件）

输入

输入	必填	说明
Agent 名称	是	描述性名称（例如，planner、code-reviewer）
描述	是	在聊天中显示为占位文本的简短描述
用途／人设	是	Agent 扮演的角色以及应有的行为
工具	建议填写	Agent 可使用的工具或工具集列表
交接	可选	完成工作后切换到的下一步 Agent

工作流

步骤 1：创建 Agent 文件

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

agents/<agent-name>.agent.md

步骤 2：添加 YAML frontmatter

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

---
name: <agent-name>
description: <brief description for chat placeholder>
tools:
  - <tool-name>
  - <tool-set-name>
---

可用的 frontmatter 字段：

字段	必填	说明
name	否	显示名称（默认使用文件名）
description	是	在聊天输入框中显示的占位文本
argument-hint	否	引导用户交互的提示文本
tools	否	可用工具／工具集列表
agents	否	允许使用的子 Agent 列表（* 表示全部，[] 表示无）
model	否	AI 模型名称或按优先级排列的模型数组
handoffs	否	下一步 Agent 切换列表
user-invokable	否	是否在 Agent 下拉菜单中显示（默认：true）
disable-model-invocation	否	是否阻止子 Agent 调用（默认：false）
target	否	目标环境：vscode 或 github-copilot
mcp-servers	否	GitHub Copilot 目标的 MCP 服务配置

步骤 3：配置工具

指定 Agent 可以使用哪些工具：

tools:
  - search              # Built-in tool
  - fetch               # Built-in tool
  - codebase            # Tool set
  - myServer/*          # All tools from MCP server

常见工具模式：

• 只读 Agent：['search', 'fetch', 'codebase']
• 完整编辑 Agent：['*'] 或特定编辑工具
• 专用 Agent：精选特定工具

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

配置切换到其他 Agent 的方式：

handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Implement the plan outlined above.
    send: false
    model: GPT-5.2 (copilot)

交接字段：

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

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

使用 Markdown 添加 Agent 的行为指令：

You are a security-focused code reviewer. Your job is to:

1. Analyze code for security vulnerabilities
2. Check for common security anti-patterns
3. Suggest secure alternatives

## Guidelines

- Focus on OWASP Top 10 vulnerabilities
- Flag hardcoded secrets immediately
- Review authentication and authorization logic

## Reference other files

See [security guidelines](../security.md) for standards.

指令编写提示：

• 使用 Markdown 链接引用其他文件
• 使用 #tool:<tool-name> 语法引用工具
• 明确说明 Agent 的行为和限制

步骤 6：验证 Agent

确认 Agent 能正确加载：

1. 打开命令面板（Ctrl+Shift+P）
2. 运行 "Chat: New Custom Agent" 或检查 Agent 下拉菜单
3. 使用“诊断”视图（在聊天视图中单击右键）检查错误

模板

---
name: <agent-name>
description: <brief description for chat placeholder>
argument-hint: <optional hint for user input>
tools:
  - <tool-1>
  - <tool-2>
handoffs:
  - label: <button-text>
    agent: <target-agent>
    prompt: <pre-filled-prompt>
    send: false
---

# <Agent Title>

<One paragraph describing the agent's persona and purpose.>

## Role

<Describe the agent's specialized role and expertise.>

## Guidelines

- <Guideline 1>
- <Guideline 2>
- <Guideline 3>

## Workflow

1. <Step 1>
2. <Step 2>
3. <Step 3>

## Constraints

- <Constraint 1>
- <Constraint 2>

示例 Agent

规划 Agent

---
name: planner
description: Generate an implementation plan
tools:
  - search
  - fetch
  - codebase
handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Implement the plan above.
---

# Planning Agent

You are a solution architect. Generate detailed implementation plans.

## Guidelines

- Analyze requirements thoroughly before planning
- Break work into discrete, testable steps
- Identify dependencies and risks
- Do NOT make code changes

代码审查 Agent

---
name: code-reviewer
description: Review code for quality and security issues
tools:
  - search
  - codebase
---

# Code Review Agent

You are a senior engineer performing code review.

## Focus Areas

- Security vulnerabilities
- Performance concerns
- Code maintainability
- Test coverage gaps

## Output Format

Provide findings as:
1. **Critical**: Must fix before merge
2. **Warning**: Should address
3. **Suggestion**: Nice to have

验证清单

• 文件扩展名为 .agent.md
• 文件位于 agents/ 目录中
• YAML frontmatter 有效（缩进正确，没有语法错误）
• 描述不为空且足够明确
• 工具列表仅包含可用工具
• 交接 Agent 名称与现有 Agent 相符
• 指令清晰且可执行
• Agent 显示在 Agent 下拉菜单中

常见问题

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

参考资料

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