Output styles - Claude Code Docs (original) (raw)

Output styles change how Claude responds, not what Claude knows. They modify the system prompt to set role, tone, and output format. Use one when you keep re-prompting for the same voice or format every turn, or when you want Claude to act as something other than a software engineer. A custom output style adds your instructions to the system prompt and lets you choose whether to keep Claude Code’s built-in software engineering instructions. Keep them when you’re changing how Claude communicates but still coding, like always answering with a diagram. Leave them out when Claude isn’t doing software engineering at all, like a writing assistant or data analyst. For instructions about your project, conventions, or codebase, use CLAUDE.md instead.

Built-in output styles

Claude Code’s Default output style is the existing system prompt, designed to help you complete software engineering tasks efficiently. There are three additional built-in output styles:

Change your output style

Run /config and select Output style to pick a style from a menu. Your selection is saved to .claude/settings.local.json at the local project level.

To set a style without the menu, edit the outputStyle field directly in a settings file:

{
  "outputStyle": "Explanatory"
}

Output style is part of the system prompt, which Claude Code reads once at session start. Changes take effect after /clear or a new session. See How Claude Code uses prompt caching for what an output style change does to the cache.

Create a custom output style

A custom output style is a Markdown file: frontmatter for metadata, then the instructions to add to the system prompt.

Plugins can also ship output styles in an output-styles/ directory.

Frontmatter

Output style files support these frontmatter fields:

Frontmatter Purpose Default
name Name of the output style, if not the file name Inherits from file name
description Description of the output style, shown in the /config picker None
keep-coding-instructions Keep Claude Code’s built-in software engineering instructions false
force-for-plugin Plugin output styles only: apply this style automatically whenever the plugin is enabled, without requiring users to select it. Overrides the user’s outputStyle setting. If multiple enabled plugins set this, Claude Code uses the first one loaded. false

How output styles work

Output styles directly modify Claude Code’s system prompt.

Token usage depends on the style. Adding instructions to the system prompt increases input tokens, though prompt caching reduces this cost after the first request in a session. The built-in Explanatory and Learning styles produce longer responses than Default by design, which increases output tokens. For custom styles, output token usage depends on what your instructions tell Claude to produce.

Several features customize how Claude Code behaves. Output styles modify the system prompt directly and apply to every response. The others add instructions without changing the default system prompt, or scope them to a specific task.

Feature How it works Use it when
Output styles Modifies the system prompt You want a different role, tone, or default response format every turn
CLAUDE.md Adds a user message after the system prompt Claude should always know your project conventions and codebase context
--append-system-prompt Appends to the system prompt without removing anything You want a one-off addition for a single invocation
Agents Runs a subagent with its own system prompt, model, and tools You want a separately scoped helper for a focused task
Skills Loads task-specific instructions when invoked or relevant You have a reusable workflow