Solo Stack Kits Directory
Claude Code workflows & skills for solo consultants and freelancers

← Blog · 2026-10-17

Claude Code Output Style Not Working? 12 Causes and Fixes

Shortcut: our free output style builder writes a valid custom output style file (front matter plus instructions), tells you where to save it, and gives you the exact /output-style command and outputStyle value, so the naming and YAML problems below can't happen. It runs in your browser.

An output style is a set of instructions that sets Claude's role, tone and response format for every response in a Claude Code session. There are built-in styles (Proactive, Concise, Explanatory and Learning, plus Default, which means no style), and you can write your own as a Markdown file in ~/.claude/output-styles/ (all your projects) or .claude/output-styles/ (one project).

When a style "doesn't work", it's almost always one of three things: Claude Code never picked up the style, a different setting won, or the style loaded and is doing exactly what its instructions say, which isn't what you expected. Work through the checks below in order.

First: which style is actually active?

Run /output-style with no argument. It lists the styles you can pick and marks the current one. If your custom style isn't in the list, start at cause 1. If it's listed but not marked as current, start at cause 5. If it's marked current and Claude still doesn't sound right, skip to cause 9.

Not loaded: 4 reasons your custom style is missing

  1. The file is in the wrong folder. Custom styles live in ~/.claude/output-styles/ (user) or .claude/output-styles/ (project). Note the plural and the hyphen: a file saved in .claude/ itself or in a singular output-style/ folder isn't in either location. (Plugins can also ship styles in their own output-styles/ directory.) Project styles load from every .claude/output-styles/ folder between your working directory and the repository root.
  2. You created or edited it during a running session. In the terminal, Claude Code reads style files when it starts. A file you add or change mid-session doesn't show up until you restart Claude Code.
  3. You're looking for it in a place that only lists built-ins. When you use /output-style from the mobile app or web via Remote Control, you can list and select only built-in styles. In the VS Code extension, the Output styles menu (type /, select Output styles) does include your custom styles, but it needs Claude Code v2.1.257 or later.
  4. You started in safe mode. claude --safe-mode launches a session with your customizations turned off, and custom output styles are one of them. Start Claude Code normally.

Loaded but not selected: 4 reasons another value wins

  1. The outputStyle value has the wrong case. In a settings file, the value is case-sensitive. Built-ins must be written Proactive, Concise, Explanatory and Learning. A value that doesn't match a style name exactly, such as explanatory, gives you the Default style, with no error. (The /output-style command ignores case, which is why it works there and not in the file.)
  2. The name doesn't match your file. A custom style's name is its file name unless you set name in the front matter. If the file is client-ready.md but the front matter says name: Client ready, the setting must say "outputStyle": "Client ready". Copy the name character for character.
  3. A closer settings file overrides yours. The /output-style command, the /config menu and the VS Code menu all save your choice to .claude/settings.local.json in the project. Local settings override the project's settings.json, and both override ~/.claude/settings.json. So a default you set in your user settings loses to any project that sets outputStyle, and an edit to .claude/settings.json loses to an old choice still sitting in settings.local.json. Managed (organization) settings apply first when present. Run /status to see which settings sources are active, and claude doctor to find invalid settings files. Our free settings precedence checker shows which file's outputStyle wins.
  4. A plugin forces its own style. A plugin output style can set force-for-plugin: true, which applies that style whenever the plugin is enabled and overrides your outputStyle setting. If you recently enabled a plugin and your style stopped applying, check that plugin.

Active but behaving oddly: 4 reasons it doesn't do what you expect

  1. Your YAML didn't parse, or a field is misspelled. If the front matter doesn't parse, the style still loads under its file name with no fields set, so your name, description and keep-coding-instructions are all dropped. A misspelled field (for example keep_coding_instructions with underscores) is ignored without an error. Field names are lowercase words separated by hyphens. Run claude --debug to see the parse error.
  2. Claude got worse at coding after you switched. On the full system prompt, a custom style leaves out Claude Code's built-in software engineering instructions (how to scope changes, write comments and verify work) unless you set keep-coding-instructions: true. The default is false. If you only wanted to change how Claude talks, add that line. One catch from the docs: the shorter system prompt doesn't include that section, so the field has no effect there; to rely on it, set the environment variable CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT to 0.
  3. Your subagents don't use it. Output styles apply to the main conversation and to a fork (which inherits the parent's conversation and system prompt). Other subagents run their own system prompt, so a style doesn't change how they respond. Set a subagent's tone in its own file.
  4. It's an instruction, not a guarantee. An output style gives Claude instructions to follow; nothing enforces it. Even the built-in Concise style writes at full length when you ask for detail, and for error reports, failing test output, security warnings and confirmations for destructive actions. If something has to happen every time, such as formatting after each edit, use a hook. If it's project knowledge, put it in CLAUDE.md, which stays loaded whichever style you pick.

Version gotchas

Several output style behaviors depend on your Claude Code version, so update before you debug further:

Desktop app note

In the desktop app, /config opens Settings > Claude Code rather than the style menu. Set the outputStyle field in a settings file instead, for example .claude/settings.local.json.

A minimal style that loads

---
description: Plain-English answers I can paste into a client email
keep-coding-instructions: true
---

Write for a non-technical client. Lead with the outcome in one sentence,
then at most three short bullets. No jargon, no code unless asked.

Save it as ~/.claude/output-styles/client-ready.md, restart Claude Code, then run /output-style client-ready. With no name field, the file name is the style name. Or set it in a settings file:

{
  "outputStyle": "client-ready"
}

Claude uses the new style starting with your next message.

Facts on this page come from Anthropic's output styles documentation and debug your configuration guide. This guide isn't affiliated with Anthropic.

If you write client-facing work in Claude Code, skills handle the repeat jobs an output style can't. Start with our free 3-skill sample (client follow-ups, meeting notes to tasks, invoice chasing), or get the full Solo Consultant Kit.