Skill Improver

Execute improvement plans generated by skill-quality-reviewer to automatically update and fix issues in Claude Skills.

Core Workflow

Read improvement-plan-{name}.md
    ↓
Parse improvement items (High/Medium/Low priority)
    ↓
Group changes by file
    ↓
Detect and resolve conflicts
    ↓
Backup original files
    ↓
Execute updates (Edit or Write tools)
    ↓
Verify results
    ↓
Generate update-report

When to Use

Trigger phrases:

"Apply improvements from improvement-plan-git-workflow.md"
"Update my skill based on the quality report"
"Execute the improvement plan for api-helper"
"Fix the issues identified in quality review"

Use this skill when:

Applying improvements from an improvement plan
Updating a skill based on quality review feedback
Executing recommended fixes from skill-quality-reviewer
Implementing structured improvements to skill documentation

Step-by-Step Guide

Step 1: Load the Improvement Plan

Read the improvement-plan-{skill-name}.md file generated by skill-quality-reviewer.

# Plan is typically in current directory
ls improvement-plan-*.md

# Or specify full path
read /path/to/improvement-plan-my-skill.md

Validate the plan:

File exists and is readable
Contains priority sections (High/Medium/Low)
Has structured improvement items
Includes file paths and suggested changes

See references/plan-format.md for detailed plan structure.

Step 2: Parse and Group Changes

Extract all improvement suggestions and organize by target file.

Extract from each item:

File path (e.g., SKILL.md:line:line or references/file.md)
Dimension (Description Quality, Content Organization, etc.)
Impact (+X points)
Current content
Suggested content
Reason for change

Build update queue:

by_file = {
  "SKILL.md": [change1, change2, ...],
  "references/guide.md": [change3, ...],
  "examples/demo.md": [change4, ...],
}

Step 3: Detect and Resolve Conflicts

Check for conflicts when multiple changes affect the same content.

Resolution strategy:

High priority takes precedence over medium/low
If same priority, preserve first change
Flag conflicts for manual review
Document resolution in update report

See references/merge-strategies.md for detailed merge logic.

Step 4: Sort by Priority

Order changes by priority within each file.

Priority order:

High Priority (execute first)
Medium Priority (execute second)
Low Priority (execute last)

Step 5: Backup and Execute

Backup location: ~/.claude/skills/backup/{skill-name}-{timestamp}/

# Use backup script
~/.claude/skills/skill-improver/scripts/backup-skill.sh <skill-path>

Apply changes:

Use Edit tool for existing content
Use Write tool for new files
Verify each change was applied

Step 6: Verify and Report

Verification checks:

YAML syntax valid
All modified files exist and are valid
New files were created successfully
No unintended changes occurred

# Use verify script
~/.claude/skills/skill-improver/scripts/verify-update.sh <skill-path>

Generate update-report-{skill-name}-{timestamp}.md documenting:

Summary (files modified, files created, total changes)
Changes Applied (per-file breakdown)
Quality Improvement (before/after scores)
Verification Results
Backup Location

See examples/update-report-example.md for report template.

Priority Handling

High Priority

Execute first. These typically address:

Critical description issues
Major writing style problems
Missing structural elements
Security-related concerns

Medium Priority

Execute after High. These typically address:

Content organization improvements
Additional examples
Documentation enhancements

Low Priority

Execute last. These typically address:

Minor clarifications
Nice-to-have improvements
Polish and refinement

Integration with Skill Quality Reviewer

This skill works seamlessly with skill-quality-reviewer:

Current Skill (67/100 D+)
    ↓ [skill-quality-reviewer]
Improvement Plan
    ↓ [skill-improver]
Improved Skill (87/100 B+)
    ↓ [skill-quality-reviewer]
Quality Report (validation)

Iterate until desired quality level reached.

Additional Resources

Reference Files

references/plan-format.md - Improvement plan file structure and format
references/merge-strategies.md - Detailed merge algorithms and conflict resolution
references/error-handling.md - Error handling strategies
references/supported-updates.md - Supported update types with examples

Example Files

examples/improvement-plan-example.md - Sample improvement plan
examples/update-report-example.md - Sample update report

Scripts

scripts/backup-skill.sh - Create backup of skill before updates
scripts/verify-update.sh - Verify skill integrity after updates

Best Practices

Before Applying Updates

Review the improvement plan - Understand what will change
Verify backup location - Ensure backups can be restored
Check for manual changes - Note any uncommitted local modifications
Estimate impact - Review expected quality improvement

During Update Execution

Process in priority order - High → Medium → Low
Verify after each file - Check updates were applied correctly
Log all changes - Document what was modified
Handle conflicts gracefully - Flag for review if needed

After Applying Updates

Review the update report - Confirm all changes were intended
Test the skill - Verify it still works correctly
Compare scores - Check quality improvement matches expectations
Keep backup - Retain backup until confident in changes

Usage Examples

Example 1: Apply improvements to local skill

User: "Apply improvements from improvement-plan-git-workflow.md"

[Claude executes the workflow:]
1. Reads improvement-plan-git-workflow.md
2. Parses all improvement items
3. Groups changes by file
4. Detects and resolves conflicts
5. Sorts by priority
6. Backs up git-workflow skill
7. Executes updates
8. Verifies results
9. Generates update-report-git-workflow-timestamp.md

Example 2: Update skill from quality review

User: "Update my api-helper skill based on quality report"

[Claude:]
1. Locates improvement-plan-api-helper.md
2. Applies all recommended changes
3. Verifies skill structure
4. Reports quality improvement: 72/100 → 91/100