Review Skills

---
name: review-skills
description: Review all skill definitions in .claude/skills/ for frontmatter correctness, progressive-disclosure hygiene, trigger clarity, merge/split candidates, and gap analysis. Files every finding to the board (tasks for high/critical, a ledger comment for medium/low).
disable-model-invocation: true
user-invocable: true
---

# Skill Review Protocol

Comprehensive review of every `.claude/skills/*/SKILL.md` file. Part of the `review-*` skill family. Cites [../_shared/review-checklist.md](../_shared/review-checklist.md) and [../_shared/anthropic-configuration-guide.md](../_shared/anthropic-configuration-guide.md).

**Owner**: `docs-manager` agent.

## When to invoke

- After adding multiple new skills in quick succession
- Quarterly audit
- After Claude Code version bumps that change skill frontmatter capabilities
- When the `/` autocomplete menu gets cluttered or confusing

## Output contract

Board tasks only. Lean summary to main agent.

---

## Step 1 — Inventory

List every `.claude/skills/*/SKILL.md` file (excluding `_shared/`). For each:
- Parse frontmatter. The full supported field set is `name`, `description`, `when_to_use`, `argument-hint`, `disable-model-invocation`, `user-invocable`, `allowed-tools`, `model`, `effort`, `context`, `agent`, `hooks`, `paths`, `shell` — see `../_shared/anthropic-configuration-guide.md` §2 for what each does. Any key outside that set is an invented field and a finding.
- Count body lines
- List supporting files in the skill directory
- Extract referenced files / commands / agents from the body

## Step 2 — Frontmatter validation

For each skill, check against `review-checklist.md` §"Skills":

| Issue | Severity |
|-------|----------|
| `name` mismatches directory | critical |
| `description` missing | high |
| `description` generic or vague | medium |
| `disable-model-invocation` / `user-invocable` combination nonsensical | high |
| `allowed-tools` uses tool names that don't exist | high |
| `paths` glob invalid syntax | high |
| Uses invented frontmatter keys | high |
| `description` + `when_to_use` combined > 1,536 chars | high |

## Step 3 — Invocation semantics

For each skill, decide whether the flag combination matches intent:

| Pattern | Intent | Flag combo |
|---------|--------|-----------|
| User-triggered command with side effects | `/commit`, `/deploy` | `disable-model-invocation: true`, `user-invocable: true` |
| Reference knowledge Claude applies | `/common-tasks`, `/troubleshooting` | (defaults) |
| Background knowledge, not user-invocable | Internal guides | `user-invocable: false` |
| Workflow Claude runs, user may also invoke | `/plan`, `/review` | `user-invocable: true`, model-invocable |

Flag mismatches.

## Step 4 — Progressive disclosure check

For each skill:
- Measure SKILL.md line count
- Identify supporting files in the same directory
- Flag SKILL.md > 300 lines as a candidate for progressive-disclose (split reference material to sibling files, link from SKILL.md)
- Flag SKILL.md > 500 lines as **required** to split (hard limit per Anthropic guidance)

## Step 5 — Trigger clarity

For each skill:
- Does the `description` tell the user when to reach for this vs. a similar skill?
- Are there obvious naming collisions (e.g., two skills with "review" in the trigger)?
- Does the skill's intent match its `name` (don't hide `/commit` under a name like `persist`)?

Flag ambiguous triggers.

## Step 6 — Redundancy / overlap

Across the roster, look for:
- Skills with overlapping scope (e.g., `review` + `review-pr`)
- Skills that do the same thing with different flags
- Skills that could be merged into a single parameterized skill

## Step 7 — Content freshness

For each skill:
1. Glob every file path mentioned in the body — flag missing
2. Grep for any referenced command (`Enter C -push`, `/plan`) — confirm still valid
3. Check for deprecated Claude Code commands (`/tag`, `/vim`, `/output-style`)
4. Check for references to retired infrastructure (Supabase Edge Functions, old MIG templates)
5. Verify any shell command examples actually work (spot-check 2-3 per skill)

## Step 8 — Gap analysis

Look for recurring manual operations that should be skills:
- Commands you run frequently (>5x/month) without a skill
- Multi-step workflows the user types out by hand
- Troubleshooting recipes not yet codified
- Repeated delegation patterns that could be a `/review-*`-style skill

Flag as "Create skill for [pattern]".

## Step 9 — Orchestrator coverage

Check that orchestrator skills like `/review` and `/review-all` reference all relevant sub-skills. If a new review-* skill was added, verify `/review-all` picks it up.

## Step 10 — File findings to the board

Create parent tasks per severity + subtasks for high/critical findings (medium/low go into ONE ledger comment on the severity parent — `.claude/rules/agent-board.md` § "Review findings → board tasks", severity-gated since 2026-09-04) on the current board project (default: `Agent Infrastructure`, `<YOUR_PROJECT_ID>`). Assigned agent: `docs-manager` for most; `code-reviewer` for skills with structural issues.

## Step 11 — Summary

Return ≤ 100 words:

```
SKILL REVIEW COMPLETE
- [N] skills reviewed (excluding _shared)
- [C/H/M/L] findings per severity → board parent tasks
- [G] gap candidates
- [MS] merge/split recommendations
```

## Anti-patterns to flag

- SKILL.md > 500 lines (must progressive-disclose)
- `disable-model-invocation: true` + `user-invocable: false` (unreachable)
- `description` that just restates the `name`
- Skills with identical trigger keywords
- Shell commands that reference retired services
- `allowed-tools` that includes `*` (grant specific tools)

## Tools used

- Read, Glob, Grep
- Board MCP (create_task, update_task, log_activity)