generate-voice-guide

# Generate Voice Guide

Turn a real person's past posts into a structured voice guide that other skills can use to draft in-voice content. Produces one guide per platform (X, LinkedIn, or both) with persona, dos/don'ts, banned phrases, hook patterns, format rules, and example posts.

**This is an agent-executed skill** — the agent handles scraping, analysis, drafting, and iteration via the tools available in the session. No bundled Python script.

## When to use

- A user wants to build a personal voice guide for social content
- Another skill (e.g. `create-x-content`, `create-linkedin-content`, `social-kit`) needs a voice guide and one doesn't exist
- The user wants to mimic someone else's public voice (for ghostwriting, parody, or study)

**When NOT to use:** For analysing a company's blog/landing-page voice, use `brand-voice-extractor` instead. That's for corporate marketing voice; this one is for individual social voice.

## Quick Start

Interactive:
```
/generate-voice-guide
```

Args mode:
```
/generate-voice-guide --profile @GooseworksAI --platforms x,linkedin --output ~/.goose-skills/voice-guides
```

## Discovery Questions (front-loaded)

Ask these up front if not supplied via flags:

1. **Whose voice?** "Paste an X/Twitter handle (e.g. `@GooseworksAI`), a LinkedIn profile URL, or both. You can mimic your own voice or someone else's."
2. **Which platforms?** "Generate a voice guide for X, LinkedIn, or both?"
3. **How many posts to scan?** "Default: 50 X posts / 25 LinkedIn posts. Higher = more signal, more tokens, slower."
4. **Save location?** "Default: `~/.goose-skills/voice-guides/voice-{x,linkedin}.md`. Ok to use that, or prefer a different path?"

## Workflow

### Phase 1 — Scrape past posts

**For X:**
- Use Apify actor `apidojo/twitter-user-tweets-scraper` (or whichever X scraper is available in the session) keyed to the handle.
- Fetch the target count (default 50). Exclude replies, retweets, and quote tweets unless the user specifies otherwise — we want original voice.
- Requires `APIFY_API_TOKEN` env var. If missing, surface a clear error with the setup link.

**For LinkedIn:**
- Use Apify actor `harvestapi/linkedin-profile-posts` keyed to the profile URL.
- Fetch the target count (default 25). Include only original posts (no reshares).

**Fallback (no scraper available or posts paywalled):** ask the user to paste 15–25 posts as plain text.

Store raw post text, engagement metrics (likes, views if available), and timestamps.

### Phase 2 — Generate v1 voice guide

Use `voice-x.md` / `voice-linkedin.md` template references (see "Template Skeleton" below) to produce v1 of the guide. Do NOT copy content from them — only the *structure*.

Analyse the scraped posts for:

- **Persona** — inferred role, audience, credentials, tone spectrum
- **The "meat" principle** — what concrete substance typically appears: tools, numbers, builds, steps, links
- **Dos** — observed hook patterns, connective phrases, list style, casual asides, emoji usage, CTA patterns
- **Don'ts** — patterns the author conspicuously avoids (no threads, no engagement bait, etc.)
- **Banned phrases** — common LLM-speak the author never uses (`excited to share`, `leverage`, `game-changing`, `thrilled`, etc.). List 10–20.
- **Hook patterns** — 5–8 distinct opening-line templates drawn from real posts
- **Format rules** — word count ranges, bullet style, density, line-break rhythm
- **Tone calibration** — educator vs conversational ratio; when each applies
- **Example posts with analysis** — pull 4–6 real posts and explain *why* each works, what pattern it exemplifies

### Phase 3 — Sample + feedback loop (5+ iterations)

This is where voice-guide quality is made. Do NOT skip iterations.

Each iteration:

1. **Generate 3 sample posts** from the current guide, each using a different hook pattern from the guide. Use topics from the user's own posting history so they're easy to judge (e.g. if they post about AI agents, draft on AI agents).
2. **Show the user:**
   - Which hook pattern each sample used
   - The 3 sample posts
   - 1–2 lines from the current guide that most influenced the samples
3. **Ask for feedback** — specific prompts:
   - "Which samples sound like you? Which don't?"
   - "What's the most off-sounding phrase or pattern?"
   - "What's missing — a hook you use, a rule you follow?"
4. **Apply feedback** — revise the guide. Update dos/don'ts, hook patterns, banned phrases, examples. Note what changed in a short changelog at the top of the guide during iteration.
5. **Repeat.**

**Stopping rule:** continue until the user explicitly says "this is good" AND at least 5 iterations have completed. 5 is a floor, not a ceiling. If the user says "good enough" at iteration 2, push back: "Voice guides need at least 5 rounds to actually lock in. Can we do 3 more?"

### Phase 4 — Save + register

1. Write the final guide to the resolved output path (default `~/.goose-skills/voice-guides/voice-<platform>.md`).
2. Strip the iteration changelog — only keep the final clean guide.
3. Update `~/.goose-skills/config.json`:
   ```json
   {
     "voice_guides": {
       "x": "<absolute path to voice-x.md>",
       "linkedin": "<absolute path to voice-linkedin.md>"
     }
   }
   ```
   Create the directory/file if missing. Merge with existing config if present (don't overwrite other keys).
4. Print a confirmation with the saved paths and a next-step suggestion: "You can now run `/create-x-content --brief \"...\"` and it'll use this voice guide automatically."

## Template Skeleton

Every generated voice guide should have these top-level sections, in order:

```
# Voice Guide: <Platform> — <Handle or Name>

## Persona
## The "Meat" Principle
## Dos
## Don'ts
## Banned Phrases
## Hook Patterns
## CTA Guidelines
## Format Rules
## Tone Calibration
## Example Posts That Exemplify The Voice
```

Match the depth and specificity of a well-written voice guide — prose for persona, numbered lists for dos/don'ts, quoted examples w