guide10 min read2mo ago

Claude Code Output Styles in 2026: The Complete Guide

The /output-style command was removed in v2.1.91, switching has been live since v2.1.251, and a style switch keeps your prompt cache. The full reference, checked against Anthropic's docs.

Claude Code Output Styles in 2026: The Complete Guide
claude codeoutput stylesclaude code output stylescustom output stylekeep-coding-instructionsclaude code settings

Key Takeaways
  • The /output-style command no longer exists. It was deprecated in v2.1.73 and removed in v2.1.91, so the instruction at the top of most guides fails silently.
  • Switching styles mid-session has applied from your next message since v2.1.251. Guides still telling you to run /clear are describing an older release.
  • A style switch is one of the few mid-session changes that keeps your prompt cache. Running /clear to "apply" it throws away the cache the switch preserved.
  • Custom styles silently drop Claude Code's software engineering instructions unless you set keep-coding-instructions: true. The default is false.
  • Five built-in styles, four frontmatter fields, three file locations, and one setting key: outputStyle.

5 built-ins · 4 frontmatter fields · 7 reference tables · every rule quoted from the docs

You read that Claude Code output styles let you stop re-prompting for the same tone every turn, typed /output-style, and got nothing back. The command was removed three minor versions after it was deprecated, which is why the first instruction in most write-ups on this topic is now dead on arrival. What replaced it is a /config menu and a single settings field, and the switching rules changed again underneath that in v2.1.251.

That second change is the one worth your attention, because the old advice is not merely stale, it is costly. Every guide I could reach still says a style change needs /clear or a fresh session to take effect. It does not, and /clear is exactly the wrong move: Anthropic's prompt-caching reference lists a style switch under the actions that keep your cache intact, while /clear discards it.

This is the reference that sorts it out: what the five built-ins actually do, the three ways to switch that still work, what a switch costs, how to write a custom style without accidentally lobotomising Claude's coding behaviour, and where styles stop reaching.

I checked every field name, file path, version number and cache behaviour here against Anthropic's own documentation rather than against other guides, which matters more than usual on a feature that has changed three times in two months.

A dark terminal window floating in space with several style preset cards fanned beside it in different accent colours and a glowing ribbon looping back into the terminal, representing a style change that keeps the cache
Five built-in styles, one terminal, and a switch that no longer costs you the session.

What Output Styles Actually Change

An output style changes the instructions Claude Code gives Claude. Not what Claude knows, not what it can reach, and not what it is allowed to run. The docs put it plainly: output styles "set Claude's role, tone, and output format for every response".

That distinction decides whether this is the feature you want. If you keep re-typing "stop explaining, just show me the diff", that is a style problem. If Claude keeps forgetting your project uses pnpm, that is a memory problem and belongs in CLAUDE.md.

FeatureHow it worksReach for it when
---------
Output stylesChanges Claude Code's default instructionsYou want a different role, tone or default format every turn
CLAUDE.mdAdds a user message after the system promptClaude should always know your project conventions
--append-system-promptAppends to the system prompt without removing anythingYou want a one-off addition passed at launch
AgentsRuns a subagent with its own system prompt, model and toolsYou want a separately scoped helper for a focused task
SkillsLoads task-specific instructions when invoked or relevantYou have a reusable workflow

The row that catches people is the first one. Output styles replace part of Claude Code's default instructions; the other four only add to them. That is why a custom style can quietly change how Claude scopes and verifies work, which the section on keep-coding-instructions below returns to. If you are still deciding which extension point fits your problem, our plugins vs skills vs MCP decision guide maps the same territory from the other direction.

The Five Built-In Output Styles

Default is the standard set of software engineering instructions. Four more ship with Claude Code, and they differ more than their names suggest.

StyleWhat Claude does differentlyRequires
---------
DefaultStandard software engineering instructionsAny version
ProactiveExecutes immediately, makes reasonable assumptions rather than pausing on routine decisions, prefers action over planningAny version
ConciseLeads with the result, skips preamble and narration, keeps responses short by defaultv2.1.237 or later
ExplanatoryAdds educational "Insights" while working, explaining implementation choices and codebase patternsAny version
LearningShares Insights and asks you to write small strategic pieces yourself, leaving TODO(human) markers in your codeAny version

