Output styles

Adapt Claude Code for uses beyond software engineering

Output styles allow you to use Claude Code as any type of agent while keeping its core capabilities, such as running local scripts, reading/writing files, and tracking TODOs.

Built-in output styles

Claude Code's Default output style is the existing system prompt, designed to help you complete software engineering tasks efficiently.

There are two additional built-in output styles focused on teaching you the codebase and how Claude operates:

Explanatory: Provides educational "Insights" in between helping you complete software engineering tasks. Helps you understand implementation choices and codebase patterns.
Learning: Collaborative, learn-by-doing mode where Claude will not only share "Insights" while coding, but also ask you to contribute small, strategic pieces of code yourself. Claude Code will add TODO(human) markers in your code for you to implement.

How output styles work

Output styles directly modify Claude Code's system prompt.

Non-default output styles exclude instructions specific to code generation and efficient output normally built into Claude Code (such as responding concisely and verifying code with tests).
Instead, these output styles have their own custom instructions added to the system prompt.

Change your output style

You can either:

Run /output-style to access the menu and select your output style (this can also be accessed from the /config menu)
Run /output-style [style], such as /output-style explanatory, to directly switch to a style

These changes apply to the local project level and are saved in .claude/settings.local.json.

Create a custom output style

To set up a new output style with Claude's help, run /output-style:new I want an output style that ...

By default, output styles created through /output-style:new are saved as markdown files at the user level in ~/.claude/output-styles and can be used across projects. They have the following structure:

---
name: My Custom Style
description:
  A brief description of what this style does, to be displayed to the user
---

# Custom Style Instructions

You are an interactive CLI tool that helps users with software engineering
tasks. [Your custom instructions here...]

## Specific Behaviors

[Define how the assistant should behave in this style...]

You can also create your own output style Markdown files and save them either at the user level (~/.claude/output-styles) or the project level (.claude/output-styles).

Output Styles vs. CLAUDE.md vs. --append-system-prompt

Output styles completely "turn off" the parts of Claude Code's default system prompt specific to software engineering. Neither CLAUDE.md nor --append-system-prompt edit Claude Code's default system prompt. CLAUDE.md adds the contents as a user message following Claude Code's default system prompt. --append-system-prompt appends the content to the system prompt.

Output Styles vs. Agents

Output styles directly affect the main agent loop and only affect the system prompt. Agents are invoked to handle specific tasks and can include additional settings like the model to use, the tools they have available, and some context about when to use the agent.

Output Styles vs. Custom Slash Commands

You can think of output styles as "stored system prompts" and custom slash commands as "stored prompts".

output-styles.md +40 −101

1# Output styles1# Output styles

2 2

~~3> [DEPRECATED] Adapt Claude Code for uses beyond software engineering~~3> Adapt Claude Code for uses beyond software engineering

~~5<Warning>~~

~~6 Output styles are **DEPRECATED.** On **November 5, 2025** or later, we'll~~

~~7 stop supporting the output styles feature. Use `--system-prompt-file`,~~

~~8 `--system-prompt`, `--append-system-prompt`, CLAUDE.md, or [plugins](/en/docs/claude-code/plugins) instead.~~

