cc-dev-template 0.1.6 → 0.1.8

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

@@ -1,7 +1,5 @@
 # Skill Development Principles
 
-This document contains the deep knowledge required to create, audit, and modify Claude Code skills correctly. Read this before any skill work.
-
 ## The Fundamental Truth
 
 **A skill is just a prompt with progressive disclosure.**
@@ -16,45 +14,92 @@ This document contains the deep knowledge required to create, audit, and modify
 
 When a skill "activates," Claude simply reads the SKILL.md file. The file contains natural language instructions telling Claude what to do.
 
-## Why Progressive Disclosure Matters
+## The Most Common Mistake: Documentation vs Instructions
+
+**This is the #1 reason skills fail.** People write SKILL.md as if it's a README explaining what the skill does. But SKILL.md IS the prompt—it must tell Claude what to DO.
+
+### Documentation (WRONG)
+
+```markdown
+## Purpose
+
+This skill orchestrates the complete migration of Oracle Forms to React/Go.
+
+**Who this is for**: Developers migrating Oracle Forms.
 
-### The Problem Without Skills
+**Success looks like**: Running /implement-form progresses through all phases.
 
-To handle a complex workflow, all instructions must be in one giant prompt:
+## How It Works
 
+The skill has 12 phases. Phase 1 does scaffolding, Phase 2 does discovery...
 ```
-Here's how to plan a feature:
-1. First gather requirements...     [500 lines]
-2. Then explore the codebase...     [500 lines]
-3. Then check ADRs...               [500 lines]
-4. Then draft the plan...           [500 lines]
-5. Then validate...                 [500 lines]
-6. Then finalize...                 [500 lines]
+
+**Why this fails:** Claude reads this and thinks "interesting information, but what should I DO right now?" There are no actionable instructions.
+
+### Instructions (CORRECT)
+
+```markdown
+## What To Do Now
+
+<step name="Get Form Name">
+Ask which form to implement. Store the form name.
+</step>
+
+<step name="Check Workflow State">
+Look for `.claude/workflows/{formname}/workflow.yaml`
+
+If exists: Read it, determine current phase.
+If not: Create new workflow, start at phase 1.
+</step>
+
+<step name="Route to Phase">
+Based on `currentPhase`, read the appropriate file:
+
+| Phase | File |
+|-------|------|
+| phase1 | `references/phase1.md` |
+| phase2 | `references/phase2.md` |
+</step>
 ```
 
-**Problems:**
-- Massive context consumption upfront (3,000+ lines)
+**Why this works:** Claude knows exactly what to do. Each step is an action. Heavy content (schemas, phase details) lives in references/.
+
+### Red Flags in SKILL.md
+
+| Red Flag | Problem |
+|----------|---------|
+| "Who this is for:" | Meta-description. Claude doesn't need audience info. |
+| "Success looks like:" | Describes outcomes, doesn't instruct. |
+| "This skill orchestrates..." | Describes what skill IS, not what to DO. |
+| "The purpose is..." | Documentation language. |
+| Large inline schemas | Reference material, not instructions. |
+| Phase explanations | Should route to phase files, not explain inline. |
+
+### The Test
+
+After writing SKILL.md, ask: **"If Claude reads this right now, does it know what action to take?"**
+
+If the answer is "it would understand what the skill is about" but not "it would know what to do," rewrite it.
+
+## Progressive Disclosure
+
+### The Problem Without It
+
+To handle a complex workflow, all instructions must be in one giant prompt (3,000+ lines). Problems:
+- Massive context consumption upfront
 - Claude may get confused by irrelevant instructions
 - Hard to maintain and update
-- Scales poorly—can't add new capabilities without bloating context
+- Scales poorly
 
 ### The Solution: Three-Level Loading
 
-Skills use progressive disclosure to load information just-in-time:
-
 | Level | What Loads | When | Size Target |
 |-------|------------|------|-------------|
 | **1. Metadata** | `name` + `description` | Always (at startup) | ~100 words |
-| **2. SKILL.md body** | Full instructions | When skill triggers | 1,500-2,000 words |
-| **3. Bundled resources** | references/, scripts/, assets/ | Only when Claude needs them | Unlimited |
+| **2. SKILL.md body** | Full instructions | When skill triggers | <2,000 words |
+| **3. Bundled resources** | references/, scripts/ | Only when Claude needs them | Unlimited |
 
