# Create Custom Agent

Creates VS Code custom agent files (.agent.md) for specialized AI personas with tools...

- Repository: https://github.com/dotnet/skills (5787 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add dotnet/skills --skill create-custom-agent -g -a claude-code -y`
Codex: `npx skills add dotnet/skills --skill create-custom-agent -g -a codex -y`
Cursor: `npx skills add dotnet/skills --skill create-custom-agent -g -a cursor -y`
Gemini CLI: `npx skills add dotnet/skills --skill create-custom-agent -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add dotnet/skills`

## Description

Creates VS Code custom agent files (.agent.md) for specialized AI personas with tools, instructions, and handoffs. Use when scaffolding new custom agents, configuring agent workflows, or setting up agent-to-agent handoffs.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Create Custom 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.

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

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

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

## Workflow

### Step 1: Create the agent file

Create a file with `.agent.md` extension in the `agents/` directory:

```
agents/<agent-name>.agent.md
```

### Step 2: Add YAML frontmatter

Add the header with required and optional fields:

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

#### Available frontmatter fields:

The rest: https://github.com/dotnet/skills/blob/HEAD/.agents/skills/create-custom-agent/SKILL.md