# Claude Code Output Styles: Concise, Custom and Cost

> Claude Code output styles change tone, length and role for a whole session. Learn the four built-ins, how to write a custom one, and what it does to cost.

Canonical: https://bridge-terminal.com/atlas/blog/claude-code-output-styles-concise-custom/
Last updated: 2026-11-06

Published 6 November 2026 · Technical · From Atlas · 7 min read

## The short version

- A Claude Code output style is a set of instructions that sets role, tone and response format for every response in a session; it does not change what Claude knows about your project.
- Four built-in styles come besides Default: Proactive, Concise, Explanatory and Learning. Switch with /output-style, the /config menu, or the outputStyle setting.
- A custom style is a Markdown file in an output-styles folder with optional frontmatter; set keep-coding-instructions to true if Claude should still code the same way.
- A style is an instruction Claude follows, not a guarantee, so anything that must happen every time belongs in a hook.
- Switching style mid-session keeps the prompt cache, because the new instructions arrive as a message in the conversation. Subagents other than forks are not affected by styles.

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?

| Style | What changes | Use it when |
| :- | :- | :- |
| Proactive | Claude starts work right away and makes reasonable assumptions on routine decisions instead of asking | You will correct course if an assumption is wrong |
| Concise | Responses lead with the result and drop preamble, narration and recaps | Default responses are longer than you want |
| Explanatory | Short `Insight` blocks explain the choices behind the code | You are getting to know a codebase |
| Learning | The same `Insight` blocks, plus small pieces of code left for you to write | You want hands-on practice |

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:

```text
/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:

```json
{
  "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:

```markdown
---
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:

| Field | Effect |
| :- | :- |
| `name` | Name shown in the `/config` picker; default is the file name |
| `description` | Description shown in the picker |
| `keep-coding-instructions` | `true` keeps Claude Code's built-in software engineering instructions alongside your style; default `false` |
| `force-for-plugin` | Plugin styles only: apply automatically whenever the plugin is enabled, overriding the user's `outputStyle`. If several enabled plugins set it, the first one loaded is used |

### 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:

| You want | Use |
| :- | :- |
| Every response in a certain voice, length or format, or Claude in a different role | An output style |
| Claude to know your conventions, commands and structure | CLAUDE.md |
| Instructions for one kind of task, such as a release checklist | A skill |
| Something to happen every time, such as formatting after each edit or blocking a command | A hook |
| A helper with its own model, tools and instructions | A subagent |
| An addition to the system prompt that you pass at launch | `--append-system-prompt` |

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](https://bridge-terminal.com/atlas/) runs each of its engineers as its own Claude Code session with a written role.

## Questions people ask

### What is a Claude Code output style?

It is a set of instructions that sets Claude's role, tone and response format for every response in a session. Claude Code ships four besides Default: Proactive, Concise, Explanatory and Learning, and you can write your own.

### How do I change the output style in Claude Code?

Run /output-style followed by the style name, or run /config and choose Output style, or set the outputStyle field in a settings file. In a settings file the value is case-sensitive, and a mismatch gives you the Default style.

### Does switching output style break the prompt cache?

No. 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. A model switch is different: each model has its own cache.

### Where do custom output styles go?

Save a Markdown file in ~/.claude/output-styles for yourself, .claude/output-styles in a project, or .claude/output-styles inside the managed settings directory for policy. Set keep-coding-instructions to true in the frontmatter if Claude should keep its software engineering instructions.

### Can an output style force Claude to follow a rule?

No. A style is an instruction Claude follows, not a guarantee. For something that must happen every time, such as formatting after each edit or blocking a command, use a hook.

## About Atlas: Styles per engineer: where Atlas stands today

Atlas runs each engineer as its own Claude Code session with a written role and a model and effort suited to it. Choosing an output style per role is not something Atlas does today. It is coming to Atlas, built in, so it needs no setup. Until then, you can use output styles in your own Claude Code sessions. — https://bridge-terminal.com/atlas/

## Sources

- [Output styles - Claude Code docs](https://code.claude.com/docs/en/output-styles)
- [How Claude Code uses prompt caching](https://code.claude.com/docs/en/prompt-caching.md)

_Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._

## Related

- [Claude Code Agent Teams: Setup, Cost and When to Use](https://bridge-terminal.com/atlas/blog/claude-code-agent-teams-setup-cost-limits/)
- [Claude Code /compact vs /clear: Manage Context and Cost](https://bridge-terminal.com/atlas/blog/claude-code-compact-clear-context-management/)
- [Claude Code Resume: Continue, Name and Branch Sessions](https://bridge-terminal.com/atlas/blog/claude-code-resume-sessions-name-branch/)