Source: https://docs.claude.com/en/docs/agent-sdk/modifying-system-prompts

Agent Skills are now available! Learn more about extending Claude's capabilities with Agent Skills .

Claude Docs home page

English

Search...

Ctrl K

Search...

Navigation

Guides

Modifying system prompts

Home Developer Guide API Reference Model Context Protocol (MCP) Resources Release Notes

On this page

• Understanding system prompts

• Methods of modification

• Method 1: CLAUDE.md files (project-level instructions)

• How CLAUDE.md works with the SDK

• Example CLAUDE.md

• Using CLAUDE.md with the SDK

• When to use CLAUDE.md

• Method 2: Output styles (persistent configurations)

• Creating an output style

• Using output styles

• Method 3: Using systemPrompt with append

• Method 4: Custom system prompts

• Comparison of all four approaches

• Use cases and best practices

• When to use CLAUDE.md

• When to use output styles

• When to use systemPrompt with append

• When to use custom systemPrompt

• Combining approaches

• Example: Output style with session-specific additions

• See also

System prompts define Claude’s behavior, capabilities, and response style. The Claude Agent SDK provides three ways to customize system prompts: using output styles (persistent, file-based configurations), appending to Claude Code’s prompt, or using a fully custom prompt.

​

Understanding system prompts

A system prompt is the initial instruction set that shapes how Claude behaves throughout a conversation.

Default behavior: The Agent SDK uses an empty system prompt by default for maximum flexibility. To use Claude Code’s system prompt (tool instructions, code guidelines, etc.), specify systemPrompt: { preset: "claude_code" } in TypeScript or system_prompt="claude_code" in Python.

Claude Code’s system prompt includes:

• Tool usage instructions and available tools
• Code style and formatting guidelines
• Response tone and verbosity settings
• Security and safety instructions
• Context about the current working directory and environment

​

Methods of modification

​

Method 1: CLAUDE.md files (project-level instructions)

CLAUDE.md files provide project-specific context and instructions that are automatically read by the Agent SDK when it runs in a directory. They serve as persistent “memory” for your project.

​

How CLAUDE.md works with the SDK

Location and discovery:

• Project-level: CLAUDE.md or .claude/CLAUDE.md in your working directory
• User-level: ~/.claude/CLAUDE.md for global instructions across all projects

IMPORTANT: The SDK only reads CLAUDE.md files when you explicitly configure settingSources (TypeScript) or setting_sources (Python):

• Include 'project' to load project-level CLAUDE.md
• Include 'user' to load user-level CLAUDE.md (~/.claude/CLAUDE.md)

The claude_code system prompt preset does NOT automatically load CLAUDE.md - you must also specify setting sources. Content format: CLAUDE.md files use plain markdown and can contain:

• Coding guidelines and standards
• Project-specific context
• Common commands or workflows
• API conventions
• Testing requirements

​

Example CLAUDE.md

Copy

# Project Guidelines

## Code Style

- Use TypeScript strict mode
- Prefer functional components in React
- Always include JSDoc comments for public APIs

## Testing

- Run `npm test` before committing
- Maintain >80% code coverage
- Use jest for unit tests, playwright for E2E

## Commands

- Build: `npm run build`
- Dev server: `npm run dev`
- Type check: `npm run typecheck`

​

Using CLAUDE.md with the SDK

TypeScript

Python

Copy

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

// IMPORTANT: You must specify settingSources to load CLAUDE.md
// The claude_code preset alone does NOT load CLAUDE.md files
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"], // Required to load CLAUDE.md from project
  },
})) {
  messages.push(message);
}

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

​

When to use CLAUDE.md

Best for:

• Team-shared context - Guidelines everyone should follow
• Project conventions - Coding standards, file structure, naming patterns
• Common commands - Build, test, deploy commands specific to your project
• Long-term memory - Context that should persist across all sessions
• Version-controlled instructions - Commit to git so the team stays in sync

Key characteristics:

• ✅ Persistent across all sessions in a project
• ✅ Shared with team via git
• ✅ Automatic discovery (no code changes needed)
• ⚠️ Requires loading settings via settingSources

​

Method 2: Output styles (persistent configurations)

Output styles are saved configurations that modify Claude’s system prompt. They’re stored as markdown files and can be reused across sessions and projects.

​

Creating an output style

TypeScript

Python

Copy

import { writeFile, mkdir } from "fs/promises";
import { join } from "path";
import { homedir } from "os";

