Skip to content

Commit e830ff6

Browse files
konsta95claude
konsta95
and
claude
committed
plugin-dev: make agent descriptions parseable YAML and validate the form
Four shipped agent files (plugin-dev agent-creator, plugin-validator, skill-reviewer; pr-review-toolkit code-simplifier) carry a multi-line description with unindented continuation lines and a first line ending in "Examples:". Claude Code's YAML parser rejects that frontmatter: in .claude/agents/ the file is ignored, and as a plugin agent it is registered with the placeholder description "Agent from <plugin> plugin" and no triggering examples. - Rewrite the four descriptions as `description: |-` block scalars (text unchanged; code-simplifier's literal "\n" become line breaks). - Teach the same form in the agent-development skill: Complete Format, Minimal Agent, the description syntax note, the documented examples and references, and agent-creator's own instructions and template. - validate-agent.sh: read the description as a YAML parser does and reject the three shapes the parser cannot load (value ending in ':', unindented continuation, ': ' inside a plain continuation); stop aborting on a missing field (grep exit 1 under set -euo pipefail); count with $((x + 1)) instead of ((x++)). - validate-agent.test.sh: pin full-length extraction, exact length with keys after the description, the three rejections, the two accepted fragile shapes, warnings-only exit 0, optional tools, missing field. Co-Authored-By: Claude Fable 5.1 <[email protected]>
1 parent f173a69 commit e830ff6

11 files changed

Lines changed: 690 additions & 301 deletions

File tree

‎plugins/plugin-dev/agents/agent-creator.md‎

Lines changed: 50 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,34 @@
11
---
22
name: agent-creator
3-
description: Use this agent when the user asks to "create an agent", "generate an agent", "build a new agent", "make me an agent that...", or describes agent functionality they need. Trigger when user wants to create autonomous agents for plugins. Examples:
4-
5-
<example>
6-
Context: User wants to create a code review agent
7-
user: "Create an agent that reviews code for quality issues"
8-
assistant: "I'll use the agent-creator agent to generate the agent configuration."
9-
<commentary>
10-
User requesting new agent creation, trigger agent-creator to generate it.
11-
</commentary>
12-
</example>
13-
14-
<example>
15-
Context: User describes needed functionality
16-
user: "I need an agent that generates unit tests for my code"
17-
assistant: "I'll use the agent-creator agent to create a test generation agent."
18-
<commentary>
19-
User describes agent need, trigger agent-creator to build it.
20-
</commentary>
21-
</example>
22-
23-
<example>
24-
Context: User wants to add agent to plugin
25-
user: "Add an agent to my plugin that validates configurations"
26-
assistant: "I'll use the agent-creator agent to generate a configuration validator agent."
27-
<commentary>
28-
Plugin development with agent addition, trigger agent-creator.
29-
</commentary>
30-
</example>
3+
description: |-
4+
Use this agent when the user asks to "create an agent", "generate an agent", "build a new agent", "make me an agent that...", or describes agent functionality they need. Trigger when user wants to create autonomous agents for plugins. Examples:
5+
6+
<example>
7+
Context: User wants to create a code review agent
8+
user: "Create an agent that reviews code for quality issues"
9+
assistant: "I'll use the agent-creator agent to generate the agent configuration."
10+
<commentary>
11+
User requesting new agent creation, trigger agent-creator to generate it.
12+
</commentary>
13+
</example>
14+
15+
<example>
16+
Context: User describes needed functionality
17+
user: "I need an agent that generates unit tests for my code"
18+
assistant: "I'll use the agent-creator agent to create a test generation agent."
19+
<commentary>
20+
User describes agent need, trigger agent-creator to build it.
21+
</commentary>
22+
</example>
23+
24+
<example>
25+
Context: User wants to add agent to plugin
26+
user: "Add an agent to my plugin that validates configurations"
27+
assistant: "I'll use the agent-creator agent to generate a configuration validator agent."
28+
<commentary>
29+
Plugin development with agent addition, trigger agent-creator.
30+
</commentary>
31+
</example>
3132
3233
model: sonnet
3334
color: magenta
@@ -78,7 +79,8 @@ When a user describes what they want an agent to do, you will:
7879

