output-styles-guide

Output Styles Guide

Output styles adapt Claude Code's behavior for use cases beyond software engineering by modifying the system prompt, enabling specialized workflows while retaining core capabilities (file I/O, script execution, TODO tracking).

What Are Output Styles?

Output styles are customized system prompts that replace or supplement Claude Code's default software engineering focus. They:

• Exclude efficiency-focused coding instructions when not needed.
• Inject custom instructions tailored to a specific role or workflow.
• Persist at project level (.claude/settings.local.json) or user level (~/.claude/output-styles).
• Preserve tool access (Bash, file editing, TODO management).

Built-In Output Styles

Default

Standard Claude Code behavior optimized for software engineering: concise output, code verification, efficient task completion.

Explanatory

Adds "Insights" sections between tasks to explain implementation choices and codebase patterns. Ideal for understanding complex code or teaching.

Learning

Collaborative, learn-by-doing mode. Shares insights and requests your contribution on small code sections via TODO(human) markers. Best for skill-building or onboarding.

Changing Your Output Style

Interactive menu:

/output-style
# or access via /config

Direct command:

/output-style explanatory
/output-style default
/output-style learning

Changes apply at project level and save to .claude/settings.local.json.

Creating Custom Output Styles

Quick start (guided):

/output-style:new I want an output style that [describes your use case]

Claude creates and saves a template; you refine it.

Manual creation:

Create a markdown file at ~/.claude/output-styles/<name>.md (user-level, shared across projects) or .claude/output-styles/<name>.md (project-level only).

Structure:

---
name: My Custom Style
description: Brief description shown in /output-style menu
---

# Custom Style Instructions

You are an interactive CLI tool. [Your instructions here...]

## Specific Behaviors

[Define how the assistant behaves...]

Example: Research Assistant Style

---
name: Research Assistant
description: Focused, depth-first analysis with citations and hypothesis tracking.
---

# Research Assistant Mode

You are a research partner specializing in deep investigation and synthesis.

## Specific Behaviors

- Request sources and cite evidence when making claims.
- Track open hypotheses explicitly.
- Summarize findings in bullet-point format with confidence levels.
- Flag uncertainty and propose next investigation steps.

Best practices for custom styles:

• Be specific: "summarize in 3 bullets", "include citations", "ask for feedback".
• Retain tool flexibility: don't disable essential capabilities unless necessary.
• Test with a few tasks to verify behavior before distributing.

Common Use Cases

Use Case	Style	Benefit
Learning codebase	Explanatory	Understand why code is structured this way
Onboarding engineers	Learning	Active participation, hands-on skill building
Research/analysis	Custom	Depth-first investigation, hypothesis tracking
Technical writing	Custom	Structured outlines, examples, glossary generation
Product/UX work	Custom	Personas, user flows, journey mapping focus

Output Styles vs. Related Features

Feature	Purpose	Scope
Output Styles	Persistent system prompt modification	Affects all main agent interactions
CLAUDE.md	Project-level instructions added after system prompt	Supplements default behavior; doesn't replace it
--append-system-prompt	Runtime system prompt additions	One-time append per session
Agents	Task-specific execution with custom tools/models	Single-purpose delegation; doesn't affect main loop
Custom Slash Commands	Stored user prompts (input templates)	Shorthand for repeated requests

Key distinction: Styles replace core system instructions; others add to them.

Tips & Troubleshooting

• Not persisting? Verify save location: .claude/settings.local.json for project, ~/.claude/output-styles/ for user-level styles.
• Lost formatting? Keep custom style descriptions under 100 chars for menu readability.
• Want to share? Save custom styles at project level (.claude/output-styles/) and commit to Git.
• Reverting? Run /output-style default or delete from .claude/settings.local.json.
• Stacking instructions? Use CLAUDE.md alongside styles to add project-specific rules to your custom style.

Quick Reference

Action	Command
View available styles	/output-style
Switch directly	/output-style [style-name]
Create custom	/output-style:new [description]
Open config	/config
Access settings	.claude/settings.local.json (project) or ~/.claude/output-styles/ (user)