create-agent

What this skill does

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

```yaml
# 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.

```markdown
<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.

```markdown
<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.

```markdown
<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.
</commentary>
assistant: "I'll use the security-analyzer agent to check the database code."
</example>
```

### Pattern 4: Tool Usage Pattern

Agent triggers based on prior tool usage.

```markdown
<example>
Context: User made multiple edits to test files
user: "I've updated all the tests"
assistant: "Great! Let me verify test quality."
<commentary>
Multiple Edit tools used on test files. Proactively trigger test-quality-analyzer
to ensure tests follow best practices.
</commentary>
assistant: "I'll use the test-quality-analyzer agent to review the tests."
</example>
```

## System Prompt Design

The system prompt (markdown body after frontmatter) defines agent behavior. Use this proven template:

```markdown
You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility - what the agent MUST do]
2. [Secondary responsibility]
3. [Additional responsibilities...]

**Analysis Process:**
1. [Step one - be specific]
2. [Step two]
3. [Step three]
[...]

**Quality Standards:**
- [Standard 1 - measurable criteria]
- [Standard 2]

**Output Format:**
Provide results in this format:
- [What to include]
- [How to structure]

**Edge Cases:**
Handle these situations:
- [Edge case 1]: [How to handle]
- [Edge case 2]: [How to handle]

**What NOT to Do:**
- [Anti-pattern 1]
- [Anti-pattern 2]
```

### System Prompt Principles

| Principle | Good | Bad |
|-----------|------|-----|
| Be specific | "Check for SQL injection in query strings" | "Look for security issues" |
| Include examples | "Format: `## Critical Issues\n- Issue 1`" | "Use proper formatting" |
| Define boundaries | "Do NOT modify files, only analyze" | No boundaries stated |
| Provide fallbacks | "If unsure, ask for clarification" | Assume and proceed |
| Quality mechanisms | "Verify each finding with evidence" | No verification |

### Validation Requirements

System prompts must be:

- **Length**: 20-10,000 characters (ideal: 500-3,000)
- **Well-structured**: Clear sections with responsibilities, process, output format
- **Specific**: Actionable instructions, not vague guidance
- **Complete**: Handles edge cases and quality standards

## AI-Assisted Agent Generation

Use this prompt to generate agent configura