Initial commit

skills/create-agent-skills/workflows/create-new-skill.md

@@ -0,0 +1,191 @@
+# Workflow: Create a New Skill
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/recommended-structure.md
+2. references/skill-structure.md
+3. references/core-principles.md
+4. references/use-xml-tags.md
+</required_reading>
+
+<process>
+## Step 1: Adaptive Requirements Gathering
+
+**If user provided context** (e.g., "build a skill for X"):
+→ Analyze what's stated, what can be inferred, what's unclear
+→ Skip to asking about genuine gaps only
+
+**If user just invoked skill without context:**
+→ Ask what they want to build
+
+### Using AskUserQuestion
+
+Ask 2-4 domain-specific questions based on actual gaps. Each question should:
+- Have specific options with descriptions
+- Focus on scope, complexity, outputs, boundaries
+- NOT ask things obvious from context
+
+Example questions:
+- "What specific operations should this skill handle?" (with options based on domain)
+- "Should this also handle [related thing] or stay focused on [core thing]?"
+- "What should the user see when successful?"
+
+### Decision Gate
+
+After initial questions, ask:
+"Ready to proceed with building, or would you like me to ask more questions?"
+
+Options:
+1. **Proceed to building** - I have enough context
+2. **Ask more questions** - There are more details to clarify
+3. **Let me add details** - I want to provide additional context
+
+## Step 2: Research Trigger (If External API)
+
+**When external service detected**, ask using AskUserQuestion:
+"This involves [service name] API. Would you like me to research current endpoints and patterns before building?"
+
+Options:
+1. **Yes, research first** - Fetch current documentation for accurate implementation
+2. **No, proceed with general patterns** - Use common patterns without specific API research
+
+If research requested:
+- Use Context7 MCP to fetch current library documentation
+- Or use WebSearch for recent API documentation
+- Focus on 2024-2025 sources
+- Store findings for use in content generation
+
+## Step 3: Decide Structure
+
+**Simple skill (single workflow, <200 lines):**
+→ Single SKILL.md file with all content
+
+**Complex skill (multiple workflows OR domain knowledge):**
+→ Router pattern:
+```
+skill-name/
+├── SKILL.md (router + principles)
+├── workflows/ (procedures - FOLLOW)
+├── references/ (knowledge - READ)
+├── templates/ (output structures - COPY + FILL)
+└── scripts/ (reusable code - EXECUTE)
+```
+
+Factors favoring router pattern:
+- Multiple distinct user intents (create vs debug vs ship)
+- Shared domain knowledge across workflows
+- Essential principles that must not be skipped
+- Skill likely to grow over time
+
+**Consider templates/ when:**
+- Skill produces consistent output structures (plans, specs, reports)
+- Structure matters more than creative generation
+
+**Consider scripts/ when:**
+- Same code runs across invocations (deploy, setup, API calls)
+- Operations are error-prone when rewritten each time
+
+See references/recommended-structure.md for templates.
+
+## Step 4: Create Directory
+
+```bash
+mkdir -p ~/.claude/skills/{skill-name}
+# If complex:
+mkdir -p ~/.claude/skills/{skill-name}/workflows
+mkdir -p ~/.claude/skills/{skill-name}/references
+# If needed:
+mkdir -p ~/.claude/skills/{skill-name}/templates  # for output structures
+mkdir -p ~/.claude/skills/{skill-name}/scripts    # for reusable code
+```
+
+## Step 5: Write SKILL.md
+
+**Simple skill:** Write complete skill file with:
+- YAML frontmatter (name, description)
+- `<objective>`
+- `<quick_start>`
+- Content sections with pure XML
+- `<success_criteria>`
+
+**Complex skill:** Write router with:
+- YAML frontmatter
+- `<essential_principles>` (inline, unavoidable)
+- `<intake>` (question to ask user)
+- `<routing>` (maps answers to workflows)
+- `<reference_index>` and `<workflows_index>`
+
+## Step 6: Write Workflows (if complex)
+
+For each workflow:
+```xml
+<required_reading>
+Which references to load for this workflow
+</required_reading>
+
+<process>
+Step-by-step procedure
+</process>
+
+<success_criteria>
+How to know this workflow is done
+</success_criteria>
+```
+
+## Step 7: Write References (if needed)
+
+Domain knowledge that:
+- Multiple workflows might need
+- Doesn't change based on workflow
+- Contains patterns, examples, technical details
+
+## Step 8: Validate Structure
+
+Check:
+- [ ] YAML frontmatter valid
+- [ ] Name matches directory (lowercase-with-hyphens)
+- [ ] Description says what it does AND when to use it (third person)
+- [ ] No markdown headings (#) in body - use XML tags
+- [ ] Required tags present: objective, quick_start, success_criteria
+- [ ] All referenced files exist
+- [ ] SKILL.md under 500 lines
+- [ ] XML tags properly closed
+
+## Step 9: Create Slash Command
+
+```bash
+cat > ~/.claude/commands/{skill-name}.md << 'EOF'
+---
+description: {Brief description}
+argument-hint: [{argument hint}]
+allowed-tools: Skill({skill-name})
+---
+
+Invoke the {skill-name} skill for: $ARGUMENTS
+EOF
+```
+
+## Step 10: Test
+
+Invoke the skill and observe:
+- Does it ask the right intake question?
+- Does it load the right workflow?
+- Does the workflow load the right references?
+- Does output match expectations?
+
+Iterate based on real usage, not assumptions.
+</process>
+
+<success_criteria>
+Skill is complete when:
+- [ ] Requirements gathered with appropriate questions
+- [ ] API research done if external service involved
+- [ ] Directory structure correct
+- [ ] SKILL.md has valid frontmatter
+- [ ] Essential principles inline (if complex skill)
+- [ ] Intake question routes to correct workflow
+- [ ] All workflows have required_reading + process + success_criteria
+- [ ] References contain reusable domain knowledge
+- [ ] Slash command exists and works
+- [ ] Tested with real invocation
+</success_criteria>