What Is Output Styles? A Complete Guide to Claude Code’s Output Style Configuration and Customization

What Is Output Styles?

Output Styles is a Claude Code configuration feature that swaps the agent’s behavior, tone, and response shape on demand. It ships with several built-in styles (default, Explanatory, Learning) and lets you create your own with a small Markdown file. Switching styles changes how Claude responds without changing which Claude model you are talking to.

Think of it as having Claude change jackets between meetings. The brain is the same — Sonnet 4.6, Opus 4.6, or Haiku 4.5 — but the persona, verbosity, and process change to fit the situation. Important: in practice, teams use different styles for onboarding, code review, technical writing, and customer-facing demos. The key idea is that you decouple the agent’s “what model” from its “how it responds” — and that turns out to be one of the highest-leverage controls in a long-running coding agent.

How to Pronounce Output Styles

How Output Styles Works

Internally, Output Styles substitutes a portion of the system prompt that Claude Code sends to the model. The active style is recorded in settings.json under the outputStyle key, and the user can change it at any time with the /output-style slash command. The change takes effect on the next message — there is no model reload, no extra latency, and no incremental token cost beyond a normal prompt swap.

Pipeline

Important to remember: Output Styles is a system-prompt-level control, not a model-level control. The same Sonnet 4.6 will produce dramatically different output under Explanatory versus default, but the underlying capabilities (reasoning, tool use, context window) are unchanged.

Built-in Output Styles

Output Styles Usage and Examples

The simplest interaction is the /output-style slash command inside Claude Code. It lists the available styles and lets you pick one with the arrow keys. Important: keep in mind that the change persists across messages until you switch again.

Switching styles via slash command

# Run inside a Claude Code session
/output-style

# UI shows:
# > default
#   Explanatory
#   Learning

Pinning a style per project

If you want a fixed style for a repository, write it into .claude/settings.json at the project root and commit it. Every clone of the repository will then default to that style.

{
  "outputStyle": "Explanatory"
}

Authoring a custom style

Custom styles are just Markdown files placed in ~/.claude/output-styles/ (user-level) or .claude/output-styles/ (project-level). The YAML frontmatter declares the name and description; the body becomes part of the system prompt.

---
name: code-review
description: Senior-engineer code review style
---

You are a senior engineer with a decade of production experience.
For every snippet the user shares, review it for:

- Readability
- Maintainability
- Security concerns
- Performance implications

Reply with a short bulleted list and concrete fixes. Avoid praise.

Once saved, the file shows up in /output-style as code-review and can be selected like any built-in style. Important: in practice, teams keep a small library of styles — review, doc-writer, test-generator, refactor — and switch between them based on the current task.

Advantages and Disadvantages of Output Styles

Advantages

• Same model, different behavior — Avoid switching to a smaller or larger model just to change tone. Note that this saves both time and budget.
• Shareable across teams — Commit styles to the repository so onboarding engineers, senior engineers, and reviewers all pull the same conventions automatically.
• Trivial to author — A Markdown file is all you need. No code, no compilation, no plugin installation.
• Instant switching — There is no model reload, so style changes apply on the very next prompt. You should treat this as a friction-free control.
• Composable with Hooks and CLAUDE.md — Styles cover behavior, CLAUDE.md covers project knowledge, Hooks cover deterministic actions. Together they form a layered configuration model.

Disadvantages

• Instruction collisions — Custom styles can contradict instructions in CLAUDE.md or installed Skills, and the resulting behavior is hard to predict. Important to remember: keep responsibilities separated.
• Style sprawl — A team that authors twenty styles ends up with no styles, because nobody knows which to choose. Treat the style catalog like API surface and prune ruthlessly.
• Cannot exceed the model’s ceiling — A style cannot make Haiku produce Opus-level reasoning. It changes how the model speaks, not how it thinks. Note that you should still pick the right model for the job.
• Hidden in chat history — When reading back a session, you may not be able to tell which style was active for which turn. You should consider logging the style transitions explicitly.

Output Styles vs Related Mechanisms

Output Styles is often confused with CLAUDE.md, Skills, and a raw API system prompt. The differences matter because each layer has a different scope and lifecycle.

In practice, you should put project knowledge in CLAUDE.md, ergonomic switching of personas in Output Styles, and concrete procedures (like “build a PDF”) in a Skill. Note that you should keep in mind: layering them is fine, but duplicating instructions across layers will confuse the agent.

Common Misconceptions

Misconception 1: Output Styles changes the model

It does not. The model selection is orthogonal — set it via the model key in settings, the /model command, or per-call API parameters. Important: changing the style on Sonnet 4.6 keeps you on Sonnet 4.6.

Misconception 2: You can declare tools or MCP servers inside a style file

Wrong. Output Styles only contributes system-prompt text. Tools and MCP servers are configured separately in settings.json or via project-level configuration. You should treat the style file as text-only.

Misconception 3: Switching styles wipes the conversation

It does not. The session continues; only the system prompt for future turns changes. Note that you should keep in mind that earlier responses retain their original style — if uniform formatting matters, restart the session.

