Skip to content
PLAYBOOK.md Docs

Quick Start

This guide walks you through creating a simple two-step playbook. By the end, you will have a working .md file that any PLAYBOOK.md-conforming implementation can execute.

Step 1: Create the file

Create a new file called my-first-playbook.md. A playbook is just a markdown file, so use whatever editor you prefer.

Step 2: Add a title

Every playbook starts with a level-1 heading. This is the only required structural element besides at least one step.

# My First Playbook


A simple two-step workflow that researches a topic and writes a summary.

The text after the title is the description. It is metadata — it does not get sent to the AI during execution.

Step 3: Declare inputs

Inputs define the variables your playbook accepts. Add an ## INPUTS section with one variable:

## INPUTS


- `topic` (string): The subject to research and summarize

This declares a required input called topic of type string. When someone runs the playbook, they provide a value for topic before execution starts.

Step 4: Add the first step

Steps use ## STEP N: Title headings. The number must be sequential starting from 1. Everything after the heading is the prompt sent to the AI.

## STEP 1: Research


Identify the 3 most important aspects of {{topic}}.


For each aspect, provide:
- A one-sentence summary
- Why it matters
- One concrete example

The {{topic}} placeholder is replaced with the user’s input value at execution time.

Step 5: Add the second step

Add a second step that builds on the first. You do not need to manually reference Step 1’s output — PLAYBOOK.md uses context accumulation, meaning each step automatically receives the outputs of all prior steps.

## STEP 2: Summarize


Based on the research above, write a concise 3-paragraph summary
of {{topic}} suitable for a general audience.


Lead with the most impactful finding.

The AI executing Step 2 sees both the Step 2 prompt and the full output from Step 1.

The complete playbook

Here is your finished file:

# My First Playbook


A simple two-step workflow that researches a topic and writes a summary.


## INPUTS


- `topic` (string): The subject to research and summarize


## STEP 1: Research


Identify the 3 most important aspects of {{topic}}.


For each aspect, provide:
- A one-sentence summary
- Why it matters
- One concrete example


## STEP 2: Summarize


Based on the research above, write a concise 3-paragraph summary
of {{topic}} suitable for a general audience.


Lead with the most impactful finding.

That is a valid, executable PLAYBOOK.md file. It has:

  • A title (# My First Playbook)
  • One input (topic)
  • Two sequential steps with variable interpolation
  • Context accumulation between steps (automatic)

Running it

You can execute this playbook in any tool that supports the PLAYBOOK.md specification:

What to try next

Now that you have the basics, explore more features:

  • Inputs — Add typed variables with defaults, enums, and multi-line text
  • Directives — Capture named outputs with @output, pause for human input with @elicit, invoke tools with @tool
  • Branching — Route execution conditionally based on input values or AI outputs
  • Examples — Browse the curated gallery of real-world playbooks