---
description: Review a skill or command against best practices and flag issues with fixes
argument-hint: [path to SKILL.md or command file]
---

# /audit-skill — Skill Quality Auditor

Review a skill file against Anthropic best practices and the writing-skills checklist. Produce structured findings with severity, then offer to fix.

## Input

Read the file at `$ARGUMENTS`. If no argument given, ask: **"Which skill should I audit?"** and list skills from `~/.claude/skills/`, `~/.claude/commands/`, and `.claude/skills/` if they exist.

## Audit Process

### 1. Read the skill file completely
Read SKILL.md and any referenced files (workflows, references, templates). Understand the full skill before judging.

### 2. Determine skill complexity
Assess before applying rules — a 20-line command doesn't need the same rigor as a 300-line workflow skill:

- **Simple** (< 50 lines, single purpose): lighter standards
- **Medium** (50-200 lines, multi-step): full standards
- **Complex** (200+ lines or multi-file): full standards + architecture review

### 3. Run the checklist

Evaluate each item. Score: PASS, WARN, FAIL.

**Frontmatter:**
- [ ] `name` present (skills) or filename is descriptive (commands)
- [ ] `description` is specific with trigger keywords
- [ ] `description` does NOT summarize workflow (the CSO trap)
- [ ] `description` is third-person
- [ ] `argument-hint` present if skill takes arguments

**Description quality (deep check):**
- Does the description answer "should I read this skill right now?" for a given task?
- Would Claude select this skill from 100+ available skills based on this description alone?
- Are there trigger keywords matching how a user would phrase their need?
- Is the description under 500 characters?

**Content:**
- [ ] SKILL.md body under 500 lines
- [ ] No time-sensitive information
- [ ] Consistent terminology (no synonym drift)
- [ ] Concrete examples (not abstract placeholders)
- [ ] File references one level deep (no A→B→C chains)
- [ ] Success criteria defined

**Structure:**
- [ ] Clear overview/purpose in first section
- [ ] Workflows have numbered steps
- [ ] Degrees of freedom match task fragility
- [ ] Progressive disclosure used (complex skills only)
- [ ] Router pattern used if multiple workflows exist (complex skills only)

**Anti-patterns:**
- [ ] No narrative storytelling (skills are references, not war stories)
- [ ] No multi-language examples for the same pattern
- [ ] No vague descriptions ("helps with X", "useful for Y")
- [ ] No first-person in description
- [ ] No deeply nested file references

## Output Format

Present findings grouped by severity:

```
## Audit: [skill-name]

**Overall: PASS / NEEDS WORK / FAIL**

### Findings

**FAIL** (must fix):
- [F1] Description summarizes workflow — "dispatches subagent per task with review"
  → Rewrite to triggering conditions only: "Use when executing implementation plans with independent tasks"

**WARN** (should fix):
- [W1] No success criteria defined
  → Add "## Success Criteria" with measurable done conditions

**PASS** (good):
- Frontmatter structure correct
- Token budget within limits (127 lines)
- Examples are concrete and runnable
```

For each finding: state what's wrong, quote the offending content, and show the fix.

## After Audit

Ask: **What's next?**
- **Fix all** — apply all suggested fixes automatically
- **Fix critical only** — apply only FAIL-level fixes
- **Discuss** — talk through specific findings before changing anything
- **Done** — take the report and fix manually

<!-- Origin: Auditor concept, contextual judgment (proportional standards), structured severity output adapted from https://github.com/glittercowboy/taches-cc-resources -->
<!-- Checklist items from Anthropic best practices and writing-skills archive (superpowers) -->