Create Voice

Operator Context

Hardcoded Behaviors (Always Apply)

• CLAUDE.md Compliance: Read and follow repository CLAUDE.md before starting any work
• No Existing File Modification: NEVER modify voice_analyzer.py, voice_validator.py, banned-patterns.json, voice-calibrator, voice-orchestrator, or any existing skill/script. The existing tools work. This skill only creates new files in

  skills/voice-{name}/

• Wabi-Sabi Throughout: Natural imperfections are features, not bugs. This principle applies at EVERY phase, not as an afterthought. See

  skills/shared-patterns/wabi-sabi-authenticity.md

• 50-Sample Minimum: Do not proceed past Step 1 without 50+ writing samples. The system tried with 3-10 and FAILED. 50+ is where it starts working. WHY: LLMs are pattern matchers, and rules tell AI what to do but samples show AI what the voice looks like. V7-V9 had correct rules but failed authorship matching (0/5 roasters). V10 passed 5/5 because it had 100+ categorized samples.
• Deterministic Before AI: Always run script-based analysis before AI interpretation. WHY: Scripts produce reproducible, quantitative baselines. AI interpretation without data drifts toward generic patterns.
• Artifacts Over Memory: Save outputs to files at every phase. Context is ephemeral; files persist.

Default Behaviors (ON unless disabled)

• Communication Style: Report progress with phase status banners. Be direct about what passed or failed, not congratulatory
• Phase Gates: Enforce GATE checkpoints between all phases. Do not proceed if the gate condition is unmet
• Iteration Limits: Maximum 3 validation/refinement iterations before escalating to user
• Validation Pipeline: Run both

  voice_validator.py validate

  and

  voice_validator.py check-banned

  during Step 6
• Reference Loading: Show users any existing voice implementation as a concrete example of "done"

Optional Behaviors (OFF unless enabled)

• Strict Mode: Require 5/5 roaster match instead of 4/5 minimum
• Verbose Analysis: Show full voice_analyzer.py JSON output inline instead of summary
• Cross-Voice Comparison: Compare new profile against existing voice profiles
• Batch Sample Import: Automated scraping/organization of samples from a single source

What This Skill CAN Do

• Guide users through the complete 7-phase voice creation pipeline
• Organize writing samples into the correct directory structure
• Run deterministic analysis via

  scripts/voice_analyzer.py

• Identify voice patterns, phrase fingerprints, and wabi-sabi markers using AI interpretation of samples + metrics
• Generate complete voice skill files (SKILL.md, profile.json, config.json) following the voice-calibrator template
• Validate generated content against the new profile using

  scripts/voice_validator.py

• Iterate on failures with targeted fixes (max 3 iterations)

What This Skill CANNOT Do

• Generate content in a voice (use

  voice-orchestrator

  after creation)
• Modify existing voice skills or profiles (use

  voice-calibrator

  )
• Scrape writing samples from the internet automatically (user must provide samples)
• Guarantee authorship matching will pass (depends on sample quality and quantity)
• Skip deterministic analysis (scripts MUST run before AI interpretation)
• Create a voice from fewer than 50 samples (hard minimum, see Hardcoded Behaviors)

Instructions

Overview

