skip to content

Personalization & Extensions

Shaping Claude Code beyond the prompt: layered settings files, plugins that bundle skills, agents, hooks and servers, and output styles with a status line. Asked because team setups live here.

part ofClaude Coderead it →
on this pageshow

explore

questions

16

In Claude Code, which built-in output styles ship, what does each one change, and how do you switch between them?

level: juniorimportance: must knowfreq 22%

answer

  1. one default plus four styles
  2. result first versus Insight blocks
  3. TODO(human) for hands-on practice
  4. /output-style, /config, outputStyle
  5. case-sensitive value, next-message switch

basics

~20 s

Claude Code starts in Default and ships four more styles: Proactive acts without routine questions, Concise leads with the result, Explanatory adds Insight blocks, and Learning also leaves TODO(human) code for you. Switch with /output-style, /config or outputStyle.

solid answer

~40 s

Default means no style is selected: Claude works from Claude Code's standard software-engineering system prompt. The other four keep those instructions and add their own. `Proactive` starts work right away and makes reasonable assumptions instead of asking about routine decisions, without changing the permission mode. `Concise` leads with the result and drops preamble, narration and recaps while doing the work as thoroughly. `Explanatory` adds short `Insight` blocks in the conversation explaining its choices, and `Learning` adds those plus a `TODO(human)` marker where you write a few lines yourself. Switch with `/output-style concise` (v2.1.269 or later), the **Output style** entry in `/config`, or the `outputStyle` key in a settings file; the command and the menu save to `.claude/settings.local.json`. Since v2.1.251 a switch applies from your next message, with no `/clear` needed.

go deeper

for a junior

Name the five built-in styles and what each changes, and show one way to switch, such as /output-style concise or the Output style entry in /config.

for a middle

Explain that the four non-default styles keep the engineering instructions and add their own, that the choice lands in .claude/settings.local.json, and why a lowercase outputStyle value silently gives Default.

for a senior

Separate tone from control: Proactive changes how readily Claude acts but not the permission mode, and Concise keeps full error and security output. Know which release made mid-session switches apply from the next message.

for a principal

Decide where a team's default style should live, user file, shared project file or nothing, knowing a developer's local choice outranks the shared one and that styles shape tone, never policy.

