Output styles change how Claude responds, not what Claude knows: they modify the system prompt to set role, tone, and output format while keeping the rest of Claude Code (file edits, scripts, TODO tracking) intact. Reach for one when you keep re-prompting for the same voice on every turn.
The three built-in styles
| Style | What it does | When to use |
|---|---|---|
| Default | Standard software-engineering system prompt: terse, code-first, minimal explanation. | Day-to-day coding; the assumption everywhere else on this site. |
| Explanatory | Adds educational “Insights” alongside Claude’s normal output: short notes about why a particular approach was chosen or what trade-offs are in play. Outputs are longer than Default. | Pairing with a teammate who needs to follow along; reviewing a session as a learning artifact. |
| Learning | Collaborative, learn-by-doing mode. Claude pauses for you to participate (write the next line, fill in the blank) instead of doing the whole task. | New developer learning a codebase; you want Claude to coach, not finish. |
The Default style has the existing system prompt; Explanatory and Learning add instructions to the end. Token usage rises with Explanatory and Learning because the output is more verbose by design.
Switch styles
Easiest path:
/configPick Output style in the menu. The selection saves to outputStyle in your settings.
Programmatic path (in ~/.claude/settings.json or <repo>/.claude/settings.json):
{
"outputStyle": "Explanatory"
}The style is set when the system prompt is built at session start. Switching mid-session via /config updates the setting but does not retroactively change the current session’s system prompt; restart for the new style to take effect.
Author a custom style
Custom styles are Markdown files with frontmatter. Project-scoped go in <repo>/.claude/output-styles/<name>.md; user-scoped go in ~/.claude/output-styles/<name>.md.
---
name: terse-engineer
description: "Terse, opinionated, no marketing softeners. For experienced devs."
keep-coding-instructions: true
---
You are a senior engineer reviewing a teammate's work. Reply in short paragraphs. Lead with the recommendation. Do not hedge. Do not include "let's" or "we'll explore". Use code where code communicates better than prose.The body of the file is appended to Claude Code’s default system prompt. With keep-coding-instructions: true, the coding-specific instructions stay; with false, they are excluded so your style takes over without “always reach for the Edit tool first” pulling in the opposite direction. Set false only when you genuinely want a non-coding role: a customer-support agent, a writing tutor, a recipe assistant. For coding-adjacent voice tweaks, leave it true.
After saving, your custom style appears in the /config Output style picker by its name (or filename if name is omitted) with the description shown alongside.
Plugins can ship styles
A plugin’s output-styles/ directory ships styles that become available when the plugin is enabled. A style can opt in to auto-apply by setting force-for-plugin: true in its frontmatter; that overrides the user’s outputStyle setting while the plugin is enabled. Useful for teams that distribute a “house voice” plugin; surprising for users who installed the plugin for a slash command and inherited a style they did not pick.
Footguns
Output styles do not override CLAUDE.md. The style edits the system-prompt scaffolding; CLAUDE.md (project, parent dirs, and user-level) is appended on top and still applies. A custom style that says “be terse” will not silence a CLAUDE.md that says “always explain your reasoning”. If the two conflict, the conflict reaches Claude verbatim and the response wobbles. Pick one source for voice (style) and keep CLAUDE.md for project facts (codebase notes, terminal commands, “use yarn not npm”).
keep-coding-instructions: false removes the parts that make Claude useful for code. Without the default instructions, Claude no longer reaches for Edit/Write tools by default, no longer tracks TODOs, no longer follows the explore-plan-code workflow. That is correct for a non-coding role; it is the wrong default for “I just want a different voice on coding work”. When in doubt, leave it true.
A plugin can hijack your output style. If a plugin ships a style and marks it auto-apply, enabling the plugin silently swaps outputStyle. Two months later you wonder why every reply is unusually verbose. Run /config and check what’s selected before blaming the model. The fix is to disable the plugin’s auto-apply or switch to a different style explicitly.
Output styles only affect the main agent loop. Subagents do not inherit the style by default; they get their own system prompt from their .claude/agents/ definition. A “be terse” style in the parent does not make a subagent’s report terse. If you need the same voice across surfaces, set both the style (parent) and the subagent’s prompt (child).
Mid-session /config changes do not take effect until restart. The system prompt is built once at session start; subsequent edits to outputStyle save to settings but the running session keeps its original prompt. If a style change must apply now, exit (Ctrl-D) and start a fresh session.
When NOT to use this
- You want a one-off tone. “Reply in bullet points” once is a per-prompt instruction, not a style. Styles earn their keep when the voice is repeated across many sessions.
- You want to add project facts. “We use Postgres 17, the API is in
src/api/” isCLAUDE.mdmaterial, not output-style material. Styles are for voice; memory is for facts. - You want to gate tool access. Style frontmatter does not control tools. Use permission rules and modes for that, not output styles.
- You are running a subagent. Subagents get their voice from their own definition file. Setting the parent’s output style does not propagate.
- You only run Claude in one place and the Default voice works. The other built-ins (Explanatory, Learning) and any custom styles you author are for specific roles. If Default already does what you need, do not introduce a style.