All pages

Agentic pipelines · Lesson 1.1 · 10 min · Free

Prompts and runbooks

Save a good prompt with variables and chain steps into a runbook.

Listen

After this lesson you know when a prompt is worth saving, how to turn the part that changes into a variable, and how to chain a good session into a runbook that loops until the work is done and then stops.

Time: 10 minutes · Works on: macOS app. The cloud workspace stores prompts and runbooks too, through save_prompt and the runbooks_* tools.

The third time, save it

Every agentic workflow has a handful of requests you make over and over: review the diff, explain this failure, write the commit message, run the tests and fix what breaks. The first time you type one, you are working out what to ask. The second time, you are remembering what worked. By the third time you are retyping a slightly worse version of the first, because you have forgotten the sentence that made it good.

That sentence is the valuable part. "Review the diff" gets a generic review. "Review the uncommitted diff. List anything that changes behaviour without a test, any error that is swallowed, and any name that no longer matches what the code does. Don't fix anything yet" gets the review you wanted. Once you have found the wording that works, save it, so every later run starts from your best version instead of your most hurried one.

A saved prompt is the smallest unit of a pipeline. Everything later in this course, schedules, plugins and Claude Code over MCP, ends up firing prompts you wrote once and trust.

Make the changing part a variable

A prompt you save should be the part that stays the same. The part that changes from run to run belongs in a variable, so you never edit the saved text by hand and never drift from the version that worked.

Compare two ways to save a release-notes request:

  • Saved as "Write release notes for 2.4 from the commits since 2.3." You edit the numbers every time, and sooner or later you forget one.
  • Saved as "Write release notes for {{version}} from the commits since {{previous}}. Group them as Added, Changed and Fixed, and leave out internal refactors." You fill in two fields and the instructions never change.

TRMNLY also fills some variables for you from the focused pane, such as {{branch}}, {{selection}} and {{cwd}}. Those are how a prompt picks up where you are. "Explain why this failed: {{selection}}" turns a terminal selection into a complete request.

A runbook is a loop with a stopping rule

A prompt is one request. A runbook is a sequence: several prompts in order, and optionally shell commands, waits, nested runbooks, repeats and loops. The point of a runbook isn't to save typing. It's to capture a loop that you know converges, with a condition that ends it.

The most useful runbook most projects have is some form of "make the tests pass":

  1. Run the test command.
  2. Ask the agent to fix the first failure it sees, and only that one.
  3. Repeat until the agent says a marker phrase, such as ALL GREEN, or until a cap, say five rounds.

Each part of that matters. The command step keeps the agent honest: it fixes what actually failed, not what it guesses might fail. "Only the first failure" keeps each round small enough to review. The marker phrase gives the loop a clear way to finish, and the cap gives it a way to give up. A loop without a cap is how an agent spends an hour rewriting a test until it passes by accident.

Write the stop condition into the prompt itself: "When every test passes, say ALL GREEN and nothing else." The runbook's Loop until step watches for that phrase, so the agent's own words end the loop.

What belongs in a prompt and what in a runbook

Use a saved prompt when Use a runbook when
It's one request It's several steps in a fixed order
You read the answer and decide what's next The next step doesn't depend on your judgement
It changes with what's on screen It has to run the same way every time

If you find yourself sending three saved prompts one after another every time, that's a runbook.

Keep the good ones where your team can see them

A prompt that lives only in your app is a prompt your teammates and your other agents never get. Put the ones that encode project knowledge, such as how to review, how to release or how to write a migration, in a folder in the repository. They're reviewed like code, they change with the code, and a new checkout gets them for free.

Do it in TRMNLY

  1. Show the right sidebar with ⌘⇧\ and click Prompts. Click + and save the review prompt above. Give it the Trigger rvw and the Tags review. See Saved prompts for every field.
  2. Right-click the row and choose Send to Agent. The prompt goes to the agent as a new turn. This is how a saved prompt becomes agent work rather than terminal text.
  3. Save the release-notes prompt with {{version}} and {{previous}} in it. Click it. The run sheet opens with a field per variable and a Preview of the finished text. Try Auto-fill, which asks your agent model to suggest values from what's in the terminal.
  4. In the Agent tab, type / in the composer. Your saved prompts appear beside the built-in slash commands, so you can fire one without leaving the agent.
  5. When you write a good prompt in the composer, click the bookmark button in the agent input row. It saves the draft as a prompt before you send it.
  6. Click the gear in the Prompts header and set Watched folder to a folder in your repository, such as prompts/. Every .md, .txt or .prompt file in it becomes a read-only prompt. A first line of #trigger: rvw sets its trigger.
  7. Now build the loop. In the Agent tab, ask: "Save a runbook called Fix tests that runs npm test, then asks you to fix the first failure, and repeats until you say ALL GREEN, at most five times." The agent builds it with its save_runbook tool, using a Shell command step and a Loop until step.
  8. Open More ▾ → Flows. Find Fix tests under Runbooks and press its play button. A new agent session runs it. Every run adds a one-line log entry with its outcome and how long it took.
  9. For a runbook that needs input when it starts, put a placeholder in a prompt step: Prepare release {?version:"Version number"} for {project}. TRMNLY asks for the value in a sheet before the run begins. Runbook placeholders use single braces, unlike prompt variables.
  10. Turn a session you're happy with straight into a runbook with Save current session (⌘⇧S) in Flows. Then use Edit… to cut the prompts that were dead ends.

Two things to know before you lean on runbooks. Edit… edits only the prompts; shell, loop and other steps come from From Template or from the agent's save_runbook. And the agent's run_runbook tool asks for approval, because it sends prompts you wrote on your behalf. That matters in the next lesson, when nobody is there to approve.

Check yourself

  • Typing your trigger and a space in a pane expands to the full prompt.
  • A prompt with two custom variables opens the run sheet with two fields.
  • Your Fix tests runbook stopped on its own, either on ALL GREEN or at its cap.
  • You can say which of your repeated requests should be a runbook and why.

Go further