skill-improver

name	skill-improver
description	This skill should be used when the user asks to "apply skill improvements", "update skill from plan", "execute improvement plan", "fix skill issues", "implement skill recommendations", or mentions applying improvements from quality review reports. Reads improvement-plan-{name}.md files generated by skill-quality-reviewer and intelligently merges and executes the suggested changes to improve Claude Skills quality.
version	1.0.0

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:

1. High priority takes precedence over medium/low
2. If same priority, preserve first change
3. Flag conflicts for manual review
4. 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:

1. High Priority (execute first)
2. Medium Priority (execute second)
3. 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:

1. YAML syntax valid
2. All modified files exist and are valid
3. New files were created successfully
4. 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

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

During Update Execution

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

After Applying Updates

1. Review the update report - Confirm all changes were intended
2. Test the skill - Verify it still works correctly
3. Compare scores - Check quality improvement matches expectations
4. 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