skill-improver

What this skill does

# 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`.

```bash
# 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}/`

```bash
# 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

```bash
# 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
```