define-brand-guidelines

name	define-brand-guidelines
description	Create a BRAND_GUIDELINES.md that defines how to communicate with your customer. Requires CUSTOMER.md to exist first. Covers voice, tone, language rules, messaging framework, and copy patterns.

Brand Guidelines Skill

Create the BRAND_GUIDELINES.md document that defines HOW to communicate with your customer. This document drives all copy and messaging: app UI, marketing, support, emails, everything.

Prerequisite: CUSTOMER.md must exist. Brand guidelines without customer definition is just aesthetic preference. The voice must resonate with WHO you're talking to.

Overview

This skill supports both creating new brand guidelines and refining existing ones.

This skill guides you through: 0. Prerequisite Check - Verify CUSTOMER.md exists; stop if not

1. Discovery - Questions about brand personality, voice, language preferences
2. Draft Generation - Create BRAND_GUIDELINES.md based on inputs
3. Refinement - Test with sample copy, iterate until voice feels right

Workflow

Phase 0: Prerequisite Check

CRITICAL: Before anything else, check for CUSTOMER.md:

1. Use Glob to search for **/CUSTOMER.md in the current directory
2. If NOT found: Stop immediately and inform the user:

"I can't create brand guidelines without knowing WHO you're talking to.

Please create your CUSTOMER.md first using /define-customer.

Brand voice without customer definition is just aesthetic preference - it won't resonate with anyone specific."

Do NOT proceed. End the workflow here.

