Output Style Engineering

Output Style Engineering

Output styles replace Claude Code's system prompt, transforming the main agent's personality while retaining all tools and capabilities.

<prerequisite> Output styles are system prompts. Before creating or improving an output style, invoke prompt-engineering to load instruction design techniques.

Skill(ai-helpers:prompt-engineering)

Skip only for trivial edits (typos, formatting).

</prerequisite>

Route to Reference

• File format, frontmatter, storage, activation — [${CLAUDE_SKILL_DIR}/references/spec.md] Frontmatter field

details, replace-vs-preserve semantics, storage paths, activation methods, scope priority, session timing and reminders, token impact, built-in styles catalog, feature comparison table, Agent SDK system prompt approaches (4 methods)

• Creating a style from scratch — [${CLAUDE_SKILL_DIR}/references/creation.md] Replace-not-augment principle,

creation methods (/output-style:new, manual, SDK), creation workflow, style pattern templates (direct professional, domain specialist with non-coding use cases, interaction mode, learning/educational with voice-first design), token impact, common failure modes

• Evaluating style quality — [${CLAUDE_SKILL_DIR}/references/evaluation.md] Scope appropriateness pre-check,

per-dimension scoring rubrics (1-10), weighted scoring formula, testing protocol (4 core + 3 persistence + 1 domain), deployment readiness go/no-go, red flags

• Style not working, needs refinement — [${CLAUDE_SKILL_DIR}/references/iteration.md] Mechanism mismatch

diagnosis, diagnostic symptom→fix mapping with community evidence, refinement techniques (repetition, contrast, consolidation), escalation patterns, rewrite vs iterate criteria

• Real-world examples with analysis — [${CLAUDE_SKILL_DIR}/references/examples.md] 5 complete styles with

dimensional scoring and improvement notes — includes non-coding examples (SaaS analyst, content strategist)

What Output Styles Change

Output styles replace the default system prompt — they don't augment it.

Replaced:

• System prompt personality and domain assumptions
• Task prioritization and interaction patterns
• Response formatting and tone
• Coding instructions (unless keep-coding-instructions: true)

Preserved (regardless of style):

• All tools (Read, Write, Bash, Grep, etc.)
• CLAUDE.md project context system
• Subagent delegation and skills
• MCP integrations
• Environment context (working directory, git status)

Key distinction from other features:

• Output style — replaces the default system prompt; file on disk
• CLAUDE.md — added as user message after the system prompt; does not modify it
• `--append-system-prompt` — appends to system prompt without removing anything
• Custom `systemPrompt` (SDK) — full replacement in code; use for specialized agents

Output styles are the ONLY file-based way to change the main agent's core personality.

keep-coding-instructions

Controls whether Claude retains its software engineering guidance.

• false (default) — removes coding workflow instructions. Use for non-coding domains (research, content, UX design)
• true — preserves safety, code quality, and test verification guidance. Use when the style is a personality overlay

for coding work (different tone, domain-specific conventions)

Rule: if the style is for someone who writes code, set true. If the style replaces coding with another domain, set false.

File Structure

~/.claude/output-styles/           # User-level (all projects)
    my-style.md
.claude/output-styles/             # Project-level (this repo)
    team-style.md

Filename becomes the style identifier (without .md). Activate with /output-style style-name or via settings. Project-level styles shadow user-level styles with the same name.

Full format details, frontmatter fields, activation methods, Agent SDK integration: see [${CLAUDE_SKILL_DIR}/references/spec.md].

Writing Style Instructions

Output styles are system prompts. Five components determine quality:

1. Define Persona Clearly

The persona is the highest-leverage element. A vague persona produces inconsistent behavior; a clear one anchors every response.

Vague (fails): "Be helpful and professional."

Clear (works): "You are a senior technical architect who communicates directly and values precision over politeness."

The test: could two people reading this persona imagine the same character? If not, add specificity.

2. Specify Concrete Behaviors

Abstract instructions ("communicate clearly") get ignored. Concrete behaviors are testable and unambiguous.

## Communication Rules

- Acknowledge valid points with "Correct" or "Valid point"
- State disagreements as "I see it differently because..."
- Never use "I'd be happy to" or "Great question"
- Open with the answer, not pleasantries

Each rule should be verifiable: you can check whether a response complies.

3. Include Tone Examples

Examples are the most reliable way to communicate expected behavior. Show contrast between default Claude and the target style:

## Tone Examples

User: "Can you help me with this code?"

Default Claude (avoid):
"Of course! I'd be happy to help you with your code.
Let me take a look at what you've got..."

This Style (use):
"Looking at the code now. Three issues:
1. [specific issue]..."

Include at least one contrast example. Cover interaction types most likely to trigger default behavior.

4. Specify Output Format

Without format guidance, response structure varies. Provide templates for common response types.

5. Add Consistency Safeguards

Styles drift mid-conversation. Explicit persistence language prevents reversion:

## Consistency

Maintain this style throughout the entire conversation. Do not revert
to default patterns even if:
- The topic changes
- The user asks follow-up questions
- Multiple turns have passed
- The task becomes complex or frustrating

If uncertain, default to MORE adherence to this style, not less.

Place Critical Rules at End

Instructions near the end of the prompt are followed more reliably. Place the rules you cannot afford to have ignored last.

Establish Priority Hierarchy

When a style has rules that could conflict, add an explicit priority order.

Common Style Patterns

• Direct Professional — remove sycophancy, focus on substance. Set keep-coding-instructions: true.
• Domain Specialist — replace coding expertise with domain knowledge. Set keep-coding-instructions: false.
• Interaction Mode — change engagement style (voice-first, quiz, pair programming). Set keep-coding-instructions

based on whether the mode involves coding.

• Learning/Educational — collaborative mentoring with guided exercises. Set keep-coding-instructions: true.

Full templates for each pattern: see [${CLAUDE_SKILL_DIR}/references/creation.md]. Scored examples: see [${CLAUDE_SKILL_DIR}/references/examples.md].

Evaluating Style Quality

First: verify scope appropriateness. Before scoring dimensions, confirm the style needs to be an output style — not CLAUDE.md, not --append-system-prompt, not a skill. If the style body could work identically as CLAUDE.md content, it should not be a style.

Six dimensions, three weighted 2x (high-leverage):

• Persona Clarity (2x) — can you describe the persona in one sentence? Would two readers imagine the same character?
• Behavioral Specificity (2x) — is every rule verifiable? Are there concrete do/don't examples?
• Example Quality (2x) — do examples show contrast (default vs this style)? Do they cover key interaction types?
• Output Format (1x) — would Claude know exactly how to structure responses?
• Consistency Safeguards (1x) — are default behaviors explicitly forbidden with alternatives?
• Scope (1x) — is keep-coding-instructions set right? Does the style know what it's for?

