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

CODEBLOCK0

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. 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:

CODEBLOCK1

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:

CODEBLOCK2

Interaction:

1. 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. 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:
CODEBLOCK3

Output: Modified skill files + change log

Quality standards: See quality-standards.md

Phase 5: Verify

Test optimization effectiveness with subagents.

Test types:

1. 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. 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
• INLINECODE2 - Verification methodology

Coordinates with:

• - skill-creator - Use quality standards when creating skills
• INLINECODE4 - Verify before deploying