jared
/
cc-os
1
0
Fork 0
Code Issues 18 Pull Requests Packages Projects Releases Wiki Activity
cc-os/plugins/cc-architect/workflows/audit-skill.md

4.3 KiB
Raw Permalink Blame History

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)"