cc-dev-template 0.1.5 → 0.1.6

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

@@ -0,0 +1,370 @@
+# 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.
+
+## 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
+
+<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="Identify Skill Scope">
+Based on the conversation, determine the skill's scope.
+
+**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)?
+
+**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]?"
+
+**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
+</step>
+
+<step name="Design the Structure">
+Plan the skill's file structure before writing anything.
+
+**Determine what's needed:**
+
+| 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 |
+
+**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)
+```
+
+**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?"
+</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]
+
+## 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>
+
+<step name="Step 2">
+[Instructions]
+</step>
+</steps>
+
+## Key Principles
+
+[Domain knowledge specific to this workflow]
+```
+
+**Script considerations:**
+- Use `process.cwd()` for project paths, not `__dirname`
+- Include clear usage comments
+- Handle errors gracefully
+- Make scripts executable (`chmod +x`)
+</step>
+
+<step name="Determine Install Location">
+Ask where the skill should be installed.
+
+**Options:**
+
+| Location | Path | Use When |
+|----------|------|----------|
+| User level | `~/.claude/skills/[name]/` | Personal skill, available everywhere |
+| Project level | `.claude/skills/[name]/` | Team skill, shared via git |
+
+**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.
+</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)
+
+**After writing, display:**
+- Full path to each created file
+- Word count for SKILL.md
+- Summary of what was created
+</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)
+
+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
+
+**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
+
+**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
+</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
+
+- 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
+
+**Response:** Ask for specific examples, walk through scenarios, request clarification on terminology.
+
+### Signs Ready to Start Writing
+
+- 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)
+
+## Output Quality Standards
+
+The created skill must:
+
+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