skill-audit

Skill Audit

Audit a Claude Code skill for quality, completeness, and correctness. Each issue is presented one at a time with multiple resolution options, always including a research option that forks parallel code + web research agents.

Input

$ARGUMENTS — path to the skill directory or SKILL.md file.

Parse Arguments

Extract from $ARGUMENTS:

• Skill Path: If path ends in SKILL.md, use its parent directory as the skill directory. Otherwise, treat as the skill directory directly.
• Verify the path exists and contains a SKILL.md file. If not found, report error and stop.

Process

Phase 1: Load Documents

1. Read SKILL.md from the skill directory.
2. Use Glob to scan the skill directory for any files in references/ subdirectory.
3. Read the audit checklist at ${CLAUDE_SKILL_DIR}/references/checklist.md.
4. Parse the SKILL.md frontmatter (YAML between --- delimiters) and body content separately.

Phase 2: Run All Checks

Evaluate every check from the checklist against the loaded skill. For each check:

• Determine status: PASS, FAIL, or N/A (if the check's precondition isn't met)
• For FAIL: record the severity and a specific description of what's wrong

Build a prioritized issue queue:

1. 🔴 CRITICAL issues first
2. 🟡 WARNING issues next
3. 🔵 INFO issues last
4. ❓ Open Questions last

Phase 3: Present Summary

## Skill Audit Summary: [skill name]

**Skill Directory:** [path]
**SKILL.md:** [line count] lines
**Reference Files:** [count] files

Found **N issues** and **M open questions**:
- 🔴 CRITICAL: [count]
- 🟡 WARNING: [count]
- 🔵 INFO: [count]
- ❓ Open Questions: [count]

Starting sequential resolution...

If zero issues found, skip to Phase 5 with PASS verdict.

Phase 4: Sequential Resolution

For each issue, present using AskUserQuestion with:

• Clear description of the issue and which checklist item it violates
• At least 2 fix options (one marked ⭐ recommended)
• Always include "🔍 Research code & web" option
• Always include "Skip" as last option