Skip to main content

Output Styles

Intermediate
What you'll learn
  • What an output style is — and how it differs from changing what Claude knows
  • The four built-in styles: Default, Proactive, Explanatory, Learning
  • How to switch styles with /config — and why the change needs a fresh session
  • How to author your own custom style as a Markdown file
  • When to reach for an output style vs CLAUDE.md vs Claude.ai custom instructions

Output styles change how Claude Code communicates — its role, tone, verbosity, and whether it explains its reasoning — by modifying the system prompt directly. They change how Claude responds, not what it knows. Reach for one when you keep re-prompting for the same voice or format every turn.

Why use them​

  • Match your workflow. Terse and action-first when you're moving fast; explanatory when you're learning.
  • Teaching mode. Some styles add educational commentary — great while you're getting to know a codebase or a technique.
  • Consistency. Set a preferred style once so every session reads the way you like.

The built-in styles​

Claude Code ships with four:

StyleWhat it does
DefaultThe standard software-engineering system prompt — efficient, action-first.
ProactiveExecutes immediately and makes reasonable assumptions instead of pausing for routine decisions. Stronger autonomous-execution guidance than auto mode, but you still see permission prompts before tools run.
ExplanatoryAdds educational "Insights" between steps, explaining implementation choices and codebase patterns.
LearningCollaborative, learn-by-doing: shares Insights and asks you to write small pieces yourself, leaving [TODO(human)] markers in your code.
Watch out
  • Explanatory and Learning produce longer responses by design, so they cost more output tokens than Default.
Press Enter or Space to flip the card. Use the left and right arrow keys to move between cards.Term shown.
1 / 4

How to switch​

Run /config and pick a style under Output style. Your choice is saved to .claude/settings.local.json at the project level. To set it without the menu, edit the outputStyle field in any settings file.

Guided walkthrough1 of 4
  1. Run /config in your session and find the Output style option.
{
  "outputStyle": "Explanatory"
}

:::warning Changes need a fresh session The output style is part of the system prompt, which Claude Code reads once at session start. A change takes effect only after /clear or a new session. (The standalone /output-style command was removed in v2.1.91 — use /config or the setting above.) :::

Create a custom style​

A custom style is a Markdown file: frontmatter, then the instructions to append to the system prompt. Save it at the user level (~/.claude/output-styles/), the project level (.claude/output-styles/), or as managed policy (.claude/output-styles/ inside the managed settings directory); the file name becomes the style name unless you set name. Plugins can ship styles in an output-styles/ directory too.

Example custom style — Diagrams first

---
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.
Pro tip
  • Set keep-coding-instructions: true when you're only changing HOW Claude communicates but still want it coding normally.
  • Leave it out (the default) when Claude isn't doing software engineering at all — say, a pure writing or data-analysis assistant — so the built-in coding instructions are dropped.

Output styles vs CLAUDE.md vs other levers​

  • Output style = a system-prompt preset for role, tone, and format — applies to every response.
  • CLAUDE.md = persistent project facts and rules (conventions, guardrails), added as a message after the system prompt.
  • Custom instructions / response styles = the Claude.ai consumer-app cousin.

:::tip Use the right lever Want Claude to "always run tests before finishing"? That's a CLAUDE.md guardrail, not a style. Want it to "explain each step as you go"? That's an output style. Keep behaviour rules in CLAUDE.md and presentation in styles. :::

Check yourself

0/5
  1. What does an output style actually change?
  2. Which built-in style leaves [TODO(human)] markers and asks you to write small pieces yourself?
  3. After changing the output style, when does it take effect?
  4. You want Claude to 'always run tests before finishing.' Which lever is that?
  5. When should you set keep-coding-instructions: true in a custom style?
Key takeaways
  • Output styles change HOW Claude communicates (role, tone, verbosity), not WHAT it knows — they edit the system prompt.
  • Four built-ins: Default (action-first), Proactive (executes with assumptions), Explanatory (adds Insights), Learning (Insights + [TODO(human)] markers).
  • Explanatory and Learning cost more output tokens because responses are longer by design.
  • Switch via /config (saved to .claude/settings.local.json) or the outputStyle setting — changes need /clear or a new session.
  • Custom styles are Markdown files in ~/.claude/output-styles/ or .claude/output-styles/; use keep-coding-instructions: true to keep coding behaviour.
  • Use CLAUDE.md for behaviour rules/guardrails and output styles for presentation.

Next​