Claude Code Output Styles and Custom Formats

Claude Code output styles change how the tool behaves at the system prompt level, not just how it formats a single reply. If you have ever wanted Claude Code to stop defaulting to "write code fast and move on" and instead explain every decision, review changes like a strict senior engineer, or write documentation in your team's house style, output styles are the mechanism built for that. This guide covers what output styles actually change, the built-in options, how to write your own, and where they fit next to CLAUDE.md and other customization tools.

What Claude Code output styles actually control

An output style is a swap-in replacement for parts of Claude Code's default system prompt. The default system prompt is heavily tuned for one job: writing and editing code efficiently, with minimal narration, inside a software engineering workflow. That tuning is useful when you want commits shipped quickly, but it gets in the way the moment you want Claude Code to behave like a tutor, a reviewer, or a writer.

Switching output styles replaces the parts of the system prompt that enforce that "terse coding agent" persona while keeping everything else that makes Claude Code Claude Code: full tool access, file editing, bash execution, subagents, hooks, and MCP servers. You are not losing capability when you switch styles, you are changing the voice and priorities Claude Code applies while using those capabilities.

This is the key distinction to hold onto: an output style changes *how Claude Code thinks and talks about the work*, not *what it is allowed to do*. A "Teaching" style and the default style can both run the same bash command and edit the same file. The teaching style will just stop and explain why first.

Built-in output styles

Claude Code ships with a small set of ready-made styles you can switch into immediately, no setup required.

• Default: the standard software-engineering-focused behavior, optimized for completing coding tasks efficiently with concise responses.
• Explanatory: Claude Code pauses to share "Insight" asides that explain the reasoning behind implementation choices, trade-offs it considered, and patterns in the codebase, while still doing the work.
• Learning: a more collaborative mode intended for pairing. Claude Code shares insights like Explanatory mode, but also asks you to contribute small pieces of code yourself, marking spots with TODO(human) comments so you write a chunk of the logic instead of Claude Code doing 100% of it.

These cover the two most common asks: "explain what you're doing" and "let me actually learn something while you help." For anything more specific, custom output styles.

Switching output styles

The fastest way to change styles is the slash command built for it:

/output-style

