Writing instructions that work

Most disappointing results are not the model being stupid. They are an instruction that was clear in your head and ambiguous on the page.

This page is about the craft of asking. It is the single highest-return habit in the whole product, because it costs nothing and you do it twenty times a day.

The test before you press send

Read your instruction back and ask: could a competent stranger do this without asking me a question?

If the answer is no, the agent will guess. Sometimes it guesses well. The times it guesses badly are the times you blame the tool.

Four things worth saying every time

Say what the finished thing looks like

This is the big one. Describe the output, not the activity.

❌ Summarise these notes.

✅ Summarise these notes into five bullet points, one line each, that I can paste into an email to a client who was not at the meeting.

The second version decides four things the first left open: how long, what shape, who is reading, and how much context they have.

Say where the material is

Agents can read your workspace. Pointing at the real file beats describing it.

❌ Based on our pricing, draft a reply.

✅ Read pricing/2026-rates.md in the workspace and draft a reply to the quote request in inbox/acme-enquiry.txt.

Say what to leave out

Half of editing an agent's output is deleting things you never wanted.

✅ No preamble, no summary at the end, no offer to help further. Just the list.

Say what done looks like

If there is a standard it has to meet, name it.

✅ Every figure must come from the spreadsheet. If a number is not in there, write TBC rather than estimating.

That last sentence is worth copying. Telling an agent what to do when it does not know is how you stop it inventing things.

Giving the job to the right agent

The VIA control on the dispatch bar lets you send a task to a named agent instead of letting the system choose.

Use a named agent when the job belongs to that one — the agent you briefed for client writing should get the client writing. It produces better work, because its standing instructions apply, and it builds a track record that means something. See Your first agent.

Leave it on AUTO for one-off work that no particular agent owns.

When the instruction gets long

If you are writing four paragraphs of instruction, stop and ask which of these you actually have:

A job description. If you will say the same thing every time, it belongs in the agent's system prompt, not in each task. Edit the agent once.

A repeatable process. If it is a sequence of steps in a fixed order, it is a workflow, not a task.

A fact the agent should already know. Put it in memory with /remember, and every future task has it. See Memory.

Genuinely a one-off. Then a long instruction is fine. Length is not the problem; repetition is.

Correcting rather than restarting

When the result is close but wrong, say what to change. Re-describing the whole job from scratch throws away the parts that were right and often reproduces the same misunderstanding.

✅ Good, but the tone is too formal for this client and the third point repeats the second. Same length, warmer, and merge three into two.

The same applies mid-run for anything driving your screen: STEER it rather than stopping and starting again. See Letting an agent use your computer.

The prompt wand

The ✦ button in the dispatch bar rewrites your instruction into a clearer one before sending.

It is genuinely useful when you know what you want but wrote it loosely. It is not a substitute for knowing what you want — it cannot add the file path you did not mention or the standard you did not state.

It costs a small call to your provider each time, which is why it is optional. Switch it on in System Config → Sound.

Two habits that compound

Keep a note of instructions that worked. When a phrasing produces exactly the right thing, save it with /remember or paste it into a note. You will want it again, and re-deriving it takes longer than you think.

When something comes back wrong three times, stop rewriting the instruction. Three failures on the same kind of work is a sign the agent needs teaching, not rephrasing — see Teaching an agent — or that the job needs splitting into smaller ones.