# Writing system prompts

The system prompt is where an agent gets its personality and its job. It is the
one field a profile can give you a head start on but can never finish for you,
because only you know what *this* agent is supposed to do. A good prompt is
short, concrete, and honest about the agent's limits.

## Lead with the role, then the rules

Open with one sentence that says who the agent is and what it is for. The model
anchors hard on the first line, so make it count: "You are a careful researcher
whose job is to find and explain information, never to change it." Everything
after that is the handful of rules that keep the agent on the rails.

## Prefer a few sharp rules over many soft ones

A prompt with five specific instructions beats one with fifteen vague ones. Each
rule should be something the model can actually act on and you could check it
against later. "Trace each claim back to a source, and say so when sources
disagree" is actionable. "Be thorough and accurate" is wallpaper — it sounds
good and changes nothing.

## State the access, and the prohibition

If the agent is read-only, say so in the prompt as well as in the tool
collection — not because the prompt enforces it (the tool set does that) but
because it tells the model how to plan. "You have read-only access: inspect
files and search the web, but make no edits" stops the agent from forming a plan
that depends on tools it does not have. The collection is the fence; the prompt
is the sign on the fence.

## Tell it what to do when it is stuck

The behaviour that separates a good agent from a frustrating one is what it does
under uncertainty. Spell it out. "When a request is ambiguous, state the
assumption you are making rather than guessing silently." "Say so when the
evidence is thin." An agent that surfaces its uncertainty is one you can trust;
an agent that hides it is one you have to babysit.

## Close with the shape of a good answer

End by describing what "done" looks like — the form, not just the content. "Close
with a concise, structured synthesis a reader could act on without re-reading
everything." "Report plainly what you changed and why." This gives the model a
target to write toward instead of trailing off whenever it runs out of tokens.

## Keep it in your own voice

Write the prompt as prose you would be comfortable putting your name on. Avoid
copying boilerplate from elsewhere; a prompt assembled from borrowed fragments
reads as incoherent to the model and tends to pull it in three directions at
once. One clear voice, a few sharp rules, an honest statement of limits — that is
the whole craft.
