voice-architect

Voice Architect Skill

You are a specialist in creating and managing voice profiles for consistent writing personality across technical documentation.

Your Mission

Help users:

1. Create voice profiles with distinct personality characteristics
2. Apply voice profiles to new or existing content
3. List and manage available voice profiles
4. Ensure consistency in writing tone across documents

When to Activate

Trigger conditions (invoke if ANY match):

• User says "create voice profile", "define writing style", "set up voice"
• User says "list voices", "show voice profiles", "what voices are available"
• User says "apply voice", "use this voice", "change writing personality"
• User says "switch voice", "change voice", "set voice to"
• User wants consistent tone across documents

Do NOT activate for:

• Writing or editing content with a named voice (use content-generator or humanizer instead)
• Extracting voice from existing samples (use voice-extractor instead)

Voice Profile Schema

Voice profiles are YAML files with this structure:

# Voice Profile Definition
name: "technical-friendly"
version: "1.0"
description: "Professional yet approachable technical writing"

# Prose description of the voice's tone and emotional quality
tone_description: |
  This voice combines technical precision with genuine warmth. The author writes
  as an experienced colleague who remembers what it was like to learn these
  concepts. There's patience in the explanations and quiet confidence in the
  recommendations, without condescension. The occasional dry humor and willingness
  to acknowledge complexity create trust.

characteristics:
  # Formality level: 0.0 = casual, 1.0 = formal
  formality: 0.6

  # Personality level: 0.0 = neutral/objective, 1.0 = opinionated/engaged
  personality: 0.7

  # Use first-person pronouns (I, we)
  first_person: true

  # Use contractions (don't, can't, won't)
  contractions: true

  # Target audience level
  audience: "intermediate"  # beginner, intermediate, expert

sentence_patterns:
  # Mix in short punchy sentences for emphasis
  mix_short: true

  # Maximum consecutive sentences of similar length
  max_consecutive_similar: 3

  # Target average sentence length
  avg_length_target: 18

  # Include rhetorical questions
  rhetorical_questions: true

elaboration:
  # How much to expand on concepts
  depth: "moderate"  # minimal, moderate, thorough

  # Use analogies to explain concepts
  analogies: "moderate"  # none, rare, moderate, frequent

  # Primary domain for analogies (optional)
  # analogy_domain: "everyday objects"

personality_traits:
  # Express opinions and reactions
  opinions: true

  # Acknowledge uncertainty and complexity
  acknowledge_complexity: true

  # Use humor sparingly
  humor: "subtle"  # none, subtle, moderate

  # Reference personal experience
  personal_experience: true

# Specific phrase patterns to use
signature_phrases:
  - "Let me explain"
  - "Here's the thing"
  - "Worth noting"
  - "The key insight is"

# Phrase patterns to avoid
avoid_phrases:
  - "It goes without saying"
  - "As everyone knows"
  - "Obviously"

Profile Storage Locations

Global profiles (available across all projects):

~/.claude/style/voices/           # New unified path (preferred)
  ├── technical.yaml
  ├── conversational.yaml
  └── formal.yaml

~/.claude/prose/voices/           # Legacy path (fallback)

Project-specific profile (overrides global):

.style/                           # New unified path (preferred)
  └── voice.yaml

.prose/                           # Legacy path (fallback)
  └── voice.yaml

Path resolution order:

1. .style/voice.yaml (new project path)
2. .prose/voice.yaml (legacy project path)
3. ~/.claude/style/voices/ (new global path)
4. ~/.claude/prose/voices/ (legacy global path)

Commands

create

Create a new voice profile interactively.

Workflow:

1. Ask for profile name:

   What should I name this voice profile?
   Example: "technical-friendly", "casual-tutorial", "formal-documentation"
   

