ratacat/claude-skills/workflows

Workflow: Audit a Skill

<required_reading> Read these reference files NOW:

1. references/recommended-structure.md
2. references/skill-structure.md
3. references/use-xml-tags.md

</required_reading>

<process>

Step 1: List Available Skills

DO NOT use AskUserQuestion - there may be many skills.

Enumerate skills in chat as numbered list:

ls ~/.claude/skills/

Present as:

Available skills:
1. create-agent-skills
2. build-macos-apps
3. manage-stripe
...

Ask: "Which skill would you like to audit? (enter number or name)"

Step 2: Read the Skill

After user selects, read the full skill structure:

# Read main file
cat ~/.claude/skills/{skill-name}/SKILL.md
 
# Check for workflows and references
ls ~/.claude/skills/{skill-name}/
ls ~/.claude/skills/{skill-name}/workflows/ 2>/dev/null
ls ~/.claude/skills/{skill-name}/references/ 2>/dev/null

Step 3: Run Audit Checklist

Evaluate against each criterion:

YAML Frontmatter

• [ ] Has name: field (lowercase-with-hyphens)
• [ ] Name matches directory name
• [ ] Has description: field
• [ ] Description says what it does AND when to use it
• [ ] Description is third person ("Use when...")

Structure

• [ ] SKILL.md under 500 lines
• [ ] Pure XML structure (no markdown headings # in body)
• [ ] All XML tags properly closed
• [ ] Has required tags: objective OR essential_principles
• [ ] Has success_criteria

Router Pattern (if complex skill)

• [ ] Essential principles inline in SKILL.md (not in separate file)
• [ ] Has intake question
• [ ] Has routing table
• [ ] All referenced workflow files exist
• [ ] All referenced reference files exist

Workflows (if present)

• [ ] Each has required_reading section
• [ ] Each has process section
• [ ] Each has success_criteria section
• [ ] Required reading references exist

Content Quality

• [ ] Principles are actionable (not vague platitudes)
• [ ] Steps are specific (not "do the thing")
• [ ] Success criteria are verifiable
• [ ] No redundant content across files

Step 4: Generate Report

Present findings as:

## Audit Report: {skill-name}
 
### ✅ Passing
- [list passing items]
 
### ⚠️ Issues Found
1. **[Issue name]**: [Description]
   → Fix: [Specific action]
 
2. **[Issue name]**: [Description]
   → Fix: [Specific action]
 
### 📊 Score: X/Y criteria passing

Step 5: Offer Fixes

If issues found, ask: "Would you like me to fix these issues?"

Options:

1. Fix all - Apply all recommended fixes
2. Fix one by one - Review each fix before applying
3. Just the report - No changes needed

If fixing:

• Make each change
• Verify file validity after each change
• Report what was fixed

</process>

<audit_anti_patterns>

Common Anti-Patterns to Flag

Skippable principles: Essential principles in separate file instead of inline Monolithic skill: Single file over 500 lines Mixed concerns: Procedures and knowledge in same file Vague steps: "Handle the error appropriately" Untestable criteria: "User is satisfied" Markdown headings in body: Using # instead of XML tags Missing routing: Complex skill without intake/routing Broken references: Files mentioned but don't exist Redundant content: Same information in multiple places </audit_anti_patterns>

<success_criteria> Audit is complete when:

• [ ] Skill fully read and analyzed
• [ ] All checklist items evaluated
• [ ] Report presented to user
• [ ] Fixes applied (if requested)
• [ ] User has clear picture of skill health

</success_criteria>