Build Custom Claude Code Sub-Agents

When to Use

• Creating a specialized agent for recurring tasks (code review, debugging, testing)
• Need an agent with specific tool permissions or limited scope
• Want to share reusable agents across projects or with your team
• Building domain-specific agents (data science, DevOps, security)
• Need to preserve main conversation context while delegating complex tasks

What This Skill Does

Guides you through creating custom sub-agents that:

• Specialize: Focused expertise for specific domains or tasks
• Isolate: Separate context windows prevent main conversation pollution
• Reuse: Deploy across projects and share with teams
• Control: Granular tool access and model selection per agent

Quick Start

1. Use the Built-In Agent Creator

# Run the agents command
/agents

Then:

1. Select "Create New Agent"
2. Choose project-level (.claude/agents/) or user-level (~/.claude/agents/)
3. Generate with Claude or manually define configuration
4. Save and test

2. Manual Agent Creation

Create a markdown file in .claude/agents/ (project) or ~/.claude/agents/ (user):

---
name: my-agent-name
description: Use this agent when [specific trigger condition]
tools: Read, Edit, Bash
model: sonnet
---

# Agent System Prompt

Your detailed instructions for the agent go here.

Be specific about:
- What tasks this agent handles
- How to approach problems
- What outputs to produce
- Any constraints or guardrails

3. Invoke Your Agent

Automatic: Claude detects matching tasks based on description Explicit: "Use the my-agent-name agent to [task]"

Agent Configuration

Required Fields

Field	Description	Example
name	Lowercase with hyphens	code-reviewer
description	When to use this agent (triggers routing)	Use PROACTIVELY to review code changes for quality and security

Optional Fields

Field	Description	Default
tools	Comma-separated tool list	All tools inherited
model	Model alias (sonnet/opus/haiku) or 'inherit'	Inherits from main

See: Configuration Reference

Agent Structure

.claude/agents/           # Project-level agents
├── code-reviewer.md
├── debugger.md
└── custom-agent.md

~/.claude/agents/         # User-level agents (global)
├── my-helper.md
└── data-analyzer.md

Priority: Project agents override user agents with same name

Common Agent Types

Code Reviewer

Reviews code for quality, security, and best practices

Triggers: After code changes, before commits

Debugger

Analyzes errors, identifies root causes, proposes fixes

Triggers: Test failures, runtime errors

Data Scientist

Writes SQL queries, performs analysis, generates reports

Triggers: Data questions, BigQuery tasks

See: Agent Examples

Best Practices

1. Single Responsibility: One focused task per agent
2. Descriptive Triggers: Use "PROACTIVELY" or "MUST BE USED" for automatic delegation
3. Detailed Prompts: Specific instructions yield better results
4. Limit Tools: Only grant necessary permissions
5. Version Control: Commit project agents for team collaboration

Full Guide: Best Practices

Available Tools

Sub-agents can access:

• File Operations: Read, Write, Edit, Glob, Grep
• Execution: Bash
• MCP Tools: Any installed MCP server tools

Use /agents interface to visually select tools.

Outputs

This skill helps you create:

• Agent configuration files (.md with YAML frontmatter)
• Specialized system prompts
• Tool permission configurations
• Reusable agent templates

Guardrails

• Agents must have focused, well-defined purposes
• Use lowercase-with-hyphens naming convention
• Always specify clear trigger conditions in description
• Grant minimal tool access (principle of least privilege)
• Test agents thoroughly before sharing with team

Advanced Topics

• Configuration Guide - Complete field reference
• Agent Examples - Real-world templates
• Best Practices - Design patterns
• Troubleshooting - Common issues

Triggers

This skill activates when you mention:

• "create an agent" or "build an agent"
• "sub-agent" or "subagent"
• "agent configuration"
• "Task tool" or "custom agent"
• "agent best practices"

Testing

To test your agent:

# Ask Claude to use it explicitly
"Use the [agent-name] agent to [task]"

# Or test automatic triggering
"[Describe a task matching agent's description]"

Verify:

• Agent triggers correctly
• Has necessary tool access
• Produces expected outputs
• Maintains scope/focus

---

Last Updated: 2025-10-27 Version: 1.0.0