create-custom-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Custom Agent

创建自定义Agent

This skill helps you create VS Code custom agent files that define specialized AI personas for development tasks. Custom agents configure which tools are available, provide specialized instructions, and can chain together via handoffs.

该技能可帮助你创建VS Code自定义Agent文件，为开发任务定义专业的AI角色。自定义Agent可配置可用工具、提供专业指令，并能通过交接功能实现多Agent联动。

When to Use

适用场景

Creating a new custom agent from scratch
Scaffolding an
```
.agent.md
```
file with proper frontmatter
Setting up agent-to-agent handoffs for multi-step workflows
Configuring tool restrictions for specialized roles (planner, reviewer, etc.)
Creating workspace-shared or user-profile agents

从零开始创建新的自定义Agent
生成带有正确前置元数据的
```
.agent.md
```
文件
为多步骤工作流设置Agent间的交接
为特定角色（如规划师、审核员等）配置工具权限
创建工作区共享或用户专属的Agent

When Not to Use

不适用场景

Creating instruction files (use
```
.instructions.md
```
instead)
Creating reusable prompts (use
```
.prompt.md
```
instead)
Modifying existing agents (edit the file directly)

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

Inputs

输入参数

Input	Required	Description
Agent name	Yes	Descriptive name for the agent (e.g., `planner` , `code-reviewer` )
Description	Yes	Brief description shown as placeholder text in chat
Purpose/Persona	Yes	What role the agent plays and how it should behave
Tools	Recommended	List of tools or tool sets the agent can use
Handoffs	Optional	Next-step agents to transition to after completing work

输入项	是否必填	描述
Agent名称	是	Agent的描述性名称（例如： `planner` 、 `code-reviewer` ）
描述	是	聊天界面中显示的占位文本
角色/定位	是	Agent的角色定位及行为方式
工具	推荐	Agent可使用的工具或工具集列表
交接配置	可选	完成任务后可切换到的后续Agent

Workflow

操作流程

Step 1: Create the agent file

步骤1：创建Agent文件

Create a file with

.agent.md

extension in the

agents/

directory:

agents/<agent-name>.agent.md

在

agents/

目录下创建扩展名为

.agent.md

的文件：

agents/<agent-name>.agent.md

Step 2: Add YAML frontmatter

步骤2：添加YAML前置元数据

Add the header with required and optional fields:

yaml

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

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

yaml

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

Available frontmatter fields:

可用的前置元数据字段：

Field	Required	Description
`name`	No	Display name (defaults to filename)
`description`	Yes	Placeholder text shown in chat input
`argument-hint`	No	Hint text guiding user interaction
`tools`	No	List of available tools/tool sets
`agents`	No	List of allowed subagents ( `*` for all, `[]` for none)
`model`	No	AI model name or prioritized array of models
`handoffs`	No	List of next-step agent transitions
`user-invokable`	No	Show in agents dropdown (default: true)
`disable-model-invocation`	No	Prevent subagent invocation (default: false)
`target`	No	Target environment: `vscode` or `github-copilot`
`mcp-servers`	No	MCP server configs for GitHub Copilot target

字段	是否必填	描述
`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服务器配置

Step 3: Configure tools

步骤3：配置工具

Specify which tools the agent can use:

yaml

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

Common tool patterns:

Read-only agents:
```
['search', 'fetch', 'codebase']
```
Full editing agents:
```
['*']
```
or specific editing tools
Specialized agents: Cherry-pick specific tools

指定Agent可使用的工具：

yaml

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

常见工具配置模式：

只读Agent：
```
['search', 'fetch', 'codebase']
```
全编辑权限Agent：
```
['*']
```
或指定具体编辑工具
专业Agent：挑选特定工具

Step 4: Add handoffs (optional)

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

Configure transitions to other agents:

yaml

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

Handoff fields:

```
label
```
: Button text displayed to user
```
agent
```
: Target agent identifier
```
prompt
```
: Pre-filled prompt for target agent
```
send
```
: Auto-submit prompt (default: false)
```
model
```
: Optional model override for handoff

配置切换到其他Agent的规则：

yaml

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
```
：交接时可选的模型覆盖配置

Step 5: Write agent instructions (body)

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

Add the agent's behavior instructions in Markdown:

markdown

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

使用Markdown编写Agent的行为指令：

markdown

你是一名专注于安全的代码审核员。你的工作内容包括：

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

Guidelines

指导原则

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

