@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/extensions/plugin-dev/skills/agent-development/references/triggering-examples.md

@@ -0,0 +1,474 @@
+# 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 (aligned with official Claude Code documentation):
+
+```markdown
+<example>
+Context: [Describe the situation - what led to this interaction]
+user: "[Exact user message or request]"
+assistant: "[How Claude invokes the agent - 'I'll use the [agent-name] agent to [action]']"
+<commentary>
+[Explanation of why this agent should be triggered in this scenario]
+</commentary>
+</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
+
+**Purpose:** Show Claude invoking the agent
+
+**Good responses:**
+
+```
+assistant: "I'll use the code-reviewer agent to analyze your OAuth implementation."
+assistant: "I'll use the pr-analyzer agent to review that PR for you."
+assistant: "I'll use the test-analyzer agent to investigate the test failure."
+```
+
+### 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>
+```
+
+## 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: "I'll use the security-analyzer agent to review the database code for security issues."
+<commentary>
+Database code written. Proactively trigger security-analyzer to check
+for SQL injection and other database security issues.
+</commentary>
+</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'll use the code-simplifier agent to refactor for better readability."
+<commentary>
+User indicates complexity issues. Trigger code-simplifier agent to improve clarity.
+</commentary>
+</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: "I'll use the test-quality-analyzer agent to verify the tests follow best practices."
+<commentary>
+Multiple Edit tools used on test files. Proactively trigger test-quality-analyzer
+to ensure tests follow best practices.
+</commentary>
+</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"
+assistant: "I'll use the code-reviewer agent to analyze the code."
+<commentary>
+Explicit review request triggers the agent.
+</commentary>
+</example>
+
+<example>
+Context: After user writes code
+user: "I've implemented the feature"
+assistant: "I'll use the code-reviewer agent to review the implementation."
+<commentary>
+Code written, proactively review for quality and issues.
+</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 for security and best practices."
+<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: "I'll use the code-reviewer agent to analyze the implementation."
+<commentary>
+Code written, proactively trigger code-reviewer agent.
+</commentary>
+</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: "I'll use the test-generator agent to create comprehensive tests."
+<commentary>
+New code without tests, proactively trigger test-generator agent.
+</commentary>
+</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 use the api-docs-writer agent to create comprehensive documentation."
+<commentary>
+New API code, proactively generate documentation.
+</commentary>
+</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: "I'll use the code-validator agent to check for issues before committing."
+<commentary>
+Before commit, proactively validate with validation-agent.
+</commentary>
+</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.

package/extensions/plugin-dev/skills/agent-development/scripts/create-agent-skeleton.sh

