Learning objectives

By the end of this chapter, you will be able to:

1. Explain what an output style is — a reusable definition that reshapes *how* Claude Code responds (role, tone, output format) by modifying its system prompt, not *what* it knows — name the built-in styles (Default, Explanatory, Learning, and the newer Proactive), and select one with `/config` → Output style (the standalone `/output-style` command the book uses was removed).
2. Author a custom output style as a Markdown file with YAML frontmatter — `description` plus the load-bearing `keep-coding-instructions` — at user scope (`~/.claude/output-styles/`) or project scope (`.claude/output-styles/`), and explain that selecting it drops Claude Code's built-in software-engineering instructions unless `keep-coding-instructions: true`.
3. Distinguish output styles from the other ways to shape Claude Code's behavior — CLAUDE.md (a user message added *after* the system prompt), `--append-system-prompt` (a one-off append), subagents (a separately scoped helper), and Skills (loaded on demand) — and pick the right tool for a given need.
4. Use a structured-output style (YAML) so the format itself carries meaning (dependencies, priority, hierarchy), and build an advanced style that adds workflow *instructions* — asking Claude to generate a complete HTML page and save it to disk — in the style definition itself, while recognizing that a style is system-prompt text (a strong nudge, not a guaranteed action: execution still depends on tools, permissions, and Claude following it; for steps that must run every time, use a hook or script).
5. Customize the status line: configure it with the `/statusline` command or the `statusLine` key in `settings.json`, and explain the data flow — Claude Code pipes session JSON (model, context usage, cost, active output style, `transcript_path`) to your script on stdin, and whatever the script prints to stdout becomes the persistent status bar, with ANSI color support.
6. Describe how several Claude Code instances, each with a distinct output style and role, can act as a 'team of specialized agents,' and judge that framing honestly against the documented alternatives — subagents and (experimental) agent teams — for role-specialized parallel work.

Before we start — system prompts, output styles, stdin/stdout, and ANSI

Skim this if you're already comfortable with what a system prompt is, what gets piped through stdin/stdout, and what YAML and ANSI escape codes are. If any of that is fuzzy, read it first — the whole chapter rests on these ideas.

The system prompt vs. your prompts. Every time you talk to Claude Code, the model receives two kinds of text. Your user prompt is the request you just typed ("fix this bug"). The system prompt is a large block of standing instructions Claude Code sends on every turn, before your request — it tells the model who it is ("you are Claude Code, a software-engineering assistant"), how to use its tools, how to be safe, and how to write code. You normally never see it. This chapter is about editing that standing block — because changing it changes how Claude behaves on every single response.

An output style is the feature for doing exactly that. It's a small, named, reusable definition that modifies the system prompt to set a role, a tone, and an output format. Claude Code ships a few built-in styles and lets you write your own as plain files. Switch styles and Claude keeps all its knowledge and tools — it just presents differently: terse bullets, structured YAML, an HTML page, a patient teacher's voice. The book's framing is worth keeping: output styles change "how responses are structured and delivered… the communication protocol between the user and the model."

A status line is the thin, always-visible strip at the very bottom of the terminal — like a car's dashboard. It's optional and fully customizable. You point Claude Code at a small script; Claude feeds that script live information about the session, and whatever the script prints shows up in the strip.

stdin and stdout (the pipe). Command-line programs have a standard input stream (stdin — text flowing in) and a standard output stream (stdout — text flowing out). Claude Code talks to your status-line script through these: it writes a blob of JSON to the script's stdin, and reads back whatever the script prints to stdout. If you've ever run cat file | grep foo, you've used a pipe — the same idea.

JSON and YAML are two ways to write structured data. JSON ({"key": "value"}) is what Claude Code pipes to your status-line script. YAML is a more human-readable format that uses indentation instead of braces — and in this chapter it shows up twice: as the frontmatter at the top of a style file, and as an output format you can ask Claude to respond in.

Frontmatter is a small YAML block fenced by --- lines at the very top of a Markdown file. You met it in Chapters 3 and 7 (skills and subagents). Output style files use the same pattern: a frontmatter block of metadata, then a Markdown body of instructions.

