Agent runbooks

A runbook is an ordinary skill whose body is a procedure: the steps, who does each one, what each reads and writes, and where to stop and ask a human. There is no DSL and no runner. The steps are prompts, and the model does the work. A small Python script, flow.py, keeps the model on the procedure. It holds the flow and the state of a run and tells the orchestrator what to do next, so the choice of the next branch, where prose drifts, is never left to reasoning.

The session that invokes the runbook becomes its orchestrator. A step that needs judgement goes to a subagent, the executor. A step whose result a fixed algorithm computes, such as the tests or a build, is a code step, a function in flow.py that flow.py runs itself. A human step is a question to the human. State lives in a run directory, .agent-runbooks/runs/<run-id>/, and steps pass work to each other through files there, not through the orchestrator's context.

A finished runbook is self-sufficient. It carries its own execution rules, executor constraints, its steps and flow as a small Python file, and a copy of the engine that runs them, so it runs where this skill is not installed. The engine can come from PyPI instead of the copy, see references/template.md. This skill is for the author, not the orchestrator.

When a runbook fits

Write one when the procedure has three or more steps, will be repeated, and involves several executors (models, harnesses, roles). A one-off task or a single subagent call is a prompt, not a runbook.

What the orchestrator sees

Design for a reader that reads the runbook's SKILL.md and what flow.py prints, and copies each step's JSON reply into flow.py. It opens no other file and runs no other command, except the status of the run when the runbook-viewer skill is installed. Transitions are computed by flow.py from the replies, never reasoned about. So anything you want checked lives in a prompt, or in a following step that runs the command and reports a field. Anything the next step needs to know lives in a file the next step's prompt names. The shape of a report is taken on the executor's word. Facts about the code and the outcome of commands are checked by a step.

Writing a runbook

Work through these in order. The output is a skill directory shaped like references/template.md. A complete one: references/runbook-review-loop. It needs only the harness's own subagent tool, so a copy of it in a skills directory runs as it is.