@@ -0,0 +1,176 @@
+#!/bin/bash
+# Agent Skeleton Generator
+# Creates a new agent file with correct structure
+
+set -euo pipefail
+
+# Usage
+if [ $# -eq 0 ]; then
+  echo "Usage: $0 <agent-name> [output-dir]"
+  echo ""
+  echo "Creates a skeleton agent file with:"
+  echo "  - Valid YAML frontmatter"
+  echo "  - Placeholder description with example block"
+  echo "  - Basic system prompt structure"
+  echo ""
+  echo "Arguments:"
+  echo "  agent-name   Agent identifier (lowercase, numbers, hyphens)"
+  echo "  output-dir   Directory to create file in (default: current directory)"
+  echo ""
+  echo "Examples:"
+  echo "  $0 code-reviewer agents/"
+  echo "  $0 test-generator"
+  echo ""
+  echo "After creation:"
+  echo "  1. Edit the file to fill in placeholders"
+  echo "  2. Add 2-4 triggering examples"
+  echo "  3. Write detailed system prompt"
+  echo "  4. Validate: ./scripts/validate-agent.sh <output-file>"
+  echo "  5. Test triggers: ./scripts/test-agent-trigger.sh <output-file>"
+  exit 1
+fi
+
+AGENT_NAME="$1"
+OUTPUT_DIR="${2:-.}"
+OUTPUT_FILE="$OUTPUT_DIR/$AGENT_NAME.md"
+
+echo "🔍 Creating agent skeleton: $AGENT_NAME"
+echo ""
+
+# Validate name format (lowercase alphanumeric + hyphens, 3-50 chars)
+if ! [[ "$AGENT_NAME" =~ ^[a-z0-9][a-z0-9-]*[a-z0-9]$ ]]; then
+  echo "❌ Invalid name: $AGENT_NAME"
+  echo ""
+  echo "Agent names must:"
+  echo "  - Start with a lowercase letter or number"
+  echo "  - End with a lowercase letter or number"
+  echo "  - Contain only lowercase letters, numbers, and hyphens"
+  echo "  - Be at least 3 characters long"
+  echo ""
+  echo "Valid examples: code-reviewer, test-gen, my-agent-123"
+  echo "Invalid examples: Code-Reviewer, -agent, agent-, a"
+  exit 1
+fi
+echo "✅ Name format valid"
+
+# Validate name length
+name_length=${#AGENT_NAME}
+if [ "$name_length" -lt 3 ]; then
+  echo "❌ Name too short: $name_length characters (minimum 3)"
+  exit 1
+fi
+if [ "$name_length" -gt 50 ]; then
+  echo "❌ Name too long: $name_length characters (maximum 50)"
+  exit 1
+fi
+echo "✅ Name length valid ($name_length characters)"
+
+# Check output directory exists
+if [ ! -d "$OUTPUT_DIR" ]; then
+  echo "❌ Directory does not exist: $OUTPUT_DIR"
+  echo ""
+  echo "Create it first with: mkdir -p $OUTPUT_DIR"
+  exit 1
+fi
+echo "✅ Output directory exists"
+
+# Check file doesn't already exist
+if [ -f "$OUTPUT_FILE" ]; then
+  echo "❌ File already exists: $OUTPUT_FILE"
+  echo ""
+  echo "Options:"
+  echo "  - Choose a different name"
+  echo "  - Delete the existing file: rm $OUTPUT_FILE"
+  echo "  - Edit the existing file directly"
+  exit 1
+fi
+echo "✅ Output path available"
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "📝 Creating agent file..."
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Create the agent skeleton file
+cat > "$OUTPUT_FILE" << EOF
+---
+name: $AGENT_NAME
+description: Use this agent when [describe triggering conditions]. Examples:
+
+<example>
+Context: [Describe the situation]
+user: "[What the user says]"
+assistant: "[How Claude responds before triggering]"
+<commentary>
+[Why this agent should trigger]
+</commentary>
+assistant: "I'll use the $AGENT_NAME agent to [action]."
+</example>
+
+<example>
+Context: [Second example situation]
+user: "[Another user request]"
+assistant: "[Claude's response]"
+<commentary>
+[Explanation of why this triggers the agent]
+</commentary>
+</example>
+
+model: inherit
+color: blue
+---
+
+You are [describe the agent's role and expertise].
+
+**Your Core Responsibilities:**
+
+1. [Primary responsibility]
+2. [Secondary responsibility]
+3. [Additional responsibility]
+
+**Process:**
+
+1. [First step]
+2. [Second step]
+3. [Third step]
+
+**Quality Standards:**
+
+- [Standard 1]
+- [Standard 2]
+- [Standard 3]
+
+**Output Format:**
+
+Provide results as:
+
+- [What to include]
+- [How to structure]
+EOF
+
+echo "✅ Created agent skeleton: $OUTPUT_FILE"
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "📋 Next Steps"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "1. Edit the file to fill in placeholders:"
+echo "   - Replace [bracketed text] with actual content"
+echo "   - Update description to explain when agent triggers"
+echo "   - Write 2-4 triggering examples"
+echo "   - Develop detailed system prompt"
+echo ""
+echo "2. Choose appropriate settings:"
+echo "   - model: inherit (default), sonnet, opus, or haiku"
+echo "   - color: blue (default), cyan, green, yellow, magenta, or red"
+echo "   - tools: Add array if restricting tools (optional)"
+echo ""
+echo "3. Validate the agent:"
+echo "   ./scripts/validate-agent.sh $OUTPUT_FILE"
+echo ""
+echo "4. Test triggering:"
+echo "   ./scripts/test-agent-trigger.sh $OUTPUT_FILE"
+echo ""
+echo "5. Load in Claude Code:"
+echo "   claude --plugin-dir /path/to/plugin"