brand-builder skill

---
name: brand-builder
description: |
  PREFER /brand-init for new projects (outputs unified brand.yaml).
  This skill outputs the legacy brand-profile.yaml format.
  Use --legacy flag or when brand-kit is not available.

  Interactive brand discovery for a project. Creates brand-profile.yaml
  that guides all future content generation.

  Run once per project to establish voice, audience, topics.
argument-hint: "[project-name] [--legacy]"
effort: medium
---

# /brand-builder

Establish brand identity. Generate content that fits.

> **Note:** For new projects, prefer `/brand-init` which outputs the unified
> `brand.yaml` format consumed by brand-kit. This skill outputs the legacy
> `brand-profile.yaml` format. Use `/brand-init` for the full brand-as-code
> pipeline (tokens + assets + templates).

## What This Does

Interactive discovery process that creates a `brand-profile.yaml` in the project root.
This profile guides `/post` and `/announce` skills to generate on-brand content.

## Process

### Phase 1: Discovery (Interactive)

Ask the user questions using `AskUserQuestion`:

**1. Target Audience**
```
Who is the primary user of [product]?
- Developers / technical users
- General consumers
- Business / enterprise
- Specific niche (describe)
```

**2. Tone & Voice**
```
What tone should [product] use?
- Professional & authoritative
- Casual & friendly
- Playful & fun
- Technical & precise
```

**3. Core Value Proposition**
```
In one sentence, what does [product] do for users?
(User provides free text)
```

**4. Content Topics**
```
What topics are relevant to [product]'s audience? (Select multiple)
- Product updates & features
- Industry news & trends
- Tips & tutorials
- Behind-the-scenes / building in public
- User stories & testimonials
- General interest in the domain
```

**5. Competitors / Inspirations**
```
What brands or products inspire [product]'s voice?
(User provides free text - optional)
```

### Phase 2: Context Gathering (Automatic)

Gather additional context without user input:

**Git History Analysis**
```bash
# Recent commits to understand what's being built
git log --oneline -20

# Key features from README
cat README.md | head -100

# Tech stack from package.json / Cargo.toml / etc.
cat package.json 2>/dev/null | jq '{name, description, keywords}'
```

**Existing Marketing Materials**
- Check for existing `brand-profile.yaml`
- Look for marketing copy in README, landing page
- Note any existing social presence

### Phase 3: Profile Generation

Generate `brand-profile.yaml` combining user input and gathered context:

```yaml
# Brand Profile for [Product Name]
# Generated by /brand-builder on [date]
# Used by /post and /announce for content generation

product:
  name: Volume
  domain: volume.app
  tagline: "Track your lifts. See your gains."
  category: health

audience:
  primary: "Gym-goers who want to track strength training progress"
  demographics:
    - Age 25-45
    - Fitness enthusiasts
    - Data-driven
  pain_points:
    - Hard to remember what weight to use
    - Can't see progress over time
    - Existing apps are too complex

voice:
  tone: casual_friendly
  personality:
    - Encouraging but not preachy
    - Data-focused without being nerdy
    - Celebrates small wins
  avoid:
    - Bro culture / toxic fitness
    - Overly technical jargon
    - Shaming language

content:
  mix:
    product_updates: 30%
    valuable_content: 70%

  topics:
    # Product-related (30%)
    - New features and improvements
    - Tips for using the app
    - User milestones

    # Domain-related (70%)
    - Strength training tips
    - Form and technique
    - Progress tracking psychology
    - Motivation and consistency
    - Gym culture and community

  hashtags:
    primary:
      - "#fitness"
      - "#strengthtraining"
      - "#gymlife"
    product:
      - "#volumeapp"
      - "#trackyourlifts"

  posting_frequency: "2-3 times per week"

inspirations:
  - "Strong app - clean and focused"
  - "Strava - community without being overwhelming"

twitter_account: "@MistyStepLLC"  # From products.yaml category

# Generated context
context:
  tech_stack: "Next.js, TypeScript, Convex"
  recent_features:
    - "Interval timer"
    - "Exercise library"
    - "Progress charts"
  github_repo: "MistyStep/volume"
```

### Phase 4: Save & Confirm

Save to project root as `brand-profile.yaml`.

Confirm with user:
```
Brand profile created for [Product].

Summary:
- Audience: [primary audience]
- Tone: [tone]
- Content mix: 30% product / 70% valuable content
- Topics: [list top 3]

Saved to: ./brand-profile.yaml

Run /post [product] to generate content using this profile.
```

## Usage

```bash
# In a project directory
/brand-builder

# Or specify project name
/brand-builder volume
```

## Output

Creates `brand-profile.yaml` in:
1. Current directory (if in a project)
2. Or `~/.claude/skills/brand-builder/profiles/[product].yaml` as fallback

## Integration

Other skills use this profile:
- `/post` - Reads profile for voice, topics, hashtags
- `/announce` - Uses profile for launch messaging
- `/social-content` - Generates content calendar from topics

## Re-running

If `brand-profile.yaml` already exists:
1. Load existing profile
2. Ask if user wants to update specific sections
3. Preserve unchanged sections
4. Update modified sections

## Example Session

```
> /brand-builder

I'll help establish a brand identity for this project.
Let me gather some context first...

[Reads README, package.json, git history]

Found: "Volume" - a fitness tracking app

Question 1 of 5: Who is your primary user?
[AskUserQuestion with options]

...

Brand profile created!

Summary:
- Audience: Gym-goers tracking strength progress
- Tone: Casual & encouraging
- Topics: Strength training, progress tracking, gym tips

Saved to: ./brand-profile.yaml

Next: Run /post volume "shipped interval timer" to generate a launch post.
```