Custom agents in VS Code

Custom agents combine instructions, tools, and an optional language model into a reusable configuration for a specific role, such as planning or code review. Switch to a custom agent instead of repeating the same instructions and selecting tools for every conversation.

This article shows you how to create, use, and manage custom agents in VS Code, configure their files, and connect them with handoffs.

What are custom agents?

The built-in agent roles provide general-purpose configurations for chat. Custom agents provide your own role-specific configurations, defined in .agent.md Markdown files.

Store an agent in your workspace to share it with project contributors, or at the user level to reuse it across workspaces. The supported file locations depend on the harness and file format.

You can reuse agent definitions with different agent harnesses. The available tools and management controls depend on the selected harness.

Why use custom agents?

Use a custom agent when a recurring task needs its own instructions and tool selection. For example:

• Give a planning agent read-only tools to research a change before implementation.
• Give a code review agent your team's review criteria.
• Give an implementation agent editing tools and instructions to follow existing project patterns.

Create a custom agent

Use the Agent Customizations editor (Preview) to create an agent in your workspace or at the user level.

Use the Session Target control to select the agent harness you intend to use, then open the editor from either surface:

• Agents window: Select Agents in the Customizations panel in the left sidebar.
• Chat view: Select Configure Chat (gear icon), and then select Agents.

The editor shows customizations for the selected harness. You can generate a custom agent with AI, or follow these steps to create the file manually:

1. Select New Agent (Workspace) or New Agent (User) from the dropdown, depending on where you want to store the agent file.

   

   Alternatively, run the Chat: New Custom Agent command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).

2. Select the location and enter a file name for the custom agent. This is the default name that appears in the agents dropdown.

3. Provide the details in the newly created .agent.md file, and then save it.

   • Fill in the YAML frontmatter to configure the agent's name, description, tools, and other options.
   • Add instructions for the agent in the body of the file. Use the examples as a starting point.

You can modify existing custom agents by opening them in the Agent Customizations editor.

Generate a custom agent with AI

Start from the Overview page of the Agent Customizations editor to generate a custom agent from a description:

1. Open the Agent Customizations editor and select Overview.
2. Enter a prompt that describes the agent's role and whether it should be available in the workspace or across your workspaces.
3. Answer any clarifying questions about the role or workflow.
4. Review the generated .agent.md file, including its tools, instructions, and frontmatter. Correct any inaccurate information and save the file.

For example, enter the following prompt:

Create a workspace custom agent for code reviews. Review changes for correctness, maintainability, and consistency with this repository's conventions. Report findings without editing files.

You can also extract a custom agent from an ongoing conversation. For example, after a multi-turn debugging session, ask "make an agent for this kind of task" to capture the workflow as a reusable custom agent.

With Local selected, you can also use these shortcuts:

• Type /create-agent in Agent mode chat and describe the role you want.
• Select Generate Agent from the dropdown in the Agents section of the Agent Customizations editor.

These shortcuts aren't available in Agent Host sessions, such as Copilot. Use the Overview workflow instead.

Use a custom agent

1. In the Chat view or Agents window, select the intended harness from the Session Target control.
2. Open the Agent dropdown and select your custom agent.
3. Enter a prompt for its role. For example, ask a planning agent to outline the changes needed for a new feature.
4. Review the response and any tool calls to check that the agent follows the intended instructions and uses appropriate tools.

If the agent doesn't appear, check that its file is in a supported location for the selected harness and that its visibility configuration permits user invocation.

Customize the agents dropdown list

To keep a custom agent available as a subagent without listing it in the Agent dropdown, set user-invocable: false in its YAML frontmatter:

user-invocable: false

This property controls picker visibility in both Local and Copilot. To show the agent again, set it to true or remove the property. Subagent invocation is controlled separately by disable-model-invocation.

Editing this property changes the agent definition, not a personal visibility preference. If you share the file in a repository, the change applies to everyone who uses that definition. It doesn't delete the agent file.

Custom agent file locations

You can define custom agents for a specific workspace or at the user level, where they are available across all your workspaces. The following table lists the supported file locations for custom agents based on their scope.

To create a user-level custom agent, use the Agent Customizations editor or the Chat: New Custom Agent command.

Custom agent file structure

Custom agent files use the .agent.md extension. An optional YAML header configures the agent, and the Markdown body provides its instructions.

Header (optional)

The header is formatted as YAML frontmatter with the following fields:

Body

The Markdown body contains the instructions the agent follows, such as its task, guidelines, and expected output.

You can reference other files by using Markdown links or the #file: syntax, for example to reuse instructions files. Relative file paths resolve from the custom agent file. To reference your environment user home folder, use ~, or start a path with ~/, such as #file:~/copilot/security-guidelines.md. Use Unix-style / path separators to keep custom agent files portable across operating systems.

To reference agent tools in the body text, use the #tool:<tool-name> syntax. For example, to reference the fetch tool, use #tool:web/fetch.

When you select the custom agent in the Chat view, the guidelines in the custom agent file body are prepended to the user chat prompt.

Examples

