/create-agent

name: create-agent
description: Comprehensive guide for creating Claude Code agents with proper structure, triggering conditions, system prompts, and validation - combines official Anthropic best practices with proven patterns

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

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

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

<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 capability, complex reasoning | Highest |

**Recommendation**: Use `inherit` unless you have a specific reason to override.

`color` (Required)

**Purpose**: Visual indicator in UI to distinguish agents

**Values**: `blue`, `cyan`, `green`, `yellow`, `magenta`, `red`

**Best Practice**: Use different colors for different agents in the same plugin to distinguish them visually.

Optional Fields

`tools` (Optional)

**Purpose**: Restrict available tools (principle of least privilege) **Format**: Array of tool names **Default**: All tools available

# Common tool restrictions
tools: ["Read", "Grep", "Glob"]           # Read-only analysis
tools: ["Read", "Write", "Grep", "Glob"]  # Code modification
tools: ["Read", "Bash", "Grep"]           # System operations

**Security Principle**: Only grant tools the agent actually needs.

Triggering Patterns

Pattern 1: Explicit Request

User directly asks for the agent's function.

<example>
Context: User wants code reviewed
user: "Can you review my code changes?"
assistant: "I'll use the code-reviewer agent to analyze the changes."
<commentary>
User explicitly requested code review, trigger the code-reviewer agent.
</commentary>
</example>

Pattern 2: Implicit Need

Agent needed based on context, not explicit request.

<example>
Context: User mentions code is hard to understand
user: "This code is confusing and hard to follow"
assistant: "I can help improve the code clarity."
<commentary>
User indicates complexity issues. Trigger code-simplifier agent to refactor
for better readability.
</commentary>
assistant: "I'll use the code-simplifier agent to suggest improvements."
</example>

Pattern 3: Proactive Trigger

Agent triggers after completing relevant work without explicit request.

<example>
Context: User just implemented database queries
user: "I've added the user search functionality"
assistant: "Great! Let me review it for security."
<commentary>
Database code written. Proactively trigger security-analyzer to check
for SQL injection and other database security issues