cc-dev-template 0.1.6 → 0.1.7

package/src/skills/create-agent-skills/references/audit.md

@@ -1,21 +1,23 @@
 # Audit Existing Skills
 
-This workflow discovers and reviews all installed skills against best practices. Use it to identify skills that need improvement and ensure consistency across skill libraries.
+This workflow discovers and reviews all installed skills against best practices. The most important check is whether the SKILL.md is written as a proper prompt, not as documentation.
 
 ## Purpose
 
 Systematically review skills to identify:
+- **Fundamental prompt problems** - Is this written as instructions TO Claude or documentation ABOUT the skill?
+- Content that belongs in references, not SKILL.md
 - Structural issues (missing files, wrong format)
 - Description problems (vague, wrong person, missing triggers)
-- Writing style violations (second person, negative framing)
-- Progressive disclosure failures (oversized SKILL.md, unreferenced resources)
-- Missing or broken references
+- Writing style violations
 
-**Success looks like:** A comprehensive report of all skills with specific, actionable findings for any that need improvement.
+**Success looks like:** Actually reading each skill and evaluating whether it would work as a prompt. Surface fundamental problems, not just superficial style issues.
 
 ## Before Starting
 
-Read `references/principles.md` if not already familiar with skill standards.
+Read `references/principles.md` to understand what makes a good skill.
+
+**Critical understanding:** A SKILL.md IS the prompt. When Claude activates a skill, it reads SKILL.md. If SKILL.md reads like documentation ("This skill does X", "Who this is for"), Claude won't know what to DO.
 
 ## Workflow
 
