132 lines
4.3 KiB
Markdown
132 lines
4.3 KiB
Markdown
# 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)"
|