Agent Runbook

Agent Runbook

Core Principle

Instructions as Code. Executable, repeatable, autonomous.

A runbook is a step-by-step guide that an AI agent can execute without human intervention (except for explicit decision points). The agent reads it and does the work.

When to Use

Use this skill when:

• Creating setup/installation guides for agents
• Automating multi-step workflows
• Building onboarding scripts
• Documenting repeatable processes
• Creating self-service automation

Runbook Anatomy

Every runbook follows this structure:

# [Title] - [Purpose]

**Last Updated:** [Date]
**Version:** [X.Y]

---

## 🤖 For AI Coding Agents

[Brief description of what this runbook does]

**Your goal:** [Clear statement of the end state]

---

## Step 0: Prerequisites Check

[Commands to verify environment is ready]

---

## Step 1-N: Execution Steps

[Each step with commands + decision points]

---

## Verification

[How to confirm success]

---

## Troubleshooting

[Common issues and solutions]

Step 0: Gather Requirements

Ask the user:

"What type of runbook do you need?"

• Setup/Installation → Environment configuration, tool installation
• Workflow/Process → Multi-step business or dev process
• Migration/Upgrade → Moving from one state to another
• Maintenance/Cleanup → Periodic tasks, housekeeping

Record: [RUNBOOK_TYPE]

"What is the runbook's purpose? (one sentence)" Record: [PURPOSE]

"What are the key decision points where the agent should ask the user?" Record: [DECISION_POINTS]

Step 1: Create File Structure

# Determine location
RUNBOOK_NAME="[snake_case_name]"

# Option A: Standalone runbook in project root
touch "${RUNBOOK_NAME}.md"

# Option B: Runbook as a skill (reusable)
mkdir -p .claude/skills/[category]/${RUNBOOK_NAME}
touch .claude/skills/[category]/${RUNBOOK_NAME}/SKILL.md

Step 2: Write Header Section

# [Title] - [Subtitle]

**Last Updated:** [Current Date]
**Version:** 1.0

---

## 🤖 For AI Coding Agents

This file contains **complete instructions** for [PURPOSE].
You (the AI agent) should execute these steps autonomously.

**Your goal:** [END_STATE - what success looks like]

---

Key elements:

• Clear title indicating what the runbook does
• Version for tracking changes
• Explicit statement that this is for agents
• Goal statement (the "done" criteria)

Step 3: Write Prerequisites Check

## Step 0: Prerequisites Check

Run these commands and record results:

