Skill reviewer

Skill Reviewer

Review a named Claude skill for skill smells (authoring anti-patterns that empirical research found in over 99% of real skills) and best-practice violations, report the findings, offer to fix them, and then learn from the run.

Skills are written once and reused thousands of times, and research shows the weakest parts — error handling, guardrails, when-to-ask-the-human — are almost never revised after the first draft. So a careful first-pass review has outsized value: a smell caught now is a smell that would otherwise ride along through every future copy and edit. That is the point of this skill.

Input

The user names a skill to review (e.g. find-invoices, or a path). If they don't name one, ask which skill. Do not invent one.

Knowledge base (read these first)

Before reviewing, read both reference files — they hold the substance:

• references/skill-smells.md — the full catalogue of named smells, grouped by theme, each with what it is, how to detect it, its severity, and the fix. This is your checklist; the authoritative smell count lives in that file, not here.
• references/best-practices.md — what "good" looks like: Anthropic's authoring rules, the SKILL.md content taxonomy, the behavioural-contract principle, and complementary agent-instruction principles.

Read references/report-template.md when you reach the reporting step.

Workflow

Step 1 — Locate and read the target skill

Resolve the named skill to a directory (or a command file), checking in this order and using the first match:

1. ~/.claude/skills/<name>/
2. <current-repo>/.claude/skills/<name>/
3. <current-repo>/.claude/commands/<name>.md or ~/.claude/commands/<name>.md — a slash command; review it too, adapting the frontmatter rules to the command format (a command's frontmatter is description + argument-hint for /help discoverability, not skill triggering — its absence is a low-severity hygiene finding, not CSD proper).
4. A path the user gave directly.

Read its SKILL.md in full, and list its bundled files (scripts/, references/, assets/). Skim bundled files enough to judge whether detail is delegated well (see the Undelegated Detail and Missing Utility Script smells). If you cannot find the skill, say so and ask the user for the path rather than guessing — reviewing the wrong file wastes their time.

Step 2 — Load the knowledge base

Read references/skill-smells.md and references/best-practices.md now (if you have not already). Hold the smell checklist and the frontmatter hard-rules in mind for the passes below.

Step 3 — Detect skill smells

Walk the full smell checklist in references/skill-smells.md — every smell, no sampling. For each smell, decide present / absent / not-applicable, and record evidence:

• For a presence smell (e.g. XML in description), quote the offending line.
• For an absence smell (e.g. No Validation Step, Never Asks Human), state what is missing and where you looked.

Do not pad the list. A smell you cannot evidence is not a finding. It is normal for a decent skill to have only a handful; it is also normal — per the research — for most skills to carry several. Report what you actually find.

Step 4 — Assess best-practice and taxonomy coverage

Using references/best-practices.md:

• Frontmatter hard-rules: run the bundled checker for the mechanical measurements instead of eyeballing them:

  node <skill-dir>/scripts/check-hard-rules.mjs <path-to-SKILL.md>
  

  It measures name/description lengths, kebab-case, angle brackets, body size, backslash paths, and a stray README.md. Judge the qualitative rules yourself: description in third person, states both what it does and when to use it, includes realistic trigger phrases. Flag each violation (these also map to specific smells).
• Content-taxonomy coverage: which of the six content categories are present vs thin. Pay special attention to Ensuring output quality and User/Agent coordination — research shows these are the least-revised parts of a skill, so a gap here is unlikely to ever be fixed later and deserves a callout now.
• Behavioural contract: how the skill handles user interaction, state, and error recovery. Weakness here is inherited silently by every copy.
• Project-rule cross-check: read the repo's own instructions (CLAUDE.md or equivalent) and compare them against the skill's literal command blocks — an inline command that contradicts a project rule is a high-severity finding, because at run time the concrete block wins over the abstract rule.

Also check: can the skill learn from its own runs?

Not one of the 26 smells — see references/best-practices.md §7, and label it as such in the report. Look for either mechanism:

• a lessons file the skill appends to and reads before the next run, or
• a closing step that asks what the skill should have done better this time.

If neither is present, report a Medium finding: every fault this skill has is permanent, because nothing carries it forward. Only 1.3% of real skills have such a mechanism (Hong et al., arXiv 2607.01456), so this will fire often — which is the point.

Step 5 — Write and present the report

Build the report using the structure in references/report-template.md and print it in full inline in the chat, before asking any questions or applying any fixes — the chat is the primary delivery of the review; a saved file is the archive, never a substitute. Write the report — and every user-facing question in the steps below — in the user's conversation language; the template fixes the structure, not the words. Rank findings by severity (security and behavioural-contract issues first). Every finding pairs evidence with a concrete, specific fix — not "add validation" but what to validate and where.

Teach, not just grade. The reader is usually trying to learn what good skill-authoring looks like, not just get this one skill patched. So give every finding a one-sentence why — the principle behind it, in plain language (why this smell makes a skill worse) — and do the same for the strengths you note (why a good thing is genuinely good). Naming the principle is what builds the reader's general skill-writing judgement, so it carries to the next skill they write.

Step 6 — Offer a file, then offer to apply fixes

After presenting the report inline, in this order:

1. Offer to save it: ask whether the user wants the report written to a file. If yes, save it to skill-reviews/<skill-name>-<YYYY-MM-DD>.md in the current repo (create the folder if needed). Get the date with date +%Y-%m-%d. State the saved path plainly in your final message of the turn — after fixes and diffs have scrolled by, the user must still be able to find both the inline report and the file.
2. Offer to apply the fixes: ask (in the user's conversation language) whether they want the skill updated with these improvements. If yes, edit the target skill's files and show a diff of what changed. Apply the high-severity fixes first. When touching interaction, state-handling, or error-recovery text (the behavioural contract), preserve the skill's evident intent — improve the contract, do not silently rewrite how the skill behaves. If a fix is a judgement call, ask before applying it.
3. Verify the applied fixes: re-run scripts/check-hard-rules.mjs on the edited SKILL.md, confirm every path or file the edits reference exists, and run any script you added once. Show the verification output — a fix without evidence it works is a finding waiting to happen.

Step 7 — Feedback loop (reflect, ask, log, self-improve)

This step is the whole reason the skill compounds in value. Do it every run.

1. Reflect honestly on the run: what went well, what was awkward or slow, any smell you were unsure how to judge, anything the knowledge base did not cover well.
2. Ask the user for feedback (in their conversation language): did the review help, did it miss anything, did any judgement land wrong? Wait for their answer.
3. Always log — append a dated entry to lessons.md in this skill's own directory, capturing (a) which skill was reviewed, (b) your self-reflection, and (c) the user's feedback verbatim-ish. This log is append-only and is the memory that lets the reviewer get better over time. Never edit or delete past entries. If the skill directory is not writable (e.g. installed as a read-only plugin), log to skill-reviews/skill-reviewer-lessons.md in the current repo instead.
4. Propose a self-improvement, apply only on approval: from your reflection plus the user's feedback, decide whether a concrete change to this skill's own instructions or reference files would help future runs. If so, describe the change and show it as a diff, then apply it only after the user says yes. Never silently self-edit — a bad self-update would degrade every future review, so the human stays in the loop. If nothing clearly warrants a change, say so and leave the instructions untouched; logging the lesson is enough. When an approved self-improvement is applied, bump metadata.version in the frontmatter (patch for wording, minor for new behaviour). If this skill is installed read-only, propose the change as an issue or PR against the upstream repo instead of editing in place.

Example

Input: "review my find-invoices skill"

Actions:

1. Read ~/.claude/skills/find-invoices/SKILL.md and its bundled files.
2. Load the smell checklist and best-practices.
3. Detect smells (e.g. finds No Validation Step — the skill downloads invoices but never checks the download succeeded; Buried Gotchas — a login caveat is mid-paragraph, not surfaced).
4. Check frontmatter and taxonomy coverage.
5. Print the report inline, severity-ranked, each finding with evidence + fix.
6. Offer to save to skill-reviews/find-invoices-2026-07-03.md; offer to apply.
7. Reflect, ask the user for feedback, log to lessons.md, propose any self-improvement for approval.

Guardrails

• Review only the skill the user named. Do not wander into unrelated skills.
• Do not apply fixes to the target skill, save a file, or self-edit this skill without the user's go-ahead for that specific action.
• Do not fabricate findings to look thorough. Under-reporting a real problem is worse, but inventing problems erodes trust in the report.
• The smell list is a lens, not law. If a "violation" is clearly deliberate and well-reasoned for this skill's purpose, note it as intentional rather than scoring it as a defect.

Caveats

• "Skills" (SKILL.md) are an Anthropic construct; the primary authoring guidance is Anthropic's, with agent-instruction principles as complements. The reference files are self-contained, so this skill works in any repo without external files.
• Smells measure authoring quality, not whether the skill runs. A skill can execute perfectly and still carry smells that make it brittle, unclear, or unsafe — and vice versa. Say so if a finding is about authoring, not function.
• Installed read-only (e.g. as a plugin), the feedback loop degrades gracefully: lessons go to the current repo and self-improvements become upstream proposals — see Step 7.
• This skill can review itself, but a self-review shares its blind spots with the artifact. When the stakes are high (e.g. before publishing), anchor the review in an external requirement list as well, and say plainly that it is a self-review.