# How to write AI agent instructions

What to put in them, a template you can copy, and how to check them with a dry run before the agent goes live

Oct 23, 2026 · Guides · 8 min read · https://arclyx.ai/blog/ai-agent-instructions

## Summary

AI agent instructions are the standing orders an agent follows on every run: the job, what done looks like, the steps, what to do when something is missing, and where the result goes. Good ones read like a brief for a capable new colleague who knows nothing about your work. This guide gives you a template and a worked example, shows how Arclyx drafts instructions from one sentence, and how to check them with a dry run on your real tools before the agent runs on its own.

## Key Takeaways

- **Instructions are a brief, not a prompt.** They're read on every run, often with nobody watching, so they have to stand on their own.
- **Name five things.** The job, what done looks like, the steps, the edge cases and where the result goes. OpenAI's guide to building agents lists the same habits: clear actions and captured edge cases [Source 1].
- **Write for a new colleague.** Anthropic's test: if a colleague with little context on the task would be confused by the prompt, Claude will be too [Source 3].
- **Test them before they run alone.** In Arclyx, Try it on a draft is a dry run: it reads with your real tools and shows you anything it would have sent, instead of sending it.
- **Change them in plain words.** Say what should change and Arclyx rewrites the instructions; the agent's tools and name stay as they are.
- **Instructions don't set limits.** What an agent can reach, spend and send is enforced outside the model, by the tools and limits you grant.

## What are AI agent instructions?

AI agent instructions are the written orders an agent follows every time it runs. A chat prompt asks for one answer while you watch; instructions have to carry a job that repeats, on a schedule or a trigger, with no one there to clarify. They say what the job is, how to do it, what to do when things go wrong, and where to deliver the result.

That difference is why instructions deserve more care than a prompt. A vague prompt costs you one follow-up question. Vague instructions cost you every run until someone notices, and an agent that runs at 8 every weekday notices nothing on its own.

## What should AI agent instructions include?

Good AI agent instructions name five things: the job, what done looks like, the steps, the edge cases, and where the result goes. Leave one out and the agent fills the gap with a guess. OpenAI's guide makes the same points: make every step a specific action or output, and plan for the cases where information is missing [Source 1].

| Part | Weak | Strong |
|---|---|---|
| The job | "Help with email" | "Sort today's unread Gmail into what needs me" |
| Done looks like | "A summary" | "Three groups, one line on why for each thread" |
| Steps | (left out) | "Read, leave out newsletters, sort, send" |
| Edge cases | (left out) | "If there's no unread mail, say so in one line" |
| Delivery | (left out) | "One email to me, Needs you today first" |

Keep each part short. Anthropic's advice for prompting Claude carries over to agent instructions: be clear and direct, and be specific about the output you want, rather than hoping the model infers it [Source 3]. Its guide to building agents adds that the simplest design that works is usually the right one [Source 2]. For instructions, that means one job per agent, not five.

## Is there a template for AI agent instructions?

Yes. Copy this, replace the angle brackets, and delete any line that doesn't apply. It works for any agent that runs on its own, in Arclyx or elsewhere, because it follows the five parts above: the job, what done looks like, the steps, the edge cases and the delivery.

```text
Job: <what this agent does, in one sentence>

When it runs: <the schedule or the event that starts it>

Steps:
1. <read or search: which tool, which items, which time window>
2. <leave out: what to ignore>
3. <decide: how to sort, rank or judge each item>
4. <write: the result, in this format>

Done looks like: <the shape of a good result: groups, length, fields>

If something is missing or goes wrong:
- <no items found: what to say>
- <a tool fails or needs a sign-in: what to report>
- <an item doesn't fit any rule: where it goes>

Deliver to: <one person or one channel, and how>
```

## What does a good example look like?

