Skip to content

brycewang-stanford/Auto-Empirical-Research-Skills / skills/33-Galaxy-Dawn-claude-scholar/skills/skill-improver

skill-improver

Verified

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.

references/plan-format.md

View on GitHub
# Improvement Plan Format

Detailed specification of the `improvement-plan-{skill-name}.md` file format generated by `skill-quality-reviewer` and consumed by `skill-improver`.

## File Structure

```markdown
# Skill Improvement Plan: {skill-name}

## Priority Summary
- **High Priority**: {count} items
- **Medium Priority**: {count} items
- **Low Priority**: {count} items

## High Priority Improvements

### 1. [Issue Title]
**File**: SKILL.md:line:line
**Dimension**: {Dimension Name}
**Impact**: +X points

**Current**:
```yaml or markdown
{current content}
```

**Suggested**:
```yaml or markdown
{suggested content}
```

**Reason**: {why this improves quality}

[Repeat for all high priority items...]

## Medium Priority Improvements
[Same format as High Priority...]

## Low Priority Improvements
[Same format as High Priority...]

## Quick Wins (Easy Fixes)
1. {quick fix description}
2. {quick fix description}

## Estimated Time to Complete
- High Priority: X hours
- Medium Priority: X hours
- Low Priority: X hours
- **Total**: X hours

## Expected Score Improvement
- Current: X/100 ({Grade})
- After High Priority: X/100 ({Grade})
- After All: X/100 ({Grade})
```

## Parsing Rules

### Priority Section Detection

**Identify sections by heading:**
```markdown
## High Priority Improvements
## Medium Priority Improvements
## Low Priority Improvements
```

**Case insensitive but exact match preferred:**
- "High Priority Improvements" ✓
- "high priority improvements" ✓ (acceptable)
- "High Priority" ✗ (incomplete)

### Item Extraction

**Each improvement item starts with:**
```markdown
### N. [Issue Title]
```

Where N is a sequential number (1, 2, 3, ...)

**Required fields within each item:**

1. **File** (required)
   ```
   **File**: SKILL.md:line:line
   **File**: references/filename.md
   **File**: examples/filename.md
   ```
   - Format: `filepath:line:line` or just `filepath`
   - Line numbers are specific for edits
   - File only indicates new file creation or append

2. **Dimension** (required)
   ```
   **Dimension**: Description Quality
   **Dimension**: Content Organization
   **Dimension**: Writing Style
   **Dimension**: Structural Integrity
   ```

3. **Impact** (required)
   ```
   **Impact**: +X points
   ```
   - Points indicate expected score improvement
   - Used for calculating expected final score

4. **Current** (required for edits)
   ```
   **Current**:
   ```yaml or markdown
   {exact current content}
   ```
   - Must match exactly for Edit operations
   - Code fence specifies format (yaml, markdown, etc.)

5. **Suggested** (required)
   ```
   **Suggested**:
   ```yaml or markdown
   {suggested replacement content}
   ```
   - Content to replace current or create

6. **Reason** (optional but recommended)
   ```
   **Reason**: {explanation}
   ```
   - Human-readable explanation
   - Included in update report

### Code Fence Formats

**Supported formats:**
```yaml
```yaml
---
name: skill-name
---
```
```

```markdown
```markdown
## Section Header

Content here...
```
```

```bash
```bash
#!/bin/bash
echo "script"
```
```

**Format determines:**
- Syntax highlighting
- Validation rules
- Parser expectations

## File Path Patterns

### SKILL.md References

**With line numbers:**
```
**File**: SKILL.md:5:10
```
- Lines 5-10 will be replaced
- Used for Edit operations

**Without line numbers:**
```
**File**: SKILL.md
```
- Typically indicates new file or append

### References/ Files

**Specific file:**
```
**File**: references/api-guide.md
**File**: references/examples-bad.md
```

**With line numbers:**
```
**File**: references/patterns.md:50:100
```

### Examples/ Files

**New file creation:**
```
**File**: examples/demo.md
```
- No line numbers
- Suggested content becomes entire file

**Modification:**
```
**File**: examples/basic-usage.sh:20:30
```

### Scripts/ Files

**Script updates:**
```
**File**: scripts/validate.sh:15:25
```

## Parsing Pseudocode

```python
def parse_improvement_plan(plan_path):
    """Parse improvement plan file into structured data."""

    plan = read_file(plan_path)
    sections = {
        'high': [],
        'medium': [],
        'low': []
    }

    current_section = None
    current_item = None

    for line in plan.split('\n'):
        # Detect section headers
        if line.startswith('## High Priority'):
            current_section = 'high'
        elif line.startswith('## Medium Priority'):
            current_section = 'medium'
        elif line.startswith('## Low Priority'):
            current_section = 'low'

        # Detect item start
        elif line.startswith('### '):
            if current_item:
                sections[current_section].append(current_item)
            current_item = {'title': line[4:].strip()}

        # Parse fields within item
        elif current_item:
            if line.startswith('**File**'):
                current_item['file'] = parse_file_path(line)
            elif line.startswith('**Dimension**'):
                current_item['dimension'] = line.split(':', 1)[1].strip()
            elif line.startswith('**Impact**'):
                current_item['impact'] = parse_impact(line)
            elif line.startswith('**Current**'):
                current_item['current'] = extract_code_fence(plan, line)
            elif line.startswith('**Suggested**'):
                current_item['suggested'] = extract_code_fence(plan, line)
            elif line.startswith('**Reason**'):
                current_item['reason'] = line.split(':', 1)[1].strip()

    # Add last item
    if current_item:
        sections[current_section].append(current_item)

    return sections
```

