Audit Skills

Audit personal Claude skills for consistency, best practices, and up-to-date standards.

Command routing

Check $ARGUMENTS:

• `help` → display help then stop
• `--fix [skill-name]` → auto-fix issues (see Fix mode)
• `--verbose [skill-name]` → show full details for every check (not just failures)
• `<skill-name>` → audit a single skill
• empty → audit all skills

Help

Doctor — Audit personal Claude skills for health and consistency

Usage:
  /audit-skills                      Audit all personal skills
  /audit-skills <skill-name>         Audit a single skill
  /audit-skills --fix                Auto-fix all skills
  /audit-skills --fix <skill-name>   Auto-fix a specific skill
  /audit-skills --verbose            Full detail for every check
  /audit-skills help                 This help

Checks performed:
  Manifest    Does the skill follow SKILLS_GUIDE.md conventions?
  Frontmatter Are all required/recommended fields present and correct?
  Content     Is the skill under 500 lines? Are references bundled?
  Tools       Are allowed-tools minimal? Any duplicates? Any contradictions?
  UX          Does it have help/config/reset? First-time detection? Memory?
  Docs        Is the description third-person with trigger keywords?
  Security    Does disable-model-invocation match the side-effect profile?
  Upstream    Does it follow latest official Claude skills documentation?

Output:
  [PASS] Check passed
  [WARN] Non-critical suggestion
  [FAIL] Violates manifest or best practice
  [INFO] Informational note

Example output:
  /slack-to-ticket
    [PASS] Third-person description
    [PASS] disable-model-invocation: true (has side effects)
    [WARN] SKILL.md is 120 lines — fine, but has inline examples that could be bundled
    [FAIL] Missing help subcommand
    [PASS] Preferences memory pattern present

Step 1: Load references

Local manifest

Read ~/.claude/skills/SKILLS_GUIDE.md — this is the source of truth for local conventions.

Latest upstream docs

Search the web for the latest Claude Code skills documentation:

ultrathink

Search for:

• site:code.claude.com skills — official skill format docs
• site:platform.claude.com agent-skills best-practices — authoring best practices
• claude code skills 2026 — any new features or changes

Fetch and read the top results. Extract:

• Any NEW frontmatter fields not in our manifest
• Any CHANGED best practices (naming, descriptions, tool restrictions)
• Any DEPRECATED patterns we're still using
• Any NEW features we should adopt

Compile a checklist of upstream checks in addition to the manifest checks.

If web search is unavailable, proceed with manifest-only checks and note: "Could not fetch upstream docs — manifest checks only."

Step 2: Discover skills

~/.claude/skills/*/SKILL.md

List all found skills. If a specific skill-name was given in $ARGUMENTS, filter to just that one.

Step 3: Audit each skill

For each skill, run every check below. Track results as PASS/WARN/FAIL/INFO.

Frontmatter checks

Tool checks

Content checks

UX checks (from manifest conventions)

Upstream checks (from fetched docs)

Apply any new checks discovered in Step 1. Common ones:

Inventory check (only on full audit)

There is no hand-maintained inventory to compare against — the README catalog is generated from each skill's frontmatter, which is the only copy that exists. Instead:

• Run make check in the skills repo: it fails if the catalog is stale or any

frontmatter won't parse (frontmatter errors fail soft in Claude Code, so this is the only place they surface)

• Run claude plugin validate ~/.claude/skills for the same check on what's installed
• Report any skill directory with no SKILL.md, or a SKILL.md with no description

Step 4: Present results

Per-skill report

/skill-name
  [PASS] 8 checks passed
  [WARN] 2 warnings
  [FAIL] 1 failure

  Failures:
    - disable-model-invocation missing (skill creates Linear issues)

  Warnings:
    - No dynamic context injection (could pre-fetch git branch)
    - SKILL.md is 180 lines with inline examples (consider bundling)

Summary (full audit only)

Doctor Summary — {date}

Skills audited: {N}
  [PASS] {N} fully healthy
  [WARN] {N} with warnings
  [FAIL] {N} with failures

Top issues:
  1. {most common failure across skills}
  2. {second most common}

Upstream updates:
  {Any new features/changes from official docs worth adopting}
  (or "All skills are up-to-date with latest docs")

Inventory:
  {N} skill directories found
  make check: {pass|fail — reason}

Step 5: Offer fixes (if --fix flag)

If --fix was passed:

1. For each FAIL, propose a specific edit
2. For each WARN, propose a fix (optional)
3. Use `AskUserQuestion` (multiSelect: true):

• One option per proposed fix
• "Apply all fixes"
• "Skip all"

1. Apply approved fixes using Edit tool
2. Run make catalog if any frontmatter description changed
3. Report what was changed

Without --fix: just report findings.

Step 6: Save audit results

Write a timestamped audit log to:

~/.claude/skills/audit-skills/last-audit.md

Format:

# Skill Audit — {date}

## Summary
- Skills: {N}
- Pass: {N}, Warn: {N}, Fail: {N}

## Per-skill results
{compact results}

## Upstream notes
{anything new from docs}

This allows comparing across audits to track improvement.

Principles

• Non-destructive by default: Only report, never modify without --fix and user confirmation.
• Manifest is local truth: SKILLS_GUIDE.md defines what "good" means for this user.
• Upstream is advisory: New features from official docs are INFO/WARN, not FAIL (unless the user's manifest adopts them).
• Be specific: Every FAIL/WARN includes exactly what's wrong and how to fix it.
• Fast: Don't re-read files unnecessarily. Parse frontmatter first, skip deep content checks if frontmatter fails.