general-skill-refiner

# General Skill Refiner

## Overview

**Purpose:** Critical analysis and improvement of agent skills

**Approach:**
- Ruthless critique - identify all issues without sugar-coating
- Clear priorities - MUST/SHOULD/NICE to have classification
- Concrete solutions - specific fixes, not just complaints
- User feedback loop - user decides what to fix
- Verify changes - ensure quality after refactoring

**Output:** Improved skill + change report in `.tasks/skill-refactoring-[date]/`

---

## Guidelines

### What Makes a Good Skill

Based on Agent Skills Complete Guide:
- **Description is king** - Most important field for skill triggering
- **Progressive disclosure** - SKILL.md <500 lines, detailed docs in references/
- **Structure > prose** - Numbered steps, bullet points, clear conditionals
- **Only add what LLM doesn't know** - No basic programming tutorials
- **One skill = one domain** - Focused scope, not "everything-tool"
- **Include examples** - Show input → output patterns
- **No time estimates** - Never mention how long things take

### Common Anti-Patterns to Look For

- ❌ **The Encyclopedia** - 5000+ line SKILL.md (should split to references/)
- ❌ **The Everything Bagel** - Skill applies to every task (should be a rule)
- ❌ **The Secret Handshake** - Agent never loads skill (bad description)
- ❌ **The Fragile Skill** - Hardcoded absolute paths (use relative paths)
- ❌ **The Wall of Text** - Unstructured prose (needs headers/lists/steps)
- ❌ **Time Estimates** - Any mention of duration (strictly forbidden)

### Priority Levels

**🔴 PRIORITY 1: MUST FIX** (breaking issues)
- Core guideline violations (time estimates, etc.)
- Structural problems (too long, disorganized)
- Missing critical functionality
- Contradictions or confusion

**🟡 PRIORITY 2: SHOULD FIX** (quality issues)
- Suboptimal workflow
- Redundant content
- Missing helpful features
- Can be simplified

**🟢 PRIORITY 3: NICE TO HAVE** (enhancements)
- Small improvements
- Additional examples
- Minor