Documentation

Topics Overview Overview Agents Quickstart Editor Tutorial Intro Videos Overview Get started Agents Quickstart Agents Tutorial Best Practices Concepts Agents Agent Harnesses Language Models Context Tools Sessions & Handoff Agent Host Architecture Customization Workspace Context Trust & Safety Run agents Agents Window Chat View Choose an Agent Harness Use Tools Browser Tools Approvals & Permissions Review & Revert Changes Artifacts Remote Agent Sessions Plan Work Memory Subagents Sessions Manage Sessions Session History AI Security Customize agents Create and Manage Instructions Agent Skills Custom Agents Language Models MCP Hooks Plugins Tools Prompt Files Use chat Chat Basics Inline & Quick Chat Add Prompt Context Tutorials & guides Customize AI Context Engineering Test-Driven Development Test with AI Test Web Apps with Browser Tools Debug with AI Edit Notebooks with AI Optimize AI Credit Usage MCP Dev Guide Prompt Examples Reference Cheat Sheet Settings Reference MCP Configuration Hooks Reference OpenTelemetry Monitoring Troubleshooting Troubleshooting Debug Chat Interactions Diagnose Prompt Caching FAQ Editor Overview Quickstart Repositories & Remotes Staging & Committing Source Control History Branches & Worktrees Merge Conflicts Collaborate on GitHub Troubleshooting FAQ Get Started Terminal Basics Terminal Profiles Shell Integration Appearance Advanced Debugging Debug Configuration Tasks Testing Integrated Browser Port Forwarding Guides & Tutorials Test-Driven Development Test Web Apps with Browser Tools Overview Enterprise Policies AI Settings Extensions Telemetry Updates Overview VS Code for the Web SSH SSH Tutorial Tunnels Dev Containers WSL WSL Tutorial GitHub Codespaces VS Code Server Linux Prerequisites Tips and Tricks FAQ GitHub Copilot Setup Linux macOS Windows Raspberry Pi Network Portable Mode Additional Components Uninstall Languages & Runtimes Extension Docs

Custom agents in VS Code

Custom agents enable you to configure the AI to adopt different personas tailored to specific development roles and tasks. For example, you might create agents for a security reviewer, planner, solution architect, or other specialized roles. Each persona can have its own behavior, available tools, and instructions.

You can also use handoffs to create guided workflows between agents. Transition seamlessly from one specialized agent to another with a single select. For example, move from a planning agent directly into an implementation agent, or hand off to a code reviewer with the relevant context.

You can use the Agent Customizations editor (Preview) to discover, create, and manage all your agent customizations in one place. Run Chat: Open Customizations from the Command Palette.

This article describes how to create and manage custom agents in VS Code.

Tip

Not sure which customization to use? See the decision matrix to compare custom agents with prompt files, agent skills, and the other options.

What are custom agents?

The built-in agent roles provide general-purpose configurations for chat in VS Code. For a more tailored chat experience, you can create your own custom agents.

Custom agents consist of a set of instructions and tools that are applied when you switch to that agent. For example, a "Plan" agent could include instructions for generating an implementation plan and only use read-only tools. By creating a custom agent, you can quickly switch to that specific configuration without having to manually select relevant tools and instructions each time.

Custom agents are defined in a .agent.md Markdown file, and can be stored in your workspace for others to use, or in your user profile, where you can reuse them across different workspaces.

You can reuse your custom agents with Copilot and cloud harnesses, enabling you to run autonomous tasks with the same specialized configurations.

Why use custom agents?

Different tasks require different capabilities. A planning agent might only need read-only tools for research and analysis to prevent accidental code changes, while an implementation agent would need full editing capabilities. Custom agents let you specify exactly which tools are available for each task, ensuring the AI has the right capabilities for the job.

Custom agents also let you provide specialized instructions that define how the AI should operate. For instance, a planning agent could instruct the AI to collect project context and generate a detailed implementation plan, while a code review agent might focus on identifying security vulnerabilities and suggesting improvements. These specialized instructions ensure consistent, task-appropriate responses every time you switch to that agent.

Note

Subagents can run with a custom agent. Learn more about running subagents with custom agents.

Handoffs

Handoffs enable you to create guided sequential workflows that transition between agents with suggested next steps. After a chat response completes, handoff buttons appear that let users move to the next agent with relevant context and a pre-filled prompt.

