Output styles

An output style is a block of instructions Claude Code adds to every request in a session. It shapes Claude's role, tone and response format, so you stop typing "keep it short" or "explain why" at the end of every prompt.

The built-in styles cover the common cases: shorter answers, more explanation, fewer questions, or a hands-on learning mode. Custom styles go further and can turn Claude into something other than a coding assistant entirely, such as a technical editor or a data analyst.

Note: A style is guidance Claude follows, not a guarantee. Project knowledge belongs in CLAUDE.md. Anything that must happen every time, like formatting after each edit, belongs in a hook.

The built-in styles

Sessions start in Default. The other four keep everything Default does and layer their own instructions on top.

Default

Selecting default means no style instructions are added at all. It appears in the /output-style list and is selected the same way as any other.

Proactive

Claude starts implementing as soon as the task arrives, makes reasonable calls on routine decisions, and does not drop into plan mode unless you ask for a plan. You can redirect it whenever you like.

The style still tells Claude to check with you in conversation before anything that deletes data or touches a shared or production system. That is a behavioural instruction, separate from permission prompts. Proactive does not change your permission mode: tool calls that needed approval before still need it.

Concise

The first sentence says what happened or gives the answer. No lead-in, no blow-by-blow narration, no closing summary, and simple questions get one to three sentences. The engineering work itself is just as thorough. Requires v2.1.237 or later.

Claude still writes in full when you explicitly ask for detail, and for anything you need in order to act safely: error reports, failing test output, security warnings and confirmations before destructive actions.

Concise is the style I leave on most of the time.

Explanatory

Claude works exactly as in Default, then adds a short Insight block next to the code it explains. The insights live in the conversation, never in your files as comments. Each one carries two or three points, for example after Claude adds a background job:

★ Insight ─────────────────────────────────────
- Jobs in this project register through queue/index.ts, so the new
  invoice reminder is picked up by the existing worker without config.
- Retries are capped at three in the shared job options, which is why
  the handler is written to be safe to run more than once.
─────────────────────────────────────────────────

Learning

Learning adds the same Insight blocks and then asks you to write part of the code. Claude handles the routine parts itself. When it reaches something with a genuine design decision (error handling, a data structure, business rules with more than one sensible answer) it leaves a TODO(human) comment in the file and sends you a brief:

● Learn by Doing

Context: The basket total is calculated in pricing.ts and already
applies item-level discounts. Voucher codes are parsed but not applied.

Your Task: In pricing.ts, implement applyVoucher() where you see
TODO(human).

Guidance: Decide whether a voucher applies before or after item
discounts, and how to handle a voucher that exceeds the basket total.
Return the new total in pence.

Claude then waits. Write your code at the marker, tell Claude you are finished, and it replies with an Insight about your solution before continuing.

Switching styles

The command and menus save to .claude/settings.local.json, the local project level. /output-style also works in -p mode, Agent SDK sessions and over Remote Control from v2.1.269, though from mobile or web you can only choose built-in styles.

To set a style by hand:

{
  "outputStyle": "Concise"
}

The settings value is case-sensitive: use Proactive, Concise, Explanatory or Learning. A near miss such as concise silently gives you Default. The /output-style command, by contrast, ignores case.

Put outputStyle in ~/.claude/settings.json to make it your default everywhere. Project settings files override it (see settings precedence).

A mid-session switch applies from your next message. Before v2.1.251 you needed /clear or a new session. The first message after a switch has a prompt caching cost because the system prompt changed.

Writing a custom style

A custom style is a Markdown file: YAML frontmatter, then the instructions.

1. Choose where it lives

Project styles load from every .claude/output-styles/ folder between your working directory and the repository root. If two define the same name, the one nearest the working directory wins. Without a name field, the file name is the style name.

In VS Code (v2.1.261+) you can create the file from the Output styles menu instead of by hand.

2. Write frontmatter and instructions

The key decision is whether to keep Claude Code's built-in software engineering instructions. Keep them (keep-coding-instructions: true) when you are changing how Claude talks but still want it coding normally. Leave them out when Claude will not be writing code.

Here is a style I use when reviewing pull requests for clients who are not developers:

---
name: Client-ready
description: Plain-English summaries a non-technical stakeholder can read
keep-coding-instructions: true
---

After any change, finish with a section headed "What this means for you"
written for someone who does not read code. Avoid jargon; if a technical
term is unavoidable, explain it in one clause.

## Format

- Use UK English.
- Keep the stakeholder section under 120 words.
- Put risks or follow-up actions in a short bulleted list at the end.

And one that drops the coding instructions entirely, for a docs-only repository:

---
name: Technical editor
description: Edit prose for clarity and house style, not code
---

You are a technical editor. Improve clarity, cut repetition and enforce
the house style in STYLE.md. Never rewrite meaning without flagging it.
Report each change as a short before and after pair.

3. Select it

Run /output-style client-ready or pick it under Output style in /config. The terminal reads style files at startup, so restart Claude Code after creating or editing one.

Plugins can also ship styles in an output-styles/ directory.

Frontmatter fields

Every field is optional and uses lowercase hyphenated names. A misspelt field is ignored without complaint. If the YAML fails to parse, the style still loads under its file name with no fields applied; run claude --debug to see the parse error.

How styles work under the hood

• The active style's instructions go out with every request.
• On the full system prompt, a custom style removes Claude Code's built-in engineering guidance (how to scope changes, write comments, verify work) unless keep-coding-instructions is true.
• Some sessions use a shorter system prompt that never contains that section, so the field has no effect there. To make sure it matters, set CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=0, which selects the full prompt on any model. See environment variables.
• Styles apply to the main conversation and to forks, which inherit the parent's system prompt. Other subagents use their own system prompt, so styles do not affect them.

Token cost: the style's text adds input tokens, largely offset by prompt caching after the first request. Explanatory and Learning produce longer answers by design, Concise produces shorter ones, and a custom style costs whatever its instructions ask for.

Style or something else?

They combine well. My usual setup is CLAUDE.md for what Claude should know, the Concise style for how it talks, and a hook for formatting. Features overview compares the full set.

Related

• Settings
• Permission modes
• Plugins overview
• Debug your configuration