## What an output style is 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. It saves you repeating "be brief" or "explain your reasoning" in each prompt. It is guidance: Claude follows it, but nothing in Claude Code enforces it. Project knowledge belongs in CLAUDE.md, and anything that must happen every time belongs in a hook. ## The five built-in styles **Default** is the absence of a style: Claude Code adds no style instructions and Claude works from its standard system prompt, written for software engineering. Each of the other four **keeps** those instructions and adds its own. | Style | What changes | Fits when | |---|---|---| | `Default` | Nothing is added | You want the standard engineering behaviour | | `Proactive` | Starts work at once, makes reasonable assumptions about routine decisions, and does not enter plan mode unless you ask for a plan | You will correct course if an assumption is wrong | | `Concise` | The first sentence states the result; no lead-in, step-by-step narration or closing recap; simple questions get one to three sentences | Default answers are longer than you want | | `Explanatory` | Adds short `Insight` blocks in the conversation explaining the choices behind the code | You are learning a codebase | | `Learning` | Adds `Insight` blocks and leaves a `TODO(human)` marker where a real design decision sits, then waits for you | New team members want hands-on practice | Some details interviewers probe: - **Concise does not cut engineering work.** It shortens prose only, and still writes in full when you ask for detail or when you need it to act safely: error reports, failing test output, security warnings and confirmations for destructive actions keep their complete content. It requires v2.1.237 or later. - **Explanatory writes nothing into your files.** The `Insight` blocks appear in the conversation, before or after the code they discuss. Learning is the style that edits files for teaching: it inserts the `TODO(human)` comment and asks you to fill it in. - **Proactive does not change the permission mode.** Your permission mode still decides which tool calls run without asking. The style's instruction to check with you before deleting data or touching shared or production systems is something Claude follows in conversation, separate from permission prompts. - **Token use differs.** Explanatory and Learning produce longer responses by design; Concise produces shorter ones. ## Switching styles 1. Run `/output-style <style>`, for example `/output-style concise`. With no argument it lists the styles and marks the current one. The command ignores case. 2. Or run `/config` and pick **Output style** from the menu. 3. Or set `outputStyle` in a settings file, such as `{"outputStyle": "Explanatory"}`. The command and the menu both save your choice to `.claude/settings.local.json`, the local project file. To make a style your default everywhere, set `outputStyle` in `~/.claude/settings.json`; a project's own settings files take precedence over it. ## Traps - **The settings value is case-sensitive.** Built-in names are written `Proactive`, `Concise`, `Explanatory` and `Learning`. A value that does not match a style name exactly, such as `explanatory`, gives you Default without an error, which is why a style that works from `/output-style` can silently fail from a hand-edited file. - **Mid-session switches apply from the next message.** Since v2.1.251 Claude uses the new style starting with your next message; before that release the new style applied only after `/clear` or a new session. - **Scripted and desktop use.** Since v2.1.269 `/output-style` also works in non-interactive runs and Agent SDK sessions. In the desktop app, `/config` opens the settings screen rather than a menu, so set `outputStyle` in a settings file there. - **Colour is a separate setting.** `/theme` changes the colour theme, including custom themes stored as JSON in `~/.claude/themes/`; it has no effect on how Claude writes. ## Release history worth knowing Anyone who learned output styles a few months earlier may remember a different command surface. In v2.1.73 the `/output-style` command was deprecated in favour of `/config`, and the style was fixed at session start. In v2.1.269 `/output-style [name]` returned to list and switch styles, including in non-interactive sessions and over Remote Control, where only built-in styles can be picked. Answers here assume v2.1.286.

  • You set "outputStyle": "concise" in .claude/settings.json and nothing changed, although /output-style concise worked earlier. Why?
    The settings value is case-sensitive while the `/output-style` command ignores case. `concise` does not match the style name `Concise` exactly, so Claude Code falls back to Default without an error. Write `"Concise"`. Also check `.claude/settings.local.json`: the command and the `/config` menu write there, and that local file outranks the shared project file.
  • Does the Proactive style mean Claude stops asking for permission before running commands?
    No. Proactive changes how Claude works, starting at once and assuming routine decisions, but it leaves the permission mode untouched, so permission prompts appear exactly as before. Its instruction to check with you before deleting data or changing a shared or production system is a conversational check Claude follows, not a permission prompt. Fewer prompts is a permission-mode decision, not a style one.
  • Which built-in style changes your files as part of its teaching, and how?
    Learning. When Claude reaches a piece with a real design decision, it writes a `TODO(human)` comment at that spot, sends a request saying what is built, what to write and what to weigh, then stops and waits. After you write the code and tell it you are done, it replies with an `Insight` about your code and continues. Explanatory never writes its explanations into files.

  • Proactive turns off permission prompts the way a permission mode would.
  • Concise does less thorough engineering work to keep answers short.
  • Explanatory writes its explanations into the code as comments.
  • outputStyle accepts any capitalisation, such as explanatory in lowercase.
  • Switching style mid-session still needs /clear or a restart.
  • /output-style is gone for good; only /config can switch styles.

Assumes Claude Code 2.1.286; /output-style <name> returned in 2.1.269, mid-session switches apply from the next message since 2.1.251, and Concise needs 2.1.237.

open as a page

What is a Claude Code plugin, and where do its manifest and its components sit in the plugin directory?

level: juniorimportance: must knowfreq 24%

basics

~20 s

A Claude Code plugin is a directory packaging skills, agents, hooks, MCP and LSP servers as one installable unit. Only the optional manifest lives in .claude-plugin/plugin.json; components sit at the plugin root, namespaced by the plugin name.

open as a page

Where do Claude Code's settings files live, and which one does a team commit versus keep personal?

level: juniorimportance: must knowfreq 30%

basics

~10 s

Claude Code reads ~/.claude/settings.json (you, every project), .claude/settings.json (the team, committed), .claude/settings.local.json (you, one project, kept out of git) and managed settings an organization deploys.

open as a page

In Claude Code, when one key is set in several settings files, which value wins, and why do list keys behave differently?

level: middleimportance: must knowfreq 17%

basics

~10 s

Claude Code uses the highest level setting a key: managed, then command line, then .claude/settings.local.json, then .claude/settings.json, then ~/.claude/settings.json. List keys such as permissions.allow merge across files instead.

open as a page

In Claude Code, how does an output style differ from CLAUDE.md, --append-system-prompt and a hook, and why can it never enforce a rule?

