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

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