ANSI escape codes are special character sequences (like \033[1;32m) that terminals interpret as "switch to bold green," etc., rather than printing literally. They're how a status-line script adds color.

Where this sits relative to Chapter 7. Chapter 7 gave you subagents — handing a scoped job to a specialist with its own system prompt. This chapter zooms back out to the main session and asks a different question: not "who do I delegate to?" but "how do I want this assistant to talk to me and what should the interface show?" By the end you'll treat Claude Code less like a fixed appliance and more like a studio you wire up for the task in front of you.

How to read this chapter. Each numbered section ends with an > Analogy — … box that restates the idea in plain language. Lean on them or skim them as you like.

Why this chapter matters

For seven chapters Claude Code has talked to you in one voice — the default software-engineering assistant. That voice is a deliberate design choice baked into its system prompt, and for most coding work it's the right one. But it's a choice, not the choice. When you're reviewing a PR you might want terse, severity-grouped bullets. When you're onboarding a teammate you might want a patient, explain-as-you-go tutor. When you're feeding Claude's output to another tool you might want rigid YAML or JSON. Re-typing "be concise, use bullets, no preamble" on every turn is friction; worse, it's unreliable.

Output styles remove that friction by letting you engineer the communication protocol itself — once, in a file, versioned with your repo. The book puts the shift plainly: you move from consuming Claude's output to designing how it's produced. And because a style is just a system-prompt modification, the same mechanism reaches surprisingly far: a style can make Claude think in structured data, or instruct it to carry out a small workflow (write a file, open it) — with the usual caveat that an instruction is a request, not a guarantee, and any file-writing or browser-opening still depends on Claude's available tools, your permissions, and Claude actually following the instruction.

This chapter builds that up in order. First, what an output style is and how you select or write one. Then how it works — it rewrites part of the system prompt — and how that differs from the other knobs you already know (CLAUDE.md, --append-system-prompt, subagents, Skills). Then two richer styles: one that responds in YAML, and one that emits a complete HTML page and asks Claude to save it. Then the status line — runtime customization of the interface, driven by a script you write. Finally, the book's closing vision: running several specialized instances side by side as a "team" — which we'll take seriously and check honestly against what the docs actually recommend.

A note on currency. Claude Code moves fast, and this is one of the chapters where it shows. The book drives everything through a standalone /output-style command — that command was removed (deprecated in v2.1.73, removed in v2.1.91); you now pick a style through /config. The set of built-in styles has also grown. We teach the current surface and flag the book's version as you go, with soft wording where the exact shape keeps moving. Verify against code.claude.com/docs/en/output-styles before you rely on a specific command name.

Lesson

1. What an output style is — and how you pick or write one

An output style changes how Claude responds, not what it knows. It sets a role, a tone, and an output format by modifying Claude Code's system prompt. Reach for one when "you keep re-prompting for the same voice or format every turn, or when you want Claude to act as something other than a software engineer."

The built-in styles. Claude Code ships a small set of ready-made styles. The Default style is the ordinary software-engineering system prompt you've used all along. As of writing there are three more:

• Explanatory — completes tasks the usual way but adds educational "Insights" along the way, explaining implementation choices and codebase patterns.
• Learning — a collaborative, learn-by-doing mode: Claude shares insights and asks you to write small strategic pieces yourself, dropping TODO(human) markers in the code for you to fill in.
• Proactive — Claude executes immediately and makes reasonable assumptions instead of pausing for routine decisions, preferring action over planning (you still see permission prompts before tools run).

The book lists only Default / Explanatory / Learning — and even flags, in a margin note, that "the built-in output styles available in Claude Code may evolve over time… depending on your installed version, you may see additional styles." That note has already come true: Proactive is a newer addition. Treat the built-in list as a moving target and check /config on your own install.

Selecting a style. The book lists and switches styles with a standalone /output-style command. That command no longer exists — it was deprecated in v2.1.73 and removed in v2.1.91. Today you switch styles one of two ways:

# The interactive way: run /config, then choose "Output style" from the menu.
/config

Your choice is saved to .claude/settings.local.json (the per-project, per-user settings file). Or set it without the menu by editing the outputStyle field in any settings file directly:

{
  "outputStyle": "Explanatory"
}

Because the output style is part of the system prompt — which Claude Code reads once at session start — a change takes effect after /clear or in a new session.

Writing your own. A custom output style is just a Markdown file: a YAML frontmatter block of metadata, then a Markdown body of instructions to add to the system prompt. Where the file lives sets its scope:

~/.claude/output-styles/        # user scope — available in all your projects
.claude/output-styles/          # project scope — committed to the repo, shared with the team

(A third, managed-policy location exists for organization-administered settings, and plugins can ship styles in an output-styles/ directory — but the two above are the ones you'll create yourself. Project styles win over user styles of the same name.)

The book's first example is a user-scoped style at ~/.claude/output-styles/minimal-bullets.md:

---
description: Concise bullet-point responses with direct communication
---
# Communication Style
- Use bullet points for all responses
- Be direct and to the point
- Use nested bullets for hierarchy
- Skip preamble and transitions

# Tone
- Professional and concise
- No hedging or qualifications

The frontmatter carries metadata; the body below it becomes the instructions added to the system prompt. The frontmatter fields are few, and only one of them is load-bearing:

• description — a short summary shown in the /config picker. (The file name becomes the style's name unless you override it with a name field.)
• keep-coding-instructions — a boolean, defaulting to false. This is the field the book never mentions, and it matters a great deal — §2 is about exactly what it does.
• force-for-plugin — for plugin-shipped styles only; auto-applies the style whenever the plugin is enabled.

Once the file exists, the style shows up in /config alongside the built-ins, and selecting it makes it active. From then on, Claude applies its instructions to every request — the minimal-bullets style turns answers into terse, filler-free nested bullets.

Analogy — the dress-code card by the door A new hire's skills don't change when they swap outfits. But a laminated card by the door says "front-of-house today: blazer, formal, brief" or "back-office: casual, chatty." An output style is that card for Claude: it doesn't change what Claude knows or which tools it has — it changes how it shows up. A few cards come pre-printed (Default, Explanatory, Learning, Proactive); you can also write your own and hang it in the personal closet (~/.claude/…) or the shared one by the project's front door (.claude/…).

2. How output styles work — rewriting the system prompt

Here's the mechanism, and the one nuance that the book half-explains. Output styles modify Claude Code's system prompt directly. Concretely:

• Every output style adds its instructions to the end of the system prompt, and sets up reminders so Claude keeps following them through the conversation.
• A custom style leaves out Claude Code's built-in software-engineering instructions — the standing guidance about how to scope changes, write comments, and verify work — unless you set keep-coding-instructions: true.

The book sees the first half of this: "Selecting an output style replaces parts of Claude Code's system prompt… Claude Code removes its default software engineering instructions and substitutes them with the selected style's instructions." What it omits is the escape hatch. That default-false behavior is perfect when Claude isn't doing software engineering at all (a writing assistant, a data analyst). But when you only want to change how Claude communicates while it keeps coding the way you trust — "always lead with a diagram," say — you set keep-coding-instructions: true, and you get both your custom instructions and the engineering brain underneath:

---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true
---
When explaining code, architecture, or data flow, start with a Mermaid
diagram showing the structure, then explain in prose.

Get this wrong and you'll be surprised: a custom style with no keep-coding-instructions flag will quietly strip out the coding guidance, and Claude may stop scoping or verifying changes the way you expect. So the rule of thumb: non-coding role → omit it (default false); change the voice but keep coding → set it true.

This is also the moment to place output styles among the other behavior-shaping tools you already know. They are not interchangeable — each works at a different layer:

The sharpest distinction is the first two. CLAUDE.md is advisory project context delivered as a user message — Claude reads it and tries to follow it. An output style is the system prompt — it sets the role itself. That's why the docs are emphatic: "For instructions about your project, conventions, or codebase, use CLAUDE.md instead" of an output style.

Analogy — the script vs. the sticky note The actor (the model) is the same person every night. Their standing script (the system prompt) tells them who they're playing and how to deliver lines. An output style rewrites pages of that script — and keep-coding-instructions is the director deciding whether to keep the "you're a meticulous engineer" pages or tear them out for a "you're a friendly writing coach" role. CLAUDE.md isn't in the script at all: it's a sticky note slipped to the actor after rehearsal — "remember, this theater's curtain is heavy, pull slowly." Helpful context, but it doesn't change who they're playing.

3. Structured output — making the format carry the meaning

So far the styles changed tone. The more interesting move is changing the shape of the output — and the book's worked example is a YAML style. The argument for it is subtle and worth getting: when you ask Claude to answer in YAML, "the format itself becomes a communication protocol." Prose is linear — one sentence after another. YAML is hierarchical — and that hierarchy can encode meaning that prose only gestures at:

• Dependencies become parent–child nesting.
• Priority can be read from ordering.
• The structure of the problem is mirrored in the structure of the answer.

The book demonstrates with a project-scoped style. You create .claude/output-styles/yaml-concise.md:

---
description: Concise YAML-formatted responses for structured tasks
---
# Output Format
- All responses must be formatted as valid YAML
- Use hierarchy and nesting to express relationships
- Keep replies concise — no full sentences unless necessary

# Structure
- Use top-level keys to represent major sections
- Nest subconcepts under their parent context
- Use lists for enumerations and sequences
- Use key-value pairs for properties and attributes

# Tone
- No prose, no filler, no transitional language
- Let the YAML structure carry the meaning

With that style active, asking Claude to plan an authentication-bug fix no longer returns a paragraph or a flat to-do list — it returns a structured plan whose shape is the architecture of the work:

investigate:
    auth_flow: &flow
        - login_endpoint
    reproduce: "invalid_token_scenario"
fix:
    dependencies: [*flow]
    files_to_modify:
        auth.js:
            scope: "token refresh logic"
            risk: "low"
        middleware.js:
            scope: "validation checks"
            risk: "urgent"
verify:
    tests: ["auth_integration", "token_expiry"]
    manual_check: "login flow end-to-end"
metadata:
    estimated_time: "2 hours"
    rollback_plan: "revert commits"
    monitoring: "error_rate_dashboard"

The book's point lands here: this "mirrors how YAML is used in configuration systems such as Kubernetes and Docker Compose" — the format nudges Claude toward thinking in relationships and dependencies rather than sequential narration. Two practical payoffs follow. First, it's machine-readable: a downstream script or tool can parse this directly, which is exactly when a rigid format earns its keep. Second, defining it at project scope means everyone on the repo who selects the style gets the same structured contract — the format is versioned with the code.

There's a deeper framing the book makes, and it's the thesis of the chapter: by designing the output format, "control over interaction is therefore not limited to model providers; developers… define and control the communication protocol." You're no longer accepting whatever shape the model defaults to — you're specifying it.

Analogy — the form vs. the blank page Hand someone a blank page and "tell me about the bug" and you get a wandering paragraph. Hand them a form — boxes for investigate, fix, files & risk, verify, rollback — and the boxes do half the thinking: they force dependencies and priorities into the open and leave no room for filler. A YAML output style is that form. The shape of the form shapes the answer.

4. A style that asks for more — HTML generation and embedded workflow instructions

The last output-style move is the one that pushes a format toward a behavior. The book's advanced example is a project-scoped style, .claude/output-styles/retro-ASCII_blog.md, that instructs Claude to answer with a complete HTML page styled like a vintage ASCII-art blog. The whole instruction set lives in one Markdown file — the book emphasizes it needs no extra scripting or plugins:

---
description: Format responses as retro HTML pages with ASCII art styling like a vintage blog
---
Format all responses as complete HTML pages with retro ASCII art styling.
Follow these guidelines:

## HTML Structure
- Always provide complete HTML5 documents with proper DOCTYPE, head, and body tags
- Use semantic HTML elements (header, main, section, article, aside, footer)

## ASCII Art Styling
- Use ASCII art for headers, dividers, and decorative elements
- Create borders using characters like =, |, +, _, ^, #, -, *
- Use monospace fonts throughout for consistent ASCII alignment

## CSS Requirements
- Embed CSS in <style> tags in the HTML head
- Use monospace fonts (Courier New, Monaco, Consolas, monospace)
- Set background to dark colors (#1a1a1a, #2d2d2d) with light text
- Use retro color schemes (green on black, amber on black, etc.)
- Add subtle glow effects or text shadows for retro terminal feel

Select that style, ask "What are output styles?", and Claude emits valid HTML markup. But raw markup printed in the terminal isn't useful — and that exposes the key idea. The book first instructs Claude, by hand, to dump the HTML to a file (output-styles-blog.html) so it can be opened in a browser. Doing that every time is repetitive. So the book's move is to embed the workflow into the style definition itself by appending a short instruction:

## Workflow
- Save the HTML response to a file after writing it, then open it in the browser

Now the style doesn't merely describe a format — it asks Claude to run a small procedure: generate the HTML, write it to disk, open it. As the book stresses, "no callable logic is introduced. The prompt remains minimal" — the style is pure instructions. But be precise about what that buys you: an output style is system-prompt text, not an execution engine. It can ask Claude to save a file and open a browser, but whether that actually happens on a given turn still depends on the tools Claude has, your permission settings, the session mode, and Claude choosing to follow the instruction — it is a strong nudge, not a guarantee. (And the book is candid that the rendered page is intentionally ugly; the point is to prove there are "no inherent limitations imposed by predefined templates" — you could just as easily have each response write a new page into a Next.js app.)

So the honest framing: a style is not just a costume — it can carry standing instructions that ask Claude to take actions. That's why output styles "influence not only how responses look but also how they are operationalized." Just don't mistake a nudge for a contract: when you need a step to run deterministically every time — on a guaranteed lifecycle event, regardless of what Claude decides — reach for a hook or a script, not an output style. (Hooks and the broader extension surface are the deterministic counterpart to a style's instructions.)

Analogy — the note on the order ticket vs. the conveyor belt Embedding a workflow in an output style is like writing "and please file a copy when you're done" at the bottom of every order ticket. A conscientious clerk will usually do it — but it's still a request to a person who needs the filing cabinet (the tools), the keys (permissions), and the will to follow through; on a busy day it might get skipped. If you need the copy filed every single time, no exceptions, you don't rely on a note — you put a conveyor belt at the end of the line that files it automatically (a hook or script). The style is the note; the hook is the belt. Use the note for "usually do this," the belt for "always do this."

5. Customizing the status line

The second half of the chapter leaves output formatting and customizes the interface at runtime. The status line is the persistent strip at the bottom of the terminal; you make it show whatever you want by pointing Claude Code at a script. There are two ways to set it up, and the book uses the first:

• The /statusline command. Describe what you want in natural language; Claude Code generates a script file in ~/.claude/ and updates your settings automatically. The book's prompt:

``text /statusline I want you to create a statusline that displays the current used output-style. ``

• Manual configuration. Add a statusLine block to a settings file yourself. The book uses the user-scoped ~/.claude/settings.json; the project-scoped .claude/settings.json is equally valid:

``json { "statusLine": { "type": "command", "command": "uv run ~/.claude/statusline.py" } } ``

type is command; command is any shell command that runs your script. (The book runs Python through the uv package manager — uv run … — but a status line can run a shell script, a Node.js file, or anything executable. Plain python3 … works fine for a stdlib-only script.)

The data flow is the thing to understand. Claude Code writes a blob of JSON describing the session to your script's stdin; your script reads it, decides what to display, and prints to stdout; whatever it prints becomes the status line. The book's minimal Python script reads the active style:

import json
import sys

input_data = json.load(sys.stdin)
style = input_data.get("output_style", "default")
print(style)

One correction worth knowing. The current JSON schema nests the style name: the field is output_style.name, not a bare output_style string. So a robust read today is input_data.get("output_style", {}).get("name", "default"). The book's one-liner above reflects an earlier shape — keep it as the idea, but use the nested field on a current install. (The canonical minimal examples in the docs read model.display_name and context_window.used_percentage, which are unambiguous.)

Color is just ANSI escape codes in what you print:

print(f"\033[1;32m{style}\033[0m")   # bold green

What's actually in that JSON is far richer than the book shows — and it's the reason the status line is powerful. The session object includes (among others):

• model.display_name / model.id — the active model;
• output_style.name — the active style (the book's example);
• context_window.used_percentage / remaining_percentage / context_window_size — live context budget (great for a usage bar);
• cost.total_cost_usd and duration fields — running session cost;
• workspace.current_dir and workspace.repo — directory and git info;
• transcript_path — a path to the session's transcript file (used next);
• and conditional extras like agent.name, pr, worktree, and subscription rate_limits.

The schema grows between releases, so check code.claude.com/docs/en/statusline for the current field list rather than memorizing it.

Extending it — the last user prompt. The book's richer example uses transcript_path to show the last thing you asked. Claude Code stores each session's messages as a JSONL file (one JSON object per line) under ~/.claude/projects/<encoded-project-path>/. The extended script opens the transcript, scans from the end for the most recent role: "user" message, skips command invocations (lines starting with /) and assistant replies, and prints it:

import json
import sys
import os

def get_last_user_prompt(transcript_path):
    """Extract the last user prompt from the transcript file."""
    try:
        if not os.path.exists(transcript_path):
            return "No transcript found"
        with open(transcript_path, "r") as f:
            content = f.read().strip()
        if not content:
            return "Empty transcript"
        for line in reversed(content.split("\n")):
            try:
                entry = json.loads(line)
                if entry.get("type") == "message" and entry.get("role") == "user":
                    message_content = entry.get("message", "")
                    if message_content.startswith("/"):   # skip slash commands
                        continue
                    return message_content
            except Exception:
                continue
        return "No user prompt found"
    except Exception as e:
        return f"Error reading transcript: {e}"

The three moves the book names are worth memorizing because they generalize to any status-line feature: (1) read structured runtime input from stdin; (2) pull the field you need (transcript_path) out of it; (3) do your own work (open the transcript, filter, format) and print the result to stdout. The status line is, in the book's words, proof that "Claude Code is extensible beyond output formatting" — it lets executable logic shape the development environment itself.

Analogy — the car dashboard A status line is the dashboard strip: speed, fuel, gear, always in view while you drive. The car (Claude Code) constantly feeds raw telemetry through a wire (the JSON on stdin); a small module you install (your script) decides which gauges to light up and how to paint them, then sends the rendered readout to the glass (stdout). Want a different gauge — cost, context %, the last thing you typed? Rewire the module. Nothing about the engine changes; you've just chosen what the driver sees.

6. A team of specialized instances — and an honest look at the idea

The chapter ends with a vision. Because an output style is a per-session setting, you can open several Claude Code instances at once — separate terminals on the same repo — and give each a different style and role. The book paints it as a small start-up team: a frontend-engineer instance using terse bullets, a backend-engineer instance answering in an OpenAPI spec format, a devops instance in YAML, a security-review instance in a careful explanatory voice. Switching terminals "becomes equivalent to switching between specialized team members," and — neatly tying the chapter together — the status line is what tells you which instance you're looking at, since the interface doesn't otherwise advertise the active style. The book's thesis lands here: "Claude Code is not a single fixed interface, but a configurable system that can be shaped into task-specific agents."

That's a genuinely useful mental model, and the mechanics are real: output styles are per-session, so nothing stops you from running role-flavored instances side by side (Chapter 6 already had you running parallel terminal instances; this just gives each one a voice). But it's worth being precise about what's documented practice versus what's the book's framing, because the gap matters when you build for real:

• "One instance per output style" is the book's metaphor, not a documented architecture. The official guidance on running work in parallel ("Run multiple Claude sessions") never proposes coordinating a team by output style. Output styles change presentation; they don't give instances a shared task list or let them talk to each other.
• For genuinely role-specialized, parallel work, the documented tools are the ones from Chapter 7. Subagents are the stable, lightweight way to hand a focused role (a security reviewer, a test writer) a scoped task in its own context. Agent teams are the heavier, coordinated option where teammates share a task list and message each other — but they're experimental and disabled by default, gated behind the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS setting, with known limitations. Reach for those when you need real coordination; reach for parallel styled instances when you just want a few differently-voiced sessions you switch between yourself.

So take the book's "team of specialized agents" as an inspiring direction and a true statement about how configurable Claude Code is — while remembering that the production-grade way to get a coordinated team is subagents (today) or agent teams (experimental), not a row of terminals distinguished only by their output style.

Analogy — the open-plan office with labeled desks Seating a frontend dev, a backend dev, and a DevOps engineer at separate desks — each with their own working style, a nameplate (the status line) telling you whose desk you're at — is a real and useful way to organize. But a functioning firm doesn't coordinate purely by desk decor: it has a manager who routes work and a way for people to talk to each other. The labeled desks are your styled instances; the manager and the inter-desk phone are subagents and agent teams. Use the desks for "let me switch hats"; bring in the manager when the work genuinely needs a coordinated crew.

The whole chapter in one image — you're at the mixing board

Analogy — pedagogical summary, drawing on all six sections

Stop thinking of yourself as a listener tuning in to whatever the station plays. You're the producer at the mixing board.

You choose the format. Default, Explanatory, Learning, Proactive — or a card you printed yourself (output styles). And you decide, with one switch, whether the engineer's training stays in the booth or gets swapped out for a writer's (keep-coding-instructions).

You wire the channels. Route the signal into a structured shape so the form itself carries the meaning (YAML), or wire in a standing action so every take is automatically bounced to disk and played back (embedded HTML workflow).

You light the VU meters. The status line is your row of gauges — model, context %, cost, the last thing you said — fed live down a cable (JSON on stdin) and painted however you like (stdout + ANSI), always glowing at the bottom of the board.

You staff the booths. Several instances, each with its own voice and role, a nameplate on each — useful for switching hats, and a true sign that Claude Code is a configurable studio, not a sealed appliance. Just remember: a coordinated crew (subagents, agent teams) is a different rig than a few booths you walk between. Either way, the console is yours. That's the whole chapter: you design the communication protocol; Claude runs it.

Activity — Audit and design your own output style

Ten minutes, individual, no setup required. You'll decide where output styles fit in your work and sketch one — sharpening the judgment the practical exercise then exercises live.

1. Spot the repeated re-prompt. Think back over your last few Claude sessions. What did you keep asking for — "be concise," "just the diff," "explain it like I'm new," "answer in JSON"? That recurring instruction is a candidate for an output style. Write it down.
2. Pick the layer. Is what you want really an output style (a role/tone/format you want every turn), or is it project context (→ CLAUDE.md), a one-off (→ --append-system-prompt), or a scoped specialist (→ a subagent)? Justify your choice using the §2 table. Getting this right is half the skill.
3. Draft the frontmatter. Write a description and, deliberately, decide keep-coding-instructions: is Claude still doing software engineering in this style (→ true) or acting as something else entirely (→ omit it / false)? State why.
4. Draft three body rules. Write the three instructions that most define the style's voice or format (e.g., "respond only in valid YAML," "lead with a one-line verdict," "no preamble"). If your style should ask Claude to do something each turn (write a file, run a check), add that as a ## Workflow rule too — remembering it's an instruction Claude usually follows, not a guaranteed action (for that, you'd use a hook).
5. Decide scope. User (~/.claude/output-styles/) or project (.claude/output-styles/)? Would your team benefit from this exact format being versioned in the repo?

Keep the result — steps 3–4 are literally a style file, and you'll create something very close to it next.

Practical exercise — Reshape the interface: two output styles and a live status line

~35–45 minutes. Hands-on. No web framework, no npm, no accounts — just Claude Code, a tiny throwaway folder, and (for the status line) Python 3, which you almost certainly already have. You'll select a built-in style, write two custom styles, prove what keep-coding-instructions does, then build a status line that shows the active style live.

Everything happens in a throwaway sandbox — nothing here touches the training repo, and the status line is configured at project scope so it's fully self-contained and easy to undo.

Setup (3 min). Create a sandbox with one small file to talk about:

mkdir -p ~/cct-ch8-lab && cd ~/cct-ch8-lab
git init -q
cat > greet.py <<'PY'
def greet(name):
    return "Hello, " + name        # no input validation; no type hint
PY
git add . && git commit -q -m "init output-styles sandbox"

Part 1 — meet the built-in styles (5 min). Start claude in the sandbox, then open the config menu and choose Output style:

/config

Switch to Explanatory (or Learning). The output style is read once at session start, so the change takes effect after you run /clear (or start a new session) — do that now, then ask: What does greet.py do and how would you harden it? Notice the extra "Insights" / teaching voice versus the Default style.

Expected outcome: after the /clear, the same question produces a noticeably different presentation. (If you ask without clearing first, you'll still get the old style — that's the "read once at session start" rule, not a bug.) (Note: the book uses a standalone /output-style command here — it was removed in v2.1.91, so use /config. If your build still has /output-style, you're on an old version.)

Part 2 — write a custom style (10 min). Create a project-scoped style by hand:

mkdir -p .claude/output-styles
cat > .claude/output-styles/minimal-bullets.md <<'MD'
---
description: Concise bullet-point responses with direct communication
---
# Communication Style
- Use bullet points for all responses
- Be direct and to the point
- Use nested bullets for hierarchy
- Skip preamble and transitions

# Tone
- Professional and concise
- No hedging or qualifications
MD

Run /config → Output style and pick minimal-bullets. Because the style is read once at session start, run /clear (or start a new session) so it takes effect, then re-ask the greet.py question.

Expected outcome: after the /clear, the answer is now terse nested bullets, no filler — your file is shaping every response.

Part 3 — prove what keep-coding-instructions does (7 min). This is the field the book omits, so feel it directly. Add a second style without the flag, and ask it to actually change code:

cat > .claude/output-styles/plain-tutor.md <<'MD'
---
description: Friendly plain-English explanations, no jargon
---
Explain everything in plain, friendly English. Assume the reader is new to programming.
Avoid jargon; define any term you must use.
MD

Select plain-tutor, then run /clear (or start a new session) so it takes effect, and ask: Add input validation to greet.py. Now edit the file to add keep-coding-instructions: true to the frontmatter, start a fresh session (or /clear), reselect it, and ask the same thing.

Expected outcome: with the flag absent (default false), the style stripped Claude Code's software-engineering instructions — it leans explanatory and may not scope/verify the edit the way you'd expect. With keep-coding-instructions: true, you get the friendly voice and the disciplined coding behavior. That difference is the whole point of the flag.

Part 4 — a live status line (12 min). Build it manually so it stays self-contained in the sandbox. Drop in this stdlib-only script:

cat > .claude/statusline.py <<'PY'
import json, sys
data = json.load(sys.stdin)
style = data.get("output_style", {}).get("name", "default")        # current schema: output_style.name
model = data.get("model", {}).get("display_name", "?")
pct   = int(data.get("context_window", {}).get("used_percentage", 0) or 0)
print(f"\033[1;32m{model}\033[0m · {pct}% · style: {style}")        # bold-green model, then context % and style
PY

Then add a statusLine block to the project settings file, .claude/settings.json (a supported manual configuration path):

{
  "statusLine": { "type": "command", "command": "python3 .claude/statusline.py" }
}

Start a fresh session in the sandbox — a status bar appears at the bottom showing the model, context %, and the active style.

Faster alternative — let Claude write it. Run /statusline with a natural-language description and Claude Code generates a script in ~/.claude/ and updates your settings automatically:

/statusline show the active output style, the model name, and the context percentage

Note this writes to your global ~/.claude/ config (there is no project-settings picker), so it touches configuration outside the sandbox — the manual path above is what keeps this lab self-contained and easy to undo.

Now confirm the style segment is live: switch the output style via /config, then run /clear (or start a new session) so the change takes effect. The status line reports the active style (output_style.name), so after the clear its style segment shows the new style.

Expected outcome: a persistent bar showing the model, context %, and the active style in green; after switching a style and clearing, the style segment reflects the new style. You've closed the loop: a script you control, fed live session JSON, painting the interface. (Windows: use python instead of python3, and forward slashes in the path.)

Success checklist

• [ ] You switched to a built-in style via /config (not the removed /output-style), ran /clear (or started a new session) so it took effect, and saw the same question answered differently.
• [ ] You wrote .claude/output-styles/minimal-bullets.md, made it the active style, and (after /clear/new session) responses became terse bullets.
• [ ] You demonstrated keep-coding-instructions: the default (false) dropped the coding behavior; true kept the voice and the engineering discipline.
• [ ] A status line is live at the bottom of the terminal, built from a script that reads session JSON on stdin and prints to stdout.
• [ ] After switching a style (and /clear/new session), the status line's style segment reflects the new style.

Common pitfalls - Reaching for the old command. /output-style was removed in v2.1.91. Use /config → Output style, or set outputStyle in a settings file. - Forgetting the style is read at session start. A new or edited style takes effect after /clear or a fresh session — not mid-turn. - Omitting keep-coding-instructions when you still want coding. A custom style defaults to dropping the software-engineering instructions. If you only meant to change the voice, set it to true. - Reading the wrong status-line field. The active style is output_style.name (nested), not a bare output_style string. The book's one-liner is from an older schema. - Editing global config by accident. The book points the status line at ~/.claude/settings.json (global). Keep the lab self-contained by using the project .claude/settings.json instead, and delete the statusLine block to undo. - Using an output style for project facts. Conventions, build commands, and codebase context belong in CLAUDE.md (a user message after the system prompt), not in a style (which is the system prompt).

Knowledge check — try the quiz

Once you've read the lesson and worked the lab, take the chapter quiz from the navigation bar. Six questions: five grounded in the book chapter, one synthesis question that ties output styles to the other behavior-shaping tools (CLAUDE.md, --append-system-prompt, subagents, Skills) and to honest multi-instance practice. Passing score is 5/6 — retake it until you're confident.

Further reading & enrichment sources

• Anthropic docs — "Output styles" (https://code.claude.com/docs/en/output-styles). The canonical reference: the four built-in styles (Default, Proactive, Explanatory, Learning), selecting via /config (the standalone /output-style command was deprecated in v2.1.73 and removed in v2.1.91), the frontmatter fields (name, description, keep-coding-instructions, force-for-plugin), the three storage locations, the "How output styles work" mechanics (instructions appended to the system prompt; software-engineering instructions dropped unless keep-coding-instructions: true), and the "Comparisons to related features" table.
• Anthropic docs — "Customize your status line" (https://code.claude.com/docs/en/statusline). The /statusline command and the statusLine settings block; the full JSON schema piped on stdin (model, output_style.name, context_window, cost, workspace, transcript_path, and conditional fields); multi-line output, ANSI color and OSC 8 hyperlinks, refresh cadence, and the workspace-trust requirement.
• Anthropic docs — "Settings" (https://code.claude.com/docs/en/settings). Where outputStyle and statusLine live and how settings precedence resolves them — highest to lowest: managed → command-line arguments → local project (.claude/settings.local.json) → shared project (.claude/settings.json) → user (~/.claude/settings.json) (permission rules are the exception — they merge across scopes rather than override).
• Anthropic docs — "Memory / CLAUDE.md" (https://code.claude.com/docs/en/memory). Why CLAUDE.md is project context added after the system prompt, not a system-prompt modification — the key contrast with output styles.
• Anthropic docs — CLI reference (https://code.claude.com/docs/en/cli-reference). --append-system-prompt (append to the system prompt for one invocation) and --system-prompt / --system-prompt-file (replace it entirely) — the headless cousins of an output style.
• Anthropic docs — "How Claude Code uses prompt caching" (https://code.claude.com/docs/en/prompt-caching). Why an output-style change is read once at session start and what it does to the cache.
• Anthropic docs — "Best practices: run multiple Claude sessions" (https://code.claude.com/docs/en/best-practices) plus "Subagents" (https://code.claude.com/docs/en/sub-agents) and "Agent teams" (https://code.claude.com/docs/en/agent-teams). The documented ways to run role-specialized work in parallel — the honest counterpart to the book's "team of specialized agents" framing; agent teams remain experimental and disabled by default.