name: create-skill
description: Interactive skill creation wizard - guides through requirements gathering to create properly structured skills
agent: engineer
version: 1.0
classification: public
last_updated: 2026-01-26
effort_default: STANDARD

⛔ DUAL-PATH ROUTING - READ THIS FIRST

STOP. This skill requires the engineer agent for complex requests.

Identity check: If you are NOT the engineer agent AND your request is complex
(multi-phase skill generation, validation, architecture planning) → DELEGATE NOW:

typescript Task(subagent_type="engineer", prompt="Execute create-skill. Request: {user_request}")

DO NOT proceed if you lack engineer expertise for:
- Multi-phase skill architecture decisions
- Integration planning and validation
- Complex workflow coordination

Path 1 - Simple (Tier 1/Haiku): Template questions, explanations
- "Show skill template"
- "Explain skill structure"
- Routes directly, no delegation needed

Path 2 - Complex (Engineer): Full skill creation
- "Create a skill with 5 phases"
- "Design skill with API integration"
- Requires engineer delegation

Skill Creation Skill

Interactive wizard to create properly structured skills with full requirements gathering.

Supporting Documentation (READ FIRST)

⚠️ MANDATORY: Read these supporting documents BEFORE executing this skill:

1. docs/requirements-questions.md - Detailed question templates for Phase 1 (DISCOVER)
2. docs/naming-conventions.md - Skill and command naming standards
3. docs/skill-structure-standards.md - Directory structure and file organization
4. docs/phase-workflow-patterns.md - Multi-phase skill patterns
5. docs/env-management-patterns.md - ENV/credential documentation patterns

These documents contain critical templates and standards that MUST be followed during skill creation.

Model Tier Routing

This skill uses the three-tier orchestration engine for cost-optimal execution:

Routing Decision Tree:
- Skill documentation and template explanations: Tier 1 (Free) - $0.00 (e.g., "Show skill template")
- Interactive skill creation with multi-phase generation: Tier 2b (Grok 4.1 Fast) - $0.70/1M ← Primary
- Complex skills with advanced patterns: Tier 2b (Grok 4.1 Fast) - $0.70/1M (requires large context)

Why Tier 2b for skill creation?
- Multi-phase wizard (requirements gathering → design → implementation → testing → documentation)
- Large context for template integration and phase generation
- Complex reasoning for skill architecture decisions
- Cost savings vs. Sonnet: 71% ($0.70 vs $2.40 per 1M)

How it works:
1. You invoke /create-skill with your skill concept
2. Base Claude's tier selector analyzes complexity and phase requirements
3. Request routes to Tier 2b automatically for wizard orchestration
4. Multi-phase generation happens with confidence scoring
5. Templates and phase files are generated with proper structure

Cost Model:
- Template explanation: $0 (Tier 1)
- New skill creation: ~$0.70 (Tier 2b for full orchestration)
- Complex skill with research: ~$1.40 (full multi-phase with research)

Reference: READ docs/skill-tier-integration.md for complete skill mapping and tier selection criteria.

Pre-flight Checklist (MANDATORY)

STOP! Before executing this skill:

• [ ] Read this SKILL.md completely
• [ ] Understand the 5-phase workflow
• [ ] Prepared to ask user questions (AskUserQuestion tool)
• [ ] Have access to templates in skills/create-skill/templates/

USE WHEN

Invoke this skill when:
- User says "create a skill" or "add new skill"
- User invokes /create-skill
- User wants to add new capability to the framework
- User describes a workflow that should become a skill
- Creating a skill that uses external APIs or credentials
- Need automatic ENV documentation generated

DO NOT use when:
- Creating a simple tool script → put in tools/ directly
- Creating just a command → use library/templates/COMMAND-TEMPLATE.md
- Creating an agent → use library/templates/AGENT-TEMPLATE.md

Quick Start

/create-skill
/create-skill [skill-name]

Output: skills/[skill-name]/ with full structure

5-Phase Workflow

