cc-dev-template 0.1.6 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/skills/create-agent-skills/SKILL.md

@@ -5,91 +5,47 @@ description: Expert guidance for creating, modifying, and auditing Claude Code s
 
 # Create Agent Skills
 
-Expert guidance for building Claude Code skills correctly. Skills are prompts with progressive disclosure—they teach Claude how to perform specific tasks repeatedly and reliably.
-
-## Why Skills Exist
-
-Skills solve one problem: **context window efficiency through progressive disclosure**.
-
-Without skills, complex workflows require loading thousands of lines of instructions upfront. With skills:
-- **Level 1**: Metadata (~100 words) loads at startup for all skills
-- **Level 2**: SKILL.md body (1,500-2,000 words) loads only when triggered
-- **Level 3**: references/, scripts/, assets/ load only when needed
-
-This means Claude can have access to unlimited specialized knowledge without paying the context cost until actually needed.
-
 ## What To Do Now
 
-Determine what the user wants to accomplish with skills.
-
 <step name="Understand Intent">
-Ask the user what they want to do:
+Ask what the user wants to do with skills.
 
-Use `AskUserQuestion` with these options:
-- **Create a new skill** - Build a skill from scratch through guided conversation
-- **Audit existing skills** - Review all skills for best practices compliance
+Use `AskUserQuestion`:
+- **Create a new skill** - Build a skill through guided conversation
+- **Audit existing skills** - Review skills for best practices compliance
 - **Modify a skill** - Update or improve an existing skill
-- **Something else** - Free-form request for other needs
+- **Something else** - Free-form request
 </step>
 
 <step name="Route to Workflow">
-Based on the user's choice:
+Based on choice, read the appropriate workflow:
 
 | Choice | Action |
 |--------|--------|
-| Create a new skill | Read `references/create.md` |
-| Audit existing skills | Read `references/audit.md` |
-| Modify a skill | Read `references/modify.md` |
-| Something else | Help them find the right workflow |
-
-Reading the workflow file is mandatory—it contains the detailed instructions for that workflow.
+| Create | Read `references/create.md` |
+| Audit | Read `references/audit.md` |
+| Modify | Read `references/modify.md` |
+| Something else | Help find the right approach |
 </step>
 
-## Core Skill Principles (Quick Reference)
-
-Before routing, understand these fundamentals that apply to ALL skill work:
-
-### A Skill IS a Prompt
-SKILL.md is not documentation about the skill—it IS what Claude reads when the skill activates. Write it as instructions TO Claude, using imperative form.
-
-### Description = Discovery
-The frontmatter `description` field determines when Claude triggers the skill. Include:
-- Third-person phrasing: "This skill should be used when..."
-- Specific trigger phrases users would say
-- Max 1024 characters
-
-### Structure Matters
-```
-skill-name/
-├── SKILL.md           # Required: lean router (1,500-2,000 words max)
-├── references/        # Detailed docs loaded as needed
-├── scripts/           # Executable utilities (token-efficient)
-└── assets/            # Files used in output, never read into context
-```
-
-### Writing Style
-- **Imperative form**: "Parse the file", "Validate the input"
-- **Never second person**: Avoid phrases like "should parse" or "can validate" with pronouns
-- **Objective instructional tone**: Facts and directives, not suggestions
-
-For complete principles, each workflow will load `references/principles.md` as needed.
-
-## Skill Locations
+## Essential Knowledge
 
-Skills can exist at two levels:
+**A skill IS a prompt.** When activated, Claude reads SKILL.md. It must contain instructions, not documentation about the skill.
 
-| Level | Path | Scope |
-|-------|------|-------|
-| User | `~/.claude/skills/` | Available in all projects |
-| Project | `.claude/skills/` | Shared with team via git |
+**Progressive disclosure.** SKILL.md should be lean (<150 lines). Heavy content goes in references/. This keeps context efficient.
 
-The audit workflow discovers skills at both levels automatically.
+**The test:** After reading SKILL.md, would Claude know what to DO? If it only knows what the skill is about, it's written wrong.
 
-## Bundled Scripts
+For complete principles, workflows load `references/principles.md` as needed.
 
-This skill includes utility scripts for validation and discovery:
+## Quick Reference
 
-- **`scripts/find-skills.js`** - Discovers all skills at user/project levels
-- **`scripts/validate-skill.js`** - Validates a skill against best practices
+**Skill locations:**
+| Level | Path |
+|-------|------|
+| User | `~/.claude/skills/` |
+| Project | `.claude/skills/` |
 