Misconception 4: Custom styles work on every Anthropic surface

They do not. Output Styles is a Claude Code feature. The Claude API, Claude.ai chat, and Claude Desktop have their own conventions. If you want consistent behavior across surfaces, encode the persona in code and inject it as a system prompt yourself.

Real-World Use Cases

Onboarding and senior engineers on the same model

You can run new hires on a custom onboarding style that explains motivation and design choices, while senior engineers stay on default for compact answers. The same Sonnet 4.6 backs both. This is a documented way to reduce questions in chat without forking infrastructure.

Documentation writing

A doc-writer style that says “no emojis, formal tone, headings included, code blocks for every snippet” makes long-form writing dramatically more consistent. Important: you should keep in mind that styles can also forbid bullets, which is useful for prose-heavy documentation.

Code review

A code-review style enforces a strict response shape — bullets for issues, code fences for fixes, no praise. Pair it with a Hook that triggers when a file is opened, and your review workflow becomes nearly automatic. Note that you should still read the suggestions critically.

Customer demos

Style files are useful when running an agent in front of a customer. A demo style with very strict response shapes and conservative tone reduces the chance of awkward output. You should keep this style locked behind project settings to prevent accidental swaps.

Pair programming with juniors

The built-in Learning style is a great starting point for juniors who want the agent to coach rather than dictate. After a few weeks, they can switch back to default for productivity.

Frequently Asked Questions (FAQ)

Q1. Where do I put style files?

User-level styles live in ~/.claude/output-styles/; project-level styles live in .claude/output-styles/ at the repository root. Project-level files override user-level ones with the same name. Important to remember: the file’s name in frontmatter is what shows up in /output-style.

Q2. Are styles versioned with the repo?

Yes, if you commit the .claude/output-styles/ directory. This is the recommended approach for shared styles. You should keep style files small and focused so reviews are easy.

Q3. Does switching styles cost extra tokens?

It costs roughly the same as a regular system prompt swap — negligible in most cases, because the style replaces an existing block rather than adding to it. Note that very long styles do increase prompt size, so keep them concise.

Q4. Can I bind a hotkey?

Not directly. The /output-style slash command is the supported entry point. Important: you can build a custom slash command that wraps style switching and adds extra logic if you need more.

Q5. Can a style call tools?

No. The style is text only. Tools and MCP servers are independent. Note that you should keep in mind that styles can encourage tool use (“always run tests after editing”) but cannot install or configure tools.

Q6. How do styles interact with subagents?

Subagents (launched via the Task tool) inherit the active Output Style by default unless overridden. Important: if your subagent should behave differently, set its style explicitly when you spawn it.

Authoring Tips

Good Output Styles are short. A page of guidance is usually more effective than ten pages, because the model already knows how to code and write — your style just nudges its emphasis. Treat the style file like a coaching note to a teammate: state the goal, the audience, the do’s and don’ts, and trust the model with the rest.

Important to remember: avoid contradictions with CLAUDE.md. If CLAUDE.md says “always include tests” and the style says “skip tests,” the agent will guess which to follow, and the answer is rarely the one you want. You should review styles alongside CLAUDE.md whenever either changes.

Finally, treat your style catalog as evolving software. Every quarter, audit which styles are actually used, prune the ones that are not, and document the rest. Note that this small piece of housekeeping pays dividends as the team grows.

Performance and Token Considerations

Output Styles substitutes a portion of the system prompt rather than appending to it, so the per-turn token cost stays roughly constant regardless of how many styles you have available. Important to remember: the only style currently consuming tokens is the active one. Idle styles sit on disk and have zero runtime cost.

That said, the active style still occupies system-prompt budget. A 4,000-character style can eat several hundred tokens that you might otherwise spend on context. You should keep in mind that this trade-off is real on long sessions, so prefer concise styles. If your style truly needs to be long, consider splitting the static knowledge into CLAUDE.md (which is cached separately) and keeping the style focused on tone and behavior.

Note that you should profile end-to-end. Switching from default to a custom 6-page style and watching latency or accuracy degrade is a clear signal to trim. Treat style length as a first-class budget alongside model choice and tool count.

Authoring Workflow Walkthrough

Here is a typical workflow for shipping a new shared style to a small team. First, identify a specific recurring need — say, “review my pull request and only flag real issues.” Second, draft a 30-line Markdown style file capturing that brief. Third, test it interactively by switching with /output-style and trying it on three or four representative cases. Fourth, commit the file under .claude/output-styles/ with a short README. Important: keep in mind that the README is what new joiners will read first, so explain when (and when not) to use the style.

You should treat the style file as living code. As reviewers find edge cases — false positives, missing categories, awkward phrasing — open small pull requests against the style. Note that diff-friendly Markdown is exactly the right format for this kind of iterative refinement, which is one reason Anthropic chose it.

Comparing Output Styles to External Prompt Libraries

