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: blue                                 # Named color for terminal display
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 one of the supported named colors: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. 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: blue
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.

### Supported Colors

Claude Code accepts these named colors (case-insensitive):

| Color | Name | Use For |
|-------|------|---------|
| 🔴 | `red` | Testing, errors, warnings |
| 🔵 | `blue` | Workflows, processes, git |
| 🟢 | `green` | Documentation, success, creation |
| 🟡 | `yellow` | Caution, validation, planning |
| 🟣 | `purple` | Meta, building, creation |
| 🟠 | `orange` | Security, alerts |
| 🩷 | `pink` | Self-improvement, feedback |
| 🩵 | `cyan` | Performance, knowledge, data |

### Format
```yaml
color: blue
```
No quotes required for color names.

### Recommended Colors by Domain

| Domain | Color | Description |
|--------|-------|-------------|
| **Meta/Building** | `purple` | Meta-programming agents |
| **GitHub/Git** | `blue` | Version control |
| **Testing/QA** | `red` | Testing agents |
| **Documentation** | `green` | Documentation |
| **Security** | `orange` | Security analysis |
| **Performance** | `cyan` | Optimization agents |
| **Research** | `purple` | Research/exploration |
| **Self-Improvement** | `pink` | Feedback tools |
| **Project Management** | `yellow` | Planning tools |

### Best Practices

1. **Consistency**: Use the same color for all agents in the same plugin
2. **Domain Matching**: Choose colors that intuitively match the agent's purpose
3. **Visibility**: All named colors are designed for good terminal visibility

## Creating an Agent

### Step 1: Gather Requirements
Ask the user:
1. What is the agent's primary purpose?
2. What tasks should it perform?
3. What tools does it need?
4. Should it have specialized knowledge or constraints?

### Step 2: Design the Agent
- Choose a clear, descriptive name (lowercase-hyphens)
- Select a color that matches the agent's domain (see Color Selection)
- Write a concise description (