How to Write AI Agent Instructions That Actually Work

An AI agent is only as good as the instructions behind it. When an agent ignores half of what you asked, invents steps you never mentioned, or gives a different answer every time, the problem is rarely the model. It is almost always the instructions. This guide walks through a repeatable way to write agent instructions that hold up: set the goal, supply the context the agent lacks, add guardrails, show an example, and tune the result until it behaves.

The approach works for any agent you configure, whether that is a custom assistant, a coding agent, a research helper, or an AI video agent you direct in plain language. The principles stay the same; only the task changes. It also covers the part most guides skip: deciding which choices you keep and which you hand to the agent, a boundary that shapes the instructions as much as any rule you write down.

What Are AI Agent Instructions?

AI agent instructions are the standing directions you give an agent before it starts working. They tell it what job it does, what to pay attention to, what it must never do, and what a good result looks like. Some platforms call this the system prompt, the agent configuration, or the persona. The label varies, but the function is the same: it is the brief the agent reads on every task, so it does not have to guess.

Instructions are different from the request you type in the moment. A request is "summarize this report." Instructions are the persistent layer underneath that says "you are a research assistant, you write in plain English, and you flag anything you are unsure about." Because the agent re-reads them on every turn, a weak instruction gets amplified across a whole session, which is why it helps to understand how an AI agent loop works before you write them.

What You Need Before You Write Instructions

Good instructions start before you open the config box. Get three things clear first.

• A specific job. Not "help me with marketing" but "draft short social captions from a product description." A vague job produces a vague agent.
• The context the agent will not have on its own. Your audience, your tone, your formats, the constraints your team knows by heart. The agent knows none of it until you say so.
• A picture of a good result. If you cannot describe what "good" looks like, the agent cannot hit it. Write down one output you would happily ship.

With those three in hand, the steps below turn them into a structure the agent can follow.

How to Write AI Agent Instructions Step by Step

The order matters. Each step builds on the one before it, moving from the broad goal down to the fine detail.

Step 1: State the Goal in One Sentence

Open with a single sentence that names the agent's job and its scope: "You are a support assistant that answers billing questions for our SaaS product." That one line sets the role, the domain, and the boundary at once. The agent now knows it handles billing, not feature requests. Keep the goal narrow. If you find yourself writing "and also" three times, you probably need two agents, not one.

Step 2: Give the Context the Agent Lacks

Next, hand the agent the background it cannot infer. This is where most instructions run too thin. Spell out your audience, your product, your tone, and any facts that should shape every answer, and write them as facts, not hopes. "Our users are non-technical small business owners" is something the agent can act on; "be helpful" is not. If the agent will use tools or data sources, name them and say when to reach for each, and know when to use MCP vs agent skills rather than cramming everything into the instructions.

Step 3: Set Guardrails and Constraints

Now tell the agent what not to do. Guardrails keep it inside the lines: never invent a price, always cite the source, keep answers under 150 words, refuse anything outside billing. Phrase each one as a clear boundary the agent can check itself against, and be specific about failure modes you have already seen. If it tends to over-explain, write "answer in two sentences unless asked for more." If it tends to guess, write "if you are not sure, say so and ask a clarifying question." Guardrails are where you encode the lessons from every bad output so far.

Step 4: Show an Example of Good Output

Instructions describe the target; an example shows it. Models are strong pattern matchers, a point OpenAI's prompt engineering guide makes repeatedly, so a single concrete example teaches more than a paragraph of description. A support agent once kept answering billing questions in three long paragraphs. The instruction said "be concise," and it ignored the line every time. Replacing that word with a worked example fixed it in one edit:

Input: "Why was I charged twice?" Good answer: "You were charged twice because your plan renewed while a one-off top-up was still processing. I have refunded the duplicate charge; it will land in three to five business days."

The agent had no idea what "concise" meant to us until it saw one. If format matters, show the format; if tone matters, let the tone live in the example. One example is usually enough; two or three help when the task has real variety.

Step 5: Decide What You Hand Off

Every agent makes some choices for you, and naming which ones, on purpose, is as much a part of the instructions as the rules you write. This is the step most guides skip, and it is where agents surprise people. For a coding agent, "use our standard stack" is vague delegation; "use React and Tailwind, and ask before adding any new dependency" says exactly which calls it can make alone and which it must escalate. For a video agent, you might hand off the model choice but keep the length and caption style. Write down, in one line, the decisions the agent owns and the ones it must bring back to you. Vague delegation is how you get output that is technically on-brief and completely wrong.

Step 6: Test and Iterate

Instructions are a first draft, never a final one. Run the agent on five or six real tasks, including the awkward edge cases, and watch where it drifts. Each miss points at a missing instruction: wrong tone means your tone line was too soft, off-topic means your scope was too wide. Add or tighten one instruction per problem, then test again. Change one thing at a time, and over a few rounds the instructions settle into something reliable.

Common Mistakes That Make Agents Drift

A few patterns cause most agent failures. Watch for these.

• Being polite instead of precise. "Please try to be accurate" is not an instruction. "Cite the source document for every factual claim" is.
• Piling on scope. An agent told to do six unrelated jobs does all of them poorly. Split the work or narrow the role.
• Skipping the guardrails. Without explicit limits, the agent fills the gaps with its own guesses, and its guesses are not yours.
• No example. Describing "professional but friendly" ten different ways still leaves it ambiguous. One example settles it instantly.
• Writing once and walking away. Instructions never tested against real tasks stay broken in ways you will not notice until a user does.

Pro Tips for Sharper Instructions

Once the basics are in place, these habits raise the quality further.

• Front-load the most important rules. Language models show a "lost in the middle" tendency, documented by researchers like Liu et al. (2023): information placed in the middle of a long context gets used less reliably than the same information at the start or end. Instructions are context too, so put the non-negotiables near the top and repeat any truly critical one at the very bottom.
• Use plain, direct language. You are writing for a reader that takes you literally. Short declarative sentences beat clever phrasing.
• Name the format explicitly. If you want a bulleted list, a table, or a strict word count, say so. Do not assume the agent will infer your preferred shape.
• Keep a change log. When you tweak an instruction to fix a behavior, note why, so you do not revert the fix weeks later after forgetting the reason.

See It in Action: Directing an AI Video Agent

The same principles are easier to feel on an agent whose output is not text. A request like "make a 20-second product teaser from this landing page, upbeat, with captions" is a full instruction in miniature: goal, context, and constraints in one line. A rendered clip also exposes a vague brief faster than paragraphs do, because you see the mistake at a glance.

Pexo is one AI video agent that works this way, which makes it a handy place to test your instruction-writing: you describe the video in plain language, and vague briefs produce vague results exactly like they do everywhere else. It also makes Step 5 concrete. Some choices, like which underlying model runs a given shot, are handed to the agent, while the ones you care about, length and captions and mood, stay in your sentence. If you build agentic workflows, it can run inside them as a text-to-video skill for Claude Code.

Conclusion

Good AI agent instructions are not a trick or a secret prompt formula. They are a clear brief: a specific goal, the context the agent lacks, honest guardrails, one solid example, and a few rounds of testing. If you remember one thing, make it this: the fastest fix for an agent that will not listen is almost always replacing an adjective with an example. "Be concise" is a wish; a two-line sample answer is an instruction. The rest is knowing which decisions you keep and which you hand off. The way to internalize it is to try it on a real agent and watch instructions turn into output. Start a video project with Pexo and see how far a well-framed request goes when the agent does the rest.