Create Agent

# Create Agent Command

Create autonomous Claude Code agents that handle complex, multi-step tasks independently. This command provides comprehensive guidance based on official Anthropic documentation and proven patterns.

## User Input

```text
Agent Name: $1
Description: $2
```

## What Are Agents?

Agents are **autonomous subprocesses** spawned via the Task tool that:

- Handle complex, multi-step tasks independently
- Have their own isolated context window
- Return results to the parent conversation
- Can be specialized for specific domains

| Concept | Agent | Command |
|---------|-------|---------|
| **Trigger** | Claude decides based on description | User invokes with `/name` |
| **Purpose** | Autonomous work | User-initiated actions |
| **Context** | Isolated subprocess | Shared conversation |
| **File format** | `agents/*.md` | `commands/*.md` |

## Agent File Structure

Agents use a unique format combining **YAML frontmatter** with a **markdown system prompt**:

```markdown
---
name: agent-identifier
description: Use this agent when [triggering conditions]. Examples:

<example>
Context: [Situation description]
user: "[User request]"
assistant: "[How assistant should respond and use this agent]"
<commentary>
[Why this agent should be triggered]
</commentary>
</example>

<example>
[Additional example...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

You are [agent role description]...

**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]

**Analysis Process:**
[Step-by-step workflow]

**Output Format:**
[What to return]
```

## Frontmatter Fields Reference

### Required Fields

#### `name` (Required)

**Format**: Lowercase with hyphens only
**Length**: 3-50 characters
**Rules**:

- Must start and end with alphanumeric character
- Only lowercase letters, numbers, and hyphens
- No underscores, spaces, or special characters

| Valid | Invalid | Reason |
|-------|---------|--------|
| `code-reviewer` | `helper` | Too generic |
| `test-generator` | `-agent-` | Starts/ends with hyphen |
| `api-docs-writer` | `my_agent` | Underscores not allowed |
| `security-analyzer` | `ag` | Too short (<3 chars) |
| `pr-quality-reviewer` | `MyAgent` | Uppercase not allowed |

#### `description` (Required, Critical)

**The most important field** - Defines when Claude triggers the agent.

**Requirements**:

- Length: 10-5,000 characters (ideal: 200-1,000 with 2-4 examples)
- **MUST start with**: "Use this agent when..."
- **MUST include**: `<example>` blocks showing usage patterns
- Each example needs: context, user request, assistant response, commentary

**Example Block Format**:

```markdown
<example>
Context: [Describe the situation - what led to this interaction]
user: "[Exact user message or request]"
assistant: "[How Claude should respond before triggering]"
<commentary>
[Explanation of why this agent should be triggered in this scenario]
</commentary>
assistant: "[How Claude triggers the agent - 'I'll use the [agent-name] agent...']"
</example>
```

**Best Practices for Descriptions**:

- Include 2-4 concrete examples
- Show both proactive and reactive triggering scenarios
- Cover different phrasings of the same intent
- Explain reasoning in commentary
- Be specific about when NOT to use the agent

#### `model` (Required)

**Values**: `inherit`, `sonnet`, `opus`, `haiku`
**Default**: `inherit` (recommended)

| Value | Use Case | Cost |
|-------|----------|------|
| `inherit` | Use parent conversation model | Default |
| `haiku` | Fast, simple tasks | Lowest |
| `sonnet` | Balanced performance | Medium |
| `opus` | Maximum