Output Styles

Intermediate

What you'll learn

What an output style is — and how it differs from changing what Claude knows
The five built-in styles: Default, Proactive, Concise, Explanatory, Learning
How to switch styles with /config — and why the change needs a fresh session
How to author your own custom style as a Markdown file (including the plugin-only force-for-plugin field)
Why output styles apply to the main conversation but NOT to subagents — with fork as the one exception
When to reach for an output style vs CLAUDE.md vs --append-system-prompt vs Claude.ai custom instructions

Output styles change how Claude Code communicates — its role, tone, verbosity, and whether it explains its reasoning — by modifying the system prompt directly. They change how Claude responds, not what it knows. Reach for one when you keep re-prompting for the same voice or format every turn.

Why use them

Match your workflow. Terse and action-first when you're moving fast; explanatory when you're learning.
Teaching mode. Some styles add educational commentary — great while you're getting to know a codebase or a technique.
Consistency. Set a preferred style once so every session reads the way you like.

The built-in styles

Claude Code ships with five:

Style	What it does	Response length vs Default
Default	The standard software-engineering system prompt — efficient, action-first.	—
Proactive	Executes immediately and makes reasonable assumptions instead of pausing for routine decisions. Stronger autonomous-execution guidance than auto mode, but you still see permission prompts before tools run.	About the same
Concise	Leads with the result, skips preamble and narration, keeps responses short by default while doing the engineering work as thoroughly as Default. Ask for an explanation and Claude answers in full. Error reports, security warnings, and destructive-action confirmations stay complete regardless. Requires v2.1.237+.	Shorter
Explanatory	Adds educational "Insights" between steps, explaining implementation choices and codebase patterns.	Longer
Learning	Collaborative, learn-by-doing: shares Insights and asks you to write small pieces yourself, leaving `[TODO(human)]` markers in your code.	Longest

Watch out

Explanatory and Learning produce longer responses by design and cost more output tokens than Default.
Concise does the opposite — shorter answers by default — but it never trims error reports, security warnings, or destructive-action confirmations.

Press Enter or Space to flip the card. Use the left and right arrow keys to move between cards.Term shown.

1 / 5

How to switch

Run /config and pick a style under Output style. Your choice is saved to .claude/settings.local.json at the project level. To set it without the menu, edit the outputStyle field in any settings file.

Guided walkthrough1 of 4

Run /config in your session and find the Output style option.

{
  "outputStyle": "Explanatory"
}

:::warning Changes need a fresh session The output style is part of the system prompt, which Claude Code reads once at session start. A change takes effect only after /clear or a new session. (The standalone /output-style command was removed in v2.1.91 — use /config or the setting above.) :::

Where output styles do — and don't — apply

Output styles modify the main conversation's system prompt. That has a specific scope:

Subagents get their own system prompt, so they don't inherit your output style. If you spawn a Concise-styled Explainer agent, the subagent still uses its own instructions.
/fork is the one exception. A forked side-conversation copies the parent's full system prompt, so it does keep your style.
Custom styles drop the built-in coding instructions unless you set keep-coding-instructions: true. That's why a "pure writing assistant" style stops behaving like an engineer — and why a "diagrams first" style needs the flag to keep coding.

Create a custom style

A custom style is a Markdown file: frontmatter, then the instructions to append to the system prompt. Save it at one of three levels; the file name becomes the style name unless you set name:

User — ~/.claude/output-styles/
Project — .claude/output-styles/ (loads from every .claude/output-styles/ between your working directory and the repo root; when two levels define the same style name, the one closest to your working directory wins — great for monorepos where a package overrides the workspace default)
Managed policy — .claude/output-styles/ inside the managed settings directory

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

Example custom style — Diagrams first

---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true
---

When explaining code, architecture, or data flow, start with a Mermaid
diagram showing the structure, then explain in prose.

Pro tip

Set keep-coding-instructions: true when you're only changing HOW Claude communicates but still want it coding normally.
Leave it out (the default) when Claude isn't doing software engineering at all — say, a pure writing or data-analysis assistant — so the built-in coding instructions are dropped.

Frontmatter fields

Field	Purpose	Default
`name`	Style name if you don't want to inherit from the file name.	File name
`description`	Shown in the `/config` picker.	None
`keep-coding-instructions`	Keep Claude Code's built-in software-engineering instructions. Set `true` when you're only changing presentation.	`false`
`force-for-plugin`	Plugin styles only. Apply this style automatically whenever the plugin is enabled, overriding the user's `outputStyle` setting. If multiple enabled plugins set this, the first one loaded wins.	`false`

Watch out

force-for-plugin is powerful and easy to misuse — it silently overrides the user's chosen style. Ship it only when the plugin genuinely cannot work in Default (say, a full role change like 'act as a customer-support agent'), and document it prominently in the plugin's README.

Output styles vs CLAUDE.md vs other levers

Several features customise Claude Code's behaviour. Output styles modify the system prompt directly and apply to every response; the others add instructions elsewhere or scope them to one task.

Lever	How it works	Reach for it when
Output style	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	One-off addition for a single non-interactive invocation
Subagents	Runs a helper 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
Custom instructions	Claude.ai consumer-app cousin	You're customising the chat app, not the CLI

:::tip Use the right lever Want Claude to "always run tests before finishing"? That's a CLAUDE.md guardrail, not a style. Want it to "explain each step as you go"? That's an output style. Want to prepend a one-off system instruction for a single -p run? That's --append-system-prompt. Keep behaviour rules in CLAUDE.md and presentation in styles. :::

Check yourself

0/8

What does an output style actually change?
Which built-in style leaves [TODO(human)] markers and asks you to write small pieces yourself?
You want Claude to lead with the result and skip the usual preamble, but still take errors and destructive-action confirmations seriously. Which built-in style?
You set Concise, then spawn a subagent. What style is the subagent using?
After changing the output style, when does it take effect?
You want Claude to 'always run tests before finishing.' Which lever is that?
When should a plugin author set force-for-plugin: true on a bundled output style?
You have two project-level styles with the same name — one in the repo root's .claude/output-styles/ and one in a nested package's .claude/output-styles/. You run Claude Code from inside the nested package. Which wins?

Key takeaways

Output styles change HOW Claude communicates (role, tone, verbosity), not WHAT it knows — they edit the system prompt.
Five built-ins: Default (action-first), Proactive (executes with assumptions), Concise (short by default, v2.1.237+), Explanatory (Insights), Learning (Insights + [TODO(human)] markers).
Concise shortens responses but never trims error reports, security warnings, or destructive-action confirmations; Explanatory and Learning cost more output tokens because responses are longer.
Styles apply to the main conversation only — subagents use their own system prompt. /fork is the one exception because it copies the parent's full prompt.
Switch via /config (saved to .claude/settings.local.json) or the outputStyle setting — changes need /clear or a new session.
Custom styles are Markdown files with frontmatter (name, description, keep-coding-instructions, and plugin-only force-for-plugin). For nested project styles, the closest .claude/output-styles/ to your working directory wins.
Right lever for the job: CLAUDE.md for behaviour rules, output styles for presentation, --append-system-prompt for one-off invocations.

Why use them​

The built-in styles​

How to switch​

Where output styles do — and don't — apply​

Create a custom style​

Example custom style — Diagrams first

Frontmatter fields​

Output styles vs CLAUDE.md vs other levers​