claude-output-styles

Claude Code Output Styles

Guide for the native Claude Code output style feature and for applying the same response-contract pattern to agents, slash commands, teams, and skills.

Two Things This Skill Covers

1. The Claude Code feature: a session-level system prompt modification selected via /config, shipped as Markdown files, optionally bundled in plugins.
2. The pattern: a reusable response-format contract authored once and referenced from agents, commands, teams, or skills when consistent, parseable output is needed.

The feature affects the main agent loop only. The pattern is portable to anywhere a system prompt or instruction block is authored.

Part 1: The Claude Code Feature

What Output Styles Do

Output styles modify Claude Code's system prompt at session start. They can:

• Replace the default software-engineering instructions with a different role/tone/format
• Preserve core capabilities (file I/O, running scripts, TODO tracking)
• Keep or remove coding-specific instructions via keep-coding-instructions

Output styles are always active once selected, for the whole session. They are set at session start — changes take effect next session so prompt caching stays stable.

Built-In Styles

Custom Style File Format

---
name: My Custom Style
description: A brief description shown in the /config picker
keep-coding-instructions: false
---

# Custom Style Instructions

You are an interactive CLI tool that helps users with [domain].

## Specific Behaviors

- Respond in [tone]
- Structure output as [format]
- When [condition], do [action]

Frontmatter Fields

Set keep-coding-instructions: true when the custom style augments coding behavior rather than replacing it.

File Locations

Project-level resolution is not one flat path — it loads from every .claude/output-styles/ between the working directory and the repository root. When more than one of these nested directories defines a style with the same name, Claude Code uses the one closest to the working directory.

Selecting a Style

• Interactive: /config → Output style → pick from menu
• Direct: edit outputStyle in .claude/settings.local.json:

{
  "outputStyle": "Explanatory"
}

Selection is written to .claude/settings.local.json at the local project level.

Shipping Output Styles in a Plugin

Place style files under <plugin-root>/output-styles/. They are discovered when the plugin is installed and appear alongside built-in and user styles in /config.

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
└── output-styles/
    ├── terse-reviewer.md
    └── verbose-tutor.md

No additional plugin.json field is required — the output-styles/ directory is discovered by convention.

Token Usage Considerations

• Output styles add to the input token count via system prompt expansion, but prompt caching amortizes this after the first request per session
• Built-in Explanatory and Learning styles produce longer output by design — higher output token cost
• Custom styles' output cost is driven by what the instructions ask Claude to produce

Part 2: The Pattern — Response Contracts for Agents, Commands, and Teams

The shape of an output style — a set of instructions controlling response format, tone, and structure — is portable. You can apply the same pattern anywhere a system prompt or instruction block is authored.

Important: Subagents Do Not Inherit Output Style

The session-level output style modifies the main agent loop's system prompt. It does not propagate to:

• Subagents spawned via the Agent tool
• Slash command execution contexts
• Skills loaded within a subagent

If you need a subagent to produce output in a specific shape, encode the contract in the agent's own definition or reference a shared contract file.

Exception: forks. A fork (Agent tool with subagent_type: "fork") is not an independent subagent — it's a continuation of the same conversation, so it inherits the parent's full system prompt, output style included. Regular subagents (any other subagent_type) still do not inherit it.

Where to Place a Contract

Why Standardize Worker Output

When a team lead spawns multiple workers and must parse their results, inconsistent output shapes force the lead to write bespoke parsing for each worker. A shared contract lets the lead:

• Extract specific fields (e.g., PR_URL, STATUS) with one parser
• Filter worker reports for pass/fail without reading prose
• Compare two workers' results reliably

Writing a Contract

A contract specifies:

• Sections the response must contain (fixed headings)
• Field formats inside sections (literal strings, enums, lengths)
• What must not appear (e.g., no prose preamble, no trailing summaries)

Use imperative language. Example contract body:

Respond using exactly these sections, in this order:

## SUMMARY
One sentence describing what was done. No preamble.

## EVIDENCE
Verbatim output from `mise run ci`. Paste the tail if too long,
marked with `[truncated]`.

## STATUS
One of: `passed` | `failed` | `blocked`.

## NEXT
One sentence — what the team lead should do with this report.

Do not add sections. Do not summarize at the end.

Referencing a Shared Contract

From an agent definition:

---
name: ci-validator
description: Runs mise run ci and returns a structured report
---

# CI Validator

Run `mise run ci`. Report using the contract in
`assets/contracts/ci-evidence-format.md` — copy the section headings
exactly.

From a team prompt template (pseudocode):

Spawn worker with prompt:
  "Fix the failing test in src/foo.ex.
   Report using {{contract: worker-report-format}}."

When to Use a Contract vs. an Output Style

Output Styles vs. Related Features

Anti-Fabrication

Do not fabricate output-style behavior or frontmatter fields not documented at https://code.claude.com/docs/en/output-styles. When authoring contracts, verify referenced files exist with Read or Glob before claiming they do. Do not claim an agent honors the session output style — it does not. For the full anti-fabrication ruleset, see core:anti-fabrication.

Common Pitfalls

• Assuming subagents inherit the style. They do not. Encode the contract in the agent definition.
• Editing outputStyle and expecting mid-session effect. Output style is fixed at session start for cache stability.
• Mixing session persona and agent response format. A session-level output style for a reviewer persona is not the right tool for "all my workers must emit structured reports."
• Over-constraining. A contract that dictates every word produces fragile output across model versions. Specify structure, not phrasing.
• Missing keep-coding-instructions. Custom styles default to stripping coding instructions — if the style is meant to augment coding, set this to true.

Assets

Reference response-format contracts in assets/:

• assets/worker-report-format.md — structured report for team workers (SUMMARY / EVIDENCE / STATUS / NEXT)
• assets/ci-evidence-format.md — verbatim CI-output contract for validation agents
• assets/review-findings-format.md — findings-list contract for code review agents

Copy, reference, or adapt these when defining agents, commands, or team workers.

References

• Claude Code Output Styles: https://code.claude.com/docs/en/output-styles
• Claude Code Plugins Reference: https://code.claude.com/docs/en/plugins-reference
• Settings: https://code.claude.com/docs/en/settings
• CLAUDE.md memory: https://code.claude.com/docs/en/memory