## Line Number Handling

### Single Line

```
**File**: SKILL.md:10:10
```
- Only line 10 is replaced

### Line Range

```
**File**: SKILL.md:10:15
```
- Lines 10-15 are replaced
- Current content should span these lines

### No Line Numbers

```
**File**: references/new-file.md
```
- New file creation
- Or append to existing file

### Line Number Extraction

```python
def parse_file_path(line):
    """Extract file path and line numbers from File field."""

    # Remove "**File**:" prefix
    value = line.split(':', 1)[1].strip()

    # Check for line numbers
    if ':' in value:
        parts = value.split(':')
        file_path = ':'.join(parts[:-2])
        start_line = int(parts[-2])
        end_line = int(parts[-1])
        return {
            'path': file_path,
            'start': start_line,
            'end': end_line
        }
    else:
        return {
            'path': value,
            'start': None,
            'end': None
        }
```

## Impact Extraction

```python
def parse_impact(line):
    """Extract impact value from Impact field."""

    # Format: **Impact**: +X points
    value = line.split(':', 1)[1].strip()
    # Extract number
    import re
    match = re.search(r'\+(\d+)', value)
    if match:
        return int(match.group(1))
    return 0
```

## Code Fence Extraction

```python
def extract_code_fence(content, start_line):
    """Extract code block starting after current line."""

    lines = content.split('\n')
    start_idx = lines.index(start_line)

    # Find opening fence
    for i in range(start_idx, len(lines)):
        if lines[i].strip().startswith('```'):
            fence_start = i
            lang = lines[i].strip()[3:]
            break

    # Find closing fence
    for i in range(fence_start + 1, len(lines)):
        if lines[i].strip() == '```':
            fence_end = i
            break

    # Extract content
    code_lines = lines[fence_start + 1:fence_end]
    return '\n'.join(code_lines)
```

## Validation Rules

### Required Sections

- [ ] High Priority Improvements (may be empty)
- [ ] Medium Priority Improvements (may be empty)
- [ ] Low Priority Improvements (may be empty)

### Required Item Fields

For each improvement item:
- [ ] **File** field present
- [ ] **Dimension** field present
- [ ] **Impact** field present
- [ ] **Current** field present (for edits)
- [ ] **Suggested** field present

### File Path Validity

- [ ] File path is valid format
- [ ] Line numbers are integers (if present)
- [ ] File extension matches content type

### Code Fence Validity

- [ ] Opening fence present
- [ ] Closing fence present
- [ ] Language identifier valid
- [ ] Content non-empty (for suggested)

## Example Improvement Plan

```markdown
# Skill Improvement Plan: example-skill

## Priority Summary
- **High Priority**: 2 items
- **Medium Priority**: 1 item
- **Low Priority**: 1 item

## High Priority Improvements

### 1. Fix Description Trigger Phrases
**File**: SKILL.md:3:5
**Dimension**: Description Quality
**Impact**: +20 points

**Current**:
```yaml
---
name: example-skill
description: Use this for helpful tasks.
---
```

**Suggested**:
```yaml
---
name: example-skill
description: This skill should be used when the user asks to "validate data",
"check schemas", or "verify formats". Perform data validation and schema
checking for JSON and YAML files.
---
```

**Reason**: Add specific trigger phrases and use third-person format.

### 2. Fix Writing Style
**File**: SKILL.md:25:30
**Dimension**: Writing Style
**Impact**: +15 points

**Current**:
```markdown
## Overview
You should use this skill to validate data files. You can choose from
JSON or XML formats.
```

**Suggested**:
```markdown
## Overview
Validate data files in JSON or XML formats with configurable schemas.
```

**Reason**: Change to imperative form, remove second person.

## Medium Priority Improvements

### 1. Add Reference Documentation
**File**: references/validation-rules.md
**Dimension**: Content Organization
**Impact**: +10 points

**Suggested**:
```markdown
# Validation Rules

## JSON Schema Rules
- Required fields validation
- Type checking
- Format validation

## YAML Schema Rules
- Structure validation
- Type coercion rules
```

**Reason**: Move detailed rules to references for progressive disclosure.

## Low Priority Improvements

### 1. Clarify Description
**File**: SKILL.md:50:52
**Dimension**: Writing Style
**Impact**: +5 points

**Current**:
```markdown
## Usage
Use the skill when you need to validate files.
```

**Suggested**:
```markdown
## Usage
Invoke skill for file validation tasks.
```

**Reason**: Use imperative form for consistency.

## Quick Wins (Easy Fixes)
1. Add space after comma in description (+2 points)
2. Fix indentation in examples section (+3 points)

## Estimated Time to Complete
- High Priority: 0.5 hours
- Medium Priority: 0.5 hours
- Low Priority: 0.25 hours
- **Total**: 1.25 hours

## Expected Score Improvement
- Current: 65/100 (D)
- After High Priority: 82/100 (B-)
- After All: 88/100 (B+)
```

## Integration Notes

**Generated by:** `skill-quality-reviewer`
**Consumed by:** `skill-improver`

**Format version:** 1.0
**Compatibility:** Must maintain backward compatibility
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall