Skill Improver

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 requested)
• Impact: Medium - prevents unnecessary work
• Implementation: Update SKILL.md section "Providing Output to the User"

• Issue #2: No systematic guide for artist characteristics (Lorn, Clams Casino)
• Root Cause: No reference for common genre/artist styles
• Proposed Change: Create references/genre-styles.md with artist characteristics and Strudel techniques
• Impact: High - translates user references into concrete implementation
• Implementation: Create reference file, update SKILL.md to reference it

5. Execution: Used skill-creator to implement both improvements; user approved both

Philosophy: Skillful Means

The goal is harmonious operation through continuous refinement:

• Concrete over abstract: Prefer working examples to theoretical descriptions
• Simplicity over completeness: Handle 80% of cases well rather than 100% poorly
• Clarity over cleverness: Straightforward instructions beat elegant complexity
• Practical over perfect: Ship useful improvements, iterate continuously
• Harmonious over comprehensive: Reduce friction, don't add features

Each improvement should make Claude's and the user's life tangibly easier. If it doesn't pass this test, don't recommend it.

Common Skill Improvement Patterns

This document catalogs recurring patterns of issues found in skills and processes, along with their solutions.

Pattern Categories

1. Clarity Issues

Ambiguous tool descriptions

• Symptom: Claude hesitates or asks clarifying questions about when/how to use a tool
• Solution: Add concrete trigger examples, decision trees, or "when to use vs when not to use" sections
• Example fix: Instead of "Use for data processing", write "Use when converting CSV to JSON, filtering datasets, or aggregating metrics"

Jargon without context

• Symptom: User or Claude confused by domain-specific terms
• Solution: Add a glossary or inline definitions for specialized terminology
• Example fix: First mention of "DAG" becomes "DAG (Directed Acyclic Graph)"

Vague workflow steps

• Symptom: Claude implements steps incorrectly or asks for clarification
• Solution: Make steps concrete and specific with clear inputs/outputs
• Example fix: Instead of "Process the data", write "Use ast-grep to extract all function definitions and write them to functions.json"

2. Completeness Issues

Missing prerequisites

• Symptom: Workflow fails because required tools, files, or setup wasn't checked
• Solution: Add prerequisite verification step at workflow beginning
• Example fix: Add "Before starting: verify pdflatex is installed with which pdflatex"

Undocumented edge cases

• Symptom: Workflow succeeds in common cases but fails in edge scenarios
• Solution: Document known edge cases and how to handle them
• Example fix: Add section "Handling Large Files (>100MB)" with chunking strategy

Incomplete error handling

• Symptom: When errors occur, Claude doesn't know how to recover
• Solution: Add troubleshooting section or error recovery procedures
• Example fix: "If API returns 429: wait 60 seconds and retry up to 3 times"

3. Efficiency Issues

Redundant instructions

• Symptom: Same information appears in multiple places, causing confusion
• Solution: Consolidate to single source of truth, use references for details
• Example fix: Move detailed API schema from SKILL.md to references/api_schema.md

Missing scripts for repetitive tasks

• Symptom: Claude rewrites the same code pattern multiple times
• Solution: Extract to a script in scripts/ directory
• Example fix: PDF rotation code → scripts/rotate_pdf.py

Context bloat

• Symptom: Skill loads too much information into context unnecessarily
• Solution: Move verbose content to references/ or assets/, load only when needed
• Example fix: Move 5000-line schema doc from SKILL.md to references/schema.md

Missing templates

• Symptom: Claude recreates boilerplate from scratch each time
• Solution: Add template to assets/ directory
• Example fix: HTML starter → assets/html-template/index.html

4. Usability Issues

Poor discoverability

• Symptom: User doesn't know skill exists or when to invoke it
• Solution: Improve skill description to be more specific about triggers
• Example fix: Change description from "Helps with data" to "This skill should be used when working with BigQuery databases, writing SQL queries, or analyzing query performance"

Overwhelming complexity

• Symptom: Skill tries to do too much, confuses rather than helps
• Solution: Split into multiple focused skills or simplify scope
• Example fix: Split "web-development" into "frontend-builder" and "api-builder"

Inconsistent terminology

• Symptom: Same concept called different names throughout skill
• Solution: Standardize terminology, add glossary if needed
• Example fix: Consistently use "endpoint" instead of mixing "endpoint", "route", "API path"

5. Structural Issues

Wrong abstraction level

• Symptom: Skill either too general (unhelpful) or too specific (inflexible)
• Solution: Aim for the "Goldilocks zone" - general patterns with concrete examples
• Example fix: Don't document every git command; document the workflow patterns

Missing decision trees

• Symptom: Claude unsure which path to take when multiple options exist
• Solution: Add explicit decision flowchart or conditional logic
• Example fix: "If file is .pdf → use pdf-editor skill, if .docx → use docx skill"

Undocumented scripts

• Symptom: Scripts exist but Claude doesn't know when/how to use them
• Solution: Reference scripts explicitly in SKILL.md with usage examples
• Example fix: Add "To rotate PDFs, use scripts/rotate_pdf.py --input file.pdf --degrees 90"

Meta-Pattern: Skillful Means

The Buddhist concept of upaya (skillful means) applies to skill development:

