BZJZ_Material/文档润色流和知识库构建流/claude-scholar/skills/skill-improver/references/plan-format.md

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

# 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:

{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:

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

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

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

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

# 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:

---
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:

## Overview
You should use this skill to validate data files. You can choose from
JSON or XML formats.

Suggested:

## 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:

# 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:

## Usage
Use the skill when you need to validate files.

Suggested:

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