Agent Instructions

Agent Instructions are the one place you say how every agent should behave, and the place every run goes to read it. You write your conventions once, how your team writes plans, the tone for a review, the things to never touch, and every chat turn and every Flow step starts from them, versioned so you always know what was in force and who set it. This page is the how-to: where you edit them, how the layers resolve, how to draft them with the agent, and how versioning and restore work.

For what instructions are and where they sit in the makeup of an agent, read the Agents & Agent Instructions concept. This page is about writing and managing them.

Where you edit them

Instructions live at two grains, and each has its own home in the product.

• Workspace-wide, on the Agent Instructions settings page. This is the text every agent reads by default, and the place most teams do all their editing.
• Per sandbox profile, on the profile's own Agent Instructions tab. When a particular sandbox profile needs different guidance, say one pointed at a different stack, you give it instructions there and they apply to every run on that profile.

The sandbox profile is the finest grain there is. There is no separate per-Flow or per-step instruction set, which keeps the model simple. A run reads one of two bodies of text: the workspace guidance, or the profile's own if the profile has it.

How the layers resolve

Instructions resolve from three layers, and the most specific one that has content wins outright:

• The platform default Disco Parrot ships, the baseline if you change nothing.
• Your workspace override, the text your team writes to encode how you work.
• An optional per-profile override, for a profile that needs its own guidance.

These layers are not stitched together. The most specific layer you have set is used in full, and the ones beneath it stand in only when the layer above is empty. Set nothing and every agent reads the platform default. Add a workspace override and that text becomes the guidance every agent follows, in place of the default, not appended to it. Point a profile at its own instructions and runs on that profile use those instead, while every other run stays on the workspace text. This is what keeps the guidance predictable. There is exactly one body of instructions in force for any run, never a stack of fragments quietly combined, so the text on the page is the text the agent reads.

The page tells you which layer is active. A source indicator reads Platform Default until you customize, then Tenant Override once your workspace text is in force; a profile's tab shows Profile Override the same way. The indicator names the active layer on every surface, so the shipped baseline and your own text are never mistaken for each other.

The policy floor

Above whatever instructions are in force sits a section you do not edit. On any run where an agent can act, a chat turn or a Flow step, the platform layers its own policy section on top of your guidance as the prompt is assembled, carrying the operating rules in force for the run, including the active environment's change policy: what the agent may apply directly and what it must propose for review. It cannot be overridden, so your customizations extend the guidance rather than removing the floor beneath it.

The floor is the same on every run, no matter who wrote the instructions beneath it or what they wrote. A workspace operator can rewrite the whole instruction body and still cannot lower the operating rules a run obeys, which is exactly the property a security or platform owner wants from a control this central.

The order is fixed, and it explains why instructions behave the way they do. The policy section sits above your instructions and cannot be moved. Your Agent Instructions come next, so your conventions govern everything below them. The prompt for whatever skill is running comes after that, as the specific task for this run. The result is predictable every time: the floor always holds, your standing guidance always applies, and the skill decides only the work in front of it.

Instructions, skills, models, and approved actions

Instructions are one of the pieces that come together when an agent runs, and they read more clearly once you can see where they sit next to the others. An agent at run time is your instructions, the skill for the task, the model it runs on, and the approved actions that bound what it may change. Each answers a different question, and instructions answer one of them without reaching into the rest.

• Instructions are the constant: how the work is done on your team, read on every run.
• A skill is the task: the named prompt for one kind of work, stacked on top of your instructions when you invoke it.
• A model is the engine: the runtime a run executes on, set by your AI runtime settings and pinnable per skill, with no bearing on what your instructions say.
• Approved actions are the boundary: the change policy that decides what a run applies directly and what it proposes for review, carried in the policy floor above your instructions.

The division is deliberate. Instructions never grant a permission or pick a model; they shape behavior within the boundary that approved actions set and on whatever model the run uses. That is why the same instructions hold whether a run is on a strong reasoning model or a fast one, and why rewriting your instructions can change how an agent works but never what it is allowed to do. The two questions, how an agent behaves and what it may touch, stay separate on purpose, so the people who own each can reason about it without watching the other.

Editing

You start from the platform default and Customize it, which creates your workspace override and opens it for editing in place. The default is read-only until you customize, so you always know whether you are changing the shipped baseline or your own text. A profile override works the same way on its own tab. The body is a markdown editor with no length limit you will reach for a working manual, so you can be as specific as your conventions need.