Two of these carry caveats that matter in practice.

Proactive is not a permission mode. It is stronger autonomous-execution guidance than auto mode applies, and it works without changing your permission mode, which means your permission mode still decides what actually runs without asking you. Turning on Proactive does not widen what Claude may execute. It changes how readily Claude decides to try.

Concise does not abbreviate the things you need in full. The docs are specific: Claude keeps doing the engineering work as thoroughly as in Default, answers in full when you ask for an explanation, and always preserves the complete content of error reports, security warnings, and confirmations for destructive actions. It shortens narration, not safety output.

Explanatory and Learning are the two that cost you tokens, by design, because both produce longer responses than Default. Concise does the opposite.

Table of the five built-in Claude Code output styles with what each changes and the minimum version required, showing Concise needs v2.1.237 or later and the other four run on any version
Five styles. Only Concise carries a version floor.

The Claude Code documentation page headed Output styles, describing how a custom output style lets you choose whether to keep Claude Code's built-in software engineering instructions
Anthropic's own reference for output styles, read September 2026.

The Command Most Guides Still Tell You to Run

There is no /output-style command. It was deprecated in v2.1.73 and removed in v2.1.91. Three surfaces replace it, and all three write to the same place.

SurfaceHow you switchWhere it savesRequires
------------
Terminal/config, then select Output style.claude/settings.local.jsonAny current version
VS Code extensionOpen the command menu with /, select Output styles.claude/settings.local.jsonv2.1.257 or later
Desktop appSet the outputStyle field in a settings fileWherever you set itAny current version

The desktop app is the odd one out. Running /config there opens Settings > Claude Code rather than a picker, so editing the field directly is the path.

You can skip the menus entirely on any surface by setting the field yourself:

{
  "outputStyle": "Explanatory"
}

That is the whole API surface. One key, one string, and the value is the style name, which for a custom style is the file name unless you override it in frontmatter.

Table of the three surfaces where you can switch output style now that the slash command was removed: the terminal config picker, the VS Code command menu on v2.1.257 or later, and the desktop app settings field
The command was deprecated in v2.1.73 and removed in v2.1.91. These three surfaces are what is left.

Switching Is Live Now, and It Keeps Your Cache

Since v2.1.251, when you switch styles mid-session Claude uses the new style starting with your next message. Before that release, a mid-session switch applied only after you ran /clear or started a new session, which is the behaviour every guide I could reach still documents.

The reason the old advice is worth actively unlearning is what it costs. Claude Code delivers the new style's instructions as a message in the conversation, so the request after a switch still reads the system prompt and the earlier conversation from cache. A style switch sits on the docs' list of actions that keep the cache, alongside changing permission mode and invoking a skill.

Mid-session actionPrompt cache
------
Changing output styleKept
Changing permission modeKept
Invoking a skill or commandKept
Editing CLAUDE.mdKept, but the edit does not apply until /clear, /compact or restart
Switching modelsInvalidated, every model has its own cache
Changing effort levelInvalidated on most models
Running /compactConversation layer invalidated by design

Read those two lists together and the old instruction inverts. You were told to run /clear so the style would apply. The style already applies, and /clear is the thing that makes your next turn slower and more expensive by rebuilding a cache the switch had left alone.

The practical version: switch whenever the task changes. Flip to Explanatory when you hit unfamiliar code, back to Concise when you are grinding through a known refactor, and stop treating it as a decision you have to make at session start.

Table of seven mid-session actions against whether each keeps or invalidates the prompt cache, showing a style change, a permission mode change and a skill invocation all kept, while switching models or running compact is invalidated
Changing output style is on the keeps-the-cache side. That is what makes clearing the session the expensive move.

Switching a Style and Editing One Are Different Operations

