Claude Output Styles: Built-In and Custom Styles
Claude output styles explained: the built-in Claude Code styles, how to switch with /output-style, and how to write a custom style file with frontmatter.
Josh Pocock7 min read
AI Coding
Output styles
Stride AI Academy
Claude output styles are sets of instructions that change Claude Code's role, tone and response format for a whole session. Claude Code ships with the Default style plus four built-in styles: Proactive, Concise, Explanatory and Learning. You switch with /output-style, and you can write your own style as a Markdown file in ~/.claude/output-styles or .claude/output-styles.
This guide covers each built-in style, every way to switch, how to write a custom style file and when another feature fits better. Everything here was checked against Claude Code's output styles docs, the CLI reference and the settings docs on November 21, 2026.
What output styles do in Claude Code
An output style is a block of instructions Claude Code sends with every request in the session. You pick it once and it shapes every reply, so you don't repeat "keep it short" or "explain your choices" in each prompt.
Output styles are a current, documented feature. The docs don't mark them as deprecated, and features such as the Concise style and the VS Code style menu need recent versions.
One thing to keep in mind: a style is an instruction Claude follows. The docs are clear that it "doesn't guarantee that something always happens or never happens." If something has to happen every time, that's a job for a hook, covered below.
The built-in output styles
Claude Code starts in Default, which means no style is selected and Claude works from its standard software engineering prompt. Each of the other four keeps those instructions and adds its own.
| Style | What changes | Use it when |
|---|---|---|
Proactive |
Claude starts work right away and makes reasonable assumptions instead of asking about routine decisions | You'd rather correct a wrong guess than answer questions |
Concise |
Replies lead with the result and drop the preamble, narration and recap | Default replies are longer than you want |
Explanatory |
Claude adds short Insight blocks explaining the choices behind its code |
You're learning a codebase and want the reasoning |
Learning |
Insight blocks plus small pieces of code left for you to write | You want hands-on practice while the task gets done |
A few details from the docs worth knowing:
- Proactive doesn't change your permission mode. Permission prompts still appear exactly as before. It also doesn't enter plan mode unless you ask for a plan, and it tells Claude to check with you before deleting data or touching a shared or production system.
- Concise answers a simple question in one to three sentences, but still writes in full when you ask for detail and for anything you need to act safely, such as error reports, failing tests and security warnings. It requires Claude Code v2.1.237 or later.
- Explanatory puts its
Insightblocks in the conversation, not in your files as comments. - Learning marks a spot in your file with a
TODO(human)comment, tells you what to write, then stops and waits until you say you're done.
How to switch output styles
There are four documented ways to change your style.
The command. Run it with a style name, or with no argument to list the styles and see which one is active:
/output-style concise
/output-styleThe command ignores case. It also works in non-interactive mode and Agent SDK sessions, and over Remote Control from the mobile app or web, where you can pick only built-in styles. That requires v2.1.269 or later.
The terminal menu. Run /config and select Output style.
VS Code. Type / in the prompt box and select Output styles. This lists your custom styles too and needs v2.1.257 or later. Our guide to Claude Code in VS Code covers the rest of the extension.
A settings file. The command and menus save your choice to .claude/settings.local.json. You can set it yourself:
{
"outputStyle": "Explanatory"
}Unlike the command, this value is case-sensitive. Write Proactive, Concise, Explanatory or Learning exactly. A value like explanatory silently gives you Default. To make a style your default everywhere, put outputStyle in ~/.claude/settings.json; a project's own settings still take precedence. The settings.json guide explains how those files layer.
When you switch mid-session, the new style applies from your next message. Before v2.1.251 you had to run /clear or start a new session first.
How to write a custom output style
A custom style is a Markdown file: frontmatter at the top, instructions underneath. The file name becomes the style name unless you set name.
Save it in one of three places:
| Level | Folder |
|---|---|
| User (all projects) | ~/.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 your working directory and the repository root. If two define the same name, the one closest to your working directory wins.
Here's the example from the docs, 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.Then run /output-style with its name, or pick it from /config. In the terminal, Claude Code reads style files at startup, so restart it after you create or edit one.
Frontmatter fields
All fields are optional. A misspelled field is ignored with no error, and if the YAML doesn't parse, the style loads under its file name with no fields set. Run claude --debug to see the parse error.
| Field | What it does | Default |
|---|---|---|
name |
Name shown in the /config picker |
The file name |
description |
Description shown in the picker | None |
keep-coding-instructions |
true keeps Claude Code's built-in software engineering instructions alongside your style |
false |
force-for-plugin |
Plugin styles only: applies the style automatically whenever the plugin is on, overriding the user's outputStyle |
false |
The keep-coding-instructions field matters most. Without it, a custom style drops Claude Code's section on how to scope changes, write comments and verify work. That's right for a writing assistant or data analyst style, and wrong if you only want to change how Claude talks while it codes. The docs note this section only exists in the full system prompt, so the field has no effect on the shorter one. Setting CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT to 0 selects the full prompt on any model.
Plugins can ship styles too, in an output-styles/ folder.
Output styles vs CLAUDE.md, skills and system prompt flags
These features overlap, so here's how the docs split them:
| You want | Use |
|---|---|
| Every reply in a certain voice, length or format, or Claude in 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, which loads only when invoked or relevant |
| Something to happen every time without exception | A hook, which Claude Code runs itself |
| A helper with its own instructions, model and tools | A subagent |
| A one-off addition when you launch | --append-system-prompt |
The system prompt flags are the closest cousin. --append-system-prompt adds text to the end of the default prompt for that launch, and --system-prompt replaces the whole prompt. The CLI reference points you to output styles instead "for persistent personas you can switch between and share across a project."
The features also combine. CLAUDE.md can hold what Claude should know, a style can set how it responds and a hook can enforce what must happen.
Things that trip people up
- Subagents ignore your style. Styles apply to the main conversation and to a forked conversation. Other subagents run their own system prompt.
- Token use changes. A style adds input tokens, which prompt caching reduces after the first request. Explanatory and Learning write longer replies by design. Concise does the opposite.
- Safe mode turns custom styles off.
claude --safe-modeskips custom output styles along with other customizations, which helps when you're not sure a style is the cause of odd behaviour.
Learn to build with Claude Code
The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code setups, and the Claude Code community is where members compare theirs.
FAQ
What are output styles in Claude Code?
They're sets of instructions that change Claude's role, tone and response format for a whole session. Claude Code includes Default plus four built-in styles, Proactive, Concise, Explanatory and Learning, and you can write your own as Markdown files.
How do I change the output style in Claude Code?
Run /output-style followed by the style name, such as /output-style concise, or run /config and select Output style. You can also set "outputStyle" in a settings file, where the name is case-sensitive.
Where do custom output style files go?
Put them in ~/.claude/output-styles for all your projects or .claude/output-styles for one project. The file name becomes the style name unless you set name in the frontmatter, and you restart Claude Code to load a new or edited file.
What does keep-coding-instructions do?
Set to true, it keeps Claude Code's built-in software engineering instructions alongside your style. It defaults to false, so a custom style without it drops those instructions, which suits styles where Claude won't be writing code.
Are output styles deprecated?
No. The current docs list Default plus four built-in styles, and since v2.1.251 a style change applies from your next message without a /clear.
Should I use an output style or CLAUDE.md?
Use CLAUDE.md for what Claude should know about your project and an output style for how it responds. CLAUDE.md stays loaded whichever style you pick, so the two work together.