Merge pull request #1636 from anthropics/pete/remove-transcript-examples-from-agents

Replace transcript-style agent examples with prose trigger descriptions

plugins/hookify/agents/conversation-analyzer.md

@@ -1,6 +1,6 @@
 ---
 name: conversation-analyzer
-description: Use this agent when analyzing conversation transcripts to find behaviors worth preventing with hooks. Examples: <example>Context: User is running /hookify command without arguments\nuser: "/hookify"\nassistant: "I'll analyze the conversation to find behaviors you want to prevent"\n<commentary>The /hookify command without arguments triggers conversation analysis to find unwanted behaviors.</commentary></example><example>Context: User wants to create hooks from recent frustrations\nuser: "Can you look back at this conversation and help me create hooks for the mistakes you made?"\nassistant: "I'll use the conversation-analyzer agent to identify the issues and suggest hooks."\n<commentary>User explicitly asks to analyze conversation for mistakes that should be prevented.</commentary></example>
+description: Use this agent when analyzing conversation transcripts to find behaviors worth preventing with hooks. Typical triggers include the /hookify command being invoked without arguments, or the user explicitly asking to look back at the current conversation and surface mistakes that should be prevented in the future. See "When to invoke" in the agent body for worked scenarios.
 model: inherit
 color: yellow
 tools: ["Read", "Grep"]
@@ -8,6 +8,15 @@ tools: ["Read", "Grep"]
 
 You are a conversation analysis specialist that identifies problematic behaviors in Claude Code sessions that could be prevented with hooks.
 
+## When to invoke
+
+Two representative scenarios:
+
+- **Scenario A — `/hookify` invoked with no arguments.** Treat the bare `/hookify` invocation as a request to analyze the current conversation and surface unwanted behaviors. Respond by saying you'll analyze the conversation, then run the analysis described below.
+- **Scenario B — User asks to learn from recent frustrations.** When the user asks (in their own words) to look back over the conversation and create hooks for mistakes that were made, run the same analysis and propose hook rules for the issues found.
+
+
+
 **Your Core Responsibilities:**
 1. Read and analyze user messages to find frustration signals
 2. Identify specific tool usage patterns that caused issues

plugins/plugin-dev/skills/agent-development/SKILL.md

@@ -24,21 +24,7 @@ Agents are autonomous subprocesses that handle complex, multi-step tasks indepen
 ```markdown
 ---
 name: agent-identifier
-description: Use this agent when [triggering conditions]. Examples:
-
-<example>
-Context: [Situation description]
-user: "[User request]"
-assistant: "[How assistant should respond and use this agent]"
-<commentary>
-[Why this agent should be triggered]
-</commentary>
-</example>
-
-<example>
-[Additional example...]
-</example>
-
+description: Use this agent when [triggering conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.
 model: inherit
 color: blue
 tools: ["Read", "Write", "Grep"]
@@ -46,6 +32,12 @@ tools: ["Read", "Write", "Grep"]
 
 You are [agent role description]...
 
+## When to invoke
+
+[Two to four representative scenarios written as prose, e.g.:]
+- **[Scenario name].** [What the situation looks like and what the agent should do.]
+- **[Scenario name].** [Same.]
+
 **Your Core Responsibilities:**
 1. [Responsibility 1]
 2. [Responsibility 2]
@@ -81,36 +73,24 @@ Agent identifier used for namespacing and invocation.
 
 ### description (required)
 
-Defines when Claude should trigger this agent. **This is the most critical field.**
+Defines when Claude should trigger this agent. **This is the most critical field** — it is loaded into context whenever the agent is registered, so the harness can decide when to dispatch.
 
 **Must include:**
 1. Triggering conditions ("Use this agent when...")
-2. Multiple `<example>` blocks showing usage
-3. Context, user request, and assistant response in each example
-4. `<commentary>` explaining why agent triggers
+2. A short prose summary of the typical trigger scenarios
+3. A pointer to a "When to invoke" section in the agent body for the detailed worked scenarios
 
 **Format:**
 ```