This is the distinction that produces the "I changed it and nothing happened" reports, and neither guide currently ranking for this query separates the two.

Switching between styles that are already loaded takes effect on your next message. Creating or editing a style file does not, at least in the terminal, because Claude Code reads style files when it starts. Edit ~/.claude/output-styles/reviewer.md mid-session and Claude keeps using the version loaded at launch.

The two-minute diagnosis
Style picker shows your style but behaviour is unchanged? You edited the file this session. Restart Claude Code. Style is not in the picker at all? The file is in the wrong directory, or you are in a session that started before you created it. Behaviour changed but Claude stopped following your usual engineering conventions? You wrote a custom style without keep-coding-instructions.

That third case is the expensive one, and it has its own section below.

Writing a Custom Output Style

A custom output style is a Markdown file: frontmatter for metadata, then the instructions. Save it at one of three levels.

LevelPathScope
---------
User~/.claude/output-stylesAll your projects
Project.claude/output-stylesAnyone working in this repo
Managed policy.claude/output-styles inside the managed settings directoryEveryone in the organisation

The file name becomes the style name unless you set name in frontmatter. Four fields are supported, and the defaults matter more than the fields.

FrontmatterPurposeDefault
---------
nameStyle name, if not the file nameInherits from file name
descriptionShown in the /config pickerNone
keep-coding-instructionsKeep Claude Code's built-in software engineering instructionsfalse
force-for-pluginPlugin styles only: apply automatically whenever the plugin is enabledfalse

keep-coding-instructions defaults to false, and that is the single biggest trap in this feature. A custom style leaves out Claude Code's built-in software engineering instructions unless you opt back in, and those instructions are not decoration: they cover how Claude scopes changes, writes comments, and verifies its work. Write a style that only says "always answer with a diagram first", omit the field, and you have also removed the guidance that made Claude check its work.

The rule is simple. Still coding, just communicating differently? Set it to true. Not doing software engineering at all, such as a writing assistant or data analyst? Leave it out.

---
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.

Table of the three scopes a custom output style can live in, user, project and managed policy, followed by the four frontmatter fields name, description, keep-coding-instructions and force-for-plugin with their defaults
Three scopes, four frontmatter fields, and one default worth changing.

The Claude Code documentation page headed Settings files and precedence, explaining which settings file wins when a key is set in several places
Precedence is a settings question, which is where a style set in more than one place is resolved.

If that frontmatter block looks familiar, it is the same shape skills and commands use, and the full slash commands reference covers the twenty fields their version supports.

Precedence, Nesting and Plugin Overrides

Project output styles load from every .claude/output-styles/ directory between your working directory and the repository root. When two of those define a style with the same name, the one closest to the working directory wins. In a monorepo that means a style in apps/web/.claude/output-styles/ beats the root copy for sessions working inside apps/web, which is usually what you want and occasionally a surprise.

Plugins can ship styles too, in an output-styles/ directory. One field makes them behave unlike anything else here: force-for-plugin applies the style automatically whenever the plugin is enabled, without the user selecting it, and it overrides the user's outputStyle setting. If more than one enabled plugin sets it, the first one loaded wins.

That is worth knowing before you debug someone's configuration. If a teammate's Claude is behaving unlike yours on the same repo with the same settings file, an enabled plugin forcing a style is a candidate that no settings diff will show you. Our roundup of the best Claude Code plugins covers what else a bundle can carry.

Where Output Styles Reach, and Where They Stop

An output style applies to the main conversation and to a fork, which inherits the parent's full conversation and system prompt. It does not apply to other subagents, because those run their own system prompt.

This catches people delegating work. Set Concise, hand a task to a subagent, and the subagent's output is not concise, because your style never reached it. If you want a subagent to behave a particular way, that belongs in the agent's own definition, and our guide to the best Claude subagents shows how those are configured.

Two more details on how styles reach Claude. The active style's instructions go out with every request, and when you select any style other than Default, Claude Code also reminds Claude of the style during the conversation. Both cost input tokens, though prompt caching absorbs most of that after the first request in a session.

