cc-dev-template 0.1.6 → 0.1.7

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

@@ -1,370 +1,129 @@
 # Create a New Skill
 
-This workflow guides the creation of a new Claude Code skill through interactive conversation. The goal is to extract domain knowledge from the user and produce a properly structured skill that works correctly on first use.
+Guide the user through building a skill via interactive conversation. Extract their domain knowledge, then produce a properly structured skill.
 
-## Purpose
-
-Transform the user's domain expertise into a reusable skill that:
-- Activates when relevant (good description with trigger phrases)
-- Uses progressive disclosure (lean SKILL.md, heavy content in references/)
-- Follows writing conventions (imperative form, positive framing)
-- Includes appropriate tooling (scripts for deterministic operations)
-
-**Success looks like:** The user can restart Claude Code, ask for help with the task the skill covers, and Claude performs exactly as discussed.
-
-## Before Starting
-
-Read `references/principles.md` to understand skill fundamentals. This workflow assumes familiarity with:
-- Three-level progressive disclosure
-- Frontmatter requirements
-- Writing style (imperative form)
-- Structure patterns
-
-## Workflow
+## What To Do
 
 <steps>
 
-<step name="Understand the Domain">
-Start an open conversation to understand what the user wants the skill to do.
-
-**Ask about:**
-- What task or workflow should this skill handle?
-- What does the user do repeatedly that they want to standardize?
-- What domain knowledge is required that Claude doesn't naturally have?
-- Are there specific tools, APIs, or file formats involved?
-- What does success look like when this task is done well?
-
-**Listen for:**
-- Concrete examples of the task being performed
-- Edge cases and gotchas the user has learned
-- Terminology and concepts specific to this domain
-- Patterns that work well vs. patterns to avoid
-
-**Take time here.** The quality of the skill depends on extracting comprehensive domain knowledge. Ask follow-up questions. Request examples. Understand WHY certain approaches work better than others.
-
-This is a conversation, not an interrogation. Let the user explain naturally and guide them to cover important aspects.
-</step>
+<step name="Have a Conversation">
+Talk with the user to understand what they need. This is the most important step.
 
-<step name="Identify Skill Scope">
-Based on the conversation, determine the skill's scope.
+**Goals of the conversation:**
+- Understand the task they want to standardize
+- Extract domain knowledge Claude doesn't naturally have
+- Learn terminology, patterns, edge cases, gotchas
+- Get concrete examples of the task done well
 
-**Determine:**
-1. **Name**: What should the skill be called? (hyphen-case, descriptive)
-2. **Single vs. Multi-workflow**: Is this one task or multiple related tasks?
-3. **Complexity**: Simple (one file) vs. Standard (with references) vs. Complete (with scripts)?
+**Good questions:**
+- "Walk me through how you do this today."
+- "What's the most important thing to get right?"
+- "What mistakes do people commonly make?"
+- "What would an expert know that a beginner wouldn't?"
 
-**Ask the user:**
-- "Based on what you've described, I'm thinking this skill should be called `[name]` and handle [scope]. Does that capture what you need?"
-- "Should this be a focused skill for just [X], or should it also handle [Y] and [Z]?"
+**Take time here.** The skill's quality depends entirely on understanding the domain deeply. Ask follow-up questions. Request examples. Understand WHY certain approaches work.
 
-**Scope guidance:**
-- **Focused is better**: One skill = one capability
-- **Split if needed**: "document-processing" should become "pdf-editor" + "xlsx-analyzer"
-- **Group if cohesive**: Related tasks that share context can be one skill with routing
+This should feel like a conversation, not a form to fill out.
 </step>
 
-<step name="Design the Structure">
-Plan the skill's file structure before writing anything.
-
-**Determine what's needed:**
+<step name="Determine Scope and Structure">
+Based on the conversation, decide:
 
