Purpose

It performs hard validation of required frontmatter rules and a best-practices review of the SKILL content. It outputs a checklist-style report suitable for pasting into a PR comment.

When to use

• You're creating or modifying a skill and want a consistent quality review.

• You want to validate naming/description conventions and catch issues early.

Example - How to invoke

Ask the agent to run this skill and provide the target path, for example:

• "Use skill-reviewer to review skills/<skill-name>/SKILL.md ."

• "Review skills/<skill-name>/SKILL.md and display the checklist report."

Inputs

• targetSkillMdPath (required): repository-relative path to the skill's SKILL.md (e.g., skills/my-skill/SKILL.md ).

Output

• A checklist-style report.

• Each checklist item has:

• status : pass | can improve | fail

• severity : high | medium | low

• For any can improve or fail : a brief, actionable suggestion.

Scope and constraints

• Only review SKILL.md files within this repository.

• DO NOT create or modify files unless the user explicitly asks.

Scoring guidance

• Only high-severity items may be marked fail . All other issues should be can improve .

• If any high-severity item is fail , the overall result must be ❌ NEEDS_CHANGES .

• Otherwise the overall result should be ✅ PASS .

Checklist items to output

Output only the checklist items that are not pass (i.e., can improve or fail ), and include the evidence for each item. Sort items by severity (high → medium → low) and then by type (fail before can improve ).

For example:

[fail] (high) Frontmatter is missing

• Evidence: No YAML block at the top of the file.

[can improve] (medium) Description explains what + when to use

• Suggestion: Description should also explain when to use the skill, not just what it does.

Hard validations checklist (high severity)

• Frontmatter exists and parses as YAML.

• Frontmatter has name (string).

• Frontmatter has description (string).

• name matches parent directory name.

• name is unique in **/SKILL.md .

• name length ≤ 64.

• name matches ^[a-z0-9-]+$ .

• name contains no XML tags.

• name contains no reserved words (anthropic , claude ).

• description is non-empty.

• description length ≤ 1024.

• description contains no XML tags.

• Referenced files (if any) exist and are within the repository, unless they reference node_modules.

Best practices checklist (low/medium severity - never fail)

• Description is under 400 lines. (low)

• Examples, if present, are concrete. (low)

• Workflows, if present, have ordered steps. (low)

• File references are one level deep where practical. (low)

• Description explains what + when to use. (medium)

• Description is specific and includes key terms. (medium)

• Heading hierarchy is logical. (medium)

• Description uses progressive disclosure for complex topics, and details live in supporting files. (medium)

• Prefer scripts stored as separate files (e.g., scripts/ ) rather than embedded long code blocks. (medium)

• Validation/verification steps exist for critical operations. (medium)

• Terminology is consistent throughout (same term used for same concept). (medium)

• Avoid extraneous docs (README/INSTALLATION_GUIDE/etc). (medium)

• No Windows-style paths in examples. (medium)

• No unexplained "magic constants" in instructions or code snippets; values are named or justified. (medium)

• Any required packages/tools are listed and there is a quick verification step. (medium)

Report format (copy/paste friendly)

Produce the report in this exact general structure:

Skill review:

Summary

• Result: <PASS | NEEDS_CHANGES>

• Fail (high):

• Can improve:

Checklist

• [<pass|can improve|fail>] (<high|medium|low>)

• Evidence: <short, specific observation>

• Suggestion: <only for can improve / fail>

When citing evidence, prefer short excerpts, avoid dumping large chunks of the SKILL content.