-
Notifications
You must be signed in to change notification settings - Fork 2
Description
Problem
The SKILL.md currently has a comprehensive "Complete Format" example in the Agent File Structure section (~50 lines), but no minimal quick-start example for users who want to get started immediately.
Users often want a copy-paste template that "just works" before diving into all the options. The complete format, while thorough, can be overwhelming for first-time agent creators.
Current State
The first example users see is the "Complete Format" which includes:
- All frontmatter fields with explanations
- Full system prompt structure
- Multiple responsibilities, process steps, quality standards
Recommended Fix
Add a "Quick Start" or "Minimal Example" section immediately after Overview, before the detailed "Agent File Structure":
## Quick Start
Minimal working agent:
\`\`\`markdown
---
name: my-reviewer
description: Use this agent when the user asks to review code. Examples:
<example>
Context: User wrote new code
user: "Review my changes"
assistant: "I'll use the my-reviewer agent to analyze the code."
<commentary>
Code review request triggers the agent.
</commentary>
</example>
model: inherit
color: blue
---
You are a code reviewer. Analyze code for issues and provide feedback.
**Process:**
1. Read the code
2. Identify issues
3. Provide recommendations
**Output:** Summary with file:line references for each finding.
\`\`\`
For complete format with all options, see [Agent File Structure](#agent-file-structure).Additional Enhancement
In the model field section, emphasize that inherit is the recommended default:
Current:
**Recommendation:** Use `inherit` unless agent needs specific model capabilities.Improved:
**Recommendation:** Use `inherit` (recommended default) unless the agent specifically needs:
- `haiku` for fast, cost-sensitive operations
- `opus` for complex reasoning requiring maximum capabilityAcceptance Criteria
- Minimal ~20-line working example added after Overview
- Example is complete and copy-paste ready
- Links to detailed sections for more options
- Model section emphasizes
inheritas default more clearly - Word count stays within ideal range (currently 1,654 words, target <2,000)
Files to Modify
plugins/plugin-dev/skills/agent-development/SKILL.md
Notes
This enhancement improves onboarding for new users while maintaining the comprehensive documentation for advanced users. The progressive disclosure principle supports having both quick-start and detailed content.