skills-improvement

# Skills Improvement

## Overview

Systematically optimize skill quality through a diagnostic-report-select-execute-verify workflow. Ensure skills comply with Claude's official best practices for maximum effectiveness.

**Core principle:** If you didn't diagnose a skill, you don't know what to fix.

---

## Workflow

```dot
digraph workflow {
    "1. Diagnose" [shape=box];
    "2. Report" [shape=box];
    "3. Select" [shape=box];
    "4. Execute" [shape=box];
    "5. Verify" [shape=box];
    
    "1. Diagnose" -> "2. Report";
    "2. Report" -> "3. Select";
    "3. Select" -> "4. Execute";
    "4. Execute" -> "5. Verify";
    "5. Verify" -> "3. Select" [label="fail"];
}
```

---

## Phase 1: Diagnose

Scan skill for quality issues across 4 categories.

**Categories:**
- **Metadata** (HIGH): name, description, keywords
- **Architecture** (MEDIUM): file structure, progressive disclosure
- **Text** (MEDIUM): conciseness, clarity, token efficiency
- **Code** (HIGH): error handling, dependencies, validation

**Process:**
1. Read SKILL.md and all referenced files
2. Apply diagnostic checklist (see references/diagnostic-checklist.md)
3. Record each issue with category, location, severity

**Output:** Raw issue list

**Detailed checklist:** See [diagnostic-checklist.md](references/diagnostic-checklist.md)

---

## Phase 2: Report

Present findings in structured format.

**Report structure:**

```markdown
# Skill Diagnostic Report: [name]

**Grade:** [A/B/C/D]
**Issues:** X total (Y high, Z medium, W low)

## High Priority (Y)
[Issues that prevent discovery or execution]

## Medium Priority (Z)
[Issues that impact quality or usability]

## Low Priority (W)
[Minor improvements]
```

**For each issue include:**
- Category and check ID
- Current state vs expected state
- Impact explanation
- Specific fix recommendation
- Reference to quality standard

**Report templates:** See [report-templates.md](references/report-templates.md)

---

## Phase 3: Select

User chooses which iss...