Claude Code Output Styles: Concise, Custom and Cost

An output style in Claude Code is a set of instructions that sets Claude's role, tone and response format for every response in a session. You pick one with /output-style, and you can write your own as a Markdown file. If your agent talks too much, explains too little, or keeps stopping to ask routine questions, an output style is the first thing to try.

This guide covers the four built-in styles, how to switch, how to write a custom one, what a style does to token use and the prompt cache, and where a style is the wrong tool. It follows the Claude Code documentation; version requirements are noted where the docs give them.

What is a Claude Code output style?

Claude Code starts in the Default style: no style instructions, just its standard system prompt, which is written for software engineering tasks. Each of the four other built-in styles keeps those standard instructions and adds its own. Claude Code sends the active style's instructions with every request, so you do not repeat "keep it short" or "explain your reasoning" in each prompt.

One point to hold on to: a style gives Claude instructions to follow. It does not guarantee that something always or never happens. That shapes when to use it, covered below.

What are the built-in output styles?

Details worth knowing:

• Proactive starts implementing as soon as you send a task and does not switch to plan mode unless you ask for a plan. It does not change your permission mode, so permission prompts appear exactly as before. Its instructions also tell Claude to check with you in the conversation before deleting data or changing a shared or production system; the docs say that check is an instruction Claude follows and is separate from permission prompts.
• Concise states the result in the first sentence and answers a simple question in one to three sentences. It does the engineering work as thoroughly as Default. Explanations you ask for, error reports, failing test output, security warnings and confirmations for destructive actions keep their full content. It requires Claude Code v2.1.237 or later.
• Explanatory writes its Insight blocks in the conversation, not into your files as comments. Each block carries two or three points.
• Learning marks a spot with a TODO(human) comment, sends a request saying what is built and what to write, then stops and waits until you tell it you are done.

How do I switch output style?

The /output-style command and the /config menu both save your choice to .claude/settings.local.json at the local project level:

/output-style concise
/output-style            # no argument: list styles, mark the current one
/config                  # then pick "Output style" from the menu

Or set it directly in a settings file:

{
  "outputStyle": "Explanatory"
}

The value in a settings file is case-sensitive. Write Proactive, Concise, Explanatory or Learning; a value that does not match exactly, such as explanatory, gives you the Default style. The /output-style command ignores case.

To make a style your default across projects, set outputStyle in ~/.claude/settings.json. A project's own settings files take precedence over that value.

Other surfaces:

• /output-style also works in non-interactive mode and Agent SDK sessions, and from the mobile app or web through Remote Control, where only built-in styles can be listed and selected. This requires v2.1.269 or later.
• The VS Code extension has an Output styles entry in its command menu, which includes your custom styles (v2.1.257 or later). From v2.1.261 you can also create a style file from that menu.
• In the desktop app, set the outputStyle field in a settings file; /config there opens the app's settings instead of a menu.

A mid-session switch applies from your next message. Before v2.1.251 it applied only after /clear or a new session.

How do I write a custom output style?

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

• User: ~/.claude/output-styles
• Project: .claude/output-styles
• Managed policy: .claude/output-styles inside the managed settings directory

Project styles load from every .claude/output-styles/ between the working directory and the repository root. If two define the same name, the one closest to the working directory wins. The file name becomes the style name unless you set name.

Here is the docs' example, which leads every explanation with a diagram while keeping Claude's coding behaviour:

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

All frontmatter fields are optional:

The keep-coding-instructions trap

On the full system prompt, a custom style leaves out Claude Code's section of built-in software engineering instructions (how to scope changes, write comments, verify work) unless you set keep-coding-instructions: true. If your style only changes communication and Claude should still code as normal, set it. Leave it out if Claude will not be doing software engineering.

The shorter system prompt does not include that section, so the field has no effect there. Setting CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT to 0 selects the full prompt on any model.

Gotchas when editing

• In the terminal, Claude Code reads style files at startup. Create or edit one mid-session and you must restart to pick it up.
• A misspelled frontmatter field is ignored without an error.
• If the YAML does not parse, the style still loads under its file name with no fields set. Run claude --debug to see the parse error.
• Plugins can ship styles in an output-styles/ directory, which is one way to give a team a shared style.

Do output styles change cost?

Yes, in both directions:

• A style's instructions add input tokens, though prompt caching reduces that cost after the first request in a session.
• Explanatory and Learning produce longer responses than Default by design, so they raise output tokens.
• Concise does the opposite: it tells Claude to keep responses short by default.
• For custom styles, output depends on what your instructions ask for.

Switching style mid-session does not break the cache. Claude Code delivers the new style's instructions as a message in the conversation, so the next request still reads the system prompt and earlier conversation from the cache. Compare that with a model switch: each model has its own cache, so switching models means the next request reads the whole history with no cache hits.

Subagents are the exception to remember. Styles apply to the main conversation and to a fork, which inherits the parent's whole conversation and system prompt. Other subagents run their own system prompt, so a style does not change how they respond. If you use Concise to tame verbose output, do not expect it to quiet your subagents.

When is an output style the wrong tool?

Because a style is only an instruction, match the need to the feature:

These combine. The docs suggest CLAUDE.md for what Claude should know, an output style for how it responds, and a hook for anything that has to be guaranteed. Do not put "never edit the migrations folder" in a style and call it enforced.

A practical setup for a team

1. Set Concise as a personal default in ~/.claude/settings.json if you read diffs more than prose.
2. For a new engineer getting to know a repo, suggest /output-style explanatory for their first week. Nothing needs to be committed for that.
3. If your team wants a house format for explanations or incident write-ups, put one Markdown file in .claude/output-styles/ and commit it, with keep-coding-instructions: true if Claude is still doing engineering.
4. When output looks odd, check which style is active. A wrong-case outputStyle value falls back to Default without telling you.
5. Keep guarantees in hooks and permissions, not in the style.

Conclusion

Output styles change how Claude Code talks to you with one command, no cache penalty on a switch, and a plain Markdown file when the built-ins do not fit. Treat them as tone and format controls, not rules, and keep enforcement in hooks.

If you run several Claude Code sessions at once, a style is chosen per session. Atlas runs each of its engineers as its own Claude Code session with a written role.