skill-improve

Reference Files

Detailed improvement guidance:

• improvement-categories.md - Types of improvements and what to look for
• prioritization-guide.md - Impact/effort matrix for prioritizing recommendations
• examples.md - Before/after examples showing improvements in action
• report-template.md - Standardized output format for improvement reports

Purpose

This skill generates actionable, prioritized improvement recommendations for Claude Code skills. Unlike skill-quality (which scores quality), this skill focuses on what to fix and in what order.

Improvement Categories

Aligned 1:1 with skill-quality's 6 evaluation dimensions:

See improvement-categories.md for detailed guidance on each category.

Priority Levels

Recommendations are prioritized by impact and effort:

See prioritization-guide.md for the complete impact/effort matrix.

Evaluation Process

1. Read the skill - Examine SKILL.md and all reference files
2. Identify issues - Find gaps, weaknesses, and opportunities
3. Categorize issues - Map each issue to a category
4. Assess impact/effort - Determine priority level
5. Generate recommendations - Provide specific, actionable advice
6. Create report - Use standardized format

What Makes a Good Recommendation

Specific: Points to exact text, files, or patterns

# Good
"Add 'when to use' guidance to line 3 of the description"

# Poor
"Improve the description"

Actionable: Tells exactly what to do

# Good
"Add these trigger phrases to description: 'organize commits',
'clean up git history', 'prepare for PR'"

# Poor
"Consider adding more trigger phrases"

Justified: Explains why it matters

# Good
"Add error handling examples (P2) - users frequently encounter
authentication failures which aren't covered"

# Poor
"Add error handling examples"

Tools Used

This skill uses read-only tools for analysis:

• Read - Examine SKILL.md and reference files
• Glob - Find all files in the skill directory
• Grep - Search for patterns and keywords
• Bash - Execute read-only commands (ls, wc, etc.)

No files are modified during evaluation.

Usage Examples

Get improvement recommendations:

How can I improve the cc-lint skill?

Focus on specific category:

What trigger phrase improvements does cc-lint need?

Quick wins only:

What are the easiest improvements for vc-ship?

Comprehensive review:

Give me all improvement recommendations for my skill

Output

Reports include:

• Prioritized list of recommendations
• Category for each recommendation
• Impact/effort assessment
• Specific implementation guidance
• Optional before/after examples

See report-template.md for the complete output format.

Relationship to Other Skills

Typical workflow:

1. Run cc-lint to fix structural issues
2. Run skill-quality to assess quality level
3. Run skill-improve to get actionable improvements
4. Implement P1/P2 recommendations
5. Re-run skill-quality to verify improvement

Improvement Workflow Tips

Start with P1s: These are high-impact, low-effort - do them first.

Batch similar work: Group documentation changes, trigger phrase updates, etc.

Validate changes: After implementing recommendations, run cc-lint to verify.

Iterate: Improvement is continuous; re-evaluate periodically.