Here is the template filled in for an inbox triage agent: a real job that runs in Arclyx today. Each line is something the agent can act on or check, and the last two lines cover the empty inbox and the delivery. The [inbox triage agent page](https://arclyx.ai/agents/inbox-triage) shows the same job end to end.

![A drafted Inbox triage agent in Arclyx with example data: the one-sentence job, Try it and Improve it on the left, and on the right its Gmail tool, the instructions in full and the weekday 8:00 schedule.](https://arclyx.ai/blog/ai-agent-instructions/img/drafted-agent-instructions.573ae9f4-1600.webp)

Read the instructions on the right against the table above:

- **The job** is in the first line: read the unread Gmail from the last day.
- **Done looks like** three named groups, with one line on why for each thread.
- **The steps** go in order: read, leave out newsletters and receipts, sort, explain, send.
- **The edge case** that matters most for a morning job is an empty inbox, so it gets its own line.
- **The delivery** is one email to one person, with the most urgent group first.

## How do you write instructions without writing a prompt?

In Arclyx you don't start from a blank page. You describe the job in one sentence, Arclyx asks up to three quick questions about what the sentence leaves out, each with an answer already picked, and then it drafts the agent: its instructions, the tools it may use and, if you named one, its schedule.

![The builder's quick questions for the inbox triage sentence, with example answers: leave out newsletters and receipts, and count replies owed, meetings and anything from a customer as needing you.](https://arclyx.ai/blog/ai-agent-instructions/img/builder-questions.645013cf-1120.webp)

The questions are the edge cases and definitions the template asks for, put to you one at a time: what to leave out, and what "needs me" means. A sentence that already names the job, the tools, when it runs and where the result goes gets fewer questions. Our page on [how to create an AI agent](https://arclyx.ai/product) has more on writing that sentence, and our [AI agent tutorial for beginners](https://arclyx.ai/blog/ai-agent-tutorial) takes one agent from its sentence to its first scheduled runs.

Then read the draft. In the drafted agent, the Instructions section opens in full with Show all. Check it against the five parts before you do anything else.

## How do you test AI agent instructions before they run?

Run them once on real data before they run on their own. In Arclyx, Try it on a draft is a dry run: the agent reads with your real tools and does every step, but anything it would post, send or write through a connector is held and listed for you as not sent. You see exactly what the instructions produce, with nothing leaving.

![A dry run of the Inbox triage draft with example data, round by round: search the unread email, read the threads, sort them, then the email it would have sent, listed under "Dry run. Nothing below was sent."](https://arclyx.ai/blog/ai-agent-instructions/img/dry-run-not-sent.80d58d01-1600.webp)

What to look for in the result:

- **Did it read the right things?** Each round shows the tool and what it asked for. A search over the wrong time window shows up here, not in the answer.
- **Is the result the shape you asked for?** Groups, length, order and the one line on why.
- **What happened at the edges?** Give the run a specific input in the optional message box to try a case that could go wrong, such as an inbox with only newsletters.

A dry run uses your real tools, so it counts toward your usage. The [test runs page](https://arclyx.ai/product/test-runs) covers what each round shows and how to test edge cases.

## How do you change instructions once the agent is live?

Say what should change, in plain words. On a draft, type it into Improve it and press Apply; Arclyx changes the draft and says what it changed. On a live agent, open its Config tab and press Improve under the instructions: Arclyx rewrites the instructions and description, and the agent's tools and name stay as they are.

![The Config tab of a live Inbox triage agent with example data: the instructions in full, and Improve open with "What should change?" filled in and the note that its tools and name stay as they are.](https://arclyx.ai/blog/ai-agent-instructions/img/improve-instructions.7b99f9cd-1600.webp)

A good change request names the case, not the wording: "put anything about the launch under Needs you today" rather than an edited paragraph. Then press Run it now on the agent's page and compare the new run with the last one. Every run is recorded round by round, so you can see whether the change did what you meant; the [observability page](https://arclyx.ai/product/observability) shows what each run records. When a run goes wrong, our guide on [how to debug AI agents](https://arclyx.ai/blog/debug-ai-agents) shows how to tell an instructions problem from a tool or data problem.

## What can't instructions control?

Instructions tell an agent what to do; they can't stop it doing something else. A model can misread a job or be steered by text in an email or a web page it reads. So the limits that matter are enforced by Arclyx outside the model, whatever the instructions say.

- **Tools:** an agent can only use the tools you granted it, through your own sign-in.
- **Email:** the email it sends goes only to the person it runs for, and in Gmail and Outlook it writes drafts for you to review and send.
- **Slack:** it posts only to the one channel you chose; the model can't pick another.
- **Spend:** every run is checked against your plan's limits, and paid plans add a ceiling per run and a monthly cap per agent.

Write instructions for the job, and set the boundaries as settings. The [guardrails page](https://arclyx.ai/product/guardrails) covers each one.

## Sources

1. OpenAI — *A practical guide to building agents* (April 2025), section "Configuring instructions". [https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)
2. Anthropic — *Building effective agents* (19 December 2024). [https://www.anthropic.com/research/building-effective-agents](https://www.anthropic.com/research/building-effective-agents)
3. Anthropic — *Prompting best practices*, "Be clear and direct" (Claude Platform docs, checked 23 October 2026). [https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)