first commit
This commit is contained in:
251
文档润色流和知识库构建流/claude-scholar/skills/skill-improver/SKILL.md
Normal file
251
文档润色流和知识库构建流/claude-scholar/skills/skill-improver/SKILL.md
Normal file
@@ -0,0 +1,251 @@
|
||||
---
|
||||
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`.
|
||||
|
||||
```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
|
||||
```
|
||||
@@ -0,0 +1,85 @@
|
||||
# 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:4
|
||||
**Dimension**: Description Quality
|
||||
**Impact**: +20 points
|
||||
|
||||
**Current**:
|
||||
```yaml
|
||||
---
|
||||
name: example-skill
|
||||
description: A helpful skill for various tasks
|
||||
---
|
||||
```
|
||||
|
||||
**Suggested**:
|
||||
```yaml
|
||||
---
|
||||
name: api-contract-manager
|
||||
description: This skill should be used when the user asks to "validate API contract", "check API compatibility", or "detect breaking changes"
|
||||
---
|
||||
```
|
||||
|
||||
**Reason**: The current description lacks specific trigger phrases and uses first-person format. The suggested version follows third-person format with clear trigger phrases.
|
||||
|
||||
### 2. Convert to Imperative Form
|
||||
**File**: SKILL.md:50:55
|
||||
**Dimension**: Writing Style
|
||||
**Impact**: +15 points
|
||||
|
||||
**Current**:
|
||||
```markdown
|
||||
You should create the file first.
|
||||
You need to validate the input.
|
||||
```
|
||||
|
||||
**Suggested**:
|
||||
```markdown
|
||||
Create the file first.
|
||||
Validate the input.
|
||||
```
|
||||
|
||||
**Reason**: Skills must use imperative form without second-person language.
|
||||
|
||||
## Medium Priority Improvements
|
||||
|
||||
### 3. Add Progressive Disclosure
|
||||
**File**: SKILL.md
|
||||
**Dimension**: Content Organization
|
||||
**Impact**: +10 points
|
||||
|
||||
**Current**: All content in SKILL.md (3000+ words)
|
||||
|
||||
**Suggested**: Move detailed content to references/ directory, keep SKILL.md under 2000 words
|
||||
|
||||
**Reason**: SKILL.md should follow progressive disclosure principles with lean main content and detailed references.
|
||||
|
||||
## Low Priority Improvements
|
||||
|
||||
### 4. Add Examples
|
||||
**File**: examples/demo.md (new file)
|
||||
**Dimension**: Structural Integrity
|
||||
**Impact**: +5 points
|
||||
|
||||
**Suggested**: Create examples/demo.md with working demonstration
|
||||
|
||||
**Reason**: Examples help users understand how to use the skill effectively.
|
||||
|
||||
## Estimated Time to Complete
|
||||
- High Priority: 1 hour
|
||||
- Medium Priority: 2 hours
|
||||
- Low Priority: 30 minutes
|
||||
- **Total**: 3.5 hours
|
||||
|
||||
## Expected Score Improvement
|
||||
- Current: 67/100 (D+)
|
||||
- After High Priority: 82/100 (B-)
|
||||
- After All: 87/100 (B+)
|
||||
@@ -0,0 +1,45 @@
|
||||
# Skill Update Report: example-skill
|
||||
|
||||
## Summary
|
||||
- **Update Date**: 2025-01-25 14:30:00
|
||||
- **Improvement Plan**: improvement-plan-example-skill.md
|
||||
- **Files Modified**: 1
|
||||
- **Files Created**: 1
|
||||
- **Total Changes Applied**: 4
|
||||
|
||||
## Changes Applied
|
||||
|
||||
### SKILL.md
|
||||
- ✅ Fixed description trigger phrases (line 3-4)
|
||||
- ✅ Changed to imperative form (line 50, 52, 55)
|
||||
- ✅ Reorganized content for progressive disclosure
|
||||
|
||||
### examples/demo.md (new)
|
||||
- ✅ Created example demonstration file
|
||||
|
||||
## Quality Improvement
|
||||
|
||||
| Dimension | Before | After | Change |
|
||||
|-----------|--------|-------|--------|
|
||||
| Description Quality | 55/100 | 90/100 | +35 |
|
||||
| Content Organization | 70/100 | 85/100 | +15 |
|
||||
| Writing Style | 60/100 | 95/100 | +35 |
|
||||
| Structural Integrity | 80/100 | 90/100 | +10 |
|
||||
| **Overall** | **67/100** | **87/100** | **+20** |
|
||||
|
||||
**Grade**: D+ → B+
|
||||
|
||||
## Verification Results
|
||||
- ✅ YAML syntax valid
|
||||
- ✅ All files updated successfully
|
||||
- ✅ No unintended changes
|
||||
- ✅ Skill structure intact
|
||||
|
||||
## Backup
|
||||
Original files backed up to: `~/.claude/skills/backup/example-skill-20250125-143000/`
|
||||
|
||||
## Notes
|
||||
- All high priority changes applied successfully
|
||||
- Medium priority reorganization completed
|
||||
- Low priority example file created
|
||||
- Skill is now ready for use
|
||||
@@ -0,0 +1,39 @@
|
||||
# Error Handling
|
||||
|
||||
## Parse Errors
|
||||
|
||||
**Symptom:** Cannot read improvement plan
|
||||
|
||||
**Solutions:**
|
||||
- Verify file exists and is readable
|
||||
- Check file follows expected format
|
||||
- Ensure proper markdown structure
|
||||
|
||||
## Conflict Errors
|
||||
|
||||
**Symptom:** Multiple changes to same content
|
||||
|
||||
**Solutions:**
|
||||
- Apply highest priority change
|
||||
- Flag conflict for manual review
|
||||
- Document decision in report
|
||||
|
||||
## Edit Failures
|
||||
|
||||
**Symptom:** Cannot find current content to replace
|
||||
|
||||
**Solutions:**
|
||||
- Verify current content matches exactly
|
||||
- Check line numbers are correct
|
||||
- File may have been modified externally
|
||||
- Skip change and document in report
|
||||
|
||||
## Verification Failures
|
||||
|
||||
**Symptom:** Update broke skill structure
|
||||
|
||||
**Solutions:**
|
||||
- Restore from backup
|
||||
- Review conflicting changes
|
||||
- Apply changes individually
|
||||
- Skip problematic changes
|
||||
@@ -0,0 +1,570 @@
|
||||
# Merge Strategies for Skill Updates
|
||||
|
||||
Detailed strategies for intelligently merging multiple improvements to the same skill files.
|
||||
|
||||
## Overview
|
||||
|
||||
When applying improvements from an improvement plan, multiple changes may affect the same file or even the same lines. This document defines strategies for detecting conflicts, resolving them, and applying updates in the correct order.
|
||||
|
||||
## Priority-Based Merging
|
||||
|
||||
### Priority Order
|
||||
|
||||
Changes are applied in strict priority order:
|
||||
|
||||
1. **High Priority** - Critical issues that must be fixed
|
||||
2. **Medium Priority** - Important improvements
|
||||
3. **Low Priority** - Nice-to-have enhancements
|
||||
|
||||
### Rationale
|
||||
|
||||
- High priority changes often fix fundamental issues
|
||||
- Applying them first ensures a solid foundation
|
||||
- Lower priority changes may depend on high priority fixes
|
||||
- Prevents wasted effort on changes that might be reverted
|
||||
|
||||
## Per-File Merge Strategy
|
||||
|
||||
### Single File, Multiple Changes
|
||||
|
||||
When multiple changes affect the same file:
|
||||
|
||||
1. **Group by file**
|
||||
```
|
||||
SKILL.md: [
|
||||
{ line: 10, priority: high, ... },
|
||||
{ line: 50, priority: high, ... },
|
||||
{ line: 100, priority: medium, ... },
|
||||
{ line: 200, priority: low, ... }
|
||||
]
|
||||
```
|
||||
|
||||
2. **Sort by line number (descending)**
|
||||
- Process from bottom to top
|
||||
- Prevents line offset issues
|
||||
- Earlier changes don't affect later line numbers
|
||||
|
||||
```
|
||||
SKILL.md: [
|
||||
{ line: 200, priority: low, ... }, # First
|
||||
{ line: 100, priority: medium, ... }, # Second
|
||||
{ line: 50, priority: high, ... }, # Third
|
||||
{ line: 10, priority: high, ... } # Fourth
|
||||
]
|
||||
```
|
||||
|
||||
3. **Apply within same line range by priority**
|
||||
- If multiple changes affect same lines
|
||||
- Higher priority wins
|
||||
- Document conflict in report
|
||||
|
||||
### Algorithm
|
||||
|
||||
```python
|
||||
def merge_per_file(changes):
|
||||
"""Merge changes for a single file."""
|
||||
|
||||
# Group by line range
|
||||
by_range = {}
|
||||
for change in changes:
|
||||
key = (change['start'], change['end'])
|
||||
if key not in by_range:
|
||||
by_range[key] = []
|
||||
by_range[key].append(change)
|
||||
|
||||
# Resolve conflicts within ranges
|
||||
resolved = []
|
||||
for range_key, range_changes in by_range.items():
|
||||
if len(range_changes) == 1:
|
||||
resolved.append(range_changes[0])
|
||||
else:
|
||||
# Conflict: pick highest priority
|
||||
priority_order = {'high': 0, 'medium': 1, 'low': 2}
|
||||
sorted_changes = sorted(
|
||||
range_changes,
|
||||
key=lambda c: priority_order[c['priority']]
|
||||
)
|
||||
winner = sorted_changes[0]
|
||||
winner['conflicts_with'] = sorted_changes[1:]
|
||||
resolved.append(winner)
|
||||
|
||||
# Sort by line number descending
|
||||
resolved.sort(key=lambda c: c['start'], reverse=True)
|
||||
|
||||
return resolved
|
||||
```
|
||||
|
||||
## Cross-File Merge Strategy
|
||||
|
||||
### Multiple Files, Multiple Changes
|
||||
|
||||
When changes span multiple files:
|
||||
|
||||
1. **Execute all High Priority changes first**
|
||||
- Across all files
|
||||
- Ensures critical fixes everywhere
|
||||
|
||||
2. **Then execute all Medium Priority changes**
|
||||
- Build on High Priority foundation
|
||||
|
||||
3. **Finally execute all Low Priority changes**
|
||||
- Polish and refine
|
||||
|
||||
### Execution Order
|
||||
|
||||
```
|
||||
Round 1: High Priority
|
||||
├── SKILL.md (High changes)
|
||||
├── references/guide.md (High changes)
|
||||
└── examples/demo.md (High changes)
|
||||
|
||||
Round 2: Medium Priority
|
||||
├── SKILL.md (Medium changes)
|
||||
├── references/guide.md (Medium changes)
|
||||
└── examples/new.md (Medium, new file)
|
||||
|
||||
Round 3: Low Priority
|
||||
└── SKILL.md (Low changes)
|
||||
```
|
||||
|
||||
### Algorithm
|
||||
|
||||
```python
|
||||
def merge_cross_files(all_changes):
|
||||
"""Merge changes across all files."""
|
||||
|
||||
# Group by priority
|
||||
by_priority = {
|
||||
'high': [],
|
||||
'medium': [],
|
||||
'low': []
|
||||
}
|
||||
|
||||
for change in all_changes:
|
||||
by_priority[change['priority']].append(change)
|
||||
|
||||
# Process each priority level
|
||||
execution_order = []
|
||||
for priority in ['high', 'medium', 'low']:
|
||||
# Group by file within priority
|
||||
by_file = {}
|
||||
for change in by_priority[priority]:
|
||||
file = change['file']
|
||||
if file not in by_file:
|
||||
by_file[file] = []
|
||||
by_file[file].append(change)
|
||||
|
||||
# Merge within each file
|
||||
for file, file_changes in by_file.items():
|
||||
merged = merge_per_file(file_changes)
|
||||
execution_order.extend(merged)
|
||||
|
||||
return execution_order
|
||||
```
|
||||
|
||||
## Conflict Detection
|
||||
|
||||
### Types of Conflicts
|
||||
|
||||
#### 1. Same Line, Different Content
|
||||
|
||||
```
|
||||
Change A: SKILL.md:10:10
|
||||
Current: "You should create file"
|
||||
Suggested: "Create the file"
|
||||
|
||||
Change B: SKILL.md:10:10
|
||||
Current: "You should create file"
|
||||
Suggested: "Create file now"
|
||||
```
|
||||
|
||||
**Resolution:** Higher priority wins, document conflict
|
||||
|
||||
#### 2. Overlapping Line Ranges
|
||||
|
||||
```
|
||||
Change A: SKILL.md:10:15
|
||||
Current: lines 10-15 content
|
||||
Suggested: new content for 10-15
|
||||
|
||||
Change B: SKILL.md:12:20
|
||||
Current: lines 12-20 content
|
||||
Suggested: new content for 12-20
|
||||
```
|
||||
|
||||
**Resolution:** Higher priority wins, lower priority is skipped
|
||||
|
||||
#### 3. Same Priority Conflicts
|
||||
|
||||
```
|
||||
Change A: SKILL.md:10:10 (High)
|
||||
Suggested: "Option A"
|
||||
|
||||
Change B: SKILL.md:10:10 (High)
|
||||
Suggested: "Option B"
|
||||
```
|
||||
|
||||
**Resolution:** First in list wins, flag for manual review
|
||||
|
||||
### Conflict Detection Algorithm
|
||||
|
||||
```python
|
||||
def detect_conflicts(changes):
|
||||
"""Detect conflicting changes."""
|
||||
|
||||
conflicts = []
|
||||
|
||||
# Sort by line range
|
||||
sorted_changes = sorted(changes, key=lambda c: (c['start'], c['end']))
|
||||
|
||||
for i in range(len(sorted_changes)):
|
||||
for j in range(i + 1, len(sorted_changes)):
|
||||
a = sorted_changes[i]
|
||||
b = sorted_changes[j]
|
||||
|
||||
# Check for overlap
|
||||
if ranges_overlap(a, b):
|
||||
# Check if suggestions differ
|
||||
if a['suggested'] != b['suggested']:
|
||||
conflicts.append({
|
||||
'changes': [a, b],
|
||||
'type': 'overlap',
|
||||
'resolution': 'priority'
|
||||
})
|
||||
|
||||
return conflicts
|
||||
|
||||
def ranges_overlap(a, b):
|
||||
"""Check if two line ranges overlap."""
|
||||
|
||||
a_start, a_end = a['start'], a['end']
|
||||
b_start, b_end = b['start'], b['end']
|
||||
|
||||
return not (a_end < b_start or b_end < a_start)
|
||||
```
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
### Resolution Strategies
|
||||
|
||||
#### 1. Priority-Based Resolution
|
||||
|
||||
**Apply highest priority change:**
|
||||
```
|
||||
Conflicting changes:
|
||||
- High: Fix description
|
||||
- Low: Clarify text
|
||||
|
||||
Resolution: Apply High, skip Low
|
||||
```
|
||||
|
||||
#### 2. First-Win Resolution
|
||||
|
||||
**For same priority conflicts:**
|
||||
```
|
||||
Conflicting changes (both High):
|
||||
- #1: Fix description option A
|
||||
- #2: Fix description option B
|
||||
|
||||
Resolution: Apply #1, skip #2, flag for review
|
||||
```
|
||||
|
||||
#### 3. Manual Review Flag
|
||||
|
||||
**Document conflicts requiring human review:**
|
||||
```markdown
|
||||
## Conflicts Requiring Manual Review
|
||||
|
||||
### SKILL.md:10:10
|
||||
**Applied:** High Priority - Fix description (Option A)
|
||||
**Skipped:** High Priority - Alternative fix (Option B)
|
||||
**Reason:** Same priority, first change applied
|
||||
|
||||
Review suggested alternative and manually apply if preferred.
|
||||
```
|
||||
|
||||
### Resolution Algorithm
|
||||
|
||||
```python
|
||||
def resolve_conflicts(changes):
|
||||
"""Resolve conflicts using priority-based strategy."""
|
||||
|
||||
priority_value = {'high': 3, 'medium': 2, 'low': 1}
|
||||
|
||||
# Track applied line ranges
|
||||
applied_ranges = []
|
||||
|
||||
# Filter changes
|
||||
resolved = []
|
||||
skipped = []
|
||||
|
||||
for change in sorted(changes, key=lambda c: (
|
||||
-priority_value[c['priority']], # Higher priority first
|
||||
c['start']
|
||||
)):
|
||||
# Check if range already applied
|
||||
conflict = False
|
||||
for applied in applied_ranges:
|
||||
if ranges_overlap(change, applied):
|
||||
conflict = True
|
||||
skipped.append({
|
||||
'change': change,
|
||||
'reason': 'overlap_with_higher_priority',
|
||||
'conflicts_with': applied
|
||||
})
|
||||
break
|
||||
|
||||
if not conflict:
|
||||
resolved.append(change)
|
||||
applied_ranges.append({
|
||||
'start': change['start'],
|
||||
'end': change['end']
|
||||
})
|
||||
|
||||
return resolved, skipped
|
||||
```
|
||||
|
||||
## Special Cases
|
||||
|
||||
### New File Creation
|
||||
|
||||
When creating new files (no line numbers):
|
||||
|
||||
1. **Check if file already exists**
|
||||
2. **If exists:** Verify content matches or skip
|
||||
3. **If not exists:** Create with suggested content
|
||||
|
||||
```python
|
||||
def handle_new_file(change, skill_path):
|
||||
"""Handle new file creation."""
|
||||
|
||||
file_path = os.path.join(skill_path, change['file'])
|
||||
|
||||
if os.path.exists(file_path):
|
||||
# File exists, verify content
|
||||
existing = read_file(file_path)
|
||||
if existing.strip() == change['suggested'].strip():
|
||||
return {'status': 'already_exists', 'action': 'skip'}
|
||||
else:
|
||||
return {
|
||||
'status': 'conflict',
|
||||
'action': 'skip',
|
||||
'reason': 'File exists with different content'
|
||||
}
|
||||
else:
|
||||
# Create new file
|
||||
write_file(file_path, change['suggested'])
|
||||
return {'status': 'created', 'action': 'created'}
|
||||
```
|
||||
|
||||
### Append Operations
|
||||
|
||||
When no line numbers and file exists:
|
||||
|
||||
```python
|
||||
def handle_append(change, skill_path):
|
||||
"""Handle append to existing file."""
|
||||
|
||||
file_path = os.path.join(skill_path, change['file'])
|
||||
|
||||
if os.path.exists(file_path):
|
||||
# Append to end
|
||||
existing = read_file(file_path)
|
||||
updated = existing + '\n\n' + change['suggested']
|
||||
write_file(file_path, updated)
|
||||
return {'status': 'appended', 'action': 'appended'}
|
||||
else:
|
||||
# Treat as new file
|
||||
write_file(file_path, change['suggested'])
|
||||
return {'status': 'created', 'action': 'created'}
|
||||
```
|
||||
|
||||
### YAML Frontmatter Updates
|
||||
|
||||
Special handling for YAML frontmatter:
|
||||
|
||||
1. **Parse existing frontmatter**
|
||||
2. **Update specific fields**
|
||||
3. **Preserve other fields**
|
||||
4. **Validate YAML syntax**
|
||||
|
||||
```python
|
||||
def update_frontmatter(file_path, updates):
|
||||
"""Update YAML frontmatter fields."""
|
||||
|
||||
# Read file
|
||||
content = read_file(file_path)
|
||||
|
||||
# Extract frontmatter
|
||||
frontmatter, body = extract_frontmatter(content)
|
||||
|
||||
# Parse YAML
|
||||
import yaml
|
||||
data = yaml.safe_load(frontmatter)
|
||||
|
||||
# Apply updates
|
||||
for key, value in updates.items():
|
||||
data[key] = value
|
||||
|
||||
# Serialize back
|
||||
new_frontmatter = yaml.dump(data, default_flow_style=False)
|
||||
|
||||
# Reconstruct file
|
||||
updated = f"---\n{new_frontmatter}---\n{body}"
|
||||
|
||||
write_file(file_path, updated)
|
||||
```
|
||||
|
||||
## Verification After Merge
|
||||
|
||||
### Post-Merge Checks
|
||||
|
||||
After applying all changes:
|
||||
|
||||
1. **Verify file existence**
|
||||
```python
|
||||
for change in applied_changes:
|
||||
file_path = os.path.join(skill_path, change['file'])
|
||||
assert os.path.exists(file_path), f"File not found: {file_path}"
|
||||
```
|
||||
|
||||
2. **Verify YAML syntax**
|
||||
```bash
|
||||
~/.claude/skills/skill-quality-reviewer/scripts/extract-yaml.sh <skill-path>
|
||||
```
|
||||
|
||||
3. **Verify content was applied**
|
||||
```python
|
||||
for change in applied_changes:
|
||||
content = read_file(change['file'])
|
||||
assert change['suggested'] in content, "Change not found in file"
|
||||
```
|
||||
|
||||
4. **Verify no unintended changes**
|
||||
```python
|
||||
# Compare backup with current
|
||||
# Only expected changes should be present
|
||||
```
|
||||
|
||||
## Complete Merge Workflow
|
||||
|
||||
```python
|
||||
def execute_merge(improvement_plan, skill_path):
|
||||
"""Complete merge workflow."""
|
||||
|
||||
# 1. Parse improvement plan
|
||||
changes = parse_improvement_plan(improvement_plan)
|
||||
|
||||
# 2. Detect conflicts
|
||||
conflicts = detect_conflicts(changes)
|
||||
|
||||
# 3. Resolve conflicts
|
||||
resolved, skipped = resolve_conflicts(changes)
|
||||
|
||||
# 4. Sort by execution order
|
||||
execution_order = merge_cross_files(resolved)
|
||||
|
||||
# 5. Backup original files
|
||||
backup_skill(skill_path)
|
||||
|
||||
# 6. Execute changes
|
||||
applied = []
|
||||
failed = []
|
||||
|
||||
for change in execution_order:
|
||||
try:
|
||||
if change['start'] is None:
|
||||
# New file or append
|
||||
result = handle_new_file(change, skill_path)
|
||||
else:
|
||||
# Edit existing content
|
||||
result = edit_file(
|
||||
change['file'],
|
||||
change['start'],
|
||||
change['end'],
|
||||
change['current'],
|
||||
change['suggested']
|
||||
)
|
||||
|
||||
applied.append({
|
||||
'change': change,
|
||||
'result': result
|
||||
})
|
||||
|
||||
except Exception as e:
|
||||
failed.append({
|
||||
'change': change,
|
||||
'error': str(e)
|
||||
})
|
||||
|
||||
# 7. Verify results
|
||||
verification = verify_merge(skill_path, applied)
|
||||
|
||||
# 8. Generate report
|
||||
report = generate_merge_report(
|
||||
applied=applied,
|
||||
failed=failed,
|
||||
skipped=skipped,
|
||||
conflicts=conflicts,
|
||||
verification=verification
|
||||
)
|
||||
|
||||
return report
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When Merging
|
||||
|
||||
1. **Always backup first** - Restore if things go wrong
|
||||
2. **Apply high priority first** - Critical fixes first
|
||||
3. **Process bottom to top** - Avoid line offset issues
|
||||
4. **Verify after each file** - Catch errors early
|
||||
5. **Document all decisions** - Clear update report
|
||||
|
||||
### When Conflicts Occur
|
||||
|
||||
1. **Prioritize by importance** - Critical over nice-to-have
|
||||
2. **Flag for review** - Let user decide when unsure
|
||||
3. **Don't silently skip** - Document everything
|
||||
4. **Preserve originals** - Backup enables recovery
|
||||
|
||||
### After Merging
|
||||
|
||||
1. **Run verification** - Ensure skill still works
|
||||
2. **Review report** - Confirm changes match intent
|
||||
3. **Test the skill** - Verify functionality
|
||||
4. **Keep backup** - Until confident in changes
|
||||
|
||||
## Error Recovery
|
||||
|
||||
### If Merge Fails
|
||||
|
||||
1. **Stop immediately** - Don't continue with errors
|
||||
2. **Identify failure point** - Which change caused issue
|
||||
3. **Restore from backup** - Return to original state
|
||||
4. **Analyze failure** - Understand why it failed
|
||||
5. **Retry selectively** - Skip problematic changes
|
||||
|
||||
### Partial Recovery
|
||||
|
||||
If some changes applied before failure:
|
||||
|
||||
```python
|
||||
def partial_recovery(applied, backup_path):
|
||||
"""Restore only failed changes."""
|
||||
|
||||
# Get list of applied files
|
||||
applied_files = set(c['file'] for c in applied)
|
||||
|
||||
# Restore only files that failed
|
||||
for file_path in failed_files:
|
||||
restore_from_backup(file_path, backup_path)
|
||||
|
||||
return {
|
||||
'restored': failed_files,
|
||||
'preserved': applied_files
|
||||
}
|
||||
```
|
||||
|
||||
This ensures successful changes are preserved while failed ones are reverted.
|
||||
@@ -0,0 +1,518 @@
|
||||
# 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
|
||||
@@ -0,0 +1,53 @@
|
||||
# Supported Update Types
|
||||
|
||||
## YAML Frontmatter Updates
|
||||
|
||||
Update name or description:
|
||||
|
||||
```yaml
|
||||
# Current
|
||||
---
|
||||
name: my-skill
|
||||
description: A helpful skill for various tasks.
|
||||
---
|
||||
|
||||
# Suggested
|
||||
---
|
||||
name: api-contract-manager
|
||||
description: This skill should be used when the user asks to "validate API contract", "check API compatibility", or "detect breaking changes"
|
||||
---
|
||||
```
|
||||
|
||||
## SKILL.md Content Updates
|
||||
|
||||
Fix writing style (imperative form):
|
||||
|
||||
```
|
||||
# Current
|
||||
You should create the file first.
|
||||
You need to validate the input.
|
||||
|
||||
# Suggested
|
||||
Create the file first.
|
||||
Validate the input.
|
||||
```
|
||||
|
||||
## References/ File Updates
|
||||
|
||||
Add new section:
|
||||
|
||||
```markdown
|
||||
## New Section
|
||||
|
||||
Content to be added...
|
||||
```
|
||||
|
||||
## New File Creation
|
||||
|
||||
Create new example file:
|
||||
|
||||
```markdown
|
||||
# examples/demo.md
|
||||
|
||||
Complete example content...
|
||||
```
|
||||
56
文档润色流和知识库构建流/claude-scholar/skills/skill-improver/scripts/backup-skill.sh
Executable file
56
文档润色流和知识库构建流/claude-scholar/skills/skill-improver/scripts/backup-skill.sh
Executable file
@@ -0,0 +1,56 @@
|
||||
#!/bin/bash
|
||||
# backup-skill.sh - Backup skill files before applying updates
|
||||
# Part of skill-improver
|
||||
|
||||
# Usage: ./backup-skill.sh <skill-path>
|
||||
# Example: ./backup-skill.sh ~/.claude/skills/git-workflow
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# Check if path provided
|
||||
if [ $# -eq 0 ]; then
|
||||
echo "Usage: $0 <skill-path>"
|
||||
echo "Example: $0 ~/.claude/skills/git-workflow"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
SKILL_PATH="$1"
|
||||
SKILL_NAME=$(basename "$SKILL_PATH")
|
||||
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
|
||||
BACKUP_DIR="$HOME/.claude/skills/backup/${SKILL_NAME}-${TIMESTAMP}"
|
||||
|
||||
# Check if skill path exists
|
||||
if [ ! -d "$SKILL_PATH" ]; then
|
||||
echo "Error: Skill path not found: ${SKILL_PATH}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Create backup directory
|
||||
echo "Creating backup directory: ${BACKUP_DIR}"
|
||||
mkdir -p "$BACKUP_DIR"
|
||||
|
||||
# Copy entire skill directory
|
||||
echo "Backing up skill: ${SKILL_NAME}"
|
||||
cp -R "$SKILL_PATH"/* "$BACKUP_DIR/"
|
||||
|
||||
# Create backup manifest
|
||||
cat > "$BACKUP_DIR/backup-manifest.txt" <<EOF
|
||||
Backup Manifest
|
||||
==============
|
||||
Skill Name: ${SKILL_NAME}
|
||||
Source Path: ${SKILL_PATH}
|
||||
Backup Date: $(date)
|
||||
Timestamp: ${TIMESTAMP}
|
||||
|
||||
Files Backed Up:
|
||||
$(find "$BACKUP_DIR" -type f ! -name "backup-manifest.txt" | sed "s|$BACKUP_DIR/||")
|
||||
|
||||
Restore Instructions:
|
||||
-------------------
|
||||
To restore this backup, run:
|
||||
cp -R ${BACKUP_DIR}/* ${SKILL_PATH}/
|
||||
EOF
|
||||
|
||||
echo "Backup complete!"
|
||||
echo "Backup location: ${BACKUP_DIR}"
|
||||
echo "Files backed up: $(find "$BACKUP_DIR" -type f ! -name "backup-manifest.txt" | wc -l)"
|
||||
251
文档润色流和知识库构建流/claude-scholar/skills/skill-improver/scripts/verify-update.sh
Executable file
251
文档润色流和知识库构建流/claude-scholar/skills/skill-improver/scripts/verify-update.sh
Executable file
@@ -0,0 +1,251 @@
|
||||
#!/bin/bash
|
||||
# verify-update.sh - Verify skill integrity after applying updates
|
||||
# Part of skill-improver
|
||||
|
||||
# Usage: ./verify-update.sh <skill-path>
|
||||
# Example: ./verify-update.sh ~/.claude/skills/git-workflow
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# Check if path provided
|
||||
if [ $# -eq 0 ]; then
|
||||
echo "Usage: $0 <skill-path>"
|
||||
echo "Example: $0 ~/.claude/skills/git-workflow"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
SKILL_PATH="$1"
|
||||
SKILL_NAME=$(basename "$SKILL_PATH")
|
||||
SKILL_FILE="${SKILL_PATH}/SKILL.md"
|
||||
|
||||
# Verification results
|
||||
PASS=0
|
||||
FAIL=0
|
||||
WARN=0
|
||||
|
||||
echo "================================"
|
||||
echo "Skill Update Verification"
|
||||
echo "================================"
|
||||
echo "Skill: ${SKILL_NAME}"
|
||||
echo "Path: ${SKILL_PATH}"
|
||||
echo ""
|
||||
|
||||
# Check 1: SKILL.md exists
|
||||
echo "Check 1: SKILL.md exists"
|
||||
if [ -f "$SKILL_FILE" ]; then
|
||||
echo "✅ PASS: SKILL.md found"
|
||||
((PASS++))
|
||||
else
|
||||
echo "❌ FAIL: SKILL.md not found"
|
||||
((FAIL++))
|
||||
echo ""
|
||||
echo "Verification Summary:"
|
||||
echo " Passed: ${PASS}"
|
||||
echo " Failed: ${FAIL}"
|
||||
echo " Warnings: ${WARN}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
|
||||
# Check 2: YAML frontmatter valid
|
||||
echo "Check 2: YAML frontmatter valid"
|
||||
if command -v yq &> /dev/null; then
|
||||
# Use yq if available for proper YAML validation
|
||||
FRONTMAFTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$SKILL_FILE")
|
||||
if echo "$FRONTMAFTER" | yq eval '.' > /dev/null 2>&1; then
|
||||
echo "✅ PASS: YAML frontmatter is valid"
|
||||
((PASS++))
|
||||
else
|
||||
echo "❌ FAIL: Invalid YAML frontmatter"
|
||||
((FAIL++))
|
||||
fi
|
||||
else
|
||||
# Fallback: basic check for name and description fields
|
||||
if grep -q "^name:" "$SKILL_FILE" && grep -q "^description:" "$SKILL_FILE"; then
|
||||
echo "✅ PASS: YAML frontmatter has required fields (name, description)"
|
||||
((PASS++))
|
||||
else
|
||||
echo "❌ FAIL: YAML frontmatter missing required fields"
|
||||
((FAIL++))
|
||||
fi
|
||||
fi
|
||||
|
||||
echo ""
|
||||
|
||||
# Check 3: Directory structure
|
||||
echo "Check 3: Directory structure"
|
||||
DIRS_OK=true
|
||||
|
||||
if [ -d "${SKILL_PATH}/references" ]; then
|
||||
echo " ✅ references/ exists"
|
||||
else
|
||||
echo " ℹ️ references/ not found (optional)"
|
||||
((WARN++))
|
||||
fi
|
||||
|
||||
if [ -d "${SKILL_PATH}/examples" ]; then
|
||||
echo " ✅ examples/ exists"
|
||||
else
|
||||
echo " ℹ️ examples/ not found (optional)"
|
||||
((WARN++))
|
||||
fi
|
||||
|
||||
if [ -d "${SKILL_PATH}/scripts" ]; then
|
||||
echo " ✅ scripts/ exists"
|
||||
# Check if scripts are executable (macOS compatible)
|
||||
SCRIPT_COUNT=$(find "${SKILL_PATH}/scripts" -type f | wc -l | tr -d ' ')
|
||||
EXEC_COUNT=0
|
||||
for script in "${SKILL_PATH}/scripts"/*; do
|
||||
if [ -f "$script" ] && [ -x "$script" ]; then
|
||||
((EXEC_COUNT++))
|
||||
fi
|
||||
done
|
||||
if [ "$SCRIPT_COUNT" -gt 0 ] && [ "$EXEC_COUNT" -eq "$SCRIPT_COUNT" ]; then
|
||||
echo " ✅ All scripts are executable"
|
||||
elif [ "$SCRIPT_COUNT" -gt 0 ]; then
|
||||
echo " ⚠️ Some scripts are not executable (${EXEC_COUNT}/${SCRIPT_COUNT} executable)"
|
||||
((WARN++))
|
||||
fi
|
||||
else
|
||||
echo " ℹ️ scripts/ not found (optional)"
|
||||
fi
|
||||
|
||||
if [ "$DIRS_OK" = true ] || [ ! -d "${SKILL_PATH}/references" ] && [ ! -d "${SKILL_PATH}/examples" ]; then
|
||||
echo "✅ PASS: Directory structure is valid"
|
||||
((PASS++))
|
||||
else
|
||||
echo "⚠️ WARN: Optional directories missing"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
|
||||
# Check 4: SKILL.md size (progressive disclosure check)
|
||||
echo "Check 4: SKILL.md size (progressive disclosure)"
|
||||
WORD_COUNT=$(wc -w < "$SKILL_FILE" | tr -d ' ')
|
||||
|
||||
if [ "$WORD_COUNT" -lt 3000 ]; then
|
||||
echo "✅ PASS: SKILL.md is ${WORD_COUNT} words (good progressive disclosure)"
|
||||
((PASS++))
|
||||
elif [ "$WORD_COUNT" -lt 5000 ]; then
|
||||
echo "⚠️ WARN: SKILL.md is ${WORD_COUNT} words (could be more concise)"
|
||||
((WARN++))
|
||||
else
|
||||
echo "❌ FAIL: SKILL.md is ${WORD_COUNT} words (too long, should use references/)"
|
||||
((FAIL++))
|
||||
fi
|
||||
|
||||
echo ""
|
||||
|
||||
# Check 5: No broken references (basic check)
|
||||
echo "Check 5: Referenced files exist"
|
||||
BROKEN_REFS=0
|
||||
|
||||
# Extract references from SKILL.md
|
||||
# Look for patterns like "See `references/file.md`" or "**`references/pattern.md`**"
|
||||
REF_FILES=$(grep -oE 'references/[-_a-zA-Z0-9\.]+' "$SKILL_FILE" | sort -u || true)
|
||||
|
||||
if [ -n "$REF_FILES" ]; then
|
||||
for ref in $REF_FILES; do
|
||||
REF_PATH="${SKILL_PATH}/${ref}"
|
||||
if [ -f "$REF_PATH" ]; then
|
||||
echo " ✅ ${ref} exists"
|
||||
else
|
||||
echo " ❌ ${ref} referenced but not found"
|
||||
((BROKEN_REFS++))
|
||||
fi
|
||||
done
|
||||
|
||||
if [ "$BROKEN_REFS" -eq 0 ]; then
|
||||
echo "✅ PASS: All referenced files exist"
|
||||
((PASS++))
|
||||
else
|
||||
echo "❌ FAIL: ${BROKEN_REFS} referenced file(s) not found"
|
||||
((FAIL++))
|
||||
fi
|
||||
else
|
||||
echo "ℹ️ No references found in SKILL.md"
|
||||
echo "✅ PASS: No broken references"
|
||||
((PASS++))
|
||||
fi
|
||||
|
||||
echo ""
|
||||
|
||||
# Check 6: Writing style (imperative form check)
|
||||
echo "Check 6: Writing style (imperative form check)"
|
||||
SECOND_PERSON=$(grep -iE "you should|you need|you can|you must|you'll|your" "$SKILL_FILE" | wc -l | tr -d ' ')
|
||||
|
||||
if [ "$SECOND_PERSON" -eq 0 ]; then
|
||||
echo "✅ PASS: No second-person language found"
|
||||
((PASS++))
|
||||
elif [ "$SECOND_PERSON" -lt 5 ]; then
|
||||
echo "⚠️ WARN: ${SECOND_PERSON} instance(s) of second-person language"
|
||||
((WARN++))
|
||||
# Still count as pass for now
|
||||
((PASS++))
|
||||
else
|
||||
echo "❌ FAIL: ${SECOND_PERSON} instances of second-person language"
|
||||
echo " (should use imperative form)"
|
||||
((FAIL++))
|
||||
fi
|
||||
|
||||
echo ""
|
||||
|
||||
# Check 7: Description quality (basic check)
|
||||
echo "Check 7: Description quality"
|
||||
DESCRIPTION=$(grep "^description:" "$SKILL_FILE" | head -1)
|
||||
|
||||
if [ -n "$DESCRIPTION" ]; then
|
||||
# Check for third person
|
||||
if echo "$DESCRIPTION" | grep -qi "this skill should be used when"; then
|
||||
echo " ✅ Uses third-person format"
|
||||
DESC_OK=true
|
||||
else
|
||||
echo " ❌ Does not use third-person format"
|
||||
DESC_OK=false
|
||||
fi
|
||||
|
||||
# Check length (100-300 characters ideal)
|
||||
DESC_LEN=$(echo "$DESCRIPTION" | cut -d: -f2- | wc -c | tr -d ' ')
|
||||
if [ "$DESC_LEN" -ge 100 ] && [ "$DESC_LEN" -le 300 ]; then
|
||||
echo " ✅ Description length is ${DESC_LEN} characters (good)"
|
||||
elif [ "$DESC_LEN" -lt 100 ]; then
|
||||
echo " ⚠️ Description is ${DESC_LEN} characters (too short)"
|
||||
DESC_OK=false
|
||||
else
|
||||
echo " ⚠️ Description is ${DESC_LEN} characters (too long)"
|
||||
DESC_OK=false
|
||||
fi
|
||||
|
||||
if [ "$DESC_OK" = true ]; then
|
||||
echo "✅ PASS: Description quality is good"
|
||||
((PASS++))
|
||||
else
|
||||
echo "⚠️ WARN: Description could be improved"
|
||||
((WARN++))
|
||||
# Still count as pass for basic check
|
||||
((PASS++))
|
||||
fi
|
||||
else
|
||||
echo "❌ FAIL: No description found in frontmatter"
|
||||
((FAIL++))
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "================================"
|
||||
echo "Verification Summary"
|
||||
echo "================================"
|
||||
echo " Passed: ${PASS}"
|
||||
echo " Failed: ${FAIL}"
|
||||
echo " Warnings: ${WARN}"
|
||||
echo ""
|
||||
|
||||
if [ "$FAIL" -eq 0 ]; then
|
||||
echo "✅ Verification PASSED"
|
||||
echo " Skill structure is valid."
|
||||
exit 0
|
||||
else
|
||||
echo "❌ Verification FAILED"
|
||||
echo " Please review and fix the failed checks."
|
||||
exit 1
|
||||
fi
|
||||
Reference in New Issue
Block a user