Claude Code Output Styles

Output Style allows you to customize Claude Code's interaction style and response method, adapting it to more use cases beyond software development while retaining core features such as running local scripts, reading/writing files, and tracking todos.

Essentially, it changes Claude Code's interaction logic and response style by modifying the system prompt.

Built-in Output Styles

Claude Code provides 3 out-of-the-box output styles:

Style Name Applicable Scenarios Core Features
Default Style (default) Daily software engineering tasks Focus on efficiently completing coding, debugging, refactoring, and other tasks, with concise and direct responses
Explanatory Style (explanatory) Learn-while-doing scenarios Explains implementation ideas, design patterns, and other knowledge points while completing tasks, suitable for developers who want to deeply understand code
Learning Style (learning) Active hands-on learning Collaborates with you to complete tasks, adding at key positionsTODO(human)markers that guide you to implement core code snippets yourself rather than directly providing answers

How It Works

When switching output styles, Claude Code adjusts the system prompt according to the following rules:

  1. All styles remove default constraint instructions such as "concise replies, efficient output"
  2. Custom styles by default remove coding-related instructions such as "verify code with tests" (if you need to keep them, you can enable them in the style filekeep-coding-instructions: true）
  3. Each style appends custom rules at the end of the system prompt, overriding default behavior
  4. Compliance checks are triggered during conversations to ensure Claude always follows the current style's instructions

Switching Output Styles

There are two ways to switch styles; the configuration is saved in the project directory's.claude/settings.local.jsonfile, andonly takes effect for the current project：

Method 1: Menu SelectionAfter entering the command, select the target style from the interactive menu:

/output-style

Method 2: Directly SpecifyAdd the style name directly after the command to accomplish it in one step:

/output-style explanatory
/output-style learning
/output-style default

Besides switching with commands, you can also directly edit.claude/settings.local.json(project-level) or~/.claude/settings.json(global-level) files to modifyoutputStylethe value of the field to switch styles.

Creating Custom Output Styles

If the built-in styles do not meet your needs, you can define your own style using a Markdown file.

1. File Save Location

Level Save Path Scope
User-level ~/.claude/output-styles/ Can be used by all projects of the current user
Project-level .claude/output-styles/(in the project root directory) Only available for the current project; can be committed to git and shared with the team

2. File Format

A custom style file consists of two parts: the topYAML frontmatter(metadata configuration) and the lowerMarkdown body(specific instruction content).

Example

---
name: data-analyst               # Style name, displayed in the /output-style menu (uses the file name if not filled)
description: Focus on transforming complex data into visual reports and analytical conclusions
                                 # Style description, shown in the menu's description text (optional)
keep-coding-instructions: false  # Whether to keep default coding-related instructions
                                 # false (default): remove coding instructions, suitable for non-development scenarios
                                 # true: keep coding instructions while also applying custom rules
---

# Role Definition
You are a professional data analysis assistant, skilled in using Python to process various types of structured data,
and turning complex data into concise and easy-to-understand visual reports.

## Response Rules
1. All analyses must include three parts: "Conclusion + Data Support + Optimization Suggestions"
2. When generating code, detailed comments must be included, with priority given to Pandas and Matplotlib
3. Avoid piling up technical jargon; explain complex concepts in plain language

## Format Requirements
1. The conclusion section should be displayed in bold
2. Code blocks should be wrapped in ```python tags
3. The suggestions section should be presented as an ordered list

## Special Scenarios
1. When encountering missing data, proactively prompt the user to supplement key information instead of directly throwing an error
2. When generating visual charts, use Chinese labels and a light theme by default

3. Frontmatter Parameter Description

Parameter Name Required? Description Default Value
name no Style name, displayed in/output-stylethe menu. If not filled, use the file name (without the .md extension) File name
description no A brief description of the style's function, displayed in the menu's description text to help distinguish multiple custom styles None
keep-coding-instructions no Whether to retain the coding-related instructions in the default system prompt. When set totrue, custom instructions will be overlaid on the default coding instructions false

4. Usage Steps

  1. Create according to the above format.mdfile (for exampledata-analyst.md）
  2. Place the file in the corresponding directory:
    • Available for all projects:~/.claude/output-styles/data-analyst.md
    • Available only for the current project:.claude/output-styles/data-analyst.md
  3. Execute in Claude Code/output-style, and you can see and select the newly created style in the menu

Differences from Related Features

Output styles look similar to the following features, but they operate at different levels:

Comparison Target Core Difference
Output Style vs CLAUDE.md Output style willReplacethe default software engineering system prompt, fundamentally changing Claude's working mode; CLAUDE.md appends project background and conventions in the form of user messages, without modifying the system prompt itself
Output Style vs --append-system-prompt Output style replaces and disables the default prompt;--append-system-promptappends content at the end of the default prompt; both preserve the original prompt
Output Style vs Subagent Output style modifies the system prompt of the main agent, affecting the global interaction style; subagent is an independent task processing module that can customize models, tools, and trigger conditions, and returns results after handling specific subtasks
Output Style vs Custom Slash Commands Output style is a "stored system prompt" that determines Claude's overall interaction style; custom slash commands are "stored user prompts" used to quickly execute a specific instruction or task

Custom Style Template

The following is a generic custom output style template. Replace the[ ]content in it with your actual needs, and save it as.mda file for use:

Example

---
name: [Style name, e.g., Writing Assistant]
description: [One-sentence description of the purpose, e.g., Focus on technical documentation writing, output clear and accurate content]
keep-coding-instructions: [true or false]
---

# 1. Core Positioning
[Define Claude's role and expertise, for example:
You are a professional technical documentation writing assistant, skilled at transforming complex technical concepts into clear and easy-to-understand text]

# 2. Response Rules
[Specify Claude's response logic, for example:
1. Each reply must include three parts: "Core Point + Detailed Explanation + Example"
2. Use active voice and avoid passive sentence structures
3. Provide a brief explanation when technical terms first appear]

# 3. Format Requirements
[Specify the layout format of the output, for example:
1. Use## for second-level headings
2. Code examples use code blocks and specify the language type
3. Key information is marked in bold]

# 4. Special Scenario Handling
[Handling rules for specific situations, for example:
1. When examples are needed, prefer real-world scenarios over abstract examples.
2. When encountering unclear requirements, confirm the intent before starting to write.]
Other extensions