# Agent Triggering Examples: Best Practices Complete guide to writing effective `` blocks in agent descriptions for reliable triggering. ## Example Block Format The standard format for triggering examples: ```markdown Context: [Describe the situation - what led to this interaction] user: "[Exact user message or request]" assistant: "[How Claude should respond before triggering]" [Explanation of why this agent should be triggered in this scenario] assistant: "[How Claude triggers the agent - usually 'I'll use the [agent-name] agent...']" ``` ## Anatomy of a Good Example ### Context **Purpose:** Set the scene - what happened before the user's message **Good contexts:** ``` Context: User just implemented a new authentication feature Context: User has created a PR and wants it reviewed Context: User is debugging a test failure Context: After writing several functions without documentation ``` **Bad contexts:** ``` Context: User needs help (too vague) Context: Normal usage (not specific) ``` ### User Message **Purpose:** Show the exact phrasing that should trigger the agent **Good user messages:** ``` user: "I've added the OAuth flow, can you check it?" user: "Review PR #123" user: "Why is this test failing?" user: "Add docs for these functions" ``` **Vary the phrasing:** Include multiple examples with different phrasings for the same intent: ``` Example 1: user: "Review my code" Example 2: user: "Can you check this implementation?" Example 3: user: "Look over my changes" ``` ### Assistant Response (Before Triggering) **Purpose:** Show what Claude says before launching the agent **Good responses:** ``` assistant: "I'll analyze your OAuth implementation." assistant: "Let me review that PR for you." assistant: "I'll investigate the test failure." ``` **Proactive example:** ``` assistant: "Great! Now let me review the code quality." Code was just written, proactively trigger review agent. ``` ### Commentary **Purpose:** Explain the reasoning - WHY this agent should trigger **Good commentary:** ``` User explicitly requested code review, trigger the code-reviewer agent. After code implementation, proactively use review agent to check quality. PR analysis request matches pr-analyzer agent's expertise. ``` **Include decision logic:** ``` User wrote tests (Test tool used). The test-analyzer agent should check test quality and coverage before continuing. ``` ### Assistant Response (Triggering) **Purpose:** Show how Claude invokes the agent **Standard pattern:** ``` assistant: "I'll use the [agent-name] agent to [what it will do]." ``` **Examples:** ``` assistant: "I'll use the code-reviewer agent to analyze the changes." assistant: "Let me use the test-generator agent to create comprehensive tests." assistant: "I'll use the security-analyzer agent to check for vulnerabilities." ``` ## Example Types ### Type 1: Explicit Request User directly asks for what the agent does: ```markdown Context: User explicitly requests security analysis user: "Check my code for security vulnerabilities" assistant: "I'll use the security-analyzer agent to perform a thorough security review." Direct security analysis request triggers the security-analyzer agent. ``` ### Type 2: Proactive Triggering Agent triggers after relevant work without explicit request: ```markdown Context: User just implemented database queries user: "I've added the user search functionality" assistant: "Great! Let me review it for security." Database code written. Proactively trigger security-analyzer to check for SQL injection and other database security issues. assistant: "I'll use the security-analyzer agent to check the database code." ``` ### Type 3: Implicit Request User implies need without stating it directly: ```markdown Context: User mentions code is hard to understand user: "This code is confusing and hard to follow" assistant: "I can help improve the code clarity." User indicates complexity issues. Trigger code-simplifier agent to refactor for better readability. assistant: "I'll use the code-simplifier agent to suggest improvements." ``` ### Type 4: Tool Usage Pattern Agent triggers based on prior tool usage: ```markdown Context: User made multiple edits to test files user: "I've updated all the tests" assistant: "Great! Let me verify test quality." Multiple Edit tools used on test files. Proactively trigger test-quality-analyzer to ensure tests follow best practices. assistant: "I'll use the test-quality-analyzer agent to review the tests." ``` ## Multiple Examples Strategy ### Cover Different Phrasings ```markdown user: "Review my code" [...] user: "Can you check my implementation?" [...] user: "Look over these changes" [...] ``` ### Cover Proactive and Reactive ```markdown Context: User explicitly requests review user: "Review my code for issues" [...] Context: After user writes code user: "I've implemented the feature" assistant: "Great! Now let me review it." Code written, proactively review. [...] ``` ### Cover Edge Cases ```markdown Context: Typical usage user: "Check my PR" [...] Context: Large PR that needs thorough analysis user: "This is a big PR, can you do a deep review?" [...] Large PR mentioned, use thorough analysis mode. ``` ## Common Mistakes ### ❌ Missing Context ```markdown user: "Review my code" assistant: "I'll use the code-reviewer agent." ``` **Why bad:** No context about what led to this request. ### ✅ With Context ```markdown Context: User just finished implementing authentication user: "Review my code" assistant: "I'll use the code-reviewer agent to analyze the auth implementation." Auth code written, review for security and best practices. ``` ### ❌ No Commentary ```markdown Context: User requests review user: "Check my changes" assistant: "I'll use the reviewer agent." ``` **Why bad:** Doesn't explain WHY agent triggers. ### ✅ With Commentary ```markdown Context: User requests review after making changes user: "Check my changes" assistant: "I'll use the code-reviewer agent to analyze the modifications." Code review request triggers agent to check quality, security, and adherence to standards. ``` ### ❌ Agent Responds Directly ```markdown user: "Review my code" assistant: "I found the following issues: [lists issues]" ``` **Why bad:** Shows agent's output, not triggering. ### ✅ Shows Triggering ```markdown user: "Review my code" assistant: "I'll use the code-reviewer agent to perform the review." Review request triggers the agent. ``` ## How Many Examples? ### Minimum: 2 Examples Cover at least: 1. Explicit request 2. One variation or proactive trigger ### Recommended: 3-4 Examples Cover: 1. Explicit request (direct ask) 2. Implicit request (user implies need) 3. Proactive trigger (after relevant work) 4. Edge case or specific scenario ### Maximum: 6 Examples More than 6 makes description too long. Focus on most important scenarios. ## Template Library ### Code Review Agent ```markdown Context: User just implemented a new feature user: "I've added the user registration feature" assistant: "Great! Let me review the code quality." Code written, proactively trigger code-reviewer agent. assistant: "I'll use the code-reviewer agent to analyze the implementation." Context: User explicitly requests review user: "Can you review my changes for issues?" assistant: "I'll use the code-reviewer agent to perform a thorough review." Explicit review request triggers the agent. ``` ### Test Generation Agent ```markdown Context: User implemented functions without tests user: "I've added the data processing functions" assistant: "Great! Let me generate tests for these." New code without tests, proactively trigger test-generator agent. assistant: "I'll use the test-generator agent to create comprehensive tests." Context: User explicitly asks for tests user: "Generate tests for my code" assistant: "I'll use the test-generator agent to create a complete test suite." Direct test generation request triggers the agent. ``` ### Documentation Agent ```markdown Context: User added new API endpoints user: "I've implemented the REST API endpoints" assistant: "I'll document these endpoints." New API code, proactively generate documentation. assistant: "I'll use the api-docs-writer agent to create comprehensive documentation." Context: User requests documentation user: "Write docs for this API" assistant: "I'll use the api-docs-writer agent to generate clear documentation." Documentation request triggers the agent. ``` ### Validation Agent ```markdown Context: User ready to commit changes user: "I'm ready to commit this code" assistant: "Let me validate it first." Before commit, proactively validate with validation-agent. assistant: "I'll use the code-validator agent to check for issues." Context: User asks for validation user: "Validate my implementation" assistant: "I'll use the code-validator agent to verify correctness." Explicit validation request triggers the agent. ``` ## Debugging Triggering Issues ### Agent Not Triggering **Check:** 1. Examples include relevant keywords from user message 2. Context matches actual usage scenarios 3. Commentary explains triggering logic clearly 4. Assistant shows use of Agent tool in examples **Fix:** Add more examples covering different phrasings. ### Agent Triggers Too Often **Check:** 1. Examples are too broad or generic 2. Triggering conditions overlap with other agents 3. Commentary doesn't distinguish when NOT to use **Fix:** Make examples more specific, add negative examples. ### Agent Triggers in Wrong Scenarios **Check:** 1. Examples don't match actual intended use 2. Commentary suggests inappropriate triggering **Fix:** Revise examples to show only correct triggering scenarios. ## Best Practices Summary ✅ **DO:** - Include 2-4 concrete, specific examples - Show both explicit and proactive triggering - Provide clear context for each example - Explain reasoning in commentary - Vary user message phrasing - Show Claude using Agent tool ❌ **DON'T:** - Use generic, vague examples - Omit context or commentary - Show only one type of triggering - Skip the agent invocation step - Make examples too similar - Forget to explain why agent triggers ## Conclusion 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.