From skill-reviewer
Reviews SKILL.md files against Anthropic's official Claude Code skill authoring best practices. Use when the user asks to review, audit, score, or check the quality of a SKILL.md file specifically — not CLAUDE.md, commands, or general markdown. Use when the user says "review my skill", "audit this skill", "check skill quality", "score my SKILL.md", or "does this skill follow best practices".
How this skill is triggered — by the user, by Claude, or both
Slash command
/skill-reviewer:reviewing-skillsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Performs a structured, scored audit of SKILL.md files against Anthropic's official Claude Code skill authoring best practices. Produces a scored report across 5 quality dimensions and optionally generates a corrected version.
Performs a structured, scored audit of SKILL.md files against Anthropic's official Claude Code skill authoring best practices. Produces a scored report across 5 quality dimensions and optionally generates a corrected version.
Follow these steps exactly.
Determine which SKILL.md file to audit:
Do NOT use $ARGUMENTS or $PWD — these variables are only available in commands, not skills.
Read the target file and record:
| Metric | Value |
|---|---|
| Total lines | Count all lines |
| Word count | Count words in body (after closing ---) |
| Frontmatter fields present | name, description, and any extras |
| Body lines | Lines after closing --- |
| Reference files detected | Any references/ paths mentioned or present in skill folder |
| Folder structure | Check for scripts/, references/, assets/ subdirectories |
| Design pattern | Identify: Sequential, Orchestrator, Iterative, Adaptive, or none |
Note the presence or absence of:
---)name: fielddescription: fieldSKILL.md)Default: Use references/best-practices.md (static, always available).
Fetch live from platform docs when user says:
Live fetch URL:
https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
If live fetch fails: fall back to references/best-practices.md silently and note the failure in the audit output under a "Guidelines Source" line.
Compare the current SKILL.md against its last committed version to detect breaking changes and regressions.
Skip entirely if any of the following are true:
git rev-parse --git-dir returns non-zero)git log --oneline -- <path> returns no output)If not skipped, run in order:
git ls-files --full-name <path-to-SKILL.md>
git show HEAD:<git-relative-path>
If this fails (file renamed, untracked, or path error): skip and note "No previous version found — file may have been renamed" in report. Do NOT attempt git log --follow; surface the limitation and move on.What to compare: See references/audit-steps.md — Regression Risk section.
Output: A Regression Risk section in the audit report, appended after the Scores table and before the Grade line. Does not affect any dimension score.
Continue with references/audit-steps.md for:
Use this for rapid pre-audit assessment:
Frontmatter
---) present and matchingname: field present, ≤64 chars, lowercase + numbers + hyphens onlyname: does not contain anthropic or claude as substringdescription: field present, ≤1024 charsBody
\)Structure
SKILL.md (case-sensitive)references/sub/file.md)Design Pattern
Scripts (apply if skill contains a scripts/ folder or has bash/python code blocks with external tool invocations)
ServerName:tool_name formatDiscoverability
Regression Risk (skip if not in git, file is new, or user opts out)
name: field unchanged (BREAKING if changed)description: trigger phrases preserved (BREAKING if any removed)description: activation intent preserved (WARNING if Use when... clause or ≥3 domain keywords absent vs. previous)references/ path disappeared)npx claudepluginhub shawn-sandy/agentics --plugin skill-reviewerValidates SKILL.md files against the agentskills specification. Catches structural, semantic, and naming issues before publishing.
Reviews SKILL.md files against best practices with structured pass/fail reports, warnings, errors, and prioritized recommendations before publishing or deploying.
Validates SKILL.md files against the agentskills.io standard, checking YAML frontmatter, required sections, line count limits, procedure format, and registry sync. Use before merging new or modified skills.