Output styles are the setting most Claude Code users have used without knowing its name. If you’ve ever gotten the “Insights” sidebar explaining a design choice mid-task, or watched Claude drop TODO(human) markers into a file and wait for you to fill them in, you’ve already used two of the four built-in output styles. This guide covers what they actually change, all four built-in options, how to build a custom one, and a piece of the feature’s history that’s worth knowing before you rely on it: Anthropic deprecated the entire feature on October 31, 2025, and reversed the decision four days later after users said the alternatives didn’t work.
Everything below is sourced from the official docs at code.claude.com/docs/en/output-styles and the related prompt-caching and permission-modes pages, current as of Claude Code v2.1.226 (August 2026).
What an output style actually changes
An output style modifies Claude Code’s system prompt — the fixed instructions sent with every request that set role, tone, and response format. It does not change what Claude knows about your codebase, and it isn’t the right tool for project-specific instructions.
That distinction trips people up because both features feel like “customize how Claude behaves”:
- Output style changes how Claude communicates and what kind of agent it is — a coding agent, a writing assistant, a data analyst. It’s read once at session start and applies to every response.
- CLAUDE.md adds a message describing your project — conventions, architecture, commands to run. It’s appended as a user message, not baked into the system prompt.
If you keep re-explaining the same voice or format every session, that’s an output style problem. If you keep re-explaining the same codebase facts, that’s a CLAUDE.md problem. Most setups need both, doing different jobs.
The four built-in styles
| Style | What it does | Best for |
|---|---|---|
| Default | Claude Code’s normal system prompt — efficient, minimal narration, optimized for finishing engineering tasks | Everyday coding work |
| Proactive | Executes immediately, makes reasonable assumptions instead of pausing for routine decisions, prefers action over planning | Fast iteration where you trust Claude’s judgment on small calls |
| Explanatory | Adds educational “Insights” between steps, explaining implementation choices and codebase patterns as it works | Understanding a new codebase, or learning why Claude made a specific choice |
| Learning | Collaborative, learn-by-doing mode — shares Insights and asks you to write small, strategic pieces of code yourself via TODO(human) markers | Pairing with Claude to actually practice writing code, not just review it |
The one worth a second look is Proactive, because it’s easy to confuse with auto mode — they sound like the same idea and Anthropic’s own docs call out the distinction explicitly. Auto mode is a permission mode: it changes whether Claude prompts you before running tools, using background safety checks to auto-approve. Proactive is an output style: it changes Claude’s default posture toward ambiguous decisions — skip the “should I do X or Y?” pause and just pick one — but it does this without touching your permission mode. Run Proactive under the default permission mode and you’ll still see prompts before tool calls; you get faster decision-making, not fewer approvals. Combine Proactive with auto mode if you want both.
Switching styles today
Run /config and select Output style from the menu. Your selection is saved to .claude/settings.local.json at the project level.
To set one without the menu, edit the outputStyle field directly in a settings file:
{
"outputStyle": "Explanatory"
}If you’ve seen /output-style mentioned as the command to use — in older blog posts, in cached documentation, or in a colleague’s muscle memory — it’s out of date. The standalone /output-style command was deprecated in v2.1.73 and fully removed in v2.1.91. /config is the only interactive path now. A number of third-party guides, and even some archived Anthropic doc mirrors, still describe /output-style:new for AI-assisted style creation; that subcommand doesn’t appear anywhere in the current official docs, so treat any guide that leads with it as stale.
One more thing worth knowing before you switch mid-task: changing your style does not apply immediately. Output style is read once at session start and held for the rest of the session — the change loads on your next /clear or new session, not the next message. See Token usage and prompt caching below for why.
The four-day reversal: a short version history
Output styles have a rockier history than most Claude Code features, and it’s directly relevant to how much you should build around them.
| Date / version | What happened |
|---|---|
| Oct 31, 2025 (v2.0.30) | Anthropic deprecated the entire output styles feature, pointing users to CLAUDE.md and plugins instead |
| Within hours | Multiple GitHub issues filed, several tagged “Critical — Blocking my work.” The core complaint: CLAUDE.md and hooks don’t replicate a system-prompt-level override — hook-injected instructions “lose their power after several rounds,” in one user’s words |
| Nov 4, 2025 (v2.0.32) | Anthropic reversed the deprecation. The changelog entry: “Un-deprecate output styles based on community feedback” |
| v2.1.73 | A narrower, later change: the standalone /output-style command (not the feature) was deprecated in favor of /config |
| v2.1.91 | /output-style command removed entirely |
| v2.1.178 | Nested-directory precedence rule added: when more than one .claude/output-styles/ directory between your working directory and the repo root defines a style with the same name, the one closest to the working directory wins |
The lesson isn’t “this feature is unstable” — it’s the opposite. The reversal happened because teams had built output styles into production workflows for business analysis, content creation, and research use cases well outside coding, and the suggested replacements genuinely didn’t cover those cases. That’s a stronger signal of staying power than a feature nobody complained about would give you. The part that actually changed since then is narrower: how you invoke the picker, not what the feature does.
Creating a custom output style
A custom output style is a Markdown file: YAML frontmatter for metadata, then the instructions appended to the system prompt.
1. Create the file. Save it at one of three levels — the file name becomes the style name unless you set name in frontmatter:
- User level:
~/.claude/output-styles/ - Project level:
.claude/output-styles/ - Managed policy:
.claude/output-styles/inside the managed settings directory
2. Decide whether to keep Claude’s coding instructions. This is the frontmatter field that matters most and the one competing guides tend to skip:
| Frontmatter field | Purpose | Default |
|---|---|---|
name | Style name shown in the /config picker, if different from the file name | Inherits file name |
description | Shown next to the name in the picker | None |
keep-coding-instructions | Keep Claude Code’s built-in software engineering instructions (scoping changes, comment conventions, verification) | false |
force-for-plugin | Plugin styles only — apply automatically whenever the plugin is enabled, overriding the user’s setting | false |
Set keep-coding-instructions: true when you’re changing how Claude communicates but it’s still coding — always leading with a diagram, for example. Leave it unset (or false) when Claude isn’t doing software engineering at all, like a writing assistant or a data analyst persona — in that case you want Claude’s built-in scoping/comment/verification instructions gone, not layered under a new persona.
Example 1 — still coding, changed communication style:
---
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.Example 2 — not coding at all:
---
name: Data analyst
description: SQL-first data analysis, no code review framing
---
You are a data analyst helping interpret datasets and write
queries. You are not reviewing or shipping production code, so
skip commentary about test coverage, code style, or PR scoping.
Lead every answer with the SQL or the number, then explain the
reasoning. Flag when a result depends on an assumption about the
schema you haven't verified.3. Switch to it. /config → Output style → pick your file. It takes effect after /clear or your next session.
Anthropic’s own guidance for AI-assisted creation used to route through /output-style:new [description]. That command no longer appears in the current docs (see the switching section above) — write the file by hand, or ask Claude Code to draft one for you in a normal conversation and save the result yourself.
File locations and precedence
Project output styles load from every .claude/output-styles/ directory between your current working directory and the repository root — not just the repo root. This matters for monorepos where a subdirectory wants its own style without touching the shared one.
As of v2.1.178, if more than one of those directories defines a style with the same name, Claude Code uses the definition closest to your working directory. A team can keep a baseline style at the repo root and let individual service directories override it by name, without renaming anything.
Plugins can also ship output styles, in an output-styles/ directory alongside their skills, hooks, and agents — see our rules gallery for real examples of how teams structure .claude/ directories, including plugin layouts.
Output styles vs. subagents and forks
Output styles apply to the main conversation only. This surprises people who assume a style change propagates everywhere:
- A subagent runs its own system prompt from scratch — your output style doesn’t carry over. If you need a subagent to communicate a certain way, that instruction has to live in the subagent’s own definition.
- A fork (
claude --fork, or forking from within a session) is the exception — it inherits the parent conversation’s full system prompt, including whatever output style was active, because a fork is a continuation of the same context rather than a fresh agent.
Token usage and prompt caching
Output style lives in the system prompt layer of Claude Code’s cache — the same layer as core instructions and tool definitions, which sits ahead of your project context (CLAUDE.md, memory) and your actual conversation. Claude Code’s cache works on a strict prefix match: everything after the first point of change gets reprocessed.
Two consequences fall out of that directly:
- Token cost scales with the style. Adding custom instructions increases input tokens (mitigated by caching after the first request in a session). Explanatory and Learning are verbose by design — more Insights, more back-and-forth — so they cost more in output tokens than Default independent of caching.
- Changing style mid-session doesn’t invalidate the cache — and doesn’t apply either. Because output style is fixed at session start, a mid-session change to it via
/configor theoutputStylesetting leaves the cached prefix untouched, but Claude also keeps using whichever style was active when the session started. The new style loads only after/clearor a fresh session — not the next message, and not/compact(which rebuilds the conversation layer, not the system prompt layer).
If you’re switching styles for a specific task, do it before you start rather than partway through — otherwise you’ll get the response format you expected two turns later than you expected it.
Output styles vs. everything else that changes how Claude behaves
Several Claude Code features overlap conceptually. This is the full picture, output styles included:
| Feature | How it works | Use it when |
|---|---|---|
| Output styles | Modifies the system prompt directly | 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 | A one-off addition for a single invocation, not a persistent style |
| Agents/subagents | Runs a separate conversation with its own system prompt, model, and tools | A separately scoped helper for a focused task, not a change to the main conversation |
| Skills | Loads task-specific instructions when invoked or relevant, appended as a message | A reusable workflow triggered by context, not a standing tone change |
| statusLine | Renders a persistent status bar from a script — doesn’t touch the system prompt or consume tokens | You want to see session state (cost, branch, context usage), not change how Claude responds |
The comparison people get wrong most often is output styles vs. statusLine, because both live under /config and both sound like “customize the UI.” They don’t overlap at all: statusLine is a read-only display fed by JSON on stdin; output style is prompt instructions that change what Claude generates. You can run a custom statusline and a custom output style at the same time with zero interaction between them.
Troubleshooting
I changed my output style and nothing changed. Expected — see Token usage and prompt caching. Run /clear or start a new session.
/output-style doesn’t exist as a command anymore. Correct as of v2.1.91. Use /config → Output style, or edit outputStyle in a settings file directly.
My custom style isn’t showing up in the /config picker. Check the file is actually in ~/.claude/output-styles/ or .claude/output-styles/ (not a random subdirectory that isn’t between your cwd and the repo root), and that the frontmatter parses — a malformed YAML block silently drops the style rather than erroring loudly.
Two directories define a style with the same name and I’m not sure which one wins. As of v2.1.178, the one closest to your working directory wins. Rename one if you need both available at once.
A subagent isn’t following my output style. It won’t — subagents run their own system prompt. Put the instruction in the subagent’s own definition instead.
FAQ
What’s the difference between output styles and CLAUDE.md? Output styles change the system prompt itself — role, tone, response format, applied to every turn. CLAUDE.md is appended as a user message describing your project’s conventions and context. Use output styles for “how Claude talks,” CLAUDE.md for “what Claude knows about this codebase.”
Does changing output style apply immediately?
No. It’s read once at session start. A mid-session change via /config takes effect after /clear or a new session, not the next message.
Is /output-style still a valid command?
No — deprecated in v2.1.73, removed in v2.1.91. Use /config and select Output style, or set the outputStyle field in a settings file.
Can a plugin ship an output style?
Yes, in an output-styles/ directory alongside the plugin’s skills, hooks, and agents. The force-for-plugin frontmatter field can apply it automatically whenever the plugin is enabled.
Does output style affect subagents? No. A subagent builds its own system prompt from scratch. A fork is the one exception — it inherits the parent’s full system prompt, output style included.
Were output styles ever removed as a feature entirely?
Briefly. Anthropic deprecated the whole feature on October 31, 2025 (v2.0.30) and reversed the decision four days later, on November 4, 2025 (v2.0.32), after user feedback showed the suggested alternatives — CLAUDE.md, hooks, plugins — didn’t replicate what a system-prompt-level override does. What did later get removed was narrower: the standalone /output-style command, in favor of /config.
Related Reading
- Claude Code Permission Modes and Rule Syntax: Complete Guide
- Claude Code Statusline: The Complete Guide to Custom Status Bars and JSON Fields
- Claude Code Subagents: Complete Reference
- How to Write Claude Code Skills
- CLAUDE.md: The Complete Guide
Browse how real teams configure Claude Code’s permissions, hooks, and output styles in our rules gallery.
Source: code.claude.com/docs/en/output-styles, plus the prompt-caching and permission-modes pages it cross-references — official Anthropic documentation, current as of Claude Code v2.1.226 (August 2026).