agileflow 2.61.0 → 2.62.0

package/src/core/commands/skill/create.md

@@ -0,0 +1,566 @@
+---
+description: Generate a custom skill with web research, cookbook pattern, and MCP integration
+argument-hint: [SKILL_NAME] (optional)
+---
+
+# /agileflow:skill:create
+
+Generate dynamic, research-backed skills that combine web documentation, user's local docs, and codebase patterns.
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## Compact Summary
+
+**ROLE**: Skill Generator - creates custom skills via comprehensive research.
+
+### Critical Rules
+1. **ALWAYS use Plan Mode** - Enter plan mode to explore before generating
+2. **Research THREE sources**: Web docs, user's local docs, user's codebase
+3. **Link to external docs** - Reference URLs, don't copy entire docs
+4. **Reference local patterns** - Point to user's existing practices and code
+5. **Use cookbook pattern** for multi-use-case skills
+6. **Output to `.claude/skills/<skill-name>/`** - directly usable by Claude Code
+
+### Generated Skill Structure
+```
+.claude/skills/<skill-name>/
+├── SKILL.md              # Pivot file with references to all sources
+├── cookbook/             # Per-use-case workflows
+├── references.md         # Links to web docs + local docs + code patterns
+├── tools/                # Executable scripts (optional)
+└── .mcp.json             # MCP server config (if applicable)
+```
+
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Workflow
+
+### Phase 1: Requirements Gathering
+
+**STEP 1**: Ask what skill the user wants
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What skill would you like to create?",
+  "header": "Skill Purpose",
+  "multiSelect": false,
+  "options": [
+    {"label": "Describe what I need", "description": "I'll explain the skill I want to build"},
+    {"label": "Database integration", "description": "Supabase, PostgreSQL, MongoDB, etc."},
+    {"label": "API integration", "description": "REST APIs, GraphQL, webhooks"},
+    {"label": "UI/Frontend", "description": "Components, styling, design system"},
+    {"label": "Development workflow", "description": "Testing, deployment, CI/CD"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**STEP 2**: Gather details based on response
+
+Extract from user's description:
+- Technology/framework
+- Primary use cases
+- Target workflow
+
+---
+
+### Phase 2: Plan Mode Research (CRITICAL)
+
+**STEP 3**: Enter Plan Mode
+
+```
+EnterPlanMode
+```
+
+**In plan mode, you will explore THREE sources:**
+
+#### Source 1: Web Documentation
+
+Search for official documentation and best practices:
+
+```
+WebSearch: "<technology> official documentation"
+WebSearch: "<technology> best practices 2025"
+WebSearch: "<technology> <use-case> guide"
+```
+
+**Collect URLs** - don't copy content, just gather links:
+- Official docs URL (e.g., `https://supabase.com/docs`)
+- API reference URL
+- GitHub repository URL
+- Tutorial/guide URLs
+
+#### Source 2: User's Local Documentation
+
+Check the user's `docs/` directory for relevant practices:
+
+```
+Glob: "docs/**/*.md"
+Grep: "<technology>" in docs/
+Grep: "design system" in docs/ (for UI skills)
+Grep: "style guide" in docs/ (for UI skills)
+```
+
+**Look for:**
+- `docs/02-practices/` - Development practices (testing, styling, security)
+- `docs/04-architecture/` - Architecture decisions
+- `docs/03-decisions/` - ADRs that affect this skill's domain
+- Any existing documentation about the technology
+
+**Example for UI skill:**
+```
+Read: docs/02-practices/styling.md (if exists)
+Read: docs/02-practices/components.md (if exists)
+Read: docs/04-architecture/design-system.md (if exists)
+```
+
+#### Source 3: User's Codebase
+
+Explore the actual code for existing patterns:
+
+```
+Glob: "src/**/*.<extension>"
+Grep: "<pattern>" in src/
+```
+
+**For UI skills, look for:**
+- Existing component patterns: `Glob: "src/components/**/*.tsx"`
+- Design tokens/theme: `Grep: "theme" or "colors" or "spacing"`
+- Styling approach: Check for Tailwind, CSS modules, styled-components
+- Existing design system: `Glob: "**/design-system/**/*"`
+
+**For Database skills, look for:**
+- Existing models: `Glob: "src/models/**/*"`
+- Database client setup: `Grep: "createClient" or "prisma"`
+- Migration patterns: `Glob: "**/migrations/**/*"`
+
+**For API skills, look for:**
+- Existing routes: `Glob: "src/api/**/*" or "src/routes/**/*"`
+- Middleware patterns: `Grep: "middleware"`
+- Error handling: `Grep: "catch" or "error"`
+
+**STEP 4**: Research MCP servers
+
+```
+WebSearch: "<technology> MCP server official"
+WebSearch: "Model Context Protocol <technology>"
+```
+
+If found, note the package name and documentation URL.
+
+**STEP 5**: Write plan with findings
+
+Write to plan file:
+
+```markdown
+# Skill: <skill-name>
+
+## Research Findings
+
+### Web Documentation
+- Official docs: <URL>
+- API reference: <URL>
+- Best practices: <URL>
+
+### Local Documentation Found
+- `docs/02-practices/styling.md` - Design system guidelines
+- `docs/04-architecture/components.md` - Component patterns
+- (or "No relevant local docs found")
+
+### Codebase Patterns Found
+- Design system: `src/styles/theme.ts` - Color tokens, spacing
+- Component pattern: `src/components/Button/` - Standard component structure
+- (or "No existing patterns found for this domain")
+
+### MCP Server
+- Found: @supabase/mcp-server
+- Docs: <URL>
+
+## Proposed Skill Structure
+- SKILL.md with references to all sources
+- cookbook/ for <use-case-1>, <use-case-2>
+- references.md linking everything
+
+## Questions for User
+- Should I include the MCP server?
+- Any other local patterns I should incorporate?
+```
+
+**STEP 6**: Exit plan mode for approval
+
+```
+ExitPlanMode
+```
+
+User reviews the plan and approves or requests changes.
+
+---
+
+### Phase 3: Skill Generation
+
+**STEP 7**: Determine skill complexity
+
+- **Simple skill** (1 use case): SKILL.md only, no cookbook
+- **Complex skill** (2+ use cases): SKILL.md + cookbook/ directory
+
+**STEP 8**: Generate SKILL.md
+
+```markdown
+---
+name: <skill-name-with-hyphens>
+description: Use when <triggering conditions and symptoms>
+---
+
+# <Skill Title>
+
+<One sentence description.>
+
+## When to Use
+
+This skill activates when:
+- <Symptom 1>
+- <Symptom 2>
+- Keywords: "<keyword1>", "<keyword2>", "<keyword3>"
+
+## Project Context
+
+**IMPORTANT**: This skill is tailored to THIS project. Before implementing:
+
+1. **Check local practices first**: Read `references.md` for project-specific patterns
+2. **Follow existing code patterns**: The codebase patterns section shows how this project does things
+3. **Use external docs for details**: Official documentation URLs are in references.md
+
+## Cookbook
+
+Based on context, select the appropriate workflow:
+
+### <Use Case 1>
+If <condition>:
+Then read cookbook/<use-case-1>.md
+
+Examples:
+- "<example request>"
+
+### <Use Case 2>
+If <condition>:
+Then read cookbook/<use-case-2>.md
+
+Examples:
+- "<example request>"
+
+## Quick Reference
+
+| Action | Command/Pattern |
+|--------|-----------------|
+| <action1> | <pattern1> |
+
+## When You're Stuck
+
+1. **Read `references.md`** - Links to all documentation sources
+2. **Check local docs** - Project practices in docs/02-practices/
+3. **Look at existing code** - See codebase patterns in references.md
+4. **Fetch external docs** - Use WebFetch on URLs in references.md
+
+## MCP Integration
+
+This skill uses the **<server-name>** MCP server.
+
+**Setup**: The `.mcp.json` in this skill folder contains the configuration.
+To activate, copy to your project's `.mcp.json` or merge with existing.
+
+## Common Mistakes
+
+- <Mistake 1>: <How to avoid>
+```
+
+**STEP 9**: Generate references.md
+
+This file links ALL documentation sources - web, local, and codebase:
+
+```markdown
+# References for <Skill Name>
+
+## External Documentation
+
+| Resource | URL | Use For |
+|----------|-----|---------|
+| Official Docs | <URL> | Core concepts, getting started |
+| API Reference | <URL> | Method signatures, parameters |
+| GitHub Repo | <URL> | Examples, issues, updates |
+| Best Practices | <URL> | Patterns, anti-patterns |
+
+## Local Project Documentation
+
+| File | Contains |
+|------|----------|
+| `docs/02-practices/<file>.md` | <description> |
+| `docs/04-architecture/<file>.md` | <description> |
+| (or "No local docs found for this domain") |
+
+## Codebase Patterns
+
+Existing patterns in this project that you MUST follow:
+
+### <Pattern Name>
+- **Location**: `src/path/to/file.ts`
+- **Pattern**: <description of what it does>
+- **Example**:
+  ```typescript
+  // Code snippet showing the pattern
+  ```
+
+### <Another Pattern>
+- **Location**: `src/path/to/other.ts`
+- **Pattern**: <description>
+
+(or "No existing patterns found - follow external docs")
+
+## MCP Server
+
+| Package | Docs | Tools Provided |
+|---------|------|----------------|
+| <package-name> | <URL> | <list of tools> |
+
+## How to Use These References
+
+1. **First**: Check "Codebase Patterns" - follow existing project conventions
+2. **Second**: Read "Local Project Documentation" for team practices
+3. **Third**: Use "External Documentation" URLs for syntax and details
+4. **To fetch docs**: `WebFetch: <URL>` with prompt "Extract <specific info>"
+```
+
+**STEP 10**: Generate cookbook entries (if complex skill)
+
+For each use case, create `cookbook/<use-case>.md`:
+
+```markdown
+# <Use Case Title>
+
+<Brief description of this workflow.>
+
+## Prerequisites
+
+- <Prerequisite 1>
+- <Prerequisite 2>
+
+## Instructions
+
+1. **<Step 1>**:
+   <Details>
+
+2. **<Step 2>**:
+   ```<language>
+   <code example>
+   ```
+
+3. **<Step 3>**:
+   <Details>
+
+## Example
+
+**Input**: <sample>
+**Output**: <result>
+
+## Troubleshooting
+
+- **<Problem>**: <Solution>
+```
+
+**STEP 11**: Generate .mcp.json (if user approved MCP)
+
+```json
+{
+  "mcpServers": {
+    "<server-name>": {
+      "command": "npx",
+      "args": ["-y", "<package-name>"],
+      "env": {
+        "<ENV_VAR>": "${<ENV_VAR>}"
+      }
+    }
+  }
+}
+```
+
+---
+
+### Phase 4: Preview & Confirmation
+
+**STEP 12**: Show skill structure
+
+Display the generated structure:
+
+```
+.claude/skills/<skill-name>/
+├── SKILL.md (XX lines)
+├── references.md          # Links to web docs, local docs, codebase patterns
+├── cookbook/
+│   ├── <use-case-1>.md
+│   └── <use-case-2>.md
+└── .mcp.json
+```
+
+**STEP 13**: Preview SKILL.md content
+
+Show the first 50 lines of SKILL.md for review.
+
+**STEP 14**: Confirm creation
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Create this skill?",
+  "header": "Confirm",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, create skill", "description": "Write all files to .claude/skills/"},
+    {"label": "No, start over", "description": "Cancel and restart"},
+    {"label": "Edit requirements", "description": "Modify before creating"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+### Phase 5: Write Files
+
+**STEP 15**: Create skill directory and files
+
+```bash
+mkdir -p .claude/skills/<skill-name>/cookbook
+```
+
+Write files:
+1. `.claude/skills/<skill-name>/SKILL.md` - Main skill file
+2. `.claude/skills/<skill-name>/references.md` - Links to web docs, local docs, codebase patterns
+3. `.claude/skills/<skill-name>/cookbook/<use-case>.md` (for each use case)
+4. `.claude/skills/<skill-name>/.mcp.json` (if MCP enabled)
+
+**STEP 16**: Verify creation
+
+```bash
+ls -la .claude/skills/<skill-name>/
+```
+
+**STEP 17**: Present next steps
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Skill created! What next?",
+  "header": "Next Steps",
+  "multiSelect": false,
+  "options": [
+    {"label": "Test the skill now", "description": "Try using the skill in this session"},
+    {"label": "Create another skill", "description": "Generate a new skill"},
+    {"label": "Done", "description": "Finish skill creation"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## Error Handling
+
+### Web Search Fails
+
+If WebSearch returns no results:
+1. Ask user for documentation URL
+2. Use generic patterns
+3. Note "manual review recommended" in SKILL.md
+
+### MCP Not Found
+
+If no MCP server found for technology:
+1. Create skill without .mcp.json
+2. Add note in SKILL.md: "No MCP server found for <technology>. MCP integration can be added later."
+3. Provide instructions for manual MCP setup
+
+### Validation Errors
+
+Before writing, validate:
+- `name` uses only letters, numbers, hyphens
+- `description` is under 1024 characters
+- SKILL.md body is under 500 lines
+- All cookbook files referenced in SKILL.md exist
+
+If validation fails:
+1. Show specific errors
+2. Offer to fix automatically
+3. Don't write until valid
+
+---
+
+## Examples
+
+### Example 1: Supabase Swift Skill
+
+**User**: "I want a skill for database management in Supabase for Swift"
+
+**Plan mode research finds:**
+- Web docs: supabase.com/docs/guides/getting-started/quickstarts/swift
+- Local docs: None found
+- Codebase: `src/lib/supabase.ts` - existing client setup
+- MCP: @supabase/mcp-server available
+
+**Generated**:
+```
+.claude/skills/supabase-swift/
+├── SKILL.md
+├── references.md              # Links to Supabase docs + local client pattern
+├── cookbook/
+│   ├── crud-operations.md
+│   ├── authentication.md
+│   ├── migrations.md
+│   └── realtime-subscriptions.md
+└── .mcp.json
+```
+
+**references.md includes:**
+- External: Supabase Swift SDK docs URL, API reference URL
+- Codebase: Points to `src/lib/supabase.ts` for client pattern
+- MCP: @supabase/mcp-server docs and tools
+
+### Example 2: UI Component Skill
+
+**User**: "I need a skill for building UI components"
+
+**Plan mode research finds:**
+- Web docs: React docs, Tailwind docs
+- Local docs: `docs/02-practices/styling.md` - design system guidelines
+- Codebase: `src/components/Button/` - existing component pattern, `src/styles/theme.ts` - color tokens
+
+**Generated**:
+```
+.claude/skills/ui-components/
+├── SKILL.md
+├── references.md              # Links to React/Tailwind + local design system
+└── cookbook/
+    ├── create-component.md
+    ├── styling-patterns.md
+    └── accessibility.md
+```
+
+**references.md includes:**
+- External: React docs URL, Tailwind docs URL
+- Local docs: `docs/02-practices/styling.md`
+- Codebase patterns: Button component structure, theme tokens location
+
+---
+
+## Usage
+
+```bash
+# Interactive mode (recommended)
+/agileflow:skill:create
+
+# With skill name hint
+/agileflow:skill:create supabase-swift
+```