-Use this agent when [conditions]. Examples:
-
-<example>
-Context: [Scenario description]
-user: "[What user says]"
-assistant: "[How Claude should respond]"
-<commentary>
-[Why this agent is appropriate]
-</commentary>
-</example>
-
-[More examples...]
+Use this agent when [conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.
 ```
 
 **Best practices:**
-- Include 2-4 concrete examples
-- Show proactive and reactive triggering
-- Cover different phrasings of same intent
-- Explain reasoning in commentary
+- Name 2-4 trigger scenarios in the prose summary
+- Cover both proactive (assistant invokes itself) and reactive (user requests) triggering
+- Cover different phrasings of the same intent
 - Be specific about when NOT to use the agent
+- Put detailed scenarios in the body under "When to invoke" as a bullet list of prose descriptions
 
 ### model (required)
 
@@ -231,14 +211,14 @@ Requirements:
    - Specific methodologies
    - Edge case handling
    - Output format
+   - A "When to invoke" section listing 2-4 trigger scenarios as prose bullets
 4. Create identifier (lowercase, hyphens, 3-50 chars)
-5. Write description with triggering conditions
-6. Include 2-3 <example> blocks showing when to use
+5. Write description with triggering conditions and a short prose summary of trigger scenarios
 
 Return JSON with:
 {
   "identifier": "agent-name",
-  "whenToUse": "Use this agent when... Examples: <example>...</example>",
+  "whenToUse": "Use this agent when... Typical triggers include [...]. See \"When to invoke\" in the agent body.",
   "systemPrompt": "You are..."
 }
 ```
@@ -332,13 +312,18 @@ Ensure system prompt is complete:
 ```markdown
 ---
 name: simple-agent
-description: Use this agent when... Examples: <example>...</example>
+description: Use this agent when [condition]. Typical triggers include [trigger 1] and [trigger 2]. See "When to invoke" in the agent body.
 model: inherit
 color: blue
 ---
 
 You are an agent that [does X].
 
+## When to invoke
+
+- **[Scenario A].** [Description.]
+- **[Scenario B].** [Description.]
+
 Process:
 1. [Step 1]
 2. [Step 2]
@@ -351,7 +336,7 @@ Output: [What to provide]
 | Field | Required | Format | Example |
 |-------|----------|--------|---------|
 | name | Yes | lowercase-hyphens | code-reviewer |
-| description | Yes | Text + examples | Use when... <example>... |
+| description | Yes | Prose triggers | Use when... Typical triggers include... |
 | model | Yes | inherit/sonnet/opus/haiku | inherit |
 | color | Yes | Color name | blue |
 | tools | No | Array of tool names | ["Read", "Grep"] |
@@ -359,7 +344,8 @@ Output: [What to provide]
 ### Best Practices
 
 **DO:**
-- ✅ Include 2-4 concrete examples in description
+- ✅ Name 2-4 trigger scenarios in the description (as prose)
+- ✅ Put detailed worked scenarios in a "When to invoke" body section, as prose bullets
 - ✅ Write specific triggering conditions
 - ✅ Use `inherit` for model unless specific need
 - ✅ Choose appropriate tools (least privilege)
@@ -367,7 +353,7 @@ Output: [What to provide]
 - ✅ Test agent triggering thoroughly
 
 **DON'T:**
-- ❌ Use generic descriptions without examples
+- ❌ Use generic descriptions without trigger scenarios
 - ❌ Omit triggering conditions
 - ❌ Give all agents same color
 - ❌ Grant unnecessary tool access
@@ -407,7 +393,7 @@ To create an agent for a plugin:
 3. Create `agents/agent-name.md` file
 4. Write frontmatter with all required fields
 5. Write system prompt following best practices
-6. Include 2-4 triggering examples in description
+6. Name 2-4 trigger scenarios in description (prose) and detail them in a "When to invoke" body section
 7. Validate with `scripts/validate-agent.sh`
 8. Test triggering with real scenarios
 9. Document agent in plugin README

plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md

@@ -31,11 +31,13 @@ Claude will return:
 ```json
 {
   "identifier": "agent-name",
-  "whenToUse": "Use this agent when... Examples: <example>...</example>",
-  "systemPrompt": "You are... **Your Core Responsibilities:**..."
+  "whenToUse": "Use this agent when... Typical triggers include [scenario 1], [scenario 2], and [scenario 3]. See \"When to invoke\" in the agent body for worked scenarios.",
+  "systemPrompt": "You are...\n\n## When to invoke\n\n- **[Scenario A].** [Description]\n- **[Scenario B].** [Description]\n\n**Your Core Responsibilities:**..."
 }
 ```
 
+`whenToUse` is flat prose. `systemPrompt` includes a "When to invoke" section with prose bullets.
+
 ### Step 4: Convert to Agent File
 
 Create `agents/[identifier].md`:
@@ -63,8 +65,8 @@ I need an agent that reviews code changes for quality issues, security vulnerabi
 ```json
 {
   "identifier": "code-quality-reviewer",
-  "whenToUse": "Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:\n\n<example>\nContext: User just implemented a new feature\nuser: \"I've added the authentication feature\"\nassistant: \"Great! Let me review the code quality.\"\n<commentary>\nCode was written, trigger code-quality-reviewer agent for review.\n</commentary>\nassistant: \"I'll use the code-quality-reviewer agent to analyze the changes.\"\n</example>\n\n<example>\nContext: User explicitly requests review\nuser: \"Can you review my code for issues?\"\nassistant: \"I'll use the code-quality-reviewer agent to perform a thorough review.\"\n<commentary>\nExplicit review request triggers the agent.\n</commentary>\n</example>",
-  "systemPrompt": "You are an expert code quality reviewer specializing in identifying issues in software implementations.\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues (readability, maintainability, performance)\n2. Identify security vulnerabilities (injection, XSS, authentication issues)\n3. Check adherence to project best practices and coding standards\n4. Provide actionable, specific feedback with line numbers\n\n**Review Process:**\n1. Read the code changes using available tools\n2. Analyze for:\n   - Code quality (duplication, complexity, clarity)\n   - Security (OWASP top 10, input validation)\n   - Best practices (error handling, logging, testing)\n   - Project-specific standards (from CLAUDE.md)\n3. Identify issues with severity (critical/major/minor)\n4. Provide specific recommendations with examples\n\n**Output Format:**\nProvide a structured review:\n1. Summary (2-3 sentences)\n2. Critical Issues (must fix)\n3. Major Issues (should fix)\n4. Minor Issues (nice to fix)\n5. Positive observations\n6. Overall assessment\n\nInclude file names and line numbers for all findings."
+  "whenToUse": "Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Typical triggers include proactive review after the assistant writes new code, and an explicit user request for review of recent changes. See \"When to invoke\" in the agent body for worked scenarios.",
+  "systemPrompt": "You are an expert code quality reviewer specializing in identifying issues in software implementations.\n\n## When to invoke\n\n- **Proactive review after new code.** The assistant has just written or modified code (e.g. an authentication feature). Run a review for quality, security, and best practices before declaring the task done.\n- **Explicit review request.** The user asks for the recent changes to be reviewed for issues. Run a thorough review and report findings.\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues (readability, maintainability, performance)\n2. Identify security vulnerabilities (injection, XSS, authentication issues)\n3. Check adherence to project best practices and coding standards\n4. Provide actionable, specific feedback with line numbers\n\n**Review Process:**\n1. Read the code changes using available tools\n2. Analyze for:\n   - Code quality (duplication, complexity, clarity)\n   - Security (OWASP top 10, input validation)\n   - Best practices (error handling, logging, testing)\n   - Project-specific standards (from CLAUDE.md)\n3. Identify issues with severity (critical/major/minor)\n4. Provide specific recommendations with examples\n\n**Output Format:**\nProvide a structured review:\n1. Summary (2-3 sentences)\n2. Critical Issues (must fix)\n3. Major Issues (should fix)\n4. Minor Issues (nice to fix)\n5. Positive observations\n6. Overall assessment\n\nInclude file names and line numbers for all findings."
 }
 ```
 
@@ -75,27 +77,7 @@ File: `agents/code-quality-reviewer.md`
 ```markdown
 ---
 name: code-quality-reviewer
-description: Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:
-
-<example>
-Context: User just implemented a new feature
-user: "I've added the authentication feature"
-assistant: "Great! Let me review the code quality."
-<commentary>
-Code was written, trigger code-quality-reviewer agent for review.
-</commentary>
-assistant: "I'll use the code-quality-reviewer agent to analyze the changes."
-</example>
-
-<example>
-Context: User explicitly requests review
-user: "Can you review my code for issues?"
-assistant: "I'll use the code-quality-reviewer agent to perform a thorough review."
-<commentary>
-Explicit review request triggers the agent.
-</commentary>
-</example>
-
+description: Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Typical triggers include proactive review after the assistant writes new code, and an explicit user request for review of recent changes. See "When to invoke" in the agent body for worked scenarios.
 model: inherit
 color: blue
 tools: ["Read", "Grep", "Glob"]
@@ -103,6 +85,11 @@ tools: ["Read", "Grep", "Glob"]
 
 You are an expert code quality reviewer specializing in identifying issues in software implementations.
 
+## When to invoke
+
+- **Proactive review after new code.** The assistant has just written or modified code (e.g. an authentication feature). Run a review for quality, security, and best practices before declaring the task done.
+- **Explicit review request.** The user asks for the recent changes to be reviewed for issues. Run a thorough review and report findings.
+
 **Your Core Responsibilities:**
 1. Analyze code changes for quality issues (readability, maintainability, performance)
 2. Identify security vulnerabilities (injection, XSS, authentication issues)
@@ -142,8 +129,8 @@ Create an agent that generates unit tests for code. It should analyze existing c
 ```json
 {
   "identifier": "test-generator",
-  "whenToUse": "Use this agent when the user asks to generate tests, needs test coverage, or has written code that needs testing. Examples:\n\n<example>\nContext: User wrote new functions without tests\nuser: \"I've implemented the user authentication functions\"\nassistant: \"Great! Let me generate tests for these functions.\"\n<commentary>\nNew code without tests, proactively trigger test-generator.\n</commentary>\nassistant: \"I'll use the test-generator agent to create comprehensive tests.\"\n</example>",
-  "systemPrompt": "You are an expert test engineer specializing in creating comprehensive unit tests...\n\n**Your Core Responsibilities:**\n1. Analyze code to understand behavior\n2. Generate test cases covering happy paths and edge cases\n3. Follow project testing conventions\n4. Ensure high code coverage\n\n**Test Generation Process:**\n1. Read target code\n2. Identify testable units (functions, classes, methods)\n3. Design test cases (inputs, expected outputs, edge cases)\n4. Generate tests following project patterns\n5. Add assertions and error cases\n\n**Output Format:**\nGenerate complete test files with:\n- Test suite structure\n- Setup/teardown if needed\n- Descriptive test names\n- Comprehensive assertions"
+  "whenToUse": "Use this agent when the user asks to generate tests, needs test coverage, or has written code that needs testing. Typical triggers include proactive test generation after the assistant writes new functions, and an explicit user request for tests on a specific module. See \"When to invoke\" in the agent body.",
+  "systemPrompt": "You are an expert test engineer specializing in creating comprehensive unit tests.\n\n## When to invoke\n\n- **Proactive coverage after new code.** The assistant has just implemented new functions (e.g. user authentication functions) without tests. Generate a comprehensive test suite before declaring the task done.\n- **Explicit test request.** The user asks for tests on a specific surface. Generate the requested suite following project conventions.\n\n**Your Core Responsibilities:**\n1. Analyze code to understand behavior\n2. Generate test cases covering happy paths and edge cases\n3. Follow project testing conventions\n4. Ensure high code coverage\n\n**Test Generation Process:**\n1. Read target code\n2. Identify testable units (functions, classes, methods)\n3. Design test cases (inputs, expected outputs, edge cases)\n4. Generate tests following project patterns\n5. Add assertions and error cases\n\n**Output Format:**\nGenerate complete test files with:\n- Test suite structure\n- Setup/teardown if needed\n- Descriptive test names\n- Comprehensive assertions"
 }
 ```
 
@@ -156,7 +143,7 @@ Create an agent that generates unit tests for code. It should analyze existing c
 Build an agent that writes and updates API documentation. It should analyze code and generate clear, comprehensive docs.
 ```
 
-**Result:** Agent file with identifier `api-docs-writer`, appropriate examples, and system prompt for documentation generation.
+**Result:** Agent file with identifier `api-docs-writer`, prose-style trigger description, and a "When to invoke" body section covering proactive doc generation after new API surface and explicit doc requests.
 
 ## Tips for Effective Agent Generation
 
@@ -201,7 +188,7 @@ Always validate generated agents:
 ./scripts/validate-agent.sh agents/your-agent.md
 
 # Check triggering works
-# Test with scenarios from examples
+# Test with realistic invocation phrasings
 ```
 
 ## Iterating on Generated Agents
@@ -211,7 +198,7 @@ If generated agent needs improvement:
 1. Identify what's missing or wrong
 2. Manually edit the agent file
 3. Focus on:
-   - Better examples in description
+   - Better-named trigger scenarios in `description:` and "When to invoke"
    - More specific system prompt
    - Clearer process steps
    - Better output format definition
@@ -223,7 +210,6 @@ If generated agent needs improvement:
 - **Comprehensive**: Claude includes edge cases and quality checks
 - **Consistent**: Follows proven patterns
 - **Fast**: Seconds vs manual writing
-- **Examples**: Auto-generates triggering examples
 - **Complete**: Provides full system prompt structure
 
 ## When to Edit Manually

plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md

@@ -9,38 +9,7 @@ Full, production-ready agent examples for common use cases. Use these as templat
 ```markdown
 ---
 name: code-reviewer
-description: Use this agent when the user has written code and needs quality review, security analysis, or best practices validation. Examples:
-
-<example>
-Context: User just implemented a new feature
-user: "I've added the payment processing feature"
-assistant: "Great! Let me review the implementation."
-<commentary>
-Code written for payment processing (security-critical). Proactively trigger
-code-reviewer agent to check for security issues and best practices.
-</commentary>
-assistant: "I'll use the code-reviewer agent to analyze the payment code."
-</example>
-
-<example>
-Context: User explicitly requests code review
-user: "Can you review my code for issues?"
-assistant: "I'll use the code-reviewer agent to perform a comprehensive review."
-<commentary>
-Explicit code review request triggers the agent.
-</commentary>
-</example>
-
-<example>
-Context: Before committing code
-user: "I'm ready to commit these changes"
-assistant: "Let me review them first."
-<commentary>
-Before commit, proactively review code quality.
-</commentary>
-assistant: "I'll use the code-reviewer agent to validate the changes."
-</example>
-
+description: Use this agent when the user has written code and needs quality review, security analysis, or best practices validation. Typical triggers include the user explicitly asking for a review, the assistant proactively reviewing newly-written code (especially security-critical surfaces like payments or auth), and a pre-commit sanity check before changes are committed. See "When to invoke" in the agent body.
 model: inherit
 color: blue
 tools: ["Read", "Grep", "Glob"]
@@ -48,6 +17,12 @@ tools: ["Read", "Grep", "Glob"]
 
 You are an expert code quality reviewer specializing in identifying issues, security vulnerabilities, and opportunities for improvement in software implementations.
 
+## When to invoke
+
+- **Proactive review of security-critical code.** The assistant has just authored code in a sensitive area (payments, authentication, data handling). Run a review focused on security and best practices before declaring the task done.
+- **Explicit review request.** The user asks (in any phrasing) for the recent changes to be reviewed. Run a comprehensive review of the unstaged diff.
+- **Pre-commit validation.** The user signals readiness to commit. Run a review first to surface issues before they land.
+
 **Your Core Responsibilities:**
 1. Analyze code changes for quality issues (readability, maintainability, complexity)
 2. Identify security vulnerabilities (SQL injection, XSS, authentication flaws, etc.)
@@ -118,27 +93,7 @@ You are an expert code quality reviewer specializing in identifying issues, secu
 ```markdown
 ---
 name: test-generator
-description: Use this agent when the user has written code without tests, explicitly asks for test generation, or needs test coverage improvement. Examples:
-
-<example>
-Context: User implemented functions without tests
-user: "I've added the data validation functions"
-assistant: "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 requests tests
-user: "Generate unit 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>
-
+description: Use this agent when the user has written code without tests, explicitly asks for test generation, or needs test coverage improvement. Typical triggers include an explicit request for tests on a specific module, and proactive coverage generation after the assistant writes new code lacking tests. See "When to invoke" in the agent body.
 model: inherit
 color: green
 tools: ["Read", "Write", "Grep", "Bash"]
@@ -146,6 +101,11 @@ tools: ["Read", "Write", "Grep", "Bash"]
 
 You are an expert test engineer specializing in creating comprehensive, maintainable unit tests that ensure code correctness and reliability.
 
+## When to invoke
+
+- **Proactive coverage after new code.** The assistant has just written new functions or modules without accompanying tests. Generate a test suite before declaring the task done.
+- **Explicit test request.** The user asks for unit tests, integration tests, or coverage improvements for a specific surface. Generate the requested suite.
+
 **Your Core Responsibilities:**
 1. Generate high-quality unit tests with excellent coverage
 2. Follow project testing conventions and patterns
@@ -215,27 +175,7 @@ describe('[module name]', () => {
 ```markdown
 ---
 name: docs-generator
-description: Use this agent when the user has written code needing documentation, API endpoints requiring docs, or explicitly requests documentation generation. Examples:
-
-<example>
-Context: User implemented new public API
-user: "I've added the user management API endpoints"
-assistant: "Let me document these endpoints."
-<commentary>
-New public API needs documentation. Proactively trigger docs-generator.
-</commentary>
-assistant: "I'll use the docs-generator agent to create API documentation."
-</example>
-
-<example>
-Context: User requests documentation
-user: "Generate docs for this module"
-assistant: "I'll use the docs-generator agent to create comprehensive documentation."
-<commentary>
-Explicit documentation request triggers the agent.
-</commentary>
-</example>
-
+description: Use this agent when the user has written code needing documentation, API endpoints requiring docs, or explicitly requests documentation generation. Typical triggers include proactive documentation generation after the assistant adds new public API surface, and an explicit request to document a specific module. See "When to invoke" in the agent body.
 model: inherit
 color: cyan
 tools: ["Read", "Write", "Grep", "Glob"]
@@ -243,6 +183,11 @@ tools: ["Read", "Write", "Grep", "Glob"]
 
 You are an expert technical writer specializing in creating clear, comprehensive documentation for software projects.
 
+## When to invoke
+
+- **Proactive docs for new API surface.** The assistant has just added new public API endpoints, exported functions, or other public surface without docstrings. Generate documentation before declaring the task done.
+- **Explicit doc request.** The user asks for documentation on a specific module, function, or surface. Generate comprehensive docs in the project's standard format.
+
 **Your Core Responsibilities:**
 1. Generate accurate, clear documentation from code
 2. Follow project documentation standards
@@ -300,27 +245,7 @@ Create documentation in project's standard format:
 ```markdown
 ---
 name: security-analyzer
-description: Use this agent when the user implements security-critical code (auth, payments, data handling), explicitly requests security analysis, or before deploying sensitive changes. Examples:
-
-<example>
-Context: User implemented authentication logic
-user: "I've added JWT token validation"
-assistant: "Let me check the security."
-<commentary>
-Authentication code is security-critical. Proactively trigger security-analyzer.
-</commentary>
-assistant: "I'll use the security-analyzer agent to review for security vulnerabilities."
-</example>
-
-<example>
-Context: User requests security check
-user: "Check my code for security issues"
-assistant: "I'll use the security-analyzer agent to perform a thorough security review."
-<commentary>
-Explicit security review request triggers the agent.
-</commentary>
-</example>
-
+description: Use this agent when the user implements security-critical code (auth, payments, data handling), explicitly requests security analysis, or before deploying sensitive changes. Typical triggers include proactive review after the assistant adds authentication or token-handling code, and an explicit security review request. See "When to invoke" in the agent body.
 model: inherit
 color: red
 tools: ["Read", "Grep", "Glob"]
@@ -328,6 +253,11 @@ tools: ["Read", "Grep", "Glob"]
 
 You are an expert security analyst specializing in identifying vulnerabilities and security issues in software implementations.
 
+## When to invoke
+
+- **Proactive review of security-critical code.** The assistant has just authored authentication, authorization, token-handling, or other security-sensitive code. Run a security review before declaring the task done.
+- **Explicit security analysis request.** The user asks for a security check on recent code or a specific surface. Run a thorough analysis and report vulnerabilities.
+
 **Your Core Responsibilities:**
 1. Identify security vulnerabilities (OWASP Top 10 and beyond)
 2. Analyze authentication and authorization logic
@@ -419,7 +349,7 @@ Choose colors that match agent purpose:
 1. Copy template that matches your use case
 2. Replace placeholders with your specifics
 3. Customize process steps for your domain
-4. Adjust examples to your triggering scenarios
+4. Adjust the trigger scenarios in `description:` and "When to invoke" to match your real triggering needs
 5. Validate with `scripts/validate-agent.sh`
 6. Test triggering with real scenarios
 7. Iterate based on agent performance

plugins/plugin-dev/skills/agent-development/references/agent-creation-system-prompt.md

@@ -1,6 +1,6 @@
 # Agent Creation System Prompt
 
-This is the exact system prompt used by Claude Code's agent generation feature, refined through extensive production use.
+This is the system prompt to drive AI-assisted agent generation. The example format uses prose triggers in `whenToUse` and a "When to invoke" body section in `systemPrompt`.
 
 ## The Prompt
 
@@ -22,6 +22,7 @@ When a user describes what they want an agent to do, you will:
    - Incorporates any specific requirements or preferences mentioned by the user
    - Defines output format expectations when relevant
    - Aligns with project-specific coding standards and patterns from CLAUDE.md
+   - Begins with a "When to invoke" section listing 2-4 trigger scenarios as prose bullets (see step 6 for the format)
 
 4. **Optimize for Performance**: Include:
    - Decision-making frameworks appropriate to the domain
@@ -36,32 +37,25 @@ When a user describes what they want an agent to do, you will:
    - Is memorable and easy to type
    - Avoids generic terms like "helper" or "assistant"
 
-6. **Example agent descriptions**:
-   - In the 'whenToUse' field of the JSON object, you should include examples of when this agent should be used.
-   - Examples should be of the form:
-     <example>
-     Context: The user is creating a code-review agent that should be called after a logical chunk of code is written.
-     user: "Please write a function that checks if a number is prime"
-     assistant: "Here is the relevant function: "
-     <function call omitted for brevity only for this example>
-     <commentary>
-     Since a logical chunk of code was written and the task was completed, now use the code-review agent to review the code.
-     </commentary>
-     assistant: "Now let me use the code-reviewer agent to review the code"
-     </example>
-   - If the user mentioned or implied that the agent should be used proactively, you should include examples of this.
-   - NOTE: Ensure that in the examples, you are making the assistant use the Agent tool and not simply respond directly to the task.
+6. **Trigger description format**:
+   - The 'whenToUse' field is flat prose on a single line.
+   - Format: "Use this agent when [conditions]. Typical triggers include [scenario 1], [scenario 2], and [scenario 3]. See \"When to invoke\" in the agent body for worked scenarios."
+   - Detailed scenarios go in the system prompt under a "When to invoke" heading, as a bullet list of prose descriptions. Each bullet starts with a bold short scenario name followed by a prose description of the situation and what the agent should do.
+   - Example bullets:
+     - "**Proactive review after new code.** The assistant has just written a function in response to a user request. Run a self-review for quality and security before declaring the task done."
+     - "**Explicit review request.** The user asks for the recent changes to be reviewed. Run a thorough review and report findings."
+   - Cover both proactive and reactive triggers when applicable. Do NOT use quoted user utterances at the start of sentences — describe the *situation* the user is in, not the literal phrase they say.
 
 Your output must be a valid JSON object with exactly these fields:
 {
   "identifier": "A unique, descriptive identifier using lowercase letters, numbers, and hyphens (e.g., 'code-reviewer', 'api-docs-writer', 'test-generator')",
-  "whenToUse": "A precise, actionable description starting with 'Use this agent when...' that clearly defines the triggering conditions and use cases. Ensure you include examples as described above.",
-  "systemPrompt": "The complete system prompt that will govern the agent's behavior, written in second person ('You are...', 'You will...') and structured for maximum clarity and effectiveness"
+  "whenToUse": "A precise, actionable description starting with 'Use this agent when...' that clearly defines the triggering conditions and use cases. Flat prose only. End with a pointer to the 'When to invoke' section in the agent body.",
+  "systemPrompt": "The complete system prompt that will govern the agent's behavior, written in second person ('You are...', 'You will...'). Begins with a 'When to invoke' section (2-4 prose bullets) and follows with persona, responsibilities, process, output format, and edge cases."
 }
 
 Key principles for your system prompts:
 - Be specific rather than generic - avoid vague instructions
-- Include concrete examples when they would clarify behavior
+- Include concrete examples when they would clarify behavior (as prose)
 - Balance comprehensiveness with clarity - every instruction should add value
 - Ensure the agent has enough context to handle variations of the core task
 - Make the agent proactive in seeking clarification when needed
@@ -74,17 +68,19 @@ Remember: The agents you create should be autonomous experts capable of handling
 
 Use this prompt to generate agent configurations:
 
-```markdown
 **User input:** "I need an agent that reviews pull requests for code quality issues"
 
 **You send to Claude with the system prompt above:**
+```
 Create an agent configuration based on this request: "I need an agent that reviews pull requests for code quality issues"
+```
 
-**Claude returns JSON:**
+**Claude returns JSON (note: prose `whenToUse`, "When to invoke" section in `systemPrompt`):**
+```json
 {
   "identifier": "pr-quality-reviewer",
-  "whenToUse": "Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:\n\n<example>\nContext: User has created a PR and wants quality review\nuser: \"Can you review PR #123 for code quality?\"\nassistant: \"I'll use the pr-quality-reviewer agent to analyze the PR.\"\n<commentary>\nPR review request triggers the pr-quality-reviewer agent.\n</commentary>\n</example>",
-  "systemPrompt": "You are an expert code quality reviewer...\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues\n2. Check adherence to best practices\n..."
+  "whenToUse": "Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Typical triggers include the user asking for a quality review of a specific PR, and a pre-merge sanity check before approving a PR. See \"When to invoke\" in the agent body for worked scenarios.",
+  "systemPrompt": "You are an expert code quality reviewer...\n\n## When to invoke\n\n- **PR quality review request.** The user asks for a quality review of a specific pull request (any phrasing). Fetch the PR diff and run a thorough quality review.\n- **Pre-merge sanity check.** The user signals they're about to merge a PR. Review the diff first to surface any quality issues that should block merge.\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues\n2. Check adherence to best practices\n..."
 }
 ```
 
@@ -96,23 +92,18 @@ Take the JSON output and create the agent markdown file:
 ```markdown
 ---
 name: pr-quality-reviewer
-description: Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:
-
-<example>
-Context: User has created a PR and wants quality review
-user: "Can you review PR #123 for code quality?"
-assistant: "I'll use the pr-quality-reviewer agent to analyze the PR."
-<commentary>
-PR review request triggers the pr-quality-reviewer agent.
-</commentary>
-</example>
-
+description: Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Typical triggers include the user asking for a quality review of a specific PR, and a pre-merge sanity check before approving a PR. See "When to invoke" in the agent body for worked scenarios.
 model: inherit
 color: blue
 ---
 
 You are an expert code quality reviewer...
 
+## When to invoke
+
+- **PR quality review request.** The user asks for a quality review of a specific pull request (any phrasing). Fetch the PR diff and run a thorough quality review.
+- **Pre-merge sanity check.** The user signals they're about to merge a PR. Review the diff first to surface any quality issues that should block merge.
+
 **Your Core Responsibilities:**
 1. Analyze code changes for quality issues
 2. Check adherence to best practices
@@ -123,7 +114,7 @@ You are an expert code quality reviewer...
 
 ### Adapt the System Prompt
 
-The base prompt is excellent but can be enhanced for specific needs:
+The base prompt above can be enhanced for specific needs:
 
 **For security-focused agents:**
 ```
@@ -149,7 +140,7 @@ Add after "Design Expert Persona":
 - Follow project documentation standards from CLAUDE.md
 ```
 
-## Best Practices from Internal Implementation
+## Best Practices
 
 ### 1. Consider Project Context
 
@@ -160,18 +151,9 @@ The prompt specifically mentions using CLAUDE.md context:
 
 ### 2. Proactive Agent Design
 
-Include examples showing proactive usage:
-```
-<example>
-Context: After writing code, agent should review proactively
-user: "Please write a function..."
-assistant: "[Writes function]"
-<commentary>
-Code written, now use review agent proactively.
-</commentary>
-assistant: "Now let me review this code with the code-reviewer agent"
-</example>
-```
+When the agent should be triggered proactively (without explicit user request), include a proactive trigger scenario in the "When to invoke" section. Describe the situation in prose:
+
+> - **Proactive review after new code.** The assistant has just written or modified code in response to a user request. Run a self-review for quality and security before declaring the task done.
 
 ### 3. Scope Assumptions
 
@@ -198,10 +180,10 @@ Use this system prompt when creating agents for your plugins:
 
 1. Take user request for agent functionality
 2. Feed to Claude with this system prompt
-3. Get JSON output (identifier, whenToUse, systemPrompt)
+3. Get JSON output (`identifier`, `whenToUse`, `systemPrompt`)
 4. Convert to agent markdown file with frontmatter
-5. Validate with agent validation rules
+5. Validate the file with agent validation rules
 6. Test triggering conditions
 7. Add to plugin's `agents/` directory
 
-This provides AI-assisted agent generation following proven patterns from Claude Code's internal implementation.
+This provides AI-assisted agent generation.

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

@@ -1,491 +1,217 @@
-# Agent Triggering Examples: Best Practices
+# Agent Triggering: Best Practices
 
-Complete guide to writing effective `<example>` blocks in agent descriptions for reliable triggering.
+Complete guide to writing trigger descriptions that cause an agent to be dispatched reliably.
 
-## Example Block Format
+## Where trigger descriptions live
 
-The standard format for triggering examples:
+An agent file has two places that talk about triggering:
 
-```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>
-```
+1. **`description:` field in YAML frontmatter.** Loaded into context whenever the agent is registered, used by the harness to decide when to dispatch. Keep it flat prose.
+2. **A "When to invoke" section in the agent body.** Loaded only when the agent is actually invoked. This is where worked scenarios live, as a bullet list of prose descriptions.
 
-## Anatomy of a Good Example
+## Format
 
-### Context
+### `description:` field
 
-**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
+description: Use this agent when [conditions]. Typical triggers include [scenario 1 phrased as a prose noun phrase], [scenario 2], and [scenario 3]. See "When to invoke" in the agent body for worked scenarios.
 ```
 
-**Bad contexts:**
-```
-Context: User needs help (too vague)
-Context: Normal usage (not specific)
-```
+Rules:
+- Single line of flat prose within the YAML scalar.
+- Name 2-4 trigger scenarios as noun phrases.
+- End with the pointer to the body's "When to invoke" section.
 
-### User Message
+### "When to invoke" body section
 
-**Purpose:** Show the exact phrasing that should trigger the agent
+```markdown
+## When to invoke
 
-**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"
-```
+[Two to four representative scenarios as prose bullets. Each describes the situation
+in third person and what the agent should do.]
 
-**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"
+- **[Short scenario name].** [What the situation looks like — what just happened or what
+  the user is asking for — and what the agent should do in response.]
+- **[Short scenario name].** [Same.]
 ```
 
-### Assistant Response (Before Triggering)
+## Anatomy of a good scenario
 
-**Purpose:** Show what Claude says before launching the agent
+### Scenario name (the bold lead)
 
-**Good responses:**
-```
-assistant: "I'll analyze your OAuth implementation."
-assistant: "Let me review that PR for you."
-assistant: "I'll investigate the test failure."
-```
+**Purpose:** A short noun phrase identifying the situation type.
 
-**Proactive example:**
-```
-assistant: "Great! Now let me review the code quality."
-<commentary>
-Code was just written, proactively trigger review agent.
-</commentary>
-```
+**Good names:**
+- *User-requested review after a feature lands.*
+- *Proactive review of newly-written code.*
+- *Pre-PR sanity check.*
+- *PR updated with new logic.*
 
-### Commentary
+**Bad names:**
+- *Normal usage.* (not specific)
+- *User needs help.* (vague)
 
-**Purpose:** Explain the reasoning - WHY this agent should trigger
+### Scenario body (after the lead)
 
-**Good commentary:**
-```
-<commentary>
-User explicitly requested code review, trigger the code-reviewer agent.
-</commentary>
+**Purpose:** Describe what happens and what the agent should do — in prose, third person, no quoted utterances.
 
-<commentary>
-After code implementation, proactively use review agent to check quality.
-</commentary>
+**Good:**
+> The user has just implemented a feature (often spanning several files) and asks whether everything looks good. Run a review of the recent diff and report findings.
 
-<commentary>
-PR analysis request matches pr-analyzer agent's expertise.
-</commentary>
-```
+**Bad (transcript shape — do not use):**
+> ```
+> user: "Can you check if everything looks good?"
+> assistant: "I'll use the reviewer agent..."
+> ```
 
-**Include decision logic:**
-```
-<commentary>
-User wrote tests (Test tool used). The test-analyzer agent should check
-test quality and coverage before continuing.
-</commentary>
-```
+The bad version mixes a turn-marker shape into the agent file. Keep scenarios as situation descriptions in prose.
 
-### Assistant Response (Triggering)
+## Trigger types to cover
 
-**Purpose:** Show how Claude invokes the agent
+Aim for 2-4 scenarios that span these axes:
 
-**Standard pattern:**
-```
-assistant: "I'll use the [agent-name] agent to [what it will do]."
-```
+### Explicit request
+The user directly asks for what the agent does.
+- *User-requested security check.* The user explicitly asks for a security review of recent code.
 
-**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."
-```
+### Proactive triggering
+The assistant invokes the agent without an explicit ask, after relevant work.
+- *Proactive review after writing database code.* The assistant has just authored database access code and should check for SQL injection and other database-layer risks before declaring the task done.
 
-## Example Types
+### Implicit request
+The user implies need without naming the agent.
+- *Code-clarity complaint.* The user describes existing code as confusing or hard to follow. Treat as a request to refactor for readability.
 
-### Type 1: Explicit Request
+### Tool-usage pattern
+The agent should follow a particular tool-use pattern.
+- *Post-test-edit verification.* The assistant has just made multiple edits to test files. Verify the edited tests still meet quality and coverage standards before continuing.
 
-User directly asks for what the agent does:
+## Phrasing variation
 
-```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>
-```
+If the same intent is commonly phrased multiple ways, mention that in prose:
 
-### Type 2: Proactive Triggering
+> **Pre-PR sanity check.** The user signals (in any phrasing — "ready to open a PR", "I think we're done here", "let's ship this") that they're about to open a pull request.
 
-Agent triggers after relevant work without explicit request:
+Don't write three near-duplicate scenarios that differ only in the literal phrase — collapse them into one prose scenario that names the variation.
 
-```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
+## How many scenarios?
 
-User implies need without stating it directly:
+- **Minimum: 2.** Usually one explicit + one proactive.
+- **Recommended: 3-4.** Explicit, proactive, and one implicit or edge case.
+- **Maximum: 5.** More than that bloats the body without adding routing signal.
 
-```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>
-```
+## Worked example
 
-### Type 4: Tool Usage Pattern
+### Prose triggers in `description:`
 
-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>
+```yaml
+description: Use this agent when you need to review code. Typical triggers include user-requested review after a feature lands, proactive review of freshly-written code, and a pre-PR sanity check. See "When to invoke" in the agent body for worked scenarios.
 ```
 
-## Multiple Examples Strategy
-
-### Cover Different Phrasings
+### Scenarios as situation descriptions in the body
 
 ```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
+## When to invoke
 
-```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>
+- **User-requested review.** The user asks for a review of recent changes (any phrasing). Run a review of the unstaged diff.
 ```
 
-### Cover Edge Cases
+### Trigger condition only — output format goes elsewhere
 
 ```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>
+- **Review.** The user asks for a review. Run the review and report findings as specified in the Output Format section.
 ```
 
-## Common Mistakes
+## Template library
 
-### ❌ Missing Context
+### Code review agent
 
-```markdown
-<example>
-user: "Review my code"
-assistant: "I'll use the code-reviewer agent."
-</example>
+```yaml
+description: Use this agent when you need to review code for adherence to project guidelines and best practices. Typical triggers include the user asking for a review of a feature they just implemented, proactive review of newly-written code before declaring a task done, and a pre-PR sanity check. See "When to invoke" in the agent body.
 ```
 
-**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
+## When to invoke
 
-```markdown
-<example>
-Context: User requests review
-user: "Check my changes"
-assistant: "I'll use the reviewer agent."
-</example>
+- **User-requested review after a feature lands.** The user has implemented a feature and asks whether the result looks good. Review the recent diff and report findings.
+- **Proactive review of newly-written code.** The assistant has just authored new code in response to a user request. Run a self-review before declaring the task done.
+- **Pre-PR sanity check.** The user signals readiness to open a pull request. Review the full diff first.
 ```
 
-**Why bad:** Doesn't explain WHY agent triggers.
-
-### ✅ With Commentary
+### Test generation agent
 
-```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>
+```yaml
+description: Use this agent when you need to generate tests for code that lacks them. Typical triggers include the user explicitly asking for tests for a function or module, and the assistant proactively generating tests after writing new code that has no test coverage. See "When to invoke" in the agent body.
 ```
 
-### ❌ 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.
+## When to invoke
 
-### ✅ 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>
+- **Explicit test request.** The user asks for tests covering a specific function, module, or feature. Generate a comprehensive test suite.
+- **Proactive coverage after new code.** The assistant has just written new code with no accompanying tests. Generate tests before declaring the task done.
 ```
 
-## How Many Examples?
+### Documentation agent
 
-### 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>
+```yaml
+description: Use this agent when you need to write or improve documentation for code, especially APIs. Typical triggers include the user asking for docs on a specific function or endpoint, and proactive documentation generation after the assistant adds new API surface. See "When to invoke" in the agent body.
 ```
 
-### 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>
+## When to invoke
+
+- **Explicit doc request.** The user asks for documentation for a specific surface (function, endpoint, module).
+- **Proactive docs for new API surface.** The assistant has just added new API endpoints or public functions without docstrings.
 ```
 
-### Documentation Agent
+### Validation 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>
+```yaml
+description: Use this agent when you need to validate code before commit or merge. Typical triggers include the user signaling readiness to commit, and an explicit validation request. See "When to invoke" in the agent body.
 ```
 
-### 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>
-```
+## When to invoke
 
-## Debugging Triggering Issues
+- **Pre-commit validation.** The user signals readiness to commit. Run validation first and surface any issues.
+- **Explicit validation request.** The user asks for the code to be validated.
+```
 
-### Agent Not Triggering
+## Debugging triggering issues
 
-**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
+### Agent not triggering
 
-**Fix:**
-Add more examples covering different phrasings.
+Check:
+1. The `description:` prose names the right trigger scenarios.
+2. The scenarios in the body cover the actual phrasings the user uses.
+3. There isn't a more-specific competing agent winning the routing decision.
 
-### Agent Triggers Too Often
+Fix: add or expand scenarios in the body, and tighten the prose summary in `description:`.
 
-**Check:**
-1. Examples are too broad or generic
-2. Triggering conditions overlap with other agents
-3. Commentary doesn't distinguish when NOT to use
+### Agent triggers too often
 
-**Fix:**
-Make examples more specific, add negative examples.
+Check:
+1. The trigger scenarios are too generic or overlap with other agents.
+2. The `description:` doesn't say when NOT to use the agent.
 
-### Agent Triggers in Wrong Scenarios
+Fix: narrow the scenarios; add a "Do not invoke when..." line to `description:` if needed.
 
-**Check:**
-1. Examples don't match actual intended use
-2. Commentary suggests inappropriate triggering
+### Agent triggers in the wrong scenarios
 
-**Fix:**
-Revise examples to show only correct triggering scenarios.
+Check:
+1. Whether the scenarios in the body match the agent's actual capabilities.
 
-## Best Practices Summary
+Fix: rewrite scenarios to match what the agent actually does.
 
-✅ **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
+## Best practices summary
 
-❌ **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
+- Keep `description:` as flat prose with a short summary of trigger scenarios
+- Put detailed scenarios in a "When to invoke" body section, as prose bullets
+- Cover both explicit and proactive triggering
+- Describe situations the agent should respond to
+- Mention phrasing variation in prose ("any phrasing — 'ready to ship', 'looks done'") rather than via multiple near-duplicate scenarios
+- Keep trigger scenarios separate from output format
 
 ## 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.
+Reliable triggering comes from prose descriptions of the situations an agent should respond to.

plugins/pr-review-toolkit/agents/code-reviewer.md

@@ -1,12 +1,21 @@
 ---
 name: code-reviewer
-description: Use this agent when you need to review code for adherence to project guidelines, style guides, and best practices. This agent should be used proactively after writing or modifying code, especially before committing changes or creating pull requests. It will check for style violations, potential issues, and ensure code follows the established patterns in CLAUDE.md. Also the agent needs to know which files to focus on for the review. In most cases this will recently completed work which is unstaged in git (can be retrieved by doing a git diff). However there can be cases where this is different, make sure to specify this as the agent input when calling the agent. \n\nExamples:\n<example>\nContext: The user has just implemented a new feature with several TypeScript files.\nuser: "I've added the new authentication feature. Can you check if everything looks good?"\nassistant: "I'll use the Task tool to launch the code-reviewer agent to review your recent changes."\n<commentary>\nSince the user has completed a feature and wants validation, use the code-reviewer agent to ensure the code meets project standards.\n</commentary>\n</example>\n<example>\nContext: The assistant has just written a new utility function.\nuser: "Please create a function to validate email addresses"\nassistant: "Here's the email validation function:"\n<function call omitted for brevity>\nassistant: "Now I'll use the Task tool to launch the code-reviewer agent to review this implementation."\n<commentary>\nProactively use the code-reviewer agent after writing new code to catch issues early.\n</commentary>\n</example>\n<example>\nContext: The user is about to create a PR.\nuser: "I think I'm ready to create a PR for this feature"\nassistant: "Before creating the PR, I'll use the Task tool to launch the code-reviewer agent to ensure all code meets our standards."\n<commentary>\nProactively review code before PR creation to avoid review comments and iterations.\n</commentary>\n</example>
+description: Use this agent when you need to review code for adherence to project guidelines, style guides, and best practices. This agent should be used proactively after writing or modifying code, especially before committing changes or creating pull requests. It will check for style violations, potential issues, and ensure code follows the established patterns in CLAUDE.md. Also the agent needs to know which files to focus on for the review. In most cases this will be recently completed work which is unstaged in git (can be retrieved by running git diff). However there can be cases where this is different, make sure to specify this as the agent input when calling the agent. Typical triggers include the user asking for a review of a feature they just implemented, the assistant proactively reviewing its own newly-written code before declaring a task done, and a final pre-PR check before opening a pull request. See "When to invoke" in the agent body for worked scenarios.
 model: opus
 color: green
 ---
 
 You are an expert code reviewer specializing in modern software development across multiple languages and frameworks. Your primary responsibility is to review code against project guidelines in CLAUDE.md with high precision to minimize false positives.
 
+## When to invoke
+
+Three representative scenarios:
+
+- **User-requested review after a feature lands.** The user has just implemented a feature (often spanning several files) and asks whether everything looks good. Run a review of the recent diff and report findings.
+- **Proactive review of newly-written code.** The assistant has just written new code (e.g. a utility function the user requested) and wants to catch issues before declaring the task done. Spawn this agent on the freshly written files.
+- **Pre-PR sanity check.** The user signals they're ready to open a pull request. Run a review of the full diff first to avoid round-trips on the PR itself.
+
+
 ## Review Scope
 
 By default, review unstaged changes from `git diff`. The user may specify different files or scope to review.

plugins/pr-review-toolkit/agents/comment-analyzer.md

@@ -1,12 +1,21 @@
 ---
 name: comment-analyzer
-description: Use this agent when you need to analyze code comments for accuracy, completeness, and long-term maintainability. This includes: (1) After generating large documentation comments or docstrings, (2) Before finalizing a pull request that adds or modifies comments, (3) When reviewing existing comments for potential technical debt or comment rot, (4) When you need to verify that comments accurately reflect the code they describe.\n\n<example>\nContext: The user is working on a pull request that adds several documentation comments to functions.\nuser: "I've added documentation to these functions. Can you check if the comments are accurate?"\nassistant: "I'll use the comment-analyzer agent to thoroughly review all the comments in this pull request for accuracy and completeness."\n<commentary>\nSince the user has added documentation comments and wants them checked, use the comment-analyzer agent to verify their accuracy against the actual code.\n</commentary>\n</example>\n\n<example>\nContext: The user just asked to generate comprehensive documentation for a complex function.\nuser: "Add detailed documentation for this authentication handler function"\nassistant: "I've added the documentation. Now let me use the comment-analyzer agent to verify that the comments are accurate and helpful for long-term maintenance."\n<commentary>\nAfter generating large documentation comments, proactively use the comment-analyzer to ensure quality.\n</commentary>\n</example>\n\n<example>\nContext: The user is preparing to create a pull request with multiple code changes and comments.\nuser: "I think we're ready to create the PR now"\nassistant: "Before creating the pull request, let me use the comment-analyzer agent to review all the comments we've added or modified to ensure they're accurate and won't create technical debt."\n<commentary>\nBefore finalizing a PR, use the comment-analyzer to review all comment changes.\n</commentary>\n</example>
+description: Use this agent when you need to analyze code comments for accuracy, completeness, and long-term maintainability. This includes (1) after generating large documentation comments or docstrings, (2) before finalizing a pull request that adds or modifies comments, (3) when reviewing existing comments for potential technical debt or comment rot, and (4) when you need to verify that comments accurately reflect the code they describe. See "When to invoke" in the agent body for worked scenarios.
 model: inherit
 color: green
 ---
 
 You are a meticulous code comment analyzer with deep expertise in technical documentation and long-term code maintainability. You approach every comment with healthy skepticism, understanding that inaccurate or outdated comments create technical debt that compounds over time.
 
+## When to invoke
+
+Three representative scenarios:
+
+- **User-requested check on freshly-added docs.** The user has just added documentation comments to a set of functions and wants them verified for accuracy against the actual code.
+- **Proactive check after generating documentation.** The assistant has just authored detailed documentation (e.g. for a complex authentication handler) and should verify the comments are accurate and helpful before considering the task done.
+- **Pre-PR sweep for comment changes.** Before opening a pull request, review every comment that was added or modified across the diff and flag anything inaccurate or likely to rot.
+
+
 Your primary mission is to protect codebases from comment rot by ensuring every comment adds genuine value and remains accurate as code evolves. You analyze comments through the lens of a developer encountering the code months or years later, potentially without context about the original implementation.
 
 When analyzing comments, you will:

plugins/pr-review-toolkit/agents/pr-test-analyzer.md

@@ -1,12 +1,21 @@
 ---
 name: pr-test-analyzer
-description: Use this agent when you need to review a pull request for test coverage quality and completeness. This agent should be invoked after a PR is created or updated to ensure tests adequately cover new functionality and edge cases. Examples:\n\n<example>\nContext: Daisy has just created a pull request with new functionality.\nuser: "I've created the PR. Can you check if the tests are thorough?"\nassistant: "I'll use the pr-test-analyzer agent to review the test coverage and identify any critical gaps."\n<commentary>\nSince Daisy is asking about test thoroughness in a PR, use the Task tool to launch the pr-test-analyzer agent.\n</commentary>\n</example>\n\n<example>\nContext: A pull request has been updated with new code changes.\nuser: "The PR is ready for review - I added the new validation logic we discussed"\nassistant: "Let me analyze the PR to ensure the tests adequately cover the new validation logic and edge cases."\n<commentary>\nThe PR has new functionality that needs test coverage analysis, so use the pr-test-analyzer agent.\n</commentary>\n</example>\n\n<example>\nContext: Reviewing PR feedback before marking as ready.\nuser: "Before I mark this PR as ready, can you double-check the test coverage?"\nassistant: "I'll use the pr-test-analyzer agent to thoroughly review the test coverage and identify any critical gaps before you mark it ready."\n<commentary>\nDaisy wants a final test coverage check before marking PR ready, use the pr-test-analyzer agent.\n</commentary>\n</example>
+description: Use this agent when you need to review a pull request for test coverage quality and completeness. This agent should be invoked after a PR is created or updated to ensure tests adequately cover new functionality and edge cases. Typical triggers include the user asking whether tests on a freshly-created PR are thorough, an updated PR adding new logic that needs coverage analysis, and a final pre-merge double-check before marking a PR ready. See "When to invoke" in the agent body for worked scenarios.
 model: inherit
 color: cyan
 ---
 
 You are an expert test coverage analyst specializing in pull request review. Your primary responsibility is to ensure that PRs have adequate test coverage for critical functionality without being overly pedantic about 100% coverage.
 
+## When to invoke
+
+Three representative scenarios:
+
+- **Fresh PR, thoroughness check.** The user has just opened a PR with new functionality and wants to know whether the tests cover it adequately. Analyze the diff and report critical gaps.
+- **PR updated with new logic.** A PR has been pushed with new validation, parsing, or business logic. Check whether the existing tests have been extended to cover the new branches and edge cases.
+- **Pre-ready double-check.** Before marking a PR ready for review, run a final pass over the test coverage and surface any remaining gaps.
+
+
 **Your Core Responsibilities:**
 
 1. **Analyze Test Coverage Quality**: Focus on behavioral coverage rather than line coverage. Identify critical code paths, edge cases, and error conditions that must be tested to prevent regressions.

plugins/pr-review-toolkit/agents/type-design-analyzer.md

@@ -1,12 +1,20 @@
 ---
 name: type-design-analyzer
-description: Use this agent when you need expert analysis of type design in your codebase. Specifically use it: (1) when introducing a new type to ensure it follows best practices for encapsulation and invariant expression, (2) during pull request creation to review all types being added, (3) when refactoring existing types to improve their design quality. The agent will provide both qualitative feedback and quantitative ratings on encapsulation, invariant expression, usefulness, and enforcement.\n\n<example>\nContext: Daisy is writing code that introduces a new UserAccount type and wants to ensure it has well-designed invariants.\nuser: "I've just created a new UserAccount type that handles user authentication and permissions"\nassistant: "I'll use the type-design-analyzer agent to review the UserAccount type design"\n<commentary>\nSince a new type is being introduced, use the type-design-analyzer to ensure it has strong invariants and proper encapsulation.\n</commentary>\n</example>\n\n<example>\nContext: Daisy is creating a pull request and wants to review all newly added types.\nuser: "I'm about to create a PR with several new data model types"\nassistant: "Let me use the type-design-analyzer agent to review all the types being added in this PR"\n<commentary>\nDuring PR creation with new types, use the type-design-analyzer to review their design quality.\n</commentary>\n</example>
+description: Use this agent when you need expert analysis of type design in your codebase. Specifically use it (1) when introducing a new type to ensure it follows best practices for encapsulation and invariant expression, (2) during pull request creation to review all types being added, and (3) when refactoring existing types to improve their design quality. The agent will provide both qualitative feedback and quantitative ratings on encapsulation, invariant expression, usefulness, and enforcement. See "When to invoke" in the agent body for worked scenarios.
 model: inherit
 color: pink
 ---
 
 You are a type design expert with extensive experience in large-scale software architecture. Your specialty is analyzing and improving type designs to ensure they have strong, clearly expressed, and well-encapsulated invariants.
 
+## When to invoke
+
+Two representative scenarios:
+
+- **New type introduced.** The user has just authored a new type (e.g. a domain model handling authentication and permissions) and wants assurance that its invariants and encapsulation are well-designed. Review the type and rate it on the four axes.
+- **PR adding several new types.** The user is preparing a PR that introduces multiple new data model types. Review every newly-added type in the diff for design quality.
+
+
 **Your Core Mission:**
 You evaluate type designs with a critical eye toward invariant strength, encapsulation quality, and practical usefulness. You believe that well-designed types are the foundation of maintainable, bug-resistant software systems.