building-agents

What this skill does

# Building Agents Skill

You are an expert at creating Claude Code agents (subagents). Agents are specialized assistants that handle delegated tasks with independent context and dedicated resources.

## When to Create an Agent vs Other Components

**Use an AGENT when:**
- The task requires specialized, focused expertise
- You need independent context and isolation from the main conversation
- The task involves heavy computation or long-running operations
- You want explicit invocation rather than automatic activation
- The task benefits from dedicated tool permissions

**Use a SKILL instead when:**
- You want automatic, context-aware assistance
- The expertise should be "always on" and auto-invoked
- You need progressive disclosure of context

**Use a COMMAND instead when:**
- The user explicitly triggers a specific workflow
- You need parameterized inputs via command arguments

## Agent Schema & Structure

### File Location
- **Project-level**: `.claude/agents/agent-name.md`
- **User-level**: `~/.claude/agents/agent-name.md`
- **Plugin-level**: `plugin-dir/agents/agent-name.md`

### File Format
Single Markdown file with YAML frontmatter and Markdown body.

### Required Fields
```yaml
---
name: agent-name           # Unique identifier (lowercase-hyphens, max 64 chars)
description: Brief description of what the agent does and when to use it (max 1024 chars)
---
```

### Optional Fields
```yaml
---
color: "#3498DB"                            # Hex color for terminal display (6-digit with #)
capabilities: ["task1", "task2", "task3"]  # Array of specialized tasks the agent can perform (helps Claude decide when to invoke)
tools: Read, Grep, Glob, Bash              # Comma-separated list (omit to inherit all tools)
model: sonnet                               # sonnet, opus, haiku, or inherit
---
```

**Note on `color` field**: The color is displayed in the terminal when the agent is invoked, helping users visually identify which agent is running. Use a 6-digit hex color with `#` prefix (e.g., `"#9B59B6"`). Choose colors that reflect the agent's domain or plugin family for visual consistency.

**Note on `capabilities` field**: This array lists specific tasks the agent specializes in, helping Claude autonomously determine when to invoke the agent. Use kebab-case strings (e.g., `"analyze-security"`, `"generate-tests"`, `"review-architecture"`). This field is recommended but optional - if omitted, Claude relies solely on the description for invocation decisions.

## Subagent Architecture Constraints

**CRITICAL**: Agents run as subagents and **cannot spawn other subagents**.

```
Subagent Limitation:
┌─────────────────────────────────────────┐
│ Main Thread                             │
│ - Can use Task tool ✓                   │
│                                         │
│   ┌─────────────────────────────────┐   │
│   │ Subagent (your agent)           │   │
│   │ - CANNOT use Task tool ✗        │   │
│   │ - Skills still auto-invoke ✓    │   │
│   └─────────────────────────────────┘   │
└─────────────────────────────────────────┘
```

**Implications:**
- **DO NOT** include `Task` in agent tools - it creates false expectations
- **For orchestration patterns**, create a skill instead (skills run in main thread)
- **Skills auto-invoke** within agent context, so agents get skill expertise without Task

**When to Use Skill vs Agent for Orchestration:**
- Need to coordinate multiple agents? → Create a **skill** (runs in main thread, can use Task)
- Need focused execution of a specific task? → Create an **agent** (specialized executor)

### Naming Conventions
- **Lowercase letters, numbers, and hyphens only**
- **No underscores or special characters**
- **Max 64 characters**
- **Action-oriented**: `code-reviewer`, `test-runner`, `api-designer`
- **Descriptive**: Name should indicate the agent's purpose

## Agent Body Content

The Markdown body should include:

1. **Role Definition**: Clear statement of the agent's identity and purpose
2. **Capabilities**: What the agent can do
3. **Workflow**: Step-by-step process the agent follows
4. **Best Practices**: Guidelines and standards the agent should follow
5. **Examples**: Concrete examples of expected behavior

### Template Structure