@@ -36,18 +38,6 @@ src/skills/                # Source skills (if in dev-template)
 node ~/.claude/skills/create-agent-skills/scripts/find-skills.js
 ```
 
-Or manually scan:
-```bash
-# User-level
-ls -la ~/.claude/skills/*/SKILL.md 2>/dev/null
-
-# Project-level
-ls -la .claude/skills/*/SKILL.md 2>/dev/null
-
-# Source (dev-template)
-ls -la src/skills/*/SKILL.md 2>/dev/null
-```
-
 **For each skill found, record:**
 - Full path to SKILL.md
 - Skill name (directory name)
@@ -67,9 +57,163 @@ If user selects "Specific skill," ask which one from the discovered list.
 </step>
 
 <step name="Audit Each Skill">
-For each skill in scope, perform these checks:
+For each skill in scope, **READ THE ENTIRE SKILL.MD FILE** and perform these checks in order. The first check is the most important.
+
+---
+
+### CHECK 0: Is This Written as a Prompt? (CRITICAL)
+
+**This is the most important check.** Read the entire SKILL.md and evaluate:
+
+**Is it instructions TO Claude, or documentation ABOUT the skill?**
+
+A SKILL.md should tell Claude what to DO right now. It should NOT describe what the skill is, who it's for, or how it works abstractly.
+
+**Red flags that indicate documentation, not a prompt:**
+
+| Red Flag | Why It's Wrong |
+|----------|----------------|
+| "Who this is for: Developers..." | Meta-description. Claude doesn't need to know the audience. |
+| "Success looks like: Running X produces Y" | Meta-description. This describes outcomes, doesn't instruct. |
+| "This skill orchestrates..." | Describes what skill IS, not what to DO. |
+| "The purpose of this skill is..." | Documentation language, not instruction. |
+| Large inline schemas (YAML, JSON examples) | Should be in references/, loaded when needed. |
+| Explaining how phases work abstractly | Should just route to phase files with instructions. |
+
+**What a good SKILL.md looks like:**
+
+```markdown
+## What To Do Now
+
+<step name="Get Input">
+Ask the user which form to implement.
+</step>
+
+<step name="Check State">
+Look for existing workflow at `.claude/workflows/{formname}/workflow.yaml`
+
+If exists: Read it, determine current phase.
+If not: Initialize new workflow.
+</step>
+
+<step name="Route to Phase">
+Based on current phase, read the appropriate file:
+
+| Phase | File |
+|-------|------|
+| phase1 | `references/phase1.md` |
+| phase2 | `references/phase2.md` |
+</step>
+```
+
+**What a BAD SKILL.md looks like:**
+
+```markdown
+## Purpose
+
+This skill orchestrates the complete migration of Oracle Forms...
+
+**Who this is for**: Developers migrating Oracle Forms.
+
+**Success looks like**: Running /implement-form progresses through all phases.
+
+## Phase Overview
+
+Phase 1 does X, Phase 2 does Y...
+
+## YAML Schema
+
+```yaml
+# 50 lines of YAML schema inline
+```
+```
+
+**Evaluation questions:**
+
+1. If Claude reads this right now, does it know what to DO?
+2. Is there a clear "What To Do Now" section with concrete steps?
+3. Or does it just describe what the skill is and how it works?
+
+**Record severity:**
+- **CRITICAL** if SKILL.md reads like documentation
+- **CRITICAL** if large schemas/examples are inline instead of in references/
+- **CRITICAL** if no clear action instructions exist
+
+```
+PROMPT_QUALITY: [skill-name] - CRITICAL: Written as documentation, not instructions. Contains "Who this is for", "Success looks like" meta-descriptions.
+PROMPT_QUALITY: [skill-name] - CRITICAL: ~200 lines of YAML schemas inline. Move to references/.
+PROMPT_QUALITY: [skill-name] - CRITICAL: No "What To Do" section. Claude won't know what action to take.
+```
+
+---
+
+### CHECK 1: Content That Should Be in References
+
+**Read the SKILL.md and identify content that doesn't belong:**
+
+| Content Type | Should Be In | Why |
+|--------------|--------------|-----|
+| YAML/JSON schemas | `references/schemas.md` | Loaded only when needed |
+| Detailed phase explanations | `references/phaseN.md` | Progressive disclosure |
+| Examples >10 lines | `references/examples.md` | Keep SKILL.md lean |
+| API documentation | `references/api.md` | Not needed upfront |
+| Historical context | `references/background.md` | Not actionable |
+
+**Count lines of inline content that should be moved:**
+- Code blocks >20 lines
+- Tables >10 rows
+- Schema definitions
+- Detailed explanations of internals
+
+**Record issues:**
+```
+CONTENT: [skill-name] - ~150 lines of YAML schemas should be in references/
+CONTENT: [skill-name] - Phase explanations (lines 50-200) should be in separate phase files
+CONTENT: [skill-name] - "Key Design Principles" section is background, not instructions
+```
 
-### Check 1: Structure Validation
+---
+
+### CHECK 2: Router Pattern (for complex skills)
+
+**If the skill has multiple workflows or phases:**
+
+Does SKILL.md act as a lean router that:
+1. Asks/determines what to do
+2. Routes to the appropriate reference file
+3. Lets the reference file contain the detailed instructions
+
+**Good pattern:**
+```markdown
+<step name="Route to Phase">
+| currentPhase | Action |
+|--------------|--------|
+| phase1 | Read `references/phase1.md` |
+| phase2 | Read `references/phase2.md` |
+</step>
+```
+
+**Bad pattern:**
+```markdown
+## Phase 1: Scaffolding
+[100 lines of phase 1 instructions]
+
+## Phase 2: Discovery
+[100 lines of phase 2 instructions]
+
+## Phase 3: Analysis
+[100 lines of phase 3 instructions]
+```
+
+**Record issues:**
+```
+ROUTER: [skill-name] - Has 12 phases but all instructions inline. Should route to reference files.
+ROUTER: [skill-name] - references/ directory exists but SKILL.md doesn't route to it.
+```
+
+---
+
+### CHECK 3: Structure Validation
 
 **Verify:**
 - [ ] SKILL.md exists
@@ -81,112 +225,81 @@ For each skill in scope, perform these checks:
 
 **Record issues:**
 ```
-STRUCTURAL: [skill-name] - [specific issue]
+STRUCTURE: [skill-name] - [specific issue]
 ```
 
-### Check 2: Description Quality
+---
+
+### CHECK 4: Description Quality
 
 **Read the description and verify:**
 - [ ] Under 1024 characters
 - [ ] Uses third person ("This skill should be used when...")
-- [ ] Contains specific trigger phrases (quoted examples of what users say)
+- [ ] Contains specific trigger phrases users would say
 - [ ] Explains WHEN to use, not just WHAT it does
-- [ ] Not overly detailed about implementation
-
-**Red flags:**
-- Starts with "Use this skill" (wrong person)
-- No quoted trigger phrases
-- Only describes functionality, not activation scenarios
-- Over 1024 characters
 
 **Record issues:**
 ```
 DESCRIPTION: [skill-name] - [specific issue]
 ```
 
-### Check 3: Writing Style
+---
 
-**Scan SKILL.md body for:**
+### CHECK 5: Writing Style
 
-**Second person violations:**
-- "you should"
-- "you can"
-- "you need"
-- "you might"
-- "you will"
-- "your"
+**Scan for second person:**
+- "you should", "you can", "you need", "you might", "your"
 
-**Passive voice (less critical but note):**
-- "should be"
-- "can be"
-- "is done"
-
-**Negative framing:**
-- "don't"
-- "never"
-- "avoid"
-- "do not"
+**Scan for negative framing:**
+- "don't", "never", "avoid", "do not"
 
 **Record issues:**
 ```
-STYLE: [skill-name] - Found [count] instances of second person ("you should", etc.)
-STYLE: [skill-name] - Found negative framing: "[example]"
+STYLE: [skill-name] - Found [count] instances of second person
+STYLE: [skill-name] - Negative framing: "[example]"
 ```
 
-### Check 4: Size Analysis
+---
+
+### CHECK 6: Size Analysis
 
 **Measure:**
-- Word count of SKILL.md body (excluding frontmatter)
-- Line count of SKILL.md
+- Word count of SKILL.md body
+- Line count
 
 **Thresholds:**
-| Metric | Good | Warning | Problem |
-|--------|------|---------|---------|
+| Metric | Good | Warning | Critical |
+|--------|------|---------|----------|
 | Words | <2,000 | 2,000-3,500 | >3,500 |
 | Lines | <300 | 300-500 | >500 |
 
-**If oversized:**
-- Check if references/ directory exists
-- If no references/, skill needs restructuring
-
 **Record issues:**
 ```
-SIZE: [skill-name] - SKILL.md is [X] words ([Y] lines) - consider moving content to references/
+SIZE: [skill-name] - SKILL.md is [X] words ([Y] lines) - needs restructuring
 ```
 
-### Check 5: Progressive Disclosure
-
-**Check structure:**
-- Does skill have references/ directory?
-- Does skill have scripts/ directory?
-- Does SKILL.md reference these resources?
-
-**Verify references are used:**
-- For each file in references/, check if SKILL.md mentions it
-- For each file in scripts/, check if SKILL.md mentions it
-- Flag unreferenced resources
-
-**Record issues:**
-```
-DISCLOSURE: [skill-name] - references/patterns.md exists but is never referenced in SKILL.md
-DISCLOSURE: [skill-name] - Large SKILL.md with no references/ directory
-```
+---
 
-### Check 6: Reference Integrity
+### CHECK 7: Reference Integrity
 
 **For every path mentioned in SKILL.md:**
-- `references/*.md` files exist
-- `scripts/*.js` or `scripts/*.py` files exist
-- `assets/*` files exist
+- Verify file exists
+- Flag broken references
+
+**For every file in references/:**
+- Check if SKILL.md mentions it
+- Flag orphaned files
 
 **Record issues:**
 ```
-BROKEN: [skill-name] - References `references/workflow.md` but file doesn't exist
+BROKEN: [skill-name] - References `references/phase1.md` but file doesn't exist
+ORPHAN: [skill-name] - `references/old-workflow.md` exists but isn't referenced
 ```
+
 </step>
 
 <step name="Generate Report">
-Compile findings into a structured report.
+Compile findings, prioritizing CRITICAL issues first.
 
 **Report format:**
 
@@ -195,140 +308,122 @@ Compile findings into a structured report.
 
 Generated: [timestamp]
 Skills audited: [count]
-Location(s): [user/project/source]
 
-## Summary
+## Critical Issues (Fix Immediately)
 
-| Status | Count |
-|--------|-------|
-| Passing | [X] |
-| Warnings | [Y] |
-| Failing | [Z] |
+### [skill-name]
+- PROMPT_QUALITY: Written as documentation, not instructions
+  - Contains "Who this is for:", "Success looks like:" meta-descriptions
+  - No clear "What To Do" section
+  - ~200 lines of inline YAML schemas
 
-## Skills Passing All Checks
+  **This skill will not work properly.** Claude won't know what action to take.
 
-- skill-name-1
-- skill-name-2
-
-## Skills with Warnings
+## Warnings
 
 ### [skill-name]
-- SIZE: SKILL.md is 2,500 words - consider refactoring
+- SIZE: 2,800 words - consider moving content to references/
+- STYLE: 3 instances of negative framing
 
-## Skills with Failures
+## Passing
 
-### [skill-name]
-- STRUCTURAL: Missing `description` in frontmatter
-- STYLE: Found 15 instances of second person
-- BROKEN: References `scripts/validate.py` but file missing
+- skill-name-1
+- skill-name-2
 
 ## Recommendations
 
-[Prioritized list of what to fix first]
+1. **[skill-name]**: Complete rewrite needed. Current version is documentation, not a prompt.
+2. **[other-skill]**: Move YAML schemas to references/schemas.md
 ```
 
 **Present the report to the user.**
 </step>
 
 <step name="Offer Fixes">
-After presenting the report, offer to fix issues.
+After presenting the report, offer to help fix issues.
 
-Use `AskUserQuestion`:
-- **Fix all auto-fixable issues** - Apply safe fixes automatically
-- **Fix specific skill** - Work on one skill at a time
-- **Just the report** - No fixes, user will handle manually
-- **Create modification tasks** - Add to todo list for later
-
-**Auto-fixable issues:**
-- Second person → imperative form conversion
-- Negative framing → positive framing conversion
-- Missing frontmatter fields (can prompt for values)
-
-**Manual-fix-required issues:**
-- Oversized SKILL.md (needs content decisions)
-- Missing referenced files (needs content creation)
-- Vague descriptions (needs user input on triggers)
-
-If user wants fixes, transition to `references/modify.md` for each skill that needs work.
-</step>
+**For CRITICAL prompt quality issues:**
+Offer to help rewrite the skill properly. This requires:
+1. Understanding what the skill should DO
+2. Rewriting as instructions, not documentation
+3. Moving heavy content to references/
+4. Creating proper router pattern
 
-</steps>
+**For other issues:**
+- Second person → imperative conversion
+- Negative → positive framing
+- Content moves to references/
 
-## Audit Checklist (Quick Reference)
+Use `AskUserQuestion`:
+- **Help fix critical issues** - Work through rewriting problematic skills
+- **Fix style issues only** - Auto-fix second person, negative framing
+- **Just the report** - No fixes now
 
-For quick manual audits, use this checklist:
+If user wants to fix critical issues, transition to `references/modify.md`.
+</step>
 
-### Must Pass
-- [ ] SKILL.md exists with valid YAML frontmatter
-- [ ] `name` and `description` fields present
-- [ ] `name` matches directory name (hyphen-case)
-- [ ] `description` under 1024 characters
-- [ ] `description` uses third person
-- [ ] `description` has trigger phrases
-- [ ] No second person in body
-- [ ] All referenced files exist
+</steps>
 
-### Should Pass
-- [ ] SKILL.md under 2,000 words
-- [ ] Uses imperative form throughout
-- [ ] Positive framing (no "don't", "never")
-- [ ] references/ used for heavy content
-- [ ] All resources in skill directory are referenced
+## Quick Audit Checklist
 
-### Nice to Have
-- [ ] Examples included
-- [ ] Clear section structure
-- [ ] Scripts for deterministic operations
+### Critical (Must Fix)
+- [ ] SKILL.md is written as instructions, not documentation
+- [ ] No meta-descriptions ("Who this is for", "Success looks like")
+- [ ] Clear "What To Do" section with concrete steps
+- [ ] Heavy content (schemas, examples) in references/, not inline
+- [ ] Router pattern used for multi-phase skills
 
-## Common Audit Findings
+### Important
+- [ ] Valid frontmatter with name and description
+- [ ] Description has trigger phrases
+- [ ] Under 2,000 words
+- [ ] All references exist
 
-### Finding: Many Skills Use Second Person
+### Style
+- [ ] No second person
+- [ ] Positive framing
+- [ ] Imperative form
 
-**Pattern:** "You should...", "You can...", "You need..."
+## Anti-Patterns to Catch
 
-**Fix approach:**
-```
-Before: "You should parse the config file first."
-After:  "Parse the config file first."
+### The Documentation Skill
+**Pattern:** Reads like a README explaining what the skill does.
+```markdown
+## Purpose
+This skill helps developers migrate forms...
 
-Before: "You can use grep to search."
-After:  "Use grep to search."
+## Who This Is For
+Developers working on Oracle Forms migration.
 
-Before: "If you need to validate, you should run the tests."
-After:  "To validate, run the tests."
+## How It Works
+The skill has 12 phases...
 ```
 
-### Finding: Descriptions Are Vague
-
-**Pattern:** "Helps with X" or "Provides Y guidance"
+**Problem:** Claude reads this and thinks "interesting, but what should I DO?"
 
-**Fix approach:**
-1. Ask user what they say when they need this skill
-2. Collect 5-10 trigger phrases
-3. Rewrite in third person with phrases
+**Fix:** Rewrite as instructions:
+```markdown
+## What To Do Now
 
-### Finding: SKILL.md Is Too Large
+<step name="Get Form Name">
+Ask which form to implement.
+</step>
 
-**Pattern:** >3,000 words with no references/
+<step name="Route to Current Phase">
+Read workflow.yaml, route to appropriate phase file.
+</step>
+```
 
-**Fix approach:**
-1. Identify logical sections
-2. Move detailed content to references/
-3. Keep routing and essential knowledge in SKILL.md
-4. Add explicit references: "For detailed patterns, read `references/patterns.md`"
+### The Kitchen Sink Skill
+**Pattern:** Everything inline, no progressive disclosure.
 
-### Finding: Unreferenced Resources
+**Problem:** 500+ lines, Claude gets lost in irrelevant details.
 
-**Pattern:** Files exist in references/ or scripts/ but SKILL.md doesn't mention them
+**Fix:** Keep SKILL.md as router (<150 lines), move details to references/.
 
-**Fix approach:**
-1. Determine if resource is needed
-2. If needed, add reference in SKILL.md
-3. If not needed, consider removing
+### The Schema Dump
+**Pattern:** 100+ lines of YAML/JSON schemas inline.
 
-## Output
+**Problem:** Schemas are reference material, not instructions.
 
-The audit produces:
-1. **Report** - Comprehensive findings for all audited skills
-2. **Recommendations** - Prioritized list of improvements
-3. **Optional fixes** - Automated corrections for simple issues
+**Fix:** Move to `references/schemas.md`, reference when needed.