Must have: persona defined, core behaviors listed, at least one contrast example, output format specified.

Detailed per-dimension scoring rubrics and testing protocol: see [${CLAUDE_SKILL_DIR}/references/evaluation.md].

Iterating on Styles

Iteration Cycle

Observe → Diagnose → Hypothesize → Modify (ONE change) → Test → Repeat

Make ONE targeted change per iteration. Multiple changes make debugging impossible.

First: Check for Mechanism Mismatch

Before iterating on the style, verify the right mechanism is in use. If instructions are in CLAUDE.md or a hook instead of an output style, they lose influence over multiple turns — iteration cannot fix a mechanism mismatch.

Common Issues and Fixes

• Reverts to sycophantic tone — weak persona, no anti-patterns. Add explicit "Never use..." list with replacements.
• Ignores format — format buried in text. Move to dedicated section, add response template.
• Inconsistent between turns — no persistence language. Add "maintain throughout" with scenario list.
• Works initially, drifts later — no reinforcement. Reinforce critical rules across multiple sections.
• Too verbose — no length constraints. Add explicit length limits.
• Wrong tone in edge cases — missing example coverage. Add contrast example for the failing scenario.
• Contradictory behavior — conflicting instructions. Add priority hierarchy.
• SE assumptions leak — keep-coding-instructions not set to false for non-coding style.

Detailed fix patterns with before/after: see [${CLAUDE_SKILL_DIR}/references/iteration.md].

Built-in Styles

• Default — standard Claude Code system prompt. Software engineering focus. Active when no style selected.
• Explanatory — inserts educational "Insight" blocks alongside task completion. Explains implementation choices.
• Learning — collaborative learn-by-doing mode. Adds TODO(human) markers for hands-on practice.

Quick Start

mkdir -p ~/.claude/output-styles

Create style-name.md:

---
name: Style Display Name
description: Brief description for the menu
keep-coding-instructions: true
---

# Style Name

[Who Claude is in this style]

## Core Behaviors
- [Explicit rules]

## Examples
[Input/output pairs showing tone contrast]

## Consistency
Maintain this style throughout the entire conversation.

## Critical Rules
[Most important rules — placement at end improves compliance]

Activate: /output-style style-name

Quick Checks

Before deploying:

• [ ] Persona defined clearly (who is Claude in this style?)
• [ ] Core behaviors are concrete and verifiable
• [ ] At least one contrast example (default vs this style)
• [ ] Output format specified
• [ ] Consistency safeguards included
• [ ] Priority hierarchy established (if rules could conflict)
• [ ] Critical rules placed at end
• [ ] keep-coding-instructions set appropriately
• [ ] Tested with varied prompts (simple, complex, edge cases, emotional)

Related Skills

• prompt-engineering — load first for instruction design techniques (output styles are system prompts)
• skill-engineering — skills and output styles complement each other; skills extend, styles replace
• subagent-engineering — subagents have their own system prompts; output styles govern the main agent only
• claude-code-sdk — consult for Agent SDK system prompt modification approaches

Creating Output Styles

Why Output Styles Exist

Output styles replace Claude Code's system prompt — they don't augment it.

You cannot remove default behaviors by adding instructions on top of them. Users have proven this:

• CLAUDE.md adds project context but cannot override the coding personality
• `--append-system-prompt` appends without substituting — default behaviors remain
• Hooks lose influence after several conversation rounds
• Users report "Claude's ingrained celebratory defaults seemingly overrode the style guidance" when using CLAUDE.md

alone

Output styles are the only file-based mechanism that replaces the core personality. Everything else augments it.

File Format

---
name: My Style Name
description: One sentence shown in the /config picker
keep-coding-instructions: false
---

# Role and Identity

[Who Claude is in this style]

## Tone and Communication

[How Claude speaks, what it avoids, phrasing patterns]

## Response Structure

[Format rules, section ordering, length guidelines]

## Specific Behaviors

[Edge cases, what to do and not do]

Frontmatter Fields

• `name` — display name; defaults to filename (without .md) if omitted
• `description` — shown in /config picker; make it scannable
• `keep-coding-instructions` — true preserves the default coding system prompt alongside your style instructions;

false (default) replaces it entirely

File Locations

• User-level (all projects) — ~/.claude/output-styles/
• Project-level (current project) — .claude/output-styles/
• Plugin-shipped — output-styles/ directory inside the plugin

Creation Methods

/output-style:new (recommended start)

Run in Claude Code:

/output-style:new [name] [verbose description of desired behavior]

Claude generates a Markdown file in ~/.claude/output-styles/. Treat as a first draft — review and tighten before use.

Manual file creation

Create a .md file directly in one of the storage locations above. Full control from the start, but requires understanding the file format and writing effective style instructions.

SDK programmatic creation

For Agent SDK integrations, write the style file to ~/.claude/output-styles/ or .claude/output-styles/ programmatically, then reference it via settingSources in SDK options. Details in [${CLAUDE_SKILL_DIR}/references/spec.md] under Agent SDK Integration.

Creation Workflow

Step 1: Clarify purpose

Answer before writing:

• What is the user _not_ getting from the default style?
• What role does this style play? (teacher, critic, domain specialist, persona)
• Does the user need coding instructions preserved?
• Is this a coding use case or a non-coding domain (business analysis, content strategy, research)?

Step 2: Choose a pattern

Select the pattern that matches the use case. Each pattern has different structural requirements — see Style Patterns below.

Step 3: Draft

Use /output-style:new for a starting point or write manually. Either way, apply the pattern's structural requirements.

Step 4: Activate and test

/output-style [name]

Or set directly in .claude/settings.local.json:

{ "outputStyle": "MyStyleName" }

The style is applied once at session start — it cannot change mid-session. Start a new session to pick up changes.

Step 5: Iterate

Test with representative prompts covering normal use and edge cases. Adjust instructions where behavior diverges from intent. Keep the file under ~300 lines; move detailed rules into referenced behaviors. Make one change per iteration — multiple changes make debugging impossible.

Style Patterns

Direct Professional

Purpose: Strip sycophancy and filler, focus on precision.

`keep-coding-instructions`: true — this is a tone overlay, not a domain switch.

Key instructions:

• Never use openers like "Great question!", "Certainly!", "I'd be happy to..."
• State conclusions before reasoning
• No trailing summaries of work just done
• Professional tone without warmth padding
• No hedging phrases ("it's worth noting that...", "might potentially")

Reversion risk: High. Default personality traits are deeply embedded — Claude acknowledges the instructions but reverts to celebratory defaults mid-session. Mitigate with multiple consistency anchors distributed throughout the style, not just one section at the end. Include explicit anti-reversion language: "If you notice yourself softening tone, correct immediately."

Domain Specialist

Purpose: Claude acts as a named expert role, replacing the software engineering identity with domain knowledge.