Running it with no arguments opens a menu of available styles (built-in plus any custom ones you've created) so you can pick interactively. You can also jump straight to one:

/output-style explanatory
/output-style learning
/output-style default

The active style is saved in your project's local settings, so it persists across sessions for that project. Switching styles does not touch your conversation history or in-flight work, it only changes the system prompt used for future turns.

Creating a custom output style

This is where output styles earn their keep. Say your team wants Claude Code to act as a strict code reviewer for one project: flag every unhandled error, refuse to approve missing tests, and never write "looks good" without justification. Or you run a documentation-heavy repo and want Claude Code to default to writing in a specific tone whenever it touches markdown files. A custom output style encodes that once, instead of repeating instructions in every prompt.

The easiest path is to let Claude Code generate the style for you:

/output-style:new I want an output style that acts as a strict senior code reviewer. It should flag missing error handling and missing tests before approving any change, explain the risk of each issue in one sentence, and never say a change is ready to merge without listing what was checked.

Claude Code will draft a style based on that description, save it, and you can then activate it with /output-style. This is usually the fastest path because you get a working starting point in one shot, and you can then open the generated file and hand-edit anything that doesn't quite match what you wanted.

You can also write one by hand. Output styles are just markdown files with YAML frontmatter, similar in shape to a CLAUDE.md file or a custom slash command. Project-level styles live in .claude/output-styles/, and user-level styles (available across every project) live in ~/.claude/output-styles/.

A minimal custom style file looks like this:

---
name: Strict Reviewer
description: Reviews code changes like a demanding senior engineer, refuses to wave through missing error handling or missing tests
---

You are operating as a strict senior code reviewer inside Claude Code.

For every code change, before considering it done:
- Confirm error handling exists for every external call (network, file system, database)
- Confirm there is at least one test covering the new behavior
- State explicitly which of the above you checked and what you found
- If either is missing, say so plainly and do not proceed until it is fixed or the user overrides you

Keep tone direct. Do not soften findings with unnecessary praise. Do not say a change is "ready to merge" without listing exactly what you verified.

Save that as .claude/output-styles/strict-reviewer.md, run /output-style, and select it. From that point on, in that project, Claude Code applies this persona on top of its normal tool access.

A documentation-focused style might look different in tone but the same in structure:

---
name: Docs Writer
description: Writes and edits documentation in plain, example-driven style with runnable code blocks
---

You are writing and editing documentation, not shipping features.

Rules:
- Every explanation of a concept needs a runnable code example immediately after it
- Avoid marketing language and hedging phrases like "you may want to consider"
- Prefer short paragraphs over long ones
- When editing existing docs, preserve the existing heading structure unless asked to restructure
- Flag any claim you are not fully sure is accurate rather than guessing

Save that one as .claude/output-styles/docs-writer.md in a docs repo and switch to it whenever you're on a documentation task, then switch back to default for feature work.

Editing, listing, and resetting output styles

Once you have more than one or two custom styles, a few housekeeping habits keep things manageable.

To see what's available, run /output-style with no argument. The menu lists built-in styles alongside any custom ones found in both .claude/output-styles/ and ~/.claude/output-styles/, so you can confirm a new file was picked up correctly before trying to activate it.

To edit an existing style, just open its markdown file directly with your normal editor, or ask Claude Code itself to edit it: "open .claude/output-styles/strict-reviewer.md and add a rule about flagging unhandled promise rejections." Since the file is plain markdown, this works the same way as editing any other project file, and changes take effect the next time you activate that style, no restart required.

To reset back to normal behavior, switch back with:

/output-style default

This is worth doing explicitly at the end of a specialized session rather than assuming the next session starts fresh. Because the active style is saved in project settings, it persists across restarts of Claude Code in that project until you change it again. If you leave a strict-reviewer style active and come back the next day to write a quick feature, you'll get review-mode pushback on ordinary work until you switch back.

If a style stops showing up in the menu, the usual cause is a malformed YAML frontmatter block, most often a missing closing --- or a name field that doesn't match the filename convention Claude Code expects. Fixing the frontmatter and re-running /output-style resolves it.

Project-level versus user-level output styles

Where you save a style file determines its scope.

• .claude/output-styles/ inside a project makes the style available only in that project, and it's natural to commit it to version control so the whole team gets the same reviewer or writer persona.
• ~/.claude/output-styles/ in your home directory makes the style available in every project on your machine, useful for personal habits like "always explain your reasoning" that you want regardless of which repo you're in.

If a project-level and user-level style share a name, the project-level one takes precedence for that project. This mirrors how CLAUDE.md works: project settings layer on top of user-level defaults.

Output styles versus CLAUDE.md

These two get confused constantly, and the confusion matters because they solve different problems.

CLAUDE.md is additive. It appends project context, conventions, and instructions on top of the existing default system prompt. Claude Code still behaves like the standard coding agent, it just now also knows your test command, your folder layout, and your team's naming conventions. Most projects should have a CLAUDE.md, and most projects do not need a custom output style.

An output style is substitutive. It replaces the behavioral core of the system prompt: the parts that say "be concise," "focus on completing the coding task," and similar directives. That is a much bigger lever, and it is the right tool when you want a fundamentally different mode of operation, not just more context.

A practical rule: if you find yourself repeating the same behavioral instruction ("explain your reasoning first," "never skip test coverage," "write in a formal tone") at the start of every session in a project, that is a signal to promote it into an output style instead of retyping it. If you're repeating factual context ("we use pnpm," "tests live in __tests__"), that belongs in CLAUDE.md.

They compose together. CLAUDE.md still loads and still applies regardless of which output style is active, so you get both the persona shift and the project facts in the same session.

Output styles versus subagents

Subagents (defined in .claude/agents/) and output styles both let you specialize Claude Code's behavior, but they operate at different scopes and for different lifetimes.

A subagent is invoked for a specific delegated task, runs in its own context window, has its own tool permissions, and reports back a result. You reach for a subagent when you want isolated, parallelizable work, like "review this diff" or "find every place this function is called," without polluting your main conversation's context.

An output style changes the main conversation's own system prompt for as long as it stays active. There is no separate context window, no delegation, no report-back step. You are talking directly to Claude Code, just with a different personality and priority set.

A good mental model: output styles change who you're talking to. Subagents change who does the work while you keep talking to the same "you."

You can combine them. A "Docs Writer" output style in your main session can still dispatch a subagent to grep the codebase for undocumented functions, get the results back, and continue writing in its docs-writer voice.

Output styles versus the append-system-prompt flag

If you only need a one-off tweak for a single command-line invocation, rather than a saved, reusable style, Claude Code also supports passing system prompt additions directly as CLI flags when you launch a session. That approach is useful for scripting and CI, where you might spin up a short-lived Claude Code process with a very specific one-time instruction and never need it again.

Output styles are the better choice when the persona is something you'll reuse across sessions, want teammates to also have access to, or want to switch between mid-session with a slash command instead of restarting the process. If the instruction is truly one-shot, a flag is simpler than creating a file.

Practical use cases worth setting up

Code review gatekeeping. Teams that want Claude Code to act as a second reviewer before a human looks at a PR benefit from a strict-reviewer style that refuses to sign off on missing tests or error handling, as shown above. This turns "please double check this" into a repeatable, always-on habit rather than something you have to remember to ask for.

Onboarding and pairing. The built-in Learning style, or a custom variant of it, is worth switching to when a junior engineer is working through a codebase with Claude Code. Forcing TODO(human) checkpoints keeps them actively writing code instead of only reviewing generated diffs, which is a real difference for skill-building.

Documentation-only sessions. A docs-writer style prevents Claude Code from slipping into "let me also refactor this function while I'm here" behavior when all you wanted was better comments and a cleaner README.

Incident response. A terse, action-first output style that skips explanations and gets straight to diagnosis-and-fix can be useful during an outage, where narration is overhead you don't have time for.

Style-guide enforcement. If your organization has a specific voice for user-facing copy, commit messages, or API documentation, encoding that voice into an output style means every engineer who runs Claude Code in that repo produces output that already matches house style, instead of everyone prompting it differently.

Common mistakes to avoid

Do not put project facts inside an output style. Facts like directory structure, build commands, and dependency versions belong in CLAUDE.md, where they get read on every session regardless of which style is active. If you bury them inside a style file, they disappear the moment someone switches back to default.

Do not write an output style that contradicts Claude Code's core safety and tool-use behavior. Output styles change tone and priorities, not permissions. Attempting to use one to bypass confirmations or expand what tools can do is not what the feature is for, and it will not reliably work that way since permission and safety behavior sit outside the swappable portion of the prompt.

Do not create a new style for every small tweak. If two styles differ only in tone with no behavioral difference, you probably only need one style plus a short reminder in your prompt. Reserve custom styles for genuinely different modes of operating, otherwise the menu from /output-style becomes cluttered and nobody remembers which one does what.

Do not forget to commit project-level styles. A style saved only in ~/.claude/output-styles/ on your machine will not show up for teammates who clone the repo. If the style is meant to be a team standard, it belongs in .claude/output-styles/ and in version control.

Do not write vague instructions and expect precise behavior. "Be more careful" is a weaker style instruction than "confirm test coverage exists for every new function before saying the task is done." Output styles work the same way any system prompt engineering works: specific, checkable instructions produce more consistent behavior than general vibes. If you notice a custom style behaving inconsistently, the fix is usually to tighten the wording, not to abandon the approach.

Rolling out output styles across a team

If you're introducing output styles to a team rather than just your own workflow, treat them like any other shared engineering convention. Start with one style that solves a real recurring friction point, such as PR review rigor or documentation tone, rather than building a full library up front. Put it in .claude/output-styles/, commit it alongside a short note in your README or CONTRIBUTING file explaining when to use it, and let engineers opt in with /output-style <name> as they find it useful.

Resist the urge to make a style mandatory by default for every session. Output styles work best as a deliberate choice for a specific kind of task, not as a blanket replacement for the default coding behavior most work still needs. A repo that forces a strict-reviewer or documentation-only style on every session will frustrate engineers doing ordinary feature work who now have to fight the persona to get a quick change shipped.

FAQ

Does switching output styles lose my conversation history? No. Switching styles only changes the system prompt applied to future turns. Your existing conversation, file edits, and context stay intact.

Can I use output styles and CLAUDE.md at the same time? Yes, and you should. CLAUDE.md's project context loads regardless of which output style is active. They are complementary: CLAUDE.md adds facts, output styles change behavior and tone.

Do output styles restrict which tools Claude Code can use? No. Output styles change the system prompt's guidance on tone, priorities, and workflow. Tool access and permissions are governed separately, through settings and permission rules, not through the output style file.

Where should I save a custom output style if I want my whole team to use it? Save it under .claude/output-styles/ inside the project and commit it to your repository. Anything under ~/.claude/output-styles/ only applies on your own machine.

What's the difference between the Explanatory and Learning built-in styles? Explanatory adds "Insight" explanations of design decisions while Claude Code still does all the implementation itself. Learning does the same, but also leaves small TODO(human) sections for you to implement, so you get hands-on practice instead of only reading explanations.

Can I have multiple custom output styles and switch between them per task? Yes. Create as many as you need and switch with /output-style <name> whenever the task changes, for example moving from a strict-reviewer style during a PR review to a docs-writer style right after.

Is an output style the right tool for changing Claude Code's response length or format only? For something that small, a direct instruction in your prompt or a short note in CLAUDE.md is usually enough. Reserve custom output styles for larger behavioral shifts you'll reuse repeatedly, not one-line formatting preferences.