7980
2. **Design Agent Configuration**:
8081
- **Identifier**: Create concise, descriptive name (lowercase, hyphens, 3-50 chars)
81-
- **Description**: Write triggering conditions starting with "Use this agent when..."
82+
- **Description**: Write triggering conditions starting with "Use this agent when...", as a
83+
YAML block scalar (`description: |-`) with every line indented two spaces
8284
- **Examples**: Create 2-4 `<example>` blocks with:
8385
```
8486
<example>
@@ -91,6 +93,11 @@ When a user describes what they want an agent to do, you will:
9193
assistant: "I'll use the [agent-name] agent to [what it does]."
9294
</example>
9395
```
96+
The examples are part of the `description` value. Write that value as a YAML block
97+
scalar (`description: |-`) and indent every line of it, `<example>` and `Context:` lines
98+
included, by two spaces. An unindented `<example>` line is a YAML parse error: Claude Code
99+
then drops the agent, or registers a plugin agent with the placeholder description
100+
"Agent from [plugin] plugin".
94101
- **System Prompt**: Create comprehensive instructions with:
95102
- Role and expertise
96103
- Core responsibilities (numbered list)
@@ -113,14 +120,27 @@ When a user describes what they want an agent to do, you will:
113120
```markdown
114121
---
115122
name: [identifier]
116-
description: [Use this agent when... Examples: <example>...</example>]
123+
description: |-
124+
Use this agent when [triggering conditions]. Examples:
125+
126+
<example>
127+
Context: [Situation that should trigger agent]
128+
user: "[User message]"
129+
assistant: "[Response before triggering]"
130+
<commentary>
131+
[Why agent should trigger]
132+
</commentary>
133+
</example>
117134
model: inherit
118135
color: [chosen-color]
119136
tools: ["Tool1", "Tool2"] # Optional
120137
---
121138
122139
[Complete system prompt]
123140
```
141+
The `|-` indicator makes the description a block scalar: the parser takes every indented
142+
line as description text, so `<example>` blocks with `Context:`, `user:` and `assistant:`
143+
lines are safe, and the strip indicator (`-`) keeps a trailing newline out of the text.
124144

125145
5. **Explain to User**: Provide summary of created agent:
126146
- What it does

‎plugins/plugin-dev/agents/plugin-validator.md‎

Lines changed: 31 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,36 @@
11
---
22
name: plugin-validator
3-
description: Use this agent when the user asks to "validate my plugin", "check plugin structure", "verify plugin is correct", "validate plugin.json", "check plugin files", or mentions plugin validation. Also trigger proactively after user creates or modifies plugin components. Examples:
4-
5-
<example>
6-
Context: User finished creating a new plugin
7-
user: "I've created my first plugin with commands and hooks"
8-
assistant: "Great! Let me validate the plugin structure."
9-
<commentary>
10-
Plugin created, proactively validate to catch issues early.
11-
</commentary>
12-
assistant: "I'll use the plugin-validator agent to check the plugin."
13-
</example>
14-
15-
<example>
16-
Context: User explicitly requests validation
17-
user: "Validate my plugin before I publish it"
18-
assistant: "I'll use the plugin-validator agent to perform comprehensive validation."
19-
<commentary>
20-
Explicit validation request triggers the agent.
21-
</commentary>
22-
</example>
23-
24-
<example>
25-
Context: User modified plugin.json
26-
user: "I've updated the plugin manifest"
27-
assistant: "Let me validate the changes."
28-
<commentary>
29-
Manifest modified, validate to ensure correctness.
30-
</commentary>
31-
assistant: "I'll use the plugin-validator agent to check the manifest."
32-
</example>
3+
description: |-
4+
Use this agent when the user asks to "validate my plugin", "check plugin structure", "verify plugin is correct", "validate plugin.json", "check plugin files", or mentions plugin validation. Also trigger proactively after user creates or modifies plugin components. Examples:
5+
6+
<example>
7+
Context: User finished creating a new plugin
8+
user: "I've created my first plugin with commands and hooks"
9+
assistant: "Great! Let me validate the plugin structure."
10+
<commentary>
11+
Plugin created, proactively validate to catch issues early.
12+
</commentary>
13+
assistant: "I'll use the plugin-validator agent to check the plugin."
14+
</example>
15+
16+
<example>
17+
Context: User explicitly requests validation
18+
user: "Validate my plugin before I publish it"
19+
assistant: "I'll use the plugin-validator agent to perform comprehensive validation."
20+
<commentary>
21+
Explicit validation request triggers the agent.
22+
</commentary>
23+
</example>
24+
25+
<example>
26+
Context: User modified plugin.json
27+
user: "I've updated the plugin manifest"
28+
assistant: "Let me validate the changes."
29+
<commentary>
30+
Manifest modified, validate to ensure correctness.
31+
</commentary>
32+
assistant: "I'll use the plugin-validator agent to check the manifest."
33+
</example>
3334
3435
model: inherit
3536
color: yellow

