skill-improver

What this skill does

# Skill Improver

## Overview

This skill guides reflective improvement of skills and processes through structured analysis. Rather than automatically suggesting changes, it provides a framework for mindful reflection to identify high-impact improvements without creating bloat.

The philosophy follows Buddhist "skillful means" (upaya) - developing concrete, practical wisdom through iteration. The goal is harmonious operation between Claude and the user by refining skills to be clearer, more complete, and more efficient.

## When to Use This Skill

**Use this skill:**
- At the end of a session when significant work has been completed
- After completing a complex task that involved multiple skills or tools
- When experiencing repeated friction, confusion, or failures during execution
- When discovering a workaround or novel pattern that should be captured
- When the user expresses frustration with a process or skill
- After successfully navigating a challenging workflow that could be easier next time

**Do not use this skill:**
- After every tiny task (reflection should be purposeful, not reflexive)
- When there's nothing substantial to improve
- During active work (finish first, then reflect)

## Reflection Workflow

### 1. Identify the Context

Clearly establish what process or skill is being reflected upon:
- What was the original goal or request?
- Which skills were used?
- What tools and resources were involved?
- How did the process unfold?

### 2. Apply the Reflection Framework

Use `references/reflection_framework.md` to systematically analyze the experience. The framework provides structured questions across five dimensions:

1. **Process Execution** - What happened? What worked? What didn't?
2. **Skill Content Analysis** - Was the skill clear, complete, efficient, accurate?
3. **Tool and Resource Analysis** - Were the right tools available? Did they work well?
4. **Pattern Recognition** - Is this a one-time issue or recurring pattern?
5. **Improvement Identification** - What specific changes would help?

Load and review the framework:

```
Read references/reflection_framework.md and work through the relevant questions
```

### 3. Identify Improvement Patterns

Consult `references/improvement_patterns.md` to recognize common issues:
- Clarity issues (ambiguous descriptions, jargon, vague steps)
- Completeness issues (missing prerequisites, edge cases, error handling)
- Efficiency issues (redundant instructions, missing scripts, context bloat)
- Usability issues (poor discoverability, overwhelming complexity)
- Structural issues (wrong abstraction level, missing decision trees)

Load and cross-reference patterns:

```
Read references/improvement_patterns.md to identify which patterns match the observed issues
```

### 4. Formulate Specific Improvements

Based on reflection, create concrete, actionable improvement proposals. Each improvement should include:

- **Skill/Process**: Name of what's being improved
- **Issue Observed**: Concrete description of the problem
- **Root Cause**: Why this happened (what's missing or wrong)
- **Proposed Change**: Specific, actionable improvement
- **Impact**: High/Medium/Low priority
- **Implementation**: Exact files and changes needed

### 5. Apply Improvement Principles

Before finalizing recommendations, verify they follow skillful means:

**Do:**
- Be specific and concrete
- Show evidence from actual experience
- Consider cost/benefit ratio
- Prefer simplification over addition
- Document principles and "why", not just "what"

**Don't:**
- Pile on multiple vague changes
- Over-engineer solutions
- Duplicate existing information
- Spam the user with minor tweaks

### 6. Execute Improvements (if appropriate)

For high-impact improvements:
- If editing an existing skill, use the skill-creator skill to make changes
- If creating a new skill is warranted, use the skill-creator skill
- For process improvements, document the new approach

For lower-impact improvements:
- Present findings to the user for future consideration
- Ask if they'd like to implement changes now or later

## Decision Tree: Improve vs Create

Sometimes the best improvement is creating a new skill. Use this decision tree:

**Create a new skill when:**
- Distinct domain sufficiently different from existing skills
- Recurring multi-step workflow that happens repeatedly
- Requires unique scripts, templates, or reference documentation
- Clear trigger that distinguishes it from other skills

**Improve existing skill when:**
- Issue is with clarity, completeness, or organization
- Missing resources (scripts, references, assets) for existing workflow
- Same domain, just needs better documentation or tools
- Edge cases or error handling need addressing

**Do nothing when:**
- Issue was a one-time environmental problem
- Adding documentation would create bloat without value
- Change would over-engineer a simple process
- Proposed improvement won't actually be used

## Resources

This skill includes reference documentation to guide the reflection process:

### references/reflection_framework.md

Structured framework with questions across five dimensions:
1. Process Execution
2. Skill Content Analysis
3. Tool and Resource Analysis
4. Pattern Recognition
5. Improvement Identification

Use this to systematically analyze what happened and identify specific improvement opportunities.

### references/improvement_patterns.md

Catalog of common skill issues and their solutions:
- Clarity issues (ambiguous descriptions, jargon, vague workflows)
- Completeness issues (missing prerequisites, edge cases, error handling)
- Efficiency issues (redundancy, missing scripts, context bloat, missing templates)
- Usability issues (discoverability, complexity, inconsistent terminology)
- Structural issues (abstraction level, decision trees, undocumented scripts)

Use this to recognize patterns and find proven solutions.

## Example Usage

### Example 1: Missing Scripts

**Scenario**: After using the `pdf-editor` skill to rotate several PDFs, Claude had to rewrite rotation code multiple times due to varying file permissions.

**Reflection**:
1. **Context**: Used pdf-editor skill to rotate PDFs, encountered permission issues
2. **Framework application**: Process execution had friction - repetitive code writing, unexpected errors
3. **Pattern recognition**: Matches "Missing scripts for repetitive tasks" and "Incomplete error handling"
4. **Improvement formulation**:
   - **Skill/Process**: pdf-editor
   - **Issue**: Rewrote PyPDF2 rotation code 3 times; permission errors not handled
   - **Root Cause**: No rotation script; permission handling undocumented
   - **Proposed Change**: Create `scripts/rotate_pdf.py` with permission handling; add troubleshooting section
   - **Impact**: High - eliminates code rewriting, prevents permission errors
   - **Implementation**: Create script, update SKILL.md to reference it
5. **Execution**: Use skill-creator to add script and update documentation

### Example 2: Missing Reference Documentation

**Scenario**: After creating a Lorn/Clams Casino inspired beat using the `strudel` skill, user feedback revealed bass tone missed the mark. User corrected: "don't need to encode every iteration" and "bass tone not reminding me of references."

**Reflection**:
1. **Context**: Used strudel skill for dark ambient hip-hop, encountered two issues
2. **Framework application**:
   - Process execution: URL encoding was inefficient during iterations
   - Skill content: No guidance for translating artist references into techniques
3. **Pattern recognition**: Matches "Vague workflow steps" and "Missing reference documentation"
4. **Improvement formulation**:
   - **Skill/Process**: strudel
   - **Issue #1**: Encoded URL after every iteration; user said only needed on initial creation
   - **Root Cause**: Skill said "Always encode after modifications" - too broad
   - **Proposed Change**: Clarify when to encode (initial only, skip iterations, final if requ