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

# Step 2: Generate Agent File

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

## YOUR TASK:
Generate the agent .md file based on the design choices gathered in Step 1.

---

## EXECUTION SEQUENCE:

### 1. Load Template

Based on agent configuration:

```
Standalone (no category)     → Read: "templates/agent-standalone.md"
Categorized (with category)  → Read: "templates/agent-categorized.md"
With preloaded skills        → Read: "templates/agent-with-skills.md"
```

### 2. Create Directory (if needed)

```bash
# For categorized agents
mkdir -p {target_dir}/{category}/
```

### 3. Generate Frontmatter

Build the YAML frontmatter from design choices:

```yaml
---
name: {agent_name}
description: {description}
```

Add optional fields only if they differ from defaults:

```yaml
# Only if not inherit
model: {model}

# Only if explicitly specified
tools: "{tools}"

# Only if blocking specific tools
disallowedTools: "{disallowed_tools}"

# Only if not default
permissionMode: {permission_mode}

# Only if preloading skills
skills:
  - {skill_1}
  - {skill_2}

# Optional visual indicator
color: {color}
```

Close frontmatter:
```yaml
---
```

### 4. Generate System Prompt Content

Based on the behavior pattern chosen in Step 1:

See [references/agent-behavior-patterns.md](../references/agent-behavior-patterns.md) for the 4 behavior pattern templates:
- **Explorer**: Search → Read → Analyze → Report (with file references)
- **Modifier**: Read → Analyze → Edit → Validate → Report
- **Validator**: Scan → Check → Report (with severity table: ERROR/WARN/INFO)
- **Custom**: User-driven from Step 1 description

### 5. Write Agent File

Use Write tool to create the file at {target_path}.

### 6. For UPDATE Subcommand

If {subcommand} = "update":
1. Read existing file at {target_path}
2. Parse current frontmatter
3. Apply only the requested changes (merge frontmatter, update content sections)
4. Use Edit tool for targeted modifications
5. Preserve custom content not being updated

### 7. Confirm Generation

```
Generated: {target_path}

Frontmatter:
  name: {agent_name}
  description: {description} (truncated)
  model: {model}
  tools: {tools}
  permissionMode: {permission_mode}

Content sections:
  - Workflow ({step_count} steps)
  - Execution Rules
  - Output Format

→ Validating agent...
```

---

## SUCCESS METRICS:
- Agent .md file created at correct path
- Frontmatter includes all required and chosen optional fields
- System prompt is clear and actionable
- Content follows the chosen behavior pattern
- No placeholder text left unreplaced

## NEXT STEP:
Proceed directly to `./step-03-validate.md`
