Claude Code output styles: changing how Claude responds

Who this is for and what you will get

Output styles suit people who find Claude Code's answers too long, or who want it to explain its decisions while they learn a codebase. A style is set once and applies to the whole session, so you do not have to repeat the same instruction in every prompt. By the end you will be able to switch among the built-in styles, know which one fits a given situation, and write a style file of your own.^[1]

What an output style is

An output style is a set of instructions. It sets Claude's role, tone and response format for every response in a session. Besides its default, Claude Code includes four built-in styles: Proactive, Concise, Explanatory and Learning.^[1]

Default is the absence of a style. Claude Code adds no style instructions and works from its standard system prompt, which is written for software engineering tasks.^[1]

A style is an instruction that Claude follows. Nothing enforces it on every response. If something must happen every time, a hook is the right tool rather than a style.^[1]

Choosing among the built-in styles

• Proactive. Claude starts implementing as soon as you send a task. It makes reasonable assumptions about routine decisions instead of stopping to ask, and it does not switch to plan mode unless you ask for a plan. Its instructions also tell it to check with you in the conversation before deleting data or changing a shared or production system. That check is separate from permission prompts. Switching to this style does not change the permission mode, so prompts appear as before.^[1]
• Concise. The first sentence states what happened or what the answer is. The lead-in, the step-by-step narration and the closing recap are left out, and a simple question gets one to three sentences. This style requires Claude Code v2.1.237 or later.^[1] When you ask for an explanation, Claude still answers in full. Error reports, failing test output, security warnings and confirmations for destructive actions keep their complete content.^[1]
• Explanatory. Claude does the task as in Default and adds short explanations in blocks labeled Insight. The blocks appear in the conversation and are not written into your files as comments. An example:

★ Insight ─────────────────────────────────────
- Every route in this repo goes through the withAuth wrapper, so the new endpoint gets session checks without its own middleware.
- Rate limits are set per route in limits.ts, which is why this change adds an entry there rather than a global default.
─────────────────────────────────────────────────

• Learning. It adds the same Insight blocks and also asks you to write some of the code. Claude handles routine implementation itself. Where a piece needs a real design decision, such as error handling, a data structure or business logic with more than one valid approach, it leaves that piece for you. It marks the spot with a TODO(human) comment and sends a request that explains what is built, what to write and what to weigh. Then it waits. When you tell it you are done, it gives an Insight about your code and carries on. A request looks like this:

● Learn by Doing

Context: The upload form is in place and calls validateFile() before accepting a file. Size and type checks work for images, but the switch statement has no handling for documents yet.

Your Task: In upload.js, implement the case "document" branch inside validateFile(). Look for TODO(human).

Guidance: Decide on a size limit for documents and whether the file extension has to match the MIME type. Return {valid: boolean, error?: string}.

Switching styles

The quickest route is /output-style <style>, for example /output-style concise. Run without an argument, the command lists the available styles and marks the current one. It also works in non-interactive mode and in Agent SDK sessions.^[1]

Alternatively, run /config and select Output style from the menu.^[1]

To skip the menu, edit the outputStyle field in a settings file:

{
  "outputStyle": "Explanatory"
}

The value is case-sensitive, so use Proactive, Concise, Explanatory or Learning exactly. A value such as explanatory that matches no style name falls back to Default, although the command itself ignores case.^[1] To use a style in every project, set outputStyle in ~/.claude/settings.json. A project's own settings files take precedence over it.^[1]

If you switch in the middle of a session, Claude uses the new style from your next message. Versions before v2.1.251 applied the change only after /clear or a new session.^[1]

Writing your own style

A custom style is a Markdown file. It starts with frontmatter for metadata and continues with the instructions for Claude. You can save it in the user directory ~/.claude/output-styles, in a project's .claude/output-styles, or in .claude/output-styles inside the managed settings directory.^[1]

Project styles load from every .claude/output-styles/ between the working directory and the repository root. When one name is defined more than once, the copy nearest the working directory is used. The file name becomes the style name unless the frontmatter sets name.^[1]

If you only want to change how Claude communicates and still want it to code the same way, add keep-coding-instructions: true. Leave it out if Claude will not be doing software engineering. Here is a style that leads every explanation with a diagram and keeps Claude's coding behavior:

---
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 name, description, keep-coding-instructions (default false) and force-for-plugin, which applies only to styles shipped by plugins.^[1] A misspelled field is ignored without any error. If the YAML does not parse, the style still loads under its file name with no fields set, and claude --debug shows the parse error.^[1] In the terminal, style files are read at startup, so restart Claude Code after you create or edit one during a session.^[1]

How it fits with other features

A style controls how Claude responds. For what Claude should know about the project, use CLAUDE.md. For a task with its own steps, use a skill. For something that must happen every time, such as formatting after each edit, use a hook. These can be combined.^[1]

Two details matter here. On the full system prompt, a custom style leaves out Claude Code's software engineering instructions unless keep-coding-instructions is true. Setting CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT to 0 selects the full prompt.^[1] Styles also apply only to the main conversation and to forks. Other subagents run their own system prompt and are not changed by the style.^[1]

Limits and common problems

• Longer answers and more tokens. Explanatory and Learning produce longer responses than Default by design, which raises output tokens. Concise does the opposite by default.^[1]
• A change did not take effect. Check that the value matches the style name in case, see whether a project settings file overrides outputStyle, and restart Claude Code if you are in the terminal.^[1]

Next step

The full details on each style and on the configuration fields are in Anthropic's Claude Code documentation for output styles.^[1]