Output Styles skill for Claude Code

A good output style changes how every response reads (voice, length, structure, role) without degrading the engineering work, fits on one screen, and is verified by a short side-by-side test against the Default style. If the requirement is about one kind of task or must never be skipped, it is not an output style.

Pick the right mechanism first

The user wants	Use	Why
Every response shorter, longer, more didactic, in a fixed format, or Claude in another role	Output style	Session-wide, switchable with one command
Claude to know build commands, conventions, architecture	CLAUDE.md (see memory-file-architect)	Knowledge, loaded regardless of style
A procedure for one kind of task (release, review, migration)	Skill (see skill-authoring)	Loads only when relevant
Something enforced every time (format after edit, block a command)	Hook (see hooks-automation)	The harness runs it; styles are only instructions
A helper with its own tools and model	Subagent (see subagent-design)	Styles do not apply to non-fork subagents
Extra instructions for one scripted run	--append-system-prompt / --append-system-prompt-file	Per-invocation, no file to manage

Check the built-ins before writing anything: Proactive (acts on routine decisions without asking), Concise (result first, no narration or recap), Explanatory (adds short Insight blocks explaining choices), Learning (Insights plus TODO(human) handoffs for the user to write code). If one of these is 80% of the ask, recommend it and stop.

How styles work (the parts that matter)

• A style’s text is sent with every request in the main conversation and in forks. Regular subagents run their own system prompt and ignore the style.
• Custom styles drop Claude Code’s built-in software-engineering instructions (scoping changes, comments, verification habits) unless the frontmatter sets keep-coding-instructions: true. Set it whenever Claude will still edit code.
• Style files are read at startup. After creating or editing one, restart Claude Code; switching between already-loaded styles applies from the next message.
• The outputStyle settings value is case-sensitive and must equal the style name exactly. A mismatch silently gives Default. The /output-style command ignores case.
• Selecting a style via /output-style or /config writes outputStyle to .claude/settings.local.json. For a personal default everywhere, set it in ~/.claude/settings.json; project settings override that.
• A style adds input tokens to every request (cached after the first). Long styles are a recurring cost; keep them under ~60 lines.

File locations and frontmatter

Scope	Path	Notes
User	~/.claude/output-styles/<file>.md	Available in every project
Project	.claude/output-styles/<file>.md	Commit to share; nested .claude/output-styles/ dirs between cwd and repo root also load, closest wins on name clash
Plugin	<plugin>/output-styles/<file>.md	force-for-plugin: true applies it automatically when the plugin is enabled

---
name: Terse Reviewer
description: Findings-first code review voice, no preamble
keep-coding-instructions: true
---

<instructions>

All keys are optional. name defaults to the file name. Misspelled keys are ignored without an error; if the YAML fails to parse, the style loads with no fields set (run claude --debug to see the parse error).

Workflow

- [ ] 1. Write the requirement as observable behavior ("first line states the result")
- [ ] 2. Check whether a built-in style already covers it
- [ ] 3. Decide keep-coding-instructions (true unless Claude stops doing engineering)
- [ ] 4. Draft the style: role, format rules, exceptions, examples
- [ ] 5. Save at the right scope; restart Claude Code
- [ ] 6. Switch with /output-style <name> and run the 4-prompt test
- [ ] 7. Trim anything that did not change behavior; commit project styles

Step 1 — observable rules, not adjectives

“Be concise” changes little. Rules Claude can follow and you can check:

Vague	Observable
Be concise	First sentence states what changed or the answer. No recap paragraph. Simple questions get 1–3 sentences
Be educational	After each non-trivial change, add one “Why” bullet naming the trade-off
Professional reports	Every response that analyzes something ends with a Findings / Evidence / Next step table
Act like a data analyst	Show the query, the result table, then one paragraph of interpretation with caveats

Step 4 — structure of a style body

Write it in this order; each section is a few bullets:

1. Role — one sentence: who Claude is in this mode and for whom.
2. Response shape — the default layout (lead line, sections, tables, length caps).
3. Always — 3–6 hard habits (cite file:line, show commands run, state assumptions).
4. Never — 2–4 things to suppress (narrating tool calls, restating the question).
5. Exceptions — when to break the shape: the user asks for detail, errors, security warnings, destructive-action confirmations. Without this, terse styles hide failures.
6. One short example of a correctly shaped response. Examples steer harder than rules; keep it under 15 lines so it is not copied verbatim.

Ready-made bodies (terse reviewer, teaching mode, incident scribe, non-coding analyst, stakeholder report writer) are in references/style-templates.md. Read it when drafting, then adapt rather than paste.

Step 6 — the 4-prompt test

Run the same four prompts in Default and in the new style (fresh session each, or /clear between):

1. A one-line factual question about the repo (“what test runner is this?”).
2. A small code change (“add input validation to <function>”).
3. A failing command (ask it to run a test you know fails).
4. A request that must override the style (“explain this module in depth”).

Pass criteria: prompts 1–2 follow the new shape; prompt 3 still shows the full error and what was tried; prompt 4 expands; the code change in prompt 2 is as careful as in Default (tests run, scope kept). If prompt 2 regressed, keep-coding-instructions is probably missing.

For scripted checks, select the style per run with --settings so nothing is persisted:

claude -p --settings '{"outputStyle":"Terse Reviewer"}' "what test runner does this repo use?"
claude -p --settings '{"outputStyle":"default"}'        "what test runner does this repo use?"

Gotchas

• Writing project conventions into a style. They vanish when someone switches styles; they belong in CLAUDE.md.
• Expecting a style to guarantee format for machine consumption. For parseable output in scripts use claude -p --output-format json or --json-schema, not a style.
• Styles that forbid explanation entirely make Claude omit test failures and risks. Always keep the Exceptions section.
• A team style committed to .claude/output-styles/ does nothing until each person selects it, unless the project .claude/settings.json sets outputStyle. Setting it at project level forces it on everyone; prefer leaving the choice to each developer.
• force-for-plugin overrides the user’s own choice. Use only for plugins whose whole purpose is the style.
• Do not name a custom style like a built-in (Concise); the picker becomes ambiguous.

Verification

1. /output-style (no argument) lists the style and marks it current.
2. The 4-prompt test passes, with the Default comparison noted.
3. /context shows the style’s token cost is modest (aim for under ~1.5k tokens).
4. If it does not apply: confirm the exact name, restart after edits, check for a project outputStyle overriding the user one, and run claude --debug for YAML errors.

Output

**Style:** Terse Reviewer (`.claude/output-styles/terse-reviewer.md`, committed)
**keep-coding-instructions:** true (Claude still edits code in this mode)
**Selected via:** `/output-style Terse Reviewer` (per developer, not forced in project settings)
**Test (Default vs style):** factual Q 4 lines -> 1; code change identical diff, tests run in both;
failing test output shown in full; "explain in depth" expanded correctly
**Not in the style (moved):** test commands -> CLAUDE.md; "always run prettier" -> PostToolUse hook