output-style-authoring

This skill is part of the authoring skill family:

• agent-authoring - Guide for creating agents
• skill-authoring - Guide for creating skills
• output-style-authoring - Guide for creating output styles (this skill)

For validation, use the corresponding audit skills:

• audit-output-style - Validate output-style configurations
• audit-coordinator - Comprehensive multi-faceted audits

New to output-styles? Start with [minimal-template.md](minimal-template.md)—a 40-line baseline.

System prompts that transform Claude into specialized personas. They modify behavior, personality, and approach for an entire session while keeping all tools available.

Use when:

• Transforming into different roles (writer, analyst, teacher)
• Changing response style for entire session
• Non-engineering use cases need different behavior
• Want persistent personality change

Don't use when: Need tool restrictions or separate context (use Agent or Skill instead)

See [design-principles.md](design-principles.md) for deep dive.

1. Transform WHO, not HOW - Define persona and approach, not rigid processes
2. Start at 40-60 lines - Add complexity only when proven necessary
3. Choose strength wisely - Most should be Active, not Passive or Dominant (see [persona-strength-spectrum.md](persona-strength-spectrum.md))

Required:

• YAML frontmatter with name and description
• Clear persona definition
• Concrete behavioral directives

Optional:

• keep-coding-instructions: true/false (default: false)
• Output format specification
• Boundaries (what you don't do)

Location:

• User: ~/.claude/output-styles/style-name.md (just you)
• Project: .claude/output-styles/style-name.md (whole team)

Patterns: See [design-patterns.md](design-patterns.md) for Role Transformation, Teaching Mode, Specialized Professional, and Quality/Audit templates.

Prefer starting with [minimal-template.md](minimal-template.md) and customizing.

Step 1: Define Role

• What persona should Claude adopt?
• Is this engineering-related? (determines keep-coding-instructions)
• Does similar style exist? (/output-style to list)
• Use AskUserQuestion if unclear

Step 2: Choose Scope

• User (~/.claude/output-styles/): Just you, all projects
• Project (.claude/output-styles/): Whole team, in git

Step 3: Decide Coding Instructions

• keep-coding-instructions: false - Non-engineering roles (writer, teacher, analyst)
• keep-coding-instructions: true - Engineering roles (security, DevOps, QA)
• Default: false

Step 4: Write Persona

Good: "You are a technical writer focused on clarity and accessibility."

Bad: "You help write documentation." (too vague)

Include WHO Claude is, primary goal, and key differentiators.

Step 5: Define Behaviors

Use concrete directives, not adjectives.

Good: "1. Start with why it matters 2. Use examples within 3 paragraphs 3. Define terms on first use"

Bad: "Be helpful and explanatory" (doesn't change behavior)

See [anti-patterns.md](anti-patterns.md) #7 for more on this.

Step 6: Write Description

200-400 chars, explains what + when to use

Good: "Clear, beginner-friendly documentation with examples"

Bad: "Helps with writing" (too vague)

Step 7: Create File

• Filename: style-name.md (lowercase-with-hyphens)
• Location: ~/.claude/output-styles/ or .claude/output-styles/
• Use [minimal-template.md](minimal-template.md) as starting point

Step 8: Test

Activate with /output-style style-name and verify:

1. Appears in menu
2. Behavior changes noticeably
3. Adds value to session
4. Test mid-session deactivation (shouldn't break conversation)

See [when-to-use-what.md](../../references/when-to-use-what.md) for complete guide.

Quick:

• Output-Style: Transform behavior for entire session (writer, analyst, teacher)
• Agent: Separate context with tool restrictions
• Skill: Conditional knowledge, auto-triggers

See [anti-patterns.md](anti-patterns.md) for full diagnostic checklist.

Common smells:

1. Persona vs process blur - Specifying HOW to execute, not WHO Claude is
2. Over 100 lines - Likely over-built; audit each section
3. Reads like user checklist - Instructions for user, not Claude's behavior
4. Mid-session removal breaks conversation - Too invasive
5. Trying to restrict tools - Can't enforce; use Agent/Skill instead

Quick tests:

• Can you describe persona in one sentence?
• Would mid-session deactivation break conversation?
• Is this WHO or HOW? (should be WHO)

• [minimal-template.md](minimal-template.md) - Start here (40-line baseline)
• [complete-examples.md](complete-examples.md) - Production examples
• [persona-strength-spectrum.md](persona-strength-spectrum.md) - Passive/Active/Dominant modes
• [anti-patterns.md](anti-patterns.md) - Warning signs and recovery

• [ ] Clear role/persona
• [ ] User or project scope
• [ ] keep-coding-instructions decision
• [ ] Concrete behaviors (not adjectives)
• [ ] 40-80 lines (justify if longer)
• [ ] Test activation and deactivation
• [ ] Refine based on usage