Project 21: Custom Output Style - Technical Writing Assistant
Project 21: Custom Output Style - Technical Writing Assistant
Transform Claude into a specialized technical writing assistant with formal documentation output, RFC-style proposals, ASCII diagrams, and TODO markers for human review.
Quick Reference
| Attribute | Value |
|---|---|
| Difficulty | Intermediate (Level 2) |
| Time Estimate | 1 week |
| Language | Markdown (with YAML frontmatter) |
| Prerequisites | Understanding of prompt engineering, documentation writing, basic Claude Code usage |
| Key Topics | Output styles, system prompts, technical writing, behavior customization |
| Claude Code Features | Output Styles, --output-style flag, keep-coding-instructions |
1. Learning Objectives
By completing this project, you will:
- Master output style fundamentals: Understand how output styles replace parts of Claude’s system prompt to fundamentally change behavior
- Design effective style specifications: Learn to write clear, actionable instructions that shape AI output consistently
- Balance constraints with flexibility: Find the sweet spot between overly rigid formatting and unpredictable output
- Implement technical writing standards: Apply formal documentation practices to AI-assisted writing
- Test and iterate on style behavior: Develop methods for verifying that your output style produces consistent, expected results
- Understand keep-coding-instructions: Know when to preserve Claude’s coding abilities vs. fully replacing behavior
2. Deep Theoretical Foundation
2.1 What Are Output Styles?
Output styles are Claude Code’s most powerful customization mechanism. Unlike CLAUDE.md (which adds context to every interaction) or hooks (which run code before/after prompts), output styles replace parts of Claude’s core system prompt.
THE CUSTOMIZATION HIERARCHY
┌────────────────────────────────────────────────────────────────┐
│ CLAUDE'S BEHAVIOR │
├────────────────────────────────────────────────────────────────┤
│ │
│ 1. SYSTEM PROMPT (Claude's core personality and rules) │
│ │ │
│ │ ┌─────────────────────────────────────────────────────┐ │
│ │ │ OUTPUT STYLE │ │
│ │ │ │ │
│ │ │ Replaces or augments parts of the system prompt │ │
│ │ │ to change fundamental behavior: tone, format, │ │
│ │ │ what to include, what to avoid │ │
│ │ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 2. CLAUDE.md (Project-specific context and instructions) │
│ │ │
│ ▼ │
│ 3. HOOKS (Pre/post processing of prompts and responses) │
│ │ │
│ ▼ │
│ 4. USER PROMPT (The actual question or request) │
│ │
└────────────────────────────────────────────────────────────────┘
Key Insight: Output styles don’t just “add instructions.” They can completely redefine how Claude approaches every interaction. This is the difference between:
- CLAUDE.md: “When documenting code, use JSDoc format.”
- Output Style: “You are a technical writer. All output must be formal documentation following RFC structure with numbered sections.”
2.2 The Anatomy of an Output Style
Output styles are Markdown files with YAML frontmatter:
---
name: style-name
description: What this style does
keep-coding-instructions: true/false
---
# The Style Body
[Instructions that replace or augment Claude's behavior]
Frontmatter Fields:
| Field | Required | Purpose |
|---|---|---|
name |
Yes | Identifier used with --output-style flag |
description |
No | Human-readable explanation |
keep-coding-instructions |
No | Whether to preserve Claude’s coding abilities |
The Markdown Body: This is where you define Claude’s new behavior. Everything you write here shapes how Claude responds.
2.3 Understanding keep-coding-instructions
The keep-coding-instructions flag is crucial for coding-related styles:
keep-coding-instructions BEHAVIOR
┌─────────────────────────────────────────────────────────────────┐
│ │
│ keep-coding-instructions: false (default) │
│ ──────────────────────────────────────── │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Claude's Default │ => │ Your Style Only │ │
│ │ System Prompt │ │ │ │
│ │ (including code │ │ (no inherent │ │
│ │ editing rules) │ │ code abilities) │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
│ Use for: Pure writing, creative tasks, non-coding contexts │
│ │
├─────────────────────────────────────────────────────────────────┤
│ │
│ keep-coding-instructions: true │
│ ────────────────────────────── │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Claude's Coding │ + │ Your Style │ │
│ │ Instructions │ │ Instructions │ │
│ │ (file editing, │ │ │ │
│ │ tool usage) │ │ (tone, format, │ │
│ │ │ │ behavior) │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
│ Use for: Coding styles, documentation styles, review styles │
│ │
└─────────────────────────────────────────────────────────────────┘
Rule of Thumb: If your style should work with code editing, set keep-coding-instructions: true.
2.4 Technical Writing Principles
From “Docs for Developers” (Bhatti et al.), effective technical documentation has these characteristics:
1. Structure and Navigation
DOCUMENTATION STRUCTURE
┌────────────────────────────────────────────────────────────────┐
│ 1. TITLE │
│ Clear, descriptive, includes the subject │
│ │
│ 2. ABSTRACT/SUMMARY │
│ 2-3 sentences answering "what is this about?" │
│ │
│ 3. OVERVIEW │
│ Context: why does this exist? What problem does it solve? │
│ │
│ 4. BODY (Numbered Sections) │
│ 4.1 Component/Concept 1 │
│ 4.1.1 Detail │
│ 4.1.2 Detail │
│ 4.2 Component/Concept 2 │
│ ... │
│ │
│ 5. DIAGRAMS │
│ Visual representation of architecture/flow │
│ │
│ 6. REFERENCES │
│ Links, citations, related documents │
└────────────────────────────────────────────────────────────────┘
2. Tone and Voice
| Do | Don’t |
|---|---|
| Use third person (“The system provides…”) | Use first person (“I think…”) |
| Avoid contractions (“do not”) | Use contractions (“don’t”) |
| Be precise and unambiguous | Be vague or use colloquialisms |
| Use active voice when possible | Overuse passive voice |
| Define technical terms | Assume all readers understand jargon |
3. Visual Elements
Technical documentation benefits enormously from visual aids:
ASCII DIAGRAM EXAMPLE
┌─────────────────────────────────────────────────────────────┐
│ System Architecture │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Client │─────▶│ API │─────▶│ Database │ │
│ │ │ │ Server │ │ │ │
│ └──────────┘ └────┬─────┘ └──────────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ Cache │ │
│ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
2.5 RFC-Style Document Structure
Request for Comments (RFC) documents have influenced technical writing standards for decades. Key elements include:
RFC DOCUMENT STRUCTURE
┌────────────────────────────────────────────────────────────────┐
│ │
│ HEADER │
│ ────── │
│ Title: [Document Title] │
│ Author: [Author Name] │
│ Status: [Draft/Proposed/Approved] │
│ Date: [YYYY-MM-DD] │
│ │
│ ABSTRACT │
│ ──────── │
│ [2-3 paragraph summary of the proposal] │
│ │
│ TABLE OF CONTENTS │
│ ───────────────── │
│ 1. Introduction │
│ 2. Background │
│ 3. Proposal │
│ 4. Security Considerations │
│ 5. References │
│ │
│ 1. INTRODUCTION │
│ ───────────────── │
│ [Problem statement and motivation] │
│ │
│ 2. BACKGROUND │
│ ────────────── │
│ [Context and prior art] │
│ │
│ 3. PROPOSAL │
│ ─────────── │
│ 3.1 Overview │
│ 3.2 Design │
│ 3.3 Implementation Notes │
│ │
│ 4. SECURITY CONSIDERATIONS │
│ ────────────────────────── │
│ [Always include, even if "None"] │
│ │
│ 5. REFERENCES │
│ ───────────── │
│ [Cited documents and standards] │
│ │
└────────────────────────────────────────────────────────────────┘
2.6 The TODO Marker Pattern
TODO markers serve as “handoff points” between AI-generated content and human review:
## Security Considerations
The authentication module uses industry-standard JWT tokens.
TODO(human): Review token expiration policy with security team.
Token storage follows browser security best practices.
TODO(security): Audit XSS vulnerability surface.
TODO Marker Types:
| Marker | Meaning |
|---|---|
TODO(human) |
Requires human review/decision |
TODO(security) |
Security team should review |
TODO(verify) |
Fact-check this claim |
TODO(example) |
Add concrete example |
TODO(diagram) |
Add visual representation |
3. The Core Question You’re Answering
“How do I fundamentally change Claude’s behavior and output format for specialized use cases?”
Output styles are the answer. Unlike configuration files or context injection, output styles change how Claude thinks, not just what it knows.
4. Concepts You Must Understand First
Stop and research these before coding:
4.1 Output Style Format
- What YAML frontmatter fields are required?
- What does the markdown body control?
- Where are output styles stored (
~/.claude/output-styles/)? - How do you activate a style (
--output-style name)?
Reference: Claude Code Documentation - “Output Styles”
4.2 The keep-coding-instructions Flag
- What does
keep-coding-instructions: truepreserve? - When should you set it to
false? - What happens if you don’t specify it?
Reference: Claude Code Documentation - Output Styles
4.3 Prompt Engineering for Behavior Change
- How specific should instructions be?
- What’s the difference between rules and guidelines?
- How do you test for consistency?
Reference: “Prompt Engineering Guide” by DAIR.AI
4.4 Technical Writing Standards
- What makes documentation “technical”?
- How does RFC structure work?
- When are diagrams necessary?
Reference: “Docs for Developers” by Bhatti et al., Chapters 2-4
5. Questions to Guide Your Design
Before implementing, think through these:
5.1 What Behavior Should Change?
- Tone: Formal vs. casual? Third person vs. first person?
- Format: Numbered sections? Specific heading structure?
- Required Elements: Diagrams? TODOs? References?
- Prohibited Elements: Emojis? Contractions? Personal opinions?
5.2 What Should Stay the Same?
- Tool usage (file editing, searching)?
- Code generation abilities?
- Context awareness?
5.3 How to Test the Style?
- What sample prompts will verify behavior?
- How do you test edge cases?
- What consistency checks should you run?
6. Thinking Exercise
Design Your Output Style Specification
Before writing code, sketch out what your style should do:
---
name: tech-writer
description: Technical writing assistant with formal documentation style
keep-coding-instructions: true # Why this choice?
---
# Technical Writing Assistant
## Tone and Voice
- [What tone to use?]
- [What voice (first/second/third person)?]
- [What to avoid?]
## Output Format
- [What structure to follow?]
- [Required sections?]
- [Numbering scheme?]
## Always Include
- [What elements are mandatory?]
## Never Do
- [What to prohibit?]
Design Questions:
- Should
keep-coding-instructionsbetrueorfalsefor a technical writer?- Consider: Will this style be used in coding contexts?
- How detailed should format instructions be?
- Too vague: “Use good structure”
- Too rigid: “Section 1 must have exactly 3 subsections”
- Just right: “Use numbered sections with clear hierarchy”
- What makes technical writing “technical”?
- Precision over personality
- Structure over flow
- Completeness over brevity
7. Real World Outcome
7.1 Example Session
$ claude --output-style tech-writer
You: Document the authentication module
Claude: [Using tech-writer output style]
# Authentication Module - Technical Specification
## Abstract
This document describes the authentication module, its architecture,
and implementation details. TODO(human): Add version and date.
## 1. Overview
The authentication module provides secure user identity verification
using industry-standard protocols.
┌─────────────────────────────────────────────┐
│ Authentication Flow │
├─────────────────────────────────────────────┤
│ │
│ Client ──► Login Form ──► Auth Service │
│ │ │
│ ▼ │
│ Token Generator │
│ │ │
│ ▼ │
│ Client ◄── JWT Token ◄── Response │
│ │
└─────────────────────────────────────────────┘
## 2. Components
### 2.1 Token Service
The Token Service generates and validates JSON Web Tokens (JWT).
It supports the following operations:
- Token generation with configurable expiration
- Token validation and refresh
- Revocation list management
TODO(security): Review token signing algorithm choice.
### 2.2 Session Manager
The Session Manager maintains active user sessions in Redis.
### 2.3 Password Handler
Password hashing uses bcrypt with a configurable work factor.
TODO(human): Confirm work factor meets security requirements.
## 3. Security Considerations
- All tokens are signed using RS256
- Passwords are never stored in plaintext
- Session tokens expire after 24 hours
TODO(security): Add rate limiting documentation.
## 4. References
- RFC 7519 - JSON Web Token (JWT)
- OWASP Authentication Cheatsheet
7.2 Contrast: Without the Style
$ claude
You: Document the authentication module
Claude: Here's an overview of the authentication module!
The auth module handles user login. When someone logs in, we check their
password and give them a token. Pretty straightforward!
Key features:
- JWT tokens for sessions
- bcrypt for passwords
- Redis for session storage
Let me know if you want more details on any part!
Notice the difference:
- With style: Formal, structured, includes diagrams, TODO markers
- Without style: Casual, unstructured, no diagrams, no review markers
8. The Interview Questions They’ll Ask
- “How would you customize an AI assistant’s output for specific use cases?”
- Discuss the spectrum from configuration to style replacement
- Explain when each approach is appropriate
- “What’s the difference between output styles and system prompts?”
- Output styles ARE system prompt modifications
- They provide a user-controllable layer
- “How do you balance constraints with flexibility in AI behavior?”
- Rules must be specific enough to enforce but general enough to apply
- Examples help more than abstract rules
- “How would you test that an output style works correctly?”
- Consistent sample prompts
- Edge case testing
- Before/after comparisons
- “What happens when output styles conflict with other instructions?”
- Priority hierarchy: system prompt > output style > CLAUDE.md > user prompt
- Conflicts should be resolved by specificity
9. Hints in Layers
Hint 1: Start Simple
Create a minimal output style with just tone changes:
---
name: tech-writer
description: Technical documentation style
keep-coding-instructions: true
---
Use formal, third-person voice. Avoid contractions.
Test this before adding more complexity.
Hint 2: Use keep-coding-instructions: true
For any style that will be used in coding contexts, preserve Claude’s code editing abilities.
Hint 3: Be Specific About Format
Instead of:
Use formal tone.
Write:
## Tone and Voice
- Use third person ("The system provides..." not "I provide...")
- Avoid contractions ("do not" instead of "don't")
- Cite sources when making claims
- Never use emojis or casual expressions
Hint 4: Add Examples
Claude follows examples better than abstract rules:
## Example Output Format
### Good (follow this):
"The authentication module provides secure identity verification.
It supports JWT tokens with configurable expiration."
### Bad (avoid this):
"So basically the auth stuff handles logins and it's pretty cool!
We use JWTs which are tokens that expire."
10. Complete Implementation
10.1 The Full Output Style File
Create this file at ~/.claude/output-styles/tech-writer.md:
---
name: tech-writer
description: Technical writing assistant producing formal documentation with diagrams and TODO markers
keep-coding-instructions: true
---
# Technical Writing Assistant
You are a technical writing assistant. Your role is to help create clear,
structured technical documentation following industry standards.
## Tone and Voice
- Use formal, third-person voice throughout
- Avoid contractions (use "do not" instead of "don't")
- Be precise and unambiguous in all statements
- Use active voice when possible ("The system validates..." not "Validation is performed...")
- Never use casual language, slang, or colloquialisms
- Do not use emojis under any circumstances
## Output Format
All documentation MUST follow this structure:
1. **Title** - Clear, descriptive title that includes the subject
2. **Abstract** - 2-3 sentence summary of the document's content
3. **Overview** - Context, purpose, and scope
4. **Body** - Numbered sections (1, 2, 3...) with subsections (1.1, 1.2...)
5. **Diagrams** - ASCII diagrams for any architectural or flow concepts
6. **References** - If applicable, links and citations
## Always Include
- At least one ASCII diagram when documenting any architectural or process concept
- `TODO(human)` markers where human review or decision is needed
- `TODO(security)` markers for security-sensitive sections
- Section numbers for navigation (1. Introduction, 1.1 Background, etc.)
- Clear headings and subheadings with hierarchy
## Diagram Format
Use ASCII box-drawing characters for diagrams:
┌─────────────┐ ┌─────────────┐ │ Component │────▶│ Component │ └─────────────┘ └─────────────┘
Arrows: ──▶ (right), ◀── (left), │ (vertical), ▼ (down), ▲ (up)
Boxes: ┌ ┐ └ ┘ (corners), ─ (horizontal), │ (vertical)
## Never Do
- Use casual language or slang
- Skip diagrams for architectural topics
- Leave sections without meaningful content
- Use first person ("I think...", "I recommend...")
- Make unsubstantiated claims without TODO markers
- Use bullet points where numbered lists are more appropriate
- Write paragraphs longer than 5 sentences without a break
## Example: Good Documentation
### Title: Authentication Module - Technical Specification
### Abstract
This document describes the authentication module architecture,
its core components, and security considerations.
### 1. Overview
The authentication module provides identity verification for the application.
It implements OAuth 2.0 and supports multiple identity providers.
### 2. Architecture
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Client │────▶│ Auth Server │────▶│ Database │ └──────────────┘ └──────┬───────┘ └──────────────┘ │ ▼ ┌──────────────┐ │ Token Store │ └──────────────┘
TODO(human): Verify architecture matches current implementation.
10.2 Testing Your Style
Create a test file at ~/.claude/test-tech-writer.md:
# Test Prompts for tech-writer Style
## Test 1: Basic Documentation
Prompt: "Document the user registration flow"
Expected: Formal tone, numbered sections, flow diagram, TODO markers
## Test 2: Code Documentation
Prompt: "Document this function: async function validateToken(token)"
Expected: Preserves code formatting, adds formal documentation structure
## Test 3: Architecture Description
Prompt: "Describe the microservices architecture of an e-commerce platform"
Expected: ASCII diagram, numbered sections, component descriptions
## Test 4: Edge Case - Casual Request
Prompt: "hey can you just give me a quick overview of REST APIs?"
Expected: Still produces formal documentation, ignores casual tone of request
## Test 5: Security Topic
Prompt: "Document the security model for user authentication"
Expected: TODO(security) markers, formal security considerations section
10.3 Using the Style
# Activate the style
claude --output-style tech-writer
# Or set as default in settings
claude config set output-style tech-writer
11. Books That Will Help
| Topic | Book | Chapter/Section |
|---|---|---|
| Technical writing fundamentals | “Docs for Developers” by Bhatti et al. | Ch. 2-4: Writing, Structure, Editing |
| Prompt engineering | “Prompt Engineering Guide” by DAIR.AI | All sections |
| Documentation style | “The Chicago Manual of Style” | Ch. 5: Grammar and Usage |
| API documentation | “REST API Design Rulebook” by Mark Masse | Ch. 6: Documentation |
| System prompt design | “Building LLM Apps” by Valentino Gagliardi | Ch. 4: Prompt Design |
12. Common Pitfalls and Solutions
| Pitfall | Symptom | Solution |
|---|---|---|
| Style too vague | Output inconsistent | Add specific examples and explicit rules |
| Style too rigid | Can’t handle edge cases | Use “prefer” instead of “must” for non-critical rules |
| Forgot keep-coding-instructions | Claude can’t edit code | Set keep-coding-instructions: true |
| Conflicting rules | Unpredictable behavior | Review rules for contradictions |
| No examples | Claude interprets differently | Add before/after examples |
13. Self-Assessment Checklist
Understanding Verification
- I can explain what output styles replace in Claude’s behavior
- I understand when to use
keep-coding-instructions: truevsfalse - I can describe the YAML frontmatter format
- I know where output style files are stored
- I understand the priority hierarchy of Claude’s instructions
Implementation Verification
- My output style produces consistently formal documentation
- ASCII diagrams appear for architectural topics
- TODO markers are included where appropriate
- Code editing still works (if keep-coding-instructions is true)
- The style handles edge cases gracefully
Integration Verification
- I can activate my style with
--output-style - The style works across different types of prompts
- I have tested with the verification prompts
14. Extensions and Challenges
14.1 Beginner Extensions
- Add support for different document types (API docs, tutorials, guides)
- Create a variation for blog post writing
- Add a reviewer mode that suggests improvements to existing docs
14.2 Intermediate Extensions
- Create multiple related styles (tech-writer-concise, tech-writer-verbose)
- Add language/localization support
- Integrate with spell-checking or grammar tools via hooks
14.3 Advanced Extensions
- Build a style that generates documentation from code comments
- Create a style that follows a specific company’s documentation standards
- Combine with hooks to auto-validate documentation format
15. Completion Criteria
Minimum Viable Completion
- Output style file created with correct frontmatter
- Formal tone is consistently applied
- Basic structure (title, sections) is enforced
- Style activates without errors
Full Completion
- ASCII diagrams appear for architectural topics
- TODO markers are included appropriately
- All five test prompts pass
- Documentation matches the examples shown
keep-coding-instructions: truepreserves code editing
Excellence (Going Above and Beyond)
- Created variations for different contexts
- Built comprehensive test suite
- Documented edge cases and limitations
- Contributed style to team or community
This guide was expanded from CLAUDE_CODE_MASTERY_40_PROJECTS.md. For the complete learning path, see the README.