skill-reviewer

Skill Reviewer

Review Claude Skills against Anthropic's official Best Practices checklist and the writing rules distilled in How to write good Claude skills.md.

What to review

This skill supports two input modes:

1. Skill directory path — Read SKILL.md, scan scripts/, references/,

templates/ subdirectories; check file structure, naming, path depth, forward-slash paths.

1. Pasted SKILL.md text — Review the text-only content. Note that

structural checks (#3 lines, #8 nesting depth, #15 file documentation, #16 forward-slash paths) will be limited or skipped.

Review process

Phase 1 — Gather

If given a directory path:

1. ls -R <skill-dir>/ to understand the file structure.
2. Read SKILL.md.
3. Skim executable files in scripts/ (check docs, error handling, voodoo constants).
4. Note file nesting depth, path style, and any auxiliary files.

If given pasted text:

1. Read the full text.
2. Note that structural checks will be marked SKIPPED (no directory).

Phase 1.5 — Optional calibration example

If the user is new to this skill or asks what a good report looks like, review evals/medium-skill-example/ first and compare the output with evals/medium-skill-example/expected-report.md. Use that example only for calibration; do not include it in the user's report unless asked.

Phase 2 — Audit (22 items)

Go through every item below. For each, record: PASS, FAIL, SKIPPED (reason), or N/A. For deeper context on why an item matters and the additional features/anti-patterns not in this checklist, see references/writing-good-skills.md.

Phase 3 — Produce the report

Output a structured report in two parts.

Group failures by severity:

• •Critical (must fix before sharing): description absent or useless, body >500 lines, path backslashes, no error handling, scripts punt to Claude.
• •Important (should fix): inconsistent terminology, weak examples, missing prerequisites, no documentation on scripts, no verification steps.
• •Minor (nice to fix): slightly long body (400-500 lines), off-by-a-few chars in frontmatter, ok-but-vague example.

For each issue, cite the item #, the specific file:line, a clear description, and a concrete fix suggestion.

### Critical

- **[#3] SKILL.md:87** — Body is 523 lines (limit: 500). The "Migration guide"
  section (lines 210-310) can be moved to `references/migration.md`.

A table with every item, result, and brief note.

| # | Category | Item | Result | Note |
|---|----------|------|--------|------|
| 1 | Core | Description specific + key terms | ✅ PASS | "Creates branded PDF reports from markdown — use when..." |
| 2 | Core | Description what + when | ❌ FAIL | Describes what but not when |
| 3 | Core | Body < 500 lines | ❌ FAIL | 523 lines |
| ... | ... | ... | ... | ... |

End the report with a summary:

• •Pass rate: X/22 (Y PASS, Z FAIL, W SKIPPED)
• •Gating recommendation:

- Clear for personal use / Ready for team share / Ready for public distribution (per the tier table below), or - Not ready with specific blocking items

Phase 4 — Self-check before delivery

Before showing the report to the user, run this four-point self-assessment. A review skill that mis-judges items wastes the user's time more than no review at all, so this step is non-optional.

1. Specificity — Every FAIL cites a concrete location: file path,

line number, or a quoted snippet from the source. Vague verdicts like "description is unclear" are not acceptable. Either point to the exact phrase, or downgrade the verdict to a question for the user.

1. Completeness — All 22 items appear in Part B with a verdict. None

silently dropped. SKIPPED and N/A are valid verdicts, but they must carry a one-line reason.

1. Spot-check accuracy — Pick 2 FAIL entries at random and re-verify

the cited evidence really exists in the source. If you cannot find it, the FAIL is wrong; remove or revise it before delivering.

1. Tier consistency — The gating recommendation matches the actual

results. Marking "Ready for team share" while #19 (evals) shows FAIL is inconsistent — fix one or the other.

End the report with one literal line: Self-check passed. If any of the four checks triggered a fix, briefly note what changed (e.g., "Self-check: removed unverifiable FAIL on #6; recounted summary").

Complete example

Input:

Please use skill-reviewer to check evals/medium-skill-example/

Expected behavior:

1. Read evals/medium-skill-example/SKILL.md.
2. Check directory structure and note that no executable script is present.
3. Produce Part A findings for the weak abstract examples, vague errors,

undocumented constants, and missing test evidence.

1. Produce Part B with all 22 checklist rows.
2. Recommend Clear for personal use, then end with Self-check passed.

The expected report for this example lives at evals/medium-skill-example/expected-report.md.

Sharing-tier gating

Maintaining this skill

Regression cases live in evals/. After changing this checklist, report format, or severity guidance:

1. Review evals/good-skill-example/,

evals/medium-skill-example/, and evals/bad-skill-example/.

1. Compare each report against its expected-report.md.
2. Record the run in evals/results.md, including model, date, pass/fail,

and any reviewer feedback.

1. Update expected reports if the rule change intentionally changes the output.

References

Working reference (used during audits)

• •references/writing-good-skills.md —

Distilled cross-comparison reference (267 lines, checklist format). Use during audits as a lookup table. Contains the "description as routing signal" insight, 5 additional features (F-23 to F-27), and 11 additional anti-patterns (AP-10 to AP-20) that extend this checklist.

Narrative docs (background reading, in docs/)

• •docs/how-to-write-good-claude-skills.md —

Full English narrative (~490 lines) — the source material that references/writing-good-skills.md distills. Read this for background on skill design methodology, not during audits.

Upstream sources (in docs/)

• •docs/Skill authoring best practices.md —

Anthropic's official 1111-line guide. The 22-item checklist in this SKILL.md is distilled from this document.

• •docs/Introduction to Claude Skills.md —

Anthropic Cookbook, 834 lines. The [S] (source) claims in how-to-write-good-claude-skills.md are quoted from this.

• •Anthropic official: Skill authoring best practices —

Same official guide, online URL. Use the local copy for offline work.