Claude Code output styles: built-ins, custom files and scope

Claude Code output styles change how the coding agent answers for an entire session: shorter replies, added explanations, fewer routine questions or a custom role and format, according to Anthropic’s output styles documentation. They do not replace project facts in CLAUDE.md, task-specific skills or hooks that must run at a lifecycle event.

Applies to: Claude Code v2.1.269 or later for the /output-style command, per Anthropic’s docs. Last checked: October 23, 2026.

On this page

Pick a built-in style

Claude Code starts with Default, which adds no style instructions. Anthropic documents four other built-ins, and each keeps the default software engineering instructions while adding its own:

Proactive does not change your permission mode, so permission prompts appear as before. Concise requires v2.1.237 or later and still writes at full length when you ask for detail, and for error reports, failing test output, security warnings and confirmations for destructive actions (Anthropic).

Switch styles from the terminal

Use the slash command with a style name, as in Anthropic’s example:

/output-style concise

Run /output-style without an argument to list the styles and mark the current one. The command requires Claude Code v2.1.269 or later and ignores case. You can also run /config and select Output style, or use the Output styles item in the VS Code extension’s command menu (v2.1.257 or later), per the docs.

The command and both menus save the choice to .claude/settings.local.json. To set it by hand, edit the outputStyle field:

{
  "outputStyle": "Explanatory"
}

In the settings file the value is case-sensitive: write Proactive, Concise, Explanatory or Learning. A value that does not match exactly, such as explanatory, gives you the Default style. To make a style your default across projects, set outputStyle in ~/.claude/settings.json; a project’s own settings files take precedence over it.

A style changed mid-session applies from your next message. Before v2.1.251, the new style applied only after /clear or a new session (Anthropic).

Create a custom output style

A custom style is a Markdown file: frontmatter for metadata, then the instructions. Anthropic lists three locations:

• User: ~/.claude/output-styles
• Project: .claude/output-styles
• Managed policy: .claude/output-styles inside the managed settings directory

The file name becomes the style name unless you set name. Project styles load from every .claude/output-styles/ between the working directory and the repository root; when two define the same name, the one closest to the working directory wins.

This is Anthropic’s example of a style that leads with a diagram while keeping 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.

Switch to it with /output-style <style> or through /config. In the terminal, Claude Code reads style files when it starts, so restart it after creating or editing one during a running session. In the VS Code extension you can also create the file from the Output styles menu, which requires v2.1.261 or later.

Decide whether to keep coding instructions

On the full system prompt, custom styles leave out Claude Code’s built-in software engineering instructions, such as how to scope changes, write comments and verify work, unless keep-coding-instructions is true (Anthropic). Set it to true when you are changing how Claude communicates but still want it coding the same way; leave it out when Claude won’t be doing software engineering.

The shorter system prompt doesn’t include that section, so the field has no effect there. To rely on it, set CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT to 0, which selects the full prompt on any model.

The frontmatter reference lists four optional fields: name, description, keep-coding-instructions and, for plugin styles only, force-for-plugin, which applies the style whenever the plugin is enabled and overrides the user’s outputStyle setting. A misspelled field is ignored without an error. If the YAML doesn’t parse, the style still loads under its file name with no fields set; run claude --debug to see the parse error.

Output style, CLAUDE.md, skill or hook?

Anthropic’s comparison table matches each need to a feature:

• Output style: every response in a certain voice, length or format, or Claude in a different role.
• CLAUDE.md: your project’s conventions, commands and structure; it stays loaded whichever style you pick. See the CLAUDE.md best practices guide.
• Skill: instructions for one kind of task, loaded only when you invoke it or the task matches.
• Hook: something that must happen every time, such as formatting after each edit or blocking a command, because Claude Code runs it at a lifecycle event. The Claude Code hooks guide covers events, matchers and exit codes.
• Subagent: a helper with its own instructions, model and tools that runs in a separate context. See the Claude Code subagents guide.

These combine: Anthropic’s example uses CLAUDE.md for what Claude should know, an output style for how it responds and a hook for anything that has to be guaranteed. An output style is an instruction Claude follows, so nothing enforces it.

When a style doesn’t take effect

The docs point to a few checks:

1. A hand-written outputStyle value must match the style name exactly; /output-style itself ignores case.
2. A project’s settings files take precedence over ~/.claude/settings.json.
3. After creating or editing a style file in the terminal, restart Claude Code.
4. An enabled plugin style with force-for-plugin: true overrides your outputStyle setting.
5. For frontmatter parse errors, run claude --debug.

Anthropic’s Debug your configuration page covers the general case.