Claude Code ships with a default voice: terse, task-focused, minimal explanation. That's correct for most sessions. But not every session is "just get it done." Sometimes you're pairing with a junior engineer who needs the reasoning spelled out. Sometimes you're the junior engineer and you want Claude to teach, not just execute. Output styles solve this without you having to re-explain your preferences in every prompt.
An output style is a persistent, swappable system-prompt layer. It changes how Claude communicates — verbosity, teaching behavior, formatting — without touching what Claude is allowed to do (that's still permission modes) or what it knows about your project (that's still CLAUDE.md). Three different concerns, three different mechanisms. Mixing them up is the #1 source of confusion here.
Output Styles vs. CLAUDE.md vs. Permission Modes
These three get conflated constantly. They're not interchangeable:
- Output styles — controls how Claude talks: verbosity, explanation depth, tone. Swappable per session.
- CLAUDE.md — controls what Claude knows: project conventions, architecture, commands. Persistent context.
- Permission modes — controls what Claude can do: which tools run without approval. Safety boundary, not a communication style.
You can run any output style with any permission mode with any CLAUDE.md. They're orthogonal. A common mistake is writing "please explain your reasoning in detail" into CLAUDE.md — that bloats context on every single session, including the ones where you just want the task done. Output styles keep that preference out of your persistent project memory and let you toggle it per session instead.
The Built-In Styles
Claude Code ships with three styles out of the box:
- Default — concise, action-first. Minimal narration between tool calls. This is what you want for routine engineering work once you trust the agent.
- Explanatory — Claude narrates its reasoning and calls out non-obvious decisions as it works. Useful when reviewing unfamiliar code, debugging something subtle, or when you need an audit trail of why a change was made a certain way.
- Learning — Claude pauses at meaningful decision points and asks you to make small implementation choices yourself, then explains the tradeoffs. Built for skill-building, not throughput. Slower, intentionally.
Switch between them mid-session with:
/output-styleThis opens a picker. No restart needed — the style change applies to the next response.
Building a Custom Output Style
The built-in three won't cover every workflow. Custom styles live as markdown files:
- Personal (all projects):
~/.claude/output-styles/ - Project-scoped (checked into the repo, shared with the team):
.claude/output-styles/
Scaffold one with the slash command instead of hand-writing the file:
/output-style:newDescribe what you want in plain language — Claude Code generates the style file for you. Or write it directly. The format is a markdown file with frontmatter:
---
name: Code Reviewer
description: Adversarial review mode — assumes every diff has a bug until proven otherwise
---
You are reviewing code, not writing it for the first time. Default to skepticism:
- For every function touched, ask "what input breaks this?" before moving on
- Flag any error handling that swallows exceptions silently
- Call out missing test coverage explicitly, don't just note it in passing
- If a diff looks too simple for the stated problem, say so — that's usually a sign
the real fix is somewhere else
- Never say "looks good" without listing what you actually checked
Save that as .claude/output-styles/code-reviewer.md, run /output-style, and it shows up alongside the built-ins. Team members who pull the repo get it automatically since it's project-scoped.
Practical Style Ideas
| Style | When to use it |
|---|---|
| Terse ops mode | Production incident response — status updates only, no narration |
| Onboarding guide | New hires exploring an unfamiliar codebase, explain-heavy |
| Migration auditor | Large refactors — force Claude to list every file touched and why, before and after each batch |
| Socratic reviewer | PR review — ask questions about design choices instead of dictating fixes |
| Client-facing summary | Generate plain-English changelogs for non-technical stakeholders |
What Output Styles Don't Do
Worth being precise about the boundaries:
- They don't grant or restrict tool access — that's
/permissionsand permission modes. - They don't inject project-specific facts (build commands, architecture, conventions) — that's still CLAUDE.md's job. Putting persistent project knowledge in an output style means it only applies when that style is active, which is the wrong scope for facts that should always be true.
- They don't persist across projects unless you put them in the personal
~/.claude/output-styles/directory. - They're not a jailbreak. An output style asking for more explanation doesn't loosen any safety or permission behavior — Claude Code enforces those separately.
A Simple Decision Rule
Before reaching for a custom output style, ask: is this preference about how information is communicated, or what Claude knows/can do? If it's the former, it's an output style. If it's the latter, it belongs in CLAUDE.md or your permission config. Getting this right keeps each mechanism doing one job, which is the whole point of having three separate systems instead of one overloaded system prompt.
Team Rollout
If you're standardizing output styles across a team, commit them to .claude/output-styles/ in the repo rather than asking each engineer to maintain their own copy in ~/.claude/output-styles/. Project-scoped styles travel with the codebase, show up automatically after git pull, and stay in sync the same way CLAUDE.md does. Reserve the personal directory for styles that are about your individual workflow, not the team's.