Generate Voice Guide Agent Skill

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:

• 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."
• Which platforms? "Generate a voice guide for X, LinkedIn, or both?"
• How many posts to scan? "Default: 50 X posts / 25 LinkedIn posts. Higher = more signal, more tokens, slower."
• 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:

• 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).
• 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
• 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?"
• 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.
• 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

• Write the final guide to the resolved output path (default ~/.goose-skills/voice-guides/voice-<platform>.md).
• Strip the iteration changelog — only keep the final clean guide.
• Update ~/.goose-skills/config.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).

• 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 with analysis. Aim for 120–250 lines.

Config File

~/.goose-skills/config.json is a lightweight cross-skill config. Schema:

{
  "voice_guides": {
    "x": "/absolute/path/to/voice-x.md",
    "linkedin": "/absolute/path/to/voice-linkedin.md"
  }
}

Sibling skills read this to discover voice guide paths. Always use absolute paths.

Inputs

| Input | Required | Default |

|-------|----------|---------|

| --profile | Yes (one of X handle, LinkedIn URL, or both) | — |

| --platforms | No | x,linkedin if both profiles given, else matches supplied profiles |

| --posts-x | No | 50 |

| --posts-linkedin | No | 25 |

| --output | No | ~/.goose-skills/voice-guides |

| --iterations-min | No | 5 |

Outputs

• <output>/voice-x.md and/or <output>/voice-linkedin.md
• Updated ~/.goose-skills/config.json with voice guide paths
• Stdout summary: paths written + quick-start command for next step

Dependencies

• Apify API token (APIFY_API_TOKEN) for scraping
• No other paid services required
• Voice guide *structural* references (open via WebFetch or read locally if the user has them) — not required to run

Tips

• 5+ iterations is the floor. If the user pushes to stop early, explain that voice guides are only good after ~5 rounds.
• Use the user's own topics for samples. Draft samples on subjects they've posted about — makes it much easier for them to spot an off-key line.
• Quote real posts in the examples section. Never paraphrase — use direct verbatim quotes with a source link.
• Call out ghost-writing or assistant-authored posts. If some posts feel dramatically different, flag it: "These 3 posts read differently — worth checking if they're yours or ghost-written."
• Don't lean on LLM clichés in the banned-phrases list. Derive bans from actual absence in the user's writing, not a generic blocklist.