review-skill

This skill reviews and fixes other skills — identifying issues and applying corrections with developer approval at each stage.

Stop after each stage and have changes reviewed with the user.

Note: The agent checks skills against conventions and best practices, then proposes fixes. The developer approves before changes are applied. When uncertain about intent, ask — don't assume.

1. •

   Read and understand the skill (agent proposes, developer confirms)

   • •Read the target SKILL.md at $ARGUMENTS (and any supporting files in the directory)
   • •Summarize: what does this skill do, when is it invoked, and what workflow does it follow?
   • •Confirm understanding before proceeding to review
2. •

   Frontmatter review (agent reviews, then fixes with developer approval)

   Check that frontmatter is well-formed and follows conventions:

   • •Is name kebab-case and does it match the directory name?
   • •Is description present, specific enough to trigger correctly, and does it include when-to-use context?
   • •Are invocation control fields appropriate for the skill's purpose?
     • •Side-effect workflows should use disable-model-invocation: true
     • •Background knowledge should use user-invocable: false
   • •Is allowed-tools set if the skill should restrict tool access?
   • •Are context/agent set appropriately if the skill runs in isolation?
   • •Are there unknown or misspelled frontmatter fields?

   Report findings as a checklist: pass / issue / suggestion. Then apply fixes for any issues, with developer approval.

3. •

   Prompt structure review (agent reviews, then fixes with developer approval)

   Check the prompt body for structural quality:

   • •Does it have a stop-after-each-stage instruction if it's a multi-stage workflow?
   • •Is there a Stage 0 for understanding/confirmation before doing work?
   • •Are agent vs developer responsibilities clear at each stage?
   • •Does it use questions to guide analysis, not just imperatives?
   • •Is the skill under 500 lines? Does it reference supporting files for detail rather than inlining everything?
   • •Is the stage numbering consistent and logical?

   Report findings as a checklist: pass / issue / suggestion. Then apply fixes for any issues, with developer approval.

4. •

   Effectiveness review (agent reviews, then fixes with developer approval)

   Check that the skill will work well in practice:

   • •Are instructions unambiguous — will Claude interpret them correctly?
   • •Is the scope right-sized? (Not trying to do too much in one skill)
   • •Are $ARGUMENTS, $0, $1 used correctly if present?
   • •Is dynamic context (exclamation-mark backtick syntax) used correctly if present?
   • •Are supporting files referenced from SKILL.md?
   • •Check for anti-patterns:
     • •Overly broad or narrow description
     • •No review pauses in a multi-stage workflow
     • •Unreferenced supporting files in the directory
     • •Task instructions in a skill with no context: fork and no clear action

   Report findings as a checklist: pass / issue / suggestion. Then apply fixes for any issues, with developer approval.

5. •

   Alignment review (agent reviews, then fixes with developer approval)

   If the skill is intended for this repo's skill library, check alignment with existing skills:

   • •Consistent formatting with other skills in the repo?
     • •Blockquotes for philosophy notes
     • •Bold for stage titles
     • •Tables for comparisons
   • •Includes "When to use this vs other skills" if it overlaps with existing skills?
   • •Follows the composition model (flesh-out -> review-steps -> strong-edit -> agent-optimize)?
   • •Has a responsibilities.md if it's a multi-stage workflow with mixed agent/developer ownership?

   If the skill is standalone (not for this repo), skip repo-specific alignment checks and note this.

   Report findings as a checklist: pass / issue / suggestion. Then apply fixes for any issues, with developer approval.

6. •

   Summary and recommendations (agent leads)

   Provide a final summary:

   • •Overall quality assessment (ready to use / needs minor fixes / needs rework)
   • •Top 3 issues to address (if any)
   • •Top 3 strengths (what the skill does well)
   • •Recommendation: publish / revise / rethink

When to Use This vs Other Skills