Text of code.visualstudio.com › docs › agent-customization › custom-agents as Styx crawled it on Oct 9, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Custom agents in VS Code

AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. 🎬 Watch The Story of VS Code! VS Code is now on Instagram, follow @vscode.ig for updates, tips, and more. Rewatch GitHub Copilot Day. Custom agents in VS Code View as Markdown Ask in VS Code Ask in VS Code Insiders 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. 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.

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. Note Subagents can run with a custom agent. Learn more about running subagents with custom agents .

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: 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 ) ). 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 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. Tip In the Chat view, with Copilot selected, type /agents in the chat input to open the Agents section of the Agent Customizations editor.

With Local selected, /agents opens the agent picker, where you can select Configure Custom Agents to open the 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: Open the Agent Customizations editor and select Overview . Enter a prompt that describes the agent's role and whether it should be available in the workspace or across your workspaces.

Answer any clarifying questions about the role or workflow. 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 In the Chat view or Agents window, select the intended harness from the Session Target control. Open the Agent dropdown and select your custom agent. Enter a prompt for its role. For example, ask a planning agent to outline the changes needed for a new feature. 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. Note The Agent Customizations editor doesn't provide an eye-icon show or hide control for custom agents in either Local or Copilot .

For agents contributed by an extension, manage the contributing extension instead. See How do I remove a custom agent? . 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. Scope Default file location Workspace .github/agents folder Workspace (Claude format) .claude/agents folder User ~/.copilot/agents or ~/.claude/agents To create a user-level custom agent, use the Agent Customizations editor or the Chat: New Custom Agent command.

Important For sessions that run on Agent Host , the agent reads user-level custom agents from the selected host's folder, such as ~/.copilot/agents or ~/.claude/agents , and not from VS Code profile user data. To move existing user-level custom agents, use the user customization migration . Note The chat.agentFilesLocations Open in VS Code Open in VS Code Insiders and chat.modeFilesLocations Open in VS Code Open in VS Code Insiders settings are deprecated and only used by the Local agent.

If you configured other agent locations with these settings, migrate the customizations to supported locations . Tip In a monorepo, enable chat.useCustomizationsInParentRepositories Open in VS Code Open in VS Code Insiders to discover custom agents from the parent repository root. Learn more about parent repository discovery . 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.

Note VS Code detects any .md files in the .github/agents folder of your workspace as custom agents. Header (optional) The header is formatted as YAML frontmatter with the following fields: Field Description description A brief description of the custom agent, shown as placeholder text i

The rest of this page is on the live site.