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

Problem Severity

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