What is a system prompt?
A system prompt is the instruction text an application sends to a model before the conversation: who the model is, what it may do, what it knows about the setting. In the Claude API it is the top-level system parameter; in OpenAI's Responses API, the instructions parameter or a developer message. Models rank it above user messages.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
Your application writes the system prompt: role, rules, context, available tools. The person chatting doesn't write it and usually never sees it.
On each request the application sends it ahead of the messages: the system parameter in the Claude Messages API, instructions or a developer message at OpenAI.
The model gives it more weight than user turns. OpenAI's Model Spec puts developer instructions above user instructions and below the platform's own rules.
It does not persist by itself. OpenAI notes that instructions apply only to the current request and are absent when you continue with previous_response_id.
A long, stable system prompt is where prompt caching pays off: the Claude API lets you put cache_control on a system block so repeated requests reuse it.
Source: Claude API reference: Messages
System prompt versus user prompt
A conversation with a model has two authors. The person types user messages. The application that wraps the model writes the system prompt, and the model is trained to treat the two differently. Anthropic's API reference describes the system parameter as a way of providing context and instructions, such as a goal or a role. OpenAI's Model Spec spells out the ranking: developer instructions sit above user instructions, so when the two conflict the developer's wording wins, and both sit below rules the platform sets. The docs offer a tidy analogy: the developer message is the function definition, the user message is the arguments it runs on.
That ranking is the whole point. A system prompt lets you set behaviour once, for every person who uses the product, without asking them to repeat it.
Example: the same instruction in two APIs
In the Claude Messages API, system is a top-level parameter, a string or an array of text blocks:
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": "You review pull requests for a TypeScript monorepo. Flag only correctness bugs. Reply in bullet points.",
"messages": [{ "role": "user", "content": "Here is the diff: ..." }]
}
In OpenAI's Responses API the same text goes in instructions, which the docs say is roughly equivalent to adding a developer message to input, and it takes priority over anything in input:
{
"model": "your-model",
"instructions": "You review pull requests for a TypeScript monorepo. Flag only correctness bugs. Reply in bullet points.",
"input": "Here is the diff: ..."
}
Notice what is missing from both: the model itself. The system prompt is part of the request, not part of the model, which is why two apps on the same model can behave so differently.
Why it matters
Three properties follow from where the system prompt lives. It is stable, so it is the natural place for a role, the house style, the list of tools and the hard rules; Anthropic's guidance notes that even a one-sentence role in the system prompt changes Claude's behaviour and tone. It is repeated, so every request pays for it in tokens, and caching a long one with cache_control is the standard fix. And it is privileged but not secret: a model will defend it, but prompt injection exists precisely because text in a user turn or a tool result can sometimes argue its way past it.
Common mistakes
- Assuming it carries over. In the Responses API,
instructionsapplies to the current request only; continue withprevious_response_idand the earlier instructions are gone unless you send them again. - Shouting. Anthropic's prompting guide notes that recent Claude models respond strongly to system prompts, so "CRITICAL: You MUST" can cause over-triggering. Plain "Use this tool when" works.
- Storing secrets in it. Keys and private data belong in your backend, not in text the model can be talked into repeating.
- Putting the task in the system prompt. Keep the role and rules there; the thing to do right now goes in the user turn, where it can change per request.
FAQ
- Is a system prompt the same as a developer message?
- In OpenAI's Responses API, near enough: the docs describe the instructions parameter as roughly equivalent to a developer message in the input array, and the Model Spec ranks developer instructions above user ones. The Claude API takes a separate system parameter instead of a message role.
- Can a user read the system prompt?
- Not by default, and you should not rely on that. OpenAI's Model Spec says the verbatim text should stay private while facts like capabilities can be shared, but models leak under pressure and prompt injection targets exactly this. Never put a secret in it.
- How does a system prompt differ from CLAUDE.md or Cursor rules?
- Those files are how a coding agent builds part of its system prompt from your repository. The agent reads them and places the content ahead of your request. The system prompt is the finished text the model actually receives on each call.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.