async function createOutputStyle(
  name: string,
  description: string,
  prompt: string
) {
  // User-level: ~/.claude/output-styles
  // Project-level: .claude/output-styles
  const outputStylesDir = join(homedir(), ".claude", "output-styles");

  await mkdir(outputStylesDir, { recursive: true });

  const content = `---
name: ${name}
description: ${description}
---

${prompt}`;

  const filePath = join(
    outputStylesDir,
    `${name.toLowerCase().replace(/\s+/g, "-")}.md`
  );
  await writeFile(filePath, content, "utf-8");
}

// Example: Create a code review specialist
await createOutputStyle(
  "Code Reviewer",
  "Thorough code review assistant",
  `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)`
);

​

Using output styles

Once created, activate output styles via:

• CLI: /output-style [style-name]
• Settings: .claude/settings.local.json
• Create new: /output-style:new [description]

Note for SDK users: Output styles are loaded when you include settingSources: ['user'] or settingSources: ['project'] (TypeScript) / setting_sources=["user"] or setting_sources=["project"] (Python) in your options.

​

Method 3: Using systemPrompt with append

You can use the Claude Code preset with an append property to add your custom instructions while preserving all built-in functionality.

TypeScript

Python

Copy

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

const messages = [];

for await (const message of query({
  prompt: "Help me write a Python function to calculate fibonacci numbers",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append:
        "Always include detailed docstrings and type hints in Python code.",
    },
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

​

Method 4: Custom system prompts

You can provide a custom string as systemPrompt to replace the default entirely with your own instructions.

TypeScript

Python

Copy

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

const customPrompt = `You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices`;

const messages = [];

for await (const message of query({
  prompt: "Create a data processing pipeline",
  options: {
    systemPrompt: customPrompt,
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

​

Comparison of all four approaches

| Feature | CLAUDE.md | Output Styles | systemPrompt with append | Custom systemPrompt | | --- | --- | --- | --- | --- | | Persistence | Per-project file | Saved as files | Session only | Session only | | Reusability | Per-project | Across projects | Code duplication | Code duplication | | Management | On filesystem | CLI + files | In code | In code | | Default tools | Preserved | Preserved | Preserved | Lost (unless included) | | Built-in safety | Maintained | Maintained | Maintained | Must be added | | Environment context | Automatic | Automatic | Automatic | Must be provided | | Customization level | Additions only | Replace default | Additions only | Complete control | | Version control | With project | Yes | With code | With code | | Scope | Project-specific | User or project | Code session | Code session |

Note: “With append” means using systemPrompt: { type: "preset", preset: "claude_code", append: "..." } in TypeScript or system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} in Python.

​

Use cases and best practices

​

When to use CLAUDE.md

Best for:

• Project-specific coding standards and conventions
• Documenting project structure and architecture
• Listing common commands (build, test, deploy)
• Team-shared context that should be version controlled
• Instructions that apply to all SDK usage in a project

Examples:

• “All API endpoints should use async/await patterns”
• “Run npm run lint:fix before committing”
• “Database migrations are in the migrations/ directory”

Important: To load CLAUDE.md files, you must explicitly set settingSources: ['project'] (TypeScript) or setting_sources=["project"] (Python). The claude_code system prompt preset does NOT automatically load CLAUDE.md without this setting.

​

When to use output styles

Best for:

• Persistent behavior changes across sessions
• Team-shared configurations
• Specialized assistants (code reviewer, data scientist, DevOps)
• Complex prompt modifications that need versioning

Examples:

• Creating a dedicated SQL optimization assistant
• Building a security-focused code reviewer
• Developing a teaching assistant with specific pedagogy

​

When to use systemPrompt with append

Best for:

• Adding specific coding standards or preferences
• Customizing output formatting
• Adding domain-specific knowledge
• Modifying response verbosity
• Enhancing Claude Code’s default behavior without losing tool instructions

​

When to use custom systemPrompt

Best for:

• Complete control over Claude’s behavior
• Specialized single-session tasks
• Testing new prompt strategies
• Situations where default tools aren’t needed
• Building specialized agents with unique behavior

​

Combining approaches

You can combine these methods for maximum flexibility:

​

Example: Output style with session-specific additions

TypeScript

Python

Copy

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

// Assuming "Code Reviewer" output style is active (via /output-style)
// Add session-specific focus areas
const messages = [];

for await (const message of query({
  prompt: "Review this authentication module",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        For this review, prioritize:
        - OAuth 2.0 compliance
        - Token storage security
        - Session management
      `,
    },
  },
})) {
  messages.push(message);
}

​

See also

• Output styles
  • Complete output styles documentation
• TypeScript SDK guide
  • Complete SDK usage guide
• Configuration guide
  • General configuration options

Was this page helpful?

YesNo

Hosting the Agent SDK MCP in the SDK

Assistant

Responses are generated using AI and may contain mistakes.