A workflow script is a program that launches your agents step by step. It fixes the main problem of multi-step agent work: code picks the next step, so the model can't skip the review or lose count of the fix rounds. I wrote dozens of them for Claude Code, and they did their job.
But a Claude Code workflow takes no input once it's running. It can't stop in the middle to ask me a question, and I kept tripping over that. A procedure that needed my answer halfway had to be cut into smaller workflows, with a gap between them where I could be asked.
A workflow is also tied to one vendor. It runs only inside Claude Code, and it can spawn only Claude agents. In my procedures Claude writes the code and Codex reviews it, so every review step was a workaround.
So every workflow I still run became a runbook: an Agent Skill with a set of prompts and a page of Python that picks the next step. It asks me when a decision is mine. Because it's a skill, it runs in any agent harness, the tool you run an agent in: Claude Code, Codex, OpenCode and so on. Each step goes to the model I name for it, whatever the vendor. And the state of a run is in files, so a lost session doesn't lose the run.
I've tested the approach at my day job, on a production codebase of over 4 million lines. AI agents write the code there and carry out the main procedures, and they now do it through runbooks.
In this article, I'll show what's inside a runbook, follow one change through it on a small repository, and show where it falls short of a workflow script.
Where Claude Code workflows fell short
My example is the workflow that ran every code task on throng-mcp, one of my open-source projects. It was JavaScript for the Claude Code Workflow tool, and the procedure in it had five steps:
- A coder implements the brief.
- The checks run.
- Two reviewers from different vendors read the diff.
- A third agent sorts their findings.
- The coder fixes what's left.
It worked. Here's where it got in my way.
- It can't ask me anything. When mine still had blocking findings after two rounds of fixes, it could only end and tell me to sort them out by hand.
- It runs in one vendor's tool. The orchestrator, the main session that launches the steps and waits for them, could only be Claude.
- Another vendor's model on one step is a workaround. My second reviewer was Codex, so the workflow spawned a cheap Claude agent as a relay. Its whole job was to make one call to an MCP server that ran the Codex review, and to hand the answer back.
- A run lives in the session. The Workflow tool keeps the state of a run inside the session. When the session was gone, the run was gone with it, and a procedure this long does get interrupted.
- The prompts are inside the program. In my workflow the prompts were strings in the JavaScript, next to the launch logic. To see what the reviewer was asked to do, you read a program.
So I stopped writing workflows and moved the procedures into skills.

A runbook is an Agent Skill
A runbook installs as an ordinary Agent Skill, and you start it like any other skill: you ask your agent to run it. From there the main session goes step by step. It launches a separate agent, a subagent, with the step's prompt. It collects the subagent's reply. Then it runs a small Python program to find out what comes next.
I like to think of the Python program as the referee of a board game. The referee knows the rules, whose turn it is and when the game is over. The players still decide what to do on their turn. In a runbook the players are the subagents, and your main session is the person who moves the pieces where the referee points.
Here's what's inside the smallest runbook, runbook-review-loop:
SKILL.md what the main session reads: inputs, execution rules, end of run flow.py the procedure: its steps and their order agent_runbooks.py the engine that flow.py imports, bundled with the runbook prompts/ one prompt per step Each step has a prompt file and an executor. An executor is a description of who runs the step, such as "the model of the main session" or "GPT-6.1 Sol at xhigh effort". The session maps it onto what it can launch. Here are the two executors and the review step:
coder = rb.executor('coder', 'the model of the main session') reviewer = rb.executor('reviewer', 'GPT-6.1 Sol at xhigh effort') review = rb.step( 'review', executor=reviewer, prompt='prompts/02-review.md', reads=['brief.md', 'implement.md', 'fix.md', 'working tree'], writes=['review.md'], reply={'findings': {'type': 'integer'}}, ) The published runbook gives both roles to the main session's model. I moved the reviewer to another model here to show that it takes one line.
The flow is one Python function, where a loop is a while and a branch is an if:
@rb.flow def main(ctx): yield implement() budget, used = ctx.inputs.maxFixRounds, 0 while True: r = yield review() if r.findings == 0: return end('ready', 'read <run>/review.md') if used >= budget: a = yield ask_rounds() if a.choice == 'stop': return end('needs_attention', 'read <run>/review.md') budget += a.rounds yield fix() used += 1 The session runs flow.py, and it prints the next launch: which executor to use and the exact message for the subagent. The session launches a subagent with that text, waits, and passes the subagent's last JSON object back to flow.py. The reply is typed. The review step returns {"findings": 1}, and flow.py decides from that number what comes next: a fix, a question to the human, or the end of the run. The model does the step. The code picks the next step.
Steps pass their work through files in a run directory, so the main session doesn't carry every step's output in its context. The state of the run is state.json in the same directory. A new session with access to that directory can run python3 flow.py <run> and get the next action.
The engine comes with the runbook, so there are no external dependencies beyond Python 3.9 or newer. Mixing vendors is optional. A step for another vendor's model needs some way to launch that model from your session. I use throng-mcp, an MCP server I wrote for that, and any other tool that starts an agent would do.
A fair question is why flow.py doesn't launch the subagents itself, with claude -p or codex exec. The tool you start the skill from already knows how to run agents. Building that a second time inside the runbook would force my way of orchestrating on you, and I think that does more harm than good. So the runbook only says what to launch next, and your session does it with its own tools and permissions. I start mine from T3 Code, with Claude or Codex as the main session. A step's question arrives in the chat you already have open. In CI, where nobody is in the chat, I hand those questions to a separate agent that makes the decisions.
The executors never talk to each other: each one reads what the previous step left in the run directory. In computing that's a blackboard system, and the version with no referee is what biologists call stigmergy, after Grassé's termites.
One run, start to finish
The example repository is a Python package with a slugify function and five unit tests. The brief asks for an optional max_length parameter that limits the length of the slug. The checks are python3 -m unittest, and the fix budget is one round.
Here's the report the runbook printed in the chat when the run ended:

