voice-tone-guide

name	voice-tone-guide
description	Creates brand voice and tone documentation with do/don't examples, vocabulary lists, platform-specific modifiers, and writing samples that any writer can follow to produce on-brand content. Use when the user needs to document their brand voice, create tone guidelines, build a writing style guide, or standardize how their brand communicates. Do NOT use for audience analysis (use `audience-analysis`), content strategy planning (use `editorial-calendar`), or actual content writing (use `blog-post-writing`).
license	Apache-2.0
metadata	{"author":"foundry-skills","version":"1.0.0","tags":"content-marketing writing template","category":"writing","subcategory":"content-marketing","depends":"","disclaimer":"none","difficulty":"intermediate"}

Voice and Tone Guide

When to Use

• User needs to document their brand voice for a content team
• User asks for tone guidelines, writing style documentation, or brand voice rules
• User wants to standardize how their brand sounds across channels and writers
• User needs a reference document that ensures consistent brand communication
• Do NOT use when the user wants to analyze their audience (use audience-analysis instead)
• Do NOT use when the user wants to plan content topics and schedules (use editorial-calendar instead)
• Do NOT use when the user wants to write actual content (use blog-post-writing instead)
• Do NOT use when the user wants to adjust the tone of existing text (use tone-adjustment instead)

Process

