# Brand Voice

> Tone of voice бренда: описание, проверка контента на соответствие, стайлгайд. Триггеры: «brand voice», «проверь на соответствие бренду».

- Skill: `jhamidun/brand-voice` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jhamidun/brand-voice`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jhamidun/brand-voice/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: JHamidun (https://skillmd.com/u/jhamidun)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jhamidun/brand-voice

---


# Brand Voice Skill

Frameworks for documenting, applying, and enforcing brand voice and style guidelines across marketing content.

## Brand Voice Documentation Framework

A complete brand voice document should cover these areas. Use this framework to help users define their brand voice or to understand an existing brand voice configuration.

### 1. Brand Personality
Define the brand as if it were a person. What are its defining traits?

Example: "If our brand were a person, they would be a knowledgeable colleague who explains complex things simply, celebrates your wins genuinely, and never talks down to you."

### 2. Voice Attributes
Select 3-5 attributes that define how the brand communicates. Each attribute should be defined with:
- What it means in practice
- What it does NOT mean (to prevent misinterpretation)
- An example demonstrating the attribute

### 3. Audience Awareness
- Who the brand is speaking to (primary and secondary audiences)
- What the audience cares about
- What level of expertise the audience has
- How the audience expects to be addressed

### 4. Core Messaging Pillars
- 3-5 key themes the brand consistently communicates
- The hierarchy of these messages (which comes first)
- How each pillar connects to audience needs

### 5. Tone Spectrum
How the voice adapts across contexts while remaining recognizably the same brand.

### 6. Style Rules
Specific grammar, formatting, and language rules. See the Style Guide Enforcement section below.

### 7. Terminology
Preferred and avoided terms. See the Terminology Management section below.

## Voice Attributes

### Common Voice Attribute Pairs

When defining brand voice, it helps to position attributes on a spectrum. Here are common attribute spectrums:

| Spectrum | One End | Other End |
|----------|---------|-----------|
| Formality | Formal, institutional | Casual, conversational |
| Authority | Expert, authoritative | Peer-level, collaborative |
| Emotion | Warm, empathetic | Direct, matter-of-fact |
| Complexity | Technical, precise | Simple, accessible |
| Energy | Bold, energetic | Calm, measured |
| Humor | Playful, witty | Serious, earnest |
| Innovation | Cutting-edge, forward-looking | Established, proven |

### Defining an Attribute

For each chosen attribute, document it in this format:

**[Attribute name]**
- **We are**: [what this means in practice]
- **We are not**: [common misinterpretation to avoid]
- **This sounds like**: [example sentence demonstrating the attribute]
- **This does NOT sound like**: [example sentence violating the attribute]

Example:

**Approachable**
- **We are**: friendly, clear, jargon-free, welcoming to beginners and experts alike
- **We are not**: dumbed-down, overly casual, or lacking substance
- **This sounds like**: "Here's how to get started — it takes about five minutes."
- **This does NOT sound like**: "Yo! This is super easy, even a noob can do it lol."

## Tone Adaptation Across Channels and Contexts

The brand voice stays consistent, but tone adapts to context. Tone is the emotional inflection applied to the voice.

### Tone by Channel

| Channel | Tone Adaptation | Example |
|---------|----------------|---------|
| Blog | Informative, conversational, educational | "Let's walk through how this works and why it matters for your team." |
| Social media (LinkedIn) | Professional, thought-provoking, concise | "Three things we learned from running 50 campaigns this quarter." |
| Social media (Twitter/X) | Punchy, direct, sometimes witty | "Your landing page has 3 seconds. Make them count." |
| Email marketing | Personal, helpful, action-oriented | "We put together something we think you'll find useful." |
| Sales collateral | Confident, benefit-driven, specific | "Teams using our platform reduce reporting time by 40%." |
| Support/Help docs | Clear, patient, step-by-step | "If you see this error, here's how to fix it." |
| Press release | Formal, factual, newsworthy | "The company today announced the launch of..." |
| Error messages | Empathetic, helpful, blame-free | "Something went wrong on our end. We're looking into it." |

### Tone by Situation

| Situation | Tone Adaptation |
|-----------|----------------|
| Product launch | Excited, confident, forward-looking |
| Incident or outage | Transparent, empathetic, accountable |
| Customer success story | Celebratory, specific, crediting the customer |
| Thought leadership | Authoritative, nuanced, evidence-based |
| Onboarding | Welcoming, encouraging, clear |
| Bad news (price increase, deprecation) | Honest, respectful, solution-oriented |
| Competitive comparison | Confident but fair, fact-based, not disparaging |

### Tone Adaptation Rule
The voice attributes remain fixed. Tone dials them up or down based on context. For example, if a brand is "bold and warm":
- In a product launch, dial up boldness
- In an incident response, dial up warmth
- Neither attribute disappears; the balance shifts

## Style Guide Enforcement

### Grammar and Mechanics
Document and enforce these choices consistently:

| Rule | Options | Example |
|------|---------|---------|
| Oxford comma | Yes / No | "fast, reliable, and secure" vs. "fast, reliable and secure" |
| Sentence case vs. title case (headings) | Sentence / Title | "How to get started" vs. "How to Get Started" |
| Contractions | Use / Avoid | "we're" vs. "we are" |
| Em dash spacing | No spaces / Spaces | "this—and more" vs. "this — and more" |
| Numbers | Spell out 1-9, numerals 10+ / Always numerals | "five features" vs. "5 features" |
| Percent | % / percent | "50%" vs. "50 percent" |
| Date format | Month DD, YYYY / DD/MM/YYYY / etc. | "January 15, 2025" |
| Time format | 12-hour / 24-hour | "3:00 PM" vs. "15:00" |
| Lists | Periods / No periods on fragments | "Set up your account." vs. "Set up your account" |

### Formatting Conventions
- Heading hierarchy (when to use H1, H2, H3)
- Bold and italic usage (bold for emphasis, italic for titles/terms)
- Link text (descriptive vs. "click here" — always descriptive)
- Image alt text requirements
- Code formatting (for technical brands)
- Callout or highlight box usage

### Punctuation and Emphasis
- Exclamation mark policy (limited use, never more than one)
- Ellipsis usage (avoid in most professional contexts)
- ALL CAPS policy (avoid; use bold for emphasis instead)
- Emoji usage by channel (professional channels: minimal or none; social: where appropriate)

## Terminology Management

### Preferred Terms

Maintain a list of preferred terms and their incorrect alternatives:

| Use This | Not This | Notes |
|----------|----------|-------|
| sign up (verb) | signup (verb) | "signup" is the noun form |
| log in (verb) | login (verb) | "login" is the noun/adjective form |
| set up (verb) | setup (verb) | "setup" is the noun/adjective form |
| email | e-mail | No hyphen |
| website | web site | One word |
| data is (singular) | data are | Unless the publication requires plural |

### Product and Feature Names
- Official capitalization for product names
- When to use the full product name vs. shorthand
- Whether to use "the" before product names
- How to handle versioning in copy
- Trademark and registration symbols (when required and when to omit)

### Inclusive Language
- Use gender-neutral language (they/them for unknown individuals)
- Avoid ableist language ("crazy", "blind spot", "lame")
- Use person-first language where appropriate
- Avoid culturally specific idioms that may not translate
- Use "simple" or "straightforward" instead of "easy" (what is easy varies by person)

### Industry Jargon Management
- Define which technical terms the audience understands without explanation
- List jargon that should always be defined or replaced with plain language
- Specify which acronyms need to be spelled out on first use
- Audience-specific glossary for terms that mean different things to different readers

### Competitor and Category Terms
- How to refer to your product category (use your preferred framing)
- How to refer to competitors (by name or generically)
- Terms competitors have coined that you should avoid (to prevent reinforcing their positioning)
- Your preferred differentiation language

## Auto-derived voice profile (extraction helper)

Когда есть **3–5 готовых постов автора** и нужно научить генератор контента (или LLM-агент) звучать «как он», вместо ручного описания voice guide извлеки структурные паттерны автоматически. Полученный JSON подаётся в rewrite-prompt как `VOICE_PROFILE` — модель пытается соблюсти числа, эмпирически работает заметно лучше, чем `«match the voice from these 3 examples»` без явных статистик.

### Что извлекать

| Метрика | Зачем нужна |
|---------|-------------|
| `avg_sentence_words` | Длина предложений — даёт ритм. Короткие 6–8 слов → бойко. Длинные 18–25 → reflective. |
| `avg_paragraph_words` | Размер «абзаца-мысли». LLM по дефолту пишет 60–80 слов на абзац, автор часто 30–40 или 100+. |
| `emoji_density` | Эмодзи на слово. Большинство тех-авторов 0.005–0.02, инфлюэнсеры 0.05+. Нулевая плотность тоже сигнал. |
| `common_emojis` | Top-8 эмодзи. Если автор часто использует 🦞, добавь его в prompt. |
| `signature_words` | Слова длиннее 5 букв, встретившиеся ≥ 2 раза в сэмплах. Идиолект автора. |
| `questions_ratio` | Доля сэмплов с `?`. Высокая (>0.6) → диалоговый стиль, низкая → утвердительный. |
| `lists_ratio` | Доля сэмплов с маркированными/нумерованными списками. Если 0 — не давать LLM писать списками. |
| `cta_style_hint` | Эвристика по последней строке каждого сэмпла: question / direct-call / soft-or-none. |

### Реализация

```python
import re
from collections import Counter