`keep-coding-instructions`: false — the style replaces coding expertise with domain expertise.

Key instructions:

• Define the expert identity and knowledge scope
• Specify what the role _does not_ do (scope boundaries)
• Set the vocabulary register (jargon level, abbreviations allowed)
• Define how the role handles requests outside its domain
• Script the boundary response: "That's outside my [role]. Here's the direction: [guidance]."

Non-coding use cases — the most common reason users create domain specialist styles:

• Business analysis — upload CSV churn data, get consultant-level insights on MRR, churn rate, LTV, CAC without

software engineering assumptions

• Content strategy — YouTube analytics, brand voice consistency, audience engagement patterns
• Research — academic paper processing, citation management, literature review
• Design — SVG modification, design system maintenance, visual hierarchy feedback
• DevOps — YAML configurations, structured data generation, infrastructure documentation

For all non-coding domain specialists, set keep-coding-instructions: false to strip the software engineering assumptions that would otherwise contaminate domain-specific advice.

Interaction Mode

Purpose: Change how Claude and user _collaborate_, not just how Claude speaks.

`keep-coding-instructions`: Based on whether the mode involves coding.

Examples:

• Pair programmer — Claude assigns tasks to the user with TODO(human), gives guidance but doesn't implement
• Socratic tutor — guides via questions rather than answers, waits for user response before continuing
• Code reviewer — evaluates submitted code rather than writing it, structures feedback by severity

Required structure for interaction modes:

• Turn structure — who acts, who responds, in what order
• Wait signals — how Claude signals it's waiting for user input
• Skip handling — what Claude does if user skips a step or asks to bypass the exercise
• Scope of action — what Claude handles vs. what the user handles

Learning / Educational

Purpose: Teach concepts through engagement, not passive explanation.

`keep-coding-instructions`: true if teaching coding concepts, false for non-coding education.

The built-in learning style uses TODO(human) markers for hands-on coding. Custom learning styles can go further:

• Voice-first / dictation design — all questions answerable by speaking (letter choices, true/false, verbal

explanation). The strongest design constraint: if the user can't answer by talking, the question is poorly designed.

• Question types — multiple choice, true/false, scenario-based, verbal explanation
• Adaptive pacing — one question at a time, progress checks every 5 questions, confusion handling
• Feedback format — correct/incorrect with explanation, next step. No superlative feedback words (perfect, amazing,

excellent).

Learning styles produce longer output tokens by design — this is intentional, not a problem to optimize away.

Token Impact

• `keep-coding-instructions: false` — reduces input tokens by removing the default coding prompt from the system

message

• `keep-coding-instructions: true` — adds both the default coding prompt AND your style instructions, increasing

input token count

• Prompt caching — after the first request in a session, the system prompt (including the output style) is cached,

reducing latency and cost for subsequent requests. Since the style is fixed per session, the cache hit rate is high.

• Explanatory / verbose styles — produce longer output tokens by design. Learning and educational styles are the

highest token consumers. Factor this into cost estimates.

Comparison: Output Styles vs. Related Features

• `CLAUDE.md` — added as a user message after the system prompt; project/user context, not persona
• `--append-system-prompt` — appends to the system prompt; preserves default coding behavior
• Output styles — replace the system prompt; fullest control over role and behavior
• Subagents — separate invocations with their own tools/model; output styles affect the main loop only
• Skills — invoked on-demand for specific workflows; output styles are always-on once selected

Detailed comparison table with persistence and scope dimensions: see [${CLAUDE_SKILL_DIR}/references/spec.md] under Comparison.

Common Failure Modes

Style reverts mid-session — Default personality traits are deeply embedded. A single consistency reminder at the end is insufficient for long sessions. Fix: distribute anti-reversion language throughout the style — at least two anchors in different sections. Include explicit scenario lists ("even if the topic changes, even if multiple turns have passed"). Users who moved style instructions from CLAUDE.md to an output style specifically because of this problem report that replacement is more effective than augmentation, but still requires reinforcement.

Coding capability lost — keep-coding-instructions: false (the default) removes all coding guidance. Users who create a tone-only style (e.g., "be more direct") accidentally lose coding capability. Fix: set keep-coding-instructions: true for any style that should augment coding behavior rather than replace it.

Instructions too vague — "Be professional" is underspecified — two readers would imagine different behaviors. Fix: list concrete behaviors ("never use emoji", "always give verdict before rationale", "no hedging phrases") rather than adjectives. Every instruction should be verifiable: you can check whether a response complies.

Style ignored in tool output — Style controls Claude's prose, not the output of bash commands, file reads, or MCP tool results. Don't expect the style to reformat tool results — it governs how Claude frames and presents information, not the raw output of tools.

Output Style Evaluation

Framework for assessing output style quality before deployment.

Scope Appropriateness

Before scoring dimensions, verify the style needs to exist as an output style. Output styles replace Claude's system prompt — that power comes with cost (losing default behaviors, requiring full persona definition). The wrong mechanism wastes effort and produces worse results.

Use an output style when:

• You need to change Claude's core personality or communication patterns
• You need to remove default software engineering assumptions (non-coding domains)
• Behavioral changes must persist reliably across long conversations (10+ turns)
• CLAUDE.md instructions or --append-system-prompt have failed to override defaults

Use something else when:

• Project-wide standards without personality change — CLAUDE.md (always loaded, no prompt replacement)
• Domain knowledge or path-filtered rules — .claude/rules/ files
• User-triggered repeatable workflows — skills
• One-time behavioral instructions — --append-system-prompt

Scope red flag: If the style body could work identically as CLAUDE.md content — no persona definition, no default behavior overrides, just project rules — it should not be a style.

Evaluation Dimensions

Six dimensions, each scored 1-10. Three are weighted 2x (persona, behaviors, examples) because they directly drive compliance. The other three are supporting elements.

1. Persona Clarity (Weight: 2x)

Does the style define WHO Claude is?

• 1-3 — No persona, or vague ("be helpful"). Two readers would imagine different personas.
• 4-6 — Role defined but lacks specificity. "You are a senior engineer" without perspective, values, or constraints.
• 7-8 — Clear persona with role, domain expertise, and perspective. One-sentence summary is obvious.
• 9-10 — Rich persona with motivations, constraints, and values. Persona naturally implies behaviors without stating

them.

Checks:

• Can you describe the persona in one sentence?
• Would two people reading the style imagine the same persona?
• Does the persona imply the right behaviors naturally?

2. Behavioral Specificity (Weight: 2x)

Are behaviors concrete and testable?

• 1-3 — Abstract instructions ("be professional", "communicate clearly"). Cannot verify compliance.
• 4-6 — Mix of concrete and abstract. Some rules are testable, others are aspirational.
• 7-8 — Mostly concrete, actionable instructions. Each rule has a clear pass/fail condition.
• 9-10 — All behaviors are specific, testable, and unambiguous. Includes both positive rules and explicit

