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 / references / triggering-examples.md

Daisy S. HollmanMerge pull request #11780 from anthropics/daisy/plugin-dev/public-marketplace c508e59 · on Nov 18, 2025 History

491 lines · 11.3 KBPreview CodeRaw

1	# Agent Triggering Examples: Best Practices
2
3	Complete guide to writing effective `<example>` blocks in agent descriptions for reliable triggering.
4
5	## Example Block Format
6
7	The standard format for triggering examples:
8
9	```markdown
10	<example>
11	Context: [Describe the situation - what led to this interaction]
12	user: "[Exact user message or request]"
13	assistant: "[How Claude should respond before triggering]"
14	<commentary>
15	[Explanation of why this agent should be triggered in this scenario]
16	</commentary>
17	assistant: "[How Claude triggers the agent - usually 'I'll use the [agent-name] agent...']"
18	</example>
19	```
20
21	## Anatomy of a Good Example
22
23	### Context
24
25	Purpose: Set the scene - what happened before the user's message
26
27	Good contexts:
28	```
29	Context: User just implemented a new authentication feature
30	Context: User has created a PR and wants it reviewed
31	Context: User is debugging a test failure
32	Context: After writing several functions without documentation
33	```
34
35	Bad contexts:
36	```
37	Context: User needs help (too vague)
38	Context: Normal usage (not specific)
39	```
40
41	### User Message
42
43	Purpose: Show the exact phrasing that should trigger the agent
44
45	Good user messages:
46	```
47	user: "I've added the OAuth flow, can you check it?"
48	user: "Review PR #123"
49	user: "Why is this test failing?"
50	user: "Add docs for these functions"
51	```
52
53	Vary the phrasing:
54	Include multiple examples with different phrasings for the same intent:
55	```
56	Example 1: user: "Review my code"
57	Example 2: user: "Can you check this implementation?"
58	Example 3: user: "Look over my changes"
59	```
60
61	### Assistant Response (Before Triggering)
62
63	Purpose: Show what Claude says before launching the agent
64
65	Good responses:
66	```
67	assistant: "I'll analyze your OAuth implementation."
68	assistant: "Let me review that PR for you."
69	assistant: "I'll investigate the test failure."
70	```
71
72	Proactive example:
73	```
74	assistant: "Great! Now let me review the code quality."
75	<commentary>
76	Code was just written, proactively trigger review agent.
77	</commentary>
78	```
79
80	### Commentary
81
82	Purpose: Explain the reasoning - WHY this agent should trigger
83
84	Good commentary:
85	```
86	<commentary>
87	User explicitly requested code review, trigger the code-reviewer agent.
88	</commentary>
89
90	<commentary>
91	After code implementation, proactively use review agent to check quality.
92	</commentary>
93
94	<commentary>
95	PR analysis request matches pr-analyzer agent's expertise.
96	</commentary>
97	```
98
99	Include decision logic:
100	```
101	<commentary>
102	User wrote tests (Test tool used). The test-analyzer agent should check
103	test quality and coverage before continuing.
104	</commentary>
105	```
106
107	### Assistant Response (Triggering)
108
109	Purpose: Show how Claude invokes the agent
110
111	Standard pattern:
112	```
113	assistant: "I'll use the [agent-name] agent to [what it will do]."
114	```
115
116	Examples:
117	```
118	assistant: "I'll use the code-reviewer agent to analyze the changes."
119	assistant: "Let me use the test-generator agent to create comprehensive tests."
120	assistant: "I'll use the security-analyzer agent to check for vulnerabilities."
121	```
122
123	## Example Types
124
125	### Type 1: Explicit Request
126
127	User directly asks for what the agent does:
128
129	```markdown
130	<example>
131	Context: User explicitly requests security analysis
132	user: "Check my code for security vulnerabilities"
133	assistant: "I'll use the security-analyzer agent to perform a thorough security review."
134	<commentary>
135	Direct security analysis request triggers the security-analyzer agent.
136	</commentary>
137	</example>
138	```
139
140	### Type 2: Proactive Triggering
141
142	Agent triggers after relevant work without explicit request:
143
144	```markdown
145	<example>
146	Context: User just implemented database queries
147	user: "I've added the user search functionality"
148	assistant: "Great! Let me review it for security."
149	<commentary>
150	Database code written. Proactively trigger security-analyzer to check
151	for SQL injection and other database security issues.
152	</commentary>
153	assistant: "I'll use the security-analyzer agent to check the database code."
154	</example>
155	```
156
157	### Type 3: Implicit Request
158
159	User implies need without stating it directly:
160
161	```markdown
162	<example>
163	Context: User mentions code is hard to understand
164	user: "This code is confusing and hard to follow"
165	assistant: "I can help improve the code clarity."
166	<commentary>
167	User indicates complexity issues. Trigger code-simplifier agent to refactor
168	for better readability.
169	</commentary>
170	assistant: "I'll use the code-simplifier agent to suggest improvements."
171	</example>
172	```
173
174	### Type 4: Tool Usage Pattern
175
176	Agent triggers based on prior tool usage:
177
178	```markdown
179	<example>
180	Context: User made multiple edits to test files
181	user: "I've updated all the tests"
182	assistant: "Great! Let me verify test quality."
183	<commentary>
184	Multiple Edit tools used on test files. Proactively trigger test-quality-analyzer
185	to ensure tests follow best practices.
186	</commentary>
187	assistant: "I'll use the test-quality-analyzer agent to review the tests."
188	</example>
189	```
190
191	## Multiple Examples Strategy
192
193	### Cover Different Phrasings
194
195	```markdown
196	<example>
197	user: "Review my code"
198	[...]
199	</example>
200
201	<example>
202	user: "Can you check my implementation?"
203	[...]
204	</example>
205
206	<example>
207	user: "Look over these changes"
208	[...]
209	</example>
210	```
211
212	### Cover Proactive and Reactive
213
214	```markdown
215	<example>
216	Context: User explicitly requests review
217	user: "Review my code for issues"
218	[...]
219	</example>
220
221	<example>
222	Context: After user writes code
223	user: "I've implemented the feature"
224	assistant: "Great! Now let me review it."
225	<commentary>
226	Code written, proactively review.
227	</commentary>
228	[...]
229	</example>
230	```
231
232	### Cover Edge Cases
233
234	```markdown
235	<example>
236	Context: Typical usage
237	user: "Check my PR"
238	[...]
239	</example>
240
241	<example>
242	Context: Large PR that needs thorough analysis
243	user: "This is a big PR, can you do a deep review?"
244	[...]
245	<commentary>
246	Large PR mentioned, use thorough analysis mode.
247	</commentary>
248	</example>
249	```
250
251	## Common Mistakes
252
253	### ❌ Missing Context
254
255	```markdown
256	<example>
257	user: "Review my code"
258	assistant: "I'll use the code-reviewer agent."
259	</example>
260	```
261
262	Why bad: No context about what led to this request.
263
264	### ✅ With Context
265
266	```markdown
267	<example>
268	Context: User just finished implementing authentication
269	user: "Review my code"
270	assistant: "I'll use the code-reviewer agent to analyze the auth implementation."
271	<commentary>
272	Auth code written, review for security and best practices.
273	</commentary>
274	</example>
275	```
276
277	### ❌ No Commentary
278
279	```markdown
280	<example>
281	Context: User requests review
282	user: "Check my changes"
283	assistant: "I'll use the reviewer agent."
284	</example>
285	```
286
287	Why bad: Doesn't explain WHY agent triggers.
288
289	### ✅ With Commentary
290
291	```markdown
292	<example>
293	Context: User requests review after making changes
294	user: "Check my changes"
295	assistant: "I'll use the code-reviewer agent to analyze the modifications."
296	<commentary>
297	Code review request triggers agent to check quality, security, and adherence to standards.
298	</commentary>
299	</example>
300	```
301
302	### ❌ Agent Responds Directly
303
304	```markdown
305	<example>
306	user: "Review my code"
307	assistant: "I found the following issues: [lists issues]"
308	</example>
309	```
310
311	Why bad: Shows agent's output, not triggering.
312
313	### ✅ Shows Triggering
314
315	```markdown
316	<example>
317	user: "Review my code"
318	assistant: "I'll use the code-reviewer agent to perform the review."
319	<commentary>
320	Review request triggers the agent.
321	</commentary>
322	</example>
323	```
324
325	## How Many Examples?
326
327	### Minimum: 2 Examples
328
329	Cover at least:
330	1. Explicit request
331	2. One variation or proactive trigger
332
333	### Recommended: 3-4 Examples
334
335	Cover:
336	1. Explicit request (direct ask)
337	2. Implicit request (user implies need)
338	3. Proactive trigger (after relevant work)
339	4. Edge case or specific scenario
340
341	### Maximum: 6 Examples
342
343	More than 6 makes description too long. Focus on most important scenarios.
344
345	## Template Library
346
347	### Code Review Agent
348
349	```markdown
350	<example>
351	Context: User just implemented a new feature
352	user: "I've added the user registration feature"
353	assistant: "Great! Let me review the code quality."
354	<commentary>
355	Code written, proactively trigger code-reviewer agent.
356	</commentary>
357	assistant: "I'll use the code-reviewer agent to analyze the implementation."
358	</example>
359
360	<example>
361	Context: User explicitly requests review
362	user: "Can you review my changes for issues?"
363	assistant: "I'll use the code-reviewer agent to perform a thorough review."
364	<commentary>
365	Explicit review request triggers the agent.
366	</commentary>
367	</example>
368	```
369
370	### Test Generation Agent
371
372	```markdown
373	<example>
374	Context: User implemented functions without tests
375	user: "I've added the data processing functions"
376	assistant: "Great! Let me generate tests for these."
377	<commentary>
378	New code without tests, proactively trigger test-generator agent.
379	</commentary>
380	assistant: "I'll use the test-generator agent to create comprehensive tests."
381	</example>
382
383	<example>
384	Context: User explicitly asks for tests
385	user: "Generate tests for my code"
386	assistant: "I'll use the test-generator agent to create a complete test suite."
387	<commentary>
388	Direct test generation request triggers the agent.
389	</commentary>
390	</example>
391	```
392
393	### Documentation Agent
394
395	```markdown
396	<example>
397	Context: User added new API endpoints
398	user: "I've implemented the REST API endpoints"
399	assistant: "I'll document these endpoints."
400	<commentary>
401	New API code, proactively generate documentation.
402	</commentary>
403	assistant: "I'll use the api-docs-writer agent to create comprehensive documentation."
404	</example>
405
406	<example>
407	Context: User requests documentation
408	user: "Write docs for this API"
409	assistant: "I'll use the api-docs-writer agent to generate clear documentation."
410	<commentary>
411	Documentation request triggers the agent.
412	</commentary>
413	</example>
414	```
415
416	### Validation Agent
417
418	```markdown
419	<example>
420	Context: User ready to commit changes
421	user: "I'm ready to commit this code"
422	assistant: "Let me validate it first."
423	<commentary>
424	Before commit, proactively validate with validation-agent.
425	</commentary>
426	assistant: "I'll use the code-validator agent to check for issues."
427	</example>
428
429	<example>
430	Context: User asks for validation
431	user: "Validate my implementation"
432	assistant: "I'll use the code-validator agent to verify correctness."
433	<commentary>
434	Explicit validation request triggers the agent.
435	</commentary>
436	</example>
437	```
438
439	## Debugging Triggering Issues
440
441	### Agent Not Triggering
442
443	Check:
444	1. Examples include relevant keywords from user message
445	2. Context matches actual usage scenarios
446	3. Commentary explains triggering logic clearly
447	4. Assistant shows use of Agent tool in examples
448
449	Fix:
450	Add more examples covering different phrasings.
451
452	### Agent Triggers Too Often
453
454	Check:
455	1. Examples are too broad or generic
456	2. Triggering conditions overlap with other agents
457	3. Commentary doesn't distinguish when NOT to use
458
459	Fix:
460	Make examples more specific, add negative examples.
461
462	### Agent Triggers in Wrong Scenarios
463
464	Check:
465	1. Examples don't match actual intended use
466	2. Commentary suggests inappropriate triggering
467
468	Fix:
469	Revise examples to show only correct triggering scenarios.
470
471	## Best Practices Summary
472
473	✅ DO:
474	- Include 2-4 concrete, specific examples
475	- Show both explicit and proactive triggering
476	- Provide clear context for each example
477	- Explain reasoning in commentary
478	- Vary user message phrasing
479	- Show Claude using Agent tool
480
481	❌ DON'T:
482	- Use generic, vague examples
483	- Omit context or commentary
484	- Show only one type of triggering
485	- Skip the agent invocation step
486	- Make examples too similar
487	- Forget to explain why agent triggers
488
489	## Conclusion
490
491	Well-crafted examples are crucial for reliable agent triggering. Invest time in creating diverse, specific examples that clearly demonstrate when and why the agent should be used.