What Are Claude Code Output Styles?
A Claude Code output style is a markdown file that directly modifies Claude's system prompt at session start. It changes role, tone, and response format while keeping core capabilities like file edits, script execution, and TODO tracking intact. The feature ships with three built-in styles and supports unlimited custom ones at the user or project level.
According to Anthropic's official documentation, output styles "completely turn off the parts of Claude Code's default system prompt specific to software engineering" unless you set keep-coding-instructions to true. That makes them the strongest customization layer in the CLI -- stronger than CLAUDE.md or the --append-system-prompt flag.
When to use an output style
- ●You keep re-prompting for the same voice or format every turn
- ●You want Claude to act as something other than a software engineer (writer, reviewer, tutor, analyst)
- ●You need a stable, repeatable communication style across every session
- ●Your team needs a shared voice for AI-generated PRs, docs, or commit messages
The Three Built-in Output Styles
Claude Code ships with three styles out of the box. Default is the engineering-focused system prompt you already use. Explanatory and Learning add narration and pair-programming behavior on top of the same core capabilities.
Speed-first engineering
Terse, action-oriented, no narration. Best for daily shipping, refactors, and bug fixes.
Narrated insights
Adds "Insights" callouts between steps explaining why Claude made each choice. Best for codebase onboarding.
Pair-programming
Inserts TODO(human) markers and asks you to write strategic pieces. Best for learning a new framework or language.
# Switch to Explanatory mode
/config
# select "Output style" -> "Explanatory"
# restart the session for the change to take effectOutput Styles vs CLAUDE.md vs Skills vs Subagents
Claude Code has four customization layers and they do not overlap. Picking the wrong one wastes context tokens or means your instructions never apply. This is the decision matrix.
| Layer | When loaded | Best for |
|---|---|---|
| Output style | Replaces system prompt at session start | Voice, role, format |
| CLAUDE.md | User message after default system prompt every session | Project facts, conventions, env notes |
| Skill | On demand: invoked or auto-detected | Multi-step procedures, task playbooks |
| Subagent | Spawned with its own context, model, and tools | Isolated work, parallel research, scoped tools |
Rule of thumb: if you keep retyping voice or format instructions, that is an output style. If you keep retyping a procedure, that is a skill. If you keep retyping facts about the codebase, that is CLAUDE.md.
The complete playbook
Every customization layer, every config, and the reasoning behind each decision -- in the full KaiShips Guide to Claude Code.
This post covers output styles. The guide covers CLAUDE.md, skills, hooks, subagents, worktrees, MCP, and 5 more chapters of production-tested configs.
Get the KaiShips Guide to Claude Code -- $29How to Switch Output Styles
There are two ways to change the active style: the interactive picker and a direct settings edit. Both write to the same outputStyle field, but the picker stores it in .claude/settings.local.json (per-machine) by default.
1. Interactive: /config menu
Type /config inside Claude Code. Pick "Output style" from the menu, then select a built-in or custom style. Saved to .claude/settings.local.json automatically.
2. Manual: edit settings.json
Add an outputStyle field to any settings file. Use ~/.claude/settings.json for global, .claude/settings.json for project (committed), or settings.local.json for per-machine overrides.
// .claude/settings.json
{
"outputStyle": "Explanatory"
}
// or with a custom style file
{
"outputStyle": "code-reviewer"
}Output styles load at session start. Changes do not affect ongoing conversations -- this is intentional, so prompt caching keeps latency and cost low. Run /clear or relaunch claude after switching.
The Output Style File Format
Output style files are plain markdown with YAML frontmatter. Claude reads the frontmatter for metadata and appends the body to the system prompt at session start. The full schema is three fields.
| Field | Required | Purpose |
|---|---|---|
| name | Optional | Display name. Falls back to the file name if omitted. |
| description | Recommended | Shown in the /config picker. Keep under 80 characters. |
| keep-coding-instructions | Optional | Defaults to false. Set to true to retain Claude Code's default coding system prompt. |
---
name: Code Reviewer
description: Terse senior reviewer voice. Focuses on bugs and design.
keep-coding-instructions: true
---
You are a senior staff engineer reviewing a pull request.
## Voice
- Terse. No filler. No "Great job!" openers.
- Reference exact files and line numbers.
- Lead each comment with severity: BLOCKER, MAJOR, MINOR, NIT.
## Focus
- Correctness bugs
- Concurrency or race conditions
- API contract changes
- Test coverage gaps
## Avoid
- Style nits Prettier or rustfmt would catch
- Praise paragraphs
- Restating the diff back to the authorUser Scope vs Project Scope
Output styles live at one of two paths. The choice determines who sees the style and where it travels.
~/.claude/output-styles/
Personal styles available across every project on your machine. Not committed. Use for your default voice or experimental personas.
.claude/output-styles/
Lives inside the repo. Commit and share with the team. Use for project-specific voices like a code reviewer that knows your codebase conventions.
Plugins can also ship output styles in an output-styles/ directory. When a plugin is installed, its styles appear in the /config picker alongside user and project styles. This is the cleanest way to distribute a voice across multiple projects without copying files.
Create a Custom Style With /output-style:new
The fastest way to ship a custom style is to ask Claude to write it. The /output-style:new command takes a plain-language description and scaffolds the file for you, frontmatter included.
Step 1 -- describe the style
Run /output-style:new and tell Claude what you want. Be specific about voice, format, and edge cases. "Terse code reviewer that flags BLOCKER and NIT" beats "be more direct."
Step 2 -- review the scaffold
Claude creates the file at the path you specify. Open it and tighten the language. Cut anything generic. The system prompt is precious context -- every word should be load-bearing.
Step 3 -- activate and test
Run /config, pick the style, restart the session, and test against your normal workflow. Iterate on the file between sessions. Most teams converge in 3-5 revisions.
# Inside Claude Code
/output-style:new
# When prompted, paste:
# "A terse staff engineer reviewer voice that flags severity
# (BLOCKER, MAJOR, MINOR, NIT), references files and lines,
# and skips style nits. Save at project scope."7 Production Output Style Examples
These are styles teams actually ship. Each one solves a specific repeating prompt or removes a category of friction. Copy the description, scaffold the file, then iterate.
Code Reviewer
Voice: staff engineer, terse. Output: severity-tagged comments (BLOCKER/MAJOR/MINOR/NIT) with file:line refs. Use when: reviewing PRs from junior or mid-level engineers.
PR Description Writer
Voice: structured technical writer. Output: Summary / Why / What changed / Test plan / Rollback notes. Use when: closing out a feature branch.
Doc Writer (DocOps)
Voice: Diataxis-aware tech writer. Output: tutorials, how-tos, references, explanations -- never mixed in one doc. Use when: drafting README and /docs pages.
Conventional Commit Bot
Voice: structured, machine-friendly. Output: commit messages strictly in type(scope): subject + body + BREAKING CHANGE footer. Use when: repos using semantic-release.
Incident Commander
Voice: calm, decisive, no speculation. Output: timestamped status updates, hypothesis / evidence / next-action sections. Use when: running a sev-2 or sev-3 incident with Claude as scribe.
SQL Analyst
Voice: data analyst, definite numbers. Output: query, expected row count, caveats, then the result table. Use when: running ad-hoc analytics inside a Claude Code session with DB access.
Plain-English Explainer
Voice: patient, jargon-light. Output: 3-sentence summary, then detailed walkthrough with analogies. Use when: handing off a system to a non-engineer (PM, designer, founder).
The community keeps adding more. The awesome-claude-code-output-styles repo on GitHub features styles like Tabloid Journalist, Zen Master, and Haiku Helper. Most are joke styles, but the structure is identical to production ones -- a useful reference for frontmatter and tone control.
Token Cost and Performance
Output styles increase the system prompt size, which means more input tokens on the first request. Anthropic's prompt caching kicks in immediately after, dropping cached input tokens to roughly 10% of the standard rate. The marginal cost after the first turn is usually negligible.
Input tokens
Style body adds 200-2000 tokens depending on length. Cached on subsequent turns. Keep styles under 1500 tokens for the best latency profile.
Output tokens
Explanatory and Learning generate 30-60% more output than Default. Custom styles cost only what your instructions ask for. A "be terse" rule actively saves output tokens.
For production agents running on cron, prefer Default or a custom terse style. Save Explanatory for interactive onboarding sessions where you want the narration.
Common Issues and Fixes
Most output style issues come from misunderstanding when the style loads, what it overrides, or where the file lives. Here are the four mistakes that catch teams.
- ●Style change ignored. Output styles load at session start. Run /clear or relaunch claude after switching.
- ●Coding instructions disappeared. Custom styles default to keep-coding-instructions: false. Set it to true if you still want the default coding system prompt active.
- ●Style not in the picker. Check the filename matches the slug, and that the file lives in ~/.claude/output-styles or .claude/output-styles exactly. Subfolders are ignored.
- ●Team members see different styles. The default selection is stored in settings.local.json (per-machine). To pin a team-wide default, set outputStyle in the committed .claude/settings.json.
Frequently Asked Questions
What is a Claude Code output style?
A Claude Code output style is a markdown file that replaces parts of Claude's default system prompt to change tone, role, or response format while keeping core capabilities like file edits, scripts, and TODO tracking. Built-in options are Default, Explanatory, and Learning. Custom styles live in ~/.claude/output-styles or .claude/output-styles and are selected through /config or the outputStyle setting.
How is an output style different from CLAUDE.md?
Output styles directly modify the system prompt and turn off Claude Code's default coding instructions unless keep-coding-instructions is set to true. CLAUDE.md is appended as a user message after the default system prompt and never replaces it. Use output styles for voice, role, and format. Use CLAUDE.md for project facts, conventions, and environment notes that should always apply.
How do I create a custom output style in Claude Code?
Run /output-style:new inside Claude Code and describe the style in plain language. Claude scaffolds a markdown file with frontmatter (name, description, keep-coding-instructions) at ~/.claude/output-styles or .claude/output-styles. Edit the file to refine the system prompt content, then activate it with /config. Changes take effect at the next session start, not mid-session.
Do output styles cost more tokens?
Yes, but the impact is small after the first request. Adding instructions increases input tokens once, then prompt caching reduces the marginal cost to roughly 10% of the original on subsequent turns. The Explanatory and Learning built-in styles increase output tokens because they produce longer, narrated responses. Custom styles cost only what your instructions tell Claude to output.
Why does my output style change not take effect immediately?
Output styles load into the system prompt at session start. Changing the active style mid-session has no effect until you start a new conversation. This is intentional -- keeping the system prompt stable lets prompt caching reduce latency and cost. Run /clear or quit and relaunch claude after switching styles.
Can I have different output styles per project?
Yes. Save project-specific styles in .claude/output-styles within your repository and commit them. The selected outputStyle is stored in .claude/settings.local.json by default, which is per-machine. To pin a style for the whole team, set outputStyle in .claude/settings.json (the shared, committed config) instead.
Related Claude Code Guides
Claude Code Skills Tutorial
Build reusable skill packages with SKILL.md and frontmatter.
CLAUDE.md Setup Guide
Persistent project context, conventions, and environment notes.
Subagents Tutorial
Spawn isolated agents with their own context, model, and tools.
Best Claude Code Configuration
The complete settings.json reference with hooks and MCP.
The complete playbook
Every customization layer, every config, and the reasoning behind each decision -- in the full KaiShips Guide to Claude Code.
This post covers output styles. The guide covers CLAUDE.md, skills, hooks, subagents, worktrees, MCP, and 5 more chapters of production-tested configs.
Get the KaiShips Guide to Claude Code -- $29