AI agents

How to write instructions for an AI agent

The short answer

Write them like a job description for a careful new hire: the job, its cases, the steps, the output, and what to do when unsure. Give the reason behind each rule, and retest on real cases after every change.

4 min read

A template that works

Seven short parts, in this order. Most AI agents need 100 to 250 words; if yours runs past a page, it is probably two jobs.

PartWhat to writeExample (support replies)
JobOne sentenceReply to questions sent to support@
CasesWhat it handles, what it leavesOrders and returns; leave complaints to me
StepsNumbered, one action eachRead, look up the order, draft
FactsWhere the answers liveReturns policy and delivery times in memory
OutputThe exact shapeUnder 120 words, first-name greeting
When unsureThe fallbackDon't draft; say what is missing
WhyThe reason behind each ruleA wrong promise costs more than delay

Before and after

  • Before: "Be helpful and answer customer emails." After: "Reply to order, delivery and returns questions sent to support@. Leave complaints and refunds for me."
  • Before: "NEVER make anything up." After: "Answer only from the returns policy in memory. If the answer is not there, tell me what is missing."
  • Before: "Keep it short." After: "Under 120 words. First name in the greeting. No bullet points."
  • Before: "Handle edge cases." After: "If there is no order number, ask for it in one line."

How to write instructions for an AI agent

  1. Step 1: Start from what you already tell people

    Your returns policy, the email you send new staff, your canned replies. Paste them in as facts; do not rewrite them from memory.

  2. Step 2: Write the job and the cases first

    One sentence for the job, then what it handles and what it leaves. Most bad AI agents fail here, not in the details.

    Do this step in 50agents

    Set up an AI agent that reads new support emails, drafts a reply from what you know about my business, and asks me before sending

    Build it

    Captain writes the first version of the instructions from your sentence and shows them on the plan. Later you change them by telling the AI agent in its chat. See the ready-made version.

  3. Step 3: Number the steps

    One action per step, each tied to a clear output. If a step says "and", it is probably two.

    Tip. Models take requests literally. "Suggest changes" may get you suggestions and no changes. Say whether it should act or only propose.

  4. Step 4: Describe the output exactly

    Length, tone, greeting, sign-off, format. Paste one good example if you have it.

  5. Step 5: Give the reason, drop the capitals

    "A voice engine cannot read ellipses" works better than "never use ellipses". Newer models follow closely, so "CRITICAL: you MUST" makes them overdo it.

    Watch out. A bare rule with no reason gets applied too literally, in cases where it was never meant to apply.

  6. Step 6: Write the unsure line

    What it does when facts are missing, the case is unclear, or a search finds nothing. "Skip it and tell me why" is a good default.

  7. Step 7: Test on 10 real cases

    Include the awkward ones. Change one thing at a time and rerun the same cases, so you know which change helped.

What can go wrong

  • It does more than you meant

    The instructions said what to do but not what to leave. Add the cases it should not touch.

  • The important rule gets lost

    The instructions grew to two pages. Cut what the AI agent never uses, and move reference facts into memory.

  • "Nothing found" when there was something

    It searched the wrong way, such as for the word "unread" instead of the unread label. Tell it what to search, and to say what it searched when it finds nothing.

  • Changes break what worked

    You fixed one case and broke another. Keep your 10 test cases and run all of them after each change.

Questions people ask

How long should AI agent instructions be?

As short as covers the job, the cases, the steps, the output and the unsure case. For most small-business AI agents that is 100 to 250 words, plus reference facts kept separately.

Should I include examples?

One good example of the output helps a lot, especially for tone. Examples of inputs belong in your test set, not in the instructions.

What goes in instructions and what goes in memory?

Instructions say how to do the job. Memory holds facts that change: prices, policies, opening hours. Keeping them apart means you update a price without touching the job.

Should I write rules in capitals?

No. Newer models follow closely, so "CRITICAL: you MUST" makes them overdo it. Give the reason behind the rule instead, and it will apply it sensibly.

How do I know a change helped?

Change one thing at a time and rerun the same real cases. If you change three things at once, you will not know which one fixed or broke it.

What should the instructions say about unclear cases?

What to do when facts are missing, the case is unclear, or a search finds nothing. "Skip it and tell me why" is a good default.

Read next

Or let Captain build it

One sentence to Captain. Free to start.

Build it with Captain
How to write instructions for an AI agentBuild it