┌──────────┐    ┌─────────┐    ┌──────────┐    ┌─────────┐    ┌─────────┐
│ DISCOVER │───▶│  DESIGN │───▶│ GENERATE │───▶│ VALIDATE│───▶│ HANDOFF │
│(Understand)   │ (Plan)  │    │(Execute) │    │(Verify) │    │ (Learn) │
└─────┬────┘    └────┬────┘    └─────┬────┘    └────┬────┘    └────┬────┘
      │              │               │              │              │
      ▼              ▼               ▼              ▼              ▼
  Requirements   Structure      Files Created   Checks Pass   User Ready
   Gathered      Designed       from Templates   All Valid    to Customize

Phase 1: DISCOVER (Requirements Gathering)

Purpose: Collect all information needed to create the skill

Gate Question: "Do I have all required information from the user?"

Required Information

BEFORE collecting requirements:
1. READ docs/requirements-questions.md for complete question templates
2. Use AskUserQuestion to collect the 8 key pieces of information

Quick Summary:
1. Skill identity (name + description)
2. Problem & solution
3. Workflows/modes
4. Agent routing (security, engineer, writer, advisor, legal, none)
5. User-facing command (yes/no)
6. Command name (if user-facing, must differ from skill name)
7. Visibility (private default, public after testing)
8. ENV/credential requirements

All new skills default to classification: private until fully tested and approved.

Phase 2: DESIGN (Structure Planning)

Purpose: Validate naming and design the skill structure

Gate Question: "Is the structure plan validated?"

Naming Validation

┌─────────────────────────────────────────────────────────────┐
│ NAMING GUIDELINES: Command and skill folder names           │
│                                                             │
│ ✅ MATCHING NAMES (Most common pattern):                   │
│    /write → skills/write/                                   │
│    /ghost → skills/ghost/                                   │
│    /advisory → skills/advisory/                             │
│    /career → skills/career/                                 │
│                                                             │
│ ✅ DIFFERENT NAMES (For multiple commands → one skill):    │
│    /arch-review → skills/advisory/                          │
│    /code-review → skills/advisory/                          │
│    /pentest → skills/security/                              │
│                                                             │
│ Both patterns are valid and supported.                      │
└─────────────────────────────────────────────────────────────┘

Validation Check:

# No naming restriction - both matching and different names work
# Just ensure no conflicts with existing commands
if command_already_exists(command_name):
    WARNING: "Command name already exists"
    ACTION: Choose different name or confirm override

Structure Design

Based on requirements, design:

skills/[skill-name]/
├── SKILL.md              # Main skill (from SKILL-TEMPLATE.md)
├── README.md             # User overview (from readme-template.md)
├── VERIFY.md             # Definition of Done (from VERIFY-TEMPLATE.md)
├── phases/               # Domain-specific phases
│   ├── 01-[Phase1].md
│   ├── 02-[Phase2].md
│   └── ...
├── reference/            # Domain knowledge
└── templates/            # Output templates (if needed)

commands/[command-name].md  # User-facing command (if applicable)

Phase Mapping

Map user's workflows to 5 universal phases:

Phase 3: GENERATE (File Creation)

Purpose: Create all skill files from templates

Gate Question: "Are all files created from templates?"

Step 3.1: Create Directory Structure

mkdir -p skills/[skill-name]/{phases,docs,templates,input,output}

Creates:

skills/[skill-name]/
├── phases/       # 5-phase workflow files
├── docs/         # Domain knowledge base (renamed from reference/)
├── templates/    # Output templates
├── input/        # User-provided data (self-contained)
└── output/       # Skill-generated deliverables (self-contained)

Note: Each skill manages its own input/ and output/ data directories independently.

Step 3.2: Generate SKILL.md

Copy from skills/create-skill/templates/SKILL-TEMPLATE.md and customize:
- Add routing gate (if agent specified)
- Fill in frontmatter (name, description, agent, etc.)
- Add effort classification
- Add 5-phase workflow diagram
- Add Success Criteria tracking

Step 3.3: Generate README.md

Copy from skills/create-skill/templates/README-TEMPLATE.md and customize:
- Problem statement
- Solution approach
- Quick start examples
- Command documentation

Step 3.4: Generate VERIFY.md

Copy from skills/create-skill/templates/VERIFY-TEMPLATE.md and customize:
- Skill-specific verification checks
- Domain-specific quality criteria

