Agent Development

Agent Development for Claude Code Plugins

Agents are autonomous markdown files with YAML frontmatter that handle multi-step tasks independently. Agents are for autonomous work; commands are for user-initiated actions.

Workflow

• Define agent purpose and triggering conditions
• Create agents/agent-name.md with frontmatter + system prompt body
• Include 2-4 <example> blocks in description
• Validate structure (see constraints below)
• Test triggering with real scenarios
• If validation fails: check error recovery table, fix, re-validate

Agent File Template

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

<example>
Context: [Situation]
user: "[Request]"
assistant: "[Response before triggering]"
<commentary>[Why this agent triggers]</commentary>
</example>

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

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary task]
2. [Secondary task]

**Process:**
1. [Step 1]
2. [Step 2]

**Output Format:**
[What to return and how]

**Edge Cases:**
- [Case]: [How to handle]

Frontmatter Reference

| Field | Required | Format | Constraints |

|-------|----------|--------|-------------|

| name | Yes | lowercase-hyphens | 3-50 chars, start/end alphanumeric, no underscores |

| description | Yes | Text + <example> blocks | 10-5000 chars, must include triggering conditions |

| model | Yes | inherit\|sonnet\|opus\|haiku | Use inherit unless specific need |

| color | Yes | blue\|cyan\|green\|yellow\|magenta\|red | Distinct per plugin |

| tools | No | Array of tool names | Least-privilege principle; default: all tools |

| hooks | No | Array of hook configs | See hooks section |

| disallowedTools | No | Array with Task(AgentName) | Prevents specific agents from running |

Color conventions: blue/cyan = analysis/review, green = success, yellow = validation, red = security, magenta = creative.

Common tool sets:

• Read-only: ["Read", "Grep", "Glob"]
• Code generation: ["Read", "Write", "Grep"]
• Testing: ["Read", "Bash", "Grep"]

Description Field

The description must include triggering conditions and 2-4 <example> blocks. Each example needs: Context, user message, assistant response, and <commentary> explaining why the agent triggers.

Cover different triggering types across examples:

• Explicit: user directly requests the agent's function
• Proactive: agent triggers after relevant work without explicit request
• Implicit: user implies need without stating it directly

See references/triggering-examples.md for detailed patterns and templates.

Hooks

Agent-level hooks scoped to agent lifecycle:

hooks:
  - type: PreToolUse    # Validate before agent uses tools
    once: true          # Runs only once per invocation
  - type: PostToolUse   # React to agent tool results
  - type: Stop          # Cleanup when agent completes

Hooks inherit agent context. No command/prompt field needed. See ../hook-development/ for full documentation.

disallowedTools

Prevent specific agents from being invoked:

disallowedTools: ["Task(SWEAgent)", "Task(ExperimentalAgent)"]

Also configurable in settings.json and via --disallowedTools CLI flag.

System Prompt Guidelines

The markdown body below the frontmatter becomes the agent's system prompt. Write in second person ("You are...", "You will...").

Required sections: Role description, Core Responsibilities, Process steps, Output Format.

Recommended sections: Quality Standards, Edge Cases.

Keep prompts under 10,000 characters. Optimal range: 500-3,000 characters. If longer, extract reference data into separate files.

See references/system-prompt-design.md for analysis, generation, validation, and orchestration prompt patterns.

Agent Organization

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

All .md files in agents/ are auto-discovered. Agents are namespaced automatically: agent-name (single plugin) or plugin:subdir:agent-name (with subdirectories).

Best Practices

• Include 2-4 concrete <example> blocks with varied phrasings in description
• Use inherit for model unless a specific model is required
• Apply least-privilege tool access
• Assign distinct colors per agent within a plugin
• Write specific, structured system prompts with clear process steps
• Define output format explicitly
• Test triggering with real scenarios before shipping

Error Recovery

| Problem | Fix |

|---------|-----|

| Agent not triggering | Add more <example> blocks with varied phrasings; verify keywords match user intent |

| Name validation fails | Ensure 3-50 chars, lowercase + hyphens only, starts/ends alphanumeric |

| System prompt too long | Keep under 10,000 chars; extract reference data into separate files |

| Agent uses wrong tools | Add explicit tools array; verify tool names match exactly |

| Agent color not showing | Confirm color is one of: blue, cyan, green, yellow, magenta, red |

| Description too vague | Add triggering conditions and concrete <example> blocks with <commentary> |

| Agent triggers incorrectly | Make examples more specific; add negative-case commentary |

Additional Resources

• references/system-prompt-design.md - Prompt patterns for analysis, generation, validation, orchestration agents
• references/triggering-examples.md - Example formats and triggering best practices
• references/agent-creation-system-prompt.md - The exact prompt from Claude Code
• examples/agent-creation-prompt.md - AI-assisted agent generation template
• examples/complete-agent-examples.md - Full agent examples for different use cases
• scripts/validate-agent.sh - Validate agent file structure