Interpretive guidance for Claude Code output styles - when they add value, when they don't, and how they relate to agents. Use when considering output styles or wondering if your workflow would benefit from them.
/plugin marketplace add racurry/neat-little-package/plugin install box-factory@neat-little-packageThis skill inherits all available tools. When active, it can use any tool Claude has access to.
This skill helps you understand when output styles actually add value. The key insight most people miss: output styles affect the main Claude Code conversation, not your agents. If you're already using agents for specialized tasks, output styles might not add anything.
Prerequisites: Load the box-factory-architecture skill for component selection context.
Core insight: Output styles modify the main Claude Code session prompt. They do NOT affect agents, which have their own isolated prompts. Most confusion about output styles stems from misunderstanding this separation.
Fetch official documentation with WebFetch:
| If you need to... | Go to... |
|---|---|
| Understand output styles vs agents | Critical Architecture Understanding |
| Decide if you need an output style | Decision Framework |
| See when output styles help | When Output Styles Actually Help |
| See when they don't help | When Output Styles Don't Help |
| Create a custom output style | Custom Style Design |
| Identify common mistakes | Common Pitfalls |
This is the most important thing to understand:
Output styles → Affect main Claude Code session (where you type)
Agents → Have their own isolated prompts (defined in agent files)
What this means practically:
Common misconception: "Should I use an output style for my code review agent?"
Reality: Your agent already has a prompt that defines its behavior. Output styles are irrelevant to agents.
Output styles modify the system prompt for the main conversation. When you delegate to an agent via the Task tool, that agent:
Scenario: You're exploring an unfamiliar codebase and want Claude to explain what it finds.
What it does: Adds "Insights" sections explaining:
When to use:
Switch: /output-style explanatory
Scenario: You want to build skills by doing, not just watching Claude work.
What it does:
TODO(human) markersWhen to use:
Switch: /output-style learning
Scenario: You're using Claude Code's file system capabilities for non-coding work.
What it does: Removes software engineering assumptions entirely.
Example domains:
Critical: For these, keep-coding-instructions: false (the default) is correct.
Scenario: You want a consistent personality across an entire work session.
What it does: Changes interaction patterns for everything, not just specific tasks.
Examples:
Key distinction: This affects ALL interactions in the session, not isolated tasks.
Scenario: You have agents for code review, writing, testing, etc.
Why styles don't help: Your agents already have focused prompts. The main conversation just delegates and integrates results.
Example: Box Factory plugins - the skill-writer, sub-agent-writer, validation-agent all have their own prompts. Adding an output style to the main session doesn't change how those agents behave.
Scenario: You want Claude to follow team coding standards, understand project structure, use specific tools.
Better alternative: CLAUDE.md
Why: CLAUDE.md is always loaded, team-shareable via git, and adds context without changing personality. It works WITH the default software engineering mode, not against it.
Scenario: You want to ensure tests run before commits, linting passes, certain files aren't modified.
Better alternative: Hooks
Why: Hooks can actually block operations (exit code 2). Output styles are just personality suggestions that can be overridden. You can't enforce with personality.
Scenario: Writing code, fixing bugs, refactoring, typical development.
Why default is optimal: The default output style IS the software engineering system prompt. It's already optimized for this. Adding a coding-focused output style is redundant.
Ask these questions:
1. Am I doing software engineering?
2. Do I need personality change or just context?
3. Is this for the whole session or specific tasks?
4. Do I need enforcement or just guidance?
5. Am I already delegating to agents?
| Style | Purpose | Use When |
|---|---|---|
| Default | Software engineering | Normal development work |
| Explanatory | Educational insights | Learning codebases, onboarding |
| Learning | Deliberate practice | Building skills, pair programming |
---
name: Style Display Name
description: Brief description for /output-style menu
keep-coding-instructions: false
---
# Persona
[Specific personality, expertise, approach]
## Interaction Patterns
[How to communicate, what to emphasize]
## Constraints
[Boundaries of the role]
~/.claude/output-styles/[style-name].md.claude/output-styles/[style-name].mdkeep-coding-instructions Toggletrue = Coding specialist variant (TDD expert, debugging coach)false = Non-engineering domain (content, research, analysis)Default is false - meaning engineering assumptions are removed.
Problem: Creating output style for specialized task
---
name: Security Reviewer
---
Focus on security vulnerabilities, OWASP top 10...
Why it fails: This is a task, not a personality. It pollutes your main session with security focus even when doing other work.
Better: Create a security-reviewer agent with Read-only tools.
Problem: Using output style for project context
---
name: Our Project
---
Use React 18, follow ESLint config, run tests before commits.
Why it fails: This is context, not personality. It replaces the engineering system prompt when you want to augment it.
Better: Put in CLAUDE.md, keep default style.
Problem: Trying to enforce with personality
---
name: Safe Mode
---
NEVER modify production files. ALWAYS run tests first.
Why it fails: Claude can still be convinced to override. No actual enforcement.
Better: Use PreToolUse hooks that exit 2 on violations.
Problem: Thinking agents need output styles
Reality: Agents have their own prompts. They don't use or inherit output styles. If you want different agent behavior, modify the agent's system prompt, not the session's output style.
Question: Would any Box Factory agents benefit from output styles?
Answer: No, and here's why:
skill-writer has its own prompt about skill designsub-agent-writer has its own prompt about agent patternsvalidation-agent has its own prompt about validation rulescomponent-reviewer has its own prompt about review criteriaThese agents operate in isolated contexts with focused instructions. The main conversation delegates to them and integrates results. Output styles only affect the main conversation, which is doing software engineering work (writing/managing Claude Code components) - exactly what the default style is optimized for.
When output styles WOULD help for Box Factory work:
Output styles are for session-level personality transformation.
They're most valuable when:
They're NOT valuable when:
The honest assessment: Most developers doing software engineering get the most value from the default style + CLAUDE.md + agents. Output styles shine for learning, onboarding, and non-engineering domains.
Before creating or using output styles:
Need Assessment:
Custom Style Design (if creating):
keep-coding-instructions set appropriately (true for coding variants, false for non-engineering)