| name | skill-reviewer |
| description | Use when reviewing, auditing, or about to publish a Claude / Agent Skill (SKILL.md plus any supporting files) to verify it follows the Agent Skills specification and Anthropic's authoring best practices. Triggers on phrases like "review this skill", "is my skill ready", "lint my SKILL.md", "audit before publishing", or before merging skill PRs. |
| license | MIT |
Skill Reviewer
Audits a skill directory against the cross-vendor Agent Skills specification and Anthropic's published authoring best practices. Reports hard violations (errors), strong recommendations (warnings), and stylistic suggestions (info).
When to use
- A skill is being prepared for publication, sharing, or PR merge.
- A skill misbehaves at runtime — discovery fails, body is skipped, scripts break.
- A skill is being ported between profiles (cross-vendor spec ↔ Claude Code superset).
- Reviewing a third-party skill before installing it.
Do NOT use for unrelated code review, generic markdown linting, or as a substitute for runtime evaluation (use the skill-creator benchmarking tools for that).
Two profiles
| Profile | Frontmatter fields | Use when |
|---|
spec (strict) | The 6 cross-vendor fields only: name, description, license, allowed-tools, metadata, compatibility | Publishing to a vendor-neutral registry, or when targeting non-Claude agents |
claude-code (default) | The 6 above plus Claude-Code-recognised extensions (when_to_use, disable-model-invocation, paths, hooks, model, argument-hint, arguments, effort, agent, shell) | Skill lives under ~/.claude/skills/ or a Claude Code plugin |
The validator auto-detects the profile from the skill's path (anything under .claude/skills/ is claude-code); override with --profile=spec.
Workflow
- Locate the skill root. Confirm with the user which directory to audit. The path must be a directory containing
SKILL.md.
- Run the validator to gather all machine-checkable findings:
python3 scripts/validate.py <path-to-skill> [--profile=spec|claude-code] [--json]
Exit code is 0 when there are no errors, 1 otherwise. JSON mode emits a structured report for piping into other tools.
- Read the findings the validator produced. Each finding has an ID (e.g.
F-007), severity, message, and a one-line citation pointing at the rule's source.
- Apply judgment to remaining concerns the validator can't fully decide:
- Description quality: is it specific and discoverable, or vague? (See
references/anti-patterns.md §1.)
- Workflow clarity: are there concrete examples, or only abstractions?
- Reference depth: do supporting files exceed one level of indirection?
- Token budget: does the body realistically deserve its size, or could it be split?
- Report to the user. Group findings by severity. For each issue, state the rule, the location (file + line), and the minimal fix. Cite the rule ID so the user can look it up in
references/rules.md.
- Do not auto-fix without explicit user permission — many findings are stylistic and the user owns the call.
What the validator checks
The validator implements 45 rules drawn from the Agent Skills spec, the official skills-ref reference validator, Anthropic's platform documentation, and Claude Code documentation. Full table with citations: references/rules.md.
Highlights:
- Hard rules (errors): SKILL.md exists; YAML frontmatter is well-formed and closed;
name matches the directory after NFKC normalisation, is 1-64 chars, lowercase, no leading/trailing/consecutive hyphens, alphanumeric-or-hyphen only; description is present, non-empty, ≤1024 chars; compatibility ≤500 chars; no XML tags or reserved words (anthropic, claude) in name/description on Anthropic platforms.
- Warnings:
SKILL.md body >500 lines or >5000 tokens; first/second-person description; description summarises workflow; vague description; reference files >1 level deep; reference files >100 lines without ToC; Windows-style paths; time-sensitive content outside an "old patterns" section; voodoo constants in scripts; broken file references; multi-language example dilution; unmodified template body.
- Info-level: description is short (<60 chars); name is generic (
helper, utils, tools); no concrete examples found; MCP tool reference not fully qualified.
Common mistakes the reviewer catches
| Pattern | Why it fails |
|---|
description: I can help you process Excel files | First-person; injected into system prompt and harms discovery (PLAT-BP) |
description: Use when X — runs script Y, then formats Z, then writes W | Workflow summary lets Claude shortcut past the body (SUPERPOWERS empirical finding) |
description: Helps with documents | Too vague to compete with other skills for invocation |
name: My_Skill | Underscores and uppercase are rejected by the spec validator |
Referencing scripts\helper.py | Backslash paths break on macOS/Linux Claude clients |
TIMEOUT = 47 # ? | Voodoo constants — every magic number needs a why-comment |
SKILL.md re-using the unmodified template body | Skill was never actually written; heuristic catches "Insert instructions below"-style markers |
Quick reference
| Need | Path |
|---|
| Run all checks | scripts/validate.py <skill> |
| Full rule table with citations | references/rules.md |
| Anti-pattern bad/good gallery | references/anti-patterns.md |
| Distilled spec summary | references/spec-summary.md |
| New-skill scaffolding template | templates/SKILL.md.template |
Output contract
A review reports:
- Errors — must-fix before publishing (spec violations).
- Warnings — strong best-practice violations; recommend fixing.
- Info — stylistic suggestions; user decides.
- Stats — line count, estimated token count, file count, profile used.
- Verdict —
READY, READY WITH WARNINGS, or NOT READY.
When delivering the review verbally, lead with the verdict, then enumerate errors, then warnings, then optional info. Cite rule IDs (F-NNN) for traceability.