-Run scripts via: `node ~/.claude/skills/create-agent-skills/scripts/[script-name].js`
+**Bundled scripts:**
+- `scripts/find-skills.js` - Discover all installed skills
+- `scripts/validate-skill.js` - Validate a skill's structure

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

@@ -1,334 +1,93 @@
 # 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.
+Read `references/principles.md` first.
 
-## Purpose
+## What To Do
 
-Systematically review skills to identify:
-- 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
+1. **Discover skills** - Run `scripts/find-skills.js` to list available skills
+2. **Ask which to audit** - Get user's choice (all, user-level, project-level, or specific skill)
+3. **Read everything** - Read SKILL.md AND every file in references/, workflows/, scripts/
+4. **Evaluate each file** - Ask: Would Claude know what to DO after reading this?
+5. **Report findings** - Present issues with principle violated and suggested fix
 
-**Success looks like:** A comprehensive report of all skills with specific, actionable findings for any that need improvement.
+## What Makes a Good Skill
 
-## Before Starting
+**Actionability**: Every file tells Claude what to DO, not what the skill is ABOUT.
 
-Read `references/principles.md` if not already familiar with skill standards.
+**Progressive disclosure**: SKILL.md is lean (<150 lines). Heavy content lives in references/. Claude loads what it needs when it needs it.
 
-## Workflow
+**Routing coherence**: Multi-phase skills route to reference files. Each file hands off clearly to the next step or completes the flow.
 
-<steps>
+**No dead ends**: At every point, Claude knows what to do next.
 
-<step name="Discover All Skills">
-Find skills at both user and project levels.
+## How to Audit
 
-**Locations to scan:**
-```
-~/.claude/skills/          # User-level skills
-.claude/skills/            # Project-level skills (current project)
-src/skills/                # Source skills (if in dev-template)
-```
-
-**Run the discovery script:**
-```bash
-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)
-- Location type (user/project/source)
-</step>
-
-<step name="Ask Audit Scope">
-Determine what to audit.
-
-Use `AskUserQuestion`:
-- **All skills** - Review everything discovered
-- **User-level only** - Just ~/.claude/skills/
-- **Project-level only** - Just .claude/skills/
-- **Specific skill** - Name the skill to audit
-
-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:
-
-### Check 1: Structure Validation
-
-**Verify:**
-- [ ] SKILL.md exists
-- [ ] SKILL.md has YAML frontmatter (starts with `---`)
-- [ ] Frontmatter has `name` field
-- [ ] Frontmatter has `description` field
-- [ ] `name` matches directory name
-- [ ] `name` is hyphen-case (lowercase, hyphens only)
-
-**Record issues:**
-```
-STRUCTURAL: [skill-name] - [specific issue]
-```
+### 1. Discover and Read Everything
 
-### Check 2: Description Quality
+Use `scripts/find-skills.js` to list available skills. After selecting a skill to audit:
 
-**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)
-- [ ] Explains WHEN to use, not just WHAT it does
-- [ ] Not overly detailed about implementation
+- Read SKILL.md completely
+- Read every file in references/, workflows/, and any other subdirectories
+- Trace the execution path: if SKILL.md says "read references/phase1.md", read that file too
 
-**Red flags:**
-- Starts with "Use this skill" (wrong person)
-- No quoted trigger phrases
-- Only describes functionality, not activation scenarios
-- Over 1024 characters
+**You cannot audit a skill without reading all its files.**
 
-**Record issues:**
-```
-DESCRIPTION: [skill-name] - [specific issue]
-```
-
-### Check 3: Writing Style
-
-**Scan SKILL.md body for:**
-
-**Second person violations:**
-- "you should"
-- "you can"
-- "you need"
-- "you might"
-- "you will"
-- "your"
-
-**Passive voice (less critical but note):**
-- "should be"
-- "can be"
-- "is done"
-
-**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]"
-```
+### 2. Evaluate Each File
 
-### Check 4: Size Analysis
+For each file, ask:
 
-**Measure:**
-- Word count of SKILL.md body (excluding frontmatter)
-- Line count of SKILL.md
+- After reading this, would Claude know what to DO next?
+- Does this tell Claude what to DO, or just describe what the skill is ABOUT?
+- Does this file hand off clearly to another file, or is there a dead end?
+- Are any referenced files missing?
 
-**Thresholds:**
-| Metric | Good | Warning | Problem |
-|--------|------|---------|---------|
-| Words | <2,000 | 2,000-3,500 | >3,500 |
-| Lines | <300 | 300-500 | >500 |
+### 3. Note External Dependencies
 
