Skill Reviewer

Skill Reviewer

Review a SKILL.md file for structural quality, completeness, and template compliance. Grades on 8 dimensions covering the canonical skill structure (see .claude/skills/_schema/SKILL.template.md + .claude/skills/_schema/AUTHORING.md). Used to catch drift before a skill ships.

This is a meta-skill — it reviews skill definitions, not skill outputs.

Claude Code Triggers

Invoke this skill when:

• "review skill [name]"
• "audit [skill-name] skill"
• "is [skill] well-defined?"
• "check skill quality for [skill]"
• "grade this SKILL.md"

Do NOT invoke when:

• User wants to review content output quality → use /voice-reviewer instead
• User wants to check the skill catalog → use /skill-catalog instead
• User wants to build a new skill from scratch → use prompt-design instead

Input Requirements

Required inputs

Optional inputs (improve quality)

Input validation checklist

Before proceeding, verify:

• SKILL.md file exists and is readable
• File contains YAML frontmatter (between --- delimiters)

If file doesn't exist: Tell the user the path is invalid and ask for the correct one.

Process (step-by-step)

Phase 1: Read and parse

Purpose: Load the SKILL.md and extract structural elements.

Steps:

1. Step 1.1: Read the file
   • Load the full SKILL.md content
   • Parse YAML frontmatter into key-value pairs
   • Identify all H2 (##) and H3 (###) sections present
   • Output: Parsed frontmatter + section inventory

Phase 1 checkpoint:

• File successfully read
• Frontmatter parsed
• Section headers cataloged

Phase 2: Grade each dimension

Purpose: Evaluate the skill against 8 quality dimensions.

Steps:

1. Dimension 1: Frontmatter completeness

   • Check for required fields: name, version, author, last_updated, description
   • Check for agentic fields: dependencies, outputs, triggers, review_gate
   • PASS: All required + agentic fields present with non-empty values
   • WARN: Required fields present but agentic fields missing
   • FAIL: Any required field missing

2. Dimension 2: Trigger quality

   • Check for ## Claude Code Triggers section
   • Count "Invoke this skill when" trigger phrases
   • Check for "Do NOT invoke when" anti-triggers
   • PASS: 4+ trigger phrases AND 2+ anti-triggers
   • WARN: 2-3 trigger phrases OR only 1 anti-trigger
   • FAIL: Missing section OR fewer than 2 triggers OR no anti-triggers

3. Dimension 3: Input definition

   • Check for ## Input Requirements section
   • Look for separation between Required and Optional inputs
   • Look for Input Validation Checklist
   • Look for "If inputs are missing" handling
   • PASS: All four elements present
   • WARN: Required/Optional separated but no validation checklist
   • FAIL: Missing section OR no input/output distinction

4. Dimension 4: Process structure

   • Check for ## Process section with named phases
   • Each phase should have: Purpose, Steps, Checkpoint
   • Count phases (minimum 2 expected)
   • PASS: 2+ phases, each with purpose + steps + checkpoint
   • WARN: Phases present but missing checkpoints
   • FAIL: No process section OR only 1 phase OR no steps

5. Dimension 5: Anti-hallucination guardrails

   • Check for ## Anti-Hallucination Guardrails section
   • Count guardrails listed
   • Check if guardrails are skill-specific (not generic copy-paste)
   • Look for placeholder format definition
   • PASS: 3+ skill-specific guardrails + placeholder format
   • WARN: 1-2 guardrails OR guardrails are generic
   • FAIL: Missing section OR zero guardrails

6. Dimension 6: Output format

   • Check for ## Output Format section
   • Look for output structure definition (headers, formatting rules)
   • For copy skills: check for character count requirements
   • For analytical / data-verdict skills (audit, scoring, ranking, reporting): check for a report-format contract — a named output structure, a literal comparable template on recurring deliverables, and a bound significance floor (quantitative-evidence-floors.md: verdict states the volume behind it, synthesizes rather than dumping rows). WARN if the skill renders verdicts from counts but ships no floor or comparable format.
   • PASS: Clear output structure with formatting rules
   • WARN: Section exists but structure is vague
   • FAIL: Missing section

7. Dimension 7: Quality checklist

   • Check for ## Quality Checklist section
   • Look for subsections: Content Quality, Format Quality, Completeness
   • Count checklist items
   • PASS: 3 subsections with 3+ items each
   • WARN: Checklist exists but fewer than 3 subsections
   • FAIL: Missing section OR fewer than 3 total items

8. Dimension 8: Skill-catalog alignment

   • Read .claude/skills/meta/catalog/skill-catalog/SKILL.md
   • Check if this skill name appears in the catalog
   • If listed: check review_gate in SKILL.md matches catalog entry
   • Check if dependencies listed match skill's Input Requirements
   • PASS: Skill registered in catalog with matching metadata
   • WARN: Skill registered but metadata doesn't match
   • FAIL: Skill not found in catalog

Phase 2 checkpoint:

• All 8 dimensions scored
• Each score has a specific finding (not just PASS/FAIL)
• Senior-engineer test: would a senior engineer say this skill is overcomplicated? If yes, flag for slim refactor regardless of dimension scores.

Phase 3: Generate report

Purpose: Compile the review into a structured report.

Steps:

1. Step 3.1: Calculate overall score

   • Count PASS, WARN, FAIL across all 8 dimensions
   • Overall verdict: ALL PASS = "Ready to ship", any FAIL = "Needs fixes", all WARN or better = "Acceptable with notes"
   • Output: Score summary

2. Step 3.2: Write the report

   • Follow the output format below
   • List critical issues (FAIL) first, then warnings
   • Include specific recommendations for each issue
   • Output: Complete review report

Skill Review: [skill-name]

Date: YYYY-MM-DD File: [path to SKILL.md] Verdict: [Ready to ship | Acceptable with notes | Needs fixes]

Score: X PASS / Y WARN / Z FAIL

Critical issues (FAIL)

[Details on each FAIL with specific line references and fix instructions]

Warnings (WARN)

[Details on each WARN with improvement suggestions]

Recommended updates

1. [Specific action to take]
2. [Specific action to take]

---

## Anti-Hallucination Guardrails

1. **Only report what's actually in the file:** Do not assume a section exists if you can't find the header. Grep for the exact header text.
2. **Count explicitly:** When reporting "4 trigger phrases found," list them. Don't approximate.
3. **Quote the file:** When flagging an issue, reference the specific line or section where the problem is.
4. **Don't invent recommendations from outside context:** Recommendations must be based on what the canonical template (`.claude/skills/_schema/SKILL.template.md`) + `AUTHORING.md` require, not general best practices.

---

## Quality Checklist (pre-delivery)

### Content quality
- [ ] All 8 dimensions actually evaluated (not skipped)
- [ ] Each finding references specific evidence from the file
- [ ] Recommendations are actionable (not vague "improve this")

### Format quality
- [ ] Score table formatted correctly
- [ ] FAIL items listed before WARN items
- [ ] Verdict matches score (no FAIL = "Ready to ship" is wrong if there are FAILs)

### Completeness
- [ ] Overall score calculated correctly
- [ ] All critical issues have fix instructions
- [ ] Report includes the file path reviewed

---