Custom Agent Builder
Create VS Code custom agent files with tools, instructions, and handoffs.
Installation
- Make sure Claude is on your device and in your terminal.
Skills load from
~/.claude/skills/when Claude Code starts up — so you need it on your machine first. If you don't have it yet, install it once with the command below, then runclaudein any terminal to verify.One-time setupnpm i -g @anthropic-ai/claude-codeAlready have it? Skip ahead.
- Paste into Claude Code or into your terminal.
This copies the whole skill folder into
~/.claude/skills/create-custom-agent-dotnet/— the SKILL.md plus any scripts, reference docs, or templates the skill ships with. Works for every skill.What this command does
- Makes a new, empty temporary folder.
- Downloads the skill's folder,
.agents/skills/create-custom-agent, fromgithub.com/dotnet/skills(branchmain), the GitHub repository it's listed from. You get the version that is there now, not a copy we keep. - Copies that folder to
~/.claude/skills/create-custom-agent-dotnet/. - Deletes the temporary folder.
Installing runs none of the skill's files; it only downloads and copies them. When you later use the skill, Claude follows its SKILL.md and may run scripts that come with it. Read them first.
Faster alternative (instruction-only skills)
Skips the clone and grabs only the SKILL.md file. Don't use this if the skill ships Python scripts, reference markdowns, or asset templates — they won't be downloaded and the skill will fail when it tries to load them.
Quick install (SKILL.md only)Sign up to copy - Restart Claude Code.
Quit and reopen Claude Code (or any other agent that loads from
~/.claude/skills/). New skills are picked up on startup. - Just ask Claude.
Skills auto-activate when your request matches the skill's description — no slash command needed. Trigger phrases live in the skill's own frontmatter; you can read them in the “What this skill does” section above.
Prefer to read the source first? Open on GitHub.
When Claude uses it
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.
What this skill does
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.mdfile 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.mdinstead) - Creating reusable prompts (use
.prompt.mdinstead) - 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:
---
name: <agent-name>
description: <brief description for chat placeholder>
tools:
- <tool-name>
- <tool-set-name>
---
Available frontmatter 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 |
Step 3: Configure tools
Specify which tools the agent can use:
tools:
- search # Built-in tool
- fetch # Built-in tool
- codebase # Tool set
- myServer/* # All tools from MCP server
Common tool patterns:
- Read-only agents:
['search', 'fetch', 'codebase'] - Full editing agents:
['*']or specific editing tools - Specialized agents: Cherry-pick specific tools
Step 4: Add handoffs (optional)
Configure transitions to other agents:
handoffs:
- label: Start Implementation
agent: implementation
prompt: Implement the plan outlined above.
send: false
model: GPT-5.2 (copilot)
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 handoff
Step 5: Write agent instructions (body)
Add the agent's behavior instructions in Markdown:
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.
Tips for instructions:
- Use Markdown links to reference other files
- Reference tools with
#tool:<tool-name>syntax - Be specific about agent behavior and constraints
Step 6: Validate the agent
Verify the agent loads correctly:
- Open Command Palette (Ctrl+Shift+P)
- Run "Chat: New Custom Agent" or check agents dropdown
- Use "Diagnostics" view (right-click in Chat view) to check for errors
Template
---
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>
Example Agents
Planning Agent
---
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
Code Review Agent
---
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
Validation Checklist
- File has
.agent.mdextension - File is in
agents/directory - YAML frontmatter is valid (proper indentation, no syntax errors)
- Description is non-empty and descriptive
- Tools list contains only available tools
- Handoff agent names match existing agents
- Instructions are clear and actionable
- Agent appears in agents dropdown
Common Pitfalls
| 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 |
References
Related skills
Word Document Editor
anthropics
Create, edit, and format Word documents with tables, images, and tracked changes.
Ask Questions If Underspecified
trailofbits
Ask clarifying questions before starting work on ambiguous requests.
CLAUDE.md Optimizer
daymade
Optimize your CLAUDE.md file for clarity, efficiency, and maintainability.
Claude Skills Troubleshooter
daymade
Diagnose and fix plugin installation, enablement, and activation problems.