How to Create Custom Agents in VS Code with .agent.md Files

VS Code custom agents let you create specialized AI personas. Instead of telling the general-purpose agent to act like a security reviewer every time, you create one once and switch to it from a dropdown.

Each agent can define its own tools, instructions, and language model.

A planning agent gets read-only access. An implementation agent gets full editing. A code reviewer gets read plus search. Switch between them instantly.

This article shows you how to create them. For running agents on multi-file tasks, see /vscode/how-to-use-coding-agents-and-the-agents-window-in-vs-code.

Agent file locations

Workspace agents are committed to version control and shared with your team. User agents are private and available across all workspaces.

The current locations, fields, and commands are documented in the official VS Code custom agents guide.

Agent file structure

An agent file has YAML frontmatter and a Markdown body. The frontmatter configures the agent's identity and capabilities:

yaml

---
name: security-reviewer
description: Review code for security vulnerabilities
tools: ['search/codebase', 'search/usages']
---

The body contains the agent's instructions. Describe the agent's role, approach, output format, and any constraints. Here is the body for the security reviewer:

markdown

You are a security reviewer. When reviewing code, look for injections, XSS, auth bypass, and exposed secrets.
 
Rate each finding by severity and suggest a concrete fix with a code example. Reference the relevant CWE or OWASP category.
 
Do not suggest changes to code style or performance. Focus only on security.

Frontmatter fields

Use Configure Tools in the chat input to inspect the current tool list. Tools from installed MCP servers can also appear. In an agent body, reference a tool with the #tool:<tool-name> syntax.

Create an agent

You can also type /create-agent in chat and describe the persona. The AI asks clarifying questions and generates the file for you. Or after a productive debugging session, ask "make an agent for this kind of task" to capture the workflow.

Chain agents with handoffs

Handoffs create guided workflows that move from one agent to another. After the current agent finishes, a button appears suggesting the next step.

The user clicks it to transition to the next agent with context pre-filled.

Add handoffs to the frontmatter:

yaml

---
name: planner
description: Create detailed implementation plans
tools: ['search/codebase', 'search/usages']
handoffs:
  - label: Start Implementation
    agent: implementer
    prompt: Now implement the plan outlined above.
    send: false
---

When the planner finishes, a Start Implementation button appears. The user clicks it, the agent switches to the implementer, and the prompt is pre-filled. If send: true, the prompt sends automatically.

Common handoff chains:

• Plan -> Implement: review the plan, then build it.
• Implement -> Review: build it, then check for issues.
• Write Failing Tests -> Make Tests Pass: TDD workflow with review between steps.

Hide agents from the dropdown

Some agents are only useful as subagents or handoff targets. Set user-invocable: false to hide them from the agents dropdown while keeping them available for handoffs and subagent calls:

yaml

---
name: research-helper
description: Search the codebase and report relevant findings
tools: ['search/codebase', 'search/usages']
user-invocable: false
---

Claude Code compatibility

If you use Claude Code alongside VS Code, you can share agent definitions. Place .md files in .claude/agents/ using the Claude format:

markdown

---
name: code-reviewer
description: Review code for issues
tools: Read, Grep, Glob
---

VS Code detects these files automatically and maps Claude tool names to VS Code equivalents. You do not need to maintain separate agent files for each tool.

Organize and manage agents

To customize which agents appear in the dropdown, select Configure Custom Agents from the agents dropdown. Hover over an agent and select the eye icon to show or hide it. Select the trash icon to delete it.

To identify where an agent comes from, hover over it in the Configure Custom Agents list. The tooltip shows whether it is built-in, workspace-defined, user-defined, or contributed by an organization or extension.

Security considerations

Custom agents let you restrict tools. For sensitive workflows, select only the read-only tools needed for the task. Tool names and capabilities can change, so inspect the current tool list and review requested actions before approval.

When sharing agents in a repository, review the instructions and tool list carefully. Terminal and editing tools can change the environment, so grant them only when the workflow requires them.

For creating reusable task templates that use your custom agents, see /vscode/how-to-create-and-use-reusable-prompt-md-files-in-vs-code.