Audit skills

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

Check	PASS	FAIL
name present	Has name	Missing
description present	Has description	Missing
description is third-person	Starts with verb in third person ("Creates", "Analyzes")	Imperative/second person ("Create", "Analyze")
description has trigger keywords	Contains "Use when" or similar usage hint	No usage context
description length	≤1024 chars	Over 1024
argument-hint present	Has hint	WARN: missing (optional but recommended)
disable-model-invocation	true if skill has side effects (check allowed-tools for Write, Edit, Bash, MCP create/update tools)	Missing when side effects present
allowed-tools present	Listed	WARN: missing (broad permissions)

Tool checks

Check	PASS	FAIL
No duplicate MCP tools	Single prefix per service	Both mcp__linear-server__* and mcp__claude_ai_Linear__*
MCP tools use canonical prefix	Uses mcp__claude_ai_Linear__*	Uses mcp__linear-server__*
No contradictory tools	Read-only skills don't have Write/Edit	Read-only principle violated
Minimal tools	Only tools actually referenced in body	Tools listed but never used

Content checks

Check	PASS	FAIL
Under 500 lines	≤500	WARN: over 500
No redundant instructions	Doesn't tell Claude how to use JSON, git basics, etc.	WARN: generic instructions
Uses numbered checklists for workflows	Steps are numbered	WARN: prose-only workflow
References bundled files if >100 lines of examples	Examples in separate files	WARN: large inline examples

UX checks (from manifest conventions)

Check	PASS	FAIL
help subcommand	Body handles $ARGUMENTS = "help"	Missing
config subcommand	Body handles $ARGUMENTS = "config"	Missing
reset subcommand	Body handles $ARGUMENTS = "reset"	Missing
First-time detection	Checks for preferences file existence	Missing
Preferences memory	References preferences.md file	Missing
Dynamic context injection	Uses !backtick`` preprocessing	WARN: missing where applicable

Upstream checks (from fetched docs)

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

Check	PASS	FAIL
context: fork for self-contained skills	Set when skill doesn't need conversation history	WARN: could benefit from fork
model field for reasoning-heavy skills	Set for complex analysis skills	INFO: could benefit from model override
Positional args $0, $1	Used for structured inputs	INFO: could use positional args
Skill directory structure	Has SKILL.md + optional reference/examples	Non-standard structure

Inventory check (only on full audit)

• Compare discovered skills against SKILLS_GUIDE.md inventory table
• Report any skills not in the inventory (WARN)
• Report any inventory entries with no matching skill (WARN)

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} skills in SKILLS_GUIDE.md
  {N} skill directories found
  {discrepancies if any}

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"
4. Apply approved fixes using Edit tool
5. Update SKILLS_GUIDE.md inventory if new skills were found
6. 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.