Skill Improver

Iteratively review and fix Claude Code skills until they meet quality standards

Automatically reviews and fixes Claude Code skills through iterative refinement cycles using the skill-reviewer agent. Continues until quality bar is met or max iterations reached.

Overview

The Skill Improver plugin runs automated fix-review cycles on Claude Code skills until they meet quality standards. It uses the skill-reviewer agent from the plugin-dev plugin to identify issues, then fixes them and re-reviews iteratively.

Author: Paweł Płatek

Prerequisites

Requires the plugin-dev plugin which provides the skill-reviewer agent.

Verify it’s enabled:

/plugins

If plugin-dev is missing, install from the Trail of Bits plugin repository.

Commands

/skill-improver <SKILL_PATH> [—max-iterations N]

Start an improvement loop for a skill:

/skill-improver ./plugins/my-plugin/skills/my-skill
/skill-improver ./skills/my-skill/SKILL.md --max-iterations 15

Arguments:

• <SKILL_PATH> - Path to skill directory or SKILL.md file
• --max-iterations N - Maximum iterations (default: 20)

/cancel-skill-improver [SESSION_ID]

Stop the active improvement loop:

/cancel-skill-improver

Changes made during the loop are preserved.

How It Works

1. Start Loop

   /skill-improver resolves the skill path and creates a session state file in .claude/

2. Review Phase

   Calls the skill-reviewer agent to identify quality issues, categorized by severity:

   • Critical - Blocks skill loading or causes runtime failures
   • Major - Significantly degrades skill effectiveness
   • Minor - Polish items, may be false positives
3. Fix Phase

   • Critical issues - Fixed immediately (always valid)
   • Major issues - Fixed immediately (required by standards)
   • Minor issues - Evaluated before fixing (may be false positives)
4. Re-review

   Runs skill-reviewer again to verify fixes worked and catch any new issues

5. Repeat or Complete

   Continues until:

   • Quality bar is met (outputs <skill-improvement-complete>)
   • Max iterations reached (default: 20)

Issue Categorization

Critical Issues (MUST fix immediately)

These block skill loading or cause runtime failures:

Missing Frontmatter

Missing name or description fields - Claude cannot index or trigger the skill

Invalid YAML

Frontmatter syntax errors - Parsing fails, skill won’t load

Broken References

Referenced files don’t exist - Runtime errors when Claude follows links

Broken Paths

Invalid file paths - Tool failures at runtime

Major Issues (MUST fix)

These significantly degrade skill effectiveness:

• Weak trigger descriptions - Claude may not recognize when to use the skill
• Wrong writing voice - Second person “you” instead of imperative
• SKILL.md exceeds 500 lines - Should use references/ for details
• Missing “When to Use” - Required by project standards
• Missing “When NOT to Use” - Required by project standards
• Description doesn’t specify when to trigger - Skill may never be selected

Minor Issues (Evaluate before fixing)

These are polish items that may or may not improve the skill:

• Subjective style preferences
• Optional enhancements
• “Nice to have” improvements
• Formatting suggestions

Evaluate minor issues before fixing. Ask:

1. Is this a genuine improvement?
2. Could this be a false positive?
3. Would this actually help Claude use the skill?

Only implement minor fixes that are clearly beneficial.

Installation

/plugin install trailofbits/skills/plugins/skill-improver

Usage Example

1. Start Improvement Loop

   /skill-improver ./plugins/my-plugin/skills/my-skill
   
2. Iteration 1 - Review

   ## Skill Review Results
   
   Critical Issues:
   - SKILL.md:1 - Missing required 'name' field in frontmatter
   
   Major Issues:
   - SKILL.md:3 - Description uses second person ("you should use")
   - Missing "When NOT to Use" section
   
   Minor Issues:
   - Line 45 is verbose
   
3. Iteration 1 - Fix

   Claude fixes critical and major issues:

   • Adds name field to frontmatter
   • Rewrites description in third person
   • Adds “When NOT to Use” section
   • Evaluates minor issue: “Line 45 is verbose”
     • Decision: Verbosity provides useful context, skip
4. Iteration 2 - Re-review

   ## Skill Review Results
   
   Minor Issues:
   - Line 45 is verbose
   
5. Iteration 2 - Evaluate

   Claude evaluates minor issue again:

   • Line 45 communicates effectively as-is
   • Verbosity provides useful context
   • No change needed
6. Complete

   All critical/major issues resolved. Claude outputs:

   <skill-improvement-complete>
   

   Loop terminates successfully.

Completion Criteria

CRITICAL: The stop hook ONLY checks for the explicit marker <skill-improvement-complete>. No other signal will terminate the loop.

When to Output the Marker

When NOT to Output the Marker

• Any critical issue remains unfixed
• Any major issue remains unfixed
• Haven’t run skill-reviewer to verify fixes worked

Multiple Sessions

Multiple improvement loops can run simultaneously on different skills. Each gets:

• Unique session ID
• Separate state file in .claude/skill-improver.*.local.md
• Independent iteration tracking

View active sessions:

ls .claude/skill-improver.*.local.md

Troubleshooting

subagent not found

Install the plugin-dev plugin:

/plugin install plugin-dev

Loop never completes

Check state:

cat .claude/skill-improver.*.local.md

Cancel manually:

/cancel-skill-improver

Orphaned state files

Remove orphaned state files:

trash .claude/skill-improver.*.local.md

Max iterations reached

The default limit is 20 iterations. If reached:

1. Review remaining issues in state file
2. Manually fix complex issues
3. Restart loop with higher limit:

/skill-improver ./skills/my-skill --max-iterations 30

Rationalizations to Reject

The skill teaches Claude to reject these shortcuts:

Rationalization	Why It’s Wrong
”I’ll just mark it complete and come back later”	Fix issues now, don’t defer
”This minor issue seems wrong, I’ll skip all of them”	Evaluate each individually
”The reviewer is being too strict”	Quality bar exists for a reason
”It’s good enough”	If there are major issues, it’s not good enough

Best Practices

Fix Critical First

Always address critical issues immediately - they block skill loading.

Verify Major Fixes

Run skill-reviewer again after fixing major issues to ensure they’re resolved.

Evaluate Minors

Don’t blindly fix minor issues - evaluate for false positives.

Output Marker

Always output <skill-improvement-complete> when done - it’s the ONLY way to stop the loop.

Related Skills

• Workflow Skill Design - Teaches skill architecture patterns
• Ask Questions If Underspecified - Uses similar iterative refinement approach