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

Output styles cover

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 Insight blocks 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:

Terminal
/output-style concise
/output-style

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

JSON
{
  "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:

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.

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

Build it with us in Stride AI Academy

Four courses, weekly live calls and a community of people building and selling AI. Or start with 320+ free guides.

Keep reading

Free AI Coding guides