重点关注OWASP Top 10漏洞
立即标记硬编码的密钥
审核身份验证和授权逻辑

Reference other files

参考其他文件

See security guidelines for standards.


Tips for instructions:
- Use Markdown links to reference other files
- Reference tools with `#tool:<tool-name>` syntax
- Be specific about agent behavior and constraints

请查看安全指南以遵循相关标准。


指令编写技巧：
- 使用Markdown链接引用其他文件
- 使用`#tool:<tool-name>`语法引用工具
- 明确Agent的行为和约束条件

Step 6: Validate the agent

步骤6：验证Agent

Verify the agent loads correctly:

Open Command Palette (Ctrl+Shift+P)
Run "Chat: New Custom Agent" or check agents dropdown
Use "Diagnostics" view (right-click in Chat view) to check for errors

验证Agent是否能正确加载：

打开命令面板（Ctrl+Shift+P）
运行“Chat: New Custom Agent”或查看Agent下拉列表
使用“Diagnostics”视图（在Chat视图中右键点击）检查错误

Template

模板

markdown

---
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
---

markdown

---
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>

<Agent标题>

<一段描述Agent角色和用途的文字>

Role

角色定位

<描述Agent的专业角色和专长>

Guidelines

指导原则

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

<指导原则1>
<指导原则2>
<指导原则3>

Workflow

工作流

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

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

Constraints

约束条件

<Constraint 1>
<Constraint 2>

undefined

<约束条件1>
<约束条件2>

undefined

Example Agents

示例Agent

Planning Agent

规划Agent

markdown

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

markdown

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

Planning Agent

规划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

undefined

规划前彻底分析需求
将工作拆分为独立、可测试的步骤
识别依赖关系和风险
请勿修改代码

undefined

Code Review Agent

代码审核Agent

markdown

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

markdown

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

Code Review Agent

代码审核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:

Critical: Must fix before merge
Warning: Should address
Suggestion: Nice to have

undefined

请按以下格式提交审核结果：

严重问题：合并前必须修复
警告：建议修复
建议：可选优化

undefined

Validation Checklist

验证检查清单

File has
```
.agent.md
```
extension
File is in
```
agents/
```
directory
YAML frontmatter is valid (proper indentation, no syntax errors)
Description is non-empty and descriptive
Tools list contains only available tools
Handoff agent names match existing agents
Instructions are clear and actionable
Agent appears in agents dropdown

文件扩展名为
```
.agent.md
```
文件位于
```
agents/
```
目录下
YAML前置元数据格式正确（缩进规范，无语法错误）
描述字段非空且具有描述性
工具列表仅包含可用工具
交接目标Agent名称与现有Agent匹配
指令清晰且可执行
Agent出现在下拉列表中

Common Pitfalls

常见问题

Pitfall	Solution
Agent not appearing in dropdown	Check file is in `agents/` directory with `.agent.md` extension
YAML syntax errors	Validate frontmatter indentation and quoting
Tools not working	Verify tool names exist; unavailable tools are ignored
Handoffs not showing	Target agent must exist; check agent identifier
Instructions too vague	Be specific about role, constraints, and workflow
Agent invoked as subagent unexpectedly	Set `disable-model-invocation: true`
Want agent only as subagent	Set `user-invokable: false`

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

create-custom-agent

Original

Translation

Create Custom Agent

创建自定义Agent

When to Use

适用场景

When Not to Use

不适用场景

Inputs

输入参数

Workflow

操作流程

Step 1: Create the agent file

步骤1：创建Agent文件

Step 2: Add YAML frontmatter

步骤2：添加YAML前置元数据

Available frontmatter fields:

可用的前置元数据字段：

Step 3: Configure tools

步骤3：配置工具

Step 4: Add handoffs (optional)

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

Step 5: Write agent instructions (body)

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

Guidelines

指导原则

Reference other files

参考其他文件

Step 6: Validate the agent

步骤6：验证Agent

Template

模板

<Agent Title>

<Agent标题>

Role

角色定位

Guidelines

指导原则

Workflow

工作流

Constraints

约束条件

Example Agents

示例Agent

Planning Agent

规划Agent

Planning Agent

规划Agent

Guidelines

指导原则

Code Review Agent

代码审核Agent

Code Review Agent

代码审核Agent

Focus Areas

重点关注领域

Output Format

输出格式

Validation Checklist

验证检查清单

Common Pitfalls

常见问题

References

参考链接