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 referenc

...