Modifying system prompts

System prompts define Claude’s behavior, capabilities, and response style. Start from the claude_code preset for CLI or IDE-like coding tools where a human watches and steers the work. Write your own prompt for agents with a different surface, identity, or permission model.

How system prompts work

A system prompt is the initial instruction set that shapes how Claude behaves throughout a conversation. The Agent SDK has three starting points for it:

Minimal default: when you don’t set systemPrompt in TypeScript or system_prompt in Python, the SDK uses a minimal prompt that covers tool calling but omits the rest of the claude_code preset’s content, including its security and safety instructions. This differs from claude -p, which uses the Claude Code system prompt by default. If you’re migrating from the CLI and want matching behavior, set the claude_code preset.
claude_code preset: the system prompt that the Claude Code CLI uses, with tool usage instructions and security and safety instructions. Set systemPrompt: { type: "preset", preset: "claude_code" } in TypeScript or system_prompt={"type": "preset", "preset": "claude_code"} in Python, optionally with append to add your own instructions on the end.
Custom string: a prompt you write yourself. The SDK sends only what you provide.

Decide on a starting point

The deciding factor is how closely your agent resembles Claude Code: a coding agent operating in a repository, with a human watching streaming output and steering the work. The further your product is from that, the more you’ll want to write your own prompt.

You’re building	Use	What you get
A CLI or IDE-like coding tool where a human watches and steers, and Claude Code’s defaults are what you want	`claude_code` preset	The Claude Code prompt, including tool guidance and safety rules
The same kind of tool, plus product-specific rules like coding standards, output format, or domain context	`claude_code` preset with `append`	Everything above, with your instructions added after the preset. Nothing is removed, so this is the lowest-risk customization
An agent with a different surface, identity, or permission model, or a non-coding agent	Custom prompt string	Only what you write. You take responsibility for replacing the tool guidance and safety instructions your agent still needs
A thin tool-calling loop with no agent persona, where you supply all behavior in the user prompt	No `systemPrompt` option	The minimal default: tool-calling support and nothing else

“Different from Claude Code” usually means one of the following:

Different surface: the output isn’t read in a terminal by the person who triggered it. Chat UIs, structured-output consumers, and non-coding automation each need a prompt that matches how their output is rendered and reviewed. Unattended coding automation, like a CI job that fixes lint errors or reviews diffs, still fits the preset because the work itself is what the preset is written for.
Different identity: the agent shouldn’t present itself as Claude Code. A support bot, a data-analysis assistant, or any domain-specific agent needs its own name, scope, and persona.
Different permission model: the agent runs autonomously without a human approving each step, or operates on a narrow set of resources. Claude Code’s prompt assumes a human is in the loop with access to a full toolset.
Non-coding tasks: most of Claude Code’s prompt is coding guidance. For research, content, or operations agents, that guidance competes with the instructions you actually need.

The comparison table shows what each customization method preserves.

Customize agent behavior

append and a custom prompt string each change the system prompt directly, and an output style changes the instructions Claude Code gives Claude for every response. CLAUDE.md takes a different path: the SDK reads it and injects its content into the conversation as project context, so it shapes behavior alongside whichever system prompt you choose. Skills, hooks, and permissions also shape behavior outside the system prompt and are covered on their own pages.

CLAUDE.md files for project-level instructions

CLAUDE.md files give Claude persistent project context and instructions. The SDK injects their content into the conversation and leaves the system prompt untouched, so they work with any system prompt configuration. For what to put in CLAUDE.md, where to place it, and how to write effective instructions, see When to add to CLAUDE.md and the rest of How Claude remembers your project. This section covers what’s specific to the SDK: how CLAUDE.md loads. The SDK reads CLAUDE.md when the matching setting source is enabled: 'project' loads CLAUDE.md or .claude/CLAUDE.md from the working directory, and 'user' loads ~/.claude/CLAUDE.md. Default query() options enable both sources, so CLAUDE.md loads automatically. If you set settingSources in TypeScript or setting_sources in Python explicitly, include the sources you need. CLAUDE.md loading is controlled by setting sources, not by the claude_code preset.

Load CLAUDE.md with the SDK

To load CLAUDE.md, set settingSources to include the level where you keep your CLAUDE.md. The example below loads a project-level CLAUDE.md alongside the claude_code preset, so Claude has both the coding-agent prompt and your project’s conventions:

import { query } from "@anthropic-ai/claude-agent-sdk";

const messages = [];

for await (const message of query({
  prompt: "Add a new React component for user profiles",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code" // Use Claude Code's system prompt
    },
    settingSources: ["project"] // Loads CLAUDE.md from project
  }
})) {
  messages.push(message);
}

// Now Claude has access to your project guidelines from CLAUDE.md

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

messages = []


async def main():
    async for message in query(
        prompt="Add a new React component for user profiles",
        options=ClaudeAgentOptions(
            system_prompt={
                "type": "preset",
                "preset": "claude_code",  # Use Claude Code's system prompt
            },
            setting_sources=["project"],  # Loads CLAUDE.md from project
        ),
    ):
        messages.append(message)


asyncio.run(main())

# Now Claude has access to your project guidelines from CLAUDE.md

When you run either example, the SDK streams messages as Claude works: a system init message, assistant messages, user messages carrying tool results, and a final result message with the session outcome. CLAUDE.md is persistent across all sessions in a project, shared with your team through git, and discovered automatically without code changes. It is not loaded if you pass an empty settingSources array.

Output styles for persistent configurations

Output styles are saved sets of instructions that change Claude’s role, tone, and output format. They’re stored as markdown files and can be reused across sessions and projects.

Create an output style

An output style is a markdown file with frontmatter for metadata, followed by the prompt content. Save it to ~/.claude/output-styles/ for a user-level style available in every project, or .claude/output-styles/ in your repository for a project-level style you can commit and share with your team. A custom output style leaves the claude_code preset’s software engineering instructions out and uses your own. To keep them and layer your instructions on top, set keep-coding-instructions: true in the frontmatter. Those instructions are only in Claude Code’s full system prompt, so the setting has no effect in a session on the shorter system prompt, which you pin on or off with CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT. Keep them when your agent is still doing software engineering work. Leave them out when you’re replacing the role entirely. The example below defines a code-review persona that keeps the coding instructions, since reviewing code still benefits from Claude Code’s security and code-quality guidance. Save it as ~/.claude/output-styles/code-reviewer.md to make it available across projects:

~/.claude/output-styles/code-reviewer.md

---
name: Code Reviewer
description: Thorough code review assistant
keep-coding-instructions: true
---

You are an expert code reviewer.

For every code submission:
1. Check for bugs and security issues
2. Evaluate performance
3. Suggest improvements
4. Rate code quality (1-10)

Activate an output style

Once created, activate output styles via:

CLI: run /output-style

Agent SDK

Build agents

Core concepts

Input and output

Extend with tools

Customize behavior

Control and observability

Deployment

SDK references

How system prompts work

Decide on a starting point

Customize agent behavior

CLAUDE.md files for project-level instructions

Load CLAUDE.md with the SDK

Output styles for persistent configurations

Create an output style

Activate an output style

​How system prompts work

​Decide on a starting point

​Customize agent behavior

​CLAUDE.md files for project-level instructions

​Load CLAUDE.md with the SDK

​Output styles for persistent configurations

​Create an output style

​Activate an output style

How system prompts work

Decide on a starting point

Customize agent behavior

CLAUDE.md files for project-level instructions

Load CLAUDE.md with the SDK

Output styles for persistent configurations

Create an output style

Activate an output style