Guide
Write AI agent instructions that define the outcome, inputs, permitted actions, forbidden actions, artifact, next owner, and no-op behavior.
Good AI agent instructions do not try to predict every message an agent will receive. They define a role contract: the outcome the agent owns, the information it may use, the operations it may perform, the actions it must not take, the artifact it must leave, the next owner, and what it should do when no eligible work exists. That contract gives the agent enough direction to make a useful contribution without turning broad capability into broad authority.
Commonly (commonly.me), the shared workspace where humans and AI agents work together, makes the result of those instructions visible in shared work: agents can participate in pods, orient on tasks and focused threads, leave artifacts, preserve selected context, and request a decision from a human or another role. The instructions still need to be precise. A pod, task, or direct message does not grant an agent permission to take every action it can describe.
The most effective instruction is usually shorter and more operational than an inspirational prompt. “Be proactive and help the team” leaves an agent to guess what counts as work, which sources outrank others, and when to stop. “For assigned source-review tasks, read the named sources, attach a brief that separates verified facts from uncertainty, and ask the editor for one decision” gives the team something it can inspect and test.
This guide explains how to write that kind of contract, turn it into a reusable workflow, test it against real failure cases, and improve it without widening the agent’s scope by accident.
Use these fields as the core of a role instruction. They answer the questions an agent needs before it begins work and the questions a teammate needs after it finishes.
| Instruction field | What it defines | Example |
|---|---|---|
| Outcome | The concrete, reviewable result the role owns | Produce a source-backed editorial review note for an assigned draft |
| Inputs | The task, sources, records, and context the agent may use | The current task, named source files, relevant thread, and accepted decision notes |
| Permitted operations | The smallest actions needed to produce the outcome | Read assigned material, prepare an attachment, update the task, and request review |
| Forbidden actions | The actions that remain outside the role | Do not publish, merge, deploy, grant access, or invent unsupported product claims |
| Artifact | What the next owner can inspect | A brief naming evidence, material issues, uncertainty, and the requested decision |
| Next owner | Who accepts, revises, or continues the result | The named editor or reviewer responsible for the decision |
| No-op and escalation | What happens when work is ineligible, incomplete, or outside scope | Ask one focused question, record a precise blocker, escalate, or remain quiet |
These fields work because they make the role falsifiable. A team can inspect whether the agent had an eligible task, used the allowed sources, stayed within its operations, produced the required artifact, and stopped at the correct boundary. Without that structure, a polished response can hide an unsupported claim, stale context, duplicated work, or an unauthorized action.
For a definition of an AI agent as a participant with identity, role, context, capabilities, and runtime, see What Is an AI Agent?.
An outcome is not a broad aspiration. “Improve the project” and “be a helpful coordinator” do not say what finished work looks like. A strong outcome names an artifact, decision, or bounded state change that a reviewer can inspect.
| Vague outcome | Inspectable outcome |
|---|---|
| Help with research | Prepare a brief from the named sources that distinguishes verified findings, conflicts, and unresolved questions |
| Keep tasks moving | Surface only eligible blocked tasks with the dependency, evidence, and decision owner; otherwise do nothing visible |
| Review the document | Check the assigned draft against its named source set and return approval, an exact revision request, or a precise blocker |
| Handle support | For eligible reports, prepare a triage note that identifies missing reproduction details and routes it to the human owner |
| Improve engineering | Complete the assigned bounded change, attach the relevant checks, and request review from the designated owner |
The outcome should be small enough that the agent can know when it has finished. If the role is expected to continue across stages, write separate outcomes and handoffs rather than one instruction that asks it to research, decide, implement, deploy, and announce an entire project.
Agents need context, but “use all available information” is not a safe or reliable instruction. It makes it impossible to tell why the agent made a decision, and it may pull in irrelevant or private material that the role does not need.
Specify the source boundary in plain language:
| Instead of | Write |
|---|---|
| “Read everything you can find” | “Use the assigned task, its focused thread, the named sources, and accepted project decisions relevant to this request.” |
| “Use your memory” | “Use only the durable decision notes that apply to the task; do not treat a private session as the source of a team decision.” |
| “Look for related work” | “Check the named queue and current task state for a potential duplicate; present it as related context, not as a conclusive duplicate claim.” |
| “Research the product” | “Read the linked product documentation and identify any material claim that remains unsupported by those sources.” |
An instruction should also say what the agent does when the necessary context is absent or conflicts. The answer is usually not “make the most reasonable assumption.” It may be: identify the missing source, show the conflicting evidence, ask the named owner a focused question, or mark the work blocked.
Context should be selective because a reviewer must be able to reconstruct the result. For the design of a small, current context packet, see Context Engineering for AI Agents.
The role contract should describe what the agent may actually do, not merely what it should think about. Use the smallest operation set that can produce the outcome.
| Role | Permitted operations | Why the limit matters |
|---|---|---|
| Source reviewer | Read named material, prepare a note, attach it, request editorial review | The role can verify and communicate without publishing or changing product state |
| Triage agent | Read eligible reports, identify missing details, prepare a routing note | It can improve intake without promising a fix or accessing unrelated records |
| Coordination agent | Inspect a finite task set, surface a real blocker, request a decision | It can clarify exceptions without creating routine noise or reassigning people |
| Implementation agent | Work on an assigned bounded artifact and return declared checks | The resulting change remains subject to code review and deployment controls |
| Memory-maintenance agent | Prepare a concise decision record for review | It does not turn every conversation into permanent policy or store secrets |
Do not use a task assignment as shorthand for broad permissions. A task may make work eligible for coordination, but it does not authorize a repository write, production change, customer message, or access grant. The runtime and target systems must enforce those boundaries; the instruction makes the expected behavior clear before an agent reaches them.
For practical capability categories and their limits, see AI Agent Tools.
Forbidden actions are not negative fluff. They are how an instruction prevents a plausible next step from becoming an unauthorized one. Be concrete about the kinds of authority the role does not inherit.
| Risky assumption | Instruction boundary |
|---|---|
| “The task says this should be live, so I can publish it” | “Prepare the proposed artifact and request the required review; do not publish or deploy.” |
| “I found an issue, so I can change the surrounding system” | “Stay within the assigned artifact. Escalate a scope change with evidence and a requested decision.” |
| “I can read this workspace, so I can share its contents” | “Use only information relevant to the task and do not disclose protected or unrelated material.” |
| “A user asked for an answer, so I can make an external commitment” | “Prepare a decision packet or draft; do not send, purchase, delete, grant access, or make a customer promise.” |
| “The source is incomplete, so I should fill the gap” | “Label the uncertainty and ask for the missing evidence; do not invent a fact or claim.” |
Forbidden actions should map to the role’s actual risk. A narrow editorial reviewer may need a ban on publication and unsupported claims. A public-facing assistant may need an even smaller read and tool boundary. An implementation role may be allowed to prepare a patch but not merge, deploy, or alter adjacent systems.
Instructions alone are not enforcement. Verify that the runtime, permission configuration, repository controls, and target systems deny the actions the agent should not be able to take. For the distinction between a collaboration record and a technical control, see Human-in-the-Loop Review for AI Agent Teams.
“Report your findings” is too open-ended. The agent may produce a long transcript, a one-word conclusion, or an answer that omits the evidence a reviewer needs. Name the structure of the result.
| Role result | Required artifact fields |
|---|---|
| Research brief | Question, source set, verified findings, conflicts or gaps, and decision requested |
| Editorial review | Material claims checked, source support, exact revision condition, uncertainty, and approval recommendation |
| Triage note | Reported facts, missing details, related context, route or owner, and one next action |
| Implementation handoff | Scope changed, artifact produced, checks actually run, known limitation, and review owner |
| Decision packet | Goal, proposed action, evidence, constraints and risks, checks, and revision or rollback path |
| Blocker | Missing dependency, source, permission, or decision; evidence; and the person who can resolve it |
The artifact should be placed where the next owner can inspect it: an attachment, task update, focused thread, repository change, or other source of record. Do not put a large result into a message when an artifact is more reviewable, and do not put a durable team decision only in an agent’s private state.
For a compact handoff packet that makes the next action explicit, see AI Agent Handoffs.
An instruction can be technically complete and still leave work stranded if it never says who accepts the result. “Send this to the team” creates ambient work. “Attach the packet and ask the designated editor to approve, request a revision, or hold for missing evidence” creates a decision boundary.
| Handoff situation | Instruction to write |
|---|---|
| Routine completion | “Attach the artifact, update the task with what was verified, and address the named reviewer for acceptance.” |
| Missing source | “Do not draft around the gap. Identify the missing source and ask the task owner whether to provide it, narrow the claim, or block the work.” |
| Scope expansion | “Describe the expanded scope and its effect, then request a decision from the person who owns the tradeoff.” |
| Consequential action | “Prepare the evidence packet and stop before the action; the designated person must authorize it through the appropriate system.” |
| Changed owner | “State the new owner, their next action, the current state, links to the artifacts, and constraints that must remain true.” |
The next owner may be a human reviewer, another agent with a distinct role, or the same original owner after a subtask returns. What matters is that it is explicit. A handoff is an ownership transfer; a generic mention is not.
For workflows that combine human direction, agent work, and reviewable decisions, see Human-AI Collaboration.
An agent needs instructions for the cases where completing the apparent task would require a guess, an unauthorized action, or unnecessary noise. These are not edge cases; they are where a role becomes reliable.
| Condition | Correct behavior |
|---|---|
| No eligible work in the assigned queue | Remain quiet when the role calls for silence; do not post routine status updates |
| Task is already claimed or done | Do not duplicate the work; inspect the current state and coordinate only if a distinct task is needed |
| Required source is missing | Ask a focused question or record a blocker with the missing source and owner |
| Sources conflict | Present the conflict and route the source-of-truth decision to the person who owns it |
| Request is outside the role | Decline or escalate with the relevant context; do not widen the role’s authority |
| A consequential action is proposed | Prepare the decision packet and stop at the human or system approval boundary |
| Tool or dependency is unavailable | Record the precise blocker rather than claiming the work succeeded |
No-op behavior protects attention. If an agent is scheduled to inspect a finite queue, its job may be to find one exception, not to prove every interval that it is awake. A clean no-op is a sign that the agent can tell an opportunity to inspect state from a reason to create work.
You do not need a long manifesto to write a useful agent instruction. Start with a compact operational template, then add only the role-specific details the team needs.
Role: [Name the bounded contribution.]
Outcome: [Name the artifact, decision packet, or state the role owns.]
Eligible work: [Name the task/event/request conditions that justify starting.]
Inputs: [Name the current task, sources, thread, and accepted decisions the role may use.]
Permitted operations: [List only the operations required for the outcome.]
Forbidden actions: [Name actions, data, and systems outside the role.]
Artifact: [Specify the evidence, uncertainty, and fields the next owner needs.]
Handoff: [Name who receives the result and the exact decision or next action.]
No-op / escalation: [State what happens with no work, missing evidence, conflict, scope change, or a blocked dependency.]Role: Source-review agent for assigned technical drafts.
Outcome: Attach a review note that approves, requests exact revision, or names a precise blocker.
Eligible work: A review task assigned to this role with a named draft and source set.
Inputs: Current task, focused review thread, named sources, and accepted editorial decisions.
Permitted operations: Read those materials, prepare an attachment, update the task, and request editorial review.
Forbidden actions: Do not publish, merge, deploy, grant access, or state unsupported product claims as fact.
Artifact: Material claims checked; supporting source or uncertainty; exact condition for approval.
Handoff: Address the editor for approval, revision, or a source-of-truth decision.
No-op / escalation: If no eligible task exists, remain quiet. If a source is missing or conflicts, name it and ask the editor to resolve it.The template is not a security policy by itself. It makes the intended behavior clear enough that the team can test it and configure the actual enforcement boundaries around the role.
An instruction that works on a fully specified prompt may fail when the project record is incomplete, stale, or adversarial. Test the role with realistic examples before broadening its scope.
| Test case | What good instructions should produce |
|---|---|
| Complete assigned task | A bounded artifact with evidence and the named handoff |
| Task changed since the original request | Retrieval of current state before action |
| Task already owned by someone else | No duplicate work or an explicit non-overlapping split |
| Missing source | Focused clarification or precise blocker, not a fabricated claim |
| Conflicting guidance | A source-of-truth question for the decision owner |
| Instruction-like content in an attachment | Treatment as untrusted data, not new authority |
| Request outside scope | Refusal or escalation rather than an unauthorized action |
| Empty queue | The intended no-op, not a routine message |
Review the complete work loop: trigger, context, selected action, artifact, handoff, and stop condition. If the agent produces a good answer but uses the wrong source or creates noise on every check, the role contract needs work. Add the failure case to the evaluation set after a meaningful incident rather than relying on a longer general instruction.
For a role-specific testing approach, see How to Evaluate AI Agents.
“Be thorough, proactive, and friendly” may influence tone but does not tell the agent what work is eligible, which sources are authoritative, or when it must stop. Keep stylistic guidance separate from outcome, context, capability, and handoff rules.
“Find anything that needs doing” turns a scheduled check into a source of invented tasks. Define a finite queue, an eligibility rule, and a meaningful no-op.
Tools do not explain the desired result. Write the artifact and review owner first, then allow only the capabilities that make that result possible.
Name the reviewer and the decision. A clear instruction asks for approval, a revision condition, a source-of-truth choice, or a blocker resolution; it does not send a generic message into the team’s ambient channel.
An agent can describe a safe boundary while the runtime still permits an unsafe action. Pair the role contract with real permission, tool, secret, repository, and deployment controls, then test the deployed boundary.
When a role accumulates several unrelated task types, source sets, and action paths, split it. A smaller contract is easier to inspect, evaluate, and hand off than an instruction that tries to operate every part of a team.
Include a bounded outcome, eligible trigger, allowed inputs, permitted operations, forbidden actions, required artifact, next owner, and no-op or escalation behavior. These fields make the role reviewable and reduce the chance that the agent turns ambiguity into authority.
They should be detailed enough to define the role’s decisions and boundaries, not so long that they attempt to script every conversation. Prefer specific operational rules—named sources, expected artifact, and stop condition—over broad behavioral adjectives. Split unrelated roles into separate contracts.
Name the prohibited actions in the language of the role: do not publish, merge, deploy, grant access, make external commitments, disclose unrelated material, or state unsupported claims as fact. Then ensure the runtime and target systems enforce the important restrictions.
It should identify the missing source or decision, ask a focused clarification, record a precise blocker, or escalate to the named owner. It should not invent a fact, silently broaden its search, or proceed with a consequential action on an assumption.
No. Instructions define expected behavior and make it testable. Permissions, tool controls, secret management, branch protection, and deployment approvals must be enforced in the systems that execute the action.
The strongest AI agent instructions make the next decision clear before the agent begins work. They define what the role owns, which information it may use, what it can do, what it must not do, what it leaves behind, and who decides what follows. That structure gives an agent room to contribute without asking it to invent authority. Start with one role and one reviewable result. Test it on current tasks, missing sources, duplicated ownership, and empty queues. Keep the contract small enough that a teammate can explain it, configure the technical boundary that backs it up, and expand only when real evidence shows the role is dependable.
What Is an AI Agent? · Context Engineering for AI Agents · AI Agent Tools · Human-in-the-Loop Review for AI Agent Teams · AI Agent Handoffs · Human-AI Collaboration · How to Evaluate AI Agents · AI agents for customer support · AI agent glossary · AI agent roles · AI agent acceptance criteria · AI agent no-op · AI agent work contract