Claude Code Output Styles: Changing How It Talks

An output style is a set of instructions that changes how Claude Code responds for a whole session: its tone, its length, its role and how much it asks before acting. Output styles are still supported. Claude Code ships a Default style and four others, Proactive, Concise, Explanatory and Learning, and you can add your own as a Markdown file in ~/.claude/output-styles/ or .claude/output-styles/. Switch with /output-style concise, or pick one under Output style in /config. A style shapes how Claude talks; it does not tell Claude about your project (that is CLAUDE.md), and it does not guarantee anything happens (that is a hook).

What an output style changes

Claude Code sends the active style’s instructions with every request, so the effect covers every reply until you switch. Anthropic’s output styles documentation↗ (opens in a new tab) describes it as a way to stop repeating the same request in each prompt: make responses shorter, add an explanation of each change, have Claude start work without routine questions, or turn it into something other than a software engineer, such as a writing assistant or a data analyst.

Two limits are worth knowing before you rely on one. A style is an instruction Claude follows, not a rule Claude Code enforces, so it makes a behavior likely rather than certain. And it applies to the main conversation and to a forked conversation only; ordinary subagents run their own system prompt, so a style does not change how they respond.

The built-in styles today

If a guide you are reading lists only Explanatory and Learning, it is out of date. The documentation now lists five:

• Default: no style selected. Claude works from Claude Code’s standard system prompt, which is written for software engineering tasks.
• Proactive: Claude starts implementing as soon as you send a task, makes reasonable assumptions about routine decisions instead of stopping to ask, and does not switch to plan mode unless you ask for a plan. It is told to check with you before deleting data or changing a shared or production system, but it does not change your permission mode, so permission prompts appear exactly as before.
• Concise: the first sentence says what happened or what the answer is, with no lead-in, narration or closing recap, and a simple question gets one to three sentences. Error reports, failing test output, security warnings and confirmations for destructive actions stay at full length. It needs Claude Code v2.1.237 or later.
• Explanatory: Claude does the task as in Default and adds short Insight blocks in the conversation, two or three points on why it made the choices it made. The explanations are not written into your files as comments.
• Learning: the same Insight blocks, plus Claude leaves some of the code for you. At a piece with a real design decision, such as error handling or a data structure, it writes a TODO(human) comment in the file, tells you what to write and what to weigh, and waits until you say you are done.

Learning is what people mean by Claude Code learning mode. It fits someone new to a language or a codebase who wants the task finished and some practice along the way. Explanatory suits getting to know an unfamiliar repository without doing the typing yourself. Both produce longer replies by design, which means more output tokens; Concise does the opposite.

Switching styles

/output-style              # list styles and mark the current one
/output-style concise      # switch; the command ignores case
/config                    # then choose Output style from the menu

The command and the menu save your choice to .claude/settings.local.json for that project. To set a default across projects, put outputStyle in ~/.claude/settings.json; a project’s own settings win over it. In a settings file the value is case-sensitive: "outputStyle": "Explanatory" works, while "explanatory" silently gives you Default. A switch applies from your next message. In the VS Code extension, type / in the prompt box and choose Output styles; in the desktop app, set outputStyle in a settings file.

{
  "outputStyle": "Concise"
}

Writing a custom output style

A custom style is a Markdown file: YAML frontmatter, then the instructions. Save it in ~/.claude/output-styles/ for yourself or .claude/output-styles/ to share with the repository; a managed-policy folder also exists for organizations. The file name becomes the style name unless you set name. Claude Code reads style files when it starts, so restart after you create or edit one.

The frontmatter has four optional fields. name and description are shown in the picker. keep-coding-instructions decides whether Claude keeps Claude Code’s built-in software engineering instructions, such as how to scope changes and verify work; it defaults to false, so a custom style drops them unless you set it to true. force-for-plugin applies only to styles shipped in a plugin and turns the style on whenever the plugin is enabled. A misspelled field is ignored without an error, and claude --debug shows a YAML parse error if the style loads with no fields set.

Example: a terse code reviewer

---
name: Terse reviewer
description: Short findings, most serious first, no praise
keep-coding-instructions: true
---

When reviewing code, list findings only, most serious first.
Each finding is one line: file:line, the problem, the fix.
Do not summarize what the code does and do not add praise.
If there is nothing worth changing, say "No findings." and stop.

This keeps the coding instructions, because the reviewer still reads and reasons about code the normal way. For a one-off review procedure, such as a release checklist, a skill is the better home; the style is for when every reply in the session should sound like this.

Example: writing for people who do not code

---
name: Plain English
description: Explain work to readers who do not write code
---

The reader is a manager or client who does not write code.
Lead with what changed for the user of the product, in one or two sentences.
Avoid jargon; if a technical term is unavoidable, explain it in a few words.
Never paste code unless asked. Name files only when the reader must act on them.
End with anything the reader has to decide, as a short list.

Here keep-coding-instructions is left out on purpose. That suits sessions where Claude mostly reads and explains, such as the work in Claude Code for non-coding tasks. If Claude will still edit code in that session, set it to true so it keeps verifying its changes.

Output style vs CLAUDE.md, skills and subagents

The question to ask is what the instruction is about and when it should apply.

• Output style: every reply in a certain voice, length or format, or Claude in a different role. One per session, switched with one command.
• CLAUDE.md: what Claude should know about your project, its commands and conventions. It stays loaded whichever style you pick; Anthropic’s memory documentation↗ (opens in a new tab) covers where the files live, and so does Claude Code memory.
• Skill: instructions for one kind of task, loaded only when you invoke it or the request matches, so it does not shape unrelated replies. See the skills documentation↗ (opens in a new tab).
• Subagent: a helper with its own system prompt, model and tools that works in a separate context and returns a summary. The subagents documentation↗ (opens in a new tab) explains why your output style does not reach it.
• Hook: something that must happen every time, such as formatting after each edit or blocking a command, run by Claude Code itself. Examples are in Claude Code hooks examples.
• --append-system-prompt: an addition you pass when you start Claude Code, for one run.

They combine: CLAUDE.md for what Claude knows, a style for how it answers, a hook for what must be guaranteed. How the extension points fit together is in plugins vs skills vs subagents. A plugin can also ship styles in an output-styles/ folder, as the plugins reference↗ (opens in a new tab) shows.

Choosing one for a team

• Commit shared custom styles to .claude/output-styles/, but leave the choice of style to each person. The menu writes to settings.local.json, which is personal.
• Do not put project rules in a style. A rule such as “never edit migrations” belongs in CLAUDE.md or a permission rule, where it applies whichever style someone picks.
• Watch cost. Every style adds input tokens, and Explanatory and Learning add output tokens. Prompt caching softens the input side after the first request.
• Show the active style in your status line if you switch often: the status line input includes output_style.name, as covered in the Claude Code status line.

A style changes the words, not the record

A Concise or Plain English style makes Claude’s updates easier to read, but they still live in a conversation that ends. If you track the work on fenbs, the useful split is simple: the style decides how Claude reports to you in the session, and the board keeps what was done. Claude writes the task’s note and plan, moves it through To Do, Next Up, In Progress and Completed, and sets a test status with notes, and History records each change under the assistant’s name. Standing instructions such as “always record the commit” go on the Decisions and rules page as rules, which every connected assistant reads first through fenbs_get_context, rather than into a style that only one person has switched on. The rhythm is in a task-tracking workflow for Claude Code, and more everyday habits are in Claude Code best practices.