OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add dotnet/skills --skill create-custom-agent
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.
npx skills add dotnet/skills --skill 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.
.agent.md file with proper frontmatter.instructions.md instead).prompt.md instead)| 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 |
Create a file with .agent.md extension in the agents/ directory:
Add the header with required and optional fields:
| 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 |
Specify which tools the agent can use:
Common tool patterns:
['search', 'fetch', 'codebase']['*'] or specific editing toolsConfigure transitions to other agents:
Handoff fields:
label: Button text displayed to useragent: Target agent identifierprompt: Pre-filled prompt for target agentsend: Auto-submit prompt (default: false)model: Optional model override for handoffAdd the agent's behavior instructions in Markdown:
Tips for instructions:
#tool:<tool-name> syntaxVerify the agent loads correctly:
.agent.md extensionagents/ directory| 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 |
tools:
- search # Built-in tool
- fetch # Built-in tool
- codebase # Tool set
- myServer/* # All tools from MCP serverhandoffs:
- label: Start Implementation
agent: implementation
prompt: Implement the plan outlined above.
send: false
model: GPT-5.2 (copilot)You are a security-focused code reviewer. Your job is to:
1. Analyze code for security vulnerabilities
2. Check for common security anti-patterns
3. Suggest secure alternatives
## Guidelines
- Focus on OWASP Top 10 vulnerabilities
- Flag hardcoded secrets immediately
- Review authentication and authorization logic
## Reference other files
See [security guidelines](../security.md) for standards.---
name: <agent-name>
description: <brief description for chat placeholder>
argument-hint: <optional hint for user input>
tools:
- <tool-1>
- <tool-2>
handoffs:
- label: <button-text>
agent: <target-agent>
prompt: <pre-filled-prompt>
send: false
---
# <Agent Title>
<One paragraph describing the agent's persona and purpose.>
## Role
<Describe the agent's specialized role and expertise.>
## Guidelines
- <Guideline 1>
- <Guideline 2>
- <Guideline 3>
## Workflow
1. <Step 1>
2. <Step 2>
3. <Step 3>
## Constraints
- <Constraint 1>
- <Constraint 2>---
name: planner
description: Generate an implementation plan
tools:
- search
- fetch
- codebase
handoffs:
- label: Start Implementation
agent: implementation
prompt: Implement the plan above.
---
# Planning Agent
You are a solution architect. Generate detailed implementation plans.
## Guidelines
- Analyze requirements thoroughly before planning
- Break work into discrete, testable steps
- Identify dependencies and risks
- Do NOT make code changes---
name: code-reviewer
description: Review code for quality and security issues
tools:
- search
- codebase
---
# Code Review Agent
You are a senior engineer performing code review.
## Focus Areas
- Security vulnerabilities
- Performance concerns
- Code maintainability
- Test coverage gaps
## Output Format
Provide findings as:
1. **Critical**: Must fix before merge
2. **Warning**: Should address
3. **Suggestion**: Nice to have