Output Styles

Adapt Claude Code's behavior for different tasks by switching system prompt styles. Output styles completely replace Claude's default software engineering prompt with specialized instructions, enabling everything from educational mentoring to custom domain-specific assistance.

Official Documentation: Claude Code Output Styles

Built-in Styles

• Default - Standard software engineering mode with scripts, TODOs, and development workflows. Use for coding tasks, debugging, and implementation work.
• Explanatory - Adds educational "Insights" sections explaining implementation choices and design decisions. Use when learning new concepts or understanding why code works a certain way.
• Learning - Collaborative mode with "Insights" plus TODO(human) markers indicating where you should contribute. Use for pair programming and hands-on skill development.

Usage

Switch to a different style:

/output-style                    # Show current style and options
/output-style explanatory       # Switch to explanatory style
/output-style learning          # Switch to learning style

Create custom styles for specialized tasks:

/output-style:new I want an output style that focuses on security reviews

Example: How Styles Change Behavior

Request: "Add user authentication with password hashing"

Default Style:

export class AuthService {
  async authenticate(email: string, password: string) {
    const user = await this.userRepo.findByEmail(email);
    if (!user) throw new UnauthorizedError();
    const valid = await bcrypt.compare(password, user.passwordHash);
    if (!valid) throw new UnauthorizedError();
    return this.generateToken(user);
  }
}

Explanatory Style:

export class AuthService {
  async authenticate(email: string, password: string) {
    const user = await this.userRepo.findByEmail(email);
    if (!user) throw new UnauthorizedError();
    const valid = await bcrypt.compare(password, user.passwordHash);
    if (!valid) throw new UnauthorizedError();
    return this.generateToken(user);
  }
}

**Insights**: Uses bcrypt for password hashing - designed to be slow and computationally expensive, making brute force attacks impractical. The salt is automatically generated and stored with the hash.

Learning Style:

export class AuthService {
  async authenticate(email: string, password: string) {
    const user = await this.userRepo.findByEmail(email);
    if (!user) throw new UnauthorizedError();
    const valid = await bcrypt.compare(password, user.passwordHash);
    if (!valid) throw new UnauthorizedError();
    return this.generateToken(user);
  }
  // TODO(human): Add rate limiting to prevent brute force attacks
  // TODO(human): Configure session management and token expiration
}

**Insights**: Authentication requires multiple security layers. You'll need to add rate limiting (try express-rate-limit) and configure session management with account lockout.

Custom Styles

Create specialized styles for unique use cases:

1. Run /output-style:new with a description of desired behavior
2. Custom styles are saved as markdown files with YAML frontmatter
3. Available locations:
   • Project-level: .claude/output-styles/
   • User-level: ~/.claude/output-styles/

Plugins can also ship output styles via an output-styles/ directory in the plugin.

Integration

Persistence: Your selected style is saved per project in .claude/settings.local.json and persists across sessions.

Interactions with other features:

• Works alongside plan mode and slash commands
• CLAUDE.md files still apply within your chosen style
• Custom instructions and project context remain active

Key distinction: Output styles completely replace the system prompt, while CLAUDE.md and --append-system-prompt add to it. Think of styles as "stored system prompts" vs custom slash commands.

Related

• Memory System - Combine output styles with persistent project context
• Context Management - Control information flow for better outputs
• Prompting Techniques - Craft better prompts within your chosen style
• Using Subagents - Apply output styles to specialized agents