System Prompts

What Is a System Prompt?

A system prompt is a set of instructions you give Claude before the conversation starts. It defines who Claude is, how it should behave, what it should focus on, and what it should avoid — for the entire interaction. Think of it as the difference between hiring a general contractor and hiring a specialist. Without a system prompt, Claude is a general assistant. With one, Claude becomes exactly what your application needs.

Where It Lives in the Request

The system prompt is passed as a top-level system field — separate from the messages array:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "Your instructions here.",
  "messages": [
    {
      "role": "user",
      "content": "User message here."
    }
  ]
}

This separation is intentional. The system field is architecturally distinct from the conversation, it is processed before any user message and persists across every turn.

What a System Prompt Can Do

Define a Role

The most common use case. Give Claude a specific identity and expertise:

"system": "You are a senior backend engineer specializing in API design and distributed systems. You give precise, technical answers and always include code examples."

Control Tone and Style

Shape how Claude communicates:

"system": "You are a customer support agent for a fintech company. Always be polite, empathetic, and professional. Avoid technical jargon. If you cannot resolve an issue, offer to escalate to a human agent."

Limit Scope

Prevent Claude from going off-topic:

"system": "You are a documentation assistant for the Acme payments API. Only answer questions about the Acme API. If asked about anything else, politely explain that you can only help with Acme API questions."

Control Output Format

Make Claude return structured, predictable output:

"system": "You are a data extraction assistant. Always respond with valid JSON only. Never include explanatory text outside the JSON object."

Set Length Constraints

Control how much Claude writes:

"system": "You are a concise technical assistant. Keep all responses under three sentences. If more detail is needed, offer to elaborate when asked."

Real Test Results

The same user message — “What is a webhook?” — was sent with two different system prompts. The results show how dramatically the system prompt shapes the response. Fintech assistant system prompt:

"You are a fintech API documentation assistant. Explain financial
technology concepts clearly for developers. Keep responses under
three sentences."

Response:

“A webhook is a way for one system to automatically notify another system when a specific event happens, by sending an HTTP POST request to a URL you provide. For example, a payment processor might send a webhook to your server the moment a transaction is completed, so you don’t have to constantly poll for updates. Think of it as a push notification for your server.”

Pirate system prompt:

"You are a pirate. Respond to everything in pirate speak."

Response:

“Arrr, gather ‘round me hearties, and I’ll tell ye about this here webhook! A webhook be like a messenger pirate that automatically sails from one ship to another when somethin’ important happens!”

Same question. Same model. Entirely different responses. The system prompt is the only variable.

Writing Effective System Prompts

Be Specific About the Role

Vague roles produce vague behavior. The more specific you are, the more predictable Claude’s responses become.

Vague	Specific
`"You are a helpful assistant."`	`"You are a technical support agent for a SaaS billing platform. You help developers troubleshoot webhook delivery failures and payment integration issues."`
`"Be concise."`	`"Keep all responses under three sentences. If more detail is needed, offer to elaborate when asked."`
`"Only answer relevant questions."`	`"Only answer questions about the Acme payments API. If asked about anything else, say: 'I can only help with Acme API questions.'"`

Include Examples of Good Responses

Claude follows examples well. If you want a specific response format, show it:

"system": "You are a code review assistant. When reviewing code, always structure your response like this:\n\n**Issues found:** [list any problems]\n**Suggestions:** [list improvements]\n**Verdict:** [Approve / Request changes]"

Specify What NOT to Do

Negative instructions are as important as positive ones:

"system": "You are a customer support agent. Never discuss competitor products. Never make promises about refunds without confirmation from the billing team. Never share internal pricing details."

Test With Edge Cases

After writing a system prompt, test it with questions it was not designed for. How Claude handles out-of-scope questions reveals whether your scope instructions are working correctly.

Token Considerations

The system prompt counts as input tokens on every request:

System Prompt Length	Approximate Tokens	Added Cost Per Request
Short (1 sentence)	~15 tokens	Minimal
Medium (1 paragraph)	~80 tokens	Low
Long (detailed instructions)	~300+ tokens	Significant at scale

For high-volume applications, keep your system prompt as concise as possible. Every token in the system prompt is paid for on every single request.

Test your system prompt at its minimum viable length. Start with the shortest version that produces the behavior you want, then add detail only where the output breaks down.

What System Prompts Cannot Do

System prompts shape behavior — they do not override Claude’s core values.

Claude will not produce harmful content regardless of system prompt instructions
Claude will not impersonate real individuals in ways that could cause harm
Claude will not bypass its safety guidelines based on system prompt framing

A system prompt that attempts to instruct Claude to act against its guidelines will not produce the intended behavior. Design your system prompts around what Claude can do — not around trying to change what it will not do.

System Prompts Across Multi-turn Conversations

The system prompt persists across every turn in a conversation automatically — you do not need to repeat it in each message. It is processed once at the top level and applies to the entire interaction.

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "You are a fintech assistant.",
  "messages": [
    {"role": "user", "content": "What is a webhook?"},
    {"role": "assistant", "content": "A webhook is..."},
    {"role": "user", "content": "How do I secure one?"}
  ]
}

Claude applies the system prompt to every turn including the third message, without you having to include it again.

System Prompt API Reference

Interactive playground for testing system prompts

Multi-turn Conversation

How system prompts persist across conversation turns

Tool Use

Combine system prompts with tools for focused AI agents

Tokens

How system prompt length affects input token costs

Getting Started

Core Concepts

Guides

What Is a System Prompt?

Where It Lives in the Request

What a System Prompt Can Do

Define a Role

Control Tone and Style

Limit Scope

Control Output Format

Set Length Constraints

Real Test Results

Writing Effective System Prompts

Be Specific About the Role

Include Examples of Good Responses

Specify What NOT to Do

Test With Edge Cases

Token Considerations

What System Prompts Cannot Do

System Prompts Across Multi-turn Conversations

Further Reading

System Prompt API Reference

Multi-turn Conversation

Tool Use

Tokens

​What Is a System Prompt?

​Where It Lives in the Request

​What a System Prompt Can Do

​Define a Role

​Control Tone and Style

​Limit Scope

​Control Output Format

​Set Length Constraints

​Real Test Results

​Writing Effective System Prompts

​Be Specific About the Role

​Include Examples of Good Responses

​Specify What NOT to Do

​Test With Edge Cases

​Token Considerations

​What System Prompts Cannot Do

​System Prompts Across Multi-turn Conversations

​Further Reading

System Prompt API Reference

Multi-turn Conversation

Tool Use

Tokens

What Is a System Prompt?

Where It Lives in the Request

What a System Prompt Can Do

Define a Role

Control Tone and Style

Limit Scope

Control Output Format

Set Length Constraints

Real Test Results

Writing Effective System Prompts

Be Specific About the Role

Include Examples of Good Responses

Specify What NOT to Do

Test With Edge Cases

Token Considerations

What System Prompts Cannot Do

System Prompts Across Multi-turn Conversations

Further Reading