Reset to the layer beneath

If you decide an override was a mistake, Reset to Default removes your workspace text and falls back to the platform baseline; on a profile, the equivalent reset drops the profile override and falls back to the workspace text. Either way the layer beneath takes over again, and the reset is captured in history as plainly as an edit.

Let the agent write them

You can ask the agent to draft or refine your instructions. Choose to edit them with AI and a focused chat opens already pinned to the scope you are on, workspace or a specific profile; describe the conventions you want and the agent writes them into that scope for you. The change goes through the same guarded path as any agent-authored edit: it is permission-checked, pinned so it cannot wander into the wrong scope, and the resulting version is stamped as AI-authored. Drafting with the agent and writing by hand land in the same place, with the same history. The first response can take ten to thirty seconds while the sandbox the agent drafts in starts up; after that the body fills in live as the agent writes, held read-only until the draft lands so a hand edit and the agent are never fighting over the same text. The agent writes up to roughly fifty thousand characters per revision, far more than a working manual needs.

Versions and restore

Every save snapshots a version, tagged with whether the edit came from a person, the agent, or the system. The Version History tab lists them with the author and a change note, filterable by who made the edit and by whether it was hand-written or agent-authored. Open a version to see a side-by-side diff against the one before it, or against the content it inherits from the layer above for the first version. Filtering the list to the agent-authored versions is the fast answer to what the agent has changed about your standing guidance, and when, which is the question a security owner brings to a control this central.

Restore brings an earlier version's content back. Restore is non-destructive, the same as every other place versioning shows up in Disco Parrot: it writes the old content forward as a new version under your name rather than discarding the later ones, so nothing is lost and the history stays a complete account of how the guidance changed. The restored version carries an automatic "Restored from" note, so the entry documents itself in the history. A save that matches the text already in force is recognized as a no-op, so the history records real changes instead of filling with duplicates.

How instructions reach a run

When an agent runs, the platform resolves the effective instructions, records which layer they came from, and assembles them into the prompt beneath the policy section. The same resolved instructions reach not only the main agent but the subagents a run fans out to, so a multi-agent run follows your conventions across every branch of the work, not just its first turn. Every run records the resolved instructions and the layer they came from, so a given run's guidance is a fact you can read back, not one you infer from how it behaved.

Read-only Ask runs read your instructions too, so the agent answers questions in the same house style it uses to do the work. The policy floor, which governs what an agent may change, applies only to runs that can act, because a question has nothing to apply or propose.

What to put in your instructions

The best instructions read like the note you would hand a strong new teammate on their first day: the conventions that are obvious once you know them and slow to discover on your own. They are standing guidance, not a task list, so write the things that hold across every run rather than the steps of any one job.

A few kinds of guidance earn their place every time.

• How your team frames its work. The shape of a plan you accept, the sections a spec carries, the level of detail a research note should land at. Write the structure down once and every plan the agent drafts arrives in it.
• The conventions an outsider would miss. The test command for this stack, the lint rules you actually enforce, the directory a new module belongs in, the commit-message shape. These are the facts that make the difference between a change that fits and one a reviewer has to reshape by hand.
• The tone you want back. How direct a review should be, whether to lead with the blocking issues or the praise, how much explanation a summary should carry. Review tone is guidance an agent follows well and a place teams rarely think to set.
• The things to never do. The queries that must never run against production, the files no agent should touch, the dependencies you do not add, the secrets that never get logged. Standing prohibitions belong here because they hold on every run regardless of the task.

Two habits keep instructions working as they grow. Write them as instructions, not background: "open the smallest pull request that stands on its own" steers a run; "we care about small PRs" mostly does not. And keep them about how the work is done rather than what to do on a given day, because the day's task is what a prompt or a skill is for. Instructions you can read in a minute and recognize as your team's house style are instructions every agent can apply on every run.

Workspace text, or a profile override?

Most of what your team writes belongs in the workspace instructions, because most conventions are true everywhere: how you frame a plan, the tone for a review, the prohibitions that hold across every stack. Reach for a profile override only when a particular environment needs guidance that would be wrong anywhere else.

The line is whether the guidance travels with the work or with the environment.