---
description: Generate an implementation plan for new features or refactoring existing code.
name: Planner
tools: ['web/fetch', 'search/codebase', 'search/usages']
model: ['Claude Opus 4.5', 'GPT-5.2']  # Tries models in order
handoffs:
  - label: Implement Plan
    agent: agent
    prompt: Implement the plan outlined above.
    send: false
---
# Planning instructions
You are in planning mode. Your task is to generate an implementation plan for a new feature or for refactoring existing code.
Don't make any code edits, just generate a plan.

The plan consists of a Markdown document that describes the implementation plan, including the following sections:

* Overview: A brief description of the feature or refactoring task.
* Requirements: A list of requirements for the feature or refactoring task.
* Implementation Steps: A detailed list of steps to implement the feature or refactoring task.
* Testing: A list of tests that need to be implemented to verify the feature or refactoring task.

---
name: Feature Builder
description: Build features by researching first, then implementing
tools: ['agent']
agents: ['Researcher', 'Implementer']
---
You are a feature builder. For each task:
1. Use the Researcher agent to gather context and find relevant patterns in the codebase
2. Use the Implementer agent to make the actual code changes based on research findings

---
name: Researcher
description: Research codebase patterns and gather context
tools: ['search/codebase', 'web/fetch', 'search/usages']
---
Research thoroughly using read-only tools. Return a summary of findings.

---
name: Implementer
description: Implement code changes based on provided context
tools: ['edit', 'read/terminalLastCommand']
---
Implement changes following existing code patterns. Make minimal, focused edits.

---
name: Strict Formatter
description: Agent that formats code after every successful tool call
hooks:
  PostToolUse:
    - type: command
      command: "./scripts/format-changed-files.sh"
---

You are a code editing agent. Follow the project's formatting requirements.

Claude agent format

Agent files in the .claude/agents folder use plain .md files, following the Claude sub-agents format. They support Claude-specific frontmatter properties:

VS Code maps Claude-specific tool names to the corresponding VS Code tools. Both the VS Code .agent.md format (with YAML arrays for tools) and the Claude format (with comma-separated strings) are supported.

Handoffs

Handoffs connect agents into a workflow with suggested next steps. After a chat response completes, handoff buttons let you switch to another agent with the conversation context and a pre-filled prompt.

Use handoffs to review one stage of a task before starting the next. For example:

• Planning to implementation: Review a plan, then hand off to an implementation agent to start coding.
• Implementation to review: Complete implementation, then switch to a code review agent.
• Failing tests to passing tests: Review generated tests, then hand off to an agent that implements the changes needed to pass them.

To define handoffs, add them to the agent's frontmatter. Each handoff specifies the target agent, the button label, and an optional prompt:

---
description: Generate an implementation plan
tools: ['search', 'web']
handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Now implement the plan outlined above.
    send: false
    model: GPT-5.2 (copilot)
---

When you select a handoff button, you switch to the target agent with the prompt pre-filled. If send: true, the prompt submits automatically.

Tool list priority

With Local, when you use tools in both a custom agent and a prompt file, the prompt file's tools take precedence. Agent Host sessions don't load prompt files. For the full priority order, see Tool list priority in the prompt files documentation.

Share custom agents across teams

To share custom agents across your team, you can create a workspace-level custom agent (.github/agents folder). If you want to share custom agents across multiple workspaces within your organization, you can define them at the GitHub organization level.

VS Code automatically detects custom agents defined at the organization level to which your account has access. These agents appear in the Agents dropdown in chat alongside the built-in agents, and your personal and workspace custom agents.

To enable discovery of organization-level custom agents, set github.copilot.chat.organizationCustomAgents.enabled Open in VS Code Open in VS Code Insiders to true.

Learn how you can create custom agents for your organization in the GitHub documentation.

Frequently asked questions

Are custom agents different from chat modes?

Custom agents were previously known as custom chat modes. The functionality remains the same, but the terminology has been updated to better reflect their purpose in customizing AI behavior for specific tasks.

If you have existing .chatmode.md files, rename them to .agent.md and place them in one of the supported custom agent locations.

How do I remove a custom agent?

To remove a custom agent you maintain, use either of these methods:

• Delete its file from the workspace or user-level location.
• Select Configure Custom Agents from the agents dropdown to open the Agent Customizations editor, hover over the custom agent, and select the trash icon.

Deleting a shared workspace agent also removes it for others when they receive the repository change. To keep the definition but remove it from the picker, see Customize the agents dropdown list.

You can't delete extension-provided agents from the Agent Customizations editor. Disable or uninstall the contributing extension to remove its agents. This also affects the extension's other features.

How do I know where a custom agent comes from?

The agents dropdown includes built-in roles and custom agents from user-level files, your workspace, organizations, extensions, and plugins.

To identify the source of a custom agent:

1. Select Configure Custom Agents from the agents dropdown.
2. Hover over the custom agent in the list. The source location is displayed in a tooltip.

Security considerations

Custom agents can restrict which tools are available, which gives you control over what the AI can do. For security-sensitive workflows, create agents with read-only tools to prevent unintended modifications. When sharing agents in a repository, review the tool list and instructions to ensure they follow the principle of least privilege.

Related resources

• Planning with agents
• Customize AI with custom instructions
• Use tools with agents