Claude Code output styles: change the system prompt without losing the coding agent

🎨 What an output style is and what it is not

An output style is a markdown file whose instructions are appended to the end of Claude Code's system prompt. It is not a user message, not a context file, not an attachment: it sits at the top of the hierarchy, the part that defines who the assistant is and how it should answer before I type anything at all.

The practical consequence is that a style applies on every single turn, without me invoking it. It is the right tool when the repetition is about form — "always answer with a diagram", "stay under five lines", "act as a data analyst, not a developer" — and the wrong one when it is about the facts of the project, where a CLAUDE.md belongs instead.

One limit worth knowing upfront: the style applies to the main conversation. A subagent runs with its own system prompt and does not inherit it; the exception is a fork of the current conversation, which carries the parent's full system prompt along with it.

🧭 The four built-in styles

The Default style is Claude Code's normal system prompt: concise, tuned for getting a software engineering task done. The other three shift register sharply.

Proactive pushes on autonomy: Claude executes immediately, makes reasonable assumptions instead of pausing on routine decisions, and prefers action over planning. Worth noting that it is a stronger nudge than auto mode applies, yet it does not touch permissions: you still get the confirmation prompts before tools run.

Explanatory weaves "Insight" blocks into its work, explaining implementation choices and codebase patterns. Learning goes further and turns collaborative: on top of the insights it leaves TODO(human) markers in the code, small strategic pieces that are mine to implement. It is the closest thing to a real pair programming session, and the one I recommend to anyone worried about switching their brain off while accepting patches blind.

⚙️ How you switch style today: /config, not /output-style

This is the first stumbling block, and not a minor one: almost every guide in circulation tells you to run /output-style style-name or /output-style:new. That command was deprecated in v2.1.73 and removed in v2.1.91: type it today and you find nothing, and the wrong conclusion is that the feature is gone.

The correct way is /config, Output style entry, which opens a menu of the available styles. The choice lands in .claude/settings.local.json, that is the local project level. Alternatively I write the outputStyle field by hand in whichever settings file I prefer, following the normal settings precedence.

The second thing to remember is that the style is part of the system prompt, which Claude Code reads only once at session start. A change has no effect on the current turn: it takes a /clear or a new session. It is the number one reason a freshly written style "does not work".

// .claude/settings.local.json
{
  "outputStyle": "Explanatory"
}

✍️ Writing a tailored style

A custom style is a markdown file: frontmatter with the metadata, then the text that ends up in the system prompt. The file name becomes the style name, unless I override it with the name field. There are three levels: user in ~/.claude/output-styles, project in .claude/output-styles, and managed policy inside the managed settings directory.

The frontmatter has four fields: name and description (the latter is what I read in the /config picker), keep-coding-instructions, which I cover next, and force-for-plugin, reserved for styles shipped inside a plugin — when set, the style applies on its own as soon as the plugin is enabled, overriding the user's choice.

A handy detail in monorepos: project styles load from every .claude/output-styles/ directory between the working directory and the repository root, and when two of them define the same style name, the one closest to my working directory wins.

---
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.

⚠️ The trap: keep-coding-instructions

This is the mistake I see most often, and it comes from an unintuitive default. A custom style, by default, leaves out Claude Code's built-in software engineering instructions: how to scope a change, how to write comments, how to verify the work. It does not sit alongside them: it replaces them with my text.

The result is an assistant that has magically "forgotten how to program", regressing on things it used to handle on its own. The cause is almost always one missing field: keep-coding-instructions: true. I add it every time I am only changing the way it communicates while the work is still writing code.

I leave it out instead when the assistant is not doing software engineering at all: a writing assistant style, a data analyst, a documentation reviewer. There the coding instructions are just dead weight in the system prompt, and dropping them is exactly the point.

🧩 When I use a style and when something else

Claude Code offers four different ways to be customized, and picking one to do another one's job is the main source of frustration. I keep them apart like this:

• Output style when I want a different role, tone or response format on every turn: it is the only one that modifies the system prompt.
• CLAUDE.md when Claude needs to know my project's conventions and context: it arrives as a message after the system prompt, it does not rewrite it.
• --append-system-prompt when I need a one-off addition for a single invocation, without removing anything already there.
• Skills when I have a reusable workflow that loads only when I invoke it or when Claude finds it relevant — not on every message.
• Subagents when I want a helper with its own system prompt, model and tools for a focused task.

✅ The checklist I follow

Operational summary, in the order that saves me the most time:

• Try the built-ins first: Explanatory and Learning already cover most of the "I want to understand what you are doing" cases.
• Write the custom style in .claude/output-styles/ if the team needs it, in ~/.claude/output-styles/ if it is a preference of mine.
• Set keep-coding-instructions: true unless the assistant really should stop acting as a developer.
• Activate it from /config, never from /output-style: that command has been gone since v2.1.91.
• Run /clear after every change to the style, otherwise I am still looking at the previous session's system prompt.
• Keep an eye on tokens: a style lengthens the system prompt, and Explanatory and Learning produce longer responses than Default by design.