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

1. Define agent purpose and triggering conditions
2. Create agents/agent-name.md with frontmatter + system prompt body
3. Include 2-4 <example> blocks in description
4. Validate structure (see constraints below)
5. Test triggering with real scenarios
6. 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

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

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