# Workflow: Audit Skill

**Model tier**: Haiku (research), Sonnet (analysis), Opus (synthesis), Haiku (cleanup)

## When to use

- Evaluating skill from marketplace
- Checking skill-architect standards compliance
- Discovering novel patterns

## Inputs required

- **skill_path** - Path to skill directory

## Output

- `.claude/plugin-data/skill-architect/audits/<skill-name>-audit.md` (gitignored)
- Summary with verdict (Ready / Not Ready)
- Delete report after user acts on findings

---

## Phase 1: Research

Subagent: haiku.
Read: `${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md`
Checklist: `${CLAUDE_PLUGIN_ROOT}/templates/audit-checklist-template.md` (Skill-Specific Attributes section)

**Setup:**
- Verify `skill_path` exists, contains `SKILL.md`
- Create scratch workspace
- Extract skill name

**Context loading:**
- Check for `invariants.md` in skill root
- Check for `.decisions/` directory
- Check for `examples/golden/` or `golden-examples/`
- Record: invariants list, prior decisions count/topics, golden examples list (or "none" for each)

**Structure audit:**
- SKILL.md at root
- Required dirs: `workflows/`, `references/`
- Optional dirs follow conventions: `templates/`, `scripts/`, `state/`
- Valid YAML frontmatter: `name`, `description`
- Name: kebab-case, <=64 chars

**Read all skill files:**
- SKILL.md
- All workflow files
- All reference files
- Templates, scripts if present

**File size checks:**
- SKILL.md <=50 lines
- reference.md files <=50 lines
- Knowledge docs <=150 lines (flag >200)
- Directory depth <=3 levels

Write: `scratch/research-findings.md`

---

## Phase 2: Analysis

Subagent: sonnet.
Read: `scratch/research-findings.md`, `${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md`, `references/layout/descriptions.md`, `references/progressive-disclosure/reference-md-pattern.md`, `references/progressive-disclosure/splitting-knowledge.md`, `references/subagent-pattern.md`, `workflows/create-skill.md`

**Content compliance evaluation:**
- SKILL.md routing-only vs inlined content
- reference.md files route properly
- Progressive disclosure structure appropriate

**Quality assessment:**
- Description follows "When/Why, Not How"
- Trigger unambiguous (no "if needed")
- Workflows have clear steps, subagent hints

**Skippability assessment (SINGLE primary workflow, referenced not inlined):**
1. SKILL.md protective measures? (blocking instruction, summary of key steps)
2. Workflow has non-obvious steps? (domain-specific logic vs general practice)

**Flag skip risk if:**
- Single workflow reference-only AND no blocking/summary AND non-obvious steps

**Don't flag:**
- Multiple workflows, matches general practice, inlined, or has blocking+summary

Write: `scratch/analysis-findings.md`

---

## Phase 3: Synthesis

Subagent: opus.
Read: `scratch/analysis-findings.md`, `${CLAUDE_PLUGIN_ROOT}/references/tool-patterns/severity-guide.md`, `references/tool-patterns/catalog.md`

**Pattern detection:**
- Note genuinely different approaches (not style)
- Evaluate trade-offs
- Flag substantive patterns to the user as candidates for the tool patterns
  catalog (`references/tool-patterns/catalog.md`)
- Pattern capability assessment: Verification? Brainstorming? Audit? Role-Workflow?
- See `references/tool-patterns/catalog.md` for criteria

**Classify findings:**
- Classify by severity (significant/minor/polish)
- Verdict: Ready (0 significant) or Not Ready (1+ significant)

**Impact analysis per recommendation:**
- What could degrade?
- Invariant conflict?
- Golden example impact?

If contradicts invariant or affects golden example: note and require user approval.

Write: `.claude/plugin-data/skill-architect/audits/<skill-name>-audit.md`

**Present report to user:**
- Walk through significant findings first
- Offer to fix or let user handle
- Patterns worth adding: confirm before adding to `references/tool-patterns/catalog.md`
- After user confirms: invoke cleanup

**Cleanup (haiku):**
- Delete scratch workspace
- Delete audit report
- Record decisions if needed:
  - Template: `references/tool-patterns/templates/decision-record-template.md`
  - Write: `<skill_path>/.decisions/YYYY-MM-DD-<topic>.md`
  - When: invariant changes, golden example updates, pattern adoptions, exceptions, trade-offs
  - Prompt: "Were any significant decisions made? (invariants, golden examples, patterns, exceptions)"