EMOJI_RE = re.compile(
    r"[\U0001F300-\U0001FAFF\U0001F1E0-\U0001F1FF☀-➿⌀-⏿]"
)
SENT_RE = re.compile(r"[.!?…]+[ \n]")


def analyze(samples: list[str]) -> dict:
    if not samples:
        return {}
    total = "\n\n".join(samples)
    emojis = EMOJI_RE.findall(total)
    sent_lens = [len(s.split()) for s in SENT_RE.split(total) if s.strip()]
    para_lens = [len(p.split()) for p in total.split("\n\n") if p.strip()]

    word_counts = Counter(re.findall(r"\w{5,}", total.lower()))
    signature_words = [w for w, c in word_counts.most_common(20) if c >= 2]

    has_questions = sum(1 for s in samples if "?" in s)
    has_lists = sum(1 for s in samples if re.search(r"^\s*[-•*\d]\.?\s", s, re.M))

    return {
        "samples_count": len(samples),
        "avg_sentence_words": round(sum(sent_lens) / max(len(sent_lens), 1), 1),
        "avg_paragraph_words": round(sum(para_lens) / max(len(para_lens), 1), 1),
        "emoji_density": round(len(emojis) / max(len(total.split()), 1), 3),
        "common_emojis": [e for e, _ in Counter(emojis).most_common(8)],
        "signature_words": signature_words,
        "questions_ratio": round(has_questions / len(samples), 2),
        "lists_ratio": round(has_lists / len(samples), 2),
        "cta_style_hint": _infer_cta(samples),
    }


