Appearance
An Output Style is a format contract in a file — declare it once in .claude/output-styles/, reference it by path in every command, and format drift between runs becomes impossible.
Primitive
Output Style
The artifact
A markdown file that owns the shape of one artifact class.
.claude/output-styles/review-report.md
# Review Report Style
Who Uses This
Commands:/review/re-review
Consumers:fix agentPR gate
Sections
## Summary
Required: yes | Format: 2–4 sentences, no bullet points
High-level verdict on the change. First sentence states pass/fail.
## Findings
Required: yes | Format: ordered list, severity prefix
Each item: [CRITICAL|WARN|INFO] — description — file:line
## Verdict
Required: yes | Format: single token on its own line
One of: APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION
Field Conventions
| Field | Type | Required | Notes |
|---|---|---|---|
| severity | enum | yes | CRITICAL, WARN, INFO — uppercase only |
| file_ref | string | yes | format: path/to/file.ts:42 |
| verdict | enum | yes | last line of output, no punctuation |
| metadata | object | no | run_id, model_version if present |
The style file is the single source of truth for what a review report looks like — commands cite it, consumers rely on it.
Without vs with
Format drift is silent until a parser breaks.
Withoutformat defined inline
Run 1 — Claude 3.5
## Summary
Change looks good overall...
## Issues Found
1. WARN auth.ts:12 ...
## DecisionAPPROVE
Run 2 — Claude Sonnet
## Summary(missing)
## Findings
- auth.ts line 12: warn...
## Recommendationapprove
Downstream parser breaks. Section heading differs run-to-run. PR gate can't extract verdict reliably.
Withstyle referenced by path
Run 1 — Claude 3.5
## Summary
Change looks good overall...
## Findings
1. WARN auth.ts:12 ...
## Verdict
APPROVE
Run 2 — Claude Sonnet
## Summary
Minor issues found...
## Findings
1. WARN auth.ts:12 ...
## Verdict
REQUEST_CHANGES
Both runs produce identical structure. Parser always works. Edit the style file once to fix all consumers.
Format drift is not a model problem — it's an architecture problem. The style file solves it structurally.
How it's referenced
Path reference, not inline copy — so edits propagate automatically.
The command template that wires in the Output Style at invocation time
# In .claude/commands/review.md — command template
Review the staged diff. Format your output according to:
$(cat .claude/output-styles/review-report.md)
# The style file is read at runtime and injected into the prompt.
# The command never hardcodes format — it delegates to the style file.
●The style file is not inlined. The $(cat ...) shell expansion loads it at runtime. If you improve the style tomorrow, every command that references it gets the update automatically — no find-and-replace across commands.
●Any command can cite the same style. /review and /re-review both expand the same file. One format contract governs both artifacts — the contract lives in one place.
●Consumers get a stable schema. The fix agent and PR gate parse output that is structurally identical across runs, models, and authors because the style file is the invariant.
The pattern is the same as a schema file for a database — you don't inline the column list into every query; you declare it once and every query defers to it.
When to create one
Create when consistency is load-bearing. Skip when it isn't.
Create one
Format consistency is load-bearing
- 2 or more commands emit the same artifact class
- Downstream code parses or diffs the output
- Format must survive model variant changes
- Multiple authors or agents produce the artifact
- The artifact feeds a gate, a summary, or a scorecard
Skip it
Overhead exceeds value
- The artifact is one-off — produced once, read once
- Format is simple enough to specify inline in the command
- Only one command ever produces this artifact class
- No downstream consumer relies on the structure
- The format changes so frequently a file would drift anyway
The signal to create an Output Style is a second command that produces the same artifact — at that moment, the format contract needs a home.
The discipline
Declare format once, by reference — never inline, never duplicated.
Format drift is invisible until a parser fails at 2 AM. The Output Style forecloses that failure by making structure a declared contract rather than an emergent property of each run. Edit one file and every consumer inherits the change. That's the whole primitive.