---
name: clawd-skill-review
description: >
  Audit Claude Code skills against Anthropic's best practices (structure, scripts,
  gotchas, progressive disclosure, hooks, composition, description quality).
  Use when the user says /claude-skill-review, /skill-review, 'audit my skills',
  'review skill quality', 'check skill best practices', 'skill health check',
  'audit des skills', 'qualite des skills', or wants to evaluate skill maturity
  against Anthropic guidelines. Also trigger when the user asks 'are my skills
  well written?', 'how can I improve my skills?', or compares their skills to
  best practices.
argument-hint: "[skill-name | 'all' | 'all --summary']"
allowed-tools:
  - Read
  - Bash
  - Glob
  - Grep
  - Agent
---

Audit one or all skills in a plugin against Anthropic's published best practices for Claude Code skills. Produces a structured scorecard with maturity rating and concrete, prioritized improvements.

## Determine scope

Parse `$ARGUMENTS` to decide what to review:
- A skill name (e.g. `review`, `ci-debug`) → review only that skill
- `all` or empty → review every skill in the plugin (full detail)
- `all --summary` → plugin overview with summary table + recurring patterns only (no per-skill detail)
- A path → review the skill at that path

To find skills, look for directories containing a `SKILL.md` file. The typical plugin layout is:
```
plugins/<plugin-name>/skills/<skill-name>/SKILL.md
```

If the current directory is inside a plugin, use it. Otherwise scan the nearest plugin root.

## Scan each skill

For each skill, run the scan command to get structural metadata quickly:

```bash
pysae-ai-tools internal scan-skill <skill-directory>
```

Then read the SKILL.md to analyze content. If the skill has reference files, read them too — you need the full picture to judge progressive disclosure and content quality.

## Apply the 15-point checklist

Read `references/anthropic-best-practices.md` for the detailed rubric. For each check, assign one of:
- **PASS** — clearly meets the criteria
- **PARTIAL** — partially meets, with a specific gap noted
- **MISSING** — does not meet the criteria
- **N/A** — not applicable to this skill type (counts as PASS for scoring)

The 15 checks, grouped:

**Structure (1-5)**: executable scripts, progressive disclosure, gotchas section, file size, config pattern

**Description (6-7)**: trigger spec quality, avoids vagueness

**Content (8-10)**: avoids obvious, avoids railroading, has examples

**Advanced (11-14)**: persistent memory, on-demand hooks, skill composition, dual-mode

**Classification (15)**: clear single category

Be honest in scoring — inflated scores defeat the purpose. But be fair: mark N/A when a check genuinely doesn't apply. Read the **Scoring calibration** section in `references/anthropic-best-practices.md` for concrete examples of how to score edge cases consistently.

**N/A guidelines** — only mark N/A when the check is structurally impossible for this skill type:
- **Memory (11)**: N/A only for pure one-shot skills with no useful history (changelog, mr). NOT N/A for skills that repeat (ci-debug, deploy) — they benefit from memory even if they don't use it yet.
- **Hooks (12)**: N/A only for read-only skills with zero mutation risk (discover, compound). NOT N/A for skills that edit files or call destructive APIs.
- **Dual-mode (14)**: N/A only for skills that fundamentally require human interaction at every step. NOT N/A for skills that could plausibly run in CI (implement, ci-debug, deploy).
- **Config (5)**: N/A only when the skill has truly zero environment-specific values. If there are Project IDs, channel IDs, or API endpoints anywhere (including in references/), it's MISSING or PARTIAL, not N/A.

## Score and classify

Count PASS + N/A as points:
| Level | Score | Meaning |
|-------|-------|---------|
| Basic | 0-5 | Functional, few best practices |
| Intermediate | 6-10 | Solid foundation, missing advanced patterns |
| Advanced | 11-13 | Well-crafted, room for polish |
| Expert | 14-15 | Best-in-class |

## Generate the report

Output in French. Use this structure:

**For a single skill:**
```markdown
# Skill Review: {skill_name}

## Scorecard
| # | Check | Status | Notes |
|---|-------|--------|-------|
| 1 | Scripts exécutables | ✅/⚠️/❌ | ... |
| ... | ... | ... | ... |

## Maturité: {level} ({N}/15)

## Top 3 améliorations
1. **{titre}** — {quoi faire, pourquoi (ref best practice), exemple concret}
2. ...
3. ...
```

**For all skills — full mode (default):**
Include a summary table first, then individual scorecards.
```markdown
# Skill Review: Plugin Overview

## Vue d'ensemble
| Skill | Score | Maturité | Catégorie | Lacune principale |
|-------|-------|----------|-----------|-------------------|
| ... | .../15 | ... | ... | ... |

## Patterns récurrents
- {gap partagé par plusieurs skills + recommandation}

## Détail par skill
### {skill_name}
{individual scorecard}
```

**For all skills — summary mode (`all --summary`):**
Only the summary table + recurring patterns + top 5 plugin-wide improvements. No per-skill detail. Useful for a quick health check without the full report.
```markdown
# Skill Review: Plugin Summary

## Vue d'ensemble
| Skill | Score | Maturité | Catégorie | Lacune principale |
|-------|-------|----------|-----------|-------------------|

## Patterns récurrents

## Top 5 améliorations plugin-wide
```

## Prioritize improvements

When listing improvements, order by impact — not by checklist number. The highest-impact improvements are usually:
1. Missing scripts for mechanical/repetitive operations (saves tokens every invocation)
2. Missing gotchas (prevents repeated failures)
3. Hardcoded values that should be in config (portability)
4. Composition opportunities (DRY across skills)

Reference the Anthropic best practices when explaining *why* something matters — the reasoning helps the user decide whether to invest in the fix.

## Gotchas

- **Don't break composition** — before suggesting a skill be split or merged, check cross-references. If `code-implement` calls `/glab-mr` which calls `/code-changelog`, suggesting to merge them would break the chain.
- **N/A vs MISSING distinction matters** — a deployment skill without dual-mode is MISSING. A changelog skill without dual-mode is N/A. Think about what the skill *does* to decide.
- **Line count isn't everything** — a 400-line SKILL.md with clear sections and progressive disclosure is better than a 100-line SKILL.md that's missing critical information. Size is a signal, not the score.
- **Scan script may miss nuances** — the script counts keywords but can't judge quality. Always read the actual content before grading. The script gives you signals, your reading gives you the grade.
- **Skills that compose heavily may look "thin"** — a skill that delegates most work to other skills isn't empty, it's well-designed. Don't penalize composition.
- **Langue française** : respecter les [règles de rédaction en français](../references/french-writing-rules.md) pour tout texte généré
