Output Styles and Formatting Control

You ask Claude Code to fix a bug. It fixes the bug. Then it writes six paragraphs explaining what a bug is, the history of debugging, and the philosophical implications of error handling. You scroll past all of it, find the one line that actually changed, and close your eyes for a moment.

Output styles exist to stop this. They control how Claude Code responds, not just what it does.

Built-in Output Styles

Three ship out of the box.

Default is standard software engineering mode. Claude Code acts like a capable dev, explains what it did, shows relevant code, moves on. Perfectly fine for most work.

Explanatory adds educational context. After making changes, Claude Code includes "Insights" sections explaining why it made specific choices and what codebase patterns it noticed. Really useful when you're navigating an unfamiliar codebase and want to learn the architecture while shipping.

Learning flips the dynamic entirely. Instead of doing everything, Claude Code works collaboratively and drops TODO(human) markers where you should implement things yourself. It sets up scaffolding and leaves you to fill in the gaps. Great if you're a junior dev or just picking up a new language.

Under the hood, each style modifies Claude Code's system prompt. They all exclude the default instructions that push for concise output, so each style has room to shape responses its own way.

Switching Styles

Two ways to change mid-session:

# Opens a selection menu
/output-style
 
# Sets a specific style directly
/output-style explanatory

Your choice saves to .claude/settings.local.json at the project level. Persists between sessions, so you set it once and forget about it.

You can also set the outputStyle field in your settings file directly if you want different styles per project without switching manually.

Custom Output Styles

The built-in ones are fine. Writing your own is more fun.

Custom styles are Markdown files with frontmatter. Two locations:

• ~/.claude/output-styles/ for global styles (all projects)
• .claude/output-styles/ inside a project for project-specific ones

A custom style file looks like this:

---
name: Terse Diff
description: Show only what changed, nothing else
keep-coding-instructions: true
---
 
# Terse Diff Style
 
You respond with ONLY the changes you made. Format:
 
1. File path
2. A brief one-line summary of the change
3. Nothing else
 
Do not explain why. Do not suggest next steps.
Do not show unchanged code. No filler.

Three frontmatter fields:

• name: What shows up in the /output-style menu
• description: Short explanation of what the style does
• keep-coding-instructions: Whether to preserve Claude Code's default coding behavior alongside your style. Defaults to false, meaning your style replaces the coding parts of the system prompt

Pay attention to that last one. If your style is purely about formatting ("be terse"), set it to true so Claude Code still knows how to write good code. If your style redefines the whole interaction model (a review-only mode, say), leave it false.

Try it

Create ~/.claude/output-styles/code-only.md:

---
name: Code Only
description: Zero prose, just code changes
keep-coding-instructions: true
---
 
# Code Only
 
Show ONLY code blocks. No explanations before or after.
If you need to communicate something critical (like a
breaking change), use a single-line code comment.

Run /output-style, select "Code Only," make a request. Watch the response shrink. Every token goes toward actual code instead of narration.

When to Use What

Output styles aren't the only formatting lever. The distinctions matter:

Output styles vs CLAUDE.md. Styles modify the system prompt. CLAUDE.md content gets injected as a user message after the system prompt. For global behavior changes ("always be concise"), styles hit harder. For project-specific rules ("always run tests after changes"), CLAUDE.md is the right place.

Output styles vs --append-system-prompt. Styles replace parts of the default prompt. The append flag adds to it. One-off additions go through the flag.

Output styles vs Skills. Styles stay active the entire session. Skills fire once. "Always respond tersely" is a style. "Run this review checklist right now" is a skill. Don't mix them up.

For simpler formatting preferences you might not need a custom style at all. CLAUDE.md rules handle a lot:

- Be concise. No filler words.
- Show only code changes, not explanations.
- End with a brief summary of what changed and why.
- Use bullet points, not paragraphs.
- Never repeat the task description back to me.

These rules apply every session without style switching and stack with whatever output style is active.

The pattern I like best: Default output style plus strict formatting rules in CLAUDE.md. Standard coding behavior, your preferred response format. No custom style file needed for basic preferences.

What Matters

Three built-in styles: Default (balanced), Explanatory (educational), Learning (collaborative with TODO(human) markers). Custom styles are Markdown files with frontmatter in ~/.claude/output-styles/ or .claude/output-styles/. Set keep-coding-instructions: true when your style only changes formatting, not behavior, so Claude Code doesn't forget how to write code.

CLAUDE.md formatting rules handle simple preferences and stack with active styles. Use Explanatory when learning a codebase, a terse custom style during rapid iteration, Default for everything else.