1---
2name: Agent Development
3description: This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
4version: 0.1.0
5---
6 
7# Agent Development for Claude Code Plugins
8 
9## Overview
10 
11Agents are autonomous subprocesses that handle complex, multi-step tasks independently. Understanding agent structure, triggering conditions, and system prompt design enables creating powerful autonomous capabilities.
12 
13**Key concepts:**
14- Agents are FOR autonomous work, commands are FOR user-initiated actions
15- Markdown file format with YAML frontmatter
16- Triggering via description field with examples
17- System prompt defines agent behavior
18- Model and color customization
19 
20## Agent File Structure
21 
22### Complete Format
23 
24```markdown
25---
26name: agent-identifier
27description: Use this agent when [triggering conditions]. Examples:
28 
29<example>
30Context: [Situation description]
31user: "[User request]"
32assistant: "[How assistant should respond and use this agent]"
33<commentary>
34[Why this agent should be triggered]
35</commentary>
36</example>
37 
38<example>
39[Additional example...]
40</example>
41 
42model: inherit
43color: blue
44tools: ["Read", "Write", "Grep"]
45---
46 
47You are [agent role description]...
48 
49**Your Core Responsibilities:**
501. [Responsibility 1]
512. [Responsibility 2]
52 
53**Analysis Process:**
54[Step-by-step workflow]
55 
56**Output Format:**
57[What to return]
58```
59 
60## Frontmatter Fields
61 
62### name (required)
63 
64Agent identifier used for namespacing and invocation.
65 
66**Format:** lowercase, numbers, hyphens only
67**Length:** 3-50 characters
68**Pattern:** Must start and end with alphanumeric
69 
70**Good examples:**
71- `code-reviewer`
72- `test-generator`
73- `api-docs-writer`
74- `security-analyzer`
75 
76**Bad examples:**
77- `helper` (too generic)
78- `-agent-` (starts/ends with hyphen)
79- `my_agent` (underscores not allowed)
80- `ag` (too short, < 3 chars)
81 
82### description (required)
83 
84Defines when Claude should trigger this agent. **This is the most critical field.**
85 
86**Must include:**
871. Triggering conditions ("Use this agent when...")
882. Multiple `<example>` blocks showing usage
893. Context, user request, and assistant response in each example
904. `<commentary>` explaining why agent triggers
91 
92**Format:**
93```
94Use this agent when [conditions]. Examples:
95 
96<example>
97Context: [Scenario description]
98user: "[What user says]"
99assistant: "[How Claude should respond]"
100<commentary>
101[Why this agent is appropriate]
102</commentary>
103</example>
104 
105[More examples...]
106```
107 
108**Best practices:**
109- Include 2-4 concrete examples
110- Show proactive and reactive triggering
111- Cover different phrasings of same intent
112- Explain reasoning in commentary
113- Be specific about when NOT to use the agent
114 
115### model (required)
116 
117Which model the agent should use.
118 
119**Options:**
120- `inherit` - Use same model as parent (recommended)
121- `sonnet` - Claude Sonnet (balanced)
122- `opus` - Claude Opus (most capable, expensive)
123- `haiku` - Claude Haiku (fast, cheap)
124 
125**Recommendation:** Use `inherit` unless agent needs specific model capabilities.
126 
127### color (required)
128 
129Visual identifier for agent in UI.
130 
131**Options:** `blue`, `cyan`, `green`, `yellow`, `magenta`, `red`
132 
133**Guidelines:**
134- Choose distinct colors for different agents in same plugin
135- Use consistent colors for similar agent types
136- Blue/cyan: Analysis, review
137- Green: Success-oriented tasks
138- Yellow: Caution, validation
139- Red: Critical, security
140- Magenta: Creative, generation
141 
142### tools (optional)
143 
144Restrict agent to specific tools.
145 
146**Format:** Array of tool names
147 
148```yaml
149tools: ["Read", "Write", "Grep", "Bash"]
150```
151 
152**Default:** If omitted, agent has access to all tools
153 
154**Best practice:** Limit tools to minimum needed (principle of least privilege)
155 
156**Common tool sets:**
157- Read-only analysis: `["Read", "Grep", "Glob"]`
158- Code generation: `["Read", "Write", "Grep"]`
159- Testing: `["Read", "Bash", "Grep"]`
160- Full access: Omit field or use `["*"]`
161 
162## System Prompt Design
163 
164The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.
165 
166### Structure
167 
168**Standard template:**
169```markdown
170You are [role] specializing in [domain].
171 
172**Your Core Responsibilities:**
1731. [Primary responsibility]
1742. [Secondary responsibility]
1753. [Additional responsibilities...]
176 
177**Analysis Process:**
1781. [Step one]
1792. [Step two]
1803. [Step three]
181[...]
182 
183**Quality Standards:**
184- [Standard 1]
185- [Standard 2]
186 
187**Output Format:**
188Provide results in this format:
189- [What to include]
190- [How to structure]
191 
192**Edge Cases:**
193Handle these situations:
194- [Edge case 1]: [How to handle]
195- [Edge case 2]: [How to handle]
196```
197 
198### Best Practices
199 
200✅ **DO:**
201- Write in second person ("You are...", "You will...")
202- Be specific about responsibilities
203- Provide step-by-step process
204- Define output format
205- Include quality standards
206- Address edge cases
207- Keep under 10,000 characters
208 
209❌ **DON'T:**
210- Write in first person ("I am...", "I will...")
211- Be vague or generic
212- Omit process steps
213- Leave output format undefined
214- Skip quality guidance
215- Ignore error cases
216 
217## Creating Agents
218 
219### Method 1: AI-Assisted Generation
220 
221Use this prompt pattern (extracted from Claude Code):
222 
223```
224Create an agent configuration based on this request: "[YOUR DESCRIPTION]"
225 
226Requirements:
2271. Extract core intent and responsibilities
2282. Design expert persona for the domain
2293. Create comprehensive system prompt with:
230   - Clear behavioral boundaries
231   - Specific methodologies
232   - Edge case handling
233   - Output format
2344. Create identifier (lowercase, hyphens, 3-50 chars)
2355. Write description with triggering conditions
2366. Include 2-3 <example> blocks showing when to use
237 
238Return JSON with:
239{
240  "identifier": "agent-name",
241  "whenToUse": "Use this agent when... Examples: <example>...</example>",
242  "systemPrompt": "You are..."
243}
244```
245 
246Then convert to agent file format with frontmatter.
247 
248See `examples/agent-creation-prompt.md` for complete template.
249 
250### Method 2: Manual Creation
251 
2521. Choose agent identifier (3-50 chars, lowercase, hyphens)
2532. Write description with examples
2543. Select model (usually `inherit`)
2554. Choose color for visual identification
2565. Define tools (if restricting access)
2576. Write system prompt with structure above
2587. Save as `agents/agent-name.md`
259 
260## Validation Rules
261 
262### Identifier Validation
263 
264```
265✅ Valid: code-reviewer, test-gen, api-analyzer-v2
266❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)
267```
268 
269**Rules:**
270- 3-50 characters
271- Lowercase letters, numbers, hyphens only
272- Must start and end with alphanumeric
273- No underscores, spaces, or special characters
274 
275### Description Validation
276 
277**Length:** 10-5,000 characters
278**Must include:** Triggering conditions and examples
279**Best:** 200-1,000 characters with 2-4 examples
280 
281### System Prompt Validation
282 
283**Length:** 20-10,000 characters
284**Best:** 500-3,000 characters
285**Structure:** Clear responsibilities, process, output format
286 
287## Agent Organization
288 
289### Plugin Agents Directory
290 
291```
292plugin-name/
293└── agents/
294    ├── analyzer.md
295    ├── reviewer.md
296    └── generator.md
297```
298 
299All `.md` files in `agents/` are auto-discovered.
300 
301### Namespacing
302 
303Agents are namespaced automatically:
304- Single plugin: `agent-name`
305- With subdirectories: `plugin:subdir:agent-name`
306 
307## Testing Agents
308 
309### Test Triggering
310 
311Create test scenarios to verify agent triggers correctly:
312 
3131. Write agent with specific triggering examples
3142. Use similar phrasing to examples in test
3153. Check Claude loads the agent
3164. Verify agent provides expected functionality
317 
318### Test System Prompt
319 
320Ensure system prompt is complete:
321 
3221. Give agent typical task
3232. Check it follows process steps
3243. Verify output format is correct
3254. Test edge cases mentioned in prompt
3265. Confirm quality standards are met
327 
328## Quick Reference
329 
330### Minimal Agent
331 
332```markdown
333---
334name: simple-agent
335description: Use this agent when... Examples: <example>...</example>
336model: inherit
337color: blue
338---
339 
340You are an agent that [does X].
341 
342Process:
3431. [Step 1]
3442. [Step 2]
345 
346Output: [What to provide]
347```
348 
349### Frontmatter Fields Summary
350 
351| Field | Required | Format | Example |
352|-------|----------|--------|---------|
353| name | Yes | lowercase-hyphens | code-reviewer |
354| description | Yes | Text + examples | Use when... <example>... |
355| model | Yes | inherit/sonnet/opus/haiku | inherit |
356| color | Yes | Color name | blue |
357| tools | No | Array of tool names | ["Read", "Grep"] |
358 
359### Best Practices
360 
361**DO:**
362- ✅ Include 2-4 concrete examples in description
363- ✅ Write specific triggering conditions
364- ✅ Use `inherit` for model unless specific need
365- ✅ Choose appropriate tools (least privilege)
366- ✅ Write clear, structured system prompts
367- ✅ Test agent triggering thoroughly
368 
369**DON'T:**
370- ❌ Use generic descriptions without examples
371- ❌ Omit triggering conditions
372- ❌ Give all agents same color
373- ❌ Grant unnecessary tool access
374- ❌ Write vague system prompts
375- ❌ Skip testing
376 
377## Additional Resources
378 
379### Reference Files
380 
381For detailed guidance, consult:
382 
383- **`references/system-prompt-design.md`** - Complete system prompt patterns
384- **`references/triggering-examples.md`** - Example formats and best practices
385- **`references/agent-creation-system-prompt.md`** - The exact prompt from Claude Code
386 
387### Example Files
388 
389Working examples in `examples/`:
390 
391- **`agent-creation-prompt.md`** - AI-assisted agent generation template
392- **`complete-agent-examples.md`** - Full agent examples for different use cases
393 
394### Utility Scripts
395 
396Development tools in `scripts/`:
397 
398- **`validate-agent.sh`** - Validate agent file structure
399- **`test-agent-trigger.sh`** - Test if agent triggers correctly
400 
401## Implementation Workflow
402 
403To create an agent for a plugin:
404 
4051. Define agent purpose and triggering conditions
4062. Choose creation method (AI-assisted or manual)
4073. Create `agents/agent-name.md` file
4084. Write frontmatter with all required fields
4095. Write system prompt following best practices
4106. Include 2-4 triggering examples in description
4117. Validate with `scripts/validate-agent.sh`
4128. Test triggering with real scenarios
4139. Document agent in plugin README
414 
415Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.
416