‎plugins/plugin-dev/agents/skill-reviewer.md‎

Lines changed: 30 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,35 @@
11
---
22
name: skill-reviewer
3-
description: Use this agent when the user has created or modified a skill and needs quality review, asks to "review my skill", "check skill quality", "improve skill description", or wants to ensure skill follows best practices. Trigger proactively after skill creation. Examples:
4-
5-
<example>
6-
Context: User just created a new skill
7-
user: "I've created a PDF processing skill"
8-
assistant: "Great! Let me review the skill quality."
9-
<commentary>
10-
Skill created, proactively trigger skill-reviewer to ensure it follows best practices.
11-
</commentary>
12-
assistant: "I'll use the skill-reviewer agent to review the skill."
13-
</example>
14-
15-
<example>
16-
Context: User requests skill review
17-
user: "Review my skill and tell me how to improve it"
18-
assistant: "I'll use the skill-reviewer agent to analyze the skill quality."
19-
<commentary>
20-
Explicit skill review request triggers the agent.
21-
</commentary>
22-
</example>
23-
24-
<example>
25-
Context: User modified skill description
26-
user: "I updated the skill description, does it look good?"
27-
assistant: "I'll use the skill-reviewer agent to review the changes."
28-
<commentary>
29-
Skill description modified, review for triggering effectiveness.
30-
</commentary>
31-
</example>
3+
description: |-
4+
Use this agent when the user has created or modified a skill and needs quality review, asks to "review my skill", "check skill quality", "improve skill description", or wants to ensure skill follows best practices. Trigger proactively after skill creation. Examples:
5+
6+
<example>
7+
Context: User just created a new skill
8+
user: "I've created a PDF processing skill"
9+
assistant: "Great! Let me review the skill quality."
10+
<commentary>
11+
Skill created, proactively trigger skill-reviewer to ensure it follows best practices.
12+
</commentary>
13+
assistant: "I'll use the skill-reviewer agent to review the skill."
14+
</example>
15+
16+
<example>
17+
Context: User requests skill review
18+
user: "Review my skill and tell me how to improve it"
19+
assistant: "I'll use the skill-reviewer agent to analyze the skill quality."
20+
<commentary>
21+
Explicit skill review request triggers the agent.
22+
</commentary>
23+
</example>
24+
25+
<example>
26+
Context: User modified skill description
27+
user: "I updated the skill description, does it look good?"
28+
assistant: "I'll use the skill-reviewer agent to review the changes."
29+
<commentary>
30+
Skill description modified, review for triggering effectiveness.
31+
</commentary>
32+
</example>
3233
3334
model: inherit
3435
color: cyan

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

