skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
boringmarketer/boring-marketing-skills110 installs

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-voice
view source ↗

Is 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

ModeWhenSignal
ExtractThey have content they're proud ofPasted content, file paths, "analyze these"
BuildNo crawlable surface exists, or existing content is deliberately being abandoned"I don't have content" AND no site/socials to mine
Auto-ScrapeA crawlable surface exists, whether or not they mentioned itURL in the message, or a domain/handle findable in brand.yaml / positioning.md / stack.md
Drift CheckSaved 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.

  1. 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").
  2. Vocabulary: signature words and coinages, banned words, jargon level and what jargon signals (peer vs seller), profanity policy.
  3. Rhythm: sentence-length distribution (the mix, not the average), paragraph shape, fragment use, where the prose speeds up and slows down.
  4. Structure: how pieces open (story / claim / question), how they transition, how they close (CTA / open loop / cold stop), formatting habits.
  5. 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?
  6. 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:

  1. Read everything once for gestalt, then once per dimension.
  2. 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.
  3. Write the profile (template below), citing exhibit IDs per the falsifiability rule.
  4. 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):

  1. 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.)
  2. 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.)
  3. Admired voices: "2-3 voices you admire (any field) and the one specific thing each does that you'd steal."
  4. Audience: "Who are you talking to, and how do THEY talk?" (Skip if audience.md already 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:

AgentSourcesMethod
WebsiteHomepage, /about, 2-3 blog postsFirecrawl map+scrape if available, else WebFetch
Social postsPublic X posts; Instagram/Facebook/LinkedIn posts ONLY via ScrapeCreatorsWeb search to locate handles. Skip login-walled hosts and label them instead of fetching them
SpokenYouTube videos and podcast appearances (transcripts)Search "{brand/founder} podcast OR youtube", fetch transcripts
NewsletterPublic 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:

  1. Load ./brand/voice-profile.md and load references/ai-tells.md.
  2. 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.
  3. 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.
  4. Separately flag AI-tell contamination: any cluster of 3+ tells from ai-tells.md in one piece, quoted.
  5. Verdict per piece and overall: aligned / drifting / off-voice.
  6. 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:

  1. Email opening: 3-4 sentences, as if to their list. Greeting style, rhythm, vocabulary, personality all live.
  2. Social post: for whichever platform the brand is most active on, using that platform's row from the adaptations table.
  3. 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:

  1. ## VOICE PROFILE: {Brand}, then one line of date and what the profile is for. No mode, data label or evidence line.
  2. 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.
  3. 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.
  4. 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
  5. 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-copy or /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.

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>