Engineering teams that have been working with LLMs since 2023 often have an existing collection of system prompts — checked into a private repo, or hosted on internal platforms. Output Styles is not a replacement for those libraries; it is a delivery channel that integrates them with the rest of Claude Code. You should keep your prompt library in source control and treat each Output Style as a generated artifact.

Concretely, a small build script can read your canonical prompts from prompts/ and emit Markdown files into .claude/output-styles/ with the appropriate frontmatter. This keeps a single source of truth while letting Claude Code consume the result. Important to remember: the same prompts can be reused on the Claude API for backend services, so investing in a portable format pays off across surfaces.

Patterns From Production Use

After several months of production use across organizations, a few patterns repeat. Understanding them shortens the learning curve.

Style per persona, not per task. Teams that started with one style per task ended up with dozens of similar files. Switching to one style per persona (“reviewer,” “documenter,” “instructor”) collapsed the catalog and made selection obvious. Important: you should keep in mind that personas tend to be stable across years; tasks change every sprint.

Treat the active style as a context signal. When a teammate switches to code-review, they are signaling to the agent and to anyone reading the screen that they want a careful, slow, second-opinion answer. Make sure your style names communicate intent clearly, because the choice itself is part of the user interface.

Keep brand voice in CLAUDE.md, not in styles. Brand voice (e.g. “we never say ‘leverage'”) is project-wide and rarely changes. Putting it in CLAUDE.md keeps every style consistent. Note that you should keep in mind: this avoids the maintenance burden of duplicating brand rules across every style file.

Anti-Patterns to Avoid

The most common anti-pattern is burying tool instructions inside a style. Output Styles cannot grant or restrict tool access — only Claude Code’s settings and MCP configuration can. Telling a style “do not use Bash” creates a gap between your stated intent and what Claude Code actually allows; the model will eventually break the rule under pressure. You should configure tool access at the settings layer instead.

The second anti-pattern is ten-page styles that try to do everything. A style that simultaneously demands rigorous testing, a specific PR template, and three layers of explanation will rarely produce all three reliably. Important to remember: split the responsibilities — testing into a Hook, PR template into CLAUDE.md, explanation depth into the style.

The third anti-pattern is treating a style as a permanent fix. Styles are configuration, not code. If you find yourself repeatedly editing a style to handle the same edge case, that is usually a sign the underlying instruction belongs somewhere more robust — like a Skill that runs deterministic steps. You should reach for code, not prose, when behavior must be precise.

Roadmap and Ecosystem

Output Styles is one of the newer Claude Code primitives, and the ecosystem around it is still forming. Expect to see community-curated style collections published as plugins, integrations with code review tools, and tighter coupling with Subagents (so a Task-spawned subagent can run under its own style automatically). Important: you should subscribe to the Claude Code release notes if you maintain styles for an organization, because new frontmatter fields and new built-in styles arrive regularly.

From a tooling perspective, treating styles as plain Markdown means the existing tools you already use for documentation — linters, spell-checkers, diff tools, code search — work without modification. Note that you should keep in mind: this is a meaningful design choice that lowers the barrier to ownership across teams that are not LLM specialists.

Style Examples for Common Roles

To make adoption easier, here are sketch outlines for several real-world styles teams have shipped. Each is intentionally short to encourage iteration.

technical-writer style

Goal: produce documentation that reads like a vendor’s official guide. Banned: bulleted lists in body prose, emoji, exclamation marks. Required: section headings every two to three paragraphs, code blocks for every command, IPA when introducing pronunciation. You should keep in mind that this style works best when paired with a doc-template Skill that handles structure.

incident-responder style

Goal: triage production incidents calmly. Banned: speculation, broad rewrites. Required: short observed-vs-expected statements, explicit unknowns, links to runbooks. Important: instruct the agent to stop and request a human review before applying any change with blast radius greater than a single service.

refactor-coach style

Goal: improve code without rewriting it. Banned: large structural changes, renaming public APIs. Required: small mechanical refactors with rationale, before-and-after diffs, justification rooted in named code smells (long parameter list, feature envy, etc.). Note that you should keep this style focused on reasoning rather than action.

Conclusion checklist for adopting Output Styles

Before you commit a new style file, run through this checklist. First, is the goal one persona can plausibly satisfy across many tasks? If yes, proceed; if no, you probably want a Skill or a Hook. Second, can the style be expressed in under 100 lines of Markdown? Long styles are red flags. Third, does it duplicate any rule that already lives in CLAUDE.md? If so, choose one location and remove the duplicate. Fourth, will the team be able to discover and select this style easily?

Important to remember: small, well-named, well-documented styles are vastly more useful than encyclopedic ones. Treat them like APIs that other engineers will actually depend on — because once committed, they are.

Conclusion

• Output Styles is Claude Code’s mechanism for switching response behavior on demand.
• Built-in styles include default, Explanatory, and Learning.
• Custom styles are simple Markdown files with YAML frontmatter.
• Switching is via /output-style or the outputStyle setting.
• Styles change behavior, not model — pick the model separately.
• Keep styles small, focused, and committed alongside the repository.
• Use them to standardize onboarding, code review, documentation, and demos across a team.

References