skill-review

Skill Review

One skill, two modes. Use --scope=all for an ecosystem-wide bulk scan; use --scope=<skill-name> for a thorough single-skill deep dive. Both modes produce a structured markdown report plus a JSON sidecar that skill-update can consume to generate fix plans.

When to Use

• Periodic health check across the skill ecosystem (--scope=all)
• After bulk edits or a new batch of skills lands (--scope=all)
• Reviewing a single skill before publishing (--scope=<name>)
• Investigating why one skill won't trigger or produces poor output (--scope=<name>)
• Quality-gating a skill before it enters the ecosystem (--scope=<name>)

Inputs

The skill takes a single positional argument:

• all — bulk scan across skills/**/SKILL.md
• <skill-name> — deep dive on skills/**/<skill-name>/SKILL.md

Optional follow-on context:

• Focus — narrow the run to specific checks ("just ownership", "just descriptions")
• Why-now — what prompted the review (e.g., "it never triggers", "outputs are wrong")

Process

Phase 0: Parse the Argument

1. Read the argument. If it equals all (case-insensitive), enter Mode A.
2. Otherwise treat the argument as a skill name. Glob for skills/**/<arg>/SKILL.md. If exactly one match, enter Mode B. If zero matches, return a list of fuzzy candidates and stop. If multiple matches, ask the user to disambiguate.

Mode A — Bulk Scan (--scope=all)

Optimize for speed. Score quickly, flag issues, move on. Use subagents to parallelize check categories where available.

A1. Discovery

1. Glob skills/**/SKILL.md
2. Parse frontmatter from each
3. Build a skill inventory table with columns: Skill, Category, Version, Description Length, Body Lines, Refs Count

A2. Bulk Checks

Run these check categories. Full checklist lives in references/audit-checklist.md.

• Frontmatter consistency — required fields present, name matches directory, version is valid semver, description starts with action verb and is ≤200 chars
• Spec compliance (FAIL) — no < or > in frontmatter field values (security rule); description ≤1024 chars (hard ceiling)
• Spec compliance (WARN) — reserved-prefix name (claude-* / anthropic-*). Acceptable as a documented exception when the skill targets the corresponding Anthropic product. Verify the documented exception exists in the skill body.
• Tool field naming — allowed-tools (hyphen) is canonical; allowed_tools (underscore) accepted as deprecated alias (warn but don't fail)
• Ownership conflict detection — collect every owns.directories and owns.patterns across agent roles. Flag overlaps. Validate against the v1.1 resolved conflicts table in frontmatter-spec.md
• Description quality scoring — has action verb, ≥3 trigger contexts, keyword variants, states exclusions if ambiguous, estimated "pushiness" (low/medium/high)
• Progressive disclosure — SKILL.md body line + word count, references linked from body, body >5,000 words OR >500 lines flagged (soft warning), references >300 lines without TOC flagged
• Cross-skill consistency — composes_with and spawned_by point to real skills, no circular composes_with chains, no orphan reference files
• Coverage gaps — compare inventory against docs/architecture.md, CLAUDE.md, and the orchestrator's File Ownership Map; flag roles or workflows referenced but not implemented