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.
| Part | What to write | Example (support replies) |
|---|---|---|
| Job | One sentence | Reply to questions sent to support@ |
| Cases | What it handles, what it leaves | Orders and returns; leave complaints to me |
| Steps | Numbered, one action each | Read, look up the order, draft |
| Facts | Where the answers live | Returns policy and delivery times in memory |
| Output | The exact shape | Under 120 words, first-name greeting |
| When unsure | The fallback | Don't draft; say what is missing |
| Why | The reason behind each rule | A 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
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.
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 itCaptain 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.
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.
Step 4: Describe the output exactly
Length, tone, greeting, sign-off, format. Paste one good example if you have it.
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.
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.
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.