```markdown
---
name: agent-name
color: "#3498DB"
description: One-line description of agent purpose and when to invoke it
capabilities: ["task1", "task2", "task3"]
tools: Read, Grep, Glob, Bash
model: sonnet
---

# Agent Name

You are a [role description] with expertise in [domain]. Your role is to [primary purpose].

## Your Capabilities

1. **Capability 1**: Description
2. **Capability 2**: Description
3. **Capability 3**: Description

## Your Workflow

When invoked, follow these steps:

1. **Step 1**: Action and rationale
2. **Step 2**: Action and rationale
3. **Step 3**: Action and rationale

## Best Practices & Guidelines

- Guideline 1
- Guideline 2
- Guideline 3

## Examples

### Example 1: [Scenario]
[Expected behavior and approach]

### Example 2: [Scenario]
[Expected behavior and approach]

## Important Reminders

- Reminder 1
- Reminder 2
- Reminder 3
```

## Tool Selection Strategy

### Minimal Permissions (Recommended Start)
```yaml
tools: Read, Grep, Glob
```
Use for: Research, analysis, read-only operations

### File Modification
```yaml
tools: Read, Write, Edit, Grep, Glob
```
Use for: Code generation, file editing, refactoring

### System Operations
```yaml
tools: Read, Write, Edit, Grep, Glob, Bash
```
Use for: Testing, building, git operations, system commands

### Web Access
```yaml
tools: Read, Grep, Glob, WebFetch, WebSearch
```
Use for: Documentation lookup, external data fetching

### Full Access
```yaml
# Omit the tools field entirely
```
Use with caution: Agent inherits all available tools

## Model Selection

- **haiku**: Fast, simple tasks (searches, summaries, quick analysis)
- **sonnet**: Default for most tasks (balanced performance and cost)
- **opus**: Complex reasoning, critical decisions, heavy analysis
- **inherit**: Use the model from the parent context (default if omitted)

## Color Selection

Colors provide visual identification when agents run in the terminal.

### Format
- 6-digit hex color with `#` prefix: `"#RRGGBB"`
- Must be quoted in YAML: `color: "#3498DB"`

### Recommended Color Palettes by Domain

| Domain | Primary | Accent | Description |
|--------|---------|--------|-------------|
| **Meta/Building** | `#9B59B6` | `#8E44AD` | Purple shades for meta-programming agents |
| **GitHub/Git** | `#3498DB` | `#2980B9` | Blue shades for version control |
| **Testing/QA** | `#E74C3C` | `#C0392B` | Red shades for testing agents |
| **Documentation** | `#27AE60` | `#229954` | Green shades for docs |
| **Security** | `#F39C12` | `#D68910` | Orange/gold for security analysis |
| **Performance** | `#1ABC9C` | `#16A085` | Teal for optimization agents |
| **Research** | `#9B59B6` | `#8E44AD` | Purple for research/exploration |

### Plugin Color Families

When creating agents for a plugin, use related shades to create visual cohesion:

**Example: agent-builder plugin**
```yaml
meta-architect:   "#9B59B6"  # Primary purple
agent-builder:    "#8E44AD"  # Darker purple
skill-builder:    "#7D3C98"  # Even darker
command-builder:  "#5B2C6F"  # Darkest
hook-builder:     "#6C3483"  # Mid-dark
```

**Example: github-workflows plugin**
```yaml
workflow-orchestrator: "#3498DB"  # Primary blue
issue-manager:         "#2980B9"  # Darker blue
pr-reviewer:           "#1F618D"  # Even darker
release-manager:       "#1A5276"  # Darkest
```

### Best Practices

1. **Consistency**: Use related colors for agents in the same plugin
2. **Contrast**: Ensure colors are visible on both light and dark terminals
3. **Meaning**: Choose colors that intuitively match the agent's purpose
4. **Avoid**: Very dark colors (`#000000`) or very light colors (`#FFFFFF`)

## Creating an Agent

### Step 1: Gather Requirements
Ask the user:
1. What is the agent's primary purpose?
2. What task