Refine Claude Skills with Automated Quality Assurance

Skill Improvement Methodology iteratively improves a Claude Code skill by repeatedly calling the skill-reviewer agent from the plugin-dev plugin, fixing what it flags, and re-reviewing until the skill meets quality standards - a five-step core loop: review, categorize issues by severity, fix critical and major issues, evaluate minor issues for validity before fixing, and repeat.

Use this when improving a skill with multiple quality issues, iterating on a new skill until it meets standards, running automated fix-review cycles instead of manual editing, or enforcing consistent quality across skills. Skip it for a one-time review (use /skill-reviewer directly), a quick single fix (edit the file directly), non-skill files (it only works on SKILL.md files), or experimental skills still being explored, where manual iteration gives more control.

Issues are triaged into three tiers. Critical issues must be fixed immediately since they block loading or cause runtime failures: missing required frontmatter fields like name or description, invalid YAML syntax, referenced files that don't exist, or broken file paths. Major issues must also be fixed since they significantly degrade effectiveness: weak or vague trigger descriptions, second-person "you" voice instead of imperative, a SKILL.md over 500 lines without splitting into references/, missing "When to Use"/"When NOT to Use" sections, or a description that doesn't specify when to trigger. Minor issues get evaluated before fixing - is it a genuine improvement, could it be a false positive, would it actually help Claude use the skill - since the reviewer can produce false positives on subjective style preferences or "nice to have" polish. It requires the plugin-dev plugin, verified with /plugins, and invokes skill-reviewer by asking Claude to review the skill at an absolute path and categorize issues by severity.

Completion is gated on an explicit marker, <skill-improvement-complete>, output only when skill-reviewer reports a pass or no issues, all critical/major issues are fixed and verified by re-running the reviewer, or remaining issues are minor and have been evaluated as false positives or not worth fixing - natural-language statements like "looks good" or "quality bar met" do not stop the loop, since the stop hook checks for the marker alone. A worked example shows iteration 1 flagging a missing frontmatter name field (critical), a second-person description (major), and a missing "When NOT to Use" section (major), all fixed; iteration 2 flags only a verbose line, which is evaluated and skipped as not worth changing before the marker is output.

Anyone maintaining Claude Code skills who wants automated, standards-based quality enforcement instead of manual review cycles, guided against four specific rationalizations: marking a skill complete to "come back later," skipping all minor issues because one seems wrong, dismissing the reviewer as "too strict," or calling a skill "good enough" while major issues remain.