---
name: step-02-generate
description: Generate SKILL.md file from template based on design choices
next_step: steps/step-03-steps.md
---

# Step 2: Generate SKILL.md

## MANDATORY EXECUTION RULES:
- ALWAYS load the appropriate template from `templates/` directory
- ALWAYS use the design choices from Step 1
- For UPDATE: read existing SKILL.md first, then apply changes
- Generate COMPLETE SKILL.md (not a stub)

## YOUR TASK:
Generate the SKILL.md file based on the skill type and design choices gathered in Step 1.

---

## EXECUTION SEQUENCE:

### 1. Load Template

Based on {skill_type}:

```
"simple"      → Read: "templates/skill-simple.md"
"progressive" → Read: "templates/skill-progressive.md"
"forked"      → Read: "templates/skill-forked.md"
```

### 2. Create Directory Structure

```bash
# Create skill directory
mkdir -p {target_dir}

# For progressive skills, create subdirectories
mkdir -p {target_dir}/steps/
mkdir -p {target_dir}/references/  # optional but recommended
mkdir -p {target_dir}/templates/   # optional, for code templates
```

### 3. Generate SKILL.md

Use the loaded template as a base. Replace all placeholders with actual values:

**Frontmatter generation:**

```yaml
---
name: {skill_name}
description: |
  {description}
```

Add optional fields only if they differ from defaults:

```yaml
# Only if manual-only
disable-model-invocation: true

# Only if hidden
user-invocable: false

# Only if skill accepts arguments
argument-hint: "{argument_hint}"

# Only if not "inherit"
model: {model}

# Only for forked skills
context: fork
agent: {agent}
allowed-tools: "{allowed_tools}"
```

Close frontmatter:

```yaml
---
```

**Content generation:**

Generate appropriate XML sections based on {skill_type}:

**All types get:**
- `<objective>` - One paragraph from {description}
- `<quick_start>` - Usage examples with /skill_name
- `<execution_rules>` - Standard rules
- `<success_criteria>` - Completion conditions

**Progressive type additionally gets:**
- `<parameters>` with `<flags>` and `<examples>`
- `<workflow>` - Numbered high-level steps
- `<state_variables>` - Table of persistent variables
- `<entry_point>` - Points to step-00-init.md
- `<step_files>` - Table mapping steps to files

**Forked type additionally gets:**
- Note about isolated context
- Direct workflow (no step loading)

### 4. Write SKILL.md

Use Write tool to create `{target_dir}/SKILL.md` with generated content.

### 5. For UPDATE subcommand

If {subcommand} = "update":
1. Read existing `{target_dir}/SKILL.md`
2. Parse current frontmatter and sections
3. Apply only the requested changes (merge, don't replace entirely)
4. Use Edit tool to modify specific sections
5. Preserve any custom content not being updated

### 6. Confirm Generation

```
Generated: {target_dir}/SKILL.md ({line_count} lines)

Frontmatter:
  name: {skill_name}
  description: {description} (truncated)
  type: {skill_type}
  ...

Sections: {list of XML sections included}

→ Generating step files...
```

---

## SUCCESS METRICS:
- SKILL.md created/updated at correct path
- Frontmatter includes all required fields
- Appropriate XML sections for skill type
- Under 500 lines
- No placeholder text left unreplaced

## NEXT STEP:
- If {skill_type} = "progressive" → proceed to `./step-03-steps.md`
- If {skill_type} = "simple" or "forked" → skip to `./step-04-validate.md`