\`\`\`bash
# Check [tool1]
[command] --version

# Check [tool2]  
[command] --version

# Check current state
[diagnostic command]
\`\`\`

**If [condition]:** [Tell user what to do]
**If [other condition]:** [Alternative path]

Pattern:

1. List all required tools/conditions
2. Provide check commands
3. Define what to do if checks fail
4. Never assume - always verify

Step 4: Write Execution Steps

Each step follows this pattern:

## Step N: [Action Title]

**Agent Instructions:** [Brief context for why this step exists]

### [Sub-action if needed]

\`\`\`bash
# Comments explaining what this does
[command]
[command]
\`\`\`

### Decision Point (if applicable)

**Ask the user:**

"[Question requiring user input]?"
- **Option A** → [What happens if chosen]
- **Option B** → [What happens if chosen]
- **Option C** → [What happens if chosen]

**Record answer:** `[VARIABLE_NAME]`

### Conditional Execution

**If [VARIABLE_NAME] = "Option A":**

\`\`\`bash
[commands for this path]
\`\`\`

**If [VARIABLE_NAME] = "Option B":**

\`\`\`bash
[commands for this path]
\`\`\`

Best practices:

• One logical action per step
• Commands in code blocks (executable)
• Decision points clearly marked with "Ask the user:"
• Variables in [BRACKETS] or backticks
• Conditional paths clearly labeled

Step 5: Write Verification Section

## Verification

**Run verification checks:**

\`\`\`bash
# 1. Check [first thing]
[command]

# 2. Check [second thing]
[command]

# 3. Check [third thing]
[command]
\`\`\`

**Success criteria:**

- ✅ [Criterion 1]
- ✅ [Criterion 2]
- ✅ [Criterion 3]

**If all checks pass:** [Success message] 🎉

Key elements:

• Concrete verification commands
• Checklist with ✅ markers
• Clear success/failure criteria

Step 6: Write Troubleshooting Section

## Troubleshooting

### Issue: [Problem description]

**Solution:**

\`\`\`bash
[fix commands]
\`\`\`

### Issue: [Another problem]

**Solution:**

[Explanation and fix]

Include:

• Common failure modes
• Error messages users might see
• Copy-paste solutions
• Links to external docs if needed

Step 7: Add Reference Section (Optional)

## Reference

**Full Documentation:** [URL]

**Related Resources:**
- [Resource 1]
- [Resource 2]

**Available Options:**
- **Option A:** [Description]
- **Option B:** [Description]

---

## Support

**Issues?** [Where to report]
**Questions?** [Where to ask]

Runbook Design Patterns

Pattern 1: Detection → Ask → Execute

### Automatic Detection

\`\`\`bash
# Detect current state
if [ -d ".git" ]; then
  echo "STATE=git-initialized"
else
  echo "STATE=no-git"
fi
\`\`\`

### Ask User to Confirm

**Present the user with a question:**

"We detected [STATE]. Is this correct?"
- **Yes** → Continue with detected settings
- **No, change to X** → Use alternative

**Record answer:** `[CONFIRMED_STATE]`

### Execute Based on State

**If [CONFIRMED_STATE] = "git-initialized":**
[commands]

Pattern 2: Gather All → Execute All

## Configuration (Answer All Questions First)

**Q1:** "What is your project name?"
**Record:** `[PROJECT_NAME]`

**Q2:** "Which framework?"
- React
- Vue
- Svelte

**Record:** `[FRAMEWORK]`

**Q3:** "Include testing?"
- Yes
- No

**Record:** `[INCLUDE_TESTS]`

---

## Execution (Now Run Everything)

\`\`\`bash
# Using recorded values
npx create-[FRAMEWORK]-app [PROJECT_NAME]

# If [INCLUDE_TESTS] = yes
npm install --save-dev jest
\`\`\`

Pattern 3: Idempotent Steps

## Step N: Install Package

\`\`\`bash
# Check if already installed
if ! command -v [tool] &>/dev/null; then
  echo "Installing [tool]..."
  [install command]
else
  echo "[tool] already installed, skipping"
fi
\`\`\`

Quick Reference

Runbook Structure:
├── Header (title, version, goal)
├── Step 0: Prerequisites
├── Steps 1-N: Execution
│   ├── Commands (in code blocks)
│   ├── Decision Points ("Ask the user:")
│   └── Conditional Paths (If X = Y:)
├── Verification (success criteria)
├── Troubleshooting (common issues)
└── Reference (optional)

Key Markers:
  **Agent Instructions:**  → Context for the agent
  **Ask the user:**        → Decision point (pause for input)
  **Record:**              → Store user's answer
  **If [VAR] = "X":**      → Conditional execution
  ✅                       → Success criterion
  🎉                       → Completion celebration

Variables:
  [VARIABLE_NAME]          → User input placeholder
  `$VARIABLE`              → Shell variable
  [command]                → Placeholder for actual command

Example: Mini Runbook

# Database Setup - Local PostgreSQL

**Version:** 1.0

---

## 🤖 For AI Coding Agents

**Your goal:** Set up local PostgreSQL with a project database.

---

## Step 0: Prerequisites

\`\`\`bash
which psql || echo "PostgreSQL not installed"
\`\`\`

---

## Step 1: Get Configuration

**Ask the user:**

"What should the database be named?"
**Record:** `[DB_NAME]`

"Create a dedicated user? (recommended)"
- **Yes** → Create user with same name as DB
- **No** → Use default postgres user

**Record:** `[CREATE_USER]`

---

## Step 2: Create Database

\`\`\`bash
createdb [DB_NAME]
\`\`\`

**If [CREATE_USER] = Yes:**

\`\`\`bash
createuser [DB_NAME] --createdb
psql -c "ALTER USER [DB_NAME] WITH PASSWORD '[DB_NAME]123';"
\`\`\`

---

## Verification

\`\`\`bash
psql -d [DB_NAME] -c "SELECT 1;"
\`\`\`

**Success:** ✅ Query returns 1

---

## Troubleshooting

### Issue: `createdb: command not found`

\`\`\`bash
# macOS
brew install postgresql@15
brew services start postgresql@15
\`\`\`

Validation Checklist

Before finalizing a runbook, verify:

• Header has title, version, and goal
• Prerequisites check all dependencies
• Steps are numbered and logical
• Commands are in code blocks
• Decision points use "Ask the user:" pattern
• Variables are clearly marked with [BRACKETS]
• Conditionals cover all paths
• Verification has concrete success criteria
• Troubleshooting covers common failures
• Idempotent - can run multiple times safely

Anti-Patterns to Avoid

❌ Vague instructions: "Configure the database appropriately" ✅ Specific commands: "Run createdb myapp_dev"

❌ Assumed knowledge: "Set up Docker" ✅ Explicit steps: "Install Docker: brew install docker"

❌ Missing decision points: Silently picking defaults ✅ Explicit choices: "Ask the user: Which option?"

❌ No verification: "You're done!" ✅ Concrete checks: "Run docker ps - should show container running"

❌ Monolithic steps: One giant step with 50 commands ✅ Atomic steps: One logical action per step