Review a proposed Agent Skill for structural validity and content quality before publishing. Runs the skill-validator CLI to check for structural issues, scores the skill with an LLM judge, and interprets results to advise SMEs on what to address. Use when a user wants to review, validate, or quality-check an Agent Skill.
Permissions
Files
SKILL.md
review-skill
Review a proposed Agent Skill for structural validity and content quality before publishing. Runs the skill-validator CLI to check for structural issues, scores the skill with an LLM judge, and interprets results to advise SMEs on what to address. Use when a user wants to review, validate, or quality-check an Agent Skill.
compatibility
Requires skill-validator CLI and claude CLI for LLM scoring. LLM scoring can be skipped for structural-only review.
You are helping an SME review an Agent Skill before publishing. This is a
multi-step process: determine environment, verify prerequisites, run structural
validation, review content, optionally run LLM scoring, and interpret results.
Follow every step in order.
If the state file exists with prereqs_passed: true, offer:
Found saved settings — configured for [full/structural-only] reviews.
Continue with saved settings — skip to Step 2
Re-run prerequisite checks
Change environment — switch between full and structural-only
Option 1: read llm_scoring from the file and skip to Step 2.
Options 2-3: continue below.
If no state file exists, or the user chose to re-check/change, ask:
LLM scoring evaluates content quality across multiple dimensions.
Yes, run LLM scoring — full review with LLM scoring
No, skip LLM scoring — structural validation only
Option 1: set LLM_SCORING=true.
Option 2: set LLM_SCORING=false. Run Step 1a only, then jump to Step 2.
Step 1: Verify Prerequisites
1a. Check for skill-validator binary
skill-validator --version
If not found, search common locations (/usr/local/bin, /opt/homebrew/bin,
~/go/bin). If found but not on PATH, tell the user. If not found anywhere,
follow references/install-skill-validator.md.
If --version is not at least v1.5.1, help the user upgrade with
brew upgrade skill-validator or
go install github.com/agent-ecosystem/skill-validator/cmd/skill-validator@latest.
Do NOT proceed until this succeeds.
1b. Check for claude CLI (LLM scoring only)
If LLM_SCORING=true, verify the Claude CLI is available:
claude --version
If not found, tell the user to install Claude Code:
Ask the user for the path to the skill they want to review, unless they have
already provided it. Verify the path contains a SKILL.md file:
ls <path>/SKILL.md
If SKILL.md does not exist at the given path, tell the user this is not a
valid skill directory and ask them to provide the correct path.
Step 3: Run Structural Validation
Run the full check suite:
skill-validator check <path>
Capture the exit code:
Exit code
Meaning
0
Clean — no errors or warnings
1
Errors found — must fix before publishing
2
Warnings only — review but not blocking
3
CLI/usage error — check the command
Exit 0: proceed. Exit 2: note warnings, proceed. Exit 1: list errors — these
are blocking. The user must fix them before the skill can be published. Do NOT
proceed to LLM scoring if exit code is 1.
Step 4: Content Review
Read the SKILL.md and any reference files, then evaluate each check below.
Report which checks pass and which do not, with specific details on what is
missing.
Check
Criteria
Examples
Does the skill provide examples of expected inputs and outputs?
Edge cases
Does the skill document common edge cases or failure modes?
Scope-gating
Does the skill define when to stop/continue, prerequisites, and conditions for branching paths?
MongoDB data access
If the skill needs MongoDB contextual data, does it instruct agents to use the MCP server for auth and tool calls? Skip if not applicable.
Flag any failing checks as areas the SME should address. These are not blocking
but should be resolved before publishing for best results.
Step 5: LLM Scoring and Interpretation
If LLM_SCORING=false, skip to Step 6.
If LLM_SCORING=true, follow the "Run LLM Scoring" and "Interpret LLM Scores"
sections of
references/llm-scoring.md.
Step 6: Present the Review Summary
If LLM_SCORING=true, follow the "Full Review Summary" section of
references/llm-scoring.md.
Include any failing content review checks from Step 4 in the action items.
If LLM_SCORING=false, present structural result, content review result,
areas to address, and a self-assessment checklist using the scoring dimensions
from assets/report.md. Note that LLM scoring was skipped;
advise re-running with LLM scoring enabled or self-assessing against the report
dimensions.
Example Review Summary Structure
Structure the final summary with these sections in order:
Structural validation — pass/fail with errors or warnings
SKILL.md scores — overall and per-dimension table
Reference scores — per-file table with overall and lowest dimension
Novelty assessment — mean novelty vs threshold of 3; list novel_info
per file for SME verification
Action items — prioritized list of what to fix
Recommendation — ready to publish / minor revisions / significant rework