Handoffs are useful for orchestrating multi-step workflows that give developers control for reviewing and approving each step before moving to the next one. For example:

Planning Implementation: Generate a plan in planning agent, then hand off to implementation agent to start coding.
Implementation Review: Complete implementation, then switch to a code review agent to check for quality and security issues.
Write Failing Tests Write Passing Tests: Generate failing tests that are easier to review than big implementations, then hand off to make those tests pass by implementing the required code changes.

To define handoffs in your agent file, add them to the frontmatter. Each handoff specifies the target agent, the button label, and an optional prompt to send:

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

Agent orchestration example

The following example shows a "Feature Builder" agent that coordinates specialized subagents for a research-then-implement workflow. The main agent uses the agents property to restrict which agents can be invoked as subagents.

feature-builder.agent.md - The coordinating agent:

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

implementer.agent.md - Code editing agent:

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

You are a code editing agent. After making changes, files are automatically formatted.

Learn more about hooks in Agent hooks.

Claude agent format

Agent files in the .claude/agents folder use plain .md files and support Claude-specific frontmatter properties:

Field	Description
`name`	Agent name (required)
`description`	What the agent does
`tools`	Comma-separated string of allowed tools (for example, `"Read, Grep, Glob, Bash"`)
`disallowedTools`	Comma-separated string of tools to block

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.

Note

VS Code also detects .md files in the .claude/agents folder, following the Claude sub-agents format. This enables you to use the same agent definitions across VS Code and Claude Code.

Create a custom agent

You can create a custom agent file in your workspace or user profile.

Tip

Type /agents in the chat input to quickly open the Configure Custom Agents menu.

In the Chat view, select Configure Chat (gear icon) to open the Agent Customizations editor and then select the Agents tab.
Select New Agent (Workspace) or New Agent (User) from the dropdown, depending on where you want to store the agent file.

[Screenshot of the Agent Customizations editor, showing the Agents tab and the dropdown to create a new custom agent.]

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

Tip
You can configure additional locations where VS Code searches for custom agent files by using the chat.agentFilesLocations Open in VS Code Open in VS Code Insiders setting. This is useful for sharing agents across projects or keeping them in a central location outside your workspace.
Select the location and enter a file name for the custom agent. This is the default name that appears in the agents dropdown.
Provide the details for the custom agent in the newly created .agent.md file.
- Fill in the YAML frontmatter at the top of the file to configure the custom agent's name, description, tools, and other settings.
- Add instructions for the custom agent in the body of the file.

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

Generate a custom agent with AI

You can use AI to generate a custom agent based on a description of the role. Type /create-agent in Agent mode chat and describe the persona you want (for example, "a security review agent"). The agent asks clarifying questions and generates an .agent.md file with appropriate tools, instructions, and frontmatter.

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.

You can also generate a custom agent from the Agent Customizations editor by selecting Generate Agent from the dropdown.

If you have multiple custom agents, you can customize which ones appear in the agents dropdown. To show or hide specific custom agents:

Select Configure Custom Agents from the agents dropdown.
Hover over a custom agent in the list, and then select the eye icon to show or hide it from the agents dropdown.

Tool list priority

When you use tools in both a custom agent and a prompt file, the prompt file's tools take precedence. 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 to convert them to the new custom agent format and place them in the appropriate location ( chat.agentFilesLocations Open in VS Code Open in VS Code Insiders ) to continue using them.

How do I remove a custom agent?

To completely remove a custom agent from VS Code:

Delete the corresponding .agent.md file from your workspace or user profile.
Select Configure Custom Agents from the agents dropdown, hover over the custom agent in the list, and select the trash icon.

To remove a custom agent that was contributed by an extension, you need to uninstall the extension that provides it. If you don't want to uninstall the extension, you can hide the custom agent from the agents dropdown instead. Follow the steps in Customize the agents dropdown list.

How do I know where a custom agent comes from?

Custom agents can come from different sources: built-in agents, user-defined agents in your profile, workspace-defined agents in your current workspace, organization-defined agents, or extension-contributed agents.

To identify the source of a custom agent:

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

Tip

Use the chat customization diagnostics view to see all loaded custom agents, prompt files, instruction files, and skills along with any errors. Right-click in the Chat view and select Diagnostics. Learn more about troubleshooting AI in VS Code.

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

8/19/2026