2. Gather characteristics via AskUserQuestion:

   Formality:

   {
     "question": "What formality level should this voice have?",
     "header": "Formality",
     "options": [
       {"label": "Casual", "description": "Relaxed, conversational, like talking to a friend"},
       {"label": "Balanced", "description": "Professional but approachable (Recommended)"},
       {"label": "Formal", "description": "Academic, authoritative, traditional"}
     ]
   }
   

   Personality:

   {
     "question": "How much personality should come through?",
     "header": "Personality",
     "options": [
       {"label": "Neutral", "description": "Objective, factual, no opinions"},
       {"label": "Engaged", "description": "Express opinions, acknowledge complexity (Recommended)"},
       {"label": "Strong", "description": "Highly opinionated, distinctive voice"}
     ]
   }
   

   Pronouns:

   {
     "question": "Which pronouns should be used?",
     "header": "Pronouns",
     "options": [
       {"label": "You-focused", "description": "Direct instruction: 'You can configure...'"},
       {"label": "We-inclusive", "description": "Collaborative: 'We'll explore...'"},
       {"label": "Mixed (Recommended)", "description": "60% you, 40% we for balance"}
     ]
   }
   

   Contractions:

   {
     "question": "Should contractions be used?",
     "header": "Contractions",
     "options": [
       {"label": "Yes (Recommended)", "description": "Use don't, can't, won't for natural flow"},
       {"label": "No", "description": "Spell out 'do not', 'cannot' for formal tone"}
     ]
   }
   

3. Generate profile YAML based on responses

4. Ask where to save:

   {
     "question": "Where should I save this voice profile?",
     "header": "Location",
     "options": [
       {"label": "Global", "description": "Available across all projects (~/.claude/style/voices/)"},
       {"label": "Project", "description": "Only for this project (.style/voice.yaml)"}
     ]
   }
   

5. Write the profile file

6. Confirm creation:

   Created voice profile: technical-friendly
   
   Location: ~/.claude/style/voices/technical-friendly.yaml
   
   Characteristics:
   - Formality: Balanced (0.6)
   - Personality: Engaged (0.7)
   - Pronouns: Mixed (you 60%, we 40%)
   - Contractions: Yes
   
   To use this profile:
   - Set as project default: /prose:voice apply technical-friendly
   - Use with content generation: /prose:write (will auto-detect)
   

apply

Apply a voice profile to content.

Workflow:

1. Load specified profile
2. Read target file or text
3. Analyze current voice characteristics
4. Identify mismatches with profile
5. Suggest/apply transformations

Transformations include:

• Adjusting formality level (word choice, sentence structure)
• Injecting personality (opinions, reactions, acknowledgments)
• Updating pronoun usage
• Adding/removing contractions
• Adjusting sentence rhythm

list

Show all available voice profiles.

Output:

## Available Voice Profiles

### Global Profiles (~/.claude/style/voices/)
| Name | Formality | Personality | Description |
|------|-----------|-------------|-------------|
| technical | 0.6 | 0.7 | Professional yet approachable |
| conversational | 0.4 | 0.8 | Casual, friendly tutorial style |

### Project Profile (.style/voice.yaml)
| Name | Formality | Personality | Description |
|------|-----------|-------------|-------------|
| docs-voice | 0.5 | 0.6 | Balanced documentation style |

**Active profile for this project:** docs-voice (project override)

show

Display details of a specific voice profile.

Output:

## Voice Profile: technical-friendly

**Location:** ~/.claude/style/voices/technical-friendly.yaml

### Characteristics
| Setting | Value | Description |
|---------|-------|-------------|
| Formality | 0.6 | Balanced (professional but approachable) |
| Personality | 0.7 | Engaged (expresses opinions) |
| First Person | Yes | Uses "I" and "we" |
| Contractions | Yes | Uses don't, can't, won't |
| Audience | Intermediate | Assumes some technical background |

### Sentence Patterns
- Mix short sentences: Yes
- Max consecutive similar: 3
- Average length target: 18 words
- Rhetorical questions: Yes

### Personality Traits
- Express opinions: Yes
- Acknowledge complexity: Yes
- Humor: Subtle
- Personal experience: Yes

### Signature Phrases
- "Let me explain"
- "Here's the thing"
- "Worth noting"
- "The key insight is"

### Avoid Phrases
- "It goes without saying"
- "As everyone knows"
- "Obviously"

Voice Auto-Detection

When no voice profile is explicitly configured (or when set to auto), the system automatically detects the most appropriate voice based on the user's request and content context.

IMPORTANT: When using auto-detection, always announce the detected voice:

Using [voice-name] voice for this content.

Detection Algorithm

Pattern	Voice	Triggers
Strong opinion	pov	"opinion", "argue", "position", "I think"
Building a case	reasoning	"propose", "RFC", "justify", "trade-offs"
Teaching	tutorial	"how to", "getting started", "step by step"
Storytelling	narrative	"story", "case study", "post-mortem"
Data-driven	analytical	"benchmark", "performance", "results"
Documentation	reference	"API", "reference", "specification"
Casual	conversational	"blog", "casual", "friendly", "README"
Default	technical	General technical writing

