Personas and instructions
A persona and a set of instructions look similar — both are prose you write for an Agent — but they live on opposite sides of publishing. A persona is durable identity: it's written once on the Agent, compiled into every version it publishes, and a change to it only takes effect the next time that Agent is republished. Instructions live on a Workflow's agent step: per-job task text, rendered fresh against the live run — the trigger's data, earlier steps' outputs, workflow state — every time the step executes, with changes going live the instant you publish the Workflow. No build, no wait.
That difference should drive what you put where. If it's true of the Agent no matter what work it's handed, it belongs in the persona. If it's specific to one standing job — what to do with this trigger's data, what shape the output should take — it belongs in the agent step's instructions.
Writing a persona
A persona is role and working style, not a job description. The most common mistake is writing something too generic to change how the Agent actually behaves — it compiles fine and does nothing.
| Vague | Specific |
|---|---|
| "You are a helpful assistant." | "You are a support-triage specialist for a B2B SaaS product. You read incoming tickets, judge urgency, and file well-formed issues in Linear for anything that's a real bug. You never promise a fix timeline, and you escalate billing disputes to a human instead of trying to resolve them yourself." |
| "You write good code." | "Pragmatic senior engineer. Reads before it writes. Prefers the smallest correct diff over a rewrite, and flags anything touching authentication or billing for human review instead of changing it unilaterally." |
| "You are a marketing assistant." | "You draft launch announcements and social copy in a direct, confident voice — no exclamation points. You never publish anything yourself; every draft goes back to a human for review before it goes out." |
Each specific version does three things the vague one doesn't: it names a domain, it names a working style, and it names an explicit boundary — something the Agent should refuse or hand off rather than attempt. That boundary is doing real work; without it, a persona only describes competence, not judgment.
Keep a persona about role and working style, not procedure. A step-by-step process — "when a ticket mentions billing, do X then Y then Z" — belongs in a skill the Agent is equipped with, or in an agent step's instructions if the process is specific to one standing job, not in the persona itself. And a deterministic procedure often shouldn't be prose at all: if it's "search, then dedupe, then file," those are tool and control steps in the pipeline, not sentences an Agent has to follow.
Writing instructions
Instructions are the agent step's task: what to do, what shape you want the output in, and what to do with the specific data the run carries. They are not context — the Agent's own equipment (its connections and skills) is the context, and instructions may name that equipment in prose but never extend it. They're also not the pipeline: the step order, the loops, the conditions all live in the pipeline's structure, so instructions can stay about the judgment call this one step exists to make. (An infer step's prompt follows the same advice, just aimed at a one-shot model call rather than a full Agent.)
Working with @ references
Instructions and prompts reference the run with @ tokens, resolved when the step executes: @trigger.<field> for the trigger event's data, @steps.<slug>.<path> for an earlier step's output, @state.<key>, @item inside a loop, @now. Say a support-form Workflow's trigger has fields keyed email, subject, and body:
A new support request came in.
From: @trigger.email
Subject: @trigger.subject
@trigger.body
File this as a Linear issue if it describes a bug. Summarize the request in
the issue description rather than pasting it verbatim.
A reference that can't be legal is flagged in the editor and blocks publish: a typo'd form-field key (@trigger.eamil when no field is keyed that), @steps pointing at a step that runs later, @item outside a loop. A reference that's legal but empty at run time — a webhook key this particular POST didn't carry, a state key not yet written — renders as "(not provided)" so the step still runs; write instructions that tolerate that where the data is genuinely optional.
Anti-patterns
- Instructions assuming a tool the Agent isn't equipped with. The pipeline can't check an Agent's equipment for you — naming a connection or skill in instructions is plain prose. If the Agent doesn't actually have the tool, the step fails or flounders at run time; equip the Agent, or better, make the call a
toolstep and take the guesswork out entirely. - A persona naming a specific model. Which model an Agent runs on is chosen in the Model section, not written in prose — see Models. A persona that says "you are running on GPT-4" is not just noise, it's actively wrong the moment someone changes the preset, and there's nothing that keeps prose like that in sync with the real setting.
- Instructions expecting a reply where none is delivered. A webhook's HTTP response is only an acknowledgement that a run started — never the result — and a Slack thread gets a reply only when the Workflow declares one. Instructions that talk about "responding to the request" are describing something that doesn't happen on those paths; the run's record is its step timeline. See Triggers.
The iteration loop
Instructions are cheap to change precisely because they don't build anything: edit the step, publish (instant), fire the Workflow from the header's Run popover, and open the run in the Runs tab — the agent step embeds its child run's full transcript right in the timeline, so you can read exactly what the Agent was told and what it did with it. If the output isn't shaped the way you wanted, adjust and run again — there's no publish-and-wait cycle between iterations the way there is for a persona edit on the Agent side.
See Agents and Workflows for how persona and instructions fit into the rest of each concept, and the agent editor for where a persona is actually written.