Dev Skills Auditor

Audit Skills

Audit a plugin folder for compliance with Claude Code skill and agent best practices.

Variables

PLUGIN_PATH: $ARGUMENTS

Workflow

If no PLUGIN_PATH is provided, STOP and ask the user to provide it.

Step 1: Discover Plugin Structure

1. Verify .claude-plugin/plugin.json exists and is valid JSON
2. Scan skills/ for all SKILL.md files
3. Scan agents/ for all agent definition files
4. Check for CLAUDE.md at plugin root
5. Build inventory of all components to audit

Step 2: Audit Each Skill

For every SKILL.md found, check each rule below. Track pass/fail per skill.

Frontmatter Rules

Content Rules

Step 3: Audit Each Agent

For every agent definition file, check:

Step 4: Audit Plugin Structure

Step 5: Write Analysis Report

Write the full audit report to {PLUGIN_PATH}/analysis.md. This file is the persistent artifact of the audit — it stays in the plugin folder for reference and tracking over time.

Use this structure for the file:

# Plugin Audit: {plugin-name}

**Path**: {PLUGIN_PATH}
**Date**: {today}
**Skills**: {count} | **Agents**: {count}

## Summary

| Severity | Count |
|----------|-------|
| ERROR    | {n}   |
| WARN     | {n}   |
| INFO     | {n}   |
| PASS     | {n}   |

## Plugin Structure
- P1: {PASS/FAIL} — plugin.json valid
- P2: {PASS/FAIL} — plugin.json has name
...

## Skills

### {skill-name}
- F1: {PASS/FAIL} — name exists
- F2: {PASS/FAIL} — name format
...

### {skill-name}
...

## Agents

### {agent-name}
- A1: {PASS/FAIL} — name exists
...

## Top Issues (by impact)

1. {Most impactful issue + suggested fix}
2. {Next issue + suggested fix}
3. ...

## Suggested Fixes

{For each ERROR and WARN, a specific actionable fix}

Step 6: Summarize to User

After writing the file, print a brief summary to the user:

• Total pass/fail counts
• Number of ERRORs and WARNs
• Path to the written analysis.md
• Top 3 highest-impact issues to fix first

Do NOT write fixes to skill/agent files. Only report them in analysis.md. The user decides what to apply.

Recognized Frontmatter Fields

Skills: name, description, argument-hint, allowed-tools, disable-model-invocation, user-invocable, context, agent, model, hooks

Agents: name, description, tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, memory, hooks, color, background, isolation

Description Quality Signals

Good signals (any of these = likely good):

• Starts with action verb: Analyze, Audit, Generate, Review, Research, Explain, Build, Deploy, Convert
• Contains trigger phrase: "Use when", "Use for", "Use after", "Use proactively"
• Mentions specific domain/context

Bad signals (any of these = likely bad):

• Under 30 characters
• Generic words only: "helper", "tool", "processor", "thing"
• No use-case context
• Just restates the name