Output token cost varies by style rather than by the instructions' length. Explanatory and Learning produce longer responses than Default by design. Concise produces shorter ones. For a custom style, whatever your instructions tell Claude to produce is what you pay for.

Which Style to Actually Use

Most people should not stay on one. The switch is cheap and live, so match it to the task in front of you.

SituationStyleWhy
---------
Grinding through a refactor you already understandConciseNarration is pure overhead when you know the plan
Reading unfamiliar code or debugging something subtleExplanatoryThe Insights are the point, and you want the audit trail
Learning a codebase or a languageLearningTODO(human) markers force the retention that reading does not
Long autonomous runs on work you have scopedProactiveFewer stops on routine decisions, permissions unchanged
Anything where you are unsureDefaultIt is the tuned baseline, not a fallback

The one combination to avoid is a custom style without keep-coding-instructions for actual engineering work. Everything else here is reversible in one message.

Skip the blank file
A custom style is a prompt, and prompts are easier to edit than to start. Skiln indexes installable Claude skills, commands, agents and MCP servers with their real install paths, so you can begin from frontmatter that already parses. Browse skills · Browse commands · Generate a config
Disclosure: Skiln publishes this article and runs the directory it links to.

Every field, path, version number and default above comes from Anthropic's output styles reference. The cache behaviour is from how Claude Code uses prompt caching, which lists a style switch among the actions that keep the cache, with the underlying mechanism documented in the Claude API prompt caching reference, and the subagent boundary is from the subagents reference. For the working habits these styles are meant to support, Anthropic's Claude Code best practices is the companion piece. Where a version number here disagrees with another guide, the release notes are what the product enforces.

Frequently Asked Questions

Why does /output-style not work in Claude Code?▾
Because the command no longer exists. It was deprecated in v2.1.73 and removed in v2.1.91. Use /config and select Output style in the terminal, the Output styles entry in the VS Code command menu, or set the outputStyle field directly in a settings file such as .claude/settings.local.json. All three write the same setting.
Do I need to run /clear for an output style change to take effect?▾
No, not since v2.1.251. Claude uses the new style starting with your next message. That was the rule before v2.1.251, which is why most guides still say it, but running /clear now costs you: a style switch keeps your prompt cache intact, and /clear rebuilds it, so the advice makes your next turn slower and more expensive for no benefit.
Does changing output style invalidate the prompt cache?▾
No. Claude Code delivers the new style's instructions as a message in the conversation, so the request after a switch still reads the system prompt and the earlier conversation from cache. The documentation lists changing output style under actions that keep the cache, alongside changing permission mode and invoking a skill. Switching models or effort level is what invalidates it.
What does keep-coding-instructions do, and should I set it?▾
It keeps Claude Code's built-in software engineering instructions, which cover how Claude scopes changes, writes comments and verifies work. It defaults to false, so a custom style drops them unless you opt back in. Set it to true whenever Claude is still writing code and you are only changing how it communicates. Leave it out only when the style is for non-engineering work such as writing or data analysis.
Where do custom output style files go?▾
Three levels: ~/.claude/output-styles for your user account, .claude/output-styles for a project, and .claude/output-styles inside the managed settings directory for an organisation. The file name becomes the style name unless you set name in the frontmatter. Project styles load from every such directory between your working directory and the repository root, and on a name clash the one closest to the working directory wins.
I edited my output style file and nothing changed. Why?▾
Switching between styles applies immediately, but style files themselves are read when Claude Code starts. If you create or edit a style file during a running terminal session, restart Claude Code to pick up the change. These are two different operations that most guides describe as one.
Do output styles apply to subagents?▾
Only to forks. A fork inherits the parent's full conversation and system prompt, so your style carries over. Other subagents run their own system prompt, so a style set in the main conversation does not change how they respond. If you need a subagent to behave a certain way, put it in that agent's own definition.

Stay in the Loop

Join 1,000+ developers. Get the best new Skills & MCPs weekly.

No spam. Unsubscribe anytime.