Creating Custom Agents

Learn how to create specialized AI agents that enhance your Claude Code workflow. This guide covers everything from basic agent structure to advanced patterns.

What you'll learn:

Agent configuration structure
Template system and variables
Best practices and patterns
Testing and deployment

Quick Start

Choose a Template

Start with the template that best fits your needs:

.claude/agents/_templates/
├── AI_ORCHESTRATOR_BUILDER_TEMPLATE.md
├── BACKEND_BUILDER_TEMPLATE.md
└── FRONTEND_DESIGNER_TEMPLATE.md

Copy and Customize

# Copy template
cp .claude/agents/_templates/BACKEND_BUILDER_TEMPLATE.md \
   .claude/agents/builders/my-custom-agent.md
 
# Or create from scratch
touch .claude/agents/specialists/my-specialist.md

Define Agent Configuration

---
name: my-custom-agent
category: specialist
specialization: specific-domain
 
description: |-
  Clear description of what this agent does.
  Call when you need {specific-capability}.
 
example: "Build a {concrete-example}"
 
context: |-
  Use when you need {CAPABILITY} - explain when to invoke this agent.
  Clarify what it does vs what it delegates.
 
tools: [Write, Read, Edit, Bash, Grep]
model: sonnet
---

Test Your Agent

# Invoke agent in Claude Code
/agent my-custom-agent "Test task"
 
# Or use agent command
claude agent run my-custom-agent --input "test.md"

Agent Configuration Structure

Basic Agent YAML

---
# Identity
name: agent-name              # Unique identifier (kebab-case)
category: builder | designer | specialist | reviewer
specialization: domain-expertise  # What makes this agent unique
 
# Documentation
description: |-
  Multi-line description of agent capabilities.
  Used for agent discovery and selection.
 
example: "Concrete example of agent usage"
 
context: |-
  When to use this agent vs other agents.
  What it's good at, what it delegates.
 
# Capabilities
tools: [Write, Read, Edit, MultiEdit, Bash, Grep, Glob, WebFetch]
model: sonnet | opus | haiku
 
# Metadata
tags: [tag1, tag2, tag3]
version: 1.0.0
color: blue | red | green | purple | pink
priority: high | medium | low
emoji: 🎯  # Visual identifier
 
# Relationships
delegates_to:
  - other-agent: "When to delegate"
 
depends_on:
  - "System dependency"
  - "Required tool or service"
---

Agent Instructions Section

After the YAML frontmatter, write detailed instructions:

# Purpose
 
Clear statement of agent purpose and philosophy.
 
## Core Philosophy
 
### Principle 1
Explanation...
 
### Principle 2
Explanation...
 
## Instructions
 
### Phase 1: {Stage Name}
 
**Step 1: {Action}**
 
```{language}
# Code examples
# Configuration examples
# Command examples
```
 
**Step 2: {Action}**
 
Detailed instructions with examples...
 
### Phase 2: {Stage Name}
 
Continue with detailed phases...
 
## Quality Standards
 
- [ ] Checklist item 1
- [ ] Checklist item 2
- [ ] Checklist item 3
 
## Examples
 
### Example 1: {Scenario}
 
**Input**: "User request"
 
**Process**:
1. Step 1
2. Step 2
3. Step 3
 
**Output**:
- Generated artifacts
- Documentation
- Test suites
 
## Success Criteria
 
Your agent implementation is successful when:
1. Criterion 1
2. Criterion 2
3. Criterion 3

Template Variables

Templates use {variable} syntax for customization:

Common Variables

template_variables:
  # Framework/Runtime
  {framework}: nextjs | fastapi | express | streamlit
  {runtime}: python | node | bun | go
  {language}: typescript | python | go
 
  # Specialization
  {specialization}: mcp-server | rest-api | graphql-api
  {approach}: kitchen-cabinet | dashboard-first | chat-first
  {design_system}: shadcn | material | custom
 
  # Technical
  {database}: postgres | mongo | redis | firestore
  {deployment}: docker | cloud-run | lambda | vercel
 
  # Domain
  {domain}: sports | finance | healthcare | ecommerce
  {resource}: leagues | teams | players | games

Using Variables in Templates

# Template definition
name: {runtime}-{framework}-builder
description: Production-grade {framework} builder for {runtime}
 
# After substitution
name: python-fastapi-builder
description: Production-grade fastapi builder for python

Agent Categories

1. Builder Agents

Create complete implementations from specifications.

