Save Playbook

Capture what was just done in this conversation and save it as a reusable playbook.

Use this after completing a workflow that should be repeatable. The skill analyzes the conversation history to extract the steps, state changes, and patterns, then generates a properly structured playbook.

When to Use

After completing a multi-step task you'll need to repeat
When you realize "I should save this as a procedure"
To document a workflow while the context is fresh
To convert ad-hoc work into structured automation

Workflow

Step 1: Analyze Conversation History

Review the current conversation to identify:

What was the goal? - The user's original request or intent
What steps were taken? - The sequence of actions performed
What was read? - Files, APIs, or state that was consulted
What was written? - Files, APIs, or state that was modified
What tools were used? - Which Claude Code tools were invoked
Were there decision points? - Places where human judgment was needed
What was the outcome? - The final result or deliverable

Step 2: Determine Playbook Name

If name provided as argument ($0), use it.

Otherwise, derive from the goal:

Use lowercase-with-hyphens
Be descriptive: deploy-to-staging not deploy
Prefix with verb: generate-, sync-, update-, create-

Step 3: Classify Complexity Tier

Based on conversation analysis:

Tier 1 - Simple Skill (no state management):

Task was stateless (no files read/written)
One-shot execution, immediate output
No side effects to track

Tier 2 - Stateful Skill (has state dependencies):

Read or wrote files/APIs
But was a one-time manual execution
No scheduling or automation needed

Tier 3 - Full Playbook (needs reliability):

Should run on a schedule
Needs approval gates (had decision points)
Failure recovery matters
Will run unattended

If unclear, ask user which tier fits best.

Step 4: Determine Automation Level (Tier 3 only)

If Tier 3, classify:

| If the workflow... | Automation = | |-------------------|--------------| | Could run completely unattended | autonomous | | Had decision points needing human judgment | gated | | Required human oversight throughout | manual |

Step 5: Extract State Dependencies (Tier 2-3)

From the conversation, identify:

| Source | Location | Read | Write | Description |
|--------|----------|------|-------|-------------|

Look for:

Files that were cat, Read, or opened
Files that were Write, Edit, or created
APIs that were called (GET = read, POST/PUT = write)
Git operations (status = read, commit/push = write)
Databases queried or updated

Step 6: Extract Process Steps

Distill the conversation into clear, numbered steps:

Strip out false starts, debugging, and errors
Keep the successful path
Generalize specific values to parameters ($0, $1, etc.)
Note where approval was needed (mark with [APPROVAL GATE])
Identify the final "write state" actions

Step 7: Determine Location

| Scope | Location | Choose When | |-------|----------|-------------| | Personal | ~/.claude/skills/[name]/ | Only you will use it | | Project | .claude/skills/[name]/ | Team should share it |

Default to project scope.

Step 8: Generate Playbook

Use the appropriate template structure:

Tier 1:

---
name: [name]
description: [derived from goal]
allowed-tools: [tools used in conversation]
user-invocable: true
---
# [Title]
## Purpose
## Process
## Outputs

Tier 2:

---
name: [name]
description: [derived from goal]
allowed-tools: [tools used]
user-invocable: true
---
# [Title]
## Purpose
## State Dependencies
[table]
## Process
## Outputs

Tier 3:

---
name: [name]
description: [derived from goal]
automation: [level]
allowed-tools: [tools used]
user-invocable: true
---
# [Title]
## Purpose
## State Dependencies
## Prerequisites
## Process
### Step 1: Read Current State
### Step N: [extracted steps]
### Final Step: Write Updated State
## Completion Checklist
## Error Recovery

Step 9: Present and Confirm

Show the generated playbook:

## Captured Playbook: [name]

**Based on:** [summary of what was done]
**Tier:** [1/2/3]
**Automation:** [level or n/a]
**Location:** [path]

**State Dependencies:**
[list or "none"]

**Process:** [N] steps
1. [step summary]
2. [step summary]
...

---

[Full SKILL.md content preview]

---

Save this playbook?

Step 10: Create Playbook

After confirmation:

mkdir -p [location]

Write SKILL.md to the location.

Verify:

cat [location]/SKILL.md | head -20

Inform user they may need to restart Claude Code.

Extraction Patterns

Identifying Steps from Conversation

Look for:

Tool calls (Bash, Read, Write, Edit, etc.)
"Let me...", "Now I'll...", "Next..."
Sequential actions toward the goal
User confirmations or approvals

Generalizing Values

Replace specific values with parameters:

| Specific | Generalized | |----------|-------------| | src/components/Button.tsx | $0 (first argument) | | 2025-02-10 | $(date +%Y-%m-%d) | | fix: update button styling | $1 (second argument) | | Hardcoded API key | $API_KEY (env variable) |

Handling Errors and Retries

If the conversation included errors:

Extract the successful path only
Optionally add error handling based on what failed
Note common failure modes in Error Recovery section

Examples

Example 1: Capturing a Deploy Workflow

After deploying an app:

User: /save-playbook deploy-to-staging

Conversation analysis:
- Goal: Deploy app to staging environment
- Steps: Build → Test → Deploy → Verify
- State: Read package.json, wrote dist/, called deploy API
- Decision point: Confirmed deployment after seeing diff

Generated: Tier 3 gated playbook with approval before deploy

Example 2: Capturing a Simple Transform

After converting a file format:

User: /save-playbook convert-csv-to-json

Conversation analysis:
- Goal: Convert CSV file to JSON
- Steps: Read CSV, transform, output JSON
- State: Read input file, wrote output file
- No scheduling needed

Generated: Tier 2 stateful skill

Example 3: Capturing a Code Explanation

After explaining code:

User: /save-playbook explain-function

Conversation analysis:
- Goal: Explain what a function does
- Steps: Read file, analyze, explain
- State: Read-only, no writes
- Pure analysis

Generated: Tier 1 simple skill

Tips

Save early: Capture while context is fresh
Review before saving: Edit the generated playbook if needed
Name clearly: Future you should understand what it does
Consider audience: Personal skill or team skill?

Related Skills

| Skill | Purpose | |-------|---------| | create-playbook | Create from scratch (no conversation to capture) | | adjust-playbook | Modify an existing playbook | | playbook-architect | Audit and improve existing skills |