Initial commit
This commit is contained in:
Zhongwei Li
491
skills/agent-development/references/triggering-examples.md
Normal file
491
skills/agent-development/references/triggering-examples.md
Normal file
@@ -0,0 +1,491 @@
|
||||
# Agent Triggering Examples: Best Practices
|
||||
|
||||
Complete guide to writing effective `<example>` blocks in agent descriptions for reliable triggering.
|
||||
|
||||
## Example Block Format
|
||||
|
||||
The standard format for triggering examples:
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
Context: [Describe the situation - what led to this interaction]
|
||||
user: "[Exact user message or request]"
|
||||
assistant: "[How Claude should respond before triggering]"
|
||||
<commentary>
|
||||
[Explanation of why this agent should be triggered in this scenario]
|
||||
</commentary>
|
||||
assistant: "[How Claude triggers the agent - usually 'I'll use the [agent-name] agent...']"
|
||||
</example>
|
||||
```
|
||||
|
||||
## 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."
|
||||
<commentary>
|
||||
Code was just written, proactively trigger review agent.
|
||||
</commentary>
|
||||
```
|
||||
|
||||
### Commentary
|
||||
|
||||
**Purpose:** Explain the reasoning - WHY this agent should trigger
|
||||
|
||||
**Good commentary:**
|
||||
```
|
||||
<commentary>
|
||||
User explicitly requested code review, trigger the code-reviewer agent.
|
||||
</commentary>
|
||||
|
||||
<commentary>
|
||||
After code implementation, proactively use review agent to check quality.
|
||||
</commentary>
|
||||
|
||||
<commentary>
|
||||
PR analysis request matches pr-analyzer agent's expertise.
|
||||
</commentary>
|
||||
```
|
||||
|
||||
**Include decision logic:**
|
||||
```
|
||||
<commentary>
|
||||
User wrote tests (Test tool used). The test-analyzer agent should check
|
||||
test quality and coverage before continuing.
|
||||
</commentary>
|
||||
```
|
||||
|
||||
### 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
|
||||
<example>
|
||||
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."
|
||||
<commentary>
|
||||
Direct security analysis request triggers the security-analyzer agent.
|
||||
</commentary>
|
||||
</example>
|
||||
```
|
||||
|
||||
### Type 2: Proactive Triggering
|
||||
|
||||
Agent triggers after relevant work without explicit request:
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
Context: User just implemented database queries
|
||||
user: "I've added the user search functionality"
|
||||
assistant: "Great! Let me review it for security."
|
||||
<commentary>
|
||||
Database code written. Proactively trigger security-analyzer to check
|
||||
for SQL injection and other database security issues.
|
||||
</commentary>
|
||||
assistant: "I'll use the security-analyzer agent to check the database code."
|
||||
</example>
|
||||
```
|
||||
|
||||
### Type 3: Implicit Request
|
||||
|
||||
User implies need without stating it directly:
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
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."
|
||||
<commentary>
|
||||
User indicates complexity issues. Trigger code-simplifier agent to refactor
|
||||
for better readability.
|
||||
</commentary>
|
||||
assistant: "I'll use the code-simplifier agent to suggest improvements."
|
||||
</example>
|
||||
```
|
||||
|
||||
### Type 4: Tool Usage Pattern
|
||||
|
||||
Agent triggers based on prior tool usage:
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
Context: User made multiple edits to test files
|
||||
user: "I've updated all the tests"
|
||||
assistant: "Great! Let me verify test quality."
|
||||
<commentary>
|
||||
Multiple Edit tools used on test files. Proactively trigger test-quality-analyzer
|
||||
to ensure tests follow best practices.
|
||||
</commentary>
|
||||
assistant: "I'll use the test-quality-analyzer agent to review the tests."
|
||||
</example>
|
||||
```
|
||||
|
||||
## Multiple Examples Strategy
|
||||
|
||||
### Cover Different Phrasings
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
user: "Review my code"
|
||||
[...]
|
||||
</example>
|
||||
|
||||
<example>
|
||||
user: "Can you check my implementation?"
|
||||
[...]
|
||||
</example>
|
||||
|
||||
<example>
|
||||
user: "Look over these changes"
|
||||
[...]
|
||||
</example>
|
||||
```
|
||||
|
||||
### Cover Proactive and Reactive
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
Context: User explicitly requests review
|
||||
user: "Review my code for issues"
|
||||
[...]
|
||||
</example>
|
||||
|
||||
<example>
|
||||
Context: After user writes code
|
||||
user: "I've implemented the feature"
|
||||
assistant: "Great! Now let me review it."
|
||||
<commentary>
|
||||
Code written, proactively review.
|
||||
</commentary>
|
||||
[...]
|
||||
</example>
|
||||
```
|
||||
|
||||
### Cover Edge Cases
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
Context: Typical usage
|
||||
user: "Check my PR"
|
||||
[...]
|
||||
</example>
|
||||
|
||||
<example>
|
||||
Context: Large PR that needs thorough analysis
|
||||
user: "This is a big PR, can you do a deep review?"
|
||||
[...]
|
||||
<commentary>
|
||||
Large PR mentioned, use thorough analysis mode.
|
||||
</commentary>
|
||||
</example>
|
||||
```
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### ❌ Missing Context
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
user: "Review my code"
|
||||
assistant: "I'll use the code-reviewer agent."
|
||||
</example>
|
||||
```
|
||||
|
||||
**Why bad:** No context about what led to this request.
|
||||
|
||||
### ✅ With Context
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
Context: User just finished implementing authentication
|
||||
user: "Review my code"
|
||||
assistant: "I'll use the code-reviewer agent to analyze the auth implementation."
|
||||
<commentary>
|
||||
Auth code written, review for security and best practices.
|
||||
</commentary>
|
||||
</example>
|
||||
```
|
||||
|
||||
### ❌ No Commentary
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
Context: User requests review
|
||||
user: "Check my changes"
|
||||
assistant: "I'll use the reviewer agent."
|
||||
</example>
|
||||
```
|
||||
|
||||
**Why bad:** Doesn't explain WHY agent triggers.
|
||||
|
||||
### ✅ With Commentary
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
Context: User requests review after making changes
|
||||
user: "Check my changes"
|
||||
assistant: "I'll use the code-reviewer agent to analyze the modifications."
|
||||
<commentary>
|
||||
Code review request triggers agent to check quality, security, and adherence to standards.
|
||||
</commentary>
|
||||
</example>
|
||||
```
|
||||
|
||||
### ❌ Agent Responds Directly
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
user: "Review my code"
|
||||
assistant: "I found the following issues: [lists issues]"
|
||||
</example>
|
||||
```
|
||||
|
||||
**Why bad:** Shows agent's output, not triggering.
|
||||
|
||||
### ✅ Shows Triggering
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
user: "Review my code"
|
||||
assistant: "I'll use the code-reviewer agent to perform the review."
|
||||
<commentary>
|
||||
Review request triggers the agent.
|
||||
</commentary>
|
||||
</example>
|
||||
```
|
||||
|
||||
## 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
|
||||
<example>
|
||||
Context: User just implemented a new feature
|
||||
user: "I've added the user registration feature"
|
||||
assistant: "Great! Let me review the code quality."
|
||||
<commentary>
|
||||
Code written, proactively trigger code-reviewer agent.
|
||||
</commentary>
|
||||
assistant: "I'll use the code-reviewer agent to analyze the implementation."
|
||||
</example>
|
||||
|
||||
<example>
|
||||
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."
|
||||
<commentary>
|
||||
Explicit review request triggers the agent.
|
||||
</commentary>
|
||||
</example>
|
||||
```
|
||||
|
||||
### Test Generation Agent
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
Context: User implemented functions without tests
|
||||
user: "I've added the data processing functions"
|
||||
assistant: "Great! Let me generate tests for these."
|
||||
<commentary>
|
||||
New code without tests, proactively trigger test-generator agent.
|
||||
</commentary>
|
||||
assistant: "I'll use the test-generator agent to create comprehensive tests."
|
||||
</example>
|
||||
|
||||
<example>
|
||||
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."
|
||||
<commentary>
|
||||
Direct test generation request triggers the agent.
|
||||
</commentary>
|
||||
</example>
|
||||
```
|
||||
|
||||
### Documentation Agent
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
Context: User added new API endpoints
|
||||
user: "I've implemented the REST API endpoints"
|
||||
assistant: "I'll document these endpoints."
|
||||
<commentary>
|
||||
New API code, proactively generate documentation.
|
||||
</commentary>
|
||||
assistant: "I'll use the api-docs-writer agent to create comprehensive documentation."
|
||||
</example>
|
||||
|
||||
<example>
|
||||
Context: User requests documentation
|
||||
user: "Write docs for this API"
|
||||
assistant: "I'll use the api-docs-writer agent to generate clear documentation."
|
||||
<commentary>
|
||||
Documentation request triggers the agent.
|
||||
</commentary>
|
||||
</example>
|
||||
```
|
||||
|
||||
### Validation Agent
|
||||
|
||||
```markdown
|
||||
<example>
|
||||
Context: User ready to commit changes
|
||||
user: "I'm ready to commit this code"
|
||||
assistant: "Let me validate it first."
|
||||
<commentary>
|
||||
Before commit, proactively validate with validation-agent.
|
||||
</commentary>
|
||||
assistant: "I'll use the code-validator agent to check for issues."
|
||||
</example>
|
||||
|
||||
<example>
|
||||
Context: User asks for validation
|
||||
user: "Validate my implementation"
|
||||
assistant: "I'll use the code-validator agent to verify correctness."
|
||||
<commentary>
|
||||
Explicit validation request triggers the agent.
|
||||
</commentary>
|
||||
</example>
|
||||
```
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user