skills/voice-{name}/references/samples/*.md

skills/voice-{name}/profile.json

skills/voice-{name}/SKILL.md

config.json

Step 1: COLLECT -- Gather 50+ Writing Samples

Where to Find Samples

reddit-samples-YYYY-MM-DD.md

hn-samples-YYYY-MM-DD.md

blog-samples.md

forum-samples-YYYY-MM-DD.md

email-samples.md

chat-samples.md

social-samples.md

Sample Quality Guidelines

• Mix of lengths: Very short (1 sentence), short (2-3 sentences), medium (paragraph), long (multi-paragraph). The distribution matters because most people write short responses most of the time.
• Mix of contexts: Technical, casual, disagreement, agreement, teaching, joking, emotional. Different contexts reveal different facets of voice.
• Mix of topics: Not all about the same subject. Topic diversity reveals stable voice patterns vs topic-specific patterns.
• DO NOT clean up samples: Typos, run-on sentences, fragments, loose punctuation ARE the voice. Cleaning destroys authenticity markers. This is the wabi-sabi principle in action at the very first step.
• DO NOT cherry-pick: Include mediocre posts alongside great ones. The mundane reveals default patterns.

Directory Setup

mkdir -p skills/voice-{name}/references/samples/

skills/voice-{name}/references/samples/

---

Sample File Format

# Reddit Samples - 2025-12-30

## r/subreddit - Thread Title
[Exact text of comment, typos and all]

---

## r/subreddit - Another Thread
[Exact text]

---

Phase 1/7: COLLECT
  Samples: {count} across {file_count} files
  Sources: {list of source types}
  GATE: {PASS if >= 50 / FAIL if < 50}

Step 2: EXTRACT -- Run Deterministic Analysis

voice_analyzer.py

Run the Analyzer

python3 ~/.claude/scripts/voice_analyzer.py analyze \
  --samples skills/voice-{name}/references/samples/*.md \
  --output skills/voice-{name}/profile.json

Also Get the Text Report

python3 ~/.claude/scripts/voice_analyzer.py analyze \
  --samples skills/voice-{name}/references/samples/*.md \
  --format text

What the Analyzer Extracts

Verify the Output

profile.json

1. Python 3 is available
2. Sample files are readable
3. File paths are correct (glob expansion can be tricky)

profile.json

sentence_metrics

punctuation_metrics

word_metrics

structure_metrics

Phase 2/7: EXTRACT
  Profile: skills/voice-{name}/profile.json
  Samples analyzed: {N}
  Total words: {N}
  Total sentences: {N}
  Average sentence length: {X} words
  GATE: {PASS/FAIL}

Step 3: PATTERN -- Identify Voice Patterns (AI-Assisted)

Phrase Fingerprints (CRITICAL)

• Signature openers: How do they start responses? ("I think the issue is...", "So basically...", "Here's what I've found...")
• Signature closers: How do they end? ("but we'll see", "does that help?", "anyway, that's my take")
• Filler phrases: Verbal tics that appear across contexts ("For what it's worth", "to be fair", "honestly")
• Hedging patterns: How they express uncertainty ("probably", "I suspect", "my guess is")
• Emphasis patterns: How they stress a point ("the key thing is", "the part people miss")

Thinking Patterns

• Concede-then-assert: "That's fair, but..." (acknowledges opposing view, then states own position)
• Hypothesis-experiment: "My theory is... I tried... and found..."
• Systems framing: "The way this works is..." (explains mechanisms, not just opinions)
• Experience-based: "In my experience..." (grounds claims in personal observation)
• Question-led: "The question is..." (frames issues as questions to investigate)
• Analogy-driven: Uses metaphors and comparisons from specific domains

Response Length Distribution

• Very short (1 sentence): ____%
• Short (2-3 sentences): ____%
• Medium (4-6 sentences): ____%
• Long (paragraph+): ____%

Natural Typos (Authenticity Markers)

• Missing apostrophes ("dont" instead of "don't")
• Common word swaps ("there" for "their")
• Dropped letters ("probabl" for "probably")
• Double-typed characters ("tthe")
• Missing spaces after punctuation ("works.But")

Wabi-Sabi Markers

• Run-on sentences: Does this person chain clauses with commas?
• Fragments: Do they use sentence fragments for emphasis?
• Loose punctuation: Is comma usage inconsistent? Is that part of the texture?
• Self-corrections: Do they change direction mid-sentence? ("Well, actually..." or "I mean,")
• Tangential asides: Do they go on tangents? (Parenthetical digressions?)

Linguistic Architectures

• Direction: Inductive (examples → conclusion) vs deductive (claim → evidence) vs mixed? Where does the main claim appear relative to supporting evidence?
• Escalation: Do stakes increase through the piece? Narrow → broad? Low → high severity?
• Ending reframe: Does the ending restate the opening, or transform it into something new?

• Structure: Short admission → pivot? Long qualification → reversal? Never concedes?
• Pivot markers: Which words signal the turn? ("but", "though", "the thing is", "and yet", "that said")
• Position: Where do concessions appear? Opening? Mid-argument? Never at the end?

• Source domains: Which fields? (cooking, construction, sports, warfare, nature, machinery, music, software, etc.)
• Deployment: Are analogies used to open? To explain mid-section? To close with a memorable image?
• Density: Every post? Rarely? Only for technical concepts?

• Opening moves: Question? Declarative claim? Anecdote? Provocation? Scene-setting?
• Closing moves: Reframe? Fragment punch? Circle back to opening? Call to action? Open question?
• Symmetry: Does the closing echo or answer the opening?

Phase 3/7: PATTERN
  Phrase fingerprints: {count}
  Thinking patterns: {count}
  Linguistic architectures: {count}/4 documented
  Length distribution: {very short}% / {short}% / {medium}% / {long}%
  Natural typos: {count}
  Wabi-sabi markers: {list}
  GATE: {PASS/FAIL}

Step 4: RULE -- Build Voice Rules

What This Voice IS (Positive Identity)

• "subtly" skeptical not "skeptical" -- dampens the trait so it appears naturally, not performatively
• "generally" conversational not "conversational" -- allows for variation
• "slightly" self-deprecating not "self-deprecating" -- prevents over-application

What This Voice IS NOT (Contrastive Identity)

Hard Prohibitions

• Em-dashes: Does this person ever use them? If not, FORBIDDEN
• Formal transitions: "However", "Furthermore", "Moreover", "Additionally", "Consequently"
• AI-typical phrases: "Let's dive in", "Here's the thing", "delve", "robust", "leverage", "ecosystem"
• The "It's not X. It's Y" pattern: Signature AI structure. Almost always prohibited
• Excessive hedging: "It's worth noting", "One might argue", "At the end of the day"

Wabi-Sabi Rules

• If they write run-on sentences: "Allow comma-chain sentences up to {N} words when expressing enthusiasm or building arguments"
• If they use fragments: "Target {X}% fragment rate for emphasis and pacing"
• If punctuation is loose: "Do not standardize comma usage; match the inconsistent pattern from samples"
• If they self-correct: "Include at least one visible direction change per long-form response"

Anti-Essay Patterns

• Staccato rhythm? (Short sentences dominating)
• No signposting? (No "First... Second... Third...")
• Single-sentence paragraphs? (Common in chat/forum)
• No introduction/conclusion structure? (Just starts talking)
• Abrupt endings? (No wrap-up, just stops)

Architectural Patterns

## Architectural Patterns

## Architectural Patterns

### Argument Flow
[Inductive/Deductive/Mixed] — [one-sentence description]
Build arguments by [specific instruction]. The main claim should appear [position].
Example from samples: "[exact quote showing the pattern]"

### Concessions
Structure: [short admission → pivot / long qualification → reversal / never concedes]
Pivot markers: [list of words this voice uses]
Example: "[exact quote]"

### Analogy Domains
Primary: [domain1, domain2]
Deployment: [where analogies appear — openers? mid-section? closers?]
Density: [frequency]
**NEVER draw analogies from**: [domains this voice avoids]
Example: "[exact quote]"

### Bookends
Opening move: [pattern]
Closing move: [pattern]
Symmetry: [yes/no/sometimes]
Example opening: "[quote]"
Example closing: "[quote]"

Phase 4/7: RULE
  Positive traits: {count} (with dampening)
  Contrastive aspects: {count}
  Hard prohibitions: {count}
  Wabi-sabi rules: {count}
  Anti-essay patterns: {list}
  Architectural patterns: {count}
  GATE: {PASS/FAIL}

Step 5: GENERATE -- Create the Voice Skill

pipelines/voice-calibrator/SKILL.md

Files to Create

1. skills/voice-{name}/SKILL.md

   -- The voice skill itself (2000+ lines)

2. skills/voice-{name}/config.json

   -- Validation configuration

3. skills/voice-{name}/profile.json

   -- Already created in Step 2

SKILL.md Structure

SKILL.md Frontmatter

---
name: voice-{name}
user-invocable: false
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
  - Skill
description: |
  Apply {Name}'s voice profile for content generation: [2-3 key traits],
  and modal writing. Use when generating content that must match {Name}'s
  distinctive voice. Do NOT use for voice analysis, voice profile creation,
  or generating content in other voices.
version: 1.0.0
command: /voice-{name}
---

SKILL.md Operator Context

• Hardcoded Behaviors: CLAUDE.md compliance, voice fidelity, wabi-sabi principle, data integrity (never modify curated content)
• Default Behaviors: Voice validation via script, em-dash prohibition (if applicable), mode selection
• Optional Behaviors: Strict mode, A/B testing

Sample Organization (THE MOST IMPORTANT SECTION)

• Very short (1 sentence, ~{X}% of responses): Include 10+ samples
• Short (2-3 sentences, ~{X}% of responses): Include 15+ samples
• Medium (4-6 sentences, ~{X}% of responses): Include 10+ samples
• Long (paragraph+, ~{X}% of responses): Include 5+ samples

• Admitting Mistakes: 5+ samples
• Acknowledging Limits: 5+ samples
• Respectful Disagreement: 5+ samples
• Technical Expertise (delivered casually): 5+ samples
• Strong Opinions (unhedged): 5+ samples
• Casual Closers: 5+ samples
• Sarcasm/Wit (if applicable): examples

Voice Metrics Section

| Metric | Target | Tolerance | Notes |
|--------|--------|-----------|-------|
| Average sentence length | {X} words | +/- 2 words | Primary rhythm indicator |
| Short sentences (3-10 words) | {X}% | +/- 5% | For emphasis and pacing |

Two-Layer Architecture

• Layer A (Always-On Base Voice): Core traits, sentence rhythm, punctuation signature, contraction rate, function word signature. These apply to ALL content regardless of mode.
• Layer B (Mode-Specific Overlays): Different modes (e.g., technical, casual, opinion, review) that adjust tone, formality, and structure while keeping Layer A constant.

Prompt Engineering Techniques (Apply Throughout)

1. Probability Dampening: Use "subtly", "slightly", "generally" before traits. WHY: Without dampening, the model cranks traits to 100%
2. Attention Anchoring: Bold all negative constraints. WHY: The model pays more attention to formatted text
3. XML Context Tags: Use

   <context type="static-instructions">

   for directives and

   <context type="safety-guardrails">

   for prohibitions. WHY: Structured tags signal instruction priority to the model
4. Few-Shot Examples: Include 3+ examples for every prohibition (especially "It's not X. It's Y"). WHY: Rules without examples are abstract; examples are concrete
5. Contrastive Pairs: For every "DO" include a "DON'T" with concrete text. WHY: The model needs to see both sides of the boundary

config.json

{
  "name": "{Name}",
  "version": "1.0.0",
  "description": "{Brief voice description}",
  "modes": ["technical", "casual", "opinion"],
  "validation": {
    "strict_banned_patterns": true,
    "em_dash_forbidden": true,
    "metric_tolerance": 0.20,
    "required_checks": ["banned_phrases", "punctuation", "rhythm"],
    "optional_checks": ["metrics", "sentence_starters", "opening_pattern"]
  },
  "thresholds": {
    "pass_score": 70,
    "error_max": 0,
    "warning_max": 3
  },
  "voice_specific_patterns": []
}

em_dash_forbidden

modes

pass_score

SKILL.md

config.json

Phase 5/7: GENERATE
  SKILL.md: {line_count} lines
  Samples section: {line_count} lines
  config.json: created
  Template sections: {present_count}/{required_count}
  GATE: {PASS/FAIL}

Step 6: VALIDATE -- Test Against Profile

Generate Test Content

1. A short response (2-3 sentences) to a casual prompt
2. A medium response (paragraph) to a technical question
3. A long response (multi-paragraph) to an opinion question

Run Validation

python3 ~/.claude/scripts/voice_validator.py validate \
  --content /tmp/voice-test-{name}-{N}.md \
  --profile skills/voice-{name}/profile.json \
  --voice {name} \
  --format text \
  --verbose

Run Banned Pattern Check

python3 ~/.claude/scripts/voice_validator.py check-banned \
  --content /tmp/voice-test-{name}-{N}.md \
  --voice {name}

Interpret Results

If Validation Fails

1. Read the violation report carefully
2. Identify the top 3 violations by severity
3. For each violation, determine if it's:
   • A real problem (AI phrase, wrong structure) -- fix in SKILL.md rules or add more samples
   • A false positive (natural imperfection flagged as error) -- adjust config.json thresholds
4. Make targeted fixes (one at a time, not wholesale rewrites)
5. Regenerate test content and revalidate
6. Maximum 3 iterations

Phase 6/7: VALIDATE
  Test 1 (short): {score}/100 - {PASS/FAIL}
  Test 2 (medium): {score}/100 - {PASS/FAIL}
  Test 3 (long): {score}/100 - {PASS/FAIL}
  Banned patterns: {CLEAN/violations found}
  Iterations: {N}/3
  GATE: {PASS/FAIL}

Step 7: ITERATE -- Refine Until Authentic

The Authorship Matching Test

1. Select 3-5 original writing samples that were NOT included in the SKILL.md (hold-out samples)
2. Generate 3-5 new pieces using the voice skill on similar topics
3. Present both sets (mixed, unlabeled) to 5 "roasters" (people familiar with the original voice)
4. Ask each roaster: "Were these written by the same person?"
5. Target: 4/5 roasters say "SAME AUTHOR"

If Authorship Matching Fails

The V10 Lesson

• V1-V6: Incremental rule improvement. Modest gains.
• V7-V9: Rules were correct but authorship matching failed 0/5. The voice had the right CONSTRAINTS but not enough EXAMPLES.
• V10: Added 100+ samples organized by pattern. Passed 5/5.

Wabi-Sabi Final Check

• Generated content contains natural imperfections from the samples (not manufactured imperfections)
• Run-on sentences appear at approximately the same rate as in the original samples
• Fragments appear for emphasis, matching sample patterns
• Typos from the natural typos list appear occasionally (not forced)
• Content does NOT read like polished professional writing (unless the original voice IS polished)
• If content is too perfect, the skill needs MORE samples and LOOSER constraints, not fewer

Phase 7/7: ITERATE
  Authorship match: {X}/5 roasters
  Iterations completed: {N}
  Final validation score: {X}/100
  GATE: {PASS/FAIL}

Final Output

===============================================================
 VOICE CREATION COMPLETE: {name}
===============================================================
 Files created:
   skills/voice-{name}/SKILL.md              (voice skill)
   skills/voice-{name}/profile.json          (metrics)
   skills/voice-{name}/config.json           (validation config)
   skills/voice-{name}/references/samples/   (organized samples)

 Validation: {PASSED/FAILED} (score: {X}/100)
 Authorship Match: {X}/5 roasters
===============================================================

Error Handling

Error: "Insufficient samples" (< 50)

1. Count current samples and report the gap
2. Suggest specific sources based on what's already provided (e.g., "You have 20 Reddit comments. Try also pulling from HN history, blog posts, or email")
3. Do NOT proceed past Step 1. The system does not work with fewer than 50 samples.

Error: "voice_analyzer.py fails"

1. Check Python 3 is available:

   python3 --version

2. Check script exists:

   ls scripts/voice_analyzer.py

3. Check file paths: Glob expansion may not work as expected in all shells. Try listing files first:

   ls skills/voice-{name}/references/samples/*.md

4. Try with explicit file list instead of glob:

   --samples file1.md file2.md file3.md

Error: "Validation score too low" (< 50 after 3 iterations)

1. Check if profile.json metrics are achievable (some metrics from small sample sets may be skewed)
2. Review banned patterns for false positives specific to this voice
3. Consider relaxing

   metric_tolerance

   in config.json from 0.20 to 0.25
4. Check if the SKILL.md has enough samples (the answer is usually: add more samples)
5. Manual review of SKILL.md instructions for contradictory rules

Error: "Authorship matching fails" (< 4/5 roasters)

Error: "SKILL.md too short" (< 2000 lines)

1. Check that all sample categories are populated (length-based AND pattern-based)
2. Verify all template sections are present
3. Add more samples -- they are the bulk of the line count
4. Do NOT pad with verbose rules. The goal is 2000+ lines of USEFUL content, primarily samples.

Error: "Wabi-sabi violations flagged as errors"

skills/shared-patterns/wabi-sabi-authenticity.md

Anti-Patterns

Do Not Clean Up Samples

Do Not Skip Deterministic Analysis

Do Not Over-Rule, Under-Sample

Do Not Manufacture Imperfections

Do Not Skip Authorship Matching

Anti-Rationalization

Reference Implementations

skills/voice-*/

skills/voice-{name}/SKILL.md

skills/voice-{name}/references/samples/

skills/voice-{name}/config.json

skills/voice-{name}/profile.json

/create-voice

Components This Skill Delegates To

scripts/voice_analyzer.py analyze

scripts/voice_analyzer.py compare

scripts/voice_validator.py validate

scripts/voice_validator.py check-banned

scripts/data/banned-patterns.json

pipelines/voice-calibrator/SKILL.md

skills/shared-patterns/wabi-sabi-authenticity.md