A runbook is how you give an AI its job.

It's one short markdown file. It says what you want done, what “done” looks like, and what to check before calling it finished. You write it once. You — or your team — can run it a hundred times after that.

That's it. The idea is small on purpose.

The equation

You may have spent time already building skills — careful instructions that tell an AI how to do a specific thing. Maybe a custom GPT. Maybe a Claude skill. Maybe a notes file you copy and paste into every session.

A skill is half of what you need. The other half is a standard — what “good” looks like for the work it's doing, and how to tell whether it got there.

Skills + standards = runbooks.

A skill, on its own, is a set of instructions. A runbook is a set of instructions plus the definition of done. That second half is what lets you trust it to run without you watching.

The three parts of a runbook

Every runbook has three parts. You can write them in any order, and you can make them as short or as detailed as the task calls for.

1. The job

What do you want done? Written the way you'd describe it to a new hire on their first day. Specific enough that someone could follow it. Short enough that they wouldn't lose the thread.

Read the uploaded PDF. Pull out the author, title, and dataset description. Cross-check the dataset name against Hugging Face. Produce a one-page summary.

2. What “done” looks like

What does the finished work need to contain? What would make you send it back?

The summary must include all three fields (author, title, dataset description).
The Hugging Face cross-check must either confirm a match or note that none was found.
The summary must be at most one page.
No field can be left blank.

This is the part most people forget to write down. It's also the part that turns a hopeful request into a reliable one.

3. How to check the work

Before the AI declares done, what should it verify? These can be simple checks — did it produce the right files, are the required sections there — or more careful ones involving a second model reviewing the output.

Confirm all output files exist and are not empty.
Re-read the summary and confirm every required field is present.
If any check fails, fix the work and check again. Up to three tries.

The AI checks its own work. If it finds something wrong, it tries again. If it can't fix it in a few tries, it tells you — rather than quietly shipping something broken.

Why markdown

A runbook is a plain text file. Nothing fancy. That sounds like a limitation at first, and it isn't.

You can read it. Six months from now, you can open the file and know exactly what it does.

You can share it. Anyone on your team can open, read, and edit a markdown file. No software to install, no platform to log into.

You can version it. Put it in a folder, track it in Dropbox or GitHub, keep a history. When you change it, you can see what changed and roll back if you need to.

You can hand it to any AI. Today your AI of choice might be Claude. Next month it might be a newer model. A runbook written in plain English works with whichever AI you point it at. You own the instructions. The AI is replaceable.

How a runbook is different from…

…a prompt. A prompt is a request. “Summarize this document.” A runbook is a specification. “Summarize this document — here's what must be in the summary, and here's how to check you got it right.” A prompt is what you say to an AI. A runbook is what you'd write for a new hire.

…an agent skill. A skill (Claude's or ChatGPT's) is a reusable instruction set you attach to a conversation. It tells the AI how to do something. A runbook takes a skill and adds what “done” looks like plus a way to check. Skills go in a runbook. Runbooks are what you actually run.

…a workflow tool. Tools like Zapier or n8n wire pre-built actions together. A runbook is one step further: you describe the outcome, and the AI figures out the steps. You don't have to pre-build every integration. You describe what you want, and Jetty provides the workspace for the AI to work it out.

A real one, start to finish

Here's a runbook for reviewing marketing content against a brand voice guide. You might write something like this if you're a marketing lead who's tired of being the voice-compliance reviewer.

# Brand voice review

## The job

Read the uploaded draft. Check it against our brand voice guide (uploads/brand-voice.md).
Produce a marked-up version of the draft with inline comments on anything that breaks
our voice rules, and a one-paragraph summary of the top changes needed.

## What "done" looks like

- Every paragraph of the draft has been reviewed.
- Any banned words (see brand-voice.md) are flagged with a suggested replacement.
- The summary calls out the top three issues by frequency.
- The marked-up draft is saved as a .md file in results/.
- The summary is saved as summary.md in results/.

## How to check

- Confirm both files exist in results/ and are not empty.
- Confirm the summary mentions exactly three issues, prioritized by frequency.
- Re-read the marked-up draft and verify every banned word has a suggested replacement.
- If any check fails, fix and recheck. Three tries max.

That's a working runbook. A team could run that every day against a week's worth of drafts. The first version would have rough edges. The fifth version — after you and your team have flagged a few misses and added them to the rules — would be better than any individual human reviewer, because it's consistent.

This is the point. You don't get a great runbook by writing it once. You get there by running it, watching where it falls short, and editing the file. That's how trust is built: by iterating. The AI is the intern; the runbook is the process doc. Both get better the more the work runs through them.

Where runbooks come from

Jetty has a few starting points depending on where you are.

If you already have Claude skills, the fastest path is to turn one into a runbook. Start here.
If you've got a task in your head but no written instructions, we can help you draft one. Step-by-step guide.
If you want to dig into the idea, read The folder is the agent — the thinking behind why markdown is the right format for this.
For the technical background, our documentation covers the full API, and Jon's essay Agent Hill-Climbing explains the “check your own work” pattern in more depth.

Ready to try it?

Write your first runbook →

You don't need to have the perfect runbook on day one. Start with a small task. Write three or four lines. Run it. See what comes back. Adjust.

Book a 20-minute walkthrough →

Bring a task from your own work. We'll turn it into a runbook together.