diff options
Diffstat (limited to '')
| -rw-r--r-- | .agents/skills/skill-quality-reviewer/references/examples-good.md | 385 |
1 files changed, 385 insertions, 0 deletions
diff --git a/.agents/skills/skill-quality-reviewer/references/examples-good.md b/.agents/skills/skill-quality-reviewer/references/examples-good.md new file mode 100644 index 0000000..ed82f28 --- /dev/null +++ b/.agents/skills/skill-quality-reviewer/references/examples-good.md @@ -0,0 +1,385 @@ +# Exemplary Skill Examples + +Collection of high-quality skill examples demonstrating best practices across all quality dimensions. Study these when creating or improving skills. + +## Example 1: hook-development (A+ Grade) + +An exemplary skill demonstrating excellent description quality, progressive disclosure, and writing style. + +### Frontmatter (Description Quality) + +```yaml +--- +name: hook-development +description: This skill should be used when the user asks to "create a hook", +"add a PreToolUse hook", "validate tool use", "implement prompt-based hooks", +"use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous +commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, +SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides +comprehensive guidance for creating and implementing Claude Code plugin hooks +with focus on advanced prompt-based hooks API. +version: 0.1.0 +--- +``` + +**Why this is excellent:** +- ✅ 8+ specific trigger phrases covering diverse scenarios +- ✅ Third-person format throughout +- ✅ Includes specific hook events for precision +- ✅ Mentions key concepts (prompt-based hooks API) +- ✅ Length is appropriate (~400 characters, acceptable for complex skill) + +### Progressive Disclosure (Content Organization) + +**SKILL.md structure:** +- Overview (50 words) +- Core concepts (200 words) +- Hook events reference (300 words) +- Development workflow (500 words) +- Best practices (400 words) +- **Total: ~1,650 words** - excellent length + +**References/ directory:** +``` +references/ +├── prompt-based-hooks.md (800 words) - Detailed guide +├── hook-patterns.md (1,200 words) - Common patterns +└── migration-guide.md (900 words) - Migration info +``` + +**Why this is excellent:** +- ✅ SKILL.md is concise and focused +- ✅ Detailed content moved to 3 reference files +- ✅ Clear progressive disclosure +- ✅ Each reference file has specific purpose + +### Writing Style (Imperative Form) + +**Example from SKILL.md:** +```markdown +## Hook Development Workflow + +### Step 1: Define the Hook Event +Identify which event the hook should trigger on. Review available events +in the Hook Events Reference section. + +### Step 2: Create hooks.json +Create a hooks.json file in the plugin's .claude-plugin/ directory. +Specify the event type and command to execute. + +### Step 3: Implement the Hook Script +Write the hook script. Ensure it is executable. Follow the prompt-based +hooks API for complex hooks. + +### Step 4: Test the Hook +Test the hook locally. Verify it triggers on the correct event. +Check output and error handling. +``` + +**Why this is excellent:** +- ✅ Every instruction uses imperative form +- ✅ No "you", "your", "should" +- ✅ Clear, actionable steps +- ✅ Consistent style throughout + +--- + +## Example 2: agent-development (A Grade) + +Strong skill with good description and organization. + +### Frontmatter + +```yaml +--- +name: agent-development +description: This skill should be used when the user asks to "create an agent", +"add an agent", "write a subagent", "agent frontmatter", "when to use description", +"agent examples", "agent tools", "agent colors", "autonomous agent", or needs +guidance on agent structure, system prompts, triggering conditions, or agent +development best practices for Claude Code plugins. +version: 0.1.0 +--- +``` + +**Strengths:** +- ✅ Multiple specific trigger phrases +- ✅ Covers agent creation scenarios +- ✅ Mentions specific agent attributes + +### Directory Structure + +``` +agent-development/ +├── SKILL.md (1,438 words) +├── references/ +│ ├── agent-generation-prompt.md (500 words) +│ └── agent-anatomy.md (400 words) +└── examples/ + ├── task-agent.md (complete example) + ├── review-agent.md (complete example) + └── interactive-agent.md (complete example) +``` + +**Strengths:** +- ✅ Lean SKILL.md +- ✅ Focused reference files +- ✅ Complete working examples +- ✅ Clear organization + +--- + +## Example 3: mcp-integration (A- Grade) + +Comprehensive skill with excellent progressive disclosure. + +### Frontmatter + +```yaml +--- +name: mcp-integration +description: This skill should be used when the user asks to "add MCP server", +"integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model +Context Protocol", "connect external service", mentions "${CLAUDE_PLUGIN_ROOT} +with MCP", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides +comprehensive guidance for integrating Model Context Protocol servers into Claude +Code plugins for external tool and service integration. +version: 0.1.0 +--- +``` + +**Strengths:** +- ✅ Specific MCP-related trigger phrases +- ✅ Lists server types for precision +- ✅ Mentions key configuration elements + +### Progressive Disclosure + +**SKILL.md**: ~1,800 words (core concepts, basic setup) + +**References/**: +- `mcp-server-types.md` - Detailed server type comparisons +- `mcp-configuration.md` - Configuration examples +- `mcp-best-practices.md` - Integration patterns +- `mcp-troubleshooting.md` - Common issues + +**Why this works:** +- ✅ Main SKILL.md covers essentials +- ✅ Each reference is 1,000-2,000 words +- ✅ Loaded only when needed +- ✅ Clear topic separation + +--- + +## Excellent Description Examples + +### Example: API-Contract Skill (Ideal Description) + +```yaml +--- +name: api-contract-manager +description: This skill should be used when the user asks to "validate API contract", +"check API compatibility", "version API schema", "detect breaking changes", or +"ensure API contract compliance". Manages API contracts through validation, +versioning, and compatibility checking. Use when designing new endpoints or +ensuring backward compatibility. +version: 0.1.0 +--- +``` + +**Analysis:** +- ✅ 5 specific trigger phrases +- ✅ Third person throughout +- ✅ 230 characters (ideal length) +- ✅ Clear use cases +- ✅ Mentions when to use (designing, compatibility) + +### Example: PDF-Editor Skill (Ideal Description) + +```yaml +--- +name: pdf-editor +description: This skill should be used when the user asks to "rotate PDF", "merge +PDF files", "split PDF pages", "compress PDF", or "crop PDF pages". Perform common +PDF manipulation operations including rotation, merging, splitting, compression, +and cropping. Works with local PDF files. +version: 0.1.0 +--- +``` + +**Analysis:** +- ✅ 5 specific operations as triggers +- ✅ Lists all supported operations +- ✅ Specifies working context (local files) +- ✅ 180 characters (excellent length) + +--- + +## Excellent Progressive Disclosure Examples + +### Example: Frontend-Builder Skill + +**SKILL.md** (1,800 words): +- Overview +- Quick Start (5 steps) +- Basic Component Creation +- Common Operations +- Reference to detailed guides + +**References/**: +- `react-patterns.md` (2,500 words) - React specific patterns +- `vue-patterns.md` (2,000 words) - Vue specific patterns +- `styling-guide.md` (1,800 words) - CSS/styling approaches +- `deployment.md` (1,500 words) - Build and deploy + +**Examples/**: +- `hello-world-react/` - Complete React example +- `hello-world-vue/` - Complete Vue example +- `component-library/` - Reusable components + +**Why this works:** +1. SKILL.md gets users started quickly +2. Framework-specific details in references/ +3. Complete examples for copy-paste +4. Progressive: overview → basics → details → examples + +--- + +## Excellent Writing Style Examples + +### Example: From Test-Driven Development Skill + +```markdown +## TDD Workflow + +### Red: Write a Failing Test +Start by writing a test that fails. This test defines the desired behavior. +Run the test to confirm it fails. + +### Green: Make the Test Pass +Write the minimum code to make the test pass. Focus on making it work, +not making it perfect. Run the test to confirm it passes. + +### Refactor: Improve the Code +Refactor the code while keeping tests green. Improve structure, readability, +and maintainability. Run tests after each change. + +### Repeat +Continue the cycle for each feature. Write test, make it pass, refactor. +``` + +**Analysis:** +- ✅ Imperative form throughout +- ✅ Clear, actionable instructions +- ✅ No second person +- ✅ Consistent style +- ✅ Easy to follow + +--- + +## Excellent Reference File Organization + +### Example: Git-Workflow Skill References + +``` +references/ +├── commit-conventions.md (1,500 words) +│ ├── Commit message format +│ ├── Type categories +│ ├── Scope values +│ └── Examples by type +├── branch-strategy.md (1,800 words) +│ ├── Branch types +│ ├── Merging policies +│ ├── Release workflow +│ └── Hotfix procedures +└── troubleshooting.md (1,200 words) + ├── Common issues + ├── Recovery procedures + └── Best practices +``` + +**Each reference file:** +- ✅ Focused on single topic +- ✅ Self-contained +- ✅ Cross-references others when needed +- ✅ Loaded only when relevant + +--- + +## Key Takeaways from Excellent Skills + +### 1. Description Quality + +**Good descriptions:** +- Have 5+ specific trigger phrases +- Use third person consistently +- Are 100-300 characters long +- Include concrete use cases + +**Example template:** +```yaml +description: This skill should be used when the user asks to "action 1", +"action 2", "action 3", or "action 4". Brief description of what the skill +does. When to use it. +``` + +### 2. Progressive Disclosure + +**Good organization:** +- SKILL.md: 1,500-2,000 words (core only) +- references/: 1,500-2,500 words per file (details) +- examples/: Complete working code +- scripts/: Utility tools + +**Rule of thumb:** If a section exceeds 500 words and covers details, +consider moving it to references/. + +### 3. Writing Style + +**Good style:** +- Use imperative verbs: Create, Validate, Check, Run +- Avoid: You should, You can, You need to +- Be objective and factual +- Keep instructions actionable + +### 4. Structural Integrity + +**Good structure:** +``` +skill-name/ +├── SKILL.md (required) +├── references/ (optional, for details) +├── examples/ (optional, for working code) +└── scripts/ (optional, for utilities) +``` + +**Validation checklist:** +- [ ] YAML frontmatter has name and description +- [ ] All referenced files exist +- [ ] Examples are complete +- [ ] Scripts are executable + +--- + +## Study These Skills + +For hands-on learning, study these high-quality skills in your environment: + +```bash +# Explore hook-development structure +ls -la ~/.claude/plugins/cache/*/skills/hook-development/ + +# Read agent-development SKILL.md +cat ~/.claude/skills/agent-development/SKILL.md + +# Review mcp-integration references +ls -la ~/.claude/skills/mcp-integration/references/ +``` + +Each demonstrates different strengths: +- **hook-development**: Progressive disclosure, utilities +- **agent-development**: Clean examples, focused content +- **mcp-integration**: Comprehensive references, clear organization + +Use these as templates when creating or improving your own skills. |