audit-extensions

<essential_principles>

1. Structure Before Content. Check that the extension follows the correct format before evaluating what it says. A beautifully written skill with invalid YAML is still broken.

2. Severity-Based Reporting. Not all issues are equal. Critical issues prevent the extension from working. Recommendations improve quality. Quick fixes are cosmetic. Report in this order.

3. Always Include Strengths. An audit that only lists problems demoralizes. Start with what the extension does well, then address issues.

4. Specific Locations. Every finding must reference a file path and line number (or line range). "The description is too vague" is not actionable. "Line 3: description lacks trigger keywords -- add phrases like 'create a hook', 'add validation'" is actionable.

5. Auto-Detect Extension Type. Determine whether the target is a skill, command, or subagent from the file path and structure. Don't require the user to specify.

</essential_principles>

Provide a path to any Claude Code extension:

• Skill: Path to a skill directory or SKILL.md file
• Slash command: Path to a .md command file
• Subagent: Path to an agents/ directory or agent config

The audit type will be auto-detected from the path and file structure.

Auto-detection logic:

1. If path contains SKILL.md or path is a directory containing SKILL.md -> skill audit
2. If path is a .md file with allowed-tools in frontmatter -> command audit
3. If path contains agent configuration with identifier field -> subagent audit
4. If ambiguous, ask user to clarify

After detecting type, read references/audit-checklist.md for the relevant checklist, then execute the audit.

<audit_process>

For all extension types, follow this process:

Phase 1: Read

1. Read the extension file(s) completely
2. Read any referenced files (workflows, references, templates)
3. Note file sizes (line counts)

Phase 2: Check Run through every item in the relevant checklist (see references/audit-checklist.md). For each item:

• PASS: Requirement met
• FAIL: Requirement not met (record file:line, severity, fix)
• N/A: Check doesn't apply to this extension

Phase 3: Anti-Pattern Scan Check against all 18 anti-patterns from shared/rules/ANTI-PATTERNS.md:

1. Markdown headings in skill body
2. Hybrid XML/markdown
3. Unclosed or improperly nested tags
4. SKILL.md over 500 lines
5. Deeply nested references
6. Vague description
7. Wrong point of view
8. Missing trigger keywords
9. Agent-focused instead of user-focused
10. Over-engineered simple skills
11. Under-specified complex skills
12. Too many options without defaults
13. Duplicating framework documentation
14. Missing success criteria
15. Explaining what Claude already knows
16. Non-descriptive names
17. Wrong case
18. Name doesn't match directory

Phase 4: Report Organize findings by severity and present with strengths first.

</audit_process>

<output_format>

## Audit Report: [extension-name] ([type])

### Strengths
- [What the extension does well -- always include at least 2 items]

### Critical Issues (must fix)
- **[C1]** [file:line] [Issue description]
  Fix: [Specific remediation]

### Recommendations (should fix)
- **[R1]** [file:line] [Issue description]
  Fix: [Specific remediation]

### Quick Fixes (nice to have)
- **[Q1]** [file:line] [Issue description]
  Fix: [Specific remediation]

### Summary
- Checks passed: X/Y
- Critical: N | Recommendations: N | Quick fixes: N
- Anti-patterns detected: N/18

### Next Steps
- [ ] Fix critical issues
- [ ] Address recommendations
- [ ] Re-run audit to verify fixes
- [ ] Run trigger test (evaluate-skills) if description was changed