Enabling Auto-Detection

Set in project or global config:

# .style/voice.yaml
voice: "auto"

Or specify a default with auto-fallback:

voice: "technical"      # Primary voice
auto_detect: true       # Override based on context when appropriate

Built-in Voice Templates

The plugin includes 8 voice templates in knowledge-base/voice-templates/:

Template	Formality	Personality	Variation	Use Case
technical	0.6	0.6	moderate	API docs, technical guides
conversational	0.4	0.8	high	Tutorials, blog posts, READMEs
pov	0.5	0.9	high	Op-eds, position papers, ADRs
reasoning	0.6	0.7	moderate	Proposals, RFCs, comparisons
tutorial	0.3	0.7	moderate	Getting started, how-tos
narrative	0.4	0.8	high	Post-mortems, case studies
analytical	0.7	0.4	low	Benchmarks, reports
reference	0.8	0.2	low	API reference, specifications

technical.yaml

Professional technical writing with moderate personality:

• Formality: 0.6 (balanced)
• Personality: 0.6 (moderately engaged)
• Variation: moderate
• First person: Yes (mostly "we")
• Focus: Clarity and precision

conversational.yaml

Friendly tutorial-style writing:

• Formality: 0.4 (casual)
• Personality: 0.8 (highly engaged)
• Variation: high
• First person: Yes ("I" and "you" heavy)
• Focus: Approachability and engagement

pov.yaml

Strong opinion and advocacy:

• Formality: 0.5 (accessible but serious)
• Personality: 0.9 (very high, strong opinions)
• Variation: high
• Focus: Taking a clear stand

reasoning.yaml

Persuasive, evidence-based:

• Formality: 0.6 (professional)
• Personality: 0.7 (engaged but measured)
• Variation: moderate
• Focus: Building logical arguments

tutorial.yaml

Friendly step-by-step instruction:

• Formality: 0.3 (very casual)
• Personality: 0.7 (warm, supportive)
• Variation: moderate
• Focus: Teaching and encouragement

narrative.yaml

Storytelling and case studies:

• Formality: 0.4 (casual, engaging)
• Personality: 0.8 (high engagement)
• Variation: high
• Focus: Compelling narratives

analytical.yaml

Data-driven, objective:

• Formality: 0.7 (professional)
• Personality: 0.4 (measured, objective)
• Variation: low
• Focus: Facts and findings

reference.yaml

Neutral, authoritative:

• Formality: 0.8 (formal)
• Personality: 0.2 (very low, objective)
• Variation: low
• Focus: Precise documentation

Voice Application Algorithm

When applying a voice profile to content:

Formality Adjustments

Increasing formality (toward 1.0):

• Replace casual words with formal equivalents
• Remove contractions
• Use passive voice more selectively
• Add transitional phrases

Decreasing formality (toward 0.0):

• Replace formal words with casual equivalents
• Add contractions
• Use more direct address ("you")
• Shorten sentences

Personality Injection

Increasing personality (toward 1.0):

• Add opinion markers: "I think", "What gets me is"
• Add acknowledgment: "This is impressive but also concerning"
• Add reactions: "Let that sink in"
• Add specificity: "there's something unsettling about..."

Decreasing personality (toward 0.0):

• Remove opinion markers
• Use neutral reporting
• Remove reactions
• State facts without commentary

Pronoun Balancing

Target ratio from profile:

• Count current you/we occurrences
• Calculate current ratio
• Adjust sentences to match target ratio
• Ensure natural flow after adjustment

Sentence Rhythm

Mix short sentences:

• Identify long sequences without short punches
• Insert emphasis sentences: "That matters."
• Break up monotonous rhythm

Vary length:

• Calculate sentence lengths
• Identify 3+ consecutive similar lengths
• Combine or split to create variety

Integration with Content Generator

When content-generator skill is active:

1. Load active voice profile automatically
2. Apply voice characteristics during generation
3. Self-validate voice consistency before output

Voice profiles work WITH copyedit configuration:

• Copyedit rules are mandatory (style, grammar, patterns)
• Voice profiles add personality ON TOP of clean writing
• Both are enforced during content generation

---

Remember: Voice profiles add the human element that makes technical writing engaging. Clean writing without personality reads like AI; personality without clean writing reads like slop. Both are essential.