brand-voice
Extracts or builds a falsifiable brand voice profile, backed by verbatim evidence from the brand's real content, that every other content skill reads, so output sounds like the brand instead of a model. Use when starting a project, when copy sounds generic or AI-written, when output must match a specific person or brand, or to check recently published content for voice drift.
How do I install this agent skill?
npx skills add https://github.com/boringmarketer/boring-marketing-skills --skill brand-voiceIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is a brand voice analyzer and profile builder. It safely uses standard external tools (Firecrawl, Exa, WebFetch) to scrape public content for voice analysis and produces markdown-based brand profiles. No malicious patterns, obfuscation, or unauthorized access were detected.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Brand Voice
Produce a voice profile specific enough that a stranger holding only the profile writes content the brand's audience would attribute to the brand, and tight enough that every line rules something out. The judgment this skill carries: voice claims are evidence-backed and falsifiable, never horoscope; the Voice Test Loop, not interrogation, is how the profile gets accurate. The method is a floor, not a ceiling. When the content in front of you argues for a better path, take it and say why.
Context
Only if ./brand/, ./brands/ or MARKETING.md exists (nothing to load otherwise), run:
python3 ${CLAUDE_SKILL_DIR}/../start-here/scripts/brand_context.py --for brand-voice
(If the script or python3 is unavailable, read the files named in reads: directly. If
none exist, proceed standalone: ask only for what the task strictly requires.)
Positioning shapes stance (a rebel brand and a trusted-advisor brand land differently on every spectrum); audience shapes jargon tolerance and register. Use them as priors, never as substitutes for evidence.
Before writing or updating any profile, load references/voice-extraction-judgment.md.
Its falsifiability rule, exhibit-citation requirement, and competitor-paste test are
the quality bar for every line of the profile.
Modes
| Mode | When | Signal |
|---|---|---|
| Extract | They have content they're proud of | Pasted content, file paths, "analyze these" |
| Build | No crawlable surface exists, or existing content is deliberately being abandoned | "I don't have content" AND no site/socials to mine |
| Auto-Scrape | A crawlable surface exists, whether or not they mentioned it | URL in the message, or a domain/handle findable in brand.yaml / positioning.md / stack.md |
| Drift Check | Saved profile exists; they want recent content audited | "drift check," "is this still on brand," recent posts + existing profile |
Tools pick the mode (extract, don't interview): when the web-scrape capability is present, check for a crawlable surface BEFORE asking anything. The message, then brand.yaml, positioning.md, stack.md for a domain or social handles. Found one → Auto-Scrape is the first pass, even if they said "help me define my voice": crawl, extract, present the drafted profile for correction. Build's questions then fill only the gaps the corpus couldn't answer (usually the anti-model and hard lines). A person with a live website should never face an interview a crawler could have skipped.
If ./brand/voice-profile.md already exists and the request isn't Drift Check, this is
an update: read the existing profile, apply the requested change or re-extract on
new evidence, run the Voice Test Loop on what changed, then save (auto-version per
start-here/references/brand-memory.md; show a 3-line summary of what changed, with no confirmation ceremony).
If no surface is findable and the mode is still ambiguous, ask ONE question: "Do you have published content that sounds like you, or are we building from scratch? (A URL works too: I'll do the research.)"
The six dimensions
Every mode analyzes (or constructs) the same six dimensions. These are the skeleton of the profile.
- Tone: position on five spectrums: Formal↔Casual, Serious↔Playful, Reserved↔Bold, Simple↔Sophisticated, Warm↔Direct. A position is only useful with its mechanism ("casual in syntax, never in punctuation" beats "pretty casual").
- Vocabulary: signature words and coinages, banned words, jargon level and what jargon signals (peer vs seller), profanity policy.
- Rhythm: sentence-length distribution (the mix, not the average), paragraph shape, fragment use, where the prose speeds up and slows down.
- Structure: how pieces open (story / claim / question), how they transition, how they close (CTA / open loop / cold stop), formatting habits.
- Personality: the 3-4 traits that show up as observable behavior in the prose: self-deprecating about what? confident how? teacher or peer? What's the recurring move?
- POV & address: I vs we, how the reader is addressed, the relationship stance (peer slightly ahead / guide / insider / rebel).
Mode: Extract
Input: 3-5 pieces the user considers "most them": posts, emails, transcripts, pages. Under ~1,500 words total, say the corpus is too thin for reliable patterns and offer to Auto-Scrape the gaps or proceed with caveats.
Process:
- Read everything once for gestalt, then once per dimension.
- Pull verbatim exhibits (5-60 words each) as you go. Every pattern you think you see must be pinned to a quote. Target 10-20 exhibits.
- Write the profile (template below), citing exhibit IDs per the falsifiability rule.
- Run the Voice Test Loop.
What separates a good extraction from a mediocre one: the mediocre one describes what the content is ABOUT; the good one describes what the writer DOES. The repeated move, the thing they never do, the habit they probably don't know they have. If you can't name three habits the brand itself would be surprised to see articulated, read the corpus again.
Mode: Build
No corpus exists, so don't fake one with 15 questions. Most answers to voice questionnaires are aspirational noise. Ask the four that actually constrain the profile, infer everything else, and let the Voice Test Loop catch inference errors (it's cheaper for the user to react to three sample paragraphs than to answer eleven more questions):
- Identity belief: "What do you believe about your space that most competitors wouldn't say out loud?" (This becomes the spine. A voice with nothing to assert defaults to mush.)
- Anti-model: "Name a brand or creator you do NOT want to sound like. What specifically grates?" (Negative space is more diagnostic than positive aspiration.)
- Admired voices: "2-3 voices you admire (any field) and the one specific thing each does that you'd steal."
- Audience: "Who are you talking to, and how do THEY talk?" (Skip if
audience.mdalready answers it.)
Optionally, a fifth if their answers leave it genuinely open: "Any hard lines: profanity, humor, hot takes, emoji?"
Then construct: derive the spectrums from belief + anti-model, vocabulary from
admired-voice mechanics + audience language, rhythm and structure as your best inference
from the register they used answering you. Mark the profile Evidence: INTAKE (exhibits pending first published content) and cite their verbatim answers as interim exhibits.
Run the Voice Test Loop. In Build mode it's load-bearing, since the samples are the
first evidence that ever existed.
Mode: Auto-Scrape
A URL in, a profile out. The research is performed, not described: fan out parallel
subagents, one per source type, using the Task/Agent tool (general-purpose). Unless
you are already running inside an onboarding agent: then do the sources yourself, in
order, within a small research budget (depth one, no sub-agents). Launch all applicable agents in a
single parallel batch:
| Agent | Sources | Method |
|---|---|---|
| Website | Homepage, /about, 2-3 blog posts | Firecrawl map+scrape if available, else WebFetch |
| Social posts | Public X posts; Instagram/Facebook/LinkedIn posts ONLY via ScrapeCreators | Web search to locate handles. Skip login-walled hosts and label them instead of fetching them |
| Spoken | YouTube videos and podcast appearances (transcripts) | Search "{brand/founder} podcast OR youtube", fetch transcripts |
| Newsletter | Public archive (Beehiiv/Substack/site) | Locate archive, fetch 2-3 editions |
WebSearch and WebFetch cover the website, spoken and newsletter rows for free. We use Firecrawl to read the website row as clean text (free tier of 1,000 credits a month, no card) and Exa to find the spoken and newsletter sources a keyword search misses (free tier, then pay as you go). Without them, WebFetch reads pages as summaries and the Sources and assumptions note says so.
Each subagent returns a structured evidence pack, not prose:
SOURCE TYPE: {website|social|spoken|newsletter}
SOURCES: {URLs fetched, word count each}
EXHIBITS: 8-15 verbatim quotes (5-60 words), numbered, each tagged with source URL
OBSERVATIONS: per-dimension notes (tone/vocab/rhythm/structure/personality/POV),
each observation referencing exhibit numbers
GAPS: what couldn't be found
Merge step: assign global exhibit IDs (E1...En), then write the profile citing them. Weighting judgment: spoken transcripts and social posts are the real voice; website copy is often agency-written. When sources conflict, trust spoken/social and note the conflict in the profile: that note is itself useful to downstream skills. If the combined corpus is under ~1,500 words, say in one line what was found per source and fall back to Extract (ask for pasted content) or Build.
After merging, ask 2-3 gap-filling questions ONLY for what the scrape couldn't answer (usually: "anything about your current voice you want to evolve rather than preserve?" and "any loved/hated words that wouldn't show up publicly?"). Then the Voice Test Loop.
The profile file's Evidence line carries LIVE (n sources). In chat, say it once in the
Sources and assumptions note, in plain words ("Based on 6 sources, about 9,000 words, read
live on Nov 13").
Mode: Drift Check
The recurring-use mode: agencies run it weekly. Requires a saved profile; without one, say so and route to Extract/Auto-Scrape.
Input: recent published content (pasted, file paths, or URLs to fetch). 3-10 pieces is the useful range; 1 piece is a spot-check, say so.
Process:
- Load
./brand/voice-profile.mdand loadreferences/ai-tells.md. - Score each piece against the profile on all six dimensions, 1-10: 9-10 indistinguishable from the exhibits; 7-8 minor lexical drift; 5-6 noticeably off; ≤4 wouldn't be attributed to the brand.
- For every dimension below 8, quote the drifting passage NEXT TO the profile exhibit it violates. Drift claims obey the same falsifiability rule as profile claims. No "feels a bit off-brand" without the two quotes side by side.
- Separately flag AI-tell contamination: any cluster of 3+ tells from ai-tells.md in one piece, quoted.
- Verdict per piece and overall: aligned / drifting / off-voice.
- The judgment call: is the drift degradation or evolution? Consistent drift across all pieces in the same direction usually means the voice has evolved: offer to update the profile to match reality (that's an update flow, with the user's confirmation that the new direction is intentional). Scattershot drift means inconsistency. The profile stands, the content needs the correction.
Output a drift report to ./campaigns/voice-drift/{YYYY-MM-DD}-drift-report.md:
per-piece dimension scores, side-by-side drift examples, AI-tell flags, verdict,
recommended action. Chat carries the verdict, the two or three worst side-by-side examples
and the action, not the score tables.
Voice Test Loop
Default after generating or updating a profile in any mode, before saving: it's the accuracy mechanism, and cheaper than more questions. Non-interactive runs (onboarding agents) can't ask: generate the samples anyway and mark the loop pending user reaction.
Step 1. Generate three samples using only the profile you just wrote:
- Email opening: 3-4 sentences, as if to their list. Greeting style, rhythm, vocabulary, personality all live.
- Social post: for whichever platform the brand is most active on, using that platform's row from the adaptations table.
- Landing page hero: headline + subhead + 1-2 supporting sentences. The voice under direct-response pressure.
The samples must be genuinely written in the profile's voice. If they could have been written without the profile, the profile failed before the user even reacts. Run that check silently and fix the profile first; show only the samples that pass.
Step 2. Present and ask: "Does this sound like you? (1) Nails it: save. (2) Close: tell me what's off. (3) Not right: show me what's wrong."
Step 3. Process the reaction:
- Nails it → save (Output section below).
- Close → ask what specifically feels off: tone, vocabulary, rhythm, or something else. Adjust ONLY the implicated profile sections, regenerate all three samples, present again.
- Not right → ask for an example of something they've written that DOES sound right, or a specific description of the miss (too formal? too safe? trying too hard?). If they provide an example, run a focused extraction on it and rebuild the offending sections. Regenerate all three, present again.
Step 4. Iteration limit: after 3 rounds without confirmation, stop spiraling: offer to (a) save the current best (the profile improves with real use, and any skill that uses it will surface misses), (b) one more targeted round, or (c) switch modes (usually Build → Extract on a real example they trust). Present the option honestly; round 4+ of guessing rarely converges.
The voice profile (canonical format)
Saved to ./brand/voice-profile.md. Markdown is the single source of truth. No JSON
block. Every claim cites exhibits per references/voice-extraction-judgment.md. The Evidence
line, exhibit IDs and appendix live in the file, not in chat. Load
references/ai-tells.md before writing the AVOID section. It is mandatory in every
profile.
# {Brand} Voice Profile
Last updated: {YYYY-MM-DD} by /brand-voice · Mode: {mode} · Evidence: {LIVE (n sources) | INTAKE}
## Voice Summary
{2-3 sentences. What this voice feels like to encounter, and the one move that makes it recognizable.}
## Core Personality Traits
- **{Trait as observable behavior}:** {what it does in the prose} ({exhibit IDs})
{3-4 traits. Each must survive the competitor-paste test.}
## Tone Spectrum
| Dimension | Position | Mechanism + evidence |
|---|---|---|
| Formal ↔ Casual | {position} | {how it shows up} ({E-ids}) |
| Serious ↔ Playful | {position} | ... |
| Reserved ↔ Bold | {position} | ... |
| Simple ↔ Sophisticated | {position} | ... |
| Warm ↔ Direct | {position} | ... |
## Vocabulary
**Use:** {signature words/phrases, each with when-to-use} ({E-ids})
**Jargon:** {level + what jargon signals for this brand} · **Profanity:** {policy}
## AVOID ← mandatory
**Brand-specific bans:** {words/phrases this brand never uses, with why} ({E-ids or intake})
**AI tells:** {the 10-20 entries from references/ai-tells.md most likely to contaminate THIS
brand's content, listed explicitly, plus: "no uniform paragraph rhythm, no rule-of-three
runs, no em-dash chains" or whichever structural tells apply}
## Rhythm & Structure
**Sentences:** {the mix, not the average} ({E-ids})
**Paragraphs / Openings / Closings / Formatting:** {observed habits} ({E-ids})
## POV & Address
First person: {I/we/mix} · Reader: {how addressed} · Stance: {peer/guide/rebel/insider} ({E-ids})
## Platform Adaptations
| Platform | Tone shift | Structure & length notes |
|---|---|---|
| X | | |
| LinkedIn | | |
| Instagram | | |
| TikTok | | |
| YouTube | | |
| Threads | | |
| Reddit | | |
| Email | | |
## Example Phrases
**On-brand:** {2-3, drawn from or modeled on exhibits}
**Off-brand:** {2-3, each with why it's wrong}
## Evidence Appendix
| ID | Quote (verbatim) | Source |
| E1 | "..." | {URL or "intake"} |
{...all exhibits cited above}
Filling the adaptations table: judgment, not template defaults
All 8 rows are required (downstream skills, content-atomizer especially, read this table per platform). Think each row individually; a casual brand may be MORE buttoned-up on LinkedIn while a formal brand loosens on X. Channel-specific judgment:
- X: the punchiest, most opinionated version of the voice; long-form posts are standard, so define both the one-liner register and the essay register.
- LinkedIn: substance-forward; the voice survives but leads with the insight, not the personality.
- Instagram: caption voice. The personality compressed; visual carries the rest.
- TikTok / YouTube: SPOKEN voice: write for the ear, contractions and fragments natural, the hook register in the first seconds matters more than anywhere else. If spoken exhibits exist, this row leans on them.
- Threads: conversational, lower-stakes than X. The voice off-duty.
- Reddit: the voice nearly disappears; community-first, zero marketing scent, plain first-person. A brand that sounds like a brand on Reddit gets buried. Say so in the row.
- Email: warmest, most 1:1 register; the reader gave you their address, write like it.
Worked example (excerpt, neutral)
Extract mode on a fractional-CFO-for-restaurants founder: 2 site pages, 14 LinkedIn posts, 1 podcast transcript. Excerpted to show the evidence standard. A real profile completes every section:
## Voice Summary
Reads like the line cook who became the numbers guy: kitchen metaphors doing real
analytical work, margins discussed in plates and shifts, allergic to consultant-speak.
Recognizable move: translates every financial concept into a service-window decision.
## Core Personality Traits
- **Kitchen-floor credibility:** anchors abstract finance in physical restaurant work, as in
"your food cost isn't a spreadsheet problem, it's a walk-in problem" (E3); opens the
podcast with prep-shift stories, not credentials (E9).
- **Numbers without hedges:** states figures flat with no softeners ("say a 4% swing" style
illustrations, never "studies suggest") (E5, E12). Zero instances of "I think" in 14 posts.
## Tone Spectrum (excerpt)
| Formal ↔ Casual | Casual in syntax, precise in numbers | Fragments mid-argument (E2),
but figures always exact, never rounded for effect (E5) |
## AVOID (excerpt)
**Brand-specific:** "hospitality space," "P&L journey," anything that sounds like a
franchise consultant (anti-model named in intake). **AI tells:** seamless, leverage,
unlock, "it's not just X, it's Y," rule-of-three runs, uniform 2-sentence paragraphs.
Note what's NOT here: "passionate about helping restaurants," "approachable but professional". Those lines would survive in any competitor's profile, so they don't exist in this one.
Output
Per start-here/references/output-format.md:
## VOICE PROFILE: {Brand}, then one line of date and what the profile is for. No mode, data label or evidence line.- The short form: voice summary, traits, tone positions and the AVOID list, with a verbatim quote where it makes a claim concrete. Exhibit IDs, the appendix and the platform table stay in the file. For Drift Check, the verdict, worst examples and action. Budget: the profile file runs about 1,200 to 2,500 words including exhibits.
- Sources and assumptions (10 lines at most), in plain words: what the profile rests on ("6 sources, about 9,000 words, read live on Nov 13" or "built from your answers, no published content yet"), what could not be read, what to confirm. A learnings.md prior that changed the work gets one line.
- Files saved:
./brand/voice-profile.md(new or updated; the old version is auto-saved to./brand/.history/)- Drift Check:
./campaigns/voice-drift/{date}-drift-report.md(new) - Update
brand.yaml; append one line to./brand/assets.md
- What's next:
/positioning-angles: the voice now has a spine; find the angle it should argue (~10 min)/audience-research: if audience.md was missing, the jargon-level calls were inferred (~15 min)/direct-response-copyor/content-atomizer: first real use; both read this profile (~15 min)
Optional one-line ask after first real use: "When you've shipped content with this profile, tell me what felt off. One line is enough."
When the user edits your work
Apply the edit, then make it stick: save a gold case to ./brand/gold/<this skill>/ and
one to three yes/no checks to ./brand/checks.md, and confirm in one line. Before handing
over any work, answer the checks the context block loaded, silently, and fix every no.
How: ${CLAUDE_SKILL_DIR}/../start-here/references/taste-loop.md.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/boringmarketer/boring-marketing-skills/brand-voice">View brand-voice on skillZs</a>