Claude Code Output Styles: A Practical Guide

What output styles are and why they matter

An output style in Claude Code changes how the agent communicates and, to a degree, how it approaches work, by swapping the system prompt that shapes its behaviour. The default style is tuned for software engineering: terse, action-oriented, light on explanation, heavy on doing. That is exactly what you want when you are shipping code. It is exactly what you do not want when you are trying to learn a codebase, write a design document, or have the agent teach you something as it works.

Output styles let you switch that posture without editing your project files. Claude Code ships with a few built-in styles, and you can author your own as small Markdown files. Switching is a single command, and the change applies to the current session, so you can move from "just do it" mode to "explain everything" mode and back as the task demands.

The reason this is worth understanding properly, rather than treating it as a cosmetic toggle, is that the communication posture genuinely changes the work. An agent told to be a patient teacher will narrate its reasoning, surface alternatives, and check understanding. The same agent in default mode will make the change and move on. For some tasks the first is far more valuable; for others it is noise. Choosing deliberately is the difference between an agent that fits the task and one that fights it.

This guide covers the built-in styles, how to switch them, how to write a custom style, worked examples for real situations, the pitfalls that catch people, and when to reach for a style versus a CLAUDE.md rule or a subagent.

The built-in styles

Claude Code ships with a small set of styles out of the box. The exact roster evolves, so check the in-app list, but the shape is consistent:

• Default is the standard software-engineering posture: concise, focused on completing the task, minimal commentary. This is the right default for almost all hands-on-keyboard development.
• Explanatory keeps the agent doing the work but adds running commentary: why it chose an approach, what a piece of code does, what the trade-offs are. Useful when you want to understand the changes as they land rather than just receive them.
• Learning goes further toward teaching. The agent works more collaboratively, explains concepts, and may leave small exercises or prompts for you to fill in, so you build understanding rather than just accept output.

To see the styles available in your install:

/output-style

Run with no argument, this lists the available styles and shows which is active. It is the fastest way to confirm what you have before switching.

How to switch styles

Switching is a slash command. To activate a style for the current session:

/output-style explanatory

The change takes effect immediately and persists for the rest of the session (and is remembered for the project, so a new session in the same project starts in the style you last selected). To return to the standard posture:

/output-style default

Because the switch is per-session and per-project rather than global, you can run one project in learning mode while another stays in default mode. There is no need to edit any file to flip between them mid-task; the command is the whole interface.

A useful habit: switch to an explanatory or learning style at the start of a session where the goal is understanding (a new codebase, a tricky bug you want to reason through together), and switch back to default the moment you move into execution. The styles are cheap to change, so match the style to the phase of work you are in.

Writing a custom output style

The built-in styles cover the common axes (terse vs explanatory vs teaching), but the real power is authoring your own. A custom output style is a Markdown file with frontmatter, stored where Claude Code looks for styles: ~/.claude/output-styles/ for styles available everywhere, or .claude/output-styles/ inside a project for styles scoped to that project.

The file structure is a name and description in frontmatter, followed by the instructions that become the agent's behavioural prompt:

---
name: Code Reviewer
description: Reviews code critically without making edits, focused on correctness and clarity
---

# Code reviewer style

You are acting as a senior code reviewer. Your job is to evaluate, not to edit.

## Behaviour
- Do NOT modify files unless explicitly asked. Your output is review, not changes.
- Read the relevant code thoroughly before commenting.
- Organise feedback into: Correctness, Clarity, and Suggestions.
- For each issue, cite the file and line, explain why it matters, and propose a fix in words.
- Lead with the most important issues. Skip nitpicks unless asked for a thorough pass.
- If the code is solid, say so plainly rather than inventing problems.

## Tone
- Direct and specific. No vague praise, no vague criticism.
- Assume the reader is an experienced engineer who wants the truth.

Save that as ~/.claude/output-styles/code-reviewer.md and it becomes selectable:

/output-style code-reviewer

Now the agent reviews rather than edits, with a consistent structure, until you switch back. The value is that you have captured a working posture once and can summon it on demand across every project.

A second example, a documentation-writing style, shows a different posture entirely:

---
name: Docs Writer
description: Writes clear technical documentation in prose, prioritising the reader over the implementation
---

# Documentation writer style

You write documentation for developers who need to use this code, not maintain it.

## Behaviour
- Write in clear prose. Code blocks support the explanation; they do not replace it.
- Start with what the reader is trying to do, then show how.
- Define every term the first time it appears.
- Prefer one worked example over three abstract descriptions.
- Never write a placeholder like "TODO" or "more details to come"; if you do not know, say what you would need to find out.