Step 3.5: Generate Phase Files with Haiku Workers

Orchestrator-Worker Pattern: Sonnet orchestrates, Haiku workers generate in parallel.

For each phase file needed:

1. Spawn Haiku Worker:
   Task({ model: "haiku", prompt: "Generate ${phaseName} for ${skillDomain}. Context: [auto-loaded]" })

2. Auto-load Context:

3. Tool signatures from library/tool-signatures.json
4. Phase template format

5. Skill requirements

6. QA Validation:

7. Use prompt-generation capability on Haiku output

8. Check: gate question, pass criteria, tools, checklists

9. Fallback Chain:

10. Try 1-3: Haiku with progressive context
11. Try 4: Sonnet generation

12. Try 5: Static template

13. Save Validated Output:

14. Write to skills/${skillName}/phases/${phaseFilename}

Expected: All phases generated in parallel (~30 seconds total)

Step 3.6: Generate Command (if user-facing)

Create commands/[command-name].md with:
- Agent routing (if applicable)
- Skill reference
- Quick start
- Mode documentation

Phase 4: VALIDATE (Quality Checks)

Purpose: Verify all files are correct and complete

Gate Question: "Do all validation checks pass?"

Validation Checklist

Structure Validation

• [ ] skills/[skill-name]/SKILL.md exists
• [ ] skills/[skill-name]/README.md exists
• [ ] skills/[skill-name]/VERIFY.md exists
• [ ] skills/[skill-name]/phases/ has at least one file
• [ ] All paths are valid

Naming Validation

• [ ] Skill folder name is lowercase-with-dashes
• [ ] Command name differs from skill folder name
• [ ] No naming conflicts with existing skills

Content Validation

• [ ] SKILL.md has routing gate (if agent specified)
• [ ] SKILL.md has valid YAML frontmatter
• [ ] SKILL.md has effort classification
• [ ] SKILL.md has 5-phase workflow
• [ ] README.md has problem/solution
• [ ] Phase files have gate questions

Integration Validation

• [ ] Command file references correct skill
• [ ] Agent routing is correct (if applicable)

Phase 5: HANDOFF (User Ready)

Purpose: Provide user with next steps to customize and use

Gate Question: "Can user customize and use the skill?"

Present to User

1. Summary of created files
2. Next steps for customization:
3. Edit SKILL.md - Add domain-specific logic
4. Fill Phase files - Add actual workflow steps
5. Add Reference materials - Import domain knowledge
6. Create templates - Add output templates if needed
7. How to invoke:
8. /[command-name] (if user-facing)
9. Or ask Claude to use the skill
10. Testing guidance

Post-Creation Reminders

• [ ] Update agent's skill list (if agent-loaded)
• [ ] Update .framework-manifest.yaml (if public skill)
• [ ] Run /git-public to sync (if public skill)
• [ ] Test the skill works

Error Recovery

Templates Used

ENV Management Integration

When generating new skills, /create-skill automatically:

✅ Asks about credentials - Question 8 of DISCOVER phase
✅ Generates env documentation - Creates docs/env-setup.md with complete setup instructions
✅ Creates .env.structure.yaml template - Ready to integrate with credential system
✅ Documents in README.md - Adds Setup & Configuration section (if credentials needed)
✅ Validates credential setup - VERIFY phase checks all ENV documentation completeness
✅ Provides verification steps - Users can test credentials load properly

Example workflow:
1. User selects "Yes, requires credentials" in DISCOVER phase
2. User provides list: "Stripe API Key, OpenAI API Key"
3. /create-skill generates:
- docs/env-setup.md with Stripe + OpenAI setup instructions
- .env.structure.yaml section template in env doc
- README "Setup & Configuration" section
- Frontmatter with env_required: true + env_keys: [STRIPE_API_KEY, OPENAI_API_KEY]
4. VERIFY phase validates all credential documentation is complete
5. HANDOFF phase guides user through credential configuration

Related Skills

• /framework-update - Update framework components
• Agent creation - Use library/templates/AGENT-TEMPLATE.md
• Command creation - Use library/templates/COMMAND-TEMPLATE.md

Version: 1.0
Last Updated: 2026-01-13
Status: Active