-**If oversized:**
-- Check if references/ directory exists
-- If no references/, skill needs restructuring
+If the skill references:
+- Sub-agents (e.g., "spawn adr-agent")
+- Commands (e.g., "run /create-adr")
+- Scripts outside the skill directory
 
-**Record issues:**
-```
-SIZE: [skill-name] - SKILL.md is [X] words ([Y] lines) - consider moving content to references/
-```
+Flag these with their expected locations. They aren't audited here, but the user should know they exist.
 
-### Check 5: Progressive Disclosure
+### 4. Check Structural Basics
 
-**Check structure:**
-- Does skill have references/ directory?
-- Does skill have scripts/ directory?
-- Does SKILL.md reference these resources?
+- SKILL.md has valid YAML frontmatter (name, description)
+- Name matches directory name
+- Description explains WHEN to use (trigger phrases), not just WHAT it does
+- Files referenced in SKILL.md actually exist
 
-**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
+## Red Flags
 
-**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
-```
+**Documentation language**: "This skill orchestrates...", "Who this is for:", "Success looks like:" - these describe, they don't instruct.
 
-### Check 6: Reference Integrity
+**Inline heavy content**: Large YAML schemas, detailed examples, extensive phase explanations - these belong in references/.
 
-**For every path mentioned in SKILL.md:**
-- `references/*.md` files exist
-- `scripts/*.js` or `scripts/*.py` files exist
-- `assets/*` files exist
+**No clear action**: After reading a file, Claude doesn't know what to do next.
 
-**Record issues:**
-```
-BROKEN: [skill-name] - References `references/workflow.md` but file doesn't exist
-```
-</step>
+**Missing routing**: Multi-phase skill but all content inline instead of routing to reference files.
 
-<step name="Generate Report">
-Compile findings into a structured report.
-
-**Report format:**
+## Report Format
 
 ```markdown
-# Skill Audit Report
-
-Generated: [timestamp]
-Skills audited: [count]
-Location(s): [user/project/source]
+# Audit Report: [skill-name]
 
 ## Summary
+- Files audited: [list all files read]
+- External dependencies: [list any sub-agents, commands, scripts referenced]
 
-| Status | Count |
-|--------|-------|
-| Passing | [X] |
-| Warnings | [Y] |
-| Failing | [Z] |
+## Findings
 
-## Skills Passing All Checks
+### [Issue title]
+**File**: [path]
+**Problem**: [what's wrong]
+**Principle**: [which principle is violated - actionability, progressive disclosure, routing, etc.]
+**Suggested fix**: [specific rewrite or change]
 
-- skill-name-1
-- skill-name-2
-
-## Skills with Warnings
-
-### [skill-name]
-- SIZE: SKILL.md is 2,500 words - consider refactoring
-
-## Skills with Failures
-
-### [skill-name]
-- STRUCTURAL: Missing `description` in frontmatter
-- STYLE: Found 15 instances of second person
-- BROKEN: References `scripts/validate.py` but file missing
-
-## Recommendations
-
-[Prioritized list of what to fix first]
+## Passing
+[What works well about this skill]
 ```
 
-**Present the report to the user.**
-</step>
-
-<step name="Offer Fixes">
-After presenting the report, offer to 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>
-
-</steps>
-
-## Audit Checklist (Quick Reference)
-
-For quick manual audits, use this checklist:
-
-### 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
-
-### 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
-
-### Nice to Have
-- [ ] Examples included
-- [ ] Clear section structure
-- [ ] Scripts for deterministic operations
-
-## Common Audit Findings
-
-### Finding: Many Skills Use Second Person
-
-**Pattern:** "You should...", "You can...", "You need..."
-
-**Fix approach:**
-```
-Before: "You should parse the config file first."
-After:  "Parse the config file first."
-
-Before: "You can use grep to search."
-After:  "Use grep to search."
-
-Before: "If you need to validate, you should run the tests."
-After:  "To validate, run the tests."
-```
-
-### Finding: Descriptions Are Vague
-
-**Pattern:** "Helps with X" or "Provides Y guidance"
-
-**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
-
-### Finding: SKILL.md Is Too Large
-
-**Pattern:** >3,000 words with no references/
-
-**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`"
-
-### Finding: Unreferenced Resources
-
-**Pattern:** Files exist in references/ or scripts/ but SKILL.md doesn't mention them
-
-**Fix approach:**
-1. Determine if resource is needed
-2. If needed, add reference in SKILL.md
-3. If not needed, consider removing
-
-## Output
+## After the Audit
 
-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
+Present findings to the user. If issues were found, offer to help fix them. For significant rewrites (documentation → instructions), transition to `references/modify.md`.