Iteratively reviews and fixes Claude Code skill quality issues until they meet standards. Runs automated fix-review cycles using the skill-reviewer agent. Use to fix skill quality issues, improve skill descriptions, run automated skill review loops, or iteratively refine a
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/skill-improver
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Iteratively reviews and fixes Claude Code skill quality issues until they meet standards. Runs automated fix-review cycles using the skill-reviewer agent. Use to fix skill quality issues, improve skill descriptions, run automated skill review loops, or iteratively refine a
📊 Stats
Stars6,228
Forks540
LanguagePython
LicenseCC-BY-SA-4.0
📦 Ships with trailofbits-skills
</> SKILL.md
skill-improver.SKILL.md
---name: skill-improver
description: "Iteratively reviews and fixes Claude Code skill quality issues until they meet standards. Runs automated fix-review cycles using the skill-reviewer agent. Use to fix skill quality issues, improve skill descriptions, run automated skill review loops, or iteratively refine a skill. Triggers on 'fix my skill', 'improve skill quality', 'skill improvement loop'. NOT for one-time reviews—use /skill-reviewer directly."
allowed-tools: Task Read Edit Write Glob Grep
---# Skill Improvement Methodology
Iteratively improve a Claude Code skill using the skill-reviewer agent until it meets quality standards.
## Prerequisites
Requires the `plugin-dev` plugin which provides the `skill-reviewer` agent.
Verify it's enabled: run `/plugins` — `plugin-dev` should appear in the list. If missing, install from the Trail of Bits plugin repository.
## Core Loop
1. **Review** - Call skill-reviewer on the target skill
2. **Categorize** - Parse issues by severity
3. **Fix** - Address critical and major issues
4. **Evaluate** - Check minor issues for validity before fixing
5. **Repeat** - Continue until quality bar is met
## When to Use
- Improving a skill with multiple quality issues
- Iterating on a new skill until it meets standards
- Automated fix-review cycles instead of manual editing
- Referenced files that don't exist — Runtime errors when Claude follows links
- Broken file paths — Same as above, leads to tool failures
### Major Issues (MUST fix)
These significantly degrade skill effectiveness:
- Weak or vague trigger descriptions — Claude may not recognize when to use the skill
- Wrong writing voice (second person "you" instead of imperative) — Inconsistent with Claude's execution model
- SKILL.md exceeds 500 lines without using references/ — Overloads context, reduces comprehension
- Missing "When to Use" or "When NOT to Use" sections — Required by project quality 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 — Reviewer may have different taste than author
- Optional enhancements — May add complexity without proportional value
- "Nice to have" improvements — Consider cost-benefit before implementing
- Formatting suggestions — Often valid but low impact
## Minor Issue Evaluation
Before implementing any minor issue fix, evaluate:
1. **Is this a genuine improvement?** - Does it add real value or just satisfy a preference?
2. **Could this be a false positive?** - Is the reviewer misunderstanding context?
3. **Would this actually help Claude use the skill?** - Focus on functional improvements
Only implement minor fixes that are clearly beneficial. Skill-reviewer may produce false positives.
## Invoking skill-reviewer
Use the skill-reviewer agent from the plugin-dev plugin. Request a review by asking Claude to:
> Review the skill at [SKILL_PATH] using the plugin-dev:skill-reviewer agent. Provide a detailed quality assessment with issues categorized by severity.
Replace `[SKILL_PATH]` with the absolute path to the skill directory (e.g., `/path/to/plugins/my-plugin/skills/my-skill`).
## Example Fix Cycle
**Iteration 1 — skill-reviewer output:**
```text
Critical: SKILL.md:1 - Missing required 'name' field in frontmatter
Major: SKILL.md:3 - Description uses second person ("you should use")
Major: Missing "When NOT to Use" section
Minor: Line 45 is verbose
```
**Fixes applied:**
- Added name field to frontmatter
- Rewrote description in third person
- Added "When NOT to Use" section
**Iteration 2 — run skill-reviewer again to verify fixes:**
```text
Minor: Line 45 is verbose
```
**Minor issue evaluation:**
Line 45 communicates effectively as-is. The verbosity provides useful context. Skip.
**All critical/major issues resolved. Output the completion marker:**
```
<skill-improvement-complete>
```
Note: The marker MUST appear in the output. Statements like "quality bar met" or "looks good" will NOT stop the loop.
## Completion Criteria
**CRITICAL**: The stop hook ONLY checks for the explicit marker below. No other signal will terminate the loop.
