mirror of
https://github.com/anthropics/claude-plugins-official.git
synced 2026-05-06 11:32:41 +00:00
Replace transcript-style agent examples with prose trigger descriptions
Several agent files used <example> blocks containing user: "..." / assistant: "..." turn markers, embedded as \n-escaped strings inside the YAML frontmatter description: field. Replace those with flat prose trigger descriptions in description: and a 'When to invoke' section in the agent body containing prose-bullet scenarios. Affected files: - 5 agent definitions: - plugins/hookify/agents/conversation-analyzer.md - plugins/pr-review-toolkit/agents/code-reviewer.md - plugins/pr-review-toolkit/agents/pr-test-analyzer.md - plugins/pr-review-toolkit/agents/type-design-analyzer.md - plugins/pr-review-toolkit/agents/comment-analyzer.md - 5 agent-development skill files updated to teach the new format: - plugins/plugin-dev/skills/agent-development/SKILL.md - .../references/triggering-examples.md - .../references/agent-creation-system-prompt.md - .../examples/complete-agent-examples.md - .../examples/agent-creation-prompt.md Routing is unaffected: each description: still names the trigger surface in plain English.
This commit is contained in:
Pete Blois
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user