Which documentation needs improvement?
Agent documentation
Specific Location
plugins/plugin-dev/agents/skill-reviewer.md - Lines 195-201
What's unclear or missing?
The "Edge Cases" section appears inside the output format markdown code block, creating ambiguity about whether it's an example of expected output or actual agent instructions.
Current structure (problematic):
**Output Format:**
\`\`\`markdown
## Skill Review: [skill-name]
...
**Edge Cases:**
- Skill with no description issues: Focus on content and organization
- Very long skill (>5,000 words): Strongly recommend splitting into references
...
\`\`\`
This agent helps users create high-quality skills...
The edge cases are embedded inside the output format example, but they are actually operational instructions for the agent, not part of the output template.
Suggested Improvement
Move the "Edge Cases" section outside the output format code block as a separate section at the end of the system prompt, consistent with how plugin-validator.md and agent-creator.md structure their edge cases:
**Output Format:**
\`\`\`markdown
## Skill Review: [skill-name]
...
### Overall Rating
...
\`\`\`
**Edge Cases:**
- Skill with no description issues: Focus on content and organization
- Very long skill (>5,000 words): Strongly recommend splitting into references
- New skill (minimal content): Provide constructive building guidance
- Perfect skill: Acknowledge quality and suggest minor enhancements only
- Missing referenced files: Report errors clearly with paths
This agent helps users create high-quality skills...
Type of issue
Additional Context
Found during comprehensive agent review comparing against Claude Code plugin subagent best practices and official documentation. The other two agents (plugin-validator.md, agent-creator.md) correctly place edge cases outside their output format examples.
Which documentation needs improvement?
Agent documentation
Specific Location
plugins/plugin-dev/agents/skill-reviewer.md- Lines 195-201What's unclear or missing?
The "Edge Cases" section appears inside the output format markdown code block, creating ambiguity about whether it's an example of expected output or actual agent instructions.
Current structure (problematic):
The edge cases are embedded inside the output format example, but they are actually operational instructions for the agent, not part of the output template.
Suggested Improvement
Move the "Edge Cases" section outside the output format code block as a separate section at the end of the system prompt, consistent with how
plugin-validator.mdandagent-creator.mdstructure their edge cases:Type of issue
Additional Context
Found during comprehensive agent review comparing against Claude Code plugin subagent best practices and official documentation. The other two agents (
plugin-validator.md,agent-creator.md) correctly place edge cases outside their output format examples.