-| Need | Solution |
-|------|----------|
-| Simple knowledge, single workflow | Minimal: just SKILL.md |
-| Detailed procedures or multiple phases | references/ directory |
-| Repeated code or validation | scripts/ directory |
-| Templates or boilerplate | assets/ directory |
+1. **Name**: What to call it (hyphen-case)
+2. **Scope**: One focused task or multiple related workflows?
+3. **Complexity**: Does it need references/? scripts/? Or just SKILL.md?
 
-**For multi-workflow skills:**
-Plan the routing in SKILL.md and what each reference file covers:
-
-```
-skill-name/
-├── SKILL.md (router: ask user intent, route to workflow)
-└── references/
-    ├── workflow-a.md
-    ├── workflow-b.md
-    └── shared-knowledge.md (if workflows share context)
-```
+**Principles:**
+- Focused is better than broad
+- If it has distinct workflows, use router pattern with references/
+- If it needs reliable code execution, add scripts/
 
-**For skills needing scripts:**
-Identify deterministic operations that should be code:
-
-```
-skill-name/
-├── SKILL.md
-├── references/
-│   └── ...
-└── scripts/
-    ├── validate.py    # Validation that needs reliability
-    └── generate.sh    # Code generation
-```
-
-**Present the plan to the user:**
-"Here's the structure I'm proposing: [describe]. Does this cover everything?"
+Confirm with user: "I'm thinking this should be called `[name]` and cover [scope]. Sound right?"
 </step>
 
 <step name="Craft the Description">
-Write the frontmatter description. This is critical for activation.
-
-**Formula:**
-```
-[What the skill does] + [When to use it with specific trigger phrases]
-```
-
-**Process:**
-1. List 5-10 phrases a user might say when they need this skill
-2. Identify the core capability in one sentence
-3. Combine into third-person description under 1024 characters
-
-**Example construction:**
-
-User phrases:
-- "create a new component"
-- "build me a React component"
-- "make a form component"
-- "scaffold a page"
-- "generate component boilerplate"
-
-Core capability: "Creates React components following team conventions"
-
-Final description:
-```yaml
-description: This skill should be used when the user asks to "create a component", "build a React component", "scaffold a page", "generate component boilerplate", or mentions creating new UI elements. Creates React components following team conventions with proper TypeScript types, styling patterns, and test files.
-```
-
-**Ask the user to validate:**
-"When you need this skill, what would you say to Claude? Let me make sure those phrases are in the description."
-</step>
-
-<step name="Write the Content">
-Generate the skill files following all conventions.
-
-**Writing rules (from principles.md):**
-
-1. **Imperative form**: "Parse the file", not "You should parse"
-2. **Positive framing**: "Use X approach", not "Don't use Y approach"
-3. **Objective tone**: Facts and directives, not suggestions
-4. **Size limits**: SKILL.md under 2,000 words; move detail to references/
-
-**Prompting principles (mandatory for quality skills):**
-
-1. **Explain WHY, not just WHAT**: Provide purpose and context. Trust Claude's intelligence.
-2. **Define success**: What does good output look like? Include concrete criteria.
-3. **Be clear and direct**: No hedging ("maybe consider..."). State what is needed.
-4. **Provide context**: Who is this for? Why does it matter? What constraints exist?
-5. **Avoid micromanagement**: Goals over step-by-step instructions unless complexity requires it.
-
-See `references/principles.md` → "Prompting Principles for Skill Content" for complete guidance.
-
-**SKILL.md structure for simple skills:**
-```markdown
----
-name: skill-name
-description: [crafted description]
----
-
-# Skill Title
-
-[Brief purpose - 1-2 sentences]
-
-## What To Do
-
-[Core instructions in imperative form]
+The description determines when Claude activates the skill. This is critical.
 
-## Key Principles
-
-[Domain knowledge the user shared]
-
-## Examples
-
-[Concrete examples from the conversation]
-```
-
-**SKILL.md structure for routing skills:**
-```markdown
----
-name: skill-name
-description: [crafted description]
----
-
-# Skill Title
-
-[Brief purpose]
-
-## What To Do Now
-
-<step name="Understand Intent">
-Ask what the user wants to accomplish.
-[Options based on workflows]
-</step>
-
-<step name="Route to Workflow">
-| Choice | Action |
-|--------|--------|
-| Option A | Read `references/workflow-a.md` |
-| Option B | Read `references/workflow-b.md` |
-</step>
-
-## Quick Reference
-
-[Shared knowledge that applies to all workflows]
-```
-
-**Reference file structure:**
-```markdown
-# Workflow Name
-
-## Purpose
-
-[What this workflow accomplishes]
-
-## Steps
-
-<steps>
-<step name="Step 1">
-[Instructions]
-</step>
+**Collect trigger phrases from user:**
+"When you need this skill, what would you say to Claude?"
 
-<step name="Step 2">
-[Instructions]
+List 5-10 phrases they might use, then combine into a description that:
+- Uses third person ("This skill should be used when...")
+- Includes the actual trigger phrases
+- Stays under 1024 characters
 </step>
-</steps>
-
-## Key Principles
 
-[Domain knowledge specific to this workflow]
-```
+<step name="Write the Skill">
+Create the skill files. Apply these principles:
 
