skill-reviewer

Reviews an existing skill in this repo against authoring conventions. Produces a severity-tiered report (error / warn / info) plus a Clean section, and classifies the skill type.

Inputs

$ARGUMENTS — one of:

• A skill name (ts-best-practices) — looks under skills/<name>/ then .agents/skills/<name>/
• A path (skills/foo/SKILL.md or skills/foo)
• Empty — ask: "Which skill should I review?"

Workflow

1. Resolve target + run lint baseline

Locate the skill directory. Confirm SKILL.md exists. In the authoring repository, when its package script and built toolkit are available, run:

pnpm skill-toolkit lint <skill-name>

Capture the lint output verbatim — it's the floor, not the ceiling. Lint passing means mechanical rules pass; it does not mean the skill is well-authored.

For an installed skill in another project, apply the bundled lint-checklist.md manually instead. Do not install the toolkit or assume a sibling skill exists. Report toolkit unavailable; manual checklist used, never a fabricated lint pass.

2. Classify the skill type

Pick exactly one — this dictates which audit lens to apply:

State the classification explicitly. If you can't classify it cleanly, that's itself a finding (the skill's purpose is fuzzy).

3. Read the deep references — not just the lint summary

Lint enforces frontmatter shape, naming, anti-shortcut words. Deep references cover what lint can't:

• description.md — description quality beyond char count
• frontmatter.md — frontmatter schema
• xml-usage.md — when to use <example> / <good> / <bad>

If you skip these and only cite lint-checklist.md, you're guessing at depth.

4. Audit frontmatter + description

Beyond the lint pass:

• Description has all 3+ verbatim triggers in double quotes
• Description has an explicit Skip when … clause naming what the skill does NOT do
• Triggers in description are realistic (a real user would say them) — not abstract teacher-ese
• Description states what's distinctive ("Bakes in …") — not just what the skill does
• Body does NOT contain ## When to use / ## When NOT to use sections — routing is the description's job, and dispatchers never read the body anyway; duplicating triggers wastes tokens and creates drift risk (warn if present)
• Claude Code extension fields present where applicable (argument-hint, user-invocable, optionally disable-model-invocation and allowed-tools) and fenced behind the # --- Claude Code extensions comment. Check supported fields against the bundled frontmatter reference, distinguishing provider extensions from the portable core.

5. Audit body

• ≥ 3 ## sections
• At least one <example> block
• No TODO / FIXME / XXX
• Workflow steps are numbered actions (not prose)
• Discipline skills SHOULD have a ## Rationalization table section — its absence on a discipline skill is a warn
• Body ≤ 500 lines

6. Emit severity-tiered output (with Clean section, even on pass)

Use this exact format. The Clean section is mandatory — it forces grounding the verdict in specific rules rather than vibes.

SUMMARY: <N> findings (<E> error / <W> warn / <I> info) — <skill-type> skill

## ERRORS
✗ <file>:<line>  <one-line-finding>
  <body — what's wrong, why it matters, suggested edit>

## WARNS
⚠ <file>:<line>  <one-line-finding>
  <body>

## INFOS
ℹ <file>:<line>  <one-line-finding>
  <body>

## Clean
- <specific rule that passes — e.g., "Description has 5 verbatim triggers in double quotes (description.md:38)">
- <another specific rule>
- <`pnpm skill-toolkit lint <name>` — <pass/fail summary>>

Empty severity sections render as ## ERRORS\n(none) — keeps the shape comparable across runs. A pass verdict is 0 error / 0 warn / 0 info plus a populated Clean section.

Anti-patterns (don't do these)

No grounding. The pass verdict carries no information the user can act on or revisit later. Use a Clean section listing specific rules.

Lint is the floor. This is the lazy-reviewer failure mode — see step 3.

If a skill genuinely has 0 findings, say so in the Clean section. Inventing critique to look thorough is worse than missing real issues.

Examples

SUMMARY: 3 findings (0 error / 2 warn / 1 info) — discipline skill

## ERRORS
(none)

## WARNS
⚠ description (SKILL.md:5)  trigger parity drift vs. README.md (5 vs 6 triggers; missing "audit this ts file")
  Add the missing trigger to description and README — the description is the dispatcher's surface.
⚠ SKILL.md:184  `@pkg/fp` reference leaks a private-monorepo assumption into a public skill
  Replace with "ternary helper" or add a one-line reference link.

## INFOS
ℹ description (SKILL.md:11)  Skip-when bundles two cases with an em dash
  Split the framework case (React/Vue/Svelte) from the functional-refactor redirect.

## Clean
- Description has Use-when phrase + 5 verbatim triggers in double quotes (description.md:38)
- Frontmatter has the documented Claude Code extension fields (argument-hint, user-invocable)
- Body has 2 <example> blocks (xml-usage.md ≥ 1 required)
- Rationalization table present — appropriate for a discipline skill (skill-creator step 6)
- pnpm skill-toolkit lint ts-best-practices — 0 error / 0 warn / 0 info

SUMMARY: 0 findings (0 error / 0 warn / 0 info) — technique skill

## ERRORS
(none)

## WARNS
(none)

## INFOS
(none)

## Clean
- Description: 720 chars, has Use-when, 5 verbatim triggers, explicit Skip-when (description.md ✓)
- Frontmatter: argument-hint, user-invocable set; no fabricated fields
- Body: ≥ 3 `## ` sections, ≥ 1 `<example>` block, no TODO/FIXME
- Companions: README.md, LICENSE, references/, scripts/ all present
- Single-source-of-truth in providers.mjs reflects the skill's own thesis
- pnpm skill-toolkit lint skill-portability — 0/0/0

Nothing manufactured. For provider compatibility, use skill-portability if installed. Its optional URL staleness check is separate from this structural review; do not assume that sibling skill is installed.

Rationalization table

Captured from baseline transcripts where reviewers without this skill skipped rules. Future reviewers: recognize your own pattern.

References

• description.md — description quality rules
• frontmatter.md — frontmatter schema
• lint-checklist.md — mechanical rules (the floor)
• xml-usage.md — <example> / <good> / <bad> boundaries

These references are vendored from the authoring sources via skill.json; the reviewer does not require sibling skills to be installed.