# Voice Engine Skill

How to build your own **Voice Architecture Engine** as a [Claude Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) — so AI output sounds like *you*, not like generic AI.

## Why this matters

Left alone, every LLM defaults to the same flattened "AI voice": hedged, over-qualified, heavy on em-dashes and "furthermore," allergic to a strong opinion. That's not neutral — it's a specific style, and it erases yours.

Your voice is an asset. It's the thing readers recognize before they finish the first sentence, the reason your writing gets attributed to you even when it's unsigned. If you let AI tools write for you without mapping that voice first, you're trading a real asset for convenience.

A voice skill is how you keep authorship at scale: you do the mapping once, structure it as a skill, and every AI-assisted draft after that starts from *your* defaults instead of the model's defaults. You're not asking the AI to "sound more human" — you're handing it a spec.

This repo walks through the five steps to build one, with a full worked example for an invented persona so you can copy the pattern without needing access to anyone's real corpus.

## Step 1 — Collect your corpus

You can't map a voice you haven't gathered. Pull raw text from every place you've actually written or spoken, unscripted:

- **Tweets / X archive** — request your own archive from X's settings (Settings → Your Account → Download an archive). This gives you a `tweets.js` file with everything you've posted, unedited by anyone else.
- **YouTube transcripts of your own videos** — use [yt-dlp](https://github.com/yt-dlp/yt-dlp) to pull audio, then [whisper.cpp](https://github.com/ggml-org/whisper.cpp) (or OpenAI's [Whisper](https://github.com/openai/whisper)) to transcribe it locally. Spoken voice is often closer to your real cadence than anything you've edited.
- **Notes app / private notes** — unfiltered first-draft thinking, before you've smoothed it for an audience.
- **Emails you wrote** — especially ones you wrote fast, under real stakes, not templated replies.
- **Podcast transcripts** — interviews or solo episodes where you were talking, not reading.

Practical extraction commands:

```bash
# Pull audio-only from your own YouTube video (use a URL you own/have rights to)
yt-dlp -x --audio-format mp3 -o "corpus/%(title)s.%(ext)s" "https://youtube.com/watch?v=YOUR_VIDEO_ID"

# Transcribe locally with whisper.cpp (after building it per its README)
./whisper-cli -m models/ggml-base.en.bin -f corpus/your-video.mp3 -otxt -of corpus/your-video

# Or with the Python Whisper package
whisper corpus/your-video.mp3 --model base --output_format txt --output_dir corpus/
```

For your X archive: unzip the downloaded archive, then extract just the tweet text from `data/tweets.js` (it's JSON wrapped in a JS variable assignment — strip the `window.YTD.tweets.part0 = ` prefix and parse the rest as JSON).

Aim for volume and range: formal and casual, written and spoken, short posts and long-form. The more contexts you cover, the more the skill can generalize instead of just memorizing one register.

## Step 2 — Map the dimensions

Once you have raw corpus, read through it and score yourself across concrete, checkable dimensions. Don't guess — pull actual sentences as evidence for each one.

- **Vocabulary register + signature phrases** — words/phrases you reach for repeatedly that aren't generic ("in other words" vs. your actual verbal tic).
- **Sentence rhythm** — do you alternate short punchy sentences with longer winding ones? Do you front-load the claim or build to it?
- **Rhetorical defaults** — do you ask rhetorical questions? Callback to something said earlier in the piece? Address the reader directly ("you")?
- **Code-switching contexts** — how does your register shift between, say, a technical explanation and a personal story?
- **Metaphor domains** — what field do your comparisons come from (sports, cooking, construction, nature, systems)? This is one of the most identifying signals in anyone's writing.
- **Forbidden words** — words or phrases you would never say, including generic AI tells ("delve," "tapestry," "in today's fast-paced world," excessive em-dashes).
- **Openers/closers** — how do you typically start and end a piece? Cold open with a claim? Ease in with context? Land on a question or a directive?

### Worked example — invented persona "Mara Voss," a fictional productivity coach

This is a made-up voice for illustration only — not a real person, not 19Keys' voice.

| Dimension | Mara Voss's pattern |
|---|---|
| Vocabulary register | Plain, blue-collar-adjacent even when the topic is abstract. Says "the actual work" instead of "execution." Signature phrase: "here's the boring part." |
| Sentence rhythm | Short declarative opener, then one longer sentence unpacking it, then a short landing line. Rarely more than two commas per sentence. |
| Rhetorical defaults | Frequently asks "so what do you do instead?" — sets up a question, then answers it herself two lines later. Rarely addresses reader as "you" in the opener; switches to "you" once she's made the claim. |
| Code-switching | Formal/structured in written guides (numbered steps), much looser and profanity-adjacent ("this is dumb, but it works") in transcript-style spoken content. |
| Metaphor domains | Construction and cooking — "load-bearing habit," "you're not seasoning a system that isn't built yet." |
| Forbidden words | "leverage," "synergy," "unlock," "journey," "delve," any sentence starting with "In today's world." |
| Openers | Cold claim, no throat-clearing: "Motivation is a bad plan." Never opens with a question. |
| Closers | One-line directive, present tense, no summary recap: "Go do the boring part." |

## Step 3 — Write the skill

Turn the dimension map into an actual [Claude Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) — a `SKILL.md` file with YAML frontmatter (name + description with trigger conditions) and structured sections the model can follow like a spec.

The complete annotated template, filled in for the Mara Voss example, lives at [`examples/my-voice/SKILL.md`](examples/my-voice/SKILL.md) in this repo. Copy that file's structure, replace every section with your own mapped dimensions from Step 2, and you have a working voice skill.

Key sections any voice skill needs:

- **Frontmatter** — `name` and a `description` that states *when* the skill should trigger (e.g., "any public-facing writing," "X posts only," "long-form only").
- **Voice DNA** — the condensed dimension table from Step 2.
- **Signature moves** — 3-5 concrete, reusable patterns (a phrase, a structure, a rhetorical habit).
- **Forbidden list** — words, phrases, and structures to actively avoid. This section does the most work — see Step 4.
- **Before/after rewrite examples** — at least 2-3 pairs showing a generic-AI sentence next to the voice-corrected version, so the model has direct pattern matches, not just abstract rules.

## Step 4 — Test and iterate

1. Generate the same piece of content twice from the same prompt: once with the skill active, once without.
2. Diff both against a real sample of your actual writing (not a piece you wrote *for* this test — something from your corpus). Look for which one shares more sentence-rhythm and word-choice patterns with the real sample.
3. Wherever the "with skill" output still slips into generic AI patterns, add the specific offending word or structure to the forbidden list.
4. Repeat. In practice, **tightening the forbidden list does more work than adding new positive instructions** — it's easier for a model to reliably avoid five banned words than to reliably imitate a subtle rhythm. Get the negative space right first, then refine the positive examples.

## Step 5 — Use it everywhere

A voice skill only pays off if it's actually in the loop:

- Reference it from your `CLAUDE.md` (or equivalent project instructions file) so any Claude Code session in that repo picks it up automatically for writing tasks.
- Wire it into content pipelines — anywhere a script or automation calls the [Claude API](https://docs.claude.com/en/api/overview) to generate copy, point that call at the skill instead of a bare prompt.
- Re-run Step 4 periodically. Your voice drifts over time (new phrases, new topics) — treat the skill file as a living document, not a one-time export.

## What's in this repo

```
voice-engine-skill/
├── README.md                    - this guide
├── SETUP.md                     - what you need to use this repo
├── .gitignore
└── examples/
    └── my-voice/
        └── SKILL.md              - full worked example skill (invented persona)
```

## Further reading

- [Claude Agent Skills overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
- [Anthropic skill-creator skill](https://github.com/anthropics/skills) (Anthropic's own skill-authoring tooling)
- [yt-dlp](https://github.com/yt-dlp/yt-dlp)
- [whisper.cpp](https://github.com/ggml-org/whisper.cpp)
- [OpenAI Whisper](https://github.com/openai/whisper)