# Claude Code Output styles

> Claude Code: Built-in and custom output styles, keep-coding-instructions, plugin distribution, and prompt-cache effects.

URL: https://docs.passion8.cc/en/docs/claude-code/output-styles
Language: en
Publisher: Passion8

An output style changes how Claude Code answers by modifying its system prompt: role, tone, format, or teaching approach. Keep project rules, coding conventions, and durable context in [Memory and rules](https://docs.passion8.cc/en/docs/claude-code/memory), not an output style.




If you repeatedly ask for a response format, use an output style. If you are describing build commands, tests, or protected directories, use CLAUDE.md or rules.




## Built-in styles

| Style | Behavior | Suitable for |
| --- | --- | --- |
| Default | Standard software-engineering agent | Most coding tasks |
| Proactive | More autonomous execution and fewer routine questions | Tasks intended to proceed automatically |
| Explanatory | Adds explanations and insights while working | Learning a codebase and onboarding |
| Learning | Collaborative learning with `TODO(human)` tasks | Teaching and practice |

Proactive is not a permission mode. Tools still follow permission rules.

## Switch styles

Use `/config`:

```text
/config
```

Select Output style. The choice is normally stored in `.claude/settings.local.json`:

```json title=".claude/settings.local.json"
{
  "outputStyle": "Explanatory"
}
```

Because the style changes the system prompt, changing it mid-session does not immediately replace the loaded prompt. Use `/clear` or start a new session.




The old `/output-style` command is deprecated and removed. Use `/config` or edit `outputStyle` directly.




## Custom output styles

A custom style is a Markdown file. Its filename supplies the default name unless frontmatter overrides it.

| Scope | Location |
| --- | --- |
| User | `~/.claude/output-styles/` |
| Project | `.claude/output-styles/` |
| Managed | `.claude/output-styles/` in the administrator-provided directory |

Example:

```markdown title=".claude/output-styles/diagrams-first.md"
---
name: Diagrams first
description: Start code explanations with a Mermaid diagram
keep-coding-instructions: true
---

When explaining code, architecture, or data flow, show a Mermaid diagram first,
then explain it in short paragraphs. Keep the diagram under 15 nodes.
```

Set `keep-coding-instructions: true` when changing presentation while retaining software-engineering behavior. You can omit it for writing, data analysis, or another non-coding role.

## Frontmatter

| Field | Purpose |
| --- | --- |
| `name` | Display name; defaults to the filename |
| `description` | Description in the `/config` picker |
| `keep-coding-instructions` | Retain the default coding instructions |
| `force-for-plugin` | Force the style when distributed by a plugin |

Plugins can ship styles in `output-styles/`. Users can select them through `/config` after enabling the plugin.

## Boundaries with other mechanisms

| Mechanism | Changes | Typical use |
| --- | --- | --- |
| Output styles | System prompt | Role, tone, default response format |
| `CLAUDE.md` | User-message context | Project rules, architecture, commands |
| `--append-system-prompt` | Additional system instructions for one launch | Scripts and CI |
| Subagents | Separate system prompt, model, and tools | Isolated specialist tasks |
| Skills | Relevant task instructions | Reusable workflows |

## Cost and caching

| Action | Effect on five-minute / one-hour caching |
| --- | --- |
| Change outputStyle and continue | Loaded system prompt usually remains unchanged immediately |
| Apply a new style after clear/new session | Changes system prompt; next request usually misses |
| Explanatory or Learning | Longer output and more output tokens |
| Long custom style | More input tokens and higher initial cache-write cost |
| Frequent style switching | Repeated prompt/cache identity changes reduce reuse |

Choose the style at the start of a task. Repeatedly changing tone mid-task is usually inefficient.

## Passion8 recommendations

| Scenario | Recommendation |
| --- | --- |
| Everyday coding | Default |
| Fewer questions and more execution | Proactive with explicit permissions |
| Learning a large project | Explanatory |
| Teaching teammates | Learning |
| Fixed delivery format | A short custom style |

Passion8 does not change the output-style mechanism. Model availability, billing, and caching still depend on the actual Claude Code request and gateway behavior.

## Official references

- [Output styles](https://code.claude.com/docs/en/output-styles.md)
- [Settings](https://code.claude.com/docs/en/settings.md)
- [Prompt caching](https://code.claude.com/docs/en/prompt-caching.md)
- [Plugins](https://code.claude.com/docs/en/plugins.md)