16 / 20Configuration7 MIN READ

Output Styles

An output style is a preset that modifies Claude Code’s system prompt to change the role, tone, and default response format for the main conversation.

What it is

Output styles change how Claude responds, not what Claude knows. Four built-ins ship with Claude Code. Default is the standard software-engineering system prompt. Proactive makes Claude execute immediately and make reasonable assumptions instead of pausing for routine decisions — stronger autonomous-execution guidance than auto mode applies, and it works without changing your permission mode, so you still see permission prompts. Explanatory adds educational "Insights" alongside the work. Learning goes further and asks you to write small pieces yourself, leaving TODO(human) markers in the code.

A custom style is a markdown file: frontmatter, then the instructions to append to the system prompt. It can live at ~/.claude/output-styles for you, .claude/output-styles for a project, or inside the managed settings directory for an organisation. Project styles load from every .claude/output-styles/ between the working directory and the repository root; when two nested directories define the same name, the one closest to your working directory wins.

The frontmatter field that matters most is keep-coding-instructions. It defaults to false, which means a custom style removes Claude Code’s built-in software-engineering instructions — how to scope changes, write comments, and verify work. Set it to true when you are changing how Claude communicates but still want it coding the same way. Leave it out when Claude is not doing software engineering at all.

What it does for you

It stops you re-prompting for the same voice every turn. If you ask for a diagram first every time, a style says it once in the system prompt.
It repurposes Claude Code for non-engineering work. Dropping the coding instructions turns the same tool into a writing assistant or a data analyst.
It makes a team convention automatic. A project style commits to the repository, so every contributor gets the same response format without configuring anything.

How it works

01The style is read once, at session start
It is part of the system prompt, which Claude Code assembles when the session begins. Changing it mid-session does not apply, and does not invalidate the prompt cache either.
02Custom instructions are appended to the system prompt
Your markdown body goes at the end of the system prompt, after the core instructions. All styles also trigger reminders during the conversation so Claude keeps adhering to them. Because the addition sits in the system prompt rather than the conversation, it costs input tokens on every request of the session, though prompt caching absorbs most of that after the first one.
03keep-coding-instructions decides what is removed
With the default of false, Claude Code leaves out the built-in software-engineering instructions. With true, they stay and your instructions are added on top.
04Selection is saved to local project settings
/config → Output style writes outputStyle to .claude/settings.local.json. You can also set the key directly in any settings file.
05The style applies to the main conversation only
A subagent runs its own system prompt, so styles do not change how subagents respond. A fork is the exception, because it inherits the parent’s full system prompt.
06Plugins can ship and force styles
A plugin can provide styles in an output-styles/ directory. A plugin style with force-for-plugin: true applies automatically whenever the plugin is enabled, overriding your outputStyle setting.

How to implement it

01Try a built-in first
Run /config, select Output style, and pick Proactive, Explanatory, or Learning. Start a new session or run /clear for it to take effect.
02Create the markdown file
Save it as ~/.claude/output-styles/<name>.md for personal use or .claude/output-styles/<name>.md to share with the repository. The file name becomes the style name unless you set name in frontmatter.
03Decide about the coding instructions
Set keep-coding-instructions: true if Claude is still writing code. Omit it if the style turns Claude into something other than a software engineer.
04Write instructions about form, not facts
Response shape, tone, ordering, what to lead with. Project conventions and codebase facts belong in CLAUDE.md, which loads as a user message instead.
05Activate and verify
Select it in /config, then /clear or start a new session. If it seems inactive, check that you restarted — the style is fixed at session start. Run /debug or /doctor when it still is not applying, since a plugin style marked force-for-plugin overrides the outputStyle setting silently.

Examples

~/.claude/output-styles/diagrams-first.mdmarkdown

---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true
---

When explaining code, architecture, or data flow, start with a Mermaid diagram
showing the structure, then explain in prose.

## Diagram conventions

Use `flowchart TD` for control flow and `sequenceDiagram` for request paths.
Keep diagrams under 15 nodes. Label every edge that carries data with what it
carries, not with a verb.

A style that changes the shape of explanations while keeping Claude coding exactly as before.

.claude/output-styles/incident-analyst.mdmarkdown