• It travels with the work. Your planning shape, your review tone, your standing prohibitions, anything that should hold no matter which repository or stack a run lands on. This is workspace text, and editing it once moves every agent at the same time.
• It travels with the environment. A test command that only makes sense for one service's stack, a review checklist tied to one codebase, a build step a single repository needs. This is a profile override, set on the sandbox profile that fronts that environment.

A profile override replaces the workspace text for runs on that profile rather than adding to it, so an override carries the full guidance a run on that profile should read, not just the part that differs. The cost of a profile override is that it is one more body of text to keep current, which is why the workspace layer is the right home for anything that is true in more than one place. When you find yourself copying the same convention into several profiles, that is the signal it belongs in the workspace text instead.

A worked example

Sarah's Analytics team writes a lot of plans, and they all follow the same shape: a problem statement, the data sources in play, the acceptance checks. Rather than restate that in every prompt, Sarah opens the Agent Instructions page, clicks Customize, and writes it down once: how the team frames a plan, the review tone she wants, the queries the agent should never run against production. From that save on, every chat turn and every Flow step on the workspace starts from those conventions. Her team briefs the task and the agent already knows the house style.

Then the team picks up a service on a different stack, fronted by its own sandbox profile. The plan-writing conventions still apply, but that service has its own test command and its own review checklist. Sarah opens that profile's Agent Instructions tab and writes guidance just for it. Now a run on that service follows the profile text, with its test command and its checklist, and a run anywhere else stays on the workspace conventions. The source indicator on each surface tells anyone looking which one a run will read.

Who can read and edit

Reading the instructions and changing them are separate permissions, so you can let the whole team see the guidance while only a few people are allowed to rewrite it.

Reading ships on every working role (the finance-only Billing Manager is the lone exception), so anyone on the workspace doing the work can see the standing guidance an agent follows, which is part of keeping agent behavior legible rather than hidden. Editing is the elevated permission, held by your owners, admins, and workspace operators, so a single, central, versioned control over how every agent behaves stays in the hands of the people accountable for it.

What a security owner can answer

A control this central draws a specific set of questions, and the page is built so each has a plain answer rather than an investigation.

• What guidance was in force on this run? Every run records the layer its instructions resolved from, and the text of that layer is on the page, in full, because layers replace rather than merge. There is one body of instructions to read, not a blend to reconstruct.
• What has changed, and who changed it? The Version History tab is the full account: every save tagged person, agent, or system, with the author and a change note, filterable to exactly the agent-authored edits when that is the question. Restore writes forward as a new version, so the history is never edited out from under you.
• What can no one override? The policy floor sits above every layer and cannot be lowered by anyone who can edit instructions, including a workspace operator rewriting the whole body. The operating rules a run obeys are the same regardless of the guidance beneath them.
• Who is allowed to rewrite this? Reading the guidance is open to the working roles; editing, resetting, and restoring it sit behind the elevated agent-instructions.manage scope, held by owners, admins, and workspace operators. The people who can change how every agent behaves are a named, accountable set.

The shape of the answer is the same each time: read the current text, read the history, and the floor holds underneath both. A governance question about agent behavior resolves on this page, without a meeting and without reverse-engineering it from how a run turned out.

Why Agent Instructions work this way

The alternative to standing instructions is repeating yourself. Without them, every prompt has to restate your conventions, every skill has to carry your house style, and the agent's behavior drifts with whoever wrote the last instruction. Disco Parrot pulls that guidance into one place, so you set it once and every agent reads it, and versions that one place so you can see what it says now and what it said before, and who changed it.

Replacement instead of merging is a deliberate choice. Concatenated layers are unpredictable: the text the agent ends up reading is a blend of things several people wrote at different times, and no one can say exactly what it amounted to. One body of instructions in force per run, with a clear record of which layer it came from, means the guidance is something you can reason about and audit, not something you have to reverse-engineer from a run's behavior.

For a planner, instructions mean the agent already knows the shape of a plan before you ask for one, so you describe the problem and skip the conventions you would otherwise retype every time. For an engineer, a profile override is how a service on its own stack gets its own test commands and review checklist without anyone editing the guidance the rest of the team relies on. For a lead, this is one versioned control over how every agent behaves, a policy floor no one can lower, and a history that answers who changed the guidance, and when, without a meeting. For a new hire, the Agent Instructions page is the team's working manual, current by definition, because the agent onboards from the exact same text they are reading.