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

Claudedocs: Add skills frontmatter field documentation 13530b1 · on Dec 11, 2025 History

446 lines · 11.1 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	skills: skill-name-1, skill-name-2
46	---
47
48	You are [agent role description]...
49
50	Your Core Responsibilities:
51	1. [Responsibility 1]
52	2. [Responsibility 2]
53
54	Analysis Process:
55	[Step-by-step workflow]
56
57	Output Format:
58	[What to return]
59	```
60
61	## Frontmatter Fields
62
63	### name (required)
64
65	Agent identifier used for namespacing and invocation.
66
67	Format: lowercase, numbers, hyphens only
68	Length: 3-50 characters
69	Pattern: Must start and end with alphanumeric
70
71	Good examples:
72	- `code-reviewer`
73	- `test-generator`
74	- `api-docs-writer`
75	- `security-analyzer`
76
77	Bad examples:
78	- `helper` (too generic)
79	- `-agent-` (starts/ends with hyphen)
80	- `my_agent` (underscores not allowed)
81	- `ag` (too short, < 3 chars)
82
83	### description (required)
84
85	Defines when Claude should trigger this agent. This is the most critical field.
86
87	Must include:
88	1. Triggering conditions ("Use this agent when...")
89	2. Multiple `<example>` blocks showing usage
90	3. Context, user request, and assistant response in each example
91	4. `<commentary>` explaining why agent triggers
92
93	Format:
94	```
95	Use this agent when [conditions]. Examples:
96
97	<example>
98	Context: [Scenario description]
99	user: "[What user says]"
100	assistant: "[How Claude should respond]"
101	<commentary>
102	[Why this agent is appropriate]
103	</commentary>
104	</example>
105
106	[More examples...]
107	```
108
109	Best practices:
110	- Include 2-4 concrete examples
111	- Show proactive and reactive triggering
112	- Cover different phrasings of same intent
113	- Explain reasoning in commentary
114	- Be specific about when NOT to use the agent
115
116	### model (required)
117
118	Which model the agent should use.
119
120	Options:
121	- `inherit` - Use same model as parent (recommended)
122	- `sonnet` - Claude Sonnet (balanced)
123	- `opus` - Claude Opus (most capable, expensive)
124	- `haiku` - Claude Haiku (fast, cheap)
125
126	Recommendation: Use `inherit` unless agent needs specific model capabilities.
127
128	### color (required)
129
130	Visual identifier for agent in UI.
131
132	Options: `blue`, `cyan`, `green`, `yellow`, `magenta`, `red`
133
134	Guidelines:
135	- Choose distinct colors for different agents in same plugin
136	- Use consistent colors for similar agent types
137	- Blue/cyan: Analysis, review
138	- Green: Success-oriented tasks
139	- Yellow: Caution, validation
140	- Red: Critical, security
141	- Magenta: Creative, generation
142
143	### tools (optional)
144
145	Restrict agent to specific tools.
146
147	Format: Array of tool names
148
149	```yaml
150	tools: ["Read", "Write", "Grep", "Bash"]
151	```
152
153	Default: If omitted, agent has access to all tools
154
155	Best practice: Limit tools to minimum needed (principle of least privilege)
156
157	Common tool sets:
158	- Read-only analysis: `["Read", "Grep", "Glob"]`
159	- Code generation: `["Read", "Write", "Grep"]`
160	- Testing: `["Read", "Bash", "Grep"]`
161	- Full access: Omit field or use `["*"]`
162
163	### skills (optional)
164
165	Declare skills to auto-load when this agent is invoked.
166
167	Format: Comma-separated list of skill names
168
169	```yaml
170	skills: database-migration, postgres-ops
171	```
172
173	Purpose: Ensures specific skills are always available to the agent, regardless of context matching. This is especially useful for:
174	- Skills that should persist across context compaction
175	- Specialized agents that always need certain domain knowledge
176	- Ensuring consistent agent behavior with required skills
177
178	Example:
179	```yaml
180	---
181	name: db-admin
182	description: Use this agent for database administration tasks...
183	model: inherit
184	color: cyan
185	tools: ["Bash", "Read", "Write"]
186	skills: database-migration, sql-optimization
187	---
188	```
189
190	Best practice: Only declare skills essential to the agent's core function. Let context-triggered skills load naturally for optional capabilities.
191
192	## System Prompt Design
193
194	The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.
195
196	### Structure
197
198	Standard template:
199	```markdown
200	You are [role] specializing in [domain].
201
202	Your Core Responsibilities:
203	1. [Primary responsibility]
204	2. [Secondary responsibility]
205	3. [Additional responsibilities...]
206
207	Analysis Process:
208	1. [Step one]
209	2. [Step two]
210	3. [Step three]
211	[...]
212
213	Quality Standards:
214	- [Standard 1]
215	- [Standard 2]
216
217	Output Format:
218	Provide results in this format:
219	- [What to include]
220	- [How to structure]
221
222	Edge Cases:
223	Handle these situations:
224	- [Edge case 1]: [How to handle]
225	- [Edge case 2]: [How to handle]
226	```
227
228	### Best Practices
229
230	✅ DO:
231	- Write in second person ("You are...", "You will...")
232	- Be specific about responsibilities
233	- Provide step-by-step process
234	- Define output format
235	- Include quality standards
236	- Address edge cases
237	- Keep under 10,000 characters
238
239	❌ DON'T:
240	- Write in first person ("I am...", "I will...")
241	- Be vague or generic
242	- Omit process steps
243	- Leave output format undefined
244	- Skip quality guidance
245	- Ignore error cases
246
247	## Creating Agents
248
249	### Method 1: AI-Assisted Generation
250
251	Use this prompt pattern (extracted from Claude Code):
252
253	```
254	Create an agent configuration based on this request: "[YOUR DESCRIPTION]"
255
256	Requirements:
257	1. Extract core intent and responsibilities
258	2. Design expert persona for the domain
259	3. Create comprehensive system prompt with:
260	- Clear behavioral boundaries
261	- Specific methodologies
262	- Edge case handling
263	- Output format
264	4. Create identifier (lowercase, hyphens, 3-50 chars)
265	5. Write description with triggering conditions
266	6. Include 2-3 <example> blocks showing when to use
267
268	Return JSON with:
269	{
270	"identifier": "agent-name",
271	"whenToUse": "Use this agent when... Examples: <example>...</example>",
272	"systemPrompt": "You are..."
273	}
274	```
275
276	Then convert to agent file format with frontmatter.
277
278	See `examples/agent-creation-prompt.md` for complete template.
279
280	### Method 2: Manual Creation
281
282	1. Choose agent identifier (3-50 chars, lowercase, hyphens)
283	2. Write description with examples
284	3. Select model (usually `inherit`)
285	4. Choose color for visual identification
286	5. Define tools (if restricting access)
287	6. Write system prompt with structure above
288	7. Save as `agents/agent-name.md`
289
290	## Validation Rules
291
292	### Identifier Validation
293
294	```
295	✅ Valid: code-reviewer, test-gen, api-analyzer-v2
296	❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)
297	```
298
299	Rules:
300	- 3-50 characters
301	- Lowercase letters, numbers, hyphens only
302	- Must start and end with alphanumeric
303	- No underscores, spaces, or special characters
304
305	### Description Validation
306
307	Length: 10-5,000 characters
308	Must include: Triggering conditions and examples
309	Best: 200-1,000 characters with 2-4 examples
310
311	### System Prompt Validation
312
313	Length: 20-10,000 characters
314	Best: 500-3,000 characters
315	Structure: Clear responsibilities, process, output format
316
317	## Agent Organization
318
319	### Plugin Agents Directory
320
321	```
322	plugin-name/
323	└── agents/
324	├── analyzer.md
325	├── reviewer.md
326	└── generator.md
327	```
328
329	All `.md` files in `agents/` are auto-discovered.
330
331	### Namespacing
332
333	Agents are namespaced automatically:
334	- Single plugin: `agent-name`
335	- With subdirectories: `plugin:subdir:agent-name`
336
337	## Testing Agents
338
339	### Test Triggering
340
341	Create test scenarios to verify agent triggers correctly:
342
343	1. Write agent with specific triggering examples
344	2. Use similar phrasing to examples in test
345	3. Check Claude loads the agent
346	4. Verify agent provides expected functionality
347
348	### Test System Prompt
349
350	Ensure system prompt is complete:
351
352	1. Give agent typical task
353	2. Check it follows process steps
354	3. Verify output format is correct
355	4. Test edge cases mentioned in prompt
356	5. Confirm quality standards are met
357
358	## Quick Reference
359
360	### Minimal Agent
361
362	```markdown
363	---
364	name: simple-agent
365	description: Use this agent when... Examples: <example>...</example>
366	model: inherit
367	color: blue
368	---
369
370	You are an agent that [does X].
371
372	Process:
373	1. [Step 1]
374	2. [Step 2]
375
376	Output: [What to provide]
377	```
378
379	### Frontmatter Fields Summary
380
381	\| Field \| Required \| Format \| Example \|
382	\|-------\|----------\|--------\|---------\|
383	\| name \| Yes \| lowercase-hyphens \| code-reviewer \|
384	\| description \| Yes \| Text + examples \| Use when... <example>... \|
385	\| model \| Yes \| inherit/sonnet/opus/haiku \| inherit \|
386	\| color \| Yes \| Color name \| blue \|
387	\| tools \| No \| Array of tool names \| ["Read", "Grep"] \|
388	\| skills \| No \| Comma-separated names \| skill-a, skill-b \|
389
390	### Best Practices
391
392	DO:
393	- ✅ Include 2-4 concrete examples in description
394	- ✅ Write specific triggering conditions
395	- ✅ Use `inherit` for model unless specific need
396	- ✅ Choose appropriate tools (least privilege)
397	- ✅ Write clear, structured system prompts
398	- ✅ Test agent triggering thoroughly
399
400	DON'T:
401	- ❌ Use generic descriptions without examples
402	- ❌ Omit triggering conditions
403	- ❌ Give all agents same color
404	- ❌ Grant unnecessary tool access
405	- ❌ Write vague system prompts
406	- ❌ Skip testing
407
408	## Additional Resources
409
410	### Reference Files
411
412	For detailed guidance, consult:
413
414	- `references/system-prompt-design.md` - Complete system prompt patterns
415	- `references/triggering-examples.md` - Example formats and best practices
416	- `references/agent-creation-system-prompt.md` - The exact prompt from Claude Code
417
418	### Example Files
419
420	Working examples in `examples/`:
421
422	- `agent-creation-prompt.md` - AI-assisted agent generation template
423	- `complete-agent-examples.md` - Full agent examples for different use cases
424
425	### Utility Scripts
426
427	Development tools in `scripts/`:
428
429	- `validate-agent.sh` - Validate agent file structure
430	- `test-agent-trigger.sh` - Test if agent triggers correctly
431
432	## Implementation Workflow
433
434	To create an agent for a plugin:
435
436	1. Define agent purpose and triggering conditions
437	2. Choose creation method (AI-assisted or manual)
438	3. Create `agents/agent-name.md` file
439	4. Write frontmatter with all required fields
440	5. Write system prompt following best practices
441	6. Include 2-4 triggering examples in description
442	7. Validate with `scripts/validate-agent.sh`
443	8. Test triggering with real scenarios
444	9. Document agent in plugin README
445
446	Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.