-**Benefits:**
-- Small initial context footprint
-- Claude only sees relevant instructions for current phase
-- Easy to add/modify individual phases
-- Scales infinitely—heavy content lives in references/
-
-### Progressive Disclosure in Practice
+### In Practice
 
 ```
 SKILL.md (small router):
@@ -64,13 +109,9 @@ SKILL.md (small router):
 references/planning.md:
   "Gather requirements.
    When done → read references/drafting.md"
-
-references/drafting.md:
-  "Create the plan artifact.
-   When done → read references/validation.md"
 ```
 
-If the user stops after planning, drafting and validation instructions are never loaded.
+If the user stops after planning, drafting instructions are never loaded.
 
 ## Frontmatter Requirements
 
@@ -97,124 +138,35 @@ description: What this skill does and when to use it
 
 The description is the most important part of a skill. Claude uses it to decide whether to activate.
 
-**Third-person format with trigger phrases:**
-
+**Good (specific triggers, third person):**
 ```yaml
-# GOOD - specific triggers, third person
-description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events (PreToolUse, PostToolUse, Stop).
-
-# GOOD - clear scenarios
-description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", or mentions hook events (PreToolUse, PostToolUse, Stop).
 ```
 
-**Common mistakes:**
-
+**Bad:**
 ```yaml
-# BAD - wrong person
+# Wrong person
 description: Use this skill when working with hooks.
 
-# BAD - vague, no triggers
+# Vague, no triggers
 description: Provides hook guidance.
 
-# BAD - no "when to use"
-description: A skill for managing PDFs.
-
-# BAD - too much detail (makes Claude think it can wing it)
-description: This skill parses PDF files using PyPDF2, extracts text with OCR fallback, handles encrypted files with password prompts, and outputs to markdown format with table preservation...
-```
-
-**Key insight from community testing:** If the description explains too much about WHAT the skill does, Claude believes it already knows enough and won't activate the skill. Keep descriptions focused on WHEN to use, not HOW it works internally.
-
-### Optional Fields
-
-```yaml
----
-name: skill-name
-description: ...
-license: Apache-2.0
-allowed-tools: Read, Grep, Glob, Write
-metadata:
-  version: 1.0.0
-  author: team-name
----
+# Too detailed (Claude thinks it knows enough and won't activate)
+description: This skill parses PDF files using PyPDF2, extracts text with OCR fallback...
 ```
 
-- `allowed-tools`: Restricts which tools Claude can use (security/safety)
-- `license`: For distributed skills
-- `metadata`: Custom key-value pairs
-
-## Writing Style Requirements
-
-### Imperative/Infinitive Form (Mandatory)
-
-Write instructions as directives, not suggestions or descriptions.
-
-**Correct (imperative):**
-```markdown
-Parse the configuration file.
-Extract the relevant fields.
-Validate input before processing.
-Run the test suite to verify changes.
-```
-
-**Incorrect (second person):**
-```markdown
-You should parse the configuration file.
-You can extract the relevant fields.
-You need to validate input before processing.
-You might want to run the test suite.
-```
-
-**Incorrect (passive/descriptive):**
-```markdown
-The configuration file should be parsed.
-Fields are extracted from the response.
-Input validation is performed.
-```
-
-### Objective Instructional Tone
-
-Focus on WHAT to do, not WHO should do it:
-
-**Correct:**
-```markdown
-To accomplish X, do Y.
-For validation, check the following criteria.
-When errors occur, retry with exponential backoff.
-```
-
-**Incorrect:**
-```markdown
-You can accomplish X by doing Y.
-Claude should check the following criteria.
-If you encounter errors, you might retry.
-```
-
-### Positive Framing
-
-Tell Claude what TO do, not what NOT to do:
-
-| Negative (avoid) | Positive (correct) |
-|------------------|-------------------|
-| Don't hallucinate facts | Only use information from provided documents |
-| Don't be too formal | Write in a conversational, friendly tone |
-| Avoid long paragraphs | Keep paragraphs to 3-4 sentences |
-| Don't skip error handling | Include comprehensive error handling |
-| Never make assumptions | Base responses on provided data |
+**Key insight:** If the description explains too much about WHAT, Claude believes it already knows enough and won't activate. Focus on WHEN to use, not HOW it works.
 
 ## Skill Structure
 
-### Minimal Skill
-
+### Minimal
 ```
 skill-name/
 └── SKILL.md
 ```
-
 Good for: Simple knowledge, no complex workflows
 
-### Standard Skill (Recommended)
-
+### Standard (Recommended)
 ```
 skill-name/
 ├── SKILL.md
@@ -223,64 +175,34 @@ skill-name/
 └── scripts/
     └── helper.py
 ```