---
name: Incident analyst
description: Writes incident timelines and postmortems from logs and commits
---

You reconstruct incidents from evidence. You do not fix code, propose patches,
or open pull requests, even when the fix is obvious — say what broke and stop.

Every response follows this order:

1. **Timeline.** Ordered events with timestamps. Each line cites the log line,
   commit, or deploy record it came from. No inference in this section.
2. **What broke.** One paragraph. Name the component and the failure mode.
3. **Why it was not caught.** The specific missing check, alert, or test.
4. **Open questions.** Evidence you would need to be confident, and where it
   would live.

Never write "likely" or "probably" without naming what would settle it. If the
evidence does not support a conclusion, say the evidence does not support a
conclusion.

A style with no `keep-coding-instructions`, so the built-in engineering instructions are dropped. Claude is analysing, not shipping.

.claude/settings.local.jsonjson

{
  "outputStyle": "Incident analyst"
}

What `/config` writes. Setting it by hand works too, and applies on the next `/clear` or restart.

Use it when

Making Claude explain implementation choices as it works, with the built-in Explanatory style.
Learning a codebase by having Claude leave TODO(human) markers for you to fill in, with the Learning style.
Running long autonomous stretches with the Proactive style, while keeping permission prompts on.
Repurposing Claude Code as a writing assistant or analyst by omitting keep-coding-instructions.
Standardising a team’s report format by committing a project style to the repository.

Avoid it when

The instruction is about your project rather than about form. CLAUDE.md loads as a user message and is re-injected after compaction; a style is not the place for codebase facts.
You need it for one invocation. --append-system-prompt adds to the system prompt for a single run without configuring anything.
You want the behaviour inside subagents. Styles apply to the main conversation only; a subagent needs its own definition.
You are dropping the coding instructions while still expecting Claude to code well. Without keep-coding-instructions: true you lose the built-in guidance on scoping changes, comments, and verification.

Common mistakes

SYMPTOMTyping /output-style and getting Unknown command.
FIXThe standalone command was deprecated in v2.1.73 and removed in v2.1.91. Use /config → Output style, or set the outputStyle key in a settings file.
SYMPTOMChanging the style mid-session and seeing no difference.
FIXThe style is part of the system prompt, read once at session start. The change applies on the next /clear or restart. It does not invalidate the prompt cache either way.
SYMPTOMA custom style makes Claude noticeably worse at coding tasks.
FIXkeep-coding-instructions defaults to false, so your style replaced the built-in software-engineering instructions. Set it to true if Claude is still writing code.
SYMPTOMExpecting a style to change how subagents respond.
FIXA subagent runs its own system prompt. Only a fork inherits the parent’s, so put the behaviour in the subagent definition instead.
SYMPTOMA style you did not select is active.
FIXA plugin style with force-for-plugin: true applies automatically whenever that plugin is enabled and overrides your outputStyle setting. Disable the plugin or check /plugin list.

Best practices

Set keep-coding-instructions: true on any style used while Claude is still writing code.
Keep style instructions about form — ordering, tone, what to lead with — and leave project facts to CLAUDE.md.
Change styles at a session boundary, since the change only applies after /clear or a restart.
Commit project styles to the repository so a team convention needs no per-developer setup.
Remember the Explanatory and Learning styles produce longer responses by design, which costs output tokens.
Use --append-system-prompt instead of a style when the addition is for one invocation.

Try it in five minutes

Write a custom style and prove it only takes effect at a session boundary.

1.Create ~/.claude/output-styles/bullet-first.md with a description, keep-coding-instructions: true, and a body saying every answer must open with a three-bullet summary before any prose.
2.In a running session, run /config, select Output style, and pick it. Ask a question — the old format is still in use.
3.Run /clear, ask again, and watch the three bullets appear.
4.Ask Claude to use a subagent for something and note the subagent’s output does not follow the style.
5.Delete keep-coding-instructions: true, /clear, and compare how Claude approaches a coding task now that the built-in engineering instructions are gone.

Verified against code.claude.com/docs/en/output-styles on 2026-08-09. See content/SOURCES.md for the full table.

← / → MOVE BETWEEN CONCEPTS