Documentation 2025-10-28 18:02 UTC to 2025-10-29 21:02 UTC

1# Output styles1# Output styles

2 2 

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

4 

5<Warning>

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

7 automatically convert your **user-level** output style files to plugins and

8 stop supporting the output styles feature. Use

9 [plugins](/en/docs/claude-code/plugins) instead. ([example

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

11 for the built-in Explanatory output style)

12</Warning>

13 

14## Deprecation timeline

15 

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

17 

18* Automatically convert user-level output style files

19 (`~/.claude/output-styles`) to plugins

20* Stop supporting the output styles feature

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

22 

23**What you need to do:**

24 

25* Migrate to plugins before November 5, 2025 for a smoother transition

26* Review the migration guide below to understand your options

27 

28## Alternative: Use plugins instead

29 

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

31behavior. The

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

33recreates the deprecated Explanatory output style functionality.

34 

35### Example: Explanatory Output Style Plugin

36 

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

38additional context that encourages Claude to provide educational insights.

39Here's what it does:

40 

41* Provides educational insights about implementation choices

42* Explains codebase patterns and decisions

43* Balances task completion with learning opportunities

44 

45### Installing a plugin

46 

47To install a plugin like `explanatory-output-style`:

48 

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

50/plugin marketplace add anthropics/claude-code

51```

52 

53```shell Install the plugin theme={null}

54/plugin install explanatory-output-style@claude-code-plugins

55```

56 

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

58/exit

59```

60 

61```shell Disable the plugin theme={null}

62/plugin manage explanatory-output-style@claude-code-plugins

63 

641. Press enter when you see claude-code-marketplace

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

663. Press down to "Apply changes", then press enter

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

68 

69/exit

70```

71 

72For more details on plugins, see the

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

74 

75## Migration guide

76 

77Output styles directly modified Claude Code's system prompt. Here's how to

78achieve similar effects with hooks and subagents, both available through Claude

79Code plugins:

80 

81### Use SessionStart hooks for context injection

82 

83If you used output styles to add context at the start of sessions, use

84[SessionStart hooks](/en/docs/claude-code/hooks#sessionstart) instead.

85 

86The hook's output (stdout) is added to the conversation context. You can also:

87 

88* Run scripts that dynamically generate context

89* Load project-specific information

90 

91<Note>

92 SessionStart hooks, just like CLAUDE.md, do not change the system prompt.

93</Note>

94 

95### Use Subagents for different system prompts

96 

97If you used output styles to change Claude's behavior for specific tasks, use

98[Subagents](/en/docs/claude-code/sub-agents) instead.

99 

100Subagents are specialized AI assistants with:

101 

102* Custom system prompts (must be in a separate context window from main loop)

103* Specific tool access permissions

104* Optional model to use, if not the main loop model

105 

106***

107 

108## Reference: Original output styles documentation

109 

110<Note>

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

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

113 hooks, or subagents.

114</Note>

4 115 

5Output styles allow you to use Claude Code as any type of agent while keeping116Output styles allow you to use Claude Code as any type of agent while keeping

6its core capabilities, such as running local scripts, reading/writing files, and117its core capabilities, such as running local scripts, reading/writing files, and

7tracking TODOs.118tracking TODOs.

8 119 

9## Built-in output styles120### Built-in output styles

10 121 

11Claude Code's **Default** output style is the existing system prompt, designed122Claude Code's **Default** output style is the existing system prompt, designed

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

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

24 code for you to implement.135 code for you to implement.

25 136 

26## How output styles work137### How output styles work

27 138 

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

29 140 

33* Instead, these output styles have their own custom instructions added to the144* Instead, these output styles have their own custom instructions added to the

34 system prompt.145 system prompt.

35 146 

36## Change your output style147### Change your output style

37 148 

38You can either:149You can either:

39 150 

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

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

48 159 

49## Create a custom output style

50 

51To set up a new output style with Claude's help, run

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

53 

54By 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:

57 

58```markdown theme={null}

59name: My Custom Style

60description:

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

62 

63# Custom Style Instructions

64 

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

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

67 

68## Specific Behaviors

69 

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

71```

72 

73You can also create your own output style Markdown files and save them either at160You can also create your own output style Markdown files and save them either at

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

75(`.claude/output-styles`).162(`.claude/output-styles`).

76 163 

77## Comparisons to related features164### Comparisons to related features

78 165 

79### Output Styles vs. CLAUDE.md vs. --append-system-prompt166#### Output Styles vs. CLAUDE.md vs. --append-system-prompt

80 167 

81Output styles completely “turn off” the parts of Claude Code’s default system168Output styles completely “turn off” the parts of Claude Code’s default system

82prompt specific to software engineering. Neither CLAUDE.md nor169prompt specific to software engineering. Neither CLAUDE.md nor

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

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

88 173 

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

90 175 

91Output styles directly affect the main agent loop and only affect the system176Output styles directly affect the main agent loop and only affect the system

92prompt. Agents are invoked to handle specific tasks and can include additional177prompt. Agents are invoked to handle specific tasks and can include additional

93settings like the model to use, the tools they have available, and some context178settings like the model to use, the tools they have available, and some context

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

95 180 

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

97 182 

98You can think of output styles as “stored system prompts” and custom slash183You can think of output styles as “stored system prompts” and custom slash

99commands as “stored prompts”.184commands as “stored prompts”.