• Concrete over abstract: Prefer working examples to theoretical descriptions
• Simplicity over completeness: Better to handle 80% of cases well than 100% poorly
• Clarity over cleverness: Straightforward instructions beat elegant complexity
• Practical over perfect: Ship useful skills, improve iteratively
• Harmonious over comprehensive: Reduce friction, don't add features

When to Create a New Skill

Sometimes improvement means recognizing a new skill is needed:

• Distinct domain: Topic is sufficiently different from existing skills
• Recurring workflow: Same multi-step process happens repeatedly
• Specialized tools: Requires unique scripts, templates, or references
• Clear trigger: Obvious when this skill should activate vs others

Anti-pattern: Creating micro-skills for single operations that could be simple instructions.

Reflection Framework for Skill Improvement

This framework provides structured questions to guide thoughtful reflection after using a skill or completing a process.

When to Reflect

Reflection is most valuable:

• At natural checkpoints (feature complete, bug resolved, task finished)
• After experiencing friction or confusion
• When a skill was just used and the experience is fresh
• After discovering a workaround or novel pattern
• When the user expresses frustration

Not after every tiny task - reflection should be purposeful, not reflexive.

Reflection Questions

Work through these questions systematically. Not all will apply to every situation.

1. Process Execution

What was attempted?

• What was the original goal or request?
• Which skills or processes were involved?
• What tools were used?

How did it go?

• Did the process complete successfully?
• Were there blockers, errors, or unexpected issues?
• What workarounds were needed?

What felt smooth?

• Which parts of the workflow felt natural and efficient?
• What aspects of the skill helped most?
• Where did the instructions match reality well?

What felt rough?

• Where did confusion arise (for Claude or user)?
• What required trial-and-error that shouldn't have?
• What took longer than expected?

2. Skill Content Analysis

Clarity

• Were instructions clear and actionable?
• Was any terminology confusing or undefined?
• Were there ambiguous decision points?
• Did examples help or confuse?

Completeness

• Was any necessary information missing?
• Were edge cases handled?
• Were error recovery procedures documented?
• Were prerequisites clearly stated?

Efficiency

• Was there redundant information?
• Could repetitive tasks be scripted?
• Should any content move to references/ or assets/?
• Is context being used efficiently?

Accuracy

• Were any instructions outdated or incorrect?
• Did APIs or tools behave differently than documented?
• Were file paths or commands wrong?

3. Tool and Resource Analysis

Missing tools

• Was there a script that should exist but doesn't?
• Would a template have helped?
• Should reference documentation be added?

Wrong tools

• Were existing scripts insufficient or buggy?
• Are templates outdated or not fit for purpose?
• Is reference documentation incomplete or wrong?

Tool usage friction

• Were tools difficult to discover?
• Were usage instructions unclear?
• Did tools require patching or modification?

4. Pattern Recognition

Recurring problems

• Is this the first time this issue appeared, or recurring?
• Have similar issues occurred in other skills?
• Is there a systemic problem to address?

Novel solutions

• Was a new technique or approach discovered?
• Should this become standard practice?
• Would other skills benefit from this learning?

User preferences

• Did the user express preferences about how to work?
• Are there patterns in what frustrates or pleases them?
• Should preferences be documented for future sessions?

5. Improvement Identification

What should change?

• Specific wording clarifications needed
• Missing sections to add
• Incorrect information to fix
• Resources to create or update
• Entire sections to restructure

Priority assessment

• High impact: Fixes blockers, prevents errors, eliminates major friction
• Medium impact: Improves clarity, adds helpful references, smooths workflow
• Low impact: Minor wording tweaks, aesthetic improvements

Scope assessment

• Quick fixes: Simple edits to SKILL.md
• Medium effort: Creating new scripts or reference docs
• Major work: Restructuring skill, splitting into multiple skills

Improvement Principles

Do

• Be specific: "Add error handling for 404 responses" not "improve error handling"
• Show evidence: Reference concrete moments of confusion or failure
• Consider cost/benefit: Will this improvement actually help future usage?
• Think iteratively: Small improvements compound over time
• Document principles: Capture the "why" behind practices, not just "what"

Don't

• Don't pile on changes: One focused improvement is better than five vague ones
• Don't over-engineer: Resist adding complexity that won't be used
• Don't duplicate: If information exists elsewhere, reference it instead
• Don't assume: Validate that the improvement actually solves the problem
• Don't spam: Not every session needs recommendations

Output Format

When suggesting improvements, structure them clearly:

Skill/Process: [Name of skill or process being improved]

Issue Observed: [Concrete description of what went wrong or could be better]

Root Cause: [Why this happened - what's missing or wrong in current skill]

Proposed Change: [Specific, actionable improvement]

Impact: [High/Medium/Low - what this fixes or improves]

Implementation: [What files to change, what to add/remove/modify]

---

Example:

Skill/Process: pdf-editor

Issue Observed: When rotating PDFs, Claude had to rewrite the PyPDF2 rotation code three times because file permissions varied

Root Cause: No script exists for PDF rotation; file permission handling not documented

Proposed Change: 1. Create scripts/rotate_pdf.py with permission handling 2. Add "Troubleshooting: Permission Issues" section to SKILL.md

Impact: High - eliminates code rewriting, prevents permission errors

Implementation:

• Create /scripts/rotate_pdf.py with proper error handling
• Add troubleshooting section after "Rotating PDFs" in SKILL.md
• Reference script in workflow: "Use scripts/rotate_pdf.py --input file.pdf --degrees 90"