category: builder
specialization: backend-api | frontend-ui | mcp-server
 
capabilities:
  - Generate production-ready code
  - Include comprehensive tests
  - Add deployment configurations
  - Create documentation
 
delegate_pattern:
  - Planning → Architect agent
  - Security review → Security auditor
  - Deployment → Deployment specialist

Example Builder:

---
name: fastapi-mcp-builder
category: builder
specialization: mcp-server-fastapi
 
description: |-
  FastAPI MCP server builder that creates production-ready
  MCP servers with FastMCP framework and Cloud Run deployment.
 
tools: [Write, MultiEdit, Bash, Read]
model: sonnet
 
delegates_to:
  - security-auditor: "For security review"
  - test-engineer: "For comprehensive testing"
---
 
# Purpose
Build production-grade MCP servers using FastAPI and FastMCP...
 
## Instructions
 
### Phase 1: Project Setup
Create MCP server structure with uv and FastMCP...
 
### Phase 2: Tool Implementation
Define MCP tools with proper schemas...

2. Designer Agents

Create implementation-ready specifications.

category: designer
specialization: ui-design | api-design | database-schema
 
capabilities:
  - Create design specifications
  - Define component architecture
  - Specify styling and behavior
  - Include accessibility requirements
 
delegate_pattern:
  - Implementation → Builder agent
  - Accessibility audit → Accessibility expert

Example Designer:

---
name: dashboard-designer
category: designer
specialization: analytics-dashboard
 
description: |-
  Analytics dashboard designer specializing in data visualization,
  real-time metrics, and interactive charts with shadcn/ui.
 
tools: [Write, Read, WebFetch]
model: sonnet
---
 
# Purpose
Design analytics dashboards with focus on data clarity...
 
## Design Approach: Dashboard-First
 
### Layout Strategy
Card-based metric display with hierarchical information...
 
### Component Specifications
MetricCard, ChartContainer, DataTable, Filters...

3. Specialist Agents

Domain experts with deep knowledge.

category: specialist
specialization: security | performance | database | ai
 
capabilities:
  - Deep domain expertise
  - Analysis and recommendations
  - Best practices enforcement
  - Problem diagnosis
 
delegate_pattern:
  - Implementation → Builder agent
  - Related specialties → Other specialists

Example Specialist:

---
name: database-optimizer
category: specialist
specialization: database-performance
 
description: |-
  Database performance specialist who analyzes queries,
  indexes, and schema design for optimal performance.
 
tools: [Read, Grep, Bash, WebFetch]
model: sonnet
---
 
# Purpose
Optimize database performance through query analysis...
 
## Analysis Process
 
### Phase 1: Query Performance
Analyze slow queries and suggest optimizations...
 
### Phase 2: Index Strategy
Recommend index additions and removals...

4. Reviewer Agents

Quality assurance and validation.

category: reviewer
specialization: code-review | security-review | accessibility
 
capabilities:
  - Analyze existing code/designs
  - Identify issues and improvements
  - Suggest specific fixes
  - Validate against standards
 
delegate_pattern:
  - Fixes → Builder agent
  - Specialized reviews → Other reviewers

Advanced Patterns

Trait Inheritance

Reuse common capabilities across agents:

# Define traits
traits:
  code_generator:
    tools: [Write, Edit, MultiEdit]
    quality_standards:
      - "Type safety"
      - "Error handling"
      - "Testing"
 
  backend_architect:
    patterns:
      - "Layered architecture"
      - "SOLID principles"
      - "Clean code"
 
# Use in agent
---
name: my-backend-agent
traits:
  - code_generator
  - backend_architect
---

Framework-Specific Variants

Create specialized variants for different frameworks:

# Base agent
---
name: backend-builder
variants:
  - name: fastapi-builder
    framework: fastapi
    runtime: python
 
  - name: express-builder
    framework: express
    runtime: node
 
  - name: hono-builder
    framework: hono
    runtime: bun
---

Multi-Agent Workflows

Design agents that coordinate with others:

---
name: full-stack-orchestrator
 
workflow:
  - phase: "Requirements"
    agent: business-analyst
    output: specifications
 
  - phase: "API Design"
    agent: api-designer
    input: specifications
    output: api-spec
 
  - phase: "Backend Implementation"
    agent: backend-builder
    input: api-spec
    output: backend-code
 
  - phase: "Frontend Design"
    agent: frontend-designer
    input: api-spec
    output: design-spec
 
  - phase: "Frontend Implementation"
    agent: frontend-builder
    input: design-spec
    output: frontend-code
 
  - phase: "Testing"
    agent: test-engineer
    input: [backend-code, frontend-code]
    output: test-suite