def _infer_cta(samples: list[str]) -> str:
    last_lines = [s.strip().split("\n")[-1] for s in samples if s.strip()]
    if not last_lines:
        return "none"
    q = sum(1 for l in last_lines if l.endswith("?"))
    imp = sum(1 for l in last_lines
              if re.search(r"(пиши|напиши|попробуй|try|comment|share|tell)", l, re.I))
    if q > len(last_lines) / 2:
        return "question-to-audience"
    if imp > 0:
        return "direct-call"
    return "soft-or-none"
```

### Применение в rewrite prompt

```python
voice_profile = analyze(user_samples)
samples_block = "\n\n---\n".join(user_samples[:5])

system = f"""You are a content editor.

USER VOICE STATISTICS (try to match within ±15%):
{json.dumps(voice_profile, ensure_ascii=False, indent=2)}

USER VOICE SAMPLES (full posts):
{samples_block}

Now rewrite the following draft in the user's voice. Match sentence length,
paragraph rhythm, emoji density, and CTA style from the statistics above.
"""
```

LLM соблюдает метрики **точнее**, чем когда даёшь только сэмплы — эмпирика с малых моделей (замер был на gpt-4o-mini/gemini-2.0-flash-эре; актуальные малые модели — haiku-4-5 через claude-cli-runner или `gemini-3.1-flash-lite`, канон `config/models.md`).

### Когда обновлять профиль

- При каждом `save_voice_samples(user_id, new_samples)` — пересчитать
- После каждого опубликованного поста — если он зашёл (виральный охват), добавить в samples; если упал — не добавлять
- Хранить максимум 10 последних сэмплов, иначе устаревший стиль доминирует

### Что НЕ извлекать алгоритмически

- **Tone of voice** в смысле «дружелюбный / профессиональный» — LLM сам считывает по сэмплам, числами не задать
- **Forbidden phrases** — добавлять руками в отдельный list, эвристика тут вредна
- **Topics of expertise** — отдельный pass с TF-IDF/embeddings, не часть voice profile

Voice profile — про **форму**, не про **смысл**. Smysl всё равно подаёт исходный draft, который ты переписываешь.