Introduction

PLAYBOOK.md is an open specification for defining multi-step AI workflows in plain markdown. A playbook is a .md file that describes a sequence of steps — each one a prompt, a tool call, or a human decision point — that execute in order with accumulated context.

Why PLAYBOOK.md?

AI workflows today are locked inside proprietary platforms. If you build a multi-step chain in one tool, you cannot move it to another without rewriting everything. PLAYBOOK.md solves this by defining a portable, human-readable format that any conforming implementation can parse and execute.

A playbook looks like this:

# Content Pipeline

Generate a polished article from a topic and audience.

## INPUTS

- `topic` (string): Subject to write about
- `audience` (enum: technical, general, executive): Target audience

## STEP 1: Research

Research {{topic}} and identify the top 5 key themes
relevant to a {{audience}} audience.

## STEP 2: Draft

Write the full article based on the research above.
Target a {{audience}} audience.

## ARTIFACTS

type: markdown

That is a complete, executable playbook. No YAML config files, no JSON schemas, no SDKs required to read it. Anyone with a text editor can write one.

Who is it for?

Prompt engineers and AI workflow builders who want their work to be portable across tools and providers.

Platform developers building AI orchestration products who want an interoperable format that users can import and export.

Teams that need to version-control, review, and collaborate on AI workflows using the same tools they use for code.

Core concepts

A PLAYBOOK.md file contains a small set of building blocks:

Concept	What it does
Title	Names the workflow. Required.
Inputs	Declares variables the user provides before execution.
Steps	Sequential units of work. Each step is a prompt sent to an AI, a tool call, or a human input request.
Directives	Annotations within steps that control behavior: capture outputs, pause for human input, reference external prompts, or invoke tools.
Branching	Conditional execution paths within a step, based on input values or prior AI outputs.
Artifacts	Declares the expected output format of the final result.

Each concept has a dedicated spec page in the Specification section.

How it relates to existing tools

PLAYBOOK.md is not a runtime. It is a document format. Think of it the way you think about OpenAPI (Swagger) for REST APIs — it defines what a workflow looks like, and implementations bring it to life.

• vs. LangChain / LlamaIndex: These are code-first orchestration libraries. PLAYBOOK.md is a declarative format. You could build a LangChain executor that reads playbooks.
• vs. ChatGPT custom instructions: Custom instructions are single-turn. PLAYBOOK.md defines multi-step workflows with branching, variables, and tool integrations.
• vs. Prompt templates: Template systems handle variable substitution. PLAYBOOK.md adds sequencing, context accumulation, branching, and a standard structure around prompts.

Specification status

PLAYBOOK.md is at v0.1.0 (Draft). The spec was extracted from a production implementation in Promptmark and proposed as a portable, tool-agnostic standard.

The spec is licensed under CC BY 4.0. Code implementations use the MIT license.

Next steps

Ready to write your first playbook? Head to the Quick Start guide.

Want the full technical reference? Start with Format in the Specification section.