surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / plugins / plugin-dev / skills / agent-development / SKILL.md

415 lines · 10.2 KBPreview CodeRaw

1	---
2	name: Agent Development
3	description: 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.
4	version: 0.1.0
5	---
6
7	# Agent Development for Claude Code Plugins
8
9	## Overview
10
11	Agents 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	---
26	name: agent-identifier
27	description: Use this agent when [triggering conditions]. Examples:
28
29	<example>
30	Context: [Situation description]
31	user: "[User request]"
32	assistant: "[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
42	model: inherit
43	color: blue
44	tools: ["Read", "Write", "Grep"]
45	---
46
47	You are [agent role description]...
48
49	Your Core Responsibilities:
50	1. [Responsibility 1]
51	2. [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
64	Agent 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
84	Defines when Claude should trigger this agent. This is the most critical field.
85
86	Must include:
87	1. Triggering conditions ("Use this agent when...")
88	2. Multiple `<example>` blocks showing usage
89	3. Context, user request, and assistant response in each example
90	4. `<commentary>` explaining why agent triggers
91
92	Format:
93	```
94	Use this agent when [conditions]. Examples:
95
96	<example>
97	Context: [Scenario description]
98	user: "[What user says]"
99	assistant: "[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
117	Which 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
129	Visual 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
144	Restrict agent to specific tools.
145
146	Format: Array of tool names
147
148	```yaml
149	tools: ["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
164	The 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
170	You are [role] specializing in [domain].
171
172	Your Core Responsibilities:
173	1. [Primary responsibility]
174	2. [Secondary responsibility]
175	3. [Additional responsibilities...]
176
177	Analysis Process:
178	1. [Step one]
179	2. [Step two]
180	3. [Step three]
181	[...]
182
183	Quality Standards:
184	- [Standard 1]
185	- [Standard 2]
186
187	Output Format:
188	Provide results in this format:
189	- [What to include]
190	- [How to structure]
191
192	Edge Cases:
193	Handle 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
221	Use this prompt pattern (extracted from Claude Code):
222
223	```
224	Create an agent configuration based on this request: "[YOUR DESCRIPTION]"
225
226	Requirements:
227	1. Extract core intent and responsibilities
228	2. Design expert persona for the domain
229	3. Create comprehensive system prompt with:
230	- Clear behavioral boundaries
231	- Specific methodologies
232	- Edge case handling
233	- Output format
234	4. Create identifier (lowercase, hyphens, 3-50 chars)
235	5. Write description with triggering conditions
236	6. Include 2-3 <example> blocks showing when to use
237
238	Return JSON with:
239	{
240	"identifier": "agent-name",
241	"whenToUse": "Use this agent when... Examples: <example>...</example>",
242	"systemPrompt": "You are..."
243	}
244	```
245
246	Then convert to agent file format with frontmatter.
247
248	See `examples/agent-creation-prompt.md` for complete template.
249
250	### Method 2: Manual Creation
251
252	1. Choose agent identifier (3-50 chars, lowercase, hyphens)
253	2. Write description with examples
254	3. Select model (usually `inherit`)
255	4. Choose color for visual identification
256	5. Define tools (if restricting access)
257	6. Write system prompt with structure above
258	7. 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	```
292	plugin-name/
293	└── agents/
294	├── analyzer.md
295	├── reviewer.md
296	└── generator.md
297	```
298
299	All `.md` files in `agents/` are auto-discovered.
300
301	### Namespacing
302
303	Agents are namespaced automatically:
304	- Single plugin: `agent-name`
305	- With subdirectories: `plugin:subdir:agent-name`
306
307	## Testing Agents
308
309	### Test Triggering
310
311	Create test scenarios to verify agent triggers correctly:
312
313	1. Write agent with specific triggering examples
314	2. Use similar phrasing to examples in test
315	3. Check Claude loads the agent
316	4. Verify agent provides expected functionality
317
318	### Test System Prompt
319
320	Ensure system prompt is complete:
321
322	1. Give agent typical task
323	2. Check it follows process steps
324	3. Verify output format is correct
325	4. Test edge cases mentioned in prompt
326	5. Confirm quality standards are met
327
328	## Quick Reference
329
330	### Minimal Agent
331
332	```markdown
333	---
334	name: simple-agent
335	description: Use this agent when... Examples: <example>...</example>
336	model: inherit
337	color: blue
338	---
339
340	You are an agent that [does X].
341
342	Process:
343	1. [Step 1]
344	2. [Step 2]
345
346	Output: [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
381	For 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
389	Working 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
396	Development 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
403	To create an agent for a plugin:
404
405	1. Define agent purpose and triggering conditions
406	2. Choose creation method (AI-assisted or manual)
407	3. Create `agents/agent-name.md` file
408	4. Write frontmatter with all required fields
409	5. Write system prompt following best practices
410	6. Include 2-4 triggering examples in description
411	7. Validate with `scripts/validate-agent.sh`
412	8. Test triggering with real scenarios
413	9. Document agent in plugin README
414
415	Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.