1
Define
Declare typed inputs, write steps in natural language, add directives for outputs, tool calls, and human checkpoints. It's a markdown file in your repo.
PLAYBOOK.md is an open specification for multi-step AI workflows. Define inputs, chain steps, branch on conditions, loop in humans — all in a .md file any model can read, write, and run.
See it in action
A playbook is just a markdown file. Here's one that triages incoming issues:
--- name: Issue Triage description: Classify and route incoming issues --- ## INPUTS - `issue` (text): Issue description from the reporter - `project` (string): Project name for context ## STEP 1: Classify You are triaging issues for the {{project}} project. Read the issue and classify it as: "bug", "feature", or "question". {{issue}} @output(issue_type, extract:"classification") ## STEP 2: Route ```if issue_type == "bug"``` Analyze this bug report for {{project}}. Provide: summary, reproduction steps, severity, affected area. ```elif issue_type == "feature"``` Draft a lightweight feature spec for {{project}}. ```else``` Provide a helpful answer about {{project}}. ```endif```
PLAYBOOK.md defines multi-step AI workflows in plain markdown. Think OpenAPI for APIs or Dockerfiles for containers, but for AI agent workflows.
Declare typed inputs, write steps in natural language, add directives for outputs, tool calls, and human checkpoints. It's a markdown file in your repo.
Any runtime that implements the spec can parse and run your playbook. Pass inputs, and the engine chains steps with variable interpolation and branching.
Each step produces outputs. Branch on them, loop back, or collect final artifacts. The playbook is the workflow and its documentation in one file.
PLAYBOOK.md is a specification, not a product. MIT-licensed code, CC BY 4.0 spec. Build on it, fork it, implement it — no permission needed.
No YAML to wrestle, no proprietary editor required. If you can write a README, you can write a playbook. It's the format you already know.
Write once, execute with any LLM provider, any model, any runtime. Your workflows belong to you, not to a vendor.
A playbook is a file. Diff it, review it, branch it, merge it. Your AI workflows get the same rigor as the rest of your codebase.
Markdown is the most-represented format in LLM training data. Models read and write playbooks without format translation, parsing edge cases, or lossy serialization.
No separate docs to maintain, no diagrams to keep in sync. Read a playbook and you understand the workflow. Hand it to a new team member and they're onboarded.
Markdown isn't just convenient for humans — it's the native format of the models that execute your workflows. LLMs were trained on more markdown than any other structured format. They parse it without edge cases. They generate it without escaping errors. They don't need a serialization layer between "understand the workflow" and "run the workflow."
That matters when agents are both the authors and the executors. An agent can generate a playbook, hand it to another agent, and it runs. No format translation. No schema validation failures from a misplaced comma. No lossy round-trip through a format the model has to fight.
Try it. Ask any model to generate a multi-step workflow as YAML, then as a PLAYBOOK.md. Compare the error rates.
You don't need to be a developer to write a playbook. If you can write a bullet list, you can define a multi-step AI workflow — give it inputs, tell it what to do at each step, and get structured results back. Markdown isn't a programming language. It's the way you already write notes, docs, and outlines.
You already write specs, briefs, and runbooks. A playbook is the same thing — except the AI can actually run it. Define the steps, set the inputs, hand it off.
Build a playbook that takes a feature brief, generates user stories, drafts acceptance criteria, and outputs a prioritized backlog — ready for sprint planning.
Stop re-prompting from scratch every time. Write a playbook once for your content pipeline — research, outline, draft, polish — and reuse it across every piece you publish.
Build a playbook that takes a topic and target platform, researches key angles, writes a draft, adapts the tone for LinkedIn vs. newsletter vs. Twitter, and outputs all three versions.
Client onboarding, proposal generation, weekly reporting — you've done these a hundred times. Write the steps down as a playbook and let AI handle the repetition while you focus on the business.
Build a playbook that takes a new client's name, industry, and goals, then generates a welcome email, a kickoff agenda, and a 30-day onboarding checklist.
Chatbot flows, support scripts, interactive experiences — describe the conversation step by step in a format that's readable by your team and executable by any AI runtime. No flowchart tool required.
Build a playbook that walks a user through troubleshooting a product issue — asks clarifying questions, narrows down the cause, and generates a resolution summary for the support ticket.
Everything you need to read, write, and run playbooks.
The full specification. Seven docs covering inputs, steps, directives, branching, and more.
Web-based editor and validator. Write playbooks and check them against the spec in real time.
Curated example playbooks. Ten real-world workflows across four categories to learn from.
TypeScript types and JSON Schema for validation. Build tooling that understands playbooks.
Read the spec, browse real-world examples, or drop into the playground and start writing.