-
 Good for: Most skills with detailed documentation or utilities
 
-### Complete Skill
-
-```
-skill-name/
-├── SKILL.md              # Lean router
-├── references/           # Docs loaded as needed
-│   ├── workflow-1.md
-│   ├── workflow-2.md
-│   └── patterns.md
-├── scripts/              # Executable utilities
-│   ├── validate.py
-│   └── generate.sh
-└── assets/               # Files for output (templates, etc.)
-    └── template.yaml
-```
-
-Good for: Complex multi-workflow skills
-
 ### When to Use Each Directory
 
-**references/** - Documentation that Claude should read into context:
+**references/** - Content Claude reads into context:
 - Detailed workflow instructions
 - Domain knowledge and patterns
-- API documentation
 - Schemas and specifications
 
 **scripts/** - Executable code for deterministic operations:
 - Validation utilities
 - Code generation
-- Data transformation
 - File operations that need reliability
 
-**Benefits of scripts:** Execute without loading into context (token-efficient), deterministic reliability, can be tested independently
-
 **assets/** - Files used in output but never read:
 - Templates Claude copies/modifies
 - Boilerplate code
-- Images, icons, fonts
-- Sample documents
 
 ## Size Guidelines
 
-### SKILL.md Body
-- **Target**: 1,500-2,000 words
-- **Maximum**: 5,000 words (strongly discouraged)
-- **Anthropic guidance**: Under 500 lines
+- **SKILL.md target**: <2,000 words
+- **SKILL.md maximum**: 5,000 words (strongly discouraged)
 
-If SKILL.md exceeds these limits, move content to references/.
+If SKILL.md exceeds limits, move content to references/.
 
-### Why Size Matters
+> "The context window is a public good—your skill shares it with everything else."
 
-> "The context window is a public good—your skill shares it with everything else. Once loaded, every token competes with conversation history."
-> — Anthropic Engineering
-
-Challenge every piece of content: Does it justify its token cost? If Claude already knows it (general programming knowledge, common patterns), remove it.
+Challenge every piece of content: Does it justify its token cost? If Claude already knows it, remove it.
 
 ## Activation Patterns
 
@@ -288,250 +210,41 @@ Challenge every piece of content: Does it justify its token cost? If Claude alre
 
 **1. Autonomous (Description Match)**
 Claude reads skill descriptions and decides when to activate based on user request matching.
-
-- Less reliable (~50-84% success rate in community testing)
+- Less reliable (~50-84% success rate)
 - Works better with specific trigger phrases
-- Can fail if description is too detailed (Claude thinks it knows enough)
+- Fails if description is too detailed
 
 **2. Explicit (Slash Command)**
 A slash command forces skill activation:
-
 ```markdown
 # /create-skill command
 Activate the create-agent-skills skill to guide the user through skill creation.
 ```
-
-- Most reliable method
-- Use for critical workflows
-- Don't rely solely on autonomous activation
+Most reliable method.
 
 **3. Hybrid (Recommended)**
 Slash command for explicit invocation + good description for autonomous discovery.
 
-### Improving Activation Reliability
-
-1. **Specific trigger phrases** in description
-2. **Reference in CLAUDE.md** for project skills
-3. **Keep description focused on WHEN**, not detailed HOW
-
 ## Common Mistakes
 
 ### Mistake 1: Treating SKILL.md as Documentation
-
-**Problem:** Writing about the skill instead of instructions for Claude
-
-```markdown
-# BAD - describes the skill
-This skill helps users create PDF documents. It uses PyPDF2
-for parsing and supports various output formats...
-```
-
-```markdown
-# GOOD - instructs Claude
-Parse the input PDF using the bundled script.
-Extract text content, preserving table structure.
-Output as markdown with proper heading hierarchy.
-```
+Writing about the skill instead of instructions for Claude.
 
 ### Mistake 2: Everything in One File
-
-**Problem:** Putting all content in SKILL.md
-
-```
-skill-name/
-└── SKILL.md  (8,000 words)
-```
-
-**Solution:** Use progressive disclosure
-
-```
-skill-name/
-├── SKILL.md  (1,800 words - router)
-└── references/
-    ├── workflow-a.md (2,500 words)
-    └── workflow-b.md (3,700 words)
-```
+Putting all content in SKILL.md instead of using references/.
 
 ### Mistake 3: Vague Descriptions
+No trigger phrases, unclear when to use.
 
-**Problem:** No trigger phrases, unclear when to use
-
-```yaml
-description: Helps with code review.
-```
-
-**Solution:** Specific scenarios and phrases
-
-```yaml
-description: This skill should be used when the user asks to "review this PR", "check my code", "find bugs", or mentions code quality, security review, or performance analysis.
-```
-
-### Mistake 4: Second Person Writing
-
-**Problem:** Using "you" throughout
-
-```markdown
-You should first read the config file.
-Then you can parse the fields.
-You might want to validate the output.
-```
-
-**Solution:** Imperative form
-
-```markdown
-First read the config file.
-Parse the fields using the schema.
-Validate output against expected format.
-```
-
-### Mistake 5: Missing Resource References
-
-**Problem:** References exist but SKILL.md doesn't mention them
-
-```markdown
-# SKILL.md
-[Content with no mention of references/]
-```
-
-**Solution:** Explicit pointers to resources
-
-```markdown
-## Additional Resources
-
-For detailed patterns, read `references/patterns.md`.
-For validation, run `scripts/validate.py`.
-```
-
-## Prompting Principles for Skill Content
-
-Skills ARE prompts. The quality of a skill depends on applying good prompting principles when writing its content. These principles come from ADR-002 (Structured Prompting Practices) and the `prompting` skill.
-
-### Core Principle: Explain WHY, Not Just WHAT
-
-Provide purpose and context rather than exhaustive implementation details. Trust Claude's intelligence.
-
-**Mental Model**: Treat Claude like a brilliant senior colleague, not a junior who needs hand-holding.
-
-**Provide:**
-- The goal or purpose of the task
-- Why this matters (business context, use case)
-- Constraints that exist (technical, business, regulatory)
-- What success looks like
-
-**Avoid providing:**
-- Every possible edge case (Claude handles these intelligently)
-- Step-by-step implementation unless genuinely needed
-- Obvious best practices for the domain
-
-### Use Positive Framing
-
-Tell Claude what TO do, not what NOT to do. Negatives require extra processing and can prime unwanted behavior.
-
-| Negative Framing | Positive Framing |
-|------------------|------------------|
-| "Don't hallucinate facts" | "Only use information from the provided documents" |
-| "Don't be too verbose" | "Keep responses concise and focused" |
-| "Avoid making assumptions" | "Base responses on the provided data" |
-| "Never skip validation" | "Always validate input before processing" |
-
-### Be Clear and Direct
-
-Claude 4.x models are more literal than previous versions. State exactly what is needed without hedging.
+### Mistake 4: Missing Resource References
+References exist but SKILL.md doesn't mention them.
 
-| Vague | Clear |
-|-------|-------|
-| "Maybe consider validating..." | "Validate input before processing" |
-| "It might be helpful to..." | "Include error handling for edge cases" |
-| "You could potentially..." | "Generate tests for all public functions" |
+## Validation
 
-### Provide Context
+Run: `node ~/.claude/skills/create-agent-skills/scripts/validate-skill.js [skill-path]`
 
-Every skill instruction benefits from context. Answer:
-1. **Why does this matter?** (Purpose, goal)
-2. **Who is this for?** (Audience, user type)
-3. **What does success look like?** (Outcomes, criteria)
-4. **What constraints exist?** (Technical limits, requirements)
-
-### The Complete Prompt Checklist
-
-When writing skill content, verify each section answers:
-
-- [ ] **WHAT** is Claude being asked to do?
-- [ ] **WHY** does this matter? (Purpose, goal)
-- [ ] **WHO** is this for? (Audience, user type)
-- [ ] **SUCCESS** looks like what? (Outcomes, criteria)
-- [ ] Frame everything **POSITIVELY** (what TO do)
-
-### Quick Diagnostics
-
-If a skill produces problematic results:
-
-| Problem | Likely Cause | Fix |
-|---------|--------------|-----|
-| Too minimal/basic | Not explicit about expectations | Add "Create a fully-featured..." or specify depth |
-| Off-topic | Missing context about purpose | Explain WHY and what it's for |
-| Inconsistent | Vague instructions | Be more direct and specific |
-| Overly cautious | Negative framing | Reframe positively |
-| Missing key details | Didn't explain success criteria | Define concrete outcomes |
-
-### Common Antipatterns
-
-**The Micromanager**: Providing step-by-step implementation instead of goals.
-- Fix: Explain the goal, let Claude handle implementation.
-
-**The Negative Nancy**: String of "don't do X" instructions.
-- Fix: Reframe every negative as a positive instruction.
-
-**The Context-Free Zone**: Bare instruction with no purpose or audience.
-- Fix: Explain who uses it, why it exists, what success looks like.
-
-**The Vague Suggestion**: Hedged language like "maybe consider..."
-- Fix: Be direct and explicit about what is needed.
-
-### Reference
-
-For comprehensive prompting guidance, consult:
-- **ADR-002**: Structured Prompting Practices for Agents and Commands
-- **Prompting skill**: `~/.claude/skills/prompting/SKILL.md`
-
-These principles are mandatory for all skill content. Apply them when writing SKILL.md files and reference documents.
-
-## Validation Checklist
-
-Before finalizing any skill, verify:
-
-### Structure
-- [ ] SKILL.md exists with valid YAML frontmatter
-- [ ] `name` field matches directory name (hyphen-case)
-- [ ] `description` field present and under 1024 characters
-- [ ] All referenced files actually exist
-
-### Description Quality
-- [ ] Uses third person ("This skill should be used when...")
-- [ ] Includes specific trigger phrases
-- [ ] Lists concrete scenarios
-- [ ] Not overly detailed about implementation
-
-### Content Quality
-- [ ] Body uses imperative/infinitive form throughout
-- [ ] No second person ("you should", "you can")
-- [ ] Body under 2,000 words (or content moved to references/)
-- [ ] Positive framing (what TO do, not what NOT to do)
-
-### Prompting Quality
-- [ ] Explains WHY, not just WHAT (purpose and context provided)
-- [ ] Clear and direct language (no hedging or vague suggestions)
-- [ ] Success criteria defined (what does good output look like?)
-- [ ] Avoids micromanagement (goals over step-by-step instructions)
-- [ ] No antipatterns (Micromanager, Negative Nancy, Context-Free Zone, Vague Suggestion)
-
-### Progressive Disclosure
-- [ ] SKILL.md acts as router to heavier content
-- [ ] Detailed docs in references/
-- [ ] Deterministic operations in scripts/
-- [ ] References clearly pointed to from SKILL.md
-
-### Testing
-- [ ] Skill triggers on expected user queries
-- [ ] Content is helpful for intended tasks
-- [ ] No duplicated information across files
+Manual checks:
+- Is this instructions, not documentation?
+- Would Claude know what to DO?
+- Is heavy content in references/?
+- Does the description have trigger phrases?

package/src/skills/create-agent-skills/templates/router-skill.md

@@ -0,0 +1,73 @@
+---
+name: {{SKILL_NAME}}
+description: {{What it does}} Use when {{trigger conditions}}.
+---
+
+<essential_principles>
+## {{Core Concept}}
+
+{{Principles that ALWAYS apply, regardless of which workflow runs}}
+
+### 1. {{First principle}}
+{{Explanation}}
+
+### 2. {{Second principle}}
+{{Explanation}}
+
+### 3. {{Third principle}}
+{{Explanation}}
+</essential_principles>
+
+<intake>
+**Ask the user:**
+
+What would you like to do?
+1. {{First option}}
+2. {{Second option}}
+3. {{Third option}}
+
+**Wait for response before proceeding.**
+</intake>
+
+<routing>
+| Response | Workflow |
+|----------|----------|
+| 1, "{{keywords}}" | `workflows/{{first-workflow}}.md` |
+| 2, "{{keywords}}" | `workflows/{{second-workflow}}.md` |
+| 3, "{{keywords}}" | `workflows/{{third-workflow}}.md` |
+
+**After reading the workflow, follow it exactly.**
+</routing>
+
+<quick_reference>
+## {{Skill Name}} Quick Reference
+
+{{Brief reference information always useful to have visible}}
+</quick_reference>
+
+<reference_index>
+## Domain Knowledge
+
+All in `references/`:
+- {{reference-1.md}} - {{purpose}}
+- {{reference-2.md}} - {{purpose}}
+</reference_index>
+
+<workflows_index>
+## Workflows
+
+All in `workflows/`:
+
+| Workflow | Purpose |
+|----------|---------|
+| {{first-workflow}}.md | {{purpose}} |
+| {{second-workflow}}.md | {{purpose}} |
+| {{third-workflow}}.md | {{purpose}} |
+</workflows_index>
+
+<success_criteria>
+A well-executed {{skill name}}:
+- {{First criterion}}
+- {{Second criterion}}
+- {{Third criterion}}
+</success_criteria>