~~9 For **Explanatory** output style users, you can reference the ([explanatory-output-style~~

~~10 plugin](https://github.com/anthropics/claude-code/tree/main/plugins/explanatory-output-style)~~

~~11 in our public repository.)~~

~~12</Warning>~~

~~14## Deprecation timeline~~

~~16As of **November 5, 2025**, Claude Code will:~~

~~18* Stop supporting the output styles feature~~

~~19* Remove the `/output-style` command and related functionality~~

~~21## Alternative for Custom Output Styles~~

~~23Use `--system-prompt-file` to start a Claude Code session with your own system~~

~~24prompt. You can also use `--system-prompt` to pass in a string to use as the system prompt, or~~

~~25`--append-system-prompt` to add to the default Claude Code system prompt.~~

~~27## Alternative for Explanatory Output Style: explanatory-output-style Plugin~~

~~29Plugins provide more powerful and flexible ways to customize Claude Code's~~

~~30behavior. The~~

~~31[`explanatory-output-style` plugin](https://github.com/anthropics/claude-code/tree/main/plugins/explanatory-output-style)~~

~~32recreates the deprecated Explanatory output style functionality.~~

~~34### Example: Explanatory Output Style Plugin~~

~~36The `explanatory-output-style` plugin uses a SessionStart hook to inject~~

~~37additional context that encourages Claude to provide educational insights.~~

~~38Here's what it does:~~

~~40* Provides educational insights about implementation choices~~

~~41* Explains codebase patterns and decisions~~

~~42* Balances task completion with learning opportunities~~

~~44### Installing a plugin~~

~~46To install a plugin like `explanatory-output-style`:~~

~~48```shell Add the marketplace (if not already added) theme={null}~~

~~49/plugin marketplace add anthropics/claude-code~~

~~50```~~

~~52```shell Install the plugin theme={null}~~

~~53/plugin install explanatory-output-style@claude-code-plugins~~

~~54```~~

~~56```shell Restart Claude Code to activate the plugin theme={null}~~

~~57/exit~~

~~58```~~

~~60```shell Disable the plugin theme={null}~~

~~61/plugin manage explanatory-output-style@claude-code-plugins~~

~~631. Press enter when you see claude-code-marketplace~~

~~642. Press space when you see explanatory-output-style to toggle enabled~~

~~653. Press down to "Apply changes", then press enter~~

~~66 You should see "Disabled 1 plugin. Restart Claude Code to apply changes."~~

~~68/exit~~

~~69```~~

~~71For more details on plugins, see the~~

~~72[Plugins documentation](/en/docs/claude-code/plugins).~~

~~74***~~

~~76## Reference: Original output styles documentation~~

~~78<Note>~~

~~79 The content below is preserved for reference only. Output styles are~~

~~80 deprecated and will be removed on November 5, 2025. Please migrate to plugins,~~

~~81 hooks, or subagents.~~

~~82</Note>~~

83 4

84Output styles allow you to use Claude Code as any type of agent while keeping5Output styles allow you to use Claude Code as any type of agent while keeping

85its core capabilities, such as running local scripts, reading/writing files, and6its core capabilities, such as running local scripts, reading/writing files, and

86tracking TODOs.7tracking TODOs.

87 8

~~88### Built-in output styles~~9## Built-in output styles

89 10

90Claude Code's **Default** output style is the existing system prompt, designed11Claude Code's **Default** output style is the existing system prompt, designed

91to help you complete software engineering tasks efficiently.12to help you complete software engineering tasks efficiently.

102 pieces of code yourself. Claude Code will add `TODO(human)` markers in your23 pieces of code yourself. Claude Code will add `TODO(human)` markers in your

103 code for you to implement.24 code for you to implement.

104 25

105### How output styles work26## How output styles work

106 27

107Output styles directly modify Claude Code's system prompt.28Output styles directly modify Claude Code's system prompt.

108 29

112* Instead, these output styles have their own custom instructions added to the33* Instead, these output styles have their own custom instructions added to the

113 system prompt.34 system prompt.

114 35

115### Change your output style36## Change your output style

116 37

117You can either:38You can either:

118 39

125These changes apply to the [local project level](/en/docs/claude-code/settings)46These changes apply to the [local project level](/en/docs/claude-code/settings)

126and are saved in `.claude/settings.local.json`.47and are saved in `.claude/settings.local.json`.

127 48

128You can also create your own output style Markdown files and save them either at49## Create a custom output style

129the user level (`~/.claude/output-styles`) or the project level

130(`.claude/output-styles`).

131 50

132### Comparisons to related features51To set up a new output style with Claude's help, run

52`/output-style:new I want an output style that ...`

133 53

134#### Output Styles vs. CLAUDE.md vs. System Prompt Flags54By default, output styles created through `/output-style:new` are saved as

55markdown files at the user level in `~/.claude/output-styles` and can be used

56across projects. They have the following structure:

135 57

136Output styles completely "turn off" the parts of Claude Code's default system58```markdown theme={null}

137prompt specific to software engineering.59---

60name: My Custom Style

61description:

62 A brief description of what this style does, to be displayed to the user

63---

65# Custom Style Instructions

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

68tasks. [Your custom instructions here...]

70## Specific Behaviors

72[Define how the assistant should behave in this style...]

73```

138 74

139**CLAUDE.md** adds the contents as a user message *following* Claude Code's default system75You can also create your own output style Markdown files and save them either at

140prompt, rather than modifying the system prompt itself.76the user level (`~/.claude/output-styles`) or the project level

77(`.claude/output-styles`).

141 78

142**System prompt CLI flags** provide different levels of control:79## Comparisons to related features

143 80

144* `--append-system-prompt`: Appends text to the end of the default system prompt81### Output Styles vs. CLAUDE.md vs. --append-system-prompt

145* `--system-prompt`: Replaces the entire default system prompt with custom text

146* `--system-prompt-file`: Loads a custom system prompt from a file

147 82

148See the [CLI reference](/en/docs/claude-code/cli-reference#system-prompt-flags) for detailed guidance on when to use each flag.83Output styles completely "turn off" the parts of Claude Code's default system

84prompt specific to software engineering. Neither CLAUDE.md nor

85`--append-system-prompt` edit Claude Code's default system prompt. CLAUDE.md

86adds the contents as a user message *following* Claude Code's default system

87prompt. `--append-system-prompt` appends the content to the system prompt.

149 88

150#### Output Styles vs. [Agents](/en/docs/claude-code/sub-agents)89### Output Styles vs. [Agents](/en/docs/claude-code/sub-agents)

151 90

152Output styles directly affect the main agent loop and only affect the system91Output styles directly affect the main agent loop and only affect the system

153prompt. Agents are invoked to handle specific tasks and can include additional92prompt. Agents are invoked to handle specific tasks and can include additional

154settings like the model to use, the tools they have available, and some context93settings like the model to use, the tools they have available, and some context

155about when to use the agent.94about when to use the agent.

156 95

157#### Output Styles vs. [Custom Slash Commands](/en/docs/claude-code/slash-commands)96### Output Styles vs. [Custom Slash Commands](/en/docs/claude-code/slash-commands)

158 97

159You can think of output styles as “stored system prompts” and custom slash98You can think of output styles as "stored system prompts" and custom slash

160commands as “stored prompts”.99commands as "stored prompts".