How to write a custom output style for Claude Code, where to put it, how to activate it, and what actually gets replaced in the system prompt.
Verified against Claude Code 2.1.222 (native binary install) on macOS.
An output style is a Markdown file that changes how Claude Code talks to you. It is injected into the system prompt. It is not a memory file and not a set of project instructions.
By default a custom style replaces the built-in coding instructions in the system prompt. Set keep-coding-instructions: true in the frontmatter to keep them and layer your style on top. This is almost always what you want if you use Claude Code for engineering work.
Built-in styles shipped with the CLI: Default, Proactive, Explanatory, Learning.
| Scope | Path | Applies to |
|---|---|---|
| User | ~/.claude/output-styles/*.md |
Every project |
| Project | <repo>/.claude/output-styles/*.md |
That repo only |
| Plugin | <plugin>/output-styles/*.md |
Where the plugin is enabled |
Directories are auto-loaded. If you set the outputStyles setting to a list of directory or file paths, the output-styles/ directory is not auto-loaded any more and only your listed paths are used.
If you run Claude Code with a non-default config directory (CLAUDE_CONFIG_DIR), the user-level path follows it. For example ~/.claude-thomas/output-styles/. Each config directory needs its own copy of the file and its own settings.json entry.
---
name: Terse
description: Bare minimum words, point form, no preamble or recap
keep-coding-instructions: true
---
# Response style
Answer in the fewest words that fully carry the information.
- No preamble, no recap of the request, no closing summary.
- Point form by default, one line per point.
- ...Frontmatter fields:
| Field | Required | Meaning |
|---|---|---|
name |
No | Name shown in the /config output style picker and used in settings.json. Defaults to the filename without .md. |
description |
No | One-line blurb in the picker. Falls back to the first line of the body. |
keep-coding-instructions |
No | true keeps the default coding instructions in the system prompt alongside your style. Omitting it means your style replaces them. |
force-for-plugin |
No | Only meaningful for plugin-bundled styles. Ignored for user styles, and logs a warning if set. |
Everything below the frontmatter is the prompt. Keep it declarative and specific. Rules like "no em dashes" or "one line per point" are followed far more reliably than "be concise".
Limit: a style file over 1 MB is skipped.
Two ways.
- In-session:
/output-style <Name>, or pick it in/configunder Preferred output style. - In settings, so it is the default for new sessions:
The value must match the style's name, not the filename, if the two differ.
The picker enumerates output-styles/ when the session starts. A file you create mid-session will not appear until you restart Claude Code.
~/.claude/output-styles/terse.md in this repo under examples/terse.md.
It optimizes for word count without giving up honesty, which is the part most "be brief" prompts get wrong. Two things make it work:
- The rules are mechanical. "One line per point", "no em dashes", "at most one caveat, as the last line" are checkable. "Be concise" is not.
- It explicitly carves out honesty: brevity is about word count, so failures, skipped steps and unverified numbers still get stated. Without that clause a terse style tends to drop caveats along with the filler.
- Output style changes the voice of every response, and can replace the default coding instructions. Use it for how Claude talks.
- CLAUDE.md is project or user context that is always loaded. Use it for facts, conventions and standing preferences. Style rules work here too, and they stack with an output style rather than replacing anything.
- Skill is invoked for a specific kind of task. Use it for a workflow, not a tone.
If you only want a tone tweak and nothing else, CLAUDE.md is the lower-risk option because it never displaces the built-in coding prompt. Reach for an output style when you want the change to be selectable per session, or when you genuinely want to swap out the default instructions.
Style is not in the picker. Restart Claude Code. Styles are enumerated at session start. If it still does not show, check the file is directly inside output-styles/ (not a subdirectory), ends in .md, and that you are looking at the right config directory.
Style shows but settings.json does not select it. The outputStyle value must match the frontmatter name exactly, case included.
Claude got worse at coding after switching. You replaced the default coding instructions. Add keep-coding-instructions: true.
Warning about force-for-plugin. That field only applies to plugin-bundled styles. Remove it from user styles.
examples/terse.md the worked example above
README.md this guide
MIT