---
name: step-01-design
description: Design agent - choose model, tools, permissions, skills to preload
next_step: steps/step-02-generate.md
---

# Step 1: Design Agent

## 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
- Tools should follow principle of least privilege

## YOUR TASK:
Guide the user through agent design decisions. Gather model, tools, permissions, skills, and system prompt content.

---

## EXECUTION SEQUENCE:

### 1. Load References

```
Read: "references/agent-frontmatter.md"
Read: "references/tools-reference.md"
Read: "references/permission-modes.md"
```

### 2. Gather Description

```yaml
AskUserQuestion:
  header: "Purpose"
  question: "Describe what this agent does and WHEN Claude should delegate to it. Be specific - Claude uses this to decide delegation. Example: 'Expert code reviewer for PR analysis. Use when reviewing code changes for security, logic, or performance.'"
```

Store in {description}.

### 3. Choose Model

```yaml
AskUserQuestion:
  header: "Model"
  question: "Which model should this agent use?"
  options:
    - label: "Haiku (Recommended for fast tasks)"
      description: "Fast and cheap. Best for: search, scan, simple checks, read-only tasks."
    - label: "Sonnet"
      description: "Balanced. Best for: code generation, analysis, most tasks."
    - label: "Opus"
      description: "Most capable. Best for: complex reasoning, architecture, planning."
    - label: "Inherit"
      description: "Use parent's model. Best when you don't want to override."
```

### 4. Choose Tools

```yaml
AskUserQuestion:
  header: "Tools"
  question: "What tools does this agent need?"
  options:
    - label: "Read-only"
      description: "Read, Grep, Glob - safe exploration only"
    - label: "Read + Write"
      description: "Read, Write, Edit, Grep, Glob - file modifications"
    - label: "Full dev"
      description: "Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch"
    - label: "Custom"
      description: "I'll specify the exact tool list"
  multiSelect: false
```

If "Custom" selected, ask for comma-separated list.

Map selections:
- Read-only → "Read, Grep, Glob"
- Read + Write → "Read, Write, Edit, Grep, Glob"
- Full dev → "Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch"

Also ask about disallowed tools:

```yaml
AskUserQuestion:
  header: "Blocked"
  question: "Should any tools be explicitly blocked? (Usually not needed)"
  options:
    - label: "None (Recommended)"
      description: "Don't block any tools beyond the allowed list"
    - label: "Block Bash"
      description: "Prevent command execution"
    - label: "Block Write/Edit"
      description: "Read-only, no file modifications"
    - label: "Custom"
      description: "I'll specify tools to block"
```

### 5. Choose Permission Mode

```yaml
AskUserQuestion:
  header: "Permissions"
  question: "How should this agent handle permission prompts?"
  options:
    - label: "Default (Recommended)"
      description: "Standard permission prompts for sensitive operations"
    - label: "Accept Edits"
      description: "Auto-accept file edits. Good for code generation agents."
    - label: "Plan (read-only)"
      description: "Read-only exploration mode. No modifications allowed."
    - label: "Don't Ask"
      description: "Auto-deny all permission prompts. For background tasks."
```

### 6. Choose Skills to Preload (optional)

```yaml
AskUserQuestion:
  header: "Skills"
  question: "Should any skills be preloaded into this agent? Preloaded skills inject their full content at startup."
  options:
    - label: "None (Recommended)"
      description: "Agent operates without preloaded skills"
    - label: "Select skills"
      description: "I'll choose which skills to preload"
```

If "Select skills", list available skills and let user choose.

### 7. Design System Prompt

Ask the user to describe the agent's behavior:

```yaml
AskUserQuestion:
  header: "Behavior"
  question: "Describe the agent's behavior pattern. Choose a template or describe custom behavior."
  options:
    - label: "Explorer"
      description: "Search codebase, read files, report findings. Workflow: Search → Read → Analyze → Report."
    - label: "Modifier"
      description: "Read code, make changes, validate. Workflow: Read → Edit → Validate → Report."
    - label: "Validator"
      description: "Check conventions, rules, quality. Workflow: Scan → Check → Report issues."
    - label: "Custom"
      description: "I'll describe the workflow and behavior"
```

If "Custom", ask for detailed description of:
1. What the agent does when invoked
2. The workflow steps (numbered)
3. Key execution rules
4. Output format

### 8. Show Design Summary

```
Agent Design:

| Field | Value |
|-------|-------|
| Name | {agent_name} |
| Description | {description} (truncated) |
| Model | {model} |
| Tools | {tools} |
| Blocked tools | {disallowed_tools} |
| Permission mode | {permission_mode} |
| Preloaded skills | {preloaded_skills} |
| Behavior pattern | {pattern} |
| Category | {category} |

→ Generating agent file...
```

---

## SUCCESS METRICS:
- All required fields gathered from user
- Model choice appropriate for agent's purpose
- Tools follow least privilege principle
- Permission mode matches risk level
- System prompt pattern identified

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