And here's the same run in runbook-viewer, an optional page that reads the run directory and lists each step with its time and output:

The brief didn't say what a negative max_length should do. The coder chose to raise ValueError. The reviewer found no errors in the cases it checked, and its one finding was that choice, which it left for me to decide. The fix round changed nothing and wrote down why, the second review kept the finding open, and flow.py asked me:
Fix rounds are spent and
03-review.mdstill lists findings. More rounds, and how many, or stop here? Anything you add goes to the coder.
I answered in the chat: one more round, keep the error, mention it in the CHANGELOG line. The session mapped that onto the choice more rounds with rounds: 1, and flow.py wrote my words to a file the coder reads. The second fix added one line to the CHANGELOG, the third review returned findings: 0, and the run ended ready, the runbook's status for a normal end, with the changes uncommitted and a review file that says what they do.
Six subagent launches, about seven minutes of their time, one question to me, three files changed. The whole run is in the repository, with every step's reply. The example is simplified on purpose, so six agents for one small function can look like overkill. My real tasks are much bigger. There a separate agent per step pays off: each one starts with a clean context, and the context of the main session stays small.
Run statistics
I counted more than 300 real runs that still had their logs. None of them failed because the session didn't follow the runbook.
More than a quarter of the runs went through runbook-implement-task, a bigger runbook with two reviewers from different vendors and a third agent that sorts their findings.
The orchestration itself is cheap. Each step adds about 3,400 tokens to the context of the main session. The work of a step stays in its subagent, and what that costs depends on the task.
Where it falls short
The orchestrator is still a model, and it may not do exactly what flow.py printed. The execution rules in SKILL.md make the session write every deviation into the run's log, so I can count them: in under 8% of my runs the session deviated from the runbook on its own. It guessed a file name instead of using the printed one. It cut a printed launch message with head and rebuilt it from memory.
In my experience these deviations rarely change the result. Mostly they cost the model a few extra steps. This is the one place where a workflow script is stricter, because its code launches the next step itself. In a runbook the referee can announce the next move, and the session can still move the wrong piece. But models are improving fast, so I expect this problem to stop mattering soon.
A runbook has no spending limit of its own. The only cap in the engine is the item count of a foreach, the flow's loop over a list: 50 by default. My biggest run launched 257 subagents: a one-off migration of a large repository, done in chunks that were each validated, reviewed and fixed. It ran through.
Try it
The project is open source, agent-runbooks on GitHub. You need Python 3.9 or newer and a harness whose session can launch subagents and wait for them (basically any harness). Install the smallest runbook into your user directory:
npx skills add agent-runbooks/gallery --skill runbook-review-loop -g Both the coder and the reviewer run on the model of your main session. Ask your agent:
Run runbook-review-loop: <your change>. The checks are <your test command>.
The runbook tells you its progress in the chat when you ask and its final state when the run ends. To follow a run live on the page from the screenshot above, install runbook-viewer as well and ask the agent to open the viewer page.
To write your own, install agent-runbook-authoring with npx skills add agent-runbooks/skills, take a procedure you run by hand every week, and ask the session for a runbook of it. The skill writes it with you.
If you try it, I'd be glad to hear how it went. The Discussions page is open for that.
I start thinking about a runbook when a task needs several subagents that have to work in a certain order. And I always write one once there's orchestration logic on top of those subagents.
Sources
- Runbooks follow the Agent Skills format.
- What runbooks are compared against: Runbooks compared with workflow engines, covering Claude Code workflows, Copilot dynamic workflows, LangGraph, the OpenAI Agents SDK and Mastra.
- The subagent tools the orchestrating session uses: Claude Code subagents and Codex subagents.
- Blackboard systems and stigmergy: L. Erman and others, The Hearsay-II Speech-Understanding System, ACM Computing Surveys, 1980, and G. Theraulaz and E. Bonabeau, A Brief History of Stigmergy, Artificial Life, 1999.