## Tone
- Plain, calm, and precise. No marketing language. No exclamation marks.

These two files turn one agent into two specialists you can switch between with a command.

Worked example: pairing a style with a task

Output styles are most useful when you match them to the kind of session you are starting. Three concrete pairings:

Onboarding to an unfamiliar codebase. You have just cloned a large repo and need to understand it before changing anything. Switch to an explanatory or learning style so the agent narrates what it finds as it reads, explains the architecture, and surfaces the parts that will bite you later.

/output-style explanatory

Then ask it to walk you through the request lifecycle or the data model. The commentary is the point; in default mode you would get a terse summary and miss the reasoning.

A focused review before a release. You want a critical pass over a diff with no edits. Activate the custom code-reviewer style above so the agent evaluates rather than touches anything, and structures its feedback consistently.

/output-style code-reviewer

Back to shipping. Once you understand the code or have the review, switch back to default and execute. The default style's terseness is now an asset, not a limitation.

/output-style default

The skill is not in any single style; it is in changing styles as the work changes phase. A session that stays in learning mode while you are trying to ship is as mismatched as a session that stays in default mode while you are trying to learn.

Pitfalls

A few failure modes catch people who treat styles as a set-and-forget setting.

Forgetting which style is active. Because a style persists for the project, you can start a new session, wonder why the agent is unusually chatty or unusually terse, and not realise a style from last week is still active. When behaviour feels off, run /output-style with no argument to see what is set, and reset to default if you are not sure.

Using a style to encode project rules. A style changes communication posture; it is not the place for project-specific facts and constraints. Putting "use pnpm not npm" or "the database is Postgres" into an output style is the wrong layer, because the style is about how the agent talks and works in general, not what is true about this project. Those facts belong in your CLAUDE.md memory file, which loads regardless of style.

Over-engineering the style file. A long, elaborate style prompt competes with the actual task for the agent's attention and can make behaviour less predictable. Keep custom styles short and focused on one clear posture. If you find yourself writing paragraphs of edge cases, you probably want a subagent with its own full prompt, not an output style.

Expecting a style to grant new capabilities. A style shapes behaviour; it does not add tools or permissions. A "code reviewer" style that says "do not edit files" is a behavioural instruction the agent will follow, but it is not a hard guarantee. If you need an actual enforcement boundary (the agent must not run a destructive command), that is a job for permission rules and hooks, not a style.

When to reach for a style versus the alternatives

Output styles overlap with two other configuration surfaces, and knowing which to use keeps your setup clean.

Use an output style when the thing you want to change is the agent's communication posture or general working approach for a stretch of work: teach me as you go, review don't edit, write prose not bullets. Styles are session-level and switchable, which makes them right for "I am in a different mode now."

Use a CLAUDE.md rule when the thing you want to change is a fact or constraint about the project that should always apply: the package manager, the test command, the directories that are off-limits, the conventions to follow. These load every session regardless of style. Our setup guide and memory setup cover how to structure them.

Use a subagent when the thing you want is a specialised worker with its own full prompt, its own tools, and the ability to run as a separate context that reports back: a dedicated test-writer, a security reviewer, a research agent. A subagent is heavier than a style and worth it when the role is a genuine specialist you invoke for a defined job rather than a posture you switch into.

The clean mental model: CLAUDE.md is what is true about the project, a subagent is a specialist you delegate to, and an output style is the mode the main agent is in right now. Output styles are the lightest of the three, which is exactly why they are the right tool for "shift how we are working for the next hour" and the wrong tool for everything more permanent.

Putting it together

Output styles are a small feature with an outsized effect on how a session feels and how well it fits the task. The built-in default, explanatory, and learning styles cover the common axis from terse execution to patient teaching. Custom styles, stored as short Markdown files in ~/.claude/output-styles/ or .claude/output-styles/, let you capture a working posture once (reviewer, docs writer, anything) and summon it with a single command.

The practitioner habit worth building is to switch styles as the work changes phase: explanatory while you learn, a focused custom style while you review, default while you ship. Keep the facts about your project in CLAUDE.md, reserve subagents for genuine specialists, and use output styles for the one thing they do best, which is changing the mode the agent is in to match the mode you are in.

Get Claudify. Custom output styles, a structured CLAUDE.md, and ready-made subagents, configured so Claude Code fits every phase of your work out of the box.