Changing how Claude talks, not what it knows
Most Claude Code customisation is about giving Claude more to work with, project facts in CLAUDE.md, reusable procedures in a skill, specialised helpers as subagents. Output styles do something different: they change how Claude communicates, its role, tone and response format, by directly rewriting the system prompt for the rest of the session. Reach for one when you find yourself re-prompting for the same voice or format every turn, or when you want Claude acting as something other than a software engineer entirely.
The five built-in styles
Claude Code's Default style is the ordinary system prompt: helping you complete software engineering tasks efficiently, with no extra commentary layered on. Four additional built-in styles sit alongside it, the newest added this week.
Proactive. Claude executes immediately, makes reasonable assumptions instead of pausing for routine decisions, and prefers action over planning. This is stronger autonomous-execution guidance than auto mode applies on its own, and importantly it works independently of your permission mode: switching to Proactive doesn't change what Claude is allowed to run without asking, only how readily it moves once something is already approved.
Explanatory. Adds educational "Insights" alongside the normal work of completing a task, aimed at helping you understand implementation choices and codebase patterns as Claude makes them, rather than just seeing the diff land.
Learning. A collaborative, learn-by-doing mode. Claude shares the same "Insights" as Explanatory, but also asks you to contribute small, strategic pieces of code yourself, marking spots with TODO(human) for you to fill in rather than writing everything itself.
Concise, added in Claude Code v2.1.237 on 20 August 2026. Claude leads with results and skips preamble and narration, while doing the work just as thoroughly as it would under any other style. The distinction Anthropic draws is specific: Concise isn't a shortcut that does less, it's the same underlying work with less commentary wrapped around it. If Explanatory and Learning add words, Concise is the style built to remove them.
| Style | What it changes | Good for |
|---|---|---|
| Default | Nothing, standard system prompt | General software engineering work |
| Proactive | Executes on reasonable assumptions instead of pausing | Fast iteration where you trust Claude's judgement on routine calls |
| Explanatory | Adds "Insights" alongside normal task completion | Learning a new codebase or unfamiliar pattern |
| Learning | Adds "Insights" plus TODO(human) markers for you to fill in | Deliberately practising by writing some of the code yourself |
| Concise | Leads with results, skips preamble and narration | Experienced users who find the normal commentary redundant |
How to switch styles
Terminal: run /config, select Output style, and pick from the menu. Claude Code saves your choice to .claude/settings.local.json, the same local project settings file the /skills menu writes to for skillOverrides.
Desktop app: set the outputStyle field directly in a settings file, since the desktop app's /config opens Settings > Claude Code rather than the terminal's picker menu.
To skip the menu entirely and set a style by hand:
{
"outputStyle": "Concise"
}
One thing worth knowing if you're following an older guide: the standalone /output-style command was deprecated in v2.1.73 and removed in v2.1.91. Use /config or edit the outputStyle field directly instead; the old command no longer exists.
A style change takes effect after /clear or in a new session, not mid-conversation, because output style is part of the system prompt, which Claude Code reads once at session start.
Writing your own output style
A custom output style is a Markdown file: YAML frontmatter for metadata, then the instructions to append to the system prompt. Save it at one of three levels, and the file name becomes the style's name unless you set one explicitly in frontmatter:
~/.claude/output-styles/ # user level, applies everywhere
.claude/output-styles/ # project level
<managed-settings-dir>/.claude/output-styles/ # managed policy level
Project-level styles load from every .claude/output-styles/ directory between your working directory and the repository root; if more than one defines a style with the same name, the one closest to your working directory wins.
Here's a minimal example that keeps Claude coding normally but always leads with a diagram:
---
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.
## Diagram conventions
Use `flowchart TD` for control flow and `sequenceDiagram` for request paths.
Keep diagrams under 15 nodes.
The frontmatter fields:
| Field | Purpose | Default |
|---|---|---|
name | Style name, if different from the file name | Inherits from file name |
description | Shown in the /config picker | None |
keep-coding-instructions | Keeps Claude Code's built-in software engineering instructions (scoping changes, comment conventions, verification) alongside your added text | false |
force-for-plugin | Plugin styles only: applies automatically whenever the plugin is enabled, overriding the user's own outputStyle choice | false |
The keep-coding-instructions decision is the one that matters most when writing your own. Set it true when you're changing Claude's tone or format but it's still doing software engineering, always answering with a diagram, always writing a specific commit message shape. Leave it out, or set it false, when Claude isn't coding at all under this style, a writing assistant, a data-analysis helper, anything where the built-in engineering instructions (how to scope a change, how to verify work) would just be noise.
Plugins can also ship output styles, in an output-styles/ directory alongside whatever else the plugin bundles.
What actually happens under the hood
Claude Code appends each style's custom instructions to the end of the system prompt, and every style triggers reminders for Claude to keep following those instructions through the conversation, not just at the first turn. A custom style leaves out Claude Code's built-in software engineering instructions by default, unless keep-coding-instructions: true overrides that.
Token cost follows directly from that mechanism: adding instructions to the system prompt increases input tokens, though prompt caching absorbs most of that cost after the first request in a session. The built-in Explanatory and Learning styles also produce longer responses by design, which increases output tokens on top of the input-side cost. Concise is the mirror case, its whole purpose is trimming output tokens by cutting preamble and narration, without changing how much actual work goes into producing the result.
Output styles apply to the main conversation only. A subagent runs its own system prompt, so a style you've selected doesn't carry over to it. A forked subagent is the one exception, since a fork inherits the parent's full system prompt, style included, because it's a continuation of the same conversation rather than a separately scoped helper starting fresh.
Output styles vs everything else that customises Claude
Several Claude Code features change behaviour in overlapping-sounding ways. Here's where output styles sit relative to the others:
| Feature | How it works | Use it when |
|---|---|---|
| Output styles | Modifies the system prompt, applies to every response | You want a different role, tone or default format for the whole session |
| CLAUDE.md | Adds a user message after the system prompt | Claude should always know your project's conventions or codebase context |
--append-system-prompt | Appends to the system prompt without removing anything | A one-off addition for a single invocation, not a saved style |
| Agents/subagents | Runs a subagent with its own system prompt, model and tools | A separately scoped helper for one focused task |
| Skills | Loads task-specific instructions only when invoked or matched | A reusable procedure that applies sometimes, not on every turn |
The practical rule: if what you want changes on every response for the rest of the session regardless of task, that's an output style. If it's project knowledge Claude should always have, that's CLAUDE.md. If it only applies to specific requests, that's a skill.
Proactive vs auto mode, a distinction worth being precise about
These two are easy to conflate because both push Claude toward acting without pausing, but they operate on different layers entirely. Auto mode is a permission-mode decision: it changes what Claude is allowed to run without asking you for approval, using a classifier to decide which actions are safe to auto-approve. The Proactive output style doesn't touch permissions at all. It changes Claude's default posture toward ambiguity within whatever's already approved, making reasonable assumptions and moving forward on routine decisions rather than stopping to check in, even in a session where auto mode is off and every command still needs your explicit approval.
The two compose rather than compete. Running Proactive without auto mode still means Claude asks before anything your permission settings would normally gate; it just asks less often about small in-between decisions that don't touch permissions at all, like which of two equally reasonable implementations to pick. Running auto mode without Proactive means fewer permission prompts, but Claude's default communication style is unchanged, it may still pause to lay out options for a genuinely ambiguous non-permission decision rather than picking one and moving on. Combining both gives you the least friction of any built-in configuration, at the cost of the most implicit decision-making happening on your behalf.
Why Concise exists
The other three added styles, Proactive, Explanatory and Learning, all add something: more autonomy, more teaching commentary, more collaborative structure. Concise is the first built-in style whose entire purpose is subtraction. Anthropic's framing in the changelog draws a specific line: Concise does the work "just as thoroughly" as any other style, only the narration around it shrinks. That's a deliberate distinction worth taking at face value rather than assuming "concise" means "faster" or "less careful." A user who wants terser communication without a corresponding drop in how much verification or care goes into the actual task now has a built-in option for that, rather than having to write a custom style or repeatedly ask Claude to "be brief" every session.
Troubleshooting
A style change doesn't seem to have taken effect. Output styles apply after /clear or a new session, not mid-conversation, since the system prompt is read once at session start. Clear or restart the session after switching.
Concise doesn't appear as an option. Confirm you're on Claude Code v2.1.237 or later, since it was only added in that release, dated 20 August 2026. Run /update if you're on an older version.
A custom style isn't picked up. Check the file lives in one of the three recognised directories (~/.claude/output-styles/, .claude/output-styles/, or the managed policy equivalent) and that its frontmatter parses; a malformed YAML block will silently keep it from appearing in the /config picker. code.claude.com/docs/en/debug-your-config covers diagnosing configuration that isn't taking effect.
Two project-level styles share a name and only one applies. This is expected when nested .claude/output-styles/ directories both define the same name between your working directory and the repository root; the one closest to your working directory takes precedence.
You want the built-in coding instructions plus a custom voice. Set keep-coding-instructions: true in your custom style's frontmatter. Without it, your style replaces Claude Code's engineering instructions rather than adding to them.
Where to go next
For how Proactive compares to auto mode specifically, see Claude Code's auto mode, now the default. For the settings file outputStyle shares with skill visibility controls, see Claude Code's skillOverrides setting explained. For when a fork inherits a style versus a fresh subagent starting its own system prompt, see how Claude Code's subagent forking works. Browse the current catalogue at getclaudeskills.com/platforms/claude-code.
Verified directly against Claude Code's own output styles documentation and the v2.1.237 changelog entry dated 20 August 2026.