---

Best Practices

1. Clear Naming

# Good names
✅ fastapi-mcp-builder         # Clear technology and purpose
✅ dashboard-designer           # Clear domain
✅ security-auditor            # Clear role
 
# Poor names
❌ builder                     # Too generic
❌ helper                      # Vague
❌ my-agent                    # Not descriptive

2. Specific Descriptions

# Good description
✅ description: |-
  FastAPI MCP server builder that creates production-ready
  MCP servers with FastMCP framework, comprehensive testing,
  and Cloud Run deployment configurations.
 
# Poor description
❌ description: "Builds MCP servers"

3. Concrete Examples

# Good example
✅ example: "Create an MCP server for sports data with get_league_info, search_players, and get_game_stats tools"
 
# Poor example
❌ example: "Build something"

4. Quality Standards

Include measurable quality criteria:

quality_standards:
  code_quality:
    - [ ] Type annotations throughout
    - [ ] Error handling comprehensive
    - [ ] Logging with context
 
  testing:
    - [ ] Unit test coverage >80%
    - [ ] Integration tests for critical paths
    - [ ] E2E tests for main workflows
 
  documentation:
    - [ ] README with quick start
    - [ ] API documentation
    - [ ] Usage examples

5. Appropriate Tool Selection

# For code generation
tools: [Write, Edit, MultiEdit, Bash]
 
# For analysis
tools: [Read, Grep, Glob, WebFetch]
 
# For testing
tools: [Bash, Read, Write]
 
# For design
tools: [Write, Read, WebFetch]

Testing Your Agent

Manual Testing

# Test agent invocation
/agent my-agent "Create a test project"
 
# Test with different inputs
/agent my-agent "Build an API"
/agent my-agent "Build an MCP server"
 
# Test delegation
/agent my-agent "Complex task requiring multiple specialists"

Automated Testing

Create test cases for your agent:

# tests/agents/my-agent.test.yaml
agent: my-agent
 
test_cases:
  - name: "Basic functionality"
    input: "Create a simple API"
    expected_outputs:
      - "main.py"
      - "requirements.txt"
      - "README.md"
 
  - name: "With tests"
    input: "Create API with tests"
    expected_outputs:
      - "tests/"
      - "pytest.ini"
 
  - name: "Error handling"
    input: "Invalid request"
    expected_behavior: "Asks clarifying questions"

Deployment

Local Development

# Agents live in .claude/agents/
.claude/agents/
├── builders/
│   └── my-builder.md
├── designers/
│   └── my-designer.md
└── specialists/
    └── my-specialist.md

Sharing Agents

# Export agent
claude agent export my-agent > my-agent.yaml
 
# Import agent
claude agent import my-agent.yaml
 
# Publish to registry (future)
claude agent publish my-agent

Real-World Examples

Example 1: Sports API Builder

Complete agent for building sports APIs:

---
name: sports-api-builder
category: builder
specialization: sports-api-fastapi
 
description: |-
  FastAPI sports API builder that understands sports data models,
  creates CRUD endpoints for leagues/teams/players, includes
  real-time updates, and deploys to Cloud Run.
 
example: "Build a REST API for Premier League with teams, players, and live game updates"
 
tools: [Write, MultiEdit, Read, Bash]
model: sonnet
 
delegates_to:
  - database-optimizer: "For query optimization"
  - security-auditor: "For security review"
---
 
# Purpose
Build production-grade sports APIs with FastAPI...
 
## Sports Data Understanding
 
### Core Entities
- League: Competition structure
- Team: Participants in leagues
- Player: Individual athletes
- Game: Competitive events
- Stats: Performance metrics
 
### Relationships
League → Teams → Players
League → Games → Teams
Games → Stats → Players
 
## Instructions
 
### Phase 1: Data Model
Generate Pydantic models for sports entities...
 
### Phase 2: CRUD Endpoints
Create REST endpoints with proper validation...
 
### Phase 3: Real-time Updates
Add WebSocket support for live game data...

Next Steps

📚 Agent Templates Guide - Deep dive into templates
🎯 Agent Best Practices - Advanced patterns
📖 Agent Catalog - Browse existing agents

Resources

📘 Developer Handbook Agent Templates Guide