-**Script considerations:**
-- Use `process.cwd()` for project paths, not `__dirname`
-- Include clear usage comments
-- Handle errors gracefully
-- Make scripts executable (`chmod +x`)
-</step>
+**The skill must be instructions, not documentation.**
+If Claude reads it, it should know what to DO, not just understand what the skill is about.
 
-<step name="Determine Install Location">
-Ask where the skill should be installed.
+**Use progressive disclosure.**
+SKILL.md should be lean (<150 lines for routers, <300 for simple skills). Heavy content goes in references/.
 
-**Options:**
+**Apply prompting guidelines:**
+- Explain WHY, not just WHAT
+- Define what success looks like
+- Be clear and direct
+- Avoid micromanagement - give goals, not step-by-step unless truly needed
 
-| Location | Path | Use When |
-|----------|------|----------|
-| User level | `~/.claude/skills/[name]/` | Personal skill, available everywhere |
-| Project level | `.claude/skills/[name]/` | Team skill, shared via git |
+**Writing style:**
+- Imperative form ("Parse the file", not "You should parse")
+- Positive framing ("Use X approach", not "Don't use Y")
+- No meta-descriptions ("Who this is for", "Success looks like" don't belong in SKILL.md)
 
-**Ask the user:**
-"Should this skill be available in all your projects (user level) or just this project/team (project level)?"
-
-For this dev-template framework, skills typically go to `src/skills/` first, then get installed to user level via the install script.
+Read `references/principles.md` for the full guide on what makes a good skill.
 </step>
 
-<step name="Create the Files">
-Write all skill files to the appropriate location.
-
-**Order:**
-1. Create directory structure
-2. Write SKILL.md
-3. Write reference files (if any)
-4. Write scripts (if any)
-5. Copy assets (if any)
+<step name="Choose Install Location">
+Ask: "Should this be available everywhere (user level) or just this project (project level)?"
 
-**After writing, display:**
-- Full path to each created file
-- Word count for SKILL.md
-- Summary of what was created
+| Level | Path |
+|-------|------|
+| User | `~/.claude/skills/[name]/` |
+| Project | `.claude/skills/[name]/` |
 </step>
 
-<step name="Validate">
-Run validation checks on the created skill.
-
-**Check:**
-- [ ] SKILL.md has valid YAML frontmatter
-- [ ] `name` matches directory name
-- [ ] `description` under 1024 characters
-- [ ] `description` uses third person and has trigger phrases
-- [ ] Body uses imperative form (scan for "you should", "you can")
-- [ ] Body under 2,000 words
-- [ ] All referenced files exist
-- [ ] Scripts are executable (if any)
+<step name="Create and Validate">
+Write the files, then validate:
 
-If validation finds issues, fix them immediately.
-
-**Run the validation script:**
 ```bash
 node ~/.claude/skills/create-agent-skills/scripts/validate-skill.js [skill-path]
 ```
-</step>
 
-<step name="Test Activation">
-Guide the user to test the skill.
-
-**Instructions for user:**
-1. Restart Claude Code (required to pick up new skills)
-2. Start a new conversation
-3. Say one of the trigger phrases from the description
-4. Verify the skill activates and behaves correctly
+Fix any issues found. The validator checks structure, but also manually verify:
+- Is this written as instructions, not documentation?
+- Would Claude know what to DO after reading this?
+- Is heavy content in references/, not inline?
+</step>
 
-**If skill doesn't activate:**
-- Check description has specific trigger phrases
-- Verify skill is in correct location
-- Try explicit invocation first to verify content works
+<step name="Test">
+Guide the user:
+1. Restart Claude Code
+2. Say one of the trigger phrases
+3. Verify the skill activates and behaves as expected
 
-**If skill activates but behaves incorrectly:**
-- Review the instructions—are they clear enough?
-- Check for second-person language that might confuse
-- Verify examples match expected behavior
+If it doesn't work, iterate. The conversation isn't over until the skill works.
 </step>
 
 </steps>
 
-## Conversation Guidance
-
-### Good Questions to Ask
-
-**Understanding the task:**
-- "Walk me through how you do this task today, step by step."
-- "What's the most important thing to get right?"
-- "What mistakes do people commonly make?"
-
-**Extracting domain knowledge:**
-- "Is there terminology I should know for this domain?"
-- "Are there patterns that always work well?"
-- "What would a senior person know that a junior wouldn't?"
-
-**Clarifying scope:**
-- "Should this skill handle [edge case] or is that out of scope?"
-- "Are there related tasks this should also cover?"
-- "What's the minimal version of this skill that would be useful?"
-
-**Validating understanding:**
-- "Let me summarize what I've learned: [summary]. What am I missing?"
-- "Here's a draft of the key instructions. Does this capture your approach?"
-
-### Signs the Conversation Needs More Depth
+## Key Principles
 
-- User gives short, general answers
-- No concrete examples have been shared
-- Edge cases haven't been discussed
-- User says "it depends" without explaining on what
-- The domain has jargon that hasn't been defined
+**The conversation matters most.** A well-structured skill with shallow domain knowledge is worse than a rough skill with deep expertise captured.
 
-**Response:** Ask for specific examples, walk through scenarios, request clarification on terminology.
+**Skills are prompts.** Every SKILL.md will be read by Claude. Write it as instructions, not as a README.
 
-### Signs Ready to Start Writing
+**Trust Claude's intelligence.** Explain goals and principles. Don't micromanage with exact templates unless the task is genuinely complex or error-prone.
 
-- Clear understanding of the core task
-- Multiple concrete examples discussed
-- Edge cases and gotchas identified
-- User has validated your understanding
-- Structure decision made (simple vs. complex)
+**Progressive disclosure.** Load details only when needed. SKILL.md routes to references/, which contain the heavy content.
 
-## Output Quality Standards
+## Quality Check
 
-The created skill must:
+Before finishing, verify:
 
-1. **Activate reliably** - Description has specific trigger phrases
-2. **Instruct clearly** - Imperative form, no ambiguity
-3. **Use context efficiently** - Progressive disclosure, lean SKILL.md
-4. **Capture domain knowledge** - The user's expertise is preserved
-5. **Work on first use** - User can restart and immediately use it
+1. **Would Claude know what to DO?** Not just understand what the skill is about.
+2. **Is domain knowledge captured?** The user's expertise should be in the skill.
+3. **Is it lean?** Heavy content in references/, not SKILL.md.
+4. **Does the description have triggers?** Specific phrases the user would say.