1. Collect brand and voice context. Ask the user for:

   • Company or brand name and what they do
   • Current audience (who reads/hears their content)
   • 3-5 adjectives that describe how the brand should sound
   • 3-5 adjectives that describe how the brand should NOT sound
   • Examples of content they like (their own or competitors')
   • Content channels: blog, social media, email, product UI, customer support

2. Define voice attributes. Establish 3-4 core voice attributes:

   • Each attribute is a named quality with a spectrum (e.g., "Confident, not arrogant")
   • Each attribute includes a definition specific to this brand
   • Each attribute has a "This, not that" pair showing the boundary
   • Voice attributes are constant across all channels -- they define who the brand is

3. Define tone variations. Tone changes by context while voice stays constant:

   • Map tone adjustments for different scenarios: celebrating wins, delivering bad news, educating, selling, apologizing
   • Map tone adjustments by channel: social media (lighter), email (direct), blog (thorough), support (empathetic)
   • For each adjustment, show how the voice attributes manifest differently

4. Create the vocabulary guide. Build lists of:

   • Use these words: Terms that reflect the brand voice (with examples in context)
   • Avoid these words: Terms that conflict with the brand voice (with preferred alternatives)
   • Industry-specific decisions: Jargon to use, jargon to explain, jargon to avoid
   • Formality markers: Contractions (yes/no), first person (I/we), exclamation marks (limit), emoji use

5. Write do/don't examples. For each voice attribute:

   • 2-3 paired examples showing the same message written on-brand and off-brand
   • Examples should cover different content types (social post, email, error message, blog intro)
   • Each pair should make the distinction obvious without additional explanation

6. Write platform-specific samples. Create one sample piece for each primary channel:

   • Blog post opening paragraph
   • Social media post
   • Email newsletter opening
   • Product notification or error message (if applicable)
   • Customer support response (if applicable)

Output Format

## Voice and Tone Guide: [Brand Name]

**Brand mission (one line):** [What the brand does and for whom]

---

### Voice Attributes

Our voice is constant. It is who we are, regardless of channel or context.

**1. [Attribute 1]: [One-sentence definition]**
- We are: [specific positive boundary]
- We are NOT: [specific negative boundary]
- Spectrum: [lower end] |----X----| [upper end]

**2. [Attribute 2]: [One-sentence definition]**
- We are: [specific positive boundary]
- We are NOT: [specific negative boundary]
- Spectrum: [lower end] |----X----| [upper end]

**3. [Attribute 3]: [One-sentence definition]**
- We are: [specific positive boundary]
- We are NOT: [specific negative boundary]
- Spectrum: [lower end] |----X----| [upper end]

**4. [Attribute 4]: [One-sentence definition] (optional)**
- We are: [specific positive boundary]
- We are NOT: [specific negative boundary]

---

### Tone Adjustments by Context

| Context | Tone Shift | Example |
|---------|-----------|---------|
| Celebrating a win | [how voice attributes adjust] | [sample sentence] |
| Delivering bad news | [how voice attributes adjust] | [sample sentence] |
| Educating/teaching | [how voice attributes adjust] | [sample sentence] |
| Selling/promoting | [how voice attributes adjust] | [sample sentence] |
| Apologizing | [how voice attributes adjust] | [sample sentence] |

### Tone Adjustments by Channel

| Channel | Tone Notes | Formality Level |
|---------|-----------|----------------|
| Blog | [adjustments] | [level] |
| Social media | [adjustments] | [level] |
| Email | [adjustments] | [level] |
| Product UI | [adjustments] | [level] |
| Support | [adjustments] | [level] |

---

### Vocabulary Guide

**Use These Words:**
| Word/Phrase | In Context |
|-------------|-----------|
| [word] | [example sentence using this word] |
| [word] | [example sentence] |

**Avoid These Words:**
| Avoid | Use Instead | Why |
|-------|------------|-----|
| [word] | [alternative] | [reason] |
| [word] | [alternative] | [reason] |

**Formality Decisions:**
| Element | Decision |
|---------|---------|
| Contractions | [yes/no/context-dependent] |
| First person | [I / we / they / context-dependent] |
| Exclamation marks | [limit per piece] |
| Emoji | [never / sparingly / platform-specific] |
| Oxford comma | [yes / no] |

---

### Do/Don't Examples

**Attribute 1: [Name]**

| Do (On-Brand) | Don't (Off-Brand) |
|--------------|-------------------|
| [on-brand version of message] | [off-brand version of same message] |
| [on-brand version] | [off-brand version] |

**Attribute 2: [Name]**

| Do (On-Brand) | Don't (Off-Brand) |
|--------------|-------------------|
| [on-brand version] | [off-brand version] |
| [on-brand version] | [off-brand version] |

---

### Platform Samples

**Blog Post Opening:**
[Sample opening paragraph demonstrating the voice on the blog]

**Social Media Post:**
[Sample post demonstrating the voice on social]

**Email Newsletter Opening:**
[Sample newsletter opening demonstrating the voice in email]

**Error Message / Notification:**
[Sample product message demonstrating the voice in UI]

---

### Quick Reference Card

| Attribute | We Are | We Are Not |
|-----------|--------|-----------|
| [1] | [positive] | [negative] |
| [2] | [positive] | [negative] |
| [3] | [positive] | [negative] |

**Before you publish, check:**
- [ ] Does this sound like [brand name], or could any company have written it?
- [ ] Would [persona name] trust this and act on it?
- [ ] Is every claim specific and supported?
- [ ] Does the tone match the context (celebrating/teaching/selling/apologizing)?

Rules

1. NEVER define voice attributes as single adjectives without boundaries -- "friendly" means nothing without "friendly, not childish" or "friendly, not artificially cheerful"
2. NEVER use more than 4 voice attributes -- more than 4 creates paralysis for writers trying to embody all of them simultaneously
3. NEVER skip the do/don't examples -- abstract voice descriptions become concrete only through paired examples
4. NEVER write a voice guide without platform-specific samples -- the same voice sounds different on Twitter than in a support email
5. NEVER conflate voice and tone -- voice is constant (who we are), tone varies by context (how we adapt)
6. ALWAYS provide a "This, not that" boundary for every voice attribute
7. ALWAYS include at least 2 do/don't paired examples per voice attribute
8. ALWAYS include a vocabulary guide with specific words to use and avoid
9. ALWAYS provide platform-specific writing samples showing the voice in action
10. ALWAYS include a quick reference card that fits on one page
11. Voice attributes should be specific to this brand, not generic ("We are confident" applies to every brand; "We explain complex things without condescension" is specific)
12. The guide should be usable by a new writer on day one -- if they cannot produce on-brand content using only this document, it is incomplete

Edge Cases

• User has no existing brand voice. Help them discover it by asking: "If your brand were a person at a dinner party, how would they talk?" and "Show me 3 pieces of content you wish you had written." Build the voice from their answers and aspirations.
• User's current voice is inconsistent across channels. Audit the inconsistencies first. Ask which channel's voice feels most authentic, and build the guide around that anchor. The guide becomes the tool for aligning the other channels.
• Brand serves audiences with very different expectations (e.g., consumers and enterprises). Create one core voice with distinct tone profiles for each audience segment. The voice stays the same; the tone adjustments section gets more detailed.
• User has a strong founder voice that the team needs to replicate. Analyze the founder's writing for patterns: sentence length, vocabulary, punctuation habits, recurring structural choices. Document these as voice attributes, not as "write like [founder name]."
• User is rebranding. Document both the old voice (what to move away from) and the new voice (what to move toward). Include a transition guide that shows the shift for each attribute.

Example

Input: "Create a voice and tone guide for our developer tools company. We make an API monitoring platform. Our audience is software engineers and DevOps teams. We want to sound technically credible but not dry. We admire how Stripe communicates."

Output:

Voice and Tone Guide: PulseAPI

Brand mission (one line): PulseAPI helps engineering teams catch API failures before their users do.

---

Voice Attributes

Our voice is constant. It is who we are, regardless of channel or context.

1. Technically Precise: We use correct terminology and show our work.

• We are: accurate, specific, and unafraid of technical depth
• We are NOT: dumbed-down, vague, or handwavy about technical details
• Spectrum: Oversimplified |--------X--| Academic

2. Direct: We say what we mean in the fewest words possible.

• We are: concise, action-oriented, and clear about what to do next
• We are NOT: wordy, hedge-filled, or buried in qualifications
• Spectrum: Terse |------X----| Verbose

3. Calm Under Pressure: We communicate urgency without panic.

• We are: composed, solution-focused, and steady in incident communication
• We are NOT: alarming, dismissive ("no big deal"), or overly apologetic
• Spectrum: Dismissive |--------X--| Panicked

4. Respectful of the Reader's Time: We front-load value.

• We are: structured, scannable, and immediately useful
• We are NOT: padded, repetitive, or forcing readers to dig for the answer
• Spectrum: Incomplete |------X----| Exhaustive

---

Tone Adjustments by Context

Context	Tone Shift	Example
Celebrating a win	Proud but factual -- lead with the achievement, not the emotion	"PulseAPI now monitors 2 billion API calls per day. Here is what we built to get there."
Delivering bad news (incident)	Calm, specific, solution-first	"API monitoring delayed by 3 minutes between 14:02-14:15 UTC. Root cause identified. All alerts are current."
Educating/teaching	Patient but not patronizing -- assume the reader is smart	"Rate limiting prevents one client from consuming all available capacity. Here is how to implement it."
Selling/promoting	Feature-first, outcome-clear -- show, do not claim	"Set up alerts in 4 lines of code. Get notified before your users notice."
Apologizing	Take responsibility, state impact, describe fix	"We made a mistake in the billing calculation for March. Here is what happened, who is affected, and what we have done."

Tone Adjustments by Channel

Channel	Tone Notes	Formality Level
Blog	Thorough, educational, code examples welcome	Medium-formal
Twitter/X	Punchy, technical one-liners, occasional dry humor	Casual
Email	Direct, action-oriented, structured with headers	Medium-formal
Product UI	Minimal, instructive, no personality flourishes	Formal
Docs	Reference-style, scannable, example-heavy	Formal

---

Vocabulary Guide

Use These Words:

Word/Phrase	In Context
"Monitor"	"Monitor your API endpoints in real time"
"Alert"	"Set up alerts for latency spikes above 500ms"
"Incident"	"During the incident, response times exceeded SLA thresholds"
"Deploy"	"Deploy the monitoring agent with one command"

Avoid These Words:

Avoid	Use Instead	Why
"Solution"	"Tool" or "platform" or the specific feature name	Vague sales language that engineers distrust
"Leverage"	"Use"	Corporate jargon -- say what you mean
"Seamless"	Describe the specific integration steps	Every product claims to be seamless; none of them are
"Cutting-edge"	Describe the specific technical capability	Meaningless superlative that signals marketing over substance
"Empower"	State what the user can now do	Patronizing and vague

Formality Decisions:

Element	Decision
Contractions	Yes -- "you'll," "we're," "it's" are natural in technical writing
First person	"We" for PulseAPI, "you" for the reader. Never "one" or "the user."
Exclamation marks	Maximum 1 per blog post, 0 in docs, 0 in incident communication
Emoji	Never in product UI or docs. Sparingly on social (max 1 per post).
Oxford comma	Yes, always

---

Do/Don't Examples

Attribute: Technically Precise

Do (On-Brand)	Don't (Off-Brand)
"PulseAPI checks endpoint health every 30 seconds and alerts you when p99 latency exceeds your defined threshold."	"PulseAPI keeps an eye on your APIs and lets you know if something seems off."
"The agent requires 12MB of memory and adds less than 2ms of latency per request."	"The agent is lightweight and has minimal impact on performance."

Attribute: Direct

Do (On-Brand)	Don't (Off-Brand)
"Add the SDK. Set your thresholds. Deploy."	"Getting started with PulseAPI is a straightforward process that begins with adding our easy-to-use SDK to your application."
"Your API returned 503 errors 47 times in the last hour."	"It appears that there may be some issues with your API availability that you might want to look into."

---

Platform Samples

Blog Post Opening: Every API has a failure budget. The question is whether you are spending it intentionally or discovering the overdraft from a customer complaint. PulseAPI's latency distribution analysis shows that 73% of API incidents are preceded by a p95 latency increase 10-15 minutes before the first error. Here is how to catch that signal.

Social Media Post (Twitter/X): Your API responded 200 OK but took 4 seconds.

Your monitoring says everything is fine.

Your users say nothing -- they already left.

p99 latency matters more than status codes.

Email Newsletter Opening: Three changes in this release: custom alerting windows, Slack thread integration for incident timelines, and a 40% reduction in false positive alerts. Here is what each one does and why we built it.

Error Message (Product UI): Alert configuration saved. Monitoring starts within 60 seconds.

---

Quick Reference Card

Attribute	We Are	We Are Not
Technically Precise	Specific, accurate, depth-first	Vague, dumbed-down, imprecise
Direct	Concise, action-oriented, clear	Wordy, hedging, buried
Calm Under Pressure	Composed, solution-focused	Alarming, dismissive, over-apologetic
Time-Respectful	Structured, scannable, front-loaded	Padded, repetitive, meandering

Before you publish, check:

• Does this sound like it was written by an engineer for engineers?
• Could a developer act on this content without asking follow-up questions?
• Is every claim specific and supported with numbers or examples?
• Does the tone match the context (teaching/announcing/resolving)?