1# Agent Triggering Examples: Best Practices
2 
3Complete guide to writing effective `<example>` blocks in agent descriptions for reliable triggering.
4 
5## Example Block Format
6 
7The standard format for triggering examples:
8 
9```markdown
10<example>
11Context: [Describe the situation - what led to this interaction]
12user: "[Exact user message or request]"
13assistant: "[How Claude should respond before triggering]"
14<commentary>
15[Explanation of why this agent should be triggered in this scenario]
16</commentary>
17assistant: "[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```
29Context: User just implemented a new authentication feature
30Context: User has created a PR and wants it reviewed
31Context: User is debugging a test failure
32Context: After writing several functions without documentation
33```
34 
35**Bad contexts:**
36```
37Context: User needs help (too vague)
38Context: 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```
47user: "I've added the OAuth flow, can you check it?"
48user: "Review PR #123"
49user: "Why is this test failing?"
50user: "Add docs for these functions"
51```
52 
53**Vary the phrasing:**
54Include multiple examples with different phrasings for the same intent:
55```
56Example 1: user: "Review my code"
57Example 2: user: "Can you check this implementation?"
58Example 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```
67assistant: "I'll analyze your OAuth implementation."
68assistant: "Let me review that PR for you."
69assistant: "I'll investigate the test failure."
70```
71 
72**Proactive example:**
73```
74assistant: "Great! Now let me review the code quality."
75<commentary>
76Code 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>
87User explicitly requested code review, trigger the code-reviewer agent.
88</commentary>
89 
90<commentary>
91After code implementation, proactively use review agent to check quality.
92</commentary>
93 
94<commentary>
95PR analysis request matches pr-analyzer agent's expertise.
96</commentary>
97```
98 
99**Include decision logic:**
100```
101<commentary>
102User wrote tests (Test tool used). The test-analyzer agent should check
103test 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```
113assistant: "I'll use the [agent-name] agent to [what it will do]."
114```
115 
116**Examples:**
117```
118assistant: "I'll use the code-reviewer agent to analyze the changes."
119assistant: "Let me use the test-generator agent to create comprehensive tests."
120assistant: "I'll use the security-analyzer agent to check for vulnerabilities."
121```
122 
123## Example Types
124 
125### Type 1: Explicit Request
126 
127User directly asks for what the agent does:
128 
129```markdown
130<example>
131Context: User explicitly requests security analysis
132user: "Check my code for security vulnerabilities"
133assistant: "I'll use the security-analyzer agent to perform a thorough security review."
134<commentary>
135Direct security analysis request triggers the security-analyzer agent.
136</commentary>
137</example>
138```
139 
140### Type 2: Proactive Triggering
141 
142Agent triggers after relevant work without explicit request:
143 
144```markdown
145<example>
146Context: User just implemented database queries
147user: "I've added the user search functionality"
148assistant: "Great! Let me review it for security."
149<commentary>
150Database code written. Proactively trigger security-analyzer to check
151for SQL injection and other database security issues.
152</commentary>
153assistant: "I'll use the security-analyzer agent to check the database code."
154</example>
155```
156 
157### Type 3: Implicit Request
158 
159User implies need without stating it directly:
160 
161```markdown
162<example>
163Context: User mentions code is hard to understand
164user: "This code is confusing and hard to follow"
165assistant: "I can help improve the code clarity."
166<commentary>
167User indicates complexity issues. Trigger code-simplifier agent to refactor
168for better readability.
169</commentary>
170assistant: "I'll use the code-simplifier agent to suggest improvements."
171</example>
172```
173 
174### Type 4: Tool Usage Pattern
175 
176Agent triggers based on prior tool usage:
177 
178```markdown
179<example>
180Context: User made multiple edits to test files
181user: "I've updated all the tests"
182assistant: "Great! Let me verify test quality."
183<commentary>
184Multiple Edit tools used on test files. Proactively trigger test-quality-analyzer
185to ensure tests follow best practices.
186</commentary>
187assistant: "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>
197user: "Review my code"
198[...]
199</example>
200 
201<example>
202user: "Can you check my implementation?"
203[...]
204</example>
205 
206<example>
207user: "Look over these changes"
208[...]
209</example>
210```
211 
212### Cover Proactive and Reactive
213 
214```markdown
215<example>
216Context: User explicitly requests review
217user: "Review my code for issues"
218[...]
219</example>
220 
221<example>
222Context: After user writes code
223user: "I've implemented the feature"
224assistant: "Great! Now let me review it."
225<commentary>
226Code written, proactively review.
227</commentary>
228[...]
229</example>
230```
231 
232### Cover Edge Cases
233 
234```markdown
235<example>
236Context: Typical usage
237user: "Check my PR"
238[...]
239</example>
240 
241<example>
242Context: Large PR that needs thorough analysis
243user: "This is a big PR, can you do a deep review?"
244[...]
245<commentary>
246Large PR mentioned, use thorough analysis mode.
247</commentary>
248</example>
249```
250 
251## Common Mistakes
252 
253### ❌ Missing Context
254 
255```markdown
256<example>
257user: "Review my code"
258assistant: "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>
268Context: User just finished implementing authentication
269user: "Review my code"
270assistant: "I'll use the code-reviewer agent to analyze the auth implementation."
271<commentary>
272Auth code written, review for security and best practices.
273</commentary>
274</example>
275```
276 
277### ❌ No Commentary
278 
279```markdown
280<example>
281Context: User requests review
282user: "Check my changes"
283assistant: "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>
293Context: User requests review after making changes
294user: "Check my changes"
295assistant: "I'll use the code-reviewer agent to analyze the modifications."
296<commentary>
297Code 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>
306user: "Review my code"
307assistant: "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>
317user: "Review my code"
318assistant: "I'll use the code-reviewer agent to perform the review."
319<commentary>
320Review request triggers the agent.
321</commentary>
322</example>
323```
324 
325## How Many Examples?
326 
327### Minimum: 2 Examples
328 
329Cover at least:
3301. Explicit request
3312. One variation or proactive trigger
332 
333### Recommended: 3-4 Examples
334 
335Cover:
3361. Explicit request (direct ask)
3372. Implicit request (user implies need)
3383. Proactive trigger (after relevant work)
3394. Edge case or specific scenario
340 
341### Maximum: 6 Examples
342 
343More 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>
351Context: User just implemented a new feature
352user: "I've added the user registration feature"
353assistant: "Great! Let me review the code quality."
354<commentary>
355Code written, proactively trigger code-reviewer agent.
356</commentary>
357assistant: "I'll use the code-reviewer agent to analyze the implementation."
358</example>
359 
360<example>
361Context: User explicitly requests review
362user: "Can you review my changes for issues?"
363assistant: "I'll use the code-reviewer agent to perform a thorough review."
364<commentary>
365Explicit review request triggers the agent.
366</commentary>
367</example>
368```
369 
370### Test Generation Agent
371 
372```markdown
373<example>
374Context: User implemented functions without tests
375user: "I've added the data processing functions"
376assistant: "Great! Let me generate tests for these."
377<commentary>
378New code without tests, proactively trigger test-generator agent.
379</commentary>
380assistant: "I'll use the test-generator agent to create comprehensive tests."
381</example>
382 
383<example>
384Context: User explicitly asks for tests
385user: "Generate tests for my code"
386assistant: "I'll use the test-generator agent to create a complete test suite."
387<commentary>
388Direct test generation request triggers the agent.
389</commentary>
390</example>
391```
392 
393### Documentation Agent
394 
395```markdown
396<example>
397Context: User added new API endpoints
398user: "I've implemented the REST API endpoints"
399assistant: "I'll document these endpoints."
400<commentary>
401New API code, proactively generate documentation.
402</commentary>
403assistant: "I'll use the api-docs-writer agent to create comprehensive documentation."
404</example>
405 
406<example>
407Context: User requests documentation
408user: "Write docs for this API"
409assistant: "I'll use the api-docs-writer agent to generate clear documentation."
410<commentary>
411Documentation request triggers the agent.
412</commentary>
413</example>
414```
415 
416### Validation Agent
417 
418```markdown
419<example>
420Context: User ready to commit changes
421user: "I'm ready to commit this code"
422assistant: "Let me validate it first."
423<commentary>
424Before commit, proactively validate with validation-agent.
425</commentary>
426assistant: "I'll use the code-validator agent to check for issues."
427</example>
428 
429<example>
430Context: User asks for validation
431user: "Validate my implementation"
432assistant: "I'll use the code-validator agent to verify correctness."
433<commentary>
434Explicit validation request triggers the agent.
435</commentary>
436</example>
437```
438 
439## Debugging Triggering Issues
440 
441### Agent Not Triggering
442 
443**Check:**
4441. Examples include relevant keywords from user message
4452. Context matches actual usage scenarios
4463. Commentary explains triggering logic clearly
4474. Assistant shows use of Agent tool in examples
448 
449**Fix:**
450Add more examples covering different phrasings.
451 
452### Agent Triggers Too Often
453 
454**Check:**
4551. Examples are too broad or generic
4562. Triggering conditions overlap with other agents
4573. Commentary doesn't distinguish when NOT to use
458 
459**Fix:**
460Make examples more specific, add negative examples.
461 
462### Agent Triggers in Wrong Scenarios
463 
464**Check:**
4651. Examples don't match actual intended use
4662. Commentary suggests inappropriate triggering
467 
468**Fix:**
469Revise 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 
491Well-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.
492