How to Write Instructions an AI Agent Can Actually Follow
Quick answer: Write a short work order, not a motivational paragraph. Name the outcome, allowed sources, required artifact, decision rules, what to do when information is unclear, and the condition that means the task is done.
Clear instructions do not guarantee a correct result. They make the result easier to test and the failure easier to diagnose.
The six fields
1. Outcome
Describe the completed work: “Create a weekly support issue brief,” not “analyze customer problems.”
2. Sources
Name what the agent may use: selected CSV exports, a folder of notes, or two policy files. State which nearby material is outside scope.
3. Artifact
Specify filename, format, sections, or columns. A visible schema reduces interpretation.
4. Rules
State the decisions the agent must make consistently. Examples: reconcile counts before writing commentary; never invent missing fields; include a source row for each claim.
5. Uncertainty
Tell the agent when to mark Unclear, ask a question, or stop. Otherwise it may fill gaps with plausible text.
6. Done
Define completion in observable terms: every selected file checked, required columns present, output saved, and unresolved cases listed.
Before and after
Vague:
Review these support files and tell me what matters.
Testable:
Outcome:
Create weekly-issue-brief.md.
Sources:
Use only the three selected support CSV exports.
Artifact:
For each issue include category, count, affected product area,
up to three source row IDs, up to two representative quotes,
and owner question.
Rules:
- Reconcile category counts with total included rows.
- Do not infer customer identity or intent.
- Put rows that do not fit a category under Unclear.
- When an issue has fewer than three rows or two quotes, include all
available evidence, state the sample size, and do not merge or invent.
Uncertainty:
Ask if exports use conflicting product names. Do not merge them silently.
Done:
Every non-empty row is counted once, totals reconcile, and the brief is saved.
The second version is not better because it is longer. It is better because the output and checks are visible.
Add an example only when it resolves ambiguity
Examples help when a label or format can be interpreted several ways. Show one representative input and the desired output row.
Do not add ten examples when one makes the rule clear. Too many examples can obscure the actual contract and encourage copying surface details.
Separate instructions from capabilities
If the agent cannot open a file, the problem may be access or format—not wording. If a calculation tool fails, adding “be accurate” will not repair it. If a model consistently misses the required reasoning, the model may not fit the task.
| Symptom | Check first | Instruction repair, if needed |
|---|---|---|
| Wrong output shape | Required output fields | Add exact fields or one example |
| Missing files | Whether files opened and were read | Clarify source list after access works |
| Invented values | Existing missing-data rule | Add a verifiable exception check |
| Conflicting sources merged | Uncertainty field | Require pause or separate treatment |
| Correct extraction, bad totals | Calculation method/tool | Require reconciliation evidence |
| Stops too often | Uncertainty rule | Narrow the conditions that require a question |
| Uses an unwanted action | Enabled tools and actual permissions | Remove capability; do not rely on prose alone |
Use verbs that name work
Prefer:
- extract;
- compare;
- reconcile;
- classify using these labels;
- draft using this structure;
- cite;
- flag;
- create a new file.
Be careful with vague verbs such as “handle,” “optimize,” “manage,” and “make better” unless you define the observable result.
State negative rules with a positive destination
Instead of only “Do not invent missing dates,” add “Put missing dates under Unclear.” The agent then has somewhere valid to place the case.
Instead of only “Do not edit originals,” add “Create a new artifact in the output folder.”
Keep permissions outside the prose too
“Use only this folder” is a task instruction. Whether access is technically restricted depends on the app, operating-system permission, model connections, and enabled tools. Use the smallest actual access that can complete the work.
A cloud model receives the context sent to it. Clear instructions do not change that data path.
Improve one field at a time
After a weak run:
- identify the first visible failure;
- decide whether it came from input, access, tool, model, or one instruction field;
- change one variable;
- rerun the same representative task;
- compare the artifact and run record.
Anthropic recommends simple, composable agent designs and careful tool interfaces. The same principle applies to instructions: use the smallest contract that makes the work testable.
Where Agenaxy fits
Agenaxy is a local-first AI agent workbench where a work order can run against selected files and return editable Artifacts with visible Activity.
Standard can use a selected local or cloud model. In Vault, each model Connection must be explicitly authorized; an authorized remote model still receives sent context. Outbound-data tools remain unavailable, and agent-run scripts are blocked from network access.
Pair the work order with a controlled delegation contract and a two-run workflow test.
Try a six-field work order
Describe the six fields for one non-confidential task in Try Agenaxy. Do not submit files, credentials, customer records, or production data through the form.
FAQ
Do AI agent instructions need a special syntax?
No. Headings and bullet points help readability, but a clear operational contract matters more than a magic format.
Should I tell the agent to think step by step?
Focus first on the required artifact, evidence, rules, and checks. You need an inspectable result and activity record, not hidden reasoning text.
How long should an AI agent instruction be?
Long enough to define the six fields, but no longer than the task requires. A narrow task may fit on one screen.
Why does the same instruction produce different results?
Models can vary, and inputs, tools, settings, or context may differ. Record those variables and compare more than one run.
Sources and Fact-Checking Notes
- Microsoft — Get started writing prompts in Microsoft 365 Copilot documents goal, context, expectations, and source as prompt elements.
- Anthropic — Building effective agents recommends simple patterns, careful tool design, and evaluation.
- Agenaxy product statements are checked against current Standard and Vault canon.