System Prompt
The system prompt is the foundation of every agent. It is present in every single call to the language model — shaping how the agent thinks, what it knows, and how it behaves. Everything in the system prompt competes for the model’s attention and accrues cost on every call.
That makes the system prompt the most valuable real estate in your agent’s design. What you put here matters. What you keep out matters just as much.
One principle governs what belongs:
Only put things in the system prompt that the agent should always have in mind.
Procedures the agent rarely needs, tasks that happen at specific times, ambient checks — those belong in skills, schedules, or the heartbeat. The system prompt is for what the agent needs in every interaction.
In the end, a system prompt is just one block of text. You can write it however you like. But we find that you end up with better agents if you consistently split it into three sections, each with a clearly defined purpose: identity, context, and instructions.
Identity
Section titled “Identity”Identity is a short statement that sets the agent’s way of thinking.
When you write “thinks like a seasoned executive coach” or “grounded in the StoryBrand framework,” the agent shifts how it reasons, what it prioritizes, and how it communicates. A well-chosen identity anchors the agent to a known reference — a discipline, a methodology, a recognizable approach — and the agent naturally adopts that way of working. Identity is about activating the right mindset, not describing a job.
Design principles:
- 2–3 sentences max. It is present in every call — keep it tight.
- Anchor to a known reference. This is the power move. The model already knows these references and naturally adopts their methods. A person, school of thought, framework, or discipline.
- Set character in a few words. “Concise and direct.” “Warm but rigorous.”
- No operational content. If you are writing verbs — “you analyze,” “you always start by” — you have crossed into instructions. Identity has no verbs.
The no-verbs test: Read your identity statement. If it contains action words, extract them to instructions.
Design question: “What existing way of thinking should this agent embody?”
Examples
Section titled “Examples”Bad:
“You are a helpful assistant.”
Activates nothing specific. The model has no reasoning pattern to lock onto.
Bad:
“You are a marketing strategist. You help the team develop campaigns. You always start by analyzing the target audience.”
Operational details have leaked in. “Help the team develop” and “always start by analyzing” are instructions, not identity.
Good:
“You are a senior marketing strategist grounded in the StoryBrand framework. Creative but rigorous.”
Clear anchor (StoryBrand), character in two words.
Good:
“You are a personal fitness coach rooted in the principles of Starting Strength. Patient, methodical, no-nonsense.”
Clear anchor (Starting Strength), character in three words. The agent knows what approach to take.
Good:
“You are a code reviewer who thinks like Martin Fowler — focused on readability, simplicity, and clean abstractions.”
Specific anchor, clear values. The agent knows exactly what to prioritize.
Context
Section titled “Context”Context is the background knowledge the agent needs to operate well. It is passive, environmental — what the agent needs to know, not what it needs to do.
Think of it as everything a new hire would need to know about the environment before they can be effective — but not their actual job duties.
Design principles:
- Environmental, not operational. Context tells the agent about its world. What tools exist, where files live, who the users are, what systems are in play. It does not tell the agent what to do with any of this.
- Stable information only. Context should rarely change. If it changes per task, it probably belongs in a skill.
- Resource map is key. In practice, the most important context is: what does the agent have access to and where is it? Tools, files, volumes, databases, APIs.
What belongs in context:
- Resource map — tools, files, volumes, systems available
- User and team information — who the agent serves, team structure
- Domain background — industry context, product knowledge
- Boundaries and constraints — what the agent cannot or should not access
What does not belong in context:
| If it is about… | It belongs in… |
|---|---|
| Who the agent is | Identity |
| What the agent should do | Instructions |
| How to do a specific procedure | A skill |
| Something the agent learns over time | Memory |
Context and memory: Your agent also has memory — knowledge it writes for itself over time. Context and memory can overlap: the agent might eventually discover where files live or how the team is structured and add that to its memory. But anything you know belongs in the agent’s world, cement it in context. That way you do not rely on the agent discovering it, and the agent can spend its memory on things you could not anticipate.
Design question: “What does this agent need to know about its environment to be effective?”
Examples
Section titled “Examples”Bad:
“You have access to the Todoist API. Always check tasks first thing and flag overdue items.”
“Always check” and “flag overdue” are instructions, not context.
Good:
“You have access to the Todoist API via the TODOIST_API_KEY secret. The user manages both personal and work tasks in Todoist, organized by project.”
Pure environmental knowledge. The agent knows what is there without being told what to do with it.
Good:
“The team communicates via Slack. Design docs live in the shared Google Drive under /design. The codebase is a TypeScript monorepo.”
Resource map — where things are.
Instructions
Section titled “Instructions”Instructions are the operational guidance the agent follows in every interaction. They are active, behavioral — what the agent does and how it works.
This is where the designer makes the most important decisions. Instructions sit at the boundary between what is always active and what is loaded on demand. Managing that boundary is the core craft of agent design.
Design principles:
- Keep them lean. Long instructions are the number one sign of a poorly designed agent. It usually means content that belongs in skills has leaked in.
- Standing operational norms only. Instructions should apply to every interaction. If something only applies sometimes, it is a skill.
- Include ongoing duties. Things the agent proactively cares about — tracking the user’s priorities, flagging blockers, maintaining a north star. These give the agent initiative beyond reactive question-and-answer.
- Rules of engagement. Behavioral patterns — “always confirm before deleting,” “summarize long threads before responding,” “keep responses concise.”
The extraction heuristic: It is natural to dump everything into instructions first. Then extract:
- Step-by-step procedures → Skills
- Time-triggered tasks → Schedules
- Ambient awareness concerns → Heartbeat
What remains after extraction — the standing norms and duties that apply to every interaction — those are your instructions.
The boundary test:
“Does the agent need this for every interaction?”
- Yes → Instructions
- Only for specific tasks → Skill
- At specific times → Schedule
- Ambient check-in → Heartbeat
Design question: “What should this agent always do, regardless of the specific task?”
Examples
Section titled “Examples”Bad:
“When the user asks for a blog post, first check the style guide in /docs/style.md, then outline three approaches, get user approval, write the draft following the template in /docs/blog-template.md, then…”
This is a skill, not an instruction. It only applies when someone asks for a blog post.
Bad:
“Respond to user questions accurately and helpfully.”
Generic and purely reactive. The agent will never proactively do anything.
Good:
“Help the user stay focused on high-value work. When they mention a new task, challenge whether it aligns with their current priorities before helping execute. Keep responses concise and actionable. Never modify shared documents without confirming first.”
Standing duties (focus tracking), rules of engagement (confirm before modifying), character reinforcement (concise).
Good:
“Maintain awareness of the user’s north star priority and reference it when relevant. When asked to review code, always check test coverage. Escalate security concerns immediately rather than attempting fixes.”
Ongoing duties plus operational rules that apply every time.
Putting it together
Section titled “Putting it together”The three sections work as a unit. Identity sets the thinking. Context provides the knowledge. Instructions define the behavior. A well-designed system prompt is lean, focused, and everything in it earns its place by being needed in every interaction.
When you find your system prompt growing long, that is a signal. Step back and apply the extraction heuristic — pull procedures into skills, time-triggered tasks into schedules, and ambient concerns into the heartbeat. What remains is your system prompt.