Install

The skill file stays in the publisher's repository.

Paste the copied command in a terminal. It installs this SKILL.md into that agent.

npx skills add dotnet/skills --skill create-custom-agent -a cursor -y

Download skill

.agents/skills/create-custom-agent/SKILL.md on GitHub

name: create-custom-agent 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.

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

Field	Required	Description
`name`	No	Display name (defaults to filename)
`description`	Yes	Placeholder text shown in chat input
`argument-hint`	No	Hint text guiding user interaction
`tools`	No	List of available tools/tool sets
`agents`	No	List of allowed subagents (`*` for all, `[]` for none)
`model`	No	AI model name or prioritized array of models
`handoffs`	No	List of next-step agent transitions
`user-invokable`	No	Show in agents dropdown (default: true)
`disable-model-invocation`	No	Prevent subagent invocation (default: false)
`target`	No	Target environment: `vscode` or `github-copilot`
`mcp-servers`	No	MCP server configs for GitHub Copilot target

Pitfall	Solution
Agent not appearing in dropdown	Check file is in `agents/` directory with `.agent.md` extension
YAML syntax errors	Validate frontmatter indentation and quoting
Tools not working	Verify tool names exist; unavailable tools are ignored
Handoffs not showing	Target agent must exist; check agent identifier
Instructions too vague	Be specific about role, constraints, and workflow
Agent invoked as subagent unexpectedly	Set `disable-model-invocation: true`
Want agent only as subagent	Set `user-invokable: false`

create-custom-agent

Install

Related skills

name: create-custom-agent 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.

Create Custom Agent

When to Use

When Not to Use

Inputs

Workflow

Step 1: Create the agent file

Step 2: Add YAML frontmatter

Available frontmatter fields:

Step 3: Configure tools

Step 4: Add handoffs (optional)

Step 5: Write agent instructions (body)

Step 6: Validate the agent

Template

Example Agents

Planning Agent

Code Review Agent

Validation Checklist

Common Pitfalls

References