anti-patterns.

Checks:

• Could you write a pass/fail test for each rule?
• Are there concrete do/don't pairs?
• Do rules use specific language ("Never open with 'Great question!'") rather than vague directives ("Don't be

sycophantic")?

3. Example Quality (Weight: 2x)

Do examples demonstrate expected behavior effectively?

• 1-3 — No examples. Behavior expectations are ambiguous.
• 4-6 — Examples present but limited — only positive examples, or only one scenario type.
• 7-8 — Multiple examples covering key scenarios. Includes contrast pairs (good vs bad).
• 9-10 — Comprehensive examples with contrast pairs across different interaction types (simple request,

disagreement, complex task, emotional pressure).

Checks:

• Do examples show both correct and incorrect behavior (contrast pairs)?
• Do examples cover different interaction types, not just one?
• Would someone unfamiliar with the style learn the right tone from examples alone?

4. Output Format Clarity (Weight: 1x)

Is response structure explicitly defined?

• 1-3 — No format guidance. Response structure varies randomly.
• 4-6 — Some format hints but no templates or examples.
• 7-8 — Clear format with structure defined. Includes at least one response template.
• 9-10 — Explicit format with templates for different response types (simple answer, analysis, error case).

Checks:

• Would Claude know exactly how to structure any response type?
• Does format guidance scale across response complexity (one-liner vs detailed analysis)?

5. Consistency Safeguards (Weight: 1x)

Does the style prevent reversion to default behaviors?

• 1-3 — No safeguards. Will revert to defaults within a few turns.
• 4-6 — Some "avoid" instructions but no reinforcement strategy. Defaults will creep back mid-conversation.
• 7-8 — Clear anti-patterns with alternatives. Includes explicit persistence language ("maintain throughout entire

conversation").

• 9-10 — Comprehensive safeguards: critical rules reinforced in multiple sections (persona, behaviors, examples,

critical rules). Explicit persistence clause with enumerated reversion triggers.

Checks:

• Are common default behaviors explicitly forbidden with replacements?
• Does the style include persistence language for long conversations?
• Are critical rules reinforced through repetition across sections?

6. Appropriate Scope (Weight: 1x)

Is the style focused and correctly bounded?

• 1-3 — Tries to cover everything, or scope is unclear. keep-coding-instructions not considered.
• 4-6 — Reasonable scope but some ambiguity about what the style is and isn't for.
• 7-8 — Well-defined scope. keep-coding-instructions set correctly. Style knows its boundaries.
• 9-10 — Perfect scope with clear boundaries. Explicitly states what's out of scope. Handles edge cases (what to do

when asked something outside the style's domain).

Checks:

• Is keep-coding-instructions set appropriately for the domain?
• Does the style know what it's for and what it's not for?
• Would the style still work if the conversation topic drifts?

Scoring

Calculate weighted score:

Score = (Persona x 2 + Behaviors x 2 + Examples x 2 +
         Format x 1 + Safeguards x 1 + Scope x 1) / 9

• 8-10 — Deploy. Style is robust and will hold across sessions.
• 6-7 — Minor refinements needed. Core is sound, edges need polish.
• 4-5 — Significant improvement needed. Multiple dimensions are weak.
• 1-3 — Major rewrite. Fundamental issues with persona, behaviors, or scope.

Testing Protocol

After scoring dimensions, validate with real usage. Each test targets a specific failure mode observed in production.

Core Tests

1. First impression — Prompt: "Hello, can you help me?" — Does the opener match the style? Any sycophantic language? This catches weak persona definition immediately. 2. Simple task — Prompt: "Summarize [topic]" — Format matches specification? Tone consistent? Tests basic compliance. 3. Disagreement — Prompt: "I think [obviously wrong thing] is correct" — Does Claude push back appropriately while maintaining style? Tests persona strength under social pressure. 4. Complex request — Prompt: "[Multi-step problem]" — Style holds under complexity? No reversion to defaults? Tests format and tone at scale.

Persistence Tests

5. Emotional pressure — Prompt: "Please help me, I'm really stuck and frustrated!" — Maintains style while showing appropriate empathy? Sycophantic defaults are strongest here. 6. Late-conversation drift — After 10+ turns of conversation, repeat tests 1-3. Style should hold identically. Styles that rely on session-start hooks would degrade here; proper output styles should not. 7. Topic shift — Mid-conversation, change the subject entirely. Does the style hold when context shifts?

Non-Coding Domain Test (when applicable)

8. SE assumption leak — For styles with keep-coding-instructions: false, prompt: "Help me with [non-coding task]" — Any software engineering assumptions leaking? References to code, files, or technical tools that don't belong?

Deployment Readiness

Go/no-go criteria for shipping a style:

Go (all must be true):

• Weighted score >= 6
• All core tests (1-4) pass
• Persistence test (6) shows no drift
• No red flags present (see below)
• keep-coding-instructions explicitly set (not relying on default)

No-go (any one blocks deployment):

• Weighted score < 4 on any 2x dimension (persona, behaviors, examples)
• Style reverts to defaults within 5 turns
• Any red flag present
• Style works identically without being a style (should be CLAUDE.md instead)

Red Flags

Immediate issues requiring attention before deployment:

• No persona definition — inconsistent behavior across turns, nothing to anchor the style
• Only positive instructions — will revert to defaults without explicit anti-patterns and replacements
• No examples — ambiguous expectations, compliance is unpredictable
• Contradictory rules without priority hierarchy — Claude picks arbitrarily between conflicting instructions
• Over 1000 lines — instructions will be progressively ignored as context fills
• No format guidance — inconsistent output structure across responses
• Style that doesn't leverage replacement — body could work as CLAUDE.md content, wasting the style mechanism
• No consistency safeguards — style will drift within a few turns, especially under emotional pressure
• Missing `keep-coding-instructions` decision — relying on default (false) without considering whether the style

needs coding capabilities

Output Style Examples

Five annotated examples covering the main style patterns. Each entry includes the full style template, a dimensional score, and improvement notes.

1. Direct Professional

Purpose: Strip sycophancy, eliminate filler, enforce concise professional communication.

Pattern: Direct Professional — keep-coding-instructions: true

Template:

---
name: Direct Professional
description: Terse, professional responses without filler, openers, or trailing summaries
---

You are a professional technical collaborator. Respond with precision and brevity.

## Communication Rules

- Never open with "Great question!", "Certainly!", "Absolutely!", "I'd be happy to...", or similar filler
- Never use "It's worth noting that...", "This is a great start, but...", or euphemistic hedging
- State conclusions first, reasoning after only if non-obvious
- No trailing summaries of work just completed
- No emoji unless explicitly requested
- Use plain declarative sentences; avoid hedging ("might", "could potentially")

## Response Structure

- Verdict or answer first
- Supporting detail in descending importance
- Stop when the point is made

## Consistency

Maintain this style throughout the entire session. Do not revert to default patterns even if:

- The topic changes
- The user asks follow-up questions
- Multiple turns have passed
- The task becomes complex or frustrating

If you notice yourself softening tone or adding filler, correct immediately.

If uncertain, default to MORE adherence to this style, not less.

Dimensional score:

• Clarity of role — high: unambiguous behavior contract
• Specificity — high: lists exact phrases to avoid, including euphemistic hedging
• Completeness — medium: no guidance for tool outputs or multi-step tasks
• Reversion risk — medium-low: dual consistency anchors (section + mid-file self-correction rule)

Improvement notes: The phrase blocklist covers the most common sycophancy patterns. For further hardening, add a contrast example showing default Claude vs. this style for the same input — examples are the most reliable way to communicate tone. The style has no guidance for error reporting or delivering bad news, which is where tone tends to revert first.

2. Domain Specialist — SaaS Business Analyst

Purpose: Claude acts as a SaaS business analyst — evaluates churn data, identifies retention patterns, communicates in business language without software engineering assumptions. Demonstrates the non-coding domain specialist pattern.

Pattern: Domain Specialist — keep-coding-instructions: false

Template:

---
name: SaaS Analyst
description: SaaS business analyst specializing in churn analysis and retention strategy
keep-coding-instructions: false
---

You are a senior SaaS business analyst. When users provide data, you analyze it through a business lens — not a
software engineering lens.

## Identity and Scope

- You identify patterns in MRR, churn rate, LTV, CAC, and cohort behavior
- You segment customers by behavior patterns, not technical implementation
- You recommend retention strategies grounded in the data
- You communicate in business language — "revenue impact", "cohort analysis", "expansion revenue", not "database
  query" or "API endpoint"

## Response Structure

For data analysis:

1. Key metrics summary (what the numbers say)
2. Segment analysis (which customers, what patterns)
3. Risk identification (what's trending wrong)
4. Retention recommendations (actionable, prioritized by impact)
5. Questions for the user (what data would sharpen the analysis)

For strategic questions:

1. Direct answer
2. Supporting evidence from available data
3. Caveats and assumptions
4. Next steps

## Tone

Direct, evidence-based. Frame findings as business decisions, not technical problems. Use percentages, dollar
amounts, and time periods — not abstractions.

## Scope Boundaries

If asked to write code, build dashboards, or implement technical solutions, respond: "That's outside my analysis
role. Based on the data, here's what the implementation should optimize for: [business requirements]."

If asked about topics outside SaaS metrics, redirect: "I can best help with SaaS business analysis. For [topic],
you'd want a different perspective."

Dimensional score:

• Clarity of role — high: business analyst identity is specific and the non-engineering framing is explicit
• Specificity — high: structured analysis format with named metrics, vocabulary register defined
• Completeness — high: scope boundaries handle both code requests and off-topic requests
• Reversion risk — low: keep-coding-instructions: false strips engineering defaults; scope boundary scripts

reinforce the domain

Improvement notes: The style could benefit from a contrast example showing how a default Claude response to CSV data differs from this style's response — default Claude would likely suggest pandas code, while this style should produce business analysis. Consider adding guidance for when the user provides incomplete data — the "Questions for the user" step partially addresses this, but explicit handling of insufficient data would strengthen it.

3. Pair Programmer (Interaction Mode)

Purpose: Collaborative coding where Claude assigns tasks to the user rather than implementing everything itself. Based on the built-in learning style's TODO(human) pattern, extended for experienced developers.

Pattern: Interaction Mode — keep-coding-instructions: true

Template:

---
name: Pair Programmer
description: Assigns implementation tasks to the user with TODO(human) markers; reviews submitted code
keep-coding-instructions: true
---

You are the navigator in a pair programming session. The user is the driver — they write code, you guide.

## Turn Structure

1. Analyze what needs to be done
2. Identify the next unit of work suitable for the user to implement
3. Insert `TODO(human): [clear task description]` at the exact location
4. Provide guidance: intent, approach options, constraints — but not the implementation
5. Wait for the user to submit their code
6. Review the submission: confirm understanding first, then flag issues by severity

## Task Assignment Rules

- Assign one task at a time
- Tasks should be implementable in 10-30 lines
- Match task complexity to user's demonstrated skill level
- For scaffolding/boilerplate, implement it yourself and assign the logic

## Review Format

After user submits:

- Confirm what they got right (one sentence)
- Flag issues: [Blocker] / [Suggestion] / [Style]
- If correct: assign next task

## What You Do vs. What the User Does

You handle: project setup, imports, boilerplate, architecture decisions
User handles: business logic, algorithms, data transformations, tests

## Override

If the user asks you to just implement it, do so without comment — respect their choice to skip the exercise.

Dimensional score:

• Clarity of role — high: navigator/driver metaphor is precise
• Specificity — high: turn structure and review format are explicit
• Completeness — high: covers the what/who boundary clearly, plus override escape hatch
• Reversion risk — low: keep-coding-instructions: true plus explicit "wait for user" anchors

Improvement notes: The 10-30 line heuristic is an anchor but needs calibration per project type — infrastructure tasks might be 5 lines, UI components might be 50. Consider adding guidance for when the user submits code that works but uses a fundamentally different approach than what was guided — the review format doesn't distinguish between "wrong" and "different."

4. Interactive Documentation Learner

Purpose: Transforms documentation into a voice-first interactive learning session. Designed for dictation — all questions are answerable by speaking a letter or short phrase. No typing or code writing required.

Pattern: Learning / Educational — keep-coding-instructions: false

Template:

---
name: Interactive Doc Learner
description: Transform documentation into dictation-friendly verbal quizzes and guided discovery
keep-coding-instructions: false
---

You are a patient technical tutor. Your goal: help users understand documentation through verbal interaction.
Every interaction must be answerable by dictation — no typing or code writing required.

## Core Constraint

NEVER ask the user to write or type code. All responses must be speakable.

## Session Flow

When documentation is provided:

1. Analyze content and identify 3-5 core concepts
2. State the plan: "I'll guide you through [topic]. Just speak your answers."
3. Ask about familiarity: "Are you familiar with [prerequisite]? Say yes or no."
4. Proceed concept by concept — one question at a time

## Question Types

**Multiple choice** — lettered options (A, B, C, D), user speaks a letter
**True/False** — user says "true" or "false", you explain why
**Verbal explanation** — "In your own words, describe [concept]"
**Scenario** — "Imagine you need to [goal]. Talk me through your approach."

## Pacing

- One question per turn
- Confirm what you heard before evaluating ("You said B — correct?")
- After correct answer: brief explanation, then next question
- After wrong answer: correct answer + explanation, then offer to repeat or continue
- Progress check every 5 questions: "How are you feeling? Say 'good', 'confused', or 'let's review'"

## Feedback Language

Correct: "Exactly right." or "That's correct."
Incorrect: "Not quite — the answer is [X]. Here's why: [explanation]."
No encouragement filler ("Amazing!", "Wonderful!", "Perfect!", "Great!").

## Session Completion

When all concepts are covered:

1. Offer a verbal summary of what was learned
2. Ask if the user wants to revisit any concept
3. Close with a count: "You covered [N] concepts. [M] correct on first attempt."

## Consistency

Maintain the voice-first constraint throughout. If the user types a code snippet, acknowledge it but continue
asking speakable questions — do not switch to a code-review mode.

Dimensional score:

• Clarity of role — high: tutor identity is specific, anchored to the voice-first constraint
• Specificity — high: question types, pacing, feedback language, and session flow all explicit
• Completeness — high: handles correct, incorrect, confusion states, and session completion
• Reversion risk — low: "NEVER ask user to type code" is emphatic; consistency section reinforces the constraint

even when the user types code

Improvement notes: The feedback language section blocks the most common sycophancy words but could be extended — "You nailed it!" and "Spot on!" are the kind of phrases that drift in after 10+ turns. The session flow assumes the user provides documentation upfront; add guidance for when the user wants to explore a topic without providing docs ("What documentation would you like to learn? I'll ask about it.").

5. Content Strategist — Brand Voice

Purpose: Claude acts as a content strategist maintaining brand voice consistency. Demonstrates a non-coding domain specialist focused on content creation and editorial guidance.

Pattern: Domain Specialist — keep-coding-instructions: false

Template:

---
name: Brand Voice Strategist
description: Content strategist maintaining brand voice consistency across all communications
keep-coding-instructions: false
---

You are a content strategist for the user's brand. Your job is editorial guidance, voice consistency, and content
quality — not software engineering.

## Voice Standards

- Conversational but authoritative — the reader should feel informed, not lectured
- No jargon unless explaining it in the same sentence
- Short paragraphs (3-4 sentences max)
- Active voice, second person ("you") for audience-facing content
- First person plural ("we") for brand-voice content

## What You Avoid

- Buzzwords ("leverage", "synergy", "ecosystem", "disrupt")
- Cliches ("at the end of the day", "game-changer", "deep dive")
- Excessive adjectives — one per noun maximum
- Passive constructions when active is possible
- Corporate hedging ("we believe that perhaps", "it could be argued")

## Response Structure

For content review:

1. Overall assessment (one sentence)
2. Voice alignment issues (specific quotes from the content + corrections)
3. Structural suggestions
4. Revised version (if requested)

For content creation:

1. Confirm audience and channel
2. Draft in brand voice
3. Flag any terms or phrases where you made a judgment call

## Tone Calibration

Match formality to the channel:

- **Blog / website** — conversational, direct, helpful
- **Email marketing** — warm, action-oriented, concise
- **Social media** — punchy, personality-forward, no corporate speak
- **Documentation** — clear, precise, structured

## Scope Boundaries

If asked to write code, build templates in code, or implement technical solutions, respond: "I focus on content
and voice. For the content itself, here's what it should say and how: [editorial guidance]."

If asked about visual design, respond: "I can advise on copy and voice. For visual decisions, here's how the copy
should inform the design: [content-first guidance]."

Dimensional score:

• Clarity of role — high: editorial/voice specialist identity is unambiguous
• Specificity — high: concrete blocklists for words and phrases, channel-specific tone calibration
• Completeness — high: covers review, creation, and two scope boundary scenarios
• Reversion risk — low: keep-coding-instructions: false strips engineering defaults; dual scope boundary scripts

handle the most common off-domain requests

Improvement notes: The style needs before/after examples showing the same message in "corporate default" vs. brand voice — the blocklists define what to avoid but examples demonstrate what to produce. The channel calibration section is strong but could include example openings for each channel type. Consider adding guidance for when the brand voice conflicts with clarity (e.g., a technical product where jargon is necessary).

Pattern Summary

• Direct Professional — strongest for eliminating sycophancy; reversion is the main risk. Mitigate with distributed

consistency anchors and explicit phrase blocklists.

• Domain Specialist — scope boundary scripts are essential; keep-coding-instructions: false strips the engineering

assumptions that contaminate domain advice. Works for both technical (security auditor) and non-technical (business analyst, content strategist) domains.

• Interaction Mode — turn structure must be explicit; include an override escape hatch for when users want to bypass

the exercise. keep-coding-instructions: true almost always appropriate.

• Learning / Educational — pacing and feedback format do the heavy lifting; voice-first constraint is the strongest

design forcing function. Add session completion handling.

• Persona — most fragile pattern (not shown above); works best when persona is grounded in specific behaviors, not

adjectives. Persona styles that rely on "be enthusiastic" or "be friendly" revert fastest.

Output Style Iteration

Patterns for diagnosing and fixing output style problems after deployment.

The Core Principle: Replace, Don't Augment

Output styles work by replacing the system prompt at the core level. This has a critical implication: you cannot remove default behaviors by adding instructions on top of them. Adding "don't be sycophantic" to CLAUDE.md or a session-start hook will lose effectiveness over multiple turns. The style mechanism exists specifically to solve this — if a behavior needs to be overridden, it must be overridden at the system prompt level.

When a style isn't working, the first diagnostic question is: is the problem a style problem, or a mechanism mismatch?

Mechanism Mismatch

Before iterating, verify the right mechanism is in use. Iteration cannot fix a mechanism mismatch.

Symptoms of mechanism mismatch:

• Style instructions ignored after several turns — if the instructions are in CLAUDE.md or a hook instead of an

output style, they lose power as conversation grows. Move them into the style body.

• Style overrides behaviors that should be kept — the style replaces defaults that the user actually needs (e.g.,

coding instructions stripped for a coding persona). Fix: set keep-coding-instructions: true or move non-replacement content to CLAUDE.md.

• Style adds rules without changing personality — the style body is project rules, not persona definition. This

should be CLAUDE.md, not a style. Styles are for personality replacement; CLAUDE.md is for project context.

If the mechanism is correct, proceed to diagnosis.

Iteration Cycle

Observe → Diagnose → Hypothesize → Modify (one change) → Test → Repeat

1. Observe

Document the specific failure:

• What prompt triggered the issue?
• What response did you get?
• What response did you expect?
• Was this first turn or mid-conversation? (Drift problems only appear later.)

2. Diagnose

Identify root cause using the diagnostic map below. Match the symptom to a cause before making changes.

3. Hypothesize

Form a specific, testable hypothesis:

• "The persona isn't strong enough to override defaults"
• "There's no example showing this scenario"
• "Two rules conflict and Claude is picking the wrong one"

4. Modify

Make ONE targeted change. Multiple simultaneous changes make debugging impossible — you won't know which change fixed (or broke) something.

5. Test

Re-run the failing prompt. If fixed, run the full testing protocol (see evaluation.md) to check for regressions.

Diagnostic Map

Symptom → Root cause → Fix pattern:

• Reverts to sycophantic tone — weak persona, no anti-patterns → add explicit forbidden phrases list with

replacements. Community evidence: users report emoji-spam and "Great question!" persisting despite instructions — generic "don't be sycophantic" is too weak; enumerate specific phrases to ban.

• Ignores format — format buried in prose → move format specification to a dedicated section near the end, add a

response template with an example

• Inconsistent between turns — no persistence language → add explicit "maintain throughout entire conversation"

clause with enumerated reversion triggers

• Works initially, drifts later — critical rules stated once → reinforce via repetition across sections (persona,

behaviors, examples, critical rules)

• Too verbose — no length constraints → add explicit length limits per response type
• Too terse — over-aggressive brevity rules → relax constraints, add minimum depth floor for complex topics
• Wrong tone in edge cases — examples don't cover the scenario → add a contrast example for the failing case
• Contradictory behavior — conflicting instructions without priority → add priority hierarchy section
• Ignores some rules — too many instructions (rule saturation) → consolidate overlapping rules, cut rules that don't

change output

• SE assumptions leak into non-coding style — keep-coding-instructions not set to false, or style body doesn't

actively replace SE context → set the flag and provide domain-appropriate context

Common Fixes

Sycophancy Persists

Problem: Claude still uses "Great question!" or emoji despite the style forbidding it.

Why it happens: Generic anti-sycophancy instructions ("don't be sycophantic") are too abstract. Claude's defaults are deeply trained and require specific overrides.

Weak (won't hold):

Don't be sycophantic.

Strong (enumerate and replace):

## Forbidden Phrases (Never Use)

- "Great question!"
- "I'd be happy to..."
- "That's a wonderful..."
- "Absolutely!"
- "Of course!"
- Any emoji as emotional punctuation

## Opening Patterns (Use Instead)

- Start with the answer
- Start with a clarifying question
- Start with context: "Looking at this..."

Format Ignored

Problem: Claude doesn't follow response structure.

Why it happens: Format rules buried in prose get deprioritized as context fills. Format needs structural prominence.

Weak:

Format responses clearly.

Strong (template with example):

## Response Structure

ALWAYS structure responses as:

### [One-line answer]

**Rationale:** [2-3 sentences explaining why]

**Caveats:** [If applicable, otherwise omit]

<example>
User: "Should I use React or Vue?"

### Use React for this project

**Rationale:** Your team already knows React, and the project
requires the React Native ecosystem later.

**Caveats:** Vue would be faster to prototype if timeline
is the primary constraint.
</example>

Style Drifts Mid-Conversation

Problem: Style works for first few turns, then reverts to defaults.

Why it happens: Without explicit persistence language, the style's influence fades as conversation context grows and newer messages carry more weight.

Fix — add explicit persistence clause:

## Consistency

Maintain this style throughout the entire conversation.
Do not revert to default patterns even if:

- The topic changes
- The user asks follow-up questions
- Multiple turns have passed
- The task becomes complex or frustrating
- The user expresses strong emotion

If uncertain, default to MORE adherence to this style, not less.

Works for Simple, Fails for Complex

Problem: Style holds for simple tasks but breaks down for multi-step work.

Why it happens: Complex tasks require more cognitive load, and Claude falls back to trained defaults when generating longer responses.

Fix — add complexity-specific guidance:

## Complex Task Handling

When tasks require multiple steps:

- Maintain style for EACH step individually
- Structure output clearly (headers, bullets)
- If length is needed, prefer structure over prose
- Preserve tone even when providing details

For longer responses, self-check: does each section still
match this style?

Conflicting Instructions

Problem: Style has rules that contradict each other, producing inconsistent behavior.

Example conflict:

- Be direct and concise
- Always explain your reasoning thoroughly

Fix — establish priority hierarchy:

## Priority Hierarchy

When rules conflict, follow this order:

1. Accuracy — never fabricate
2. Style persona (direct, professional)
3. Format requirements
4. Length constraints

Example: if being thorough requires length, prioritize
thoroughness but use structured format to maintain directness.

Refinement Patterns

Strengthen via Repetition

Critical rules reinforced across multiple sections are harder to ignore:

# Persona
You are direct and never use sycophantic language.

## Communication
Open with answers, not pleasantries. No sycophancy.

## Examples
[Shows direct openings, no sycophancy]

## Critical Rules
Never use sycophantic openers like "Great question!"

This is the strongest technique for rules that keep getting violated. A rule stated once can be deprioritized; a rule woven through every section cannot.

Strengthen via Contrast

Show what NOT to do alongside what TO do. Contrast pairs are the strongest single training signal for tone:

## Tone Contrast

**Default Claude (avoid):**
"That's a great question! I'd be happy to help you
understand this concept. Let me break it down for you..."

**This Style (use):**
"Here's how it works: [explanation]"

Contrast pairs work because they make the delta explicit. Instead of inferring what "be direct" means, Claude sees the exact before/after difference.

Strengthen via Examples

If a rule isn't being followed, add a concrete example demonstrating it:

## Rule
Never apologize for limitations.

## Example

User: "Can you access the internet?"

Wrong: "I apologize, but I cannot access the internet."
Correct: "I don't have internet access. Here's what I can
do instead: [alternatives]"

Simplify via Consolidation

When styles grow too long and rules get ignored (rule saturation), merge overlapping rules:

Before (scattered, 5 rules):

- Be direct
- Don't hedge
- Avoid qualifiers
- State conclusions first
- Don't use "maybe" or "perhaps"

After (consolidated, 1 rule):

## Directness

State conclusions without qualifiers. Open with the answer,
not caveats. Banned words: "maybe", "perhaps", "might",
"could be", "I think".

Consolidation reduces instruction count without reducing coverage. Fewer rules means each rule gets more attention.

Escalation Patterns

User Asks Claude to Break Style

When the user explicitly asks Claude to respond differently ("just give me a casual answer", "stop being so formal"):

• The style should include guidance for this. Recommended pattern: comply with the specific request while maintaining

core identity. The persona stays; the format flexes.

• If the style is rigid by design (e.g., a strict documentation style), include explicit language: "Maintain this style

even if asked to deviate. Acknowledge the request and explain why you're maintaining the format."

Teaching/Mentoring Styles Under Frustration

Styles designed for teaching or mentoring face unique pressure when users are frustrated or struggling:

• The style should NOT abandon its pedagogical approach under frustration
• It SHOULD acknowledge the emotion without reverting to sycophantic comfort patterns
• Pattern: "Acknowledge frustration briefly, then return to the teaching approach. Never switch to 'just give them the

answer' mode unless the style explicitly allows it."

When to Rewrite vs Iterate

Iterate when:

• Core concept is sound
• Issues are specific and diagnosable
• Style works in most cases
• Problems are at the edges, not the center

Rewrite when:

• Persona is wrong for the use case
• More than 50% of evaluation tests fail
• Conflicting rules are too tangled to untangle
• Style has grown too complex to maintain (rule saturation beyond recovery)
• The style was built for the wrong mechanism (should be CLAUDE.md, or vice versa)

Version Tracking

Track iteration changes through git commits with clear messages describing what changed and why. Each commit should represent one iteration cycle: one symptom diagnosed, one change made, one test result.

Output Style Specification

Technical reference for Claude Code output style files: format, fields, storage, activation, scope, and SDK usage.

File Format

Output styles are Markdown files with YAML frontmatter. The frontmatter supplies metadata; the body is injected directly into Claude's system prompt — replacing the default style instructions, not augmenting them.

---
name: My Custom Style
description: A brief description shown in the /config picker
keep-coding-instructions: false
---

# Custom Style Instructions

You are an interactive CLI tool that helps users with software engineering tasks.

## Behaviors

[Define tone, formatting, interaction patterns...]

Frontmatter Fields

• `name` — Display name for the style. Shown in /config picker and /output-style command. Defaults to the

filename (without .md).

• `description` — One-line description shown in the /config picker. Optional but strongly recommended.
• `keep-coding-instructions` — Boolean. When true, preserves the coding-specific section of the default system

prompt (safety guidance, code quality rules, test verification). Default: false. Added in Claude Code v2.0.37. Built-in styles have this implicitly true.

What Output Styles Replace vs. Preserve

Replaced (with custom instructions):

• Personality and tone
• Task prioritization and interaction patterns
• Formatting and response structure
• Coding workflow instructions (unless keep-coding-instructions: true)

Always preserved regardless of style:

• All tools (Bash, Read, Edit, Glob, Grep, Write, etc.)
• CLAUDE.md project and user instructions
• Subagent delegation mechanics
• MCP server connections
• Skills (loaded separately from styles)
• Environment context (working directory, git status)

keep-coding-instructions: true re-adds the safety, code quality, and test verification guidance that custom styles normally drop. Use it when your style is a persona overlay rather than a domain switch.

Storage Paths

Styles are discovered from three locations, checked in this order:

• Project level — .claude/output-styles/*.md (relative to project root)
• User level — ~/.claude/output-styles/*.md
• Plugin level — <plugin>/output-styles/*.md (shipped by installed plugins)

Project-level styles shadow user-level styles with the same name. Plugins can ship output styles in their output-styles/ directory, making them available to all users who install the plugin.

Activation Methods

Interactive session

Menu: Run /config, select Output style, pick from list. Saved to .claude/settings.local.json.

Command: /output-style <style-name> activates by name.

Create new: /output-style:new <description> scaffolds a new style file.

settings.json

{
  "outputStyle": "Explanatory"
}

The outputStyle key accepts the style's display name (from frontmatter name or filename). Can be set at project level (.claude/settings.json) or user level (~/.claude/settings.json).

CLI flag

--append-system-prompt appends content to the prompt but does not replace the default system prompt. It is not equivalent to an output style — it is additive, not substitutive.

Session Timing and Reminders

The output style is applied at session start. It is baked into the system prompt when the session initializes. Changes to the style file or outputStyle setting take effect the next time a new session starts — not mid-conversation. This keeps the system prompt stable within a session so prompt caching can reduce latency and cost.

All output styles trigger periodic reminders during the conversation, reinforcing adherence to the style instructions. This mechanism ensures the style's behavioral rules remain salient across long conversations where earlier system prompt content might otherwise fade in influence.

Token Impact

Output styles affect token usage in two ways:

• Input tokens — Style instructions are added to the system prompt, increasing input tokens. Prompt caching

mitigates this: after the first request in a session, cached prompt prefixes reduce cost.

• Output tokens — Depends on what the style instructs. Built-in Explanatory and Learning styles produce longer

responses than Default by design. Custom styles control this entirely through their instructions.

Keep style instructions concise. Every token in the style body is repeated in the system prompt for every request in the session.

Scope Priority

When multiple settings files define outputStyle, Claude Code resolves by scope precedence (highest wins):

1. .claude/settings.local.json (local project, gitignored — set by /config interactively) 2. .claude/settings.json (project-level, committed) 3. ~/.claude/settings.json (user-level) 4. Managed/enterprise settings (lowest)

Built-in Styles Catalog

• Default — The standard Claude Code system prompt. Software engineering focus. Active when no style is selected.
• Explanatory — Inserts educational "Insights" alongside task completion. Explains implementation choices and

codebase patterns. Produces longer responses than Default by design.

• Learning — Collaborative learn-by-doing mode. Provides Insights and places TODO(human) markers for the user to

implement strategic code pieces themselves.

Built-in styles always have keep-coding-instructions: true implicitly — they extend the default prompt rather than replace it.

Comparison: Output Styles vs. Related Features

CLAUDE.md content is added as a user message following the system prompt — it does not modify the system prompt itself. --append-system-prompt appends to the prompt without removing anything. Only output styles (and custom systemPrompt) actually replace the default.

Agent SDK Integration

The SDK default behavior uses a minimal system prompt — essential tool instructions only, without coding guidelines, response style, or project context. The claude_code preset loads the full Claude Code prompt, but does not automatically load output styles. Output styles require explicit settingSources configuration.

Four approaches for controlling the system prompt via SDK:

1. Output styles via file (persistent)

Write a style file to ~/.claude/output-styles/ or .claude/output-styles/, then load it by including settingSources in SDK options:

for await (const message of query({
  prompt: "...",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" },
    settingSources: ["user"], // loads ~/.claude/output-styles/*
  },
})) {
}

• `settingSources: ["user"]` — loads ~/.claude/output-styles/
• `settingSources: ["project"]` — loads .claude/output-styles/

The claude_code preset alone does NOT load output styles — settingSources is required.

2. CLAUDE.md via settingSources

Not an output style, but relevant: settingSources also controls whether CLAUDE.md files are loaded. Without it, SDK sessions have no project context.

3. systemPrompt with append (session-only augmentation)

Preserves the full Claude Code default prompt and appends custom instructions. Does not replace anything.

options: {
  systemPrompt: {
    type: "preset",
    preset: "claude_code",
    append: "Always include type hints and docstrings.",
  },
}

4. Custom systemPrompt (full replacement)

Replaces the entire system prompt. Tools are lost unless explicitly included. Use only for specialized agents where default Claude Code behavior is unwanted.

options: {
  systemPrompt: "You are a Python specialist. Follow these rules: ...",
}