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 permissionMode field to agent development docs 416b2c5 · on Dec 12, 2025 History

452 lines · 11.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	permissionMode: default
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	### permissionMode (optional)
164
165	Control how permission prompts are handled for the agent.
166
167	Format: String
168
169	Options:
170	- `default` - Inherit permission mode from parent conversation (default behavior)
171	- `ask` - Always prompt for permission before tool use
172	- `accept-edits` - Auto-accept file edits without prompting
173
174	```yaml
175	permissionMode: accept-edits
176	```
177
178	Default: If omitted, inherits from parent conversation settings
179
180	Backwards compatibility: `acceptEdits` is also accepted but `accept-edits` (kebab-case) is preferred for consistency with CLI flags.
181
182	Use cases:
183	- Agents performing many file operations: Use `accept-edits`
184	- Security-sensitive agents: Use `ask` to ensure oversight
185	- General purpose: Omit field to inherit conversation settings
186
187	Example:
188	```yaml
189	---
190	name: code-generator
191	description: Use this agent when...
192	model: inherit
193	color: green
194	permissionMode: accept-edits
195	---
196	```
197
198	## System Prompt Design
199
200	The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.
201
202	### Structure
203
204	Standard template:
205	```markdown
206	You are [role] specializing in [domain].
207
208	Your Core Responsibilities:
209	1. [Primary responsibility]
210	2. [Secondary responsibility]
211	3. [Additional responsibilities...]
212
213	Analysis Process:
214	1. [Step one]
215	2. [Step two]
216	3. [Step three]
217	[...]
218
219	Quality Standards:
220	- [Standard 1]
221	- [Standard 2]
222
223	Output Format:
224	Provide results in this format:
225	- [What to include]
226	- [How to structure]
227
228	Edge Cases:
229	Handle these situations:
230	- [Edge case 1]: [How to handle]
231	- [Edge case 2]: [How to handle]
232	```
233
234	### Best Practices
235
236	✅ DO:
237	- Write in second person ("You are...", "You will...")
238	- Be specific about responsibilities
239	- Provide step-by-step process
240	- Define output format
241	- Include quality standards
242	- Address edge cases
243	- Keep under 10,000 characters
244
245	❌ DON'T:
246	- Write in first person ("I am...", "I will...")
247	- Be vague or generic
248	- Omit process steps
249	- Leave output format undefined
250	- Skip quality guidance
251	- Ignore error cases
252
253	## Creating Agents
254
255	### Method 1: AI-Assisted Generation
256
257	Use this prompt pattern (extracted from Claude Code):
258
259	```
260	Create an agent configuration based on this request: "[YOUR DESCRIPTION]"
261
262	Requirements:
263	1. Extract core intent and responsibilities
264	2. Design expert persona for the domain
265	3. Create comprehensive system prompt with:
266	- Clear behavioral boundaries
267	- Specific methodologies
268	- Edge case handling
269	- Output format
270	4. Create identifier (lowercase, hyphens, 3-50 chars)
271	5. Write description with triggering conditions
272	6. Include 2-3 <example> blocks showing when to use
273
274	Return JSON with:
275	{
276	"identifier": "agent-name",
277	"whenToUse": "Use this agent when... Examples: <example>...</example>",
278	"systemPrompt": "You are..."
279	}
280	```
281
282	Then convert to agent file format with frontmatter.
283
284	See `examples/agent-creation-prompt.md` for complete template.
285
286	### Method 2: Manual Creation
287
288	1. Choose agent identifier (3-50 chars, lowercase, hyphens)
289	2. Write description with examples
290	3. Select model (usually `inherit`)
291	4. Choose color for visual identification
292	5. Define tools (if restricting access)
293	6. Write system prompt with structure above
294	7. Save as `agents/agent-name.md`
295
296	## Validation Rules
297
298	### Identifier Validation
299
300	```
301	✅ Valid: code-reviewer, test-gen, api-analyzer-v2
302	❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)
303	```
304
305	Rules:
306	- 3-50 characters
307	- Lowercase letters, numbers, hyphens only
308	- Must start and end with alphanumeric
309	- No underscores, spaces, or special characters
310
311	### Description Validation
312
313	Length: 10-5,000 characters
314	Must include: Triggering conditions and examples
315	Best: 200-1,000 characters with 2-4 examples
316
317	### System Prompt Validation
318
319	Length: 20-10,000 characters
320	Best: 500-3,000 characters
321	Structure: Clear responsibilities, process, output format
322
323	## Agent Organization
324
325	### Plugin Agents Directory
326
327	```
328	plugin-name/
329	└── agents/
330	├── analyzer.md
331	├── reviewer.md
332	└── generator.md
333	```
334
335	All `.md` files in `agents/` are auto-discovered.
336
337	### Namespacing
338
339	Agents are namespaced automatically:
340	- Single plugin: `agent-name`
341	- With subdirectories: `plugin:subdir:agent-name`
342
343	## Testing Agents
344
345	### Test Triggering
346
347	Create test scenarios to verify agent triggers correctly:
348
349	1. Write agent with specific triggering examples
350	2. Use similar phrasing to examples in test
351	3. Check Claude loads the agent
352	4. Verify agent provides expected functionality
353
354	### Test System Prompt
355
356	Ensure system prompt is complete:
357
358	1. Give agent typical task
359	2. Check it follows process steps
360	3. Verify output format is correct
361	4. Test edge cases mentioned in prompt
362	5. Confirm quality standards are met
363
364	## Quick Reference
365
366	### Minimal Agent
367
368	```markdown
369	---
370	name: simple-agent
371	description: Use this agent when... Examples: <example>...</example>
372	model: inherit
373	color: blue
374	---
375
376	You are an agent that [does X].
377
378	Process:
379	1. [Step 1]
380	2. [Step 2]
381
382	Output: [What to provide]
383	```
384
385	### Frontmatter Fields Summary
386
387	\| Field \| Required \| Format \| Example \|
388	\|-------\|----------\|--------\|---------\|
389	\| name \| Yes \| lowercase-hyphens \| code-reviewer \|
390	\| description \| Yes \| Text + examples \| Use when... <example>... \|
391	\| model \| Yes \| inherit/sonnet/opus/haiku \| inherit \|
392	\| color \| Yes \| Color name \| blue \|
393	\| tools \| No \| Array of tool names \| ["Read", "Grep"] \|
394	\| permissionMode \| No \| default/ask/accept-edits \| accept-edits \|
395
396	### Best Practices
397
398	DO:
399	- ✅ Include 2-4 concrete examples in description
400	- ✅ Write specific triggering conditions
401	- ✅ Use `inherit` for model unless specific need
402	- ✅ Choose appropriate tools (least privilege)
403	- ✅ Write clear, structured system prompts
404	- ✅ Test agent triggering thoroughly
405
406	DON'T:
407	- ❌ Use generic descriptions without examples
408	- ❌ Omit triggering conditions
409	- ❌ Give all agents same color
410	- ❌ Grant unnecessary tool access
411	- ❌ Write vague system prompts
412	- ❌ Skip testing
413
414	## Additional Resources
415
416	### Reference Files
417
418	For detailed guidance, consult:
419
420	- `references/system-prompt-design.md` - Complete system prompt patterns
421	- `references/triggering-examples.md` - Example formats and best practices
422	- `references/agent-creation-system-prompt.md` - The exact prompt from Claude Code
423
424	### Example Files
425
426	Working examples in `examples/`:
427
428	- `agent-creation-prompt.md` - AI-assisted agent generation template
429	- `complete-agent-examples.md` - Full agent examples for different use cases
430
431	### Utility Scripts
432
433	Development tools in `scripts/`:
434
435	- `validate-agent.sh` - Validate agent file structure
436	- `test-agent-trigger.sh` - Test if agent triggers correctly
437
438	## Implementation Workflow
439
440	To create an agent for a plugin:
441
442	1. Define agent purpose and triggering conditions
443	2. Choose creation method (AI-assisted or manual)
444	3. Create `agents/agent-name.md` file
445	4. Write frontmatter with all required fields
446	5. Write system prompt following best practices
447	6. Include 2-4 triggering examples in description
448	7. Validate with `scripts/validate-agent.sh`
449	8. Test triggering with real scenarios
450	9. Document agent in plugin README
451
452	Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.