Output Styles: Changing the 'Show', Not the Host
📚 Series Navigation: The previous article 31 settings.json: User-level / Project-level Configuration clarified "which file to write configurations in, and who overrides whom". This article continues to talk about a switch that lives right inside that configuration setup—output styles. What it manages is not "what Claude knows", but "how Claude responds to you". A single line of setting can switch it from the default "head-down working engineer" to another persona that explains while working, or even doesn't write code at all.
They say "if you want Claude to listen, pile it into CLAUDE.md"—pile up conventions, rules, and everything it should remember.
To be honest, this saying is only half right. CLAUDE.md is indeed a great place to put "project background" (see Article 18 for details), but if you stuff a certain type of requirement in there, you are putting it in the wrong drawer.
Which type? "I want its responding tone / persona / format to change every time" type. For example: I want it to draw a diagram before explaining every time, I want it to teach me why it writes this way while writing code, or I simply want to use it as a writing assistant instead of a programmer. If you write these requirements into CLAUDE.md, it will work sometimes and fail sometimes—because CLAUDE.md is "a user message attached after the system prompt", which is a "request" for Claude to read, not a switch to change its "nature". The real switch that changes "how Claude speaks" is called output styles.
Let's put it this way: CLAUDE.md is the project material handed to a new employee, and output styles is directly rewriting their job description—"Are you a head-down programming engineer in this role, or a mentor who explains while working?". This article will clarify how to flip this switch.
An example scenario that will make you feel it immediately: Having someone who knows absolutely nothing about code use Claude Code to polish a resume. With the default engineer persona on, it will frequently want to "help you split this paragraph into a function" or ask "do you want to add a test?"—its mind is full of engineering thinking, completely not on the same wavelength as polishing a resume. This is not a problem that CLAUDE.md can solve; this is exactly why output styles exist.
After reading this article, you will get:
- Understand in one sentence what output styles actually change (Spoiler: it's "how to respond", not "what it knows")
- What the built-in styles in Claude Code (Default, Proactive, Explanatory, Learning) are for, and when to switch to them
- How to switch styles—and a pitfall of version changes: the old
/output-stylecommand is gone, how to switch it now - Customize an output style of your own: how to write the Markdown file, what the several frontmatter fields manage, and don't press the
keep-coding-instructionsswitch wrongly - What exactly is the difference between output styles and CLAUDE.md,
--append-system-prompt, Subagent, and Skill. One table to clarify it all, never to be confused again
01 Understand First: It Changes "How to Respond", Not "What It Knows"
Let's nail down the most core sentence of this article first, everything else is built on top of it:
Output styles change how Claude responds, not what Claude knows.
This is the exact wording from the official documentation. What it means is: output styles will not pour any new knowledge about your project into Claude; what it touches is Claude's system prompt (the underlying instructions loaded at the beginning of each conversation that define "who Claude is and how it should work")—setting its persona, tone, and output format.
Analogy: The same host, changing the show means changing the stage style. It's still the same person, their professional ability hasn't changed (their articulateness and knowledge reserve are their own); but when they host the "Network News", it's a calm tone; hosting a children's show is another bouncy tone; and hosting an educational channel, they will slow down the pace, stopping to ask questions while explaining. What changes is "how this show requires them to speak", not replacing them with another person. output styles is just "changing the show" for Claude—the model is still the same model, its abilities are completely untouched, what changes is its persona, tone, and format when conversing with you.
So when does it come in handy? The official judgment given is very practical:
Use one when you find yourself re-prompting the same voice or format every turn, or when you want Claude to act as a role other than a software engineer.
(Translating into plain English, there are just two signals:)
- "I have to re-type the same request every turn"—for example, every time you have to instruct "draw a flowchart for me first when explaining", when you type it for the fifth time you should think: this shouldn't be manually typed every turn, it should be solidified into a style.
- "What I want it to do is fundamentally not writing code"—for example, using it as a writing assistant or a data analyst. Claude Code's default system prompt is tuned for "efficiently completing software engineering tasks", if you ask it to write a novel, those engineering instructions like "limit the scope of changes first, write good comments, verify the work" will actually get in the way.
Going back to the resume polishing scenario at the beginning—this is a typical case of the second signal: Claude Code's entire default persona is tuned for software engineering, if you ask it to help polish a resume, those engineering instructions like "limit the scope of changes, write good comments, verify the work" all become interferences. This kind of task of "asking it not to be an engineer" cannot be solved by writing a bunch of "please forget you are a programmer" in CLAUDE.md—CLAUDE.md is a request attached at the end, output style is the knife that changes its job description.
💡 One-sentence summary: output styles touch Claude's system prompt—changing its persona, tone, and format, changing "how to respond", not "what it knows"; you should think of it in two signals: re-typing the same sentence every turn, or wanting it to do work other than programming.
02 Four Built-in Styles: Besides Default, There Are Three Ready-made Gears
You don't have to write it yourself, Claude Code has already built in several styles, ready to switch out of the box. Let's get to know these gears first.
Default style, is the one you have been using for the previous thirty-one articles—its system prompt is specially tuned for "efficiently completing software engineering tasks". Working with its head down, being restrained in changes, and verifying when necessary, this is Claude Code's "primary job". If you have no special requirements, just use it.
Besides Default, the official has built in three gears of extra styles, I will explain one by one in a sentence what "it has more compared to the default":
Proactive—more daring to make its own decisions, leans towards acting rather than planning first. The official explanation is: it will "execute immediately, make reasonable assumptions instead of pausing for routine decisions, and bias towards action over planning". To put it plainly, it means less back-and-forth confirmation with you, less listing plans there, and pushing forward by making its own decisions when encountering routine small decisions.
There is a point easily confused here, which the official specifically pointed out: Proactive provides stronger "autonomous execution guidance" than auto mode, but it can be used without changing your permission mode—so you will still see the permission prompt before the tool runs. The permission mode (talked about in Article 20, "whether the intern asks you before acting") manages "whether to stop and ask you", Proactive manages "how aggressive its behavior style is", they are two different things, don't treat them as one.
Explanatory—giving you "knowledge points" while working. While helping you complete engineering tasks, it will insert educational "Insights", helping you understand "why it is implemented this way, what pattern this codebase is". Suitable for when you want to understand the code along the way, rather than just wanting a result.
Learning—collaborative learning by doing, and it will even leave homework for you. This is the most special gear. It not only shares insights like Explanatory, but also leaves TODO(human) markers in the code, requiring you to manually write a small, strategic piece of code snippet yourself. It's equivalent to Claude setting up the scaffold, and leaving the crucial few lines for you to fill in—forcing you to actually get hands-on, instead of watching it perform the whole time.
Putting these three gears into a real sentence, you will have a better feel:
- The same requirement "add pagination to this list", under Proactive it will most likely directly start modifying, and less likely to ask you "should we list a plan first";
- The same requirement, under Explanatory it will tell you while modifying "why use cursor pagination instead of offset here, other places in this project are also written this way";
- The same requirement, under Learning it will write the outer framework, and leave a line
// TODO(human): implement cursor parsing herein the most crucial function body, handing the pen to you.
With the four gears side by side, comparing them makes it immediately clear who should take the stage:
| Built-in Style | Core Difference vs Default | When to Switch to It | Will the Response be Longer? |
|---|---|---|---|
| Default | —— | Normal software engineering, most of the time | Baseline |
| Proactive | More daring to make decisions, less confirmation, leans towards acting | You think it's too back-and-forth, want it to let loose and work | Not necessarily |
| Explanatory | Inserts "Insights" explanations while working | Want to understand the implementation idea and codebase pattern along the way | Longer (by design) |
| Learning | Explains + leaves TODO(human) for you to write yourself | Learning scenario, want to practice while doing | Longer (by design) |
The last column "Will the response be longer?" must be singled out as a reminder: the official explicitly stated that Explanatory and Learning produce longer responses than Default by design—because they need to insert explanations and leave homework. Longer responses mean more output tokens (about how tokens are billed, see Article 06). So don't keep these two hanging as default, switch to them when you want to learn, and switch back to Default after learning, to save tokens and avoid being flooded with a bunch of explanations every time.
A simple usage route: use Default for daily work; when encountering an unfamiliar open-source repository and you want to understand its architecture while having it make changes, switch to Explanatory; when you really want to calm down and learn a new framework, and don't want to just watch it write, but want to type a few lines yourself, then switch to Learning. People who use Proactive the least are often those who are more used to it stopping for a look before acting—this is purely a personal preference, if you find it too dilly-dallying, you can completely do the reverse.
💡 One-sentence summary: Four built-in gears—Default works with head down, Proactive lets loose with less confirmation, Explanatory explains while working, Learning explains and leaves homework for you; the latter two gears have longer responses and consume more tokens, switch on demand and switch back to default when done.
03 How to Switch: That /output-style Command Is Already Gone
This section must first throw a bucket of cold water, because hidden here is a real pitfall of version change—the command that many old tutorials and old videos are still teaching is now invalid when typed.
You will most likely see this saying elsewhere: "Use the /output-style command to switch styles". This standalone command has been removed. The official documentation states it very clearly:
The standalone
/output-stylecommand was deprecated in v2.1.73 and removed in v2.1.91. Use/configor edit theoutputStylesetting directly.
So, now there are two right ways to switch styles, I will write them both clearly for you.
Route 1: Click in the /config Menu (Recommended, Intuitive)
Type /config in the Claude session, find the Output Styles item in the popped-up menu, and choose the style you want. Official exact words:
Run
/configand select Output styles to choose a style from the menu. Your selection will be saved to your local project-level.claude/settings.local.json.
Notice the landing point at the end of this sentence—the style you selected in the menu will be written into the current project's .claude/settings.local.json. This perfectly connects to the knowledge of settings.json in the previous article: settings.local.json is the copy that is project-level, belongs only to you personally, and does not enter version control (Article 31 talked about its positioning). In other words, the style you switch to affects only yourself by default, takes effect only in this project, and won't be forced upon your teammates due to code commits.
Route 2: Directly Edit the outputStyle Field
If you don't want to click the menu, you can also write it manually. Just add an outputStyle field in the settings file:
{
"outputStyle": "Explanatory"
}Fill the value with the name of the style (fill in Explanatory, Learning, Proactive for built-in ones, or the name of a custom style). Which settings file this field is written into determines its scope of effect—if you want it to be a global default, write it into the user-level ~/.claude/settings.json, if you want it exclusive to this project, write it into the project-level. The priority rules of who overrides whom are completely consistent with those taught in Article 31, I won't repeat them here.
A Timing of Effect You Must Remember
No matter which route, there is a particularity of "when does it count" after switching. The official hits the spot very accurately:
Output styles are part of the system prompt, which Claude Code reads once at the start of the session. Changes will take effect after a
/clearor in a new session.
Analogy: The script of the show is handed to the host before the broadcast. The show has already been broadcasting for half an hour, if you temporarily stuff in a new script, this episode cannot be changed—you have to wait until the next episode starts for it to take effect. output style is the same: it is part of the system prompt, Claude only reads it once at the beginning of the session. If you switch the style halfway, the current conversation won't transform immediately, you must /clear to clear it up (Article 19 taught that /clear is "wiping the table clean and restarting") or simply start a new session, then the new style will truly take the stage.
Many people stumble here the first time they switch styles: they change the style to Explanatory in /config, return to the conversation and find it is still working with its head down without half a sentence of explanation, and mistakenly think on the spot that "this feature is broken". Only after tossing about for a long time do they realize—without /clear, the old system prompt is still hanging in this conversation. Give it a /clear, and the explanation will come out immediately. Keep this pitfall in mind, it can save you the ten minutes of frustration at that time.
💡 One-sentence summary: The old
/output-stylecommand has been removed, now switching styles goes two routes—choose in the/configmenu (saved intosettings.local.json) or directly edit theoutputStylefield; remember to/clearor start a new session after switching to take effect, don't be like me and think it's broken.
04 Customize a Style of Your Own: Handled by One Markdown File
Four built-in gears not enough? You can totally write one yourself. The good news is, the barrier to entry is surprisingly low—one Markdown file is one output style.
The official explains the structure very crisply:
A custom output style is a Markdown file: frontmatter for metadata, followed by instructions to add to the system prompt.
Disassembled, it has two parts: the frontmatter at the head (metadata wrapped in ---) + the body below (the instructions you want to append into the system prompt). I will take you to create one in three steps below.
Step 1: Save the File to the Right Place
Just like the extension points (Skill, Subagent) learned before, output styles are also divided into three storage levels, where it is stored determines in which projects it can be selected:
| Level | Storage Directory | Who Can Use It |
|---|---|---|
| User-level | ~/.claude/output-styles | Can be selected in all your projects |
| Project-level | .claude/output-styles (under the project root directory) | Only the current project, can be committed with the project, shared with teammates |
| Managed policy level | .claude/output-styles inside the Managed settings directory | Distributed uniformly by the organization |
This logic of "project-level vs user-level" is the exact same line of thought as Article 31 talking about settings and Article 25 talking about memory: what you use every day yourself and is common across projects, put in user-level (~/.claude/output-styles); what is exclusive to a certain project and you want collaborators to be able to use as well, put in project-level (.claude/output-styles), it can follow git.
There is also a naming rule you have to remember:
The filename becomes the style name, unless you set
namein the frontmatter.
That is to say, if you save a code-reviewer.md, its style name defaults to code-reviewer; unless you additionally write name in the frontmatter, then name prevails.
Step 2: Write Frontmatter and Body
Let's look at this example given by the official—a style of "draw a diagram first for every explanation". I will put it up exactly as is first, then break down field by field:
---
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 upper part between --- is the frontmatter, the lower part is the body instructions ("When explaining code, architecture, or data flow, start with a Mermaid diagram showing the structure, then explain in prose..."). This body will be appended into Claude's system prompt—from then on, every time it explains, it will draw a diagram first.
There are four fields supported in the frontmatter in total, explained one by one:
| Frontmatter Field | What It Manages | Default Value |
|---|---|---|
name | Style name (if not written, uses filename) | Inherited from filename |
description | Style description, will show in the /config selector | None |
keep-coding-instructions | Whether to retain Claude Code's built-in software engineering instructions | false |
force-for-plugin | Only for plugin use: automatically apply this style when enabling the plugin, no user manual selection needed | false |
The first two are easy to understand—name is the name, description is a one-sentence description for yourself to recognize in the menu. The latter two need to be talked about separately, especially keep-coding-instructions, which is the easiest switch to press wrongly in the entire custom style, I will break it down in the next section. force-for-plugin is only relevant to making plugins (Article 24 taught that a plugin can package and distribute various extension points, and output styles can also be brought along by plugins), you won't use it for writing styles yourself daily, just knowing there is such a field is enough.
Step 3: Switch to Your New Style
After saving the file and writing the content, return to the Output Styles menu in /config, and your new style will appear in the options (with that sentence of description you wrote displayed next to it), select it. The same rule—takes effect after /clear or starting a new session.
💡 One-sentence summary: A custom style is just one Markdown file—frontmatter writes metadata, body writes instructions to append into the system prompt; store at the right level (user-level across projects, project-level follows the project), filename is style name, after writing go select in
/config,/clearto take effect.
05 That Easiest Switch to Press Wrongly: keep-coding-instructions
I left a suspense in the previous section—the frontmatter field keep-coding-instructions is worth a separate section, because if you press it wrongly, the effect of your custom style will be worlds apart.
Let's first talk about what it manages. As mentioned earlier, Claude Code's default system prompt is stuffed full of "software engineering instructions"—how to limit the scope of changes, how to write comments, how to verify work. When you write a custom style, this set of built-in instructions will be "kicked out" by default. Official exact words:
Custom output styles exclude Claude Code's built-in software engineering instructions... unless
keep-coding-instructionsis set totrue.
This field defaults to false, meaning: by default, your custom style will entirely replace the built-in engineering instructions, leaving only the paragraph you wrote. Whether to keep or kick out depends entirely on whether your style still wants Claude to do the job of programming. The judgment only requires asking one sentence:
"In this style of mine, is Claude still writing code?"
- Still writing code, just changing the way of speaking (like "programming as usual, but draw a diagram for me first every time") → Set
keep-coding-instructions: true, keep the built-in engineering instructions. The "Diagrams first" example in the previous section is of this kind—what it wants is "draw a diagram first when explaining", but Claude is still programming normally, so the official set it totruefor it. - Not writing code at all anymore (like using it as a writing assistant, data analyst) → Omit this field (let it default to
false), kick those engineering instructions clean. If it's not even programming, keeping instructions like "limit the scope of changes, write tests" is purely interference.
The official explains this judgment very clearly, which is worth remembering exactly:
Keep them when you are changing how Claude communicates but are still programming (e.g. always answering with diagrams). Omit them when Claude is not doing software engineering at all (e.g. as a writing assistant or data analyst).
I put these two situations in a comparison table, the consequences of pressing wrongly are clear at a glance:
| What Your Style Wants to Do | How keep-coding-instructions Should be Set | What Happens if Pressed Wrongly |
|---|---|---|
| ✅ Programming as usual, only changing the response way (draw diagram first, fixed format...) | true (retain engineering instructions) | ❌ Set to false: it loses engineering disciplines like "limit scope, verify", becomes clumsy and sloppy in modifying code |
| ✅ Not programming at all (writing / data analysis / translation...) | Omit (default false) | ❌ Set to true: its mind is still thinking about splitting functions, adding tests, completely not on the same wavelength as the writing assistant you want |
Back to the resume polishing scenario in Section 01—the root is right here. What was needed at that time was a "writing assistant" persona, which shouldn't carry any programming instructions at all. If one knew how to write a custom style back then, and omitted keep-coding-instructions (let the engineering instructions be kicked out by default), it wouldn't frequently want to "help you split this paragraph into a function". This switch is essentially answering "is this new persona still moonlighting as an engineer?".
💡 One-sentence summary:
keep-coding-instructionsdefaults tofalse, which will entirely kick out the built-in engineering instructions; judgment only asks one sentence "does Claude still program in this style?"—if still programming, set totrueto retain, if not programming, omit it to kick clean, if pressed in reverse the persona will go off track.
06 How It Actually Works Under the Hood: The Chunk Spliced into the System Prompt
The previous sections scattered mentions of "append into the system prompt", "read once at session start", "kick out engineering instructions"—this section explains this underlying mechanism thoroughly at once. Understanding how it works, all those "whys" from before will all connect: why you must /clear after changing styles, why it affects every response, why keep-coding-instructions can control the retention or abolition of engineering instructions.
The official summarized the working principle into three points, I translate them one by one into words you can remember:
- All output styles add their own custom instructions to the end of the system prompt.
- All output styles trigger reminders during the conversation for Claude to stick to the output style instructions.
- Custom output styles exclude Claude Code's built-in software engineering instructions... unless
keep-coding-instructionsis set totrue.
First point: Your style instructions are spliced to the "end" of the system prompt. The system prompt is the underlying instructions loaded into Claude at the beginning of each session, your output style content is appended at its very end—so it takes effect for every response in this conversation, not just governing a certain sentence.
Second point: During the conversation it will repeatedly "remind" Claude to hold the style. AI easily forgets the setting at the beginning to the back of its mind after chatting for a long time, this reminder mechanism is to periodically pull out the style instructions and recite them once, ensuring it doesn't go off track.
Third point, exactly explains the switch in the previous section: Custom styles by default will "pull out" the built-in engineering instructions from the system prompt, leaving only the paragraph you wrote; keep-coding-instructions: true is telling it "don't pull, keep it". This is why this field can decide "whether Claude still programs"—it manages the existence or abolition of that paragraph of engineering instructions in the system prompt.
One diagram to draw clearly "how the system prompt is assembled":
What this diagram says is: at the very beginning of the session, Claude Code assembles the system prompt according to the style you chose—built-in styles and custom styles with keep=true all carry engineering instructions, custom styles with keep=false pull out engineering instructions leaving only your instructions; after splicing, this prompt takes effect for every response in this session; and if you change the style halfway, you have to /clear or start a new session, only then will it re-assemble once with the new style (this is the root cause of that pitfall in Section 03).
Finally a word about tokens (for billing see Article 06). The official speaks practically:
Token usage depends on the style. Adding instructions to the system prompt will increase input tokens, though prompt caching reduces this cost after the first request in a session.
Translated into plain English: style instructions will enter the system prompt, taking up a bit of input tokens; fortunately Claude Code has prompt caching (caches the unchanging system prompt for reuse), after the first request in the session this cost comes down, no need to be too anxious. What really significantly pulls up consumption are styles like Explanatory, Learning that "produce long responses by design" (mostly in output tokens), this is the same logic as how much stuff your own custom style makes Claude generate—the longer the instructions, the more you make it produce, the more tokens, just use on demand.
💡 One-sentence summary: output style instructions are spliced to the end of the system prompt, take effect for every response in this session, and will be repeatedly reminded to hold; custom styles by default pull out built-in engineering instructions (
keep=trueto keep); changing style requires/clearto re-assemble; styles take a bit of tokens, but prompt caching catches the bottom, long response styles are the main consumption bulk.
07 output styles vs CLAUDE.md / Skill / Subagent: What Exactly Is the Difference
Having learned up to here, a question will most likely pop up in your head: This thing, and the CLAUDE.md, Skill, Subagent learned before, all sound like they can "customize Claude's behavior", what exactly is different? This section clarifies it all at once. That big table of "how to choose features" in Article 30 picks tools from requirements, here we specifically focus on "how to distinguish from output styles" to look.
First grasp the most unique feature of output styles—it directly modifies the system prompt itself, and takes effect for every response. Other features are either "adding a paragraph after the system prompt", or "loading only at a specific timing", none of them touches the root of the system prompt like it does. The official comparison table explained this layer of difference thoroughly, I'll bring it over and supplement each with a sentence in plain English:
| Feature | How It Works | When to Use It (Instead of output style) |
|---|---|---|
| Output Styles | Directly modifies system prompt, applied to every response | What you want is exactly "change a persona / tone / default format every turn" |
| CLAUDE.md (Article 18) | Appends a user message after the system prompt | What you want to pour in is project conventions and codebase background, not speaking way |
--append-system-prompt | Appends content to system prompt, deletes nothing | You only want to temporarily add some instructions for a certain single invocation |
| Subagent (Article 23) | Runs a subagent with its own independent system prompt, model, tools | You want to hand over a certain focused job to a little assistant with independent context, it only hands in conclusion after finishing |
| Skill (Article 26) | Loads specific instructions only when called / relevant | You have a reusable workflow, call out on demand |
In this table, what beginners should distinguish the most are the first two rows—output style vs CLAUDE.md. They are the easiest to confuse, because both "can make Claude listen to you". But the essence is worlds apart:
CLAUDE.md contains "content / background", output style contains "way / persona". One answers "what is this project, what are the conventions", the other answers "what tone, what format should you use to respond". Putting it more bluntly, back to the analogy at the beginning: CLAUDE.md is the project material handed to the employee, output style is the job description set for them. You wouldn't write "we use pnpm not npm" into output style (that is a project convention, goes into CLAUDE.md), nor would you write "please draw a diagram first then explain every time" into CLAUDE.md as an ironclad rule (that is a response way, should be made into an output style). The official specially left a guiding sentence in the documentation, just for fear you put it wrongly:
For instructions about your project, conventions, or codebase, use CLAUDE.md instead.
As for --append-system-prompt, it looks similar to output style in "both touching the system prompt", but one is one-off, one is persistent: --append-system-prompt is when you temporarily paste a sentence after the system prompt when starting a certain claude invocation, use and go; output style is a persistent persona saved into configuration and applied to every session. Falling onto commands is this difference—temporarily trying a certain style, you would start a session like this once:
claude --append-system-prompt "Please answer in Chinese this time, keep it short"Close it and reopen and it's gone. But if you want this style every day, then don't manually type this string of parameters every time, precipitate it into an output style, once and for all. Use the former for temporarily trying a sentence, use the latter for fixing it down, this is their division of labor.
Also Skill (Article 26) deserves a sentence of distinction: Skill is a "load only on demand reusable workflow", normally does not occupy the system prompt, it is only called in when you /<name> or Claude judges it relevant; output style is a "persona setting hanging all the time, applied to every response". One is "a recipe only dug out when needed", one is "the host's stage style running through the whole show"—for the flow of a certain specific task make a Skill, for a character tone that wants to change the whole process make an output style.
There is also a common confusion going the other direction: wanting Claude's "answer style to be concise, less nonsense", the first reaction is to write into CLAUDE.md. As a result, it works sometimes and fails sometimes—because things like style should inherently be determined by modifying the system prompt (output style), rather than relying on that "request attached at the end" of CLAUDE.md to remind. This is the same type of error as "stuffing three hundred lines of API into CLAUDE.md" in Article 30: the stuff isn't put in the right drawer.
💡 One-sentence summary: output styles' uniqueness lies in directly modifying the system prompt, applied to every response; the easiest to confuse with it is CLAUDE.md—CLAUDE.md contains project background (content), output style contains persona tone format (way); for one-off temporary added instructions use
--append-system-prompt, for assistant needing independent scope use Subagent.
08 Get Hands-on: Write a Custom Style of "Diagram First then Explain" and Run It Through
Just looking without practicing is a fake trick. This section takes you to build a custom output style from zero, switch to it, and see with your own eyes that it really takes effect. We will just do the official's most classic "diagram first then explain", the whole process does not rely on any complex project you already have, find a random directory and you can practice.
Step 1: Create the Style File
We save it to the user-level directory (~/.claude/output-styles), this way you can select it in any of your projects later. First create the directory, then create the file:
mkdir -p ~/.claude/output-stylesThen use your handy editor, create a new file diagrams-first.md under ~/.claude/output-styles/, fill in the content below (I translated the body into Chinese, convenient for you to read; instructions in Chinese Claude will follow all the same):
---
name: Diagrams first
description: Draw a diagram first for every explanation, then explain with text
keep-coding-instructions: true
---
When explaining code, architecture, or data flow, first give a Mermaid diagram showing the structure, then explain with text.
## Diagram conventions
Use `flowchart TD` for control flow, and `sequenceDiagram` for request paths. Keep nodes of each diagram under 15.Pay attention to keep-coding-instructions: true—because under this style Claude is still programming normally, just having one more habit of "drawing a diagram first", so the built-in engineering instructions must be retained (the judgment taught in Section 05).
Step 2: Switch to This Style
Enter a Claude session, type /config, go into the Output Styles menu, you should be able to see a Diagrams first (with that sentence of description you wrote displayed next to it), select it.
claudeAfter entering type /config, move the arrow keys to "Output Styles", hit Enter, select Diagrams first.
Expectation: In the menu you can see the Diagrams first item, and hanging next to it is the description "Draw a diagram first for every explanation...". Seeing it in the list = the file is correctly recognized. If not seen, most likely the file is not saved in the right directory, or the --- of the frontmatter was missed.
Step 3: /clear to Make It Take Effect
Don't rush to ask a question after selecting—first /clear (remember that pitfall in Section 03? System prompt is read once at session start):
/clearStep 4: Ask a Question, Verify It Really Draws a Diagram First
After clearing the table, ask it a question that "needs explanation", see if it obediently serves the diagram first:
Explain how the user login request goes from the frontend to the databaseExpectation: Its answer will first throw out a Mermaid diagram (most likely a sequenceDiagram, drawing the request path of frontend → backend → database), and then use text to explain. Seeing this order of "diagram in front, text in back" = your custom style has taken effect.
As a comparison, you can /config switch back to Default, /clear again, and ask the same question—it will then only give text, and no longer draw a diagram. This difference between before and after is the ironclad proof that output style is solidly changing "how to respond".
Step 5: Clean Up (Optional)
If you don't want to keep this style, just delete the file directly:
rm ~/.claude/output-styles/diagrams-first.mdAfter deleting it will disappear from the /config menu. (If it is currently being used, remember to switch back to Default in /config first.)
Running through these five steps, you have personally walked through this complete chain of "create file → switch style → /clear take effect → verify → clean up". Doing any custom style in the future is nothing more than changing the body instructions, adjusting keep-coding-instructions on demand, the flow is all this same set.
💡 One-sentence summary: Custom style practical operation is just five steps—create
.mdfile, select in/config,/clearto take effect, ask a question to verify "diagram in front text in back", delete file to clean up; switch back to Default to ask the same question for comparison, the difference is visible at a glance.
09 Summary
In this article we thoroughly dismantled output styles—that switch that changes "how Claude responds to you" instead of "what Claude knows".
Stringing together the core points to review:
| What You Want to Do | How to Do It | Key Point |
|---|---|---|
| Understand what output styles are | Change persona / tone / format in system prompt | Change "how to respond", not "what it knows" |
| Use ready-made built-in styles | Default / Proactive / Explanatory / Learning | The latter two gears have longer responses and cost more tokens, switch on demand |
| Switch styles | Choose in /config menu, or edit outputStyle field | Old /output-style command removed; /clear after switching to take effect |
| Customize a style | Write a Markdown file (frontmatter + body) | Filename is style name; store in user-level across projects, project-level follows project |
| Decide whether to retain engineering instructions | keep-coding-instructions | If still programming then true, if not then omit (default false) |
| Distinguish from CLAUDE.md | See if it contains "way" or "content" | Persona tone format → output style; project background convention → CLAUDE.md |
You should now be able to: Say clearly in one sentence what output styles change, when to switch to the four built-in gears respectively, use /config (instead of the deprecated /output-style) to switch the style correctly and know to /clear to take effect; write a Markdown custom style yourself, press the keep-coding-instructions switch right, and also be able to clear up its boundaries with CLAUDE.md, Skill, and Subagent. To put it plainly, you now have an extra key to "change Claude's persona" in your hand—the same model, can make it switch from an engineer to a mentor, switch to a writing assistant, changing outfits according to the job.
Back to the opening sentence "if you want to customize, pile it into CLAUDE.md"—now you should be clear: piling project background into CLAUDE.md is right, but things like "changing a tone, changing a persona, changing a format" which belong to "how to respond", are governed by output styles, put them in the right drawers, and both will be easy to use.
Next article 33 "Hooks"—output styles is "changing the way Claude speaks", but it ultimately still relies on Claude itself "willing to comply". Is there a mechanism that can make a certain thing unshakable, automatically happen without relying on Claude's consciousness? For example, "every time it finishes modifying a file, automatically run a formatting pass", "a certain dangerous command must be hard-blocked". This is the work Hooks do—automatic checkpoints that execute as soon as an event triggers, a prelude was left for you in the previous Article 30, the next article will tear it apart completely. Think about it: what things have you instructed Claude several times, yet still want a "hard constraint to ensure it does it every time"?