Claude Code output styles are sets of instructions that change Claude's role, tone and response format for a whole session. Claude Code ships with four built-in styles besides Default (Proactive, Concise, Explanatory and Learning), you switch with /output-style <name>, and you can write your own style as a Markdown file in ~/.claude/output-styles or .claude/output-styles.
This guide follows Anthropic's output styles documentation, checked on 24 October 2026. Some features need a recent version, noted below; run claude update if a command is missing.
What are output styles in Claude Code?
An output style is extra instruction text that Claude Code sends with every request. It shapes how Claude responds and works with you, so you don't have to repeat "keep it short" or "explain your reasoning" in each prompt. A custom style can go further and turn Claude into something other than a software engineer, such as a writing assistant or a data analyst.
The docs are clear about one limit: an output style "gives Claude instructions to follow. It doesn't guarantee that something always happens or never happens." If something has to happen every time, a hook is the right tool.
What built-in output styles are there?
Claude Code starts in Default, its standard instructions for software engineering. Each of the other four keeps those instructions and adds its own:
| Style | What changes | Use it when |
|---|---|---|
| Default | No style instructions added | You want Claude Code's standard behavior |
| Proactive | Claude starts right away and makes reasonable assumptions instead of asking about routine decisions | You'd rather correct a wrong assumption than answer routine questions |
| Concise | Responses lead with the result and leave out preamble, narration and recaps | Default answers are longer than you want |
| Explanatory | Claude adds short Insight blocks explaining the choices behind its code |
You're learning a codebase or want the reasoning with the change |
| Learning | Insight blocks plus small pieces of code left for you to write | You want hands-on practice while the task still gets done |
A few details from the docs worth knowing:
- Proactive doesn't switch to plan mode unless you ask, and it doesn't change your permission mode. It still tells Claude to check with you before deleting data or changing a shared or production system.
- Concise answers a simple question in one to three sentences but keeps full length for explanations you ask for, error reports, failing tests, security warnings and confirmations before destructive actions. It requires Claude Code v2.1.237 or later.
- Explanatory puts its Insight blocks in the conversation, not in your files as comments.
- Learning marks spots in your code with a
TODO(human)comment, explains what to write, and waits for you to say you're done.
How do you switch output styles?
The quickest way is the command:
/output-style concise
Run /output-style with no argument to list the styles and see the current one. The command ignores case. It requires Claude Code v2.1.269 or later, and it also works in non-interactive mode. Other ways to switch:
- Terminal menu: run
/configand select Output style. - VS Code extension: type
/in the prompt box and select Output styles (v2.1.257 or later). - Settings file: set
outputStyle, which is how you set it in the desktop app.
The command and menus save your choice to .claude/settings.local.json, so it applies to that project only. To make a style your default everywhere, set it in ~/.claude/settings.json:
{
"outputStyle": "Concise"
}
In settings files the value is case-sensitive. Write Proactive, Concise, Explanatory or Learning exactly; a value like concise silently gives you Default. A project's own settings override your user setting, as described in the settings docs.
A new style applies from your next message. Before v2.1.251 it took effect only after /clear or a new session.
How do you create a custom output style?
A custom style is a Markdown file with optional frontmatter followed by your instructions. Save it in one of these places:
- User:
~/.claude/output-styles, for all your projects - Project:
.claude/output-styles, shared with the repo - Managed policy:
.claude/output-stylesinside the managed settings directory
The file name becomes the style name unless you set name. Here is the example from the docs, which leads explanations with a diagram:
---
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.
The frontmatter fields are all optional:
| Field | What it does |
|---|---|
name |
Name shown in the /config picker; defaults to the file name |
description |
Description shown in the picker |
keep-coding-instructions |
true keeps Claude Code's built-in software engineering instructions; default false |
force-for-plugin |
Plugin styles only: apply the style automatically when the plugin is enabled |
The key decision is keep-coding-instructions. A custom style leaves out Claude Code's section on how to scope changes, write comments and verify work unless you set it to true. Set it when you only want to change how Claude talks. Leave it out when Claude won't be writing code at all.
Two gotchas: a misspelled field is ignored without an error, and in the terminal Claude Code reads style files at startup, so restart after creating or editing one. If the YAML doesn't parse, run claude --debug to see why. Plugins can also ship styles in an output-styles/ folder.
How is an output style different from CLAUDE.md, skills and hooks?
They solve different problems and work well together. This table follows the docs' own comparison:
| You want | Use |
|---|---|
| Every response in a certain voice, length or format, or a different role | An output style |
| Claude to know your project's conventions, commands and structure | CLAUDE.md |
| Instructions for one kind of task, like a release checklist | A skill |
| Something that must happen every time, like formatting after each edit | A hook |
| A helper with its own instructions and tools in a separate context | A subagent |
The short version: CLAUDE.md is what Claude knows, the output style is how it responds. CLAUDE.md "stays loaded whichever style you pick," so switching styles never drops your project rules. Our memory guide covers how CLAUDE.md files load.
Output styles apply to the main conversation and to forks. Other subagents run their own system prompt, so a style doesn't change how they respond. After /compact, the output style still applies, according to the context window docs.
Do output styles cost more tokens?
A little, in two ways. The style's instructions add input tokens on every request, though prompt caching reduces that after the first request in a session. And the style changes how much Claude writes: Explanatory and Learning produce longer responses by design, while Concise asks for shorter ones. If you're watching usage, Concise is the style that pushes output down. See our Claude Code tips for other ways to save tokens.
Where should you keep custom styles you like?
A good custom style is worth keeping beyond one machine. Since a style is a plain Markdown file, you can store it next to your prompts and skills. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, searchable with Cmd+K, so your style instructions and the prompts that go with them live in one place you control.