skill-improvement

Use when optimizing existing Claude skills, checking skill quality, auditing skill compliance, or when skills have obvious issues. Triggers on skill optimiza...

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

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

---

Phase 2: Report

Present findings in structured format.

Report structure:

# 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

---

Phase 3: Select

User chooses which issues to fix.

Selection interface:

## Select Issues to Fix

### High Priority ⚠️
- [ ] 1. [Problem] - Impact: [brief statement]
- [ ] 2. [Problem] - Impact: [brief statement]

### Medium Priority ⚙️
- [ ] 3. [Problem] - Impact: [brief statement]

### Low Priority 💡
- [ ] 4. [Problem] - Impact: [brief statement]

**Quick Actions:**
- `Fix all high priority` - Auto-select HIGH issues
- `Fix selected` - Process checked items
- `Details [N]` - View detailed analysis

Interaction:

1. User reviews issues
2. User checks boxes or uses quick actions
3. System confirms selection
4. Proceed to execution

---

Phase 4: Execute

Apply selected fixes to skill files.

Execution rules:

1. Backup: Create .backup before changes
2. Order: Fix HIGH → MEDIUM → LOW
3. Show: Display diff for each modification
4. Update: Propagate changes to related files
5. Log: Record all changes

Fix application:

For each selected issue:
  1. Locate exact position
  2. Generate fix content
  3. Preview change (diff)
  4. Apply edit
  5. Log change
  6. Update related content if needed

Output: Modified skill files + change log

Quality standards: See quality-standards.md

---

Phase 5: Verify

Test optimization effectiveness with subagents.

Test types:

1. Trigger test: Skill discovered correctly
2. Understanding test: Workflow interpreted correctly
3. Execution test: Can perform real task
4. Regression test: Existing function still works

Process:

1. Define test scenarios
2. Dispatch subagents (parallel)
3. Analyze results
4. Generate verification report

If verification fails:

• Document failure
• Return to Phase 3 or 4
• Apply fixes
• Re-run verification
• Iterate until pass

Verification guide: See verification-guide.md

---

Quick Reference

Phase	Action	Output
1. Diagnose	Scan skill	Issue list
2. Report	Format findings	Diagnostic report
3. Select	User chooses	Selected issues
4. Execute	Apply fixes	Modified files
5. Verify	Test changes	Verification report

---

Problem Severity

Level	Definition	Action
HIGH	Prevents discovery/execution	Must fix
MEDIUM	Impacts quality/usability	Should fix
LOW	Minor improvement	Nice to fix

---

Quality Grading

• A (Excellent): All HIGH pass, < 2 MEDIUM fail
• B (Good): All HIGH pass, < 5 MEDIUM fail
• C (Acceptable): All HIGH pass
• D (Needs Work): Any HIGH fail
• F (Broken): Multiple HIGH fail

---

Common Issues

Metadata problems:

• Name format wrong → Use lowercase-hyphen
• Description missing "Use when" → Add trigger conditions
• No keywords → Add specific trigger terms

Architecture problems:

• SKILL.md too long → Split to references/
• Deep nesting → Flatten to 1 level
• No progressive disclosure → Add "See [file.md]" links

Text problems:

• Verbose explanations → Remove, assume Claude knows basics
• Time-sensitive info → Move to "Old Patterns" section
• Terminology inconsistent → Standardize terms

Code problems:

• No error handling → Add try/except with helpful messages
• Magic numbers → Add justification comments
• Undeclared dependencies → List in SKILL.md

---

Anti-Patterns

❌ Auto-fix all issues without user selection ❌ Skip verification phase ❌ Ignore context (domain-specific needs) ❌ Break existing functionality ❌ Over-engineer simple skills

---

Integration

Dependencies:

• superpowers:writing-skills - Skill authoring patterns
• superpowers:test-driven-development - Verification methodology

Coordinates with:

• skill-creator - Use quality standards when creating skills
• superpowers:verification-before-completion - Verify before deploying