building-agents

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

---
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

---
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

---
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)

tools: Read, Grep, Glob

Use for: Research, analysis, read-only operations

File Modification

tools: Read, Write, Edit, Grep, Glob

Use for: Code generation, file editing, refactoring

System Operations

tools: Read, Write, Edit, Grep, Glob, Bash

Use for: Testing, building, git operations, system commands

Web Access

tools: Read, Grep, Glob, WebFetch, WebSearch

Use for: Documentation lookup, external data fetching

Full Access

# 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

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

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 tasks