agent-development

What this skill does

# Agent Development for Claude Code Plugins

## Overview

Agents are autonomous subprocesses that handle complex, multi-step tasks independently. Master agent structure, triggering conditions, and system prompt design to create powerful autonomous capabilities.

**Key concepts:**

- Agents are FOR autonomous work, commands are FOR user-initiated actions
- Markdown file format with YAML frontmatter
- Triggering via description field with examples
- System prompt defines agent behavior
- Model and color customization

> **Important - Field Name Difference:** Agents use `tools` to restrict tool access. Skills use `allowed-tools` for the same purpose. Don't confuse these when switching between component types.
>
> **Note on Official Documentation:** The `color` field documented in this skill is supported by Claude Code and is generated by the built-in `/agents` command, but it is not yet reflected in the [official sub-agents documentation](https://docs.claude.com/en/docs/claude-code/sub-agents). See [anthropics/claude-code#8501](https://github.com/anthropics/claude-code/issues/8501) for tracking. The [plugins-reference.md](https://docs.claude.com/en/docs/claude-code/plugins-reference) may show an older agent format using a `capabilities` field; for Claude Code plugins, prefer the structure documented in this skill which uses `tools` for tool restrictions.

## Quick Start

Minimal working agent (copy-paste ready):

```markdown
---
name: my-reviewer
description: Use this agent when the user asks to review code. Examples:

<example>
Context: User wrote new code
user: "Review my changes"
assistant: "I'll use the my-reviewer agent to analyze the code."
<commentary>
Code review request triggers the agent.
</commentary>
</example>

model: inherit
color: blue
---

You are a code reviewer. Analyze code for issues and provide feedback.

**Process:**

1. Read the code
2. Identify issues
3. Provide recommendations

**Output:** Summary with file:line references for each finding.
```

For complete format with all options, see [Agent File Structure](#agent-file-structure).

## When to Use Agents vs Commands vs Skills

| Component    | Best For                    | Triggering                       | Example Use Case                    |
| ------------ | --------------------------- | -------------------------------- | ----------------------------------- |
| **Agents**   | Autonomous multi-step tasks | Proactive or description-matched | Code review after implementation    |
| **Commands** | User-initiated actions      | Explicit `/command` invocation   | `/deploy production`                |
| **Skills**   | Knowledge and guidance      | Model-invoked based on context   | Domain expertise for PDF processing |

> **See also:** For command development, load the `command-development` skill. For skill development, load the `skill-development` skill.

### Choose Agents When

- Task requires autonomous, multi-step execution
- Proactive triggering after certain events is desired
- Specialized subprocess with focused tools needed
- Work should happen in the background or as a subagent

### Choose Commands When

- User should explicitly trigger the action
- Task has clear start/end with specific inputs
- Action should not happen automatically
- Workflow requires user confirmation at each step

### Choose Skills When

- Providing knowledge or procedural guidance
- Extending Claude's domain expertise
- No autonomous execution needed
- Information should be available contextually on-demand

## Agent File Structure

### Complete Format

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

### name (required)

Agent identifier used for namespacing and invocation.

**Format:** lowercase, numbers, hyphens only
**Length:** 3-50 characters
**Pattern:** Must start and end with alphanumeric

**Good examples:**

- `code-reviewer`
- `test-generator`
- `api-docs-writer`
- `security-analyzer`

**Bad examples:**

- `helper` (too generic)
- `-agent-` (starts/ends with hyphen)
- `my_agent` (underscores not allowed)
- `ag` (too short, < 3 chars)

### description (required)

Defines when Claude should trigger this agent. **This is the most critical field.**

**Must include:**

1. Triggering conditions ("Use this agent when...")
2. Multiple `<example>` blocks showing usage
3. Context, user request, and assistant response in each example
4. `<commentary>` explaining why agent triggers

**Format:**

```
Use this agent when [conditions]. Examples:

<example>
Context: [Scenario description]
user: "[What user says]"
assistant: "[How Claude should respond]"
<commentary>
[Why this agent is appropriate]
</commentary>
</example>

[More examples...]
```

**Best practices:**

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

### model (required)

Which model the agent should use.

**Options:**

- `inherit` - Use same model as parent (recommended)
- `sonnet` - Claude Sonnet (balanced)
- `opus` - Claude Opus (most capable, expensive)
- `haiku` - Claude Haiku (fast, cheap)

**When to choose:**

- `haiku` - Fast, simple tasks; quick analysis; cost-sensitive operations
- `sonnet` - Balanced performance; most use cases (default recommendation)
- `opus` - Complex reasoning; detailed analysis; highest capability needed

**Recommendation:** Use `inherit` (recommended default) unless the agent specifically needs:

- `haiku` for fast, cost-sensitive operations
- `opus` for complex reasoning requiring maximum capability

### color (required)

Visual identifier for agent in UI.

> **Note:** This field is supported by Claude Code but not yet in official documentation. See the [Overview note](#overview) for details.

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

**Guidelines:**

- Choose distinct colors for different agents in same plugin
- Use consistent colors for similar agent types
- Blue/cyan: Analysis, review
- Green: Success-oriented tasks
- Yellow: Caution, validation
- Red: Critical, security
- Magenta: Creative, generation

### tools (optional)

Restrict agent to specific tools.

**Format:** Comma-separated tool names

```yaml
tools: Read, Write, Grep, Bash
```

**Default:** If omitted, agent has access to all tools

**Best practice:** Limit tools to minimum needed (principle of least privilege)

**Common tool sets:**

- Read-only analysis: `Read, Grep, Glob`
- Code generation: `Read, Write, Grep`
- Testing: `Read, Bash, Grep`
- Full access: Omit field entirely

> **Important:** Agents use `tools` while Skills use `allowed-tools`. The field names differ between component types. For skill tool restrictions, see the `skill-development` skill.

### disallowedTools (optional)

Denylist complement to `tools`. Block specific tools while allowing all others:

```yaml
disallowedTools: Bash, Write
```

**Format:** Comma-separated tool names

**Default:** No tools blocked

| Field             | Approach  | Use When                                |
| ----------------- | --------- | --------------------------------------- |
| `tools`           | Allowlist | Few tools needed, restrict to minimum   |
| `disallowedTools` | Denylist  | Most tools needed, block specific risks |

**Best practice:** Prefer `tools` (allowlist) for tighter security. Use `disallowedTools` when an agent needs br