level: seniorimportance: must knowfreq 14%

basics

~20 s

An output style reshapes how Claude responds: built-ins add instructions, custom styles also drop the coding instructions unless kept. CLAUDE.md and --append-system-prompt only add. All three are guidance; enforcement comes from hooks and permission rules.

open as a page

What can a Claude Code plugin execute on your machine, and how do you review one before you install and enable it?

level: seniorimportance: must knowfreq 16%

basics

~20 s

A plugin runs code as you: hooks are shell commands, MCP and LSP servers are processes, and bin/ joins Claude's PATH. Permission rules and the sandbox do not cover hooks or servers, so read hooks.json, .mcp.json and bin/ first.

open as a page

How do you write and share a custom Claude Code output style, and what does its keep-coding-instructions field control?

level: middleimportance: should knowfreq 10%

basics

~10 s

A custom style is a Markdown file in ~/.claude/output-styles or a project's .claude/output-styles, with name, description and keep-coding-instructions frontmatter. Unless keep-coding-instructions is true, Claude Code leaves out its built-in software-engineering instructions.

open as a page

How does a Claude Code statusLine command receive session data, and how would you script a footer showing the git branch and context use?

level: middleimportance: should knowfreq 12%

basics

~20 s

Claude Code runs the statusLine command from settings with session JSON on stdin and shows whatever it prints to stdout. A script reads workspace.current_dir and context_window.used_percentage, asks git for the branch, and echoes one line.

open as a page

Rolling a Claude Code plugin out to twenty repositories, what do the user, project and local install scopes each write, and which wins?

level: middleimportance: should knowfreq 14%

basics

~20 s

Each scope writes an enabledPlugins entry: user to ~/.claude/settings.json, project to the committed .claude/settings.json, local to .claude/settings.local.json. Local beats project beats user, and a project entry turns an externally sourced plugin on without downloading it.

open as a page

How does a Claude Code plugin marketplace work, from its marketplace.json catalog to installing a plugin as name@marketplace?

level: middleimportance: should knowfreq 12%

basics

~10 s

A marketplace is a repository or directory whose .claude-plugin/marketplace.json lists plugins and where to fetch each. You register it once with /plugin marketplace add, then install plugins by entry name as plugin@marketplace.

open as a page

How does the env block in a Claude Code settings file interact with shell exports and with variables set in project-level files?

level: middleimportance: should knowfreq 8%

basics

~20 s

In a terminal session an env value overwrites the same shell export, and between files the highest-precedence one wins. Project and local files can't set some variables, such as CLAUDE_CONFIG_DIR or, since v2.1.282, the telemetry exporter variables.

open as a page

A teammate pushed fixes to your Claude Code plugin, but `claude plugin update` says it is already at the latest version. Why?

level: seniorimportance: should knowfreq 7%

basics

~20 s

Claude Code updates a plugin only when its computed version changes, and a version in plugin.json comes first. A pinned "version": "1.0.0" that was never bumped keeps everyone on the cached copy, however many commits land.

open as a page

A key committed to a repository's .claude/settings.json does nothing in one developer's Claude Code session — how do you find out why?

level: seniorimportance: should knowfreq 11%

basics

~20 s

Run /status to see which files loaded, then check for a higher layer setting the key, a key the shared file can't set, workspace trust not yet accepted, a broken or unread file, or a startup-only key.

open as a page

While developing a Claude Code plugin, how do you load and iterate on it without publishing it to a marketplace?

level: middleimportance: nice to knowfreq 8%

basics

~10 s

Start claude --plugin-dir ./my-plugin to load it for one session without installing, run /reload-plugins after each edit, and check it with claude plugin validate and the /plugin Errors tab.

open as a page

What do Claude Code's --settings and --setting-sources launch flags each do, and how do they interact with managed settings?

level: middleimportance: nice to knowfreq 6%

basics

~20 s

--settings adds JSON values for one session above the user, project and local files but below managed settings, merging key by key. --setting-sources chooses which of user, project and local files load; managed settings still load.

open as a page

A Claude Code status line goes blank, or shows a stale git branch while background subagents work: what decides when the statusLine command runs, and how do you fix each?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

The statusLine command runs at session start and on events such as a new assistant message, /compact, or a permission-mode change, debounced 300ms. Idle sessions fire none, so set refreshInterval; blank means a non-zero exit, empty stdout or an untrusted folder.

open as a page