brycewang-stanford/skill-improver

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