---
name: output-styles-pattern
description: Pattern for reshaping how the agent presents responses
layer: pattern
cc_feature: output-styles
source: ./source-rejected.md
concept: presentation-only voice and format directives
last_verified: 2026-04-18
ngram_overlap_score: null
review_status: pending
---

## Use this when

You want to change the voice, format, or rendering of agent output without changing what the agent actually does. Output styles let operators reshape how Claude Code presents its responses without changing the underlying behavior of the agent. They live as small markdown files in a known directory and bind by name. When a style is active, the runtime injects its directives into the system prompt area before the agent generates each turn.

## Shape

A style file is a short markdown document. A handful of bullets describing the desired tone, target reading level, and any structural conventions like always using level-three headings or always wrapping commands in fenced code blocks.

The runtime does not enforce any of these directives mechanically. It is the agent itself that reads the style file at turn time and chooses to comply. This means style enforcement is best-effort and degrades when the agent's primary task pulls strongly in a different direction.

## Forces

Layering matters. Styles can be defined at the user level, the project level, or supplied by an installed plugin. When more than one style is active simultaneously, the runtime concatenates them in a documented order. There is no merging or conflict resolution. If two styles disagree about whether to use markdown tables, both directives are presented to the agent, which then has to pick one. Practitioners learn to keep styles narrow and orthogonal so that conflicts are rare.

Performance is rarely an issue with styles. They add a small fixed cost to each turn for prompt assembly and that is essentially all. Unlike session-start hooks, they do not block first-turn rendering. Unlike subagent spawns, they do not introduce additional billable workers. The cost is purely the marginal tokens of the style body itself, multiplied by the number of turns in the session.

## Gotchas

- A pitfall worth flagging is the temptation to encode behavior in styles when a hook or a skill would be more appropriate. Styles change presentation, not capability. If you find yourself writing imperative instructions like "always run the linter before reporting success," that belongs in a hook, not a style.
- Testing styles is awkward because their effect is on free-form output. The standard approach is to keep a small set of canonical prompts and run them once with the style and once without, then eyeball the diff.
- Security boundaries are minimal because styles only inject text into the prompt area. They cannot run code, cannot read files, and cannot make network calls. The risk surface is therefore mostly social.
- Observability is essentially DIY. The runtime does not log which style was active for which turn or whether the agent obeyed the style's directives.

## Anti-patterns

- Encoding procedural behavior in a style instead of a hook.
- Stacking many overlapping styles whose directives conflict.
- Trusting a third-party plugin's style without reading its body.
- Treating style enforcement as a hard guarantee rather than best-effort guidance.

## Decision quick-check

Pick this approach when:

- You have multiple distinct audiences and consistent voice matters across sessions.
- The directive is purely about format, voice, or rendering — not capability.
- You can keep the style narrow enough to compose with others without conflict.

Skip it when:

- The behavior you want is procedural and would belong in a hook or skill.
- The team has only one audience and the default voice is already adequate.
- You need hard enforcement guarantees rather than best-effort agent compliance.
