Skill Mentorship Guide

This guide documents best practices extracted from high-performing skills. Use these patterns when creating or improving skills.

High-Performing Mentors

The following skills have 80%+ success rate and can serve as templates:

Skill	Success Rate	Key Sections

Pattern Adoption Rates

Pattern	Adoption	Correlation
Required Tools	1/223	High
Output Validation	0/223	High
Pre-flight Checklist	1/223	Medium
Examples	66/223	Medium
Anti-Patterns	222/223	Medium
Scope Boundaries	1/223	Low

Recommended Sections

1. Required Tools (Highest Impact)

Every skill should have a Required Tools table:

## Required Tools

| Tool | Purpose | Required |
|------|---------|----------|
| `Read` | Access source files | Yes |
| `Glob` | Find files by pattern | Yes |
| `Write` | Create output files | Optional |

2. Output Validation (High Impact)

Include a validation checklist:

## Output Validation

Before completing, verify output contains:
- [ ] All required sections present
- [ ] No placeholder text (TODO, FIXME)
- [ ] Proper formatting applied
- [ ] Examples included where applicable

3. Pre-flight Checklist (Medium Impact)

Prevent failures with prerequisites:

## Pre-flight Checklist

- [ ] Required context captured (`/cx` run)
- [ ] Target files exist and accessible
- [ ] Environment variables set
- [ ] Dependencies installed

4. Anti-Patterns (Prevention)

Document what NOT to do:

## Anti-Patterns

| Anti-Pattern | Problem | Solution |
|--------------|---------|----------|
| Skipping validation | Silent failures | Always validate output |
| Hardcoded paths | Portability issues | Use relative paths |
| Missing examples | User confusion | Include 2-3 examples |

Using the Mentor System

# Find mentors for a skill
python3 scripts/skill-mentor.py --suggest <skill-name>

# Generate improvement diff
python3 scripts/skill-mentor.py --diff <skill-name>

# View all high-scoring mentors
python3 scripts/skill-mentor.py --mentors

Success Metrics

Skills with all recommended sections average:

• 85%+ success rate
• Fewer retries
• Better user satisfaction

---

Generated by skill-mentor.py on 2026-01-11