---
name: step-01-design
description: Choose skill type, gather frontmatter information via interactive questions
next_step: steps/step-02-generate.md
---

# Step 1: Design Skill

## MANDATORY EXECUTION RULES:
- ALWAYS ask the user for design decisions (don't assume)
- For UPDATE: show current values and ask what to change
- Load reference docs for guidance
- Gather ALL needed information before proceeding to generation

## YOUR TASK:
Guide the user through skill design decisions. Gather all frontmatter fields and structural choices.

---

## EXECUTION SEQUENCE:

### 1. Load References

```
Read: "references/frontmatter-reference.md"
Read: "references/skill-patterns.md"
Read: "references/best-practices.md"
```

### 2. Choose Skill Type (if not pre-set)

If {skill_type} is not already set:

```yaml
AskUserQuestion:
  header: "Type"
  question: "What type of skill do you want to create?"
  options:
    - label: "Simple"
      description: "Single SKILL.md file, no steps. Best for simple tasks or knowledge injection."
    - label: "Progressive"
      description: "SKILL.md + step files. Best for complex multi-phase workflows."
    - label: "Forked"
      description: "Runs in isolated subagent context. Best for research/exploration tasks."
```

### 3. Gather Description

```yaml
AskUserQuestion:
  header: "Description"
  question: "Describe what this skill does and WHEN Claude should use it. Include trigger keywords. Example: 'Generate API controllers. Use when: creating controllers, API endpoints, REST routes'"
```

Store in {description}.

### 4. Gather Invocation Settings

```yaml
AskUserQuestion:
  header: "Invocation"
  question: "How should this skill be invoked?"
  options:
    - label: "Auto + Manual (Recommended)"
      description: "Claude auto-invokes when relevant AND user can invoke with /name"
    - label: "Manual only"
      description: "Only user can invoke with /name. Best for side-effect operations (deploy, commit)."
    - label: "Hidden"
      description: "Not visible in /menu. Background knowledge only."
```

Map to:
- Auto + Manual → {disable_model_invocation} = false, {user_invocable} = true
- Manual only → {disable_model_invocation} = true, {user_invocable} = true
- Hidden → {disable_model_invocation} = false, {user_invocable} = false

### 5. Gather Arguments (if applicable)

```yaml
AskUserQuestion:
  header: "Arguments"
  question: "Does this skill accept arguments? If yes, describe the format (e.g., '<name> [--flag]'). If no, type 'none'."
```

Store in {argument_hint} (or null if "none").

### 6. Gather Model Preference

```yaml
AskUserQuestion:
  header: "Model"
  question: "Which model should this skill use?"
  options:
    - label: "Inherit (Recommended)"
      description: "Use whatever model the user has configured"
    - label: "Haiku"
      description: "Fast and cheap. Best for simple, repetitive tasks."
    - label: "Sonnet"
      description: "Balanced. Good for most tasks."
    - label: "Opus"
      description: "Most capable. Best for complex reasoning."
```

### 7. Gather Tools (if applicable)

If {skill_type} is "forked":

```yaml
AskUserQuestion:
  header: "Tools"
  question: "Which tools should this skill have access to? (comma-separated)"
  options:
    - label: "Read-only (Recommended)"
      description: "Read, Grep, Glob, WebSearch, WebFetch"
    - label: "Read + Write"
      description: "Read, Write, Edit, Grep, Glob, Bash"
    - label: "Full access"
      description: "All tools available"
```

Also ask for agent type:

```yaml
AskUserQuestion:
  header: "Agent"
  question: "Which agent type for the forked context?"
  options:
    - label: "Explore (Recommended)"
      description: "Fast, read-only, optimized for searching"
    - label: "Plan"
      description: "Research and design, read-only"
    - label: "general-purpose"
      description: "Complex tasks, all tools"
```

### 8. Progressive Steps Design (if applicable)

If {skill_type} is "progressive":

Ask: "How many steps does this skill need? Describe each step briefly."

For each step, gather:
- Step number (00, 01, 02, ...)
- Step name (kebab-case)
- Step description (one line)

Store in {steps}:
```json
[
  {"number": "00", "name": "init", "description": "Parse arguments and initialize state"},
  {"number": "01", "name": "analyze", "description": "Analyze the codebase"},
  {"number": "02", "name": "generate", "description": "Generate output files"},
  {"number": "03", "name": "validate", "description": "Validate results"}
]
```

Also ask about state variables:

Ask: "What state variables should persist across steps? (name, type, description for each)"

Store in {state_vars}.

### 9. Show Design Summary

```
Skill Design:

| Field | Value |
|-------|-------|
| Name | {skill_name} |
| Type | {skill_type} |
| Description | {description} (truncated) |
| Invocation | auto+manual / manual-only / hidden |
| Arguments | {argument_hint} |
| Model | {model} |
| Tools | {allowed_tools} (if forked) |
| Agent | {agent} (if forked) |
| Steps | {step_count} (if progressive) |

Step plan (if progressive):
| # | Name | Description |
|---|------|-------------|
| 00 | {name} | {desc} |
| 01 | {name} | {desc} |
| ... | ... | ... |

→ Generating skill files...
```

---

## SUCCESS METRICS:
- All required fields gathered from user
- Skill type chosen and appropriate options collected
- Steps defined (if progressive)
- Design summary displayed and confirmed

## NEXT STEP:
After design is confirmed, proceed directly to `./step-02-generate.md`
