{"skill":{"slug":"skill-improvement","displayName":"skill-improvement","summary":"Use when optimizing existing Claude skills, checking skill quality, auditing skill compliance, or when skills have obvious issues. Triggers on skill optimiza...","description":"---\nname: skills-improvement\ndescription: Use when optimizing existing Claude skills, checking skill quality, auditing skill compliance, or when skills have obvious issues. Triggers on skill optimization requests, quality checks, or skill improvement tasks.\n---\n\n# Skills Improvement\n\n## Overview\n\nSystematically optimize skill quality through a diagnostic-report-select-execute-verify workflow. Ensure skills comply with Claude's official best practices for maximum effectiveness.\n\n**Core principle:** If you didn't diagnose a skill, you don't know what to fix.\n\n---\n\n## Workflow\n\n```dot\ndigraph workflow {\n    \"1. Diagnose\" [shape=box];\n    \"2. Report\" [shape=box];\n    \"3. Select\" [shape=box];\n    \"4. Execute\" [shape=box];\n    \"5. Verify\" [shape=box];\n    \n    \"1. Diagnose\" -> \"2. Report\";\n    \"2. Report\" -> \"3. Select\";\n    \"3. Select\" -> \"4. Execute\";\n    \"4. Execute\" -> \"5. Verify\";\n    \"5. Verify\" -> \"3. Select\" [label=\"fail\"];\n}\n```\n\n---\n\n## Phase 1: Diagnose\n\nScan skill for quality issues across 4 categories.\n\n**Categories:**\n- **Metadata** (HIGH): name, description, keywords\n- **Architecture** (MEDIUM): file structure, progressive disclosure\n- **Text** (MEDIUM): conciseness, clarity, token efficiency\n- **Code** (HIGH): error handling, dependencies, validation\n\n**Process:**\n1. Read SKILL.md and all referenced files\n2. Apply diagnostic checklist (see references/diagnostic-checklist.md)\n3. Record each issue with category, location, severity\n\n**Output:** Raw issue list\n\n**Detailed checklist:** See [diagnostic-checklist.md](references/diagnostic-checklist.md)\n\n---\n\n## Phase 2: Report\n\nPresent findings in structured format.\n\n**Report structure:**\n\n```markdown\n# Skill Diagnostic Report: [name]\n\n**Grade:** [A/B/C/D]\n**Issues:** X total (Y high, Z medium, W low)\n\n## High Priority (Y)\n[Issues that prevent discovery or execution]\n\n## Medium Priority (Z)\n[Issues that impact quality or usability]\n\n## Low Priority (W)\n[Minor improvements]\n```\n\n**For each issue include:**\n- Category and check ID\n- Current state vs expected state\n- Impact explanation\n- Specific fix recommendation\n- Reference to quality standard\n\n**Report templates:** See [report-templates.md](references/report-templates.md)\n\n---\n\n## Phase 3: Select\n\nUser chooses which issues to fix.\n\n**Selection interface:**\n\n```markdown\n## Select Issues to Fix\n\n### High Priority ⚠️\n- [ ] 1. [Problem] - Impact: [brief statement]\n- [ ] 2. [Problem] - Impact: [brief statement]\n\n### Medium Priority ⚙️\n- [ ] 3. [Problem] - Impact: [brief statement]\n\n### Low Priority 💡\n- [ ] 4. [Problem] - Impact: [brief statement]\n\n**Quick Actions:**\n- `Fix all high priority` - Auto-select HIGH issues\n- `Fix selected` - Process checked items\n- `Details [N]` - View detailed analysis\n```\n\n**Interaction:**\n1. User reviews issues\n2. User checks boxes or uses quick actions\n3. System confirms selection\n4. Proceed to execution\n\n---\n\n## Phase 4: Execute\n\nApply selected fixes to skill files.\n\n**Execution rules:**\n1. **Backup:** Create `.backup` before changes\n2. **Order:** Fix HIGH → MEDIUM → LOW\n3. **Show:** Display diff for each modification\n4. **Update:** Propagate changes to related files\n5. **Log:** Record all changes\n\n**Fix application:**\n```\nFor each selected issue:\n  1. Locate exact position\n  2. Generate fix content\n  3. Preview change (diff)\n  4. Apply edit\n  5. Log change\n  6. Update related content if needed\n```\n\n**Output:** Modified skill files + change log\n\n**Quality standards:** See [quality-standards.md](references/quality-standards.md)\n\n---\n\n## Phase 5: Verify\n\nTest optimization effectiveness with subagents.\n\n**Test types:**\n1. **Trigger test:** Skill discovered correctly\n2. **Understanding test:** Workflow interpreted correctly\n3. **Execution test:** Can perform real task\n4. **Regression test:** Existing function still works\n\n**Process:**\n1. Define test scenarios\n2. Dispatch subagents (parallel)\n3. Analyze results\n4. Generate verification report\n\n**If verification fails:**\n- Document failure\n- Return to Phase 3 or 4\n- Apply fixes\n- Re-run verification\n- Iterate until pass\n\n**Verification guide:** See [verification-guide.md](references/verification-guide.md)\n\n---\n\n## Quick Reference\n\n| Phase | Action | Output |\n|-------|--------|--------|\n| 1. Diagnose | Scan skill | Issue list |\n| 2. Report | Format findings | Diagnostic report |\n| 3. Select | User chooses | Selected issues |\n| 4. Execute | Apply fixes | Modified files |\n| 5. Verify | Test changes | Verification report |\n\n---\n\n## Problem Severity\n\n| Level | Definition | Action |\n|-------|------------|--------|\n| **HIGH** | Prevents discovery/execution | Must fix |\n| **MEDIUM** | Impacts quality/usability | Should fix |\n| **LOW** | Minor improvement | Nice to fix |\n\n---\n\n## Quality Grading\n\n- **A (Excellent):** All HIGH pass, < 2 MEDIUM fail\n- **B (Good):** All HIGH pass, < 5 MEDIUM fail\n- **C (Acceptable):** All HIGH pass\n- **D (Needs Work):** Any HIGH fail\n- **F (Broken):** Multiple HIGH fail\n\n---\n\n## Common Issues\n\n**Metadata problems:**\n- Name format wrong → Use lowercase-hyphen\n- Description missing \"Use when\" → Add trigger conditions\n- No keywords → Add specific trigger terms\n\n**Architecture problems:**\n- SKILL.md too long → Split to references/\n- Deep nesting → Flatten to 1 level\n- No progressive disclosure → Add \"See [file.md]\" links\n\n**Text problems:**\n- Verbose explanations → Remove, assume Claude knows basics\n- Time-sensitive info → Move to \"Old Patterns\" section\n- Terminology inconsistent → Standardize terms\n\n**Code problems:**\n- No error handling → Add try/except with helpful messages\n- Magic numbers → Add justification comments\n- Undeclared dependencies → List in SKILL.md\n\n---\n\n## Anti-Patterns\n\n❌ Auto-fix all issues without user selection\n❌ Skip verification phase\n❌ Ignore context (domain-specific needs)\n❌ Break existing functionality\n❌ Over-engineer simple skills\n\n---\n\n## Integration\n\n**Dependencies:**\n- `superpowers:writing-skills` - Skill authoring patterns\n- `superpowers:test-driven-development` - Verification methodology\n\n**Coordinates with:**\n- `skill-creator` - Use quality standards when creating skills\n- `superpowers:verification-before-completion` - Verify before deploying","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":659,"installsAllTime":4,"installsCurrent":3,"stars":0,"versions":1},"createdAt":1772805799783,"updatedAt":1778491751707},"latestVersion":{"version":"1.0.0","createdAt":1772805799783,"changelog":"- Initial release of the skills-improvement framework for optimizing Claude skills.\n- Introduces a step-by-step workflow for diagnosis, reporting, selection, execution, and verification of skill quality issues.\n- Defines clear severity levels, grading criteria, and common issues to guide systematic improvements.\n- Provides templates and checklists for audits and compliance with best practices.\n- Integrates with related authoring and verification skills for streamlined optimization.","license":null},"metadata":null,"owner":{"handle":"acautomata","userId":"s1713ked8kbe8evjbaxthw3msx83hs61","displayName":"Joel Young","image":"https://avatars.githubusercontent.com/u/54613293?v=4"},"moderation":null}