Brand Voice skill for Codex

A voice is defined well when two writers given the same brief produce copy a reader would attribute to the same company, the guide shows examples instead of adjectives, and the rules that can be checked automatically are checked automatically.

Inspect first

1. Look for existing guidance: rg -il "voice|tone|style guide|brand" docs/ content/ *.md and AGENTS.md. Extend what exists rather than inventing a competing guide.
2. Collect a corpus (20-50 pieces): homepage, top landing pages, onboarding emails, UI strings, docs intro pages, best social posts, founder posts, sales emails that worked.
3. Collect customer language: reviews, interviews, support tickets. The voice should sound like someone the customer trusts, using their words.
4. Note audiences and contexts: marketing site, product UI, docs, support, incident communication, social, sales.

Derive the voice from evidence

1. Mark the 5-10 pieces the team agrees “sound most like us” and the 5 that feel off.
2. Compare them line by line: sentence length, person (“we/you”), formality, humour, jargon, confidence level, how claims are made, how they handle bad news.
3. Name 3-4 voice attributes, each as “this, not that” to make it actionable:

Attribute	We are	We are not	Sounds like
Direct	Lead with the point, short sentences	Curt, cold	“Your export is ready.”
Expert	Precise terms, real numbers	Jargon to impress	“p95 latency dropped from 420 ms to 180 ms.”
Warm	Plain words, credit the reader	Gushing, exclamation-heavy	“Nice, that’s set up. Next: invite your team.”
Candid	Name limits and trade-offs	Defensive, vague	“We don’t support SAML yet. It’s planned for Q1.”

Avoid attributes every company claims (innovative, customer-centric) unless the “not” column makes them distinctive.

Tone by context

Voice stays constant; tone shifts with the reader’s situation.

Context	Reader state	Tone adjustment	Example
Marketing hero	Curious, sceptical	Confident, concrete	“Close your books in 2 days.”
Onboarding	Motivated, unsure	Encouraging, step-by-step	“Connect your bank. Takes about a minute.”
Error message	Blocked, annoyed	Calm, specific, no jokes	“We couldn’t save the file: it’s over 25 MB. Try compressing it.”
Incident / outage	Worried	Sober, factual, timestamped	“Since 14:05 UTC some uploads fail. Data is safe. Next update 14:45.”
Billing / price change	Wary	Plain, respectful, early notice	“Your plan changes on 1 March. Here’s what it means for you.”
Social	Browsing	Lighter, more personal

Vocabulary

| Use | Instead of | Why |
|---|---|---|
| workspace | account, org, tenant | Product term in the UI |
| sign in | log in, login (verb) | Matches UI buttons |
| customers | users (in marketing) | They pay us |
| set up (verb) / setup (noun) | setup (verb) | Correct usage |

Also list: product and feature names with exact capitalisation, terms never to use (internal codenames, competitor terms for your features), and words that clash with the voice. Keep spelling (US/UK), Oxford comma, date and number formats in the same document or point to the style guide.

Before/after examples

The most useful part of the guide. For each attribute and key context, show a real off-voice sentence from the corpus and its rewrite, with a one-line reason:

**Before:** "Our cutting-edge platform empowers teams to achieve more."
**After:** "Plan, ship and report on client work from one place."
**Why:** Direct and concrete; says what it does instead of claiming impact.

Aim for 10-20 pairs across contexts.

Enforce what can be enforced: Vale

Vale lints prose in Markdown, MDX, HTML and more. Install needs network (Homebrew, go install, or a release binary); ask before installing in a sandbox without network.

# .vale.ini
StylesPath = styles
MinAlertLevel = suggestion
Vocab = Brand

[*.{md,mdx}]
BasedOnStyles = Vale, Brand

# styles/Brand/Terms.yml
extends: substitution
message: "Use '%s' instead of '%s'."
level: error
ignorecase: true
swap:
  log in to: sign in to
  login to: sign in to
  organisation: workspace
  e-mail: email

# styles/Brand/Hype.yml
extends: existence
message: "'%s' is hype; say what it does instead."
level: warning
ignorecase: true
tokens:
  - cutting-edge
  - world-class
  - best-in-class
  - next-generation
  - revolutionary
  - seamless
  - leverage
  - empower

# styles/config/vocabularies/Brand/accept.txt  (product names Vale should not flag)
Acme
AcmeSync

Run and wire it in:

vale docs/ content/                 # local
vale --output=line content/ | head  # compact output for CI logs

Add it to CI or pre-commit only after the team agrees on the rules; start with level: warning for subjective rules and error only for terminology.

Applying the voice (writing or rewriting)

- [ ] 1. Identify context and reader state; pick the tone row
- [ ] 2. Draft for meaning first
- [ ] 3. Rewrite against the attributes; check each sentence against the "not" column
- [ ] 4. Replace vocabulary per the table; run Vale if configured
- [ ] 5. Read aloud: would the best writer on the team say it this way?

When an agent rewrites copy in the codebase, keep meaning, claims and legal text unchanged; flag anything where voice and accuracy conflict instead of choosing voice.

Auditing existing copy

Sample pages across contexts, then score each against the attributes (1-3) and record off-voice examples with location. Report patterns, not every instance: “Error messages in billing use passive voice and blame the user (12 of 15 sampled)”.

Gotchas

• A guide of adjectives (“friendly, bold, smart”) with no examples changes nothing.
• One tone everywhere: jokes in error messages, marketing hype in incident updates.
• Voice rules that contradict UI labels; copy and product must use the same terms.
• Banning words without offering the replacement.
• Rewriting legal or compliance text for voice without review.

Verification

• Two people (or two agent runs) rewrite the same 3 briefs with the guide; outputs match the attributes and each other in feel.
• Vale runs clean on the guide’s own “after” examples and flags the “before” examples.
• Terminology in UI strings matches the vocabulary table: rg -n -i "log in|login" src/.

Output template

# <Brand> voice and tone
## Who we are talking to
## Voice attributes (this, not that, example)
## Tone by context (table)
## Vocabulary (use / instead of / why), product names
## Before and after (10-20 pairs)
## Checklist for writers
## Enforcement (.vale.ini and rules, where they run)