AI
Claude Code Output Styles: Custom System Prompts
August 20269 min read
Output styles are a way to replace parts of Claude Code's built-in system prompt with your own instructions. Selecting one changes the agent's core behavior and communication style for the whole session, which is how the same tool can act like a patient teacher in one session and a terse operator in the next. The change lasts until you switch styles again.
Claude Code ships with three: Default, the standard software-engineering behavior; Explanatory, which keeps working but adds educational insights about its choices; and Learning, a collaborative mode that pauses to let you write pieces of the code yourself. Each maps to a different intent, from shipping fast to learning as you go.
Run the /output-style:new command to generate a starter file from a description, or write one by hand. Custom styles are Markdown files with a short frontmatter block for the name and description, followed by the instructions that become the system prompt. Project styles live in .claude/output-styles and user styles live under your home directory.
CLAUDE.md adds context as extra input without touching the core system prompt, while an output style rewrites the prompt itself. Because of that, an output style changes how Claude behaves, and CLAUDE.md supplies facts about your project. The two work together: CLAUDE.md is loaded on top of whichever style is active.
Yes. Because an output style replaces parts of the default system prompt, an aggressive one can strip out the software-engineering behaviors you rely on. If the agent suddenly stops following your usual conventions, check the active style before blaming the model, and keep custom styles focused on communication rather than removing core behavior.
Key Takeaway
Output styles let you replace Claude Code's built-in system prompt with your own, reshaping how it works and communicates across a whole session. They ship with three presets and support custom Markdown files you switch with a single command. Use them to turn the same tool into a teacher, a reviewer, or a terse operator.
Most people tune Claude Code by adding context: a CLAUDE.md here, a rule there. Output styles work at a lower level. Instead of adding to the system prompt, they replace parts of it, changing the agent's core behavior and communication style for the entire session rather than nudging it from the outside.
This guide covers what output styles are, how to build a custom one, which built-in style fits which situation, and how the feature relates to the other ways you steer Claude Code.
An output style directly edits Claude Code's system prompt. Selecting one swaps the default instructions for a different set, which is how the same tool can behave like a patient teacher in one session and a terse operator in the next. The change persists for the whole session until you switch styles again.
Claude Code ships with three built-in styles that cover the common cases:
When the built-ins do not fit, you can create your own. The /output-style:new command generates a starter file from a description, or you can write one by hand. Custom styles are Markdown files with a short frontmatter block for the name and description, followed by the instructions that become the system prompt.
Project styles live in the .claude/output-styles folder and travel with the repository; user styles live under your home directory and follow you everywhere. Switch between any of them at any time with the /output-style command.
Keep an output style focused on how Claude works and communicates, not on facts about your project. Project facts, conventions, and commands belong in CLAUDE.md, which is loaded on top of whichever style is active.
The presets map cleanly onto different intents, so picking the right one is usually a matter of what you want from the session.
Output styles are easy to confuse with CLAUDE.md, system-prompt flags, and subagents, but each sits at a different layer. CLAUDE.md and its equivalents add context as extra input without touching the core prompt. A command-line flag can append instructions to the default prompt for a single run. Output styles go further and rewrite the prompt itself.
Subagents and skills are different again: subagents run delegated work in a separate context, and skills package on-demand procedures the agent loads when relevant. Output styles are the right tool only when you want to change the baseline behavior of the main session itself, not when you want to add knowledge or delegate a task.
Because an output style replaces parts of the default system prompt, an aggressive one can strip out the software-engineering behaviors you rely on. If the agent suddenly stops following your usual coding conventions, the active style is the first place to look before you blame the model.
A few output styles earn their keep on almost any team, and they are quick to assemble once you know the format.
Output styles are the deepest of Claude Code's steering levers because they change the system prompt rather than layering context on top of it. Reach for the built-ins first, write a custom style when you need a repeatable persona, and keep project facts in CLAUDE.md. Used well, one install becomes several purpose-built agents.