Output Styles for Claude Code, your own tone in 20 minutes

You know the problem. Claude Code answers super helpful, but sometimes too verbose, sometimes too casual, sometimes with pseudo-optimism you do not need right now. You sit in code review mode and you want hard criticism, not "this looks great overall". Output Styles are exactly what that is for. One Markdown file, one prompt snippet, and Claude Code adopts a different personality for the session or the whole codebase.

1. Understand what Output Styles actually are

An Output Style is a Markdown file with YAML frontmatter that Claude Code loads as an additional system prompt fragment. Unlike skills or sub-agents, an Output Style does not change the tools Claude uses, only how it communicates. Tone, strictness, level of detail, language, format.

That means an Output Style is good for "I want Claude to answer tight" or "I need sober code review language". It is bad if you actually want to change tools, then you need a skill or sub-agent.

2. Create the directory

There are two places: user level in ~/.claude/output-styles/ and project level in .claude/output-styles/. User level applies to all projects, project level overrides user level when a name appears in both. Plugins can also ship Output Styles, but that is a different topic.

For the first test the user directory is enough:

mkdir -p ~/.claude/output-styles

3. Write the first style

Drop a file direct.md. Frontmatter with name and description, body is the prompt that gets appended to the system prompt.

---
name: Direct Reviewer
description: Tight honest code reviews without diplomacy
---

You answer tight and sober. No fluff like "great work" or
"looks good overall". When code has problems, say it directly in the first sentence.

For code reviews:
- Critical problems first, then the smaller ones
- Concrete suggestions with line number
- No summarising hymns of praise at the end
- If the code is fine, one sentence is enough

Save, done. Next time you start Claude Code the style is available.

4. Activate the style

Inside Claude Code you type /output-style and you get the list of all available styles. Default is always in there, plus whatever you set up yourself. Pick, done. The selection applies to the active session.

If you want the style as project-wide default, you can fix it in the settings.json of the project. I use this for codebases where the whole team should see the same tone.

5. Concrete use cases that pay off

I have four styles in daily use. First "direct" for code reviews and debugging, I want no diplomacy there. Second "tutor" when I have something explained to me, the style tells Claude to ask for assumptions instead of guessing. Third "german-only" which forces German in the answer because Claude likes to drift into English after 5 sentences otherwise. Fourth "diff-only" which on code changes returns only the unified diff, no prose around it.

On "diff-only" I noticed: Claude does not stick to it 100 percent, sometimes an explanation sentence still slips in. That is a prompt adherence problem, not a bug of Output Styles. On important constraints rather phrase twice ("only diff, no additional explanation, no text before or after the diff block").

6. Style vs. CLAUDE.md vs. skill, what is the difference

That was my first confusion. Three mechanisms that all influence Claude's behaviour. Here is the short delineation as I use it.

CLAUDE.md is where you store project-specific knowledge, "the DB is called X, the ENV var is Y, the deploy script is called Z". Output Style is for personality and format. Skill is for a recurring workflow with tools, for example "check cookie banner with three specific steps".

If you are not sure what you need: changing tonality is style, conveying knowledge is CLAUDE.md, step sequence with tools is skill.

7. The trap with ordering

Output Style gets appended to the system prompt, after CLAUDE.md. That means what is in the style tends to outweigh what is in CLAUDE.md. When the two contradict, the style often wins.

My case was: CLAUDE.md said "always answer with code examples when possible", the style "direct" said "keep it as short as possible". Result: no more code examples. I had to adjust the style because the project rule was more important.

Lesson: on conflicts rather soften the style than blow up the CLAUDE.md. Style is session layer, CLAUDE.md is project layer.

8. Team setup with project styles

When you work in a team, important styles belong in the repo under .claude/output-styles/. You commit that, everyone has it. Example: a "release-notes" style that sets the tone for changelog entries, an "incident-postmortem" style for outage reports.

Important here: no secrets in Output Styles. They end up in Git, everyone sees them. No API keys, no internal paths, no client names that should not be public. Output Styles are doc artefacts with system prompt effect, treat them like README files.

9. Debugging when the style does not bite

Three things that happened to me. First, style created, Claude Code was already running, new style did not show up. Fix: restart Claude Code or invoke /output-style once, sometimes that triggers a reload. Second, style is shown but not active, I just had not picked it. /output-style shows the currently active style with marker. Third, style is active but Claude does not follow it. There only helps formulating the prompt in the style more clearly and more imperatively. "Answer tight" works worse than "Maximum three sentences per answer, no introductory fluff".

10. What's next

When Output Styles clicked for you, look at Skills for Claude Code, because then you have the next layer on top: workflows that not only set tone but also tool sequences. Or read Your own slash commands for Claude Code if you want to combine the style on a call basis with concrete commands.

For the lesson layer Hooks and Skills fits as a concept refresher, that sharpens the boundary of when to use what.

Source

Output Styles officially: https://code.claude.com/docs/en/output-styles