3. If found: Read the CUSTOMER.md and extract key context:
   • ICP definition (who they are)
   • Pain points (what problems they have)
   • What they value (in a solution)
   • Anti-personas (who they're NOT)
   • Any language/communication hints

IMPORTANT - Pre-fill Recommendations: Use CUSTOMER.md to infer recommended options for all questions. Examples:

If CUSTOMER.md says...	Recommend...
ICP values "speed", "efficiency", "no patience"	Direct communication, short copy
ICP is technical (developers, engineers)	Technical language okay, precision matters
ICP values "data", "statistics", "proof"	Data-driven persuasion style
Anti-persona is "purists" or "academics"	Avoid being preachy or condescending
ICP is "fun-seekers", "casual players"	More playful tone, casual formality
ICP is "executives", "professionals"	More formal, authoritative personality

The goal: User should be able to accept all recommended defaults and get a solid brand guide. Only ask them to deviate where CUSTOMER.md doesn't provide clear signals.

Then check for existing BRAND_GUIDELINES.md:

header: "Existing Brand Guidelines Found"
question: "I found existing BRAND_GUIDELINES.md. What would you like to do?"
options:
  - "Refine it - update based on new insights"
  - "Start fresh - create new brand guidelines"
  - "Review it - just read through what's there"

Phase 1: Discovery

Use AskUserQuestion for all questions. Put the recommended option FIRST with "(Recommended)" suffix. Infer recommendations from CUSTOMER.md.

Question 1: Brand Personality

Infer from CUSTOMER.md:

• Data-driven ICP → "Authoritative expert"
• Beginners/learners → "Friendly mentor"
• Contrarian/challengers → "Provocative challenger"
• Enterprise/professional → "Calm professional"
• Fun-seekers/enthusiasts → "Energetic enthusiast" or "Witty companion"

header: "Brand Personality"
question: "If your brand was a person speaking to your customer, who would they be?"
options:
  - "[Inferred from CUSTOMER.md] (Recommended)"
  - "Authoritative expert - confident, definitive, data-driven"
  - "Friendly mentor - approachable, helpful, encouraging"
  - "Provocative challenger - bold, contrarian, challenges assumptions"
  - "Calm professional - measured, trustworthy, understated"
  - "Energetic enthusiast - excited, passionate, motivating"
  - "Witty companion - clever, playful, personality-forward"

Question 2: Voice Dimensions

Infer each dimension from CUSTOMER.md. Put recommended first.

header: "Formality"
question: "How formal is your brand's voice?"
options:
  - "[Inferred] (Recommended)"  # e.g., "Casual" if ICP is blitz players
  - "Very formal - professional, polished, no contractions"
  - "Somewhat formal - professional but approachable"
  - "Neutral - depends on context"
  - "Casual - relaxed, contractions okay, conversational"
  - "Very casual - informal, slang okay, like texting a friend"

Inference rules for formality:

• Enterprise/executives → Very formal or Somewhat formal
• Developers → Casual or Neutral
• Consumers/players → Casual or Very casual
• Default → Casual (most approachable)

header: "Tone Weight"
question: "How serious vs playful is your brand?"
options:
  - "[Inferred] (Recommended)"  # e.g., "Mostly serious" if data-driven
  - "Very serious - no humor, all business"
  - "Mostly serious - occasional lightness"
  - "Balanced - serious when needed, light when appropriate"
  - "Mostly playful - humor is part of the brand"
  - "Very playful - fun and entertainment are core"

Inference rules for tone:

• ICP values "fun", "enjoyment" → Mostly playful or Balanced
• ICP values "data", "precision" → Mostly serious
• B2B/professional → Balanced or Mostly serious
• Default → Balanced

header: "Technical Level"
question: "How technical is your language?"
options:
  - "[Inferred] (Recommended)"
  - "Highly technical - jargon expected, precision matters"
  - "Somewhat technical - domain terms with explanation"
  - "Accessible - simple language, avoid jargon"
  - "Very simple - anyone should understand"

Inference rules:

• ICP is developers/engineers → Highly technical or Somewhat technical
• ICP values "plain language", "accessible" → Accessible
• General consumers → Very simple or Accessible
• Default → Somewhat technical

header: "Directness"
question: "How direct is your communication?"
options:
  - "[Inferred] (Recommended)"
  - "Very direct - commands, no hedging, get to the point"
  - "Direct - clear and straightforward"
  - "Balanced - direct but diplomatic"
  - "Soft - suggestive, options-focused"
  - "Very soft - gentle, lots of qualifiers"

Inference rules:

• ICP values "speed", "efficiency", "no patience" → Very direct
• ICP is time-constrained → Very direct or Direct
• ICP is beginners/learners → Balanced or Soft
• Default → Direct

Question 3: Writing Style

header: "Copy Style"
question: "What does your ideal copy look like?"
options:
  - "[Inferred options pre-selected] (Recommended)"
  - "Short and punchy - minimal words, maximum impact"
  - "Concise but complete - efficient, no fluff"
  - "Conversational flow - natural, like talking"
  - "Rich and detailed - thorough explanations"
multiSelect: true

Inference: If ICP values speed → "Short and punchy". If ICP is technical → "Concise but complete".

header: "Persuasion Style"
question: "How do you persuade?"
options:
  - "[Inferred options pre-selected] (Recommended)"
  - "Data and evidence - stats, proof, numbers"
  - "Benefits and outcomes - what they'll achieve"
  - "Emotional resonance - how they'll feel"
  - "Social proof - others trust us"
  - "Authority - we're the experts"
multiSelect: true

Inference: Match to "What the ICP Values" from CUSTOMER.md.

Question 4: Language Preferences

header: "Language Rules"
question: "Select your language preferences:"
options:
  - "[Inferred bundle] (Recommended)"  # Pre-select compatible options
  - "Use contractions (we're, you'll, it's)"
  - "Avoid contractions (we are, you will, it is)"
  - "Emoji okay in appropriate contexts"
  - "No emoji ever"
  - "Exclamation marks okay (sparingly)"
  - "No exclamation marks"
  - "Industry jargon okay for our audience"
  - "Avoid all jargon"
multiSelect: true

Default recommendation: "Use contractions" + "No emoji" + "Industry jargon okay" (professional but approachable)

Question 5: Anti-Patterns

header: "Voice Anti-Patterns"
question: "What should your brand NEVER sound like?"
options:
  - "[Inferred from anti-personas] (Recommended)"
  - "Corporate buzzwords (synergy, leverage, ideate)"
  - "Overly salesy (ACT NOW! LIMITED TIME!)"
  - "Condescending or preachy"
  - "Wishy-washy or uncertain"
  - "Generic AI-speak (I hope this helps!)"
  - "Robotic or cold"
  - "Overly casual or unprofessional"
  - "Boring or dry"
multiSelect: true

Inference: Map anti-persona traits to voice anti-patterns. E.g., if anti-persona is "purists who debate principles" → recommend "Condescending or preachy".

Question 6: Core Value Propositions

header: "Value Props"
question: "What are the 2-3 main arguments/benefits your brand communicates?"
freeText: true
placeholder: "e.g., '1. Faster than alternatives 2. Data-driven decisions 3. Built for experts'"

Question 7: The Hook

header: "The Hook"
question: "What's the single most compelling thing you can say to grab attention?"
freeText: true
placeholder: "The one sentence that makes your ICP say 'tell me more'"

Question 8: Existing Copy (Optional)

header: "Examples"
question: "Do you have any existing copy you love or hate? (Paste examples or describe)"
freeText: true
placeholder: "Optional - helps calibrate the voice. e.g., 'I love Stripe's docs - clear, technical, no fluff'"

Question 9+: Gap-Filling

After core questions, verify you have clarity on:

• Brand personality (clear, specific)
• Voice dimensions (where on each spectrum)
• What to avoid (anti-patterns)
• Core messages (value props)

Keep asking until confident.

Phase 2: Draft Generation

Generate BRAND_GUIDELINES.md using this structure:

# [Product Name] Brand Guidelines

> **The Single Rule**: [One sentence that captures how every piece of copy should feel]

---

## Voice Identity

[One paragraph describing the brand's personality - who it would be if it were a person talking to the ICP]

### Voice Characteristics

| Characteristic | What This Means | Example |
|----------------|-----------------|---------|
| [Trait 1] | [How it manifests in copy] | "[Sample phrase]" |
| [Trait 2] | [How it manifests in copy] | "[Sample phrase]" |
| [Trait 3] | [How it manifests in copy] | "[Sample phrase]" |

### We Are / We Are NOT

| We Are... | We Are NOT... |
|-----------|---------------|
| [Positive trait] | [Opposite to avoid] |
| [Positive trait] | [Opposite to avoid] |
| [Positive trait] | [Opposite to avoid] |
| [Positive trait] | [Opposite to avoid] |

---

## Tone by Context

Voice is constant. Tone flexes based on context.

| Context | Tone Shift | Example |
|---------|------------|---------|
| **Marketing/Landing** | [How tone adjusts] | "[Sample]" |
| **In-App UI** | [How tone adjusts] | "[Sample]" |
| **Error Messages** | [How tone adjusts] | "[Sample]" |
| **Success States** | [How tone adjusts] | "[Sample]" |
| **Email/Notifications** | [How tone adjusts] | "[Sample]" |
| **Help/Support** | [How tone adjusts] | "[Sample]" |

---

## Language Rules

### USE These Words/Phrases

| Word/Phrase | When to Use | Instead of |
|-------------|-------------|------------|
| [Term] | [Context] | [Generic alternative] |
| [Term] | [Context] | [Generic alternative] |
| [Term] | [Context] | [Generic alternative] |

### AVOID These Words/Phrases

| Word/Phrase | Why | Use Instead |
|-------------|-----|-------------|
| [Term] | [Reason it's off-brand] | [Better alternative] |
| [Term] | [Reason it's off-brand] | [Better alternative] |
| [Term] | [Reason it's off-brand] | [Better alternative] |

### Product Terminology

| Term | Definition | Usage |
|------|------------|-------|
| [Product-specific term] | [What it means] | [How to use in copy] |
| [Product-specific term] | [What it means] | [How to use in copy] |

### Style Rules

- **Contractions**: [Yes/No/When]
- **Sentence length**: [Preference]
- **Paragraph length**: [Preference]
- **Emoji**: [Yes/No/When]
- **Exclamation marks**: [Yes/No/When]
- **Oxford comma**: [Yes/No]
- **Capitalization**: [Rules]

---

## Messaging Framework

### The Hook

> [The single most compelling sentence that grabs ICP attention]

### Core Value Propositions

**Value Prop 1: [Name]**
- **The claim**: [One sentence]
- **Why it matters to ICP**: [Connection to their pain/values from CUSTOMER.md]
- **Proof point**: [Evidence that supports this]
- **Sample copy**: "[Example headline or sentence]"

**Value Prop 2: [Name]**
- **The claim**: [One sentence]
- **Why it matters to ICP**: [Connection to their pain/values]
- **Proof point**: [Evidence]
- **Sample copy**: "[Example]"

**Value Prop 3: [Name]**
- **The claim**: [One sentence]
- **Why it matters to ICP**: [Connection to their pain/values]
- **Proof point**: [Evidence]
- **Sample copy**: "[Example]"

---

## Copy Patterns

### Headlines

- **Pattern**: [Structure - e.g., "Verb + Outcome" or "Question that implies problem"]
- **Length**: [Word count guideline]
- **Good examples**:
  - "[Example 1]"
  - "[Example 2]"
- **Bad examples**:
  - "[What to avoid 1]"
  - "[What to avoid 2]"

### Subheads

- **Pattern**: [Structure]
- **Length**: [Guideline]
- **Good examples**:
  - "[Example]"
- **Bad examples**:
  - "[What to avoid]"

### CTAs (Calls to Action)

- **Pattern**: [Structure - e.g., "Action verb + object" or "Benefit-focused"]
- **Good examples**:
  - "[Example 1]"
  - "[Example 2]"
- **Bad examples**:
  - "[What to avoid]"

### Microcopy (Buttons, Labels, Tooltips)

- **Pattern**: [Structure]
- **Good examples**:
  - "[Example]"
- **Bad examples**:
  - "[What to avoid]"

### Error Messages

- **Tone**: [How to handle errors - apologetic? matter-of-fact? helpful?]
- **Pattern**: [Structure - e.g., "What happened + What to do"]
- **Good examples**:
  - "[Example]"
- **Bad examples**:
  - "[What to avoid]"

### Empty States

- **Tone**: [Encouraging? Instructive? Playful?]
- **Pattern**: [Structure]
- **Good examples**:
  - "[Example]"
- **Bad examples**:
  - "[What to avoid]"

---

## Transformations

Show how generic copy becomes on-brand copy.

| Before (Generic) | After (On-brand) | Why Better |
|------------------|------------------|------------|
| "[Generic copy]" | "[Brand copy]" | [What changed] |
| "[Generic copy]" | "[Brand copy]" | [What changed] |
| "[Generic copy]" | "[Brand copy]" | [What changed] |

---

## Quick Reference

**Voice in one sentence**: [Brand] sounds like [memorable analogy].

**Before writing, check**:
- [ ] Does this sound like [brand personality]?
- [ ] Would [ICP from CUSTOMER.md] respond to this?
- [ ] Am I using approved terminology?
- [ ] Is this the right tone for this context?
- [ ] Have I avoided all anti-patterns?

---

## Customer Context

> *Pulled from CUSTOMER.md for reference*

**Who we're talking to**: [ICP summary]

**Their main pain**: [Key pain point]

**What they value**: [Key values from CUSTOMER.md]

**What turns them off**: [Anti-persona traits to avoid triggering]

Write this file to the current working directory as BRAND_GUIDELINES.md.

Phase 3: Refinement

After generating the initial document, test and refine:

Step 3.1: Sample Copy Test

Generate 3 sample pieces of copy using the brand guidelines:

1. A headline + subhead for the landing page
2. An error message
3. A feature description

Present to user:

header: "Sample Copy"
question: "Does this copy feel like your brand?"
[Display the samples]
options:
  - "Yes - this nails the voice"
  - "Close - minor adjustments needed"
  - "Off - something's not right"

Step 3.2: Specific Feedback

If not "Yes":

header: "What's Off?"
question: "What needs adjustment?"
options:
  - "Too formal / stiff"
  - "Too casual / unprofessional"
  - "Too playful / not serious enough"
  - "Too serious / needs more personality"
  - "Wrong word choices"
  - "Doesn't sound like us"
  - "Other - let me explain"
multiSelect: true

Step 3.3: Update and Iterate

Based on feedback:

1. Update the voice characteristics
2. Adjust the examples
3. Refine the "We Are / We Are NOT" table
4. Re-generate sample copy

Step 3.4: Completion Check

header: "Continue?"
question: "Want to refine more or test more samples?"
options:
  - "Yes - generate more samples to test"
  - "No - the brand guidelines are solid"
  - "Almost - one more round should do it"

Phase 4: Finalization

When user is satisfied:

1. Add Version History
2. Add usage instructions
3. Remind user to reference this doc when writing ANY copy

---

## Version History

- **v1.0** - [Date] - Initial creation

## Usage

Reference this document for ALL copy:
- Marketing pages
- In-app UI text
- Email templates
- Error messages
- Help documentation
- Social media
- Sales materials

**The test**: Read your copy out loud. Does it sound like [brand personality]? If not, rewrite.

Key Principles

Voice ≠ Tone

• Voice is constant (the brand's personality)
• Tone flexes by context (error vs marketing vs support)
• Define both clearly

Grounded in Customer

• Every voice choice should resonate with the ICP
• Reference CUSTOMER.md pain points and values
• The voice must feel like it's FOR them

Actionable Over Abstract

• Don't just say "be friendly" - show what friendly looks like
• Every guideline needs examples
• Before/after transformations teach better than rules

Anti-Patterns Are Critical

• Knowing what NOT to do is as important as knowing what to do
• Be specific about voice anti-patterns
• "Don't sound corporate" is vague; list the actual words to avoid

Test with Real Copy

• Guidelines are theory; sample copy is proof
• If the generated samples feel wrong, the guidelines are wrong
• Iterate until samples feel authentically on-brand

Reduce Cognitive Load

• ALWAYS use AskUserQuestion tool when available
• Put recommended option FIRST with "(Recommended)" suffix
• Pre-fill recommendations from CUSTOMER.md - user should be able to accept all defaults
• Present multi-choice questions to minimize typing
• Limit options to 6-8 max per question
• Use multiSelect for non-exclusive choices
• Only use free-text for essential context (value props, hooks)

Output Location

Write BRAND_GUIDELINES.md to the current working directory (or user-specified path).