Lines changed: 38 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -24,20 +24,21 @@ Agents are autonomous subprocesses that handle complex, multi-step tasks indepen
2424
```markdown
2525
---
2626
name: agent-identifier
27-
description: Use this agent when [triggering conditions]. Examples:
28-
29-
<example>
30-
Context: [Situation description]
31-
user: "[User request]"
32-
assistant: "[How assistant should respond and use this agent]"
33-
<commentary>
34-
[Why this agent should be triggered]
35-
</commentary>
36-
</example>
37-
38-
<example>
39-
[Additional example...]
40-
</example>
27+
description: |-
28+
Use this agent when [triggering conditions]. Examples:
29+
30+
<example>
31+
Context: [Situation description]
32+
user: "[User request]"
33+
assistant: "[How assistant should respond and use this agent]"
34+
<commentary>
35+
[Why this agent should be triggered]
36+
</commentary>
37+
</example>
38+
39+
<example>
40+
[Additional example...]
41+
</example>
4142

4243
model: inherit
4344
color: blue
@@ -83,26 +84,34 @@ Agent identifier used for namespacing and invocation.
8384

8485
Defines when Claude should trigger this agent. **This is the most critical field.**
8586

87+
**Syntax:** write it as a YAML block scalar with strip chomping (`description: |-`) and indent
88+
every line of the value by two spaces. A multi-line description without the indicator is not
89+
valid YAML: Claude Code logs `YAML frontmatter ... failed to parse` and ignores the agent
90+
(`.claude/agents/`), or registers a plugin agent with the placeholder description
91+
`Agent from <plugin> plugin`. `|-` rather than `|` keeps a trailing newline out of the text
92+
the model sees.
93+
8694
**Must include:**
8795
1. Triggering conditions ("Use this agent when...")
8896
2. Multiple `<example>` blocks showing usage
8997
3. Context, user request, and assistant response in each example
9098
4. `<commentary>` explaining why agent triggers
9199

92100
**Format:**
93-
```
94-
Use this agent when [conditions]. Examples:
95-
96-
<example>
97-
Context: [Scenario description]
98-
user: "[What user says]"
99-
assistant: "[How Claude should respond]"
100-
<commentary>
101-
[Why this agent is appropriate]
102-
</commentary>
103-
</example>
104-
105-
[More examples...]
101+
```yaml
102+
description: |-
103+
Use this agent when [conditions]. Examples:
104+
105+
<example>
106+
Context: [Scenario description]
107+
user: "[What user says]"
108+
assistant: "[How Claude should respond]"
109+
<commentary>
110+
[Why this agent is appropriate]
111+
</commentary>
112+
</example>
113+
114+
[More examples...]
106115
```
107116
108117
**Best practices:**
@@ -332,7 +341,8 @@ Ensure system prompt is complete:
332341
```markdown
333342
---
334343
name: simple-agent
335-
description: Use this agent when... Examples: <example>...</example>
344+
description: |-
345+
Use this agent when... Examples: <example>...</example>
336346
model: inherit
337347
color: blue
338348
---

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

Lines changed: 23 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,8 @@ Create `agents/[identifier].md`:
4343
```markdown
4444
---
4545
name: [identifier from JSON]
46-
description: [whenToUse from JSON]
46+
description: |-
47+
[whenToUse from JSON]
4748
model: inherit
4849
color: [choose: blue/cyan/green/yellow/magenta/red]
4950
tools: ["Read", "Write", "Grep"] # Optional: restrict tools
@@ -75,26 +76,27 @@ File: `agents/code-quality-reviewer.md`
7576
```markdown
7677
---
7778
name: code-quality-reviewer
78-
description: Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:
79-
80-
<example>
81-
Context: User just implemented a new feature
82-
user: "I've added the authentication feature"
83-
assistant: "Great! Let me review the code quality."
84-
<commentary>
85-
Code was written, trigger code-quality-reviewer agent for review.
86-
</commentary>
87-
assistant: "I'll use the code-quality-reviewer agent to analyze the changes."
88-
</example>
89-
90-
<example>
91-
Context: User explicitly requests review
92-
user: "Can you review my code for issues?"
93-
assistant: "I'll use the code-quality-reviewer agent to perform a thorough review."
94-
<commentary>
95-
Explicit review request triggers the agent.
96-
</commentary>
97-
</example>
79+
description: |-
80+
Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:
81+
82+
<example>
83+
Context: User just implemented a new feature
84+
user: "I've added the authentication feature"
85+
assistant: "Great! Let me review the code quality."
86+
<commentary>
87+
Code was written, trigger code-quality-reviewer agent for review.
88+
</commentary>
89+
assistant: "I'll use the code-quality-reviewer agent to analyze the changes."
90+
</example>
91+
92+
<example>
93+
Context: User explicitly requests review
94+
user: "Can you review my code for issues?"
95+
assistant: "I'll use the code-quality-reviewer agent to perform a thorough review."
96+
<commentary>
97+
Explicit review request triggers the agent.
98+
</commentary>
99+
</example>
98100

99101
model: inherit
100102
color: blue

0 commit comments

Comments
 (0)