Skip to content

docs(agent-development): add minimal working example after Overview #25

@sjnims

Description

@sjnims

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 capability

Acceptance 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 inherit as 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.

Metadata

Metadata

Assignees

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions