mkt-brand-voice
Skill0 starsChanged 47 days agoMITView on GitHub
Extract or build a brand's voice so every skill writes in their style. Triggers on: "brand voice", "writing style", "make this sound like me", "define our voice", "analyze my content", "voice guide", "how should we sound", "tone of voice", "brand personality", "analyze my website", "deep brand voice", "playbook mode", "AI-OS playbook". Four modes: Import (existing brand guidelines), Extract (analyze existing content), Build (interview from scratch — quick or deep Playbook variant), Auto-Scrape (URL provided, skill researches). Produces brand_context/voice-profile.md and brand_context/samples.md. Foundation skill — run before any execution skill that reads voice context. Does NOT trigger for positioning, audience research, or keyword work.
- Reads credentials
In this repository96 other files it gives its agents.
- AGENTS.mdAGENTS.md
- team_context/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- fin-company-cfoSkill
- fin-invoice-reconciliationSkill
- fin-month-end-reportingSkill
- fin-personal-cfoSkill
- meta-find-skillsSkill
- meta-memory-recallSkill
- meta-memory-writeSkill
- meta-skill-creatorSkill
- meta-skillifySkill
- meta-synthesize-localsSkill
- meta-toolifySkill
- meta-wrap-upSkill
- mkt-ab-testingSkill
- mkt-ad-creativeSkill
- mkt-adsSkill
- mkt-asoSkill
- mkt-churn-preventionSkill
- mkt-cold-emailSkill
- mkt-co-marketingSkill
- mkt-community-marketingSkill
- mkt-content-repurposingSkill
- mkt-copy-editingSkill
- mkt-copywritingSkill
- mkt-croSkill
- mkt-directory-submissionsSkill
- mkt-emailsSkill
- mkt-eventsSkill
- mkt-free-toolsSkill
- mkt-icpSkill
- mkt-influencer-marketingSkill
- mkt-jab-hookSkill
- mkt-launchSkill
- mkt-lead-magnetsSkill
- mkt-marketing-loopsSkill
- mkt-offersSkill
- mkt-onboardingSkill
- mkt-paywallsSkill
- mkt-popupsSkill
- mkt-positioningSkill
- mkt-programmatic-seoSkill
- mkt-prospectingSkill
- mkt-public-relationsSkill
- mkt-referralsSkill
- mkt-sales-enablementSkill
- mkt-schemaSkill
- mkt-signupSkill
- mkt-smsSkill
- mkt-socialSkill
- mkt-ugc-scriptsSkill
- mkt-visual-identitySkill
- ops-analyticsSkill
- ops-attributionSkill
- ops-cronSkill
- ops-ingestSkill
- ops-loopifySkill
- ops-project-managementSkill
- ops-revopsSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
26 rules. About 0 are common, 18 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈18
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 45
If it exists → Update mode.
- Distinctive: line 47
If it doesn't exist → Mode selection.
- Distinctive: line 55
If the user provides a URL in their first message, skip mode selection and go directly to Auto-Scrape.
- Distinctive: line 68
Read the provided guidelines fully
- Distinctive: line 72
Enrich offer: Ask if they want to layer on additional sources to fill gaps and add real-world samples:
- Distinctive: line 74
If yes → run Auto-Scrape or Extract on the additional sources, then merge findings into the imported profile
- Distinctive: line 75
If no → proceed with what's there, noting gaps in the profile
- Distinctive: line 79
If enriched content contradicts the guidelines, flag it: "Your guidelines say X but your LinkedIn sounds more like Y — which is the real …
- Very specific: line 97
Read references/extraction-guide.md for the full methodology — 6 dimensions, phrase harvesting, confidence zone mapping, anti-pattern …
- Very specific: line 99
After analyzing, collect 5-10 sentences that best represent the voice for samples.md.
- Very specific: line 114
If the user has already indicated a preference (e.g.
- Distinctive: line 116
If the user already produced a strong sample corpus through Import / Extract / Auto-Scrape in this session, do not offer Playbook — they …
- Very specific: line 130
Check .env for FIRECRAWL_API_KEY first
- Distinctive: line 131
If missing, use the Fallback flow below.
- Very specific: line 132
If present, use Firecrawl scrape endpoint with formats=["markdown"]
- Distinctive: line 136
When a URL is provided, also run Firecrawl branding extraction (if API key available) to auto-discover visual brand assets:
- Very specific: line 154
If Firecrawl isn't available, skip branding extraction and note: "I couldn't auto-detect your visual brand assets.
- Distinctive: line 161
Follow up with 2-3 gap-filling questions: evolution intent, hated phrases, voice inspiration
- Distinctive: line 165
If scraping fails for any reason (missing API key, site blocks requests, JS-heavy page), always offer to build brand assets anyway.
- Distinctive: line 179
Before saving any voice profile, test it with the user:
- Distinctive: line 181
Write 3 samples using the extracted or built profile:
- Distinctive: line 186
Ask: *"Does this sound like you when you're not overthinking it?"*
- Very specific: line 199
Read references/voice-profile-template.md for the exact format.
- Distinctive: line 213
After saving, show the user actual excerpts — not just confirmation of file paths.
- Very specific: line 227
If the user flags an issue with the output, add a dated entry under ## Rules in this skill's SKILL.local.md (create it if missing) and log …
- Distinctive: line 235
User can't decide on tone: Write two contrasting versions of the same sentence, ask which is closer.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Brand Voice
Outcome
Files saved to brand_context/:
voice-profile.md— the full voice system (tone, vocabulary, rhythm, platform rules)samples.md— 5-10 gold-standard sentences with source and reason notedassets.md— (Auto-Scrape only, if Firecrawl available) visual brand assets auto-discovered from URL: logo, colors, fonts, brand traits. Reports what was found and what wasn't.
The voice profile includes a structured JSON data block validated against references/voice-profile.schema.json. This enables downstream skills and automation to read voice data programmatically.
Any skill can reference these to write on-brand without asking the user about voice again.
Context Needs
| File | Load level | How it shapes this skill |
brand_context/positioning.md | Summary | Informs voice positioning — a challenger brand sounds different from a trusted advisor |
context/learnings.md | ## mkt-brand-voice section | Apply any previous corrections before starting |
Load if they exist. Proceed without them if not.
Before You Start
Check if brand_context/voice-profile.md exists.
If it exists → Update mode. Read the existing profile, show a one-paragraph summary of the current voice, and ask what they'd like to change. Don't rebuild from scratch. Before overwriting any section, show what changed and confirm.
If it doesn't exist → Mode selection. Ask:
"How do you want to set up your voice?
- I have brand guidelines — import them and I'll map everything across
- I have content samples — paste them and I'll extract your voice
- Start from scratch — I'll ask a few questions and build it
- Here's my URL — research it yourself"
If the user provides a URL in their first message, skip mode selection and go directly to Auto-Scrape. If they attach or paste a structured brand guide, go directly to Import.
Playbook note: Mode 3 (Build) has two variants — a Quick 8-question flow and a deep "AI-OS Playbook" flow. Playbook is an opt-in sub-variant of Build, never a separate mode. Only offer it when the user is entering Build mode, has no existing voice-profile.md, and hasn't already gathered a strong sample corpus from Import/Extract/Auto-Scrape. Users with an existing profile always hit Update mode and never see Playbook unless they explicitly ask for a "deep rebuild" or say "run the brand voice playbook".
Mode 1: Import
Best for: brands that already have voice/tone guidelines, brand books, or style guides.
Accepts: Pasted text, PDF, or any document containing existing brand voice guidelines.
Process:
- Read the provided guidelines fully
- Map their structure into the voice-profile.md format (see
references/voice-profile-template.md) - Flag any gaps — common missing pieces: real samples, anti-patterns (what the brand does NOT sound like), platform-specific rules, vocabulary lists
- Present a summary: "Here's what your guidelines cover and what's missing"
- Enrich offer: Ask if they want to layer on additional sources to fill gaps and add real-world samples:
- "Want me to pull from your LinkedIn, website, or other content to add real samples and fill the gaps?"
- If yes → run Auto-Scrape or Extract on the additional sources, then merge findings into the imported profile
- If no → proceed with what's there, noting gaps in the profile
Merge rules when enriching:
- The imported guidelines are the authority — enriched content fills gaps, it doesn't override
- If enriched content contradicts the guidelines, flag it: "Your guidelines say X but your LinkedIn sounds more like Y — which is the real you?"
- Samples from real content always go to
samples.md, even when the guidelines provided example copy
Mode 2: Extract
Best for: raw content — website copy, emails, social posts, newsletters, transcripts.
Sample gate: Minimum 5 samples OR 800+ total words. Under the threshold → offer Quick mode (top 5 traits + 3 rules) or ask for more content.
Sample priority — most to least authentic:
- Slack messages or casual emails (raw, unedited)
- Podcast or call transcripts
- Social posts (LinkedIn, Twitter)
- Website copy (most edited, least authentic)
Run the extraction:
Read references/extraction-guide.md for the full methodology — 6 dimensions, phrase harvesting, confidence zone mapping, anti-pattern sourcing, and self-critique checklist.
After analyzing, collect 5-10 sentences that best represent the voice for samples.md.
Mode 3: Build
Best for: starting fresh, or existing content is too generic to reliably extract from.
Quick vs Deep fork (ask this first):
"Quick setup (5-8 targeted questions, ~5 min) or the full AI-OS playbook (deeper interview, ~10-15 min, better for people starting from zero)?"
- Quick → use
references/build-questions.md. Ask a maximum of 8 questions, prioritised by what context is already loaded. Ifpositioning.mdis loaded, skip questions it already answers. After building, ask for 2-3 sample sentences forsamples.md. - Playbook → use
references/playbook-questions.md. Walk through Step 1 (Personality, 5 questions), Step 2 (Strategic Framework, 4 questions — skip Q1/Q2 ificp.md/positioning.mdexist), and Step 3 (Example Collection). Samples collected during the interview feed directly intosamples.md. Follow the Playbook's Synthesis Instructions — derive every characteristic from the user's actual answers, never template from the example brief.
If the user has already indicated a preference (e.g. the /start-here flow passed through a "deep flow" flag, or the user said "run the brand voice playbook"), skip the fork and route directly to the matching variant.
If the user already produced a strong sample corpus through Import / Extract / Auto-Scrape in this session, do not offer Playbook — they already have the raw material; keep Build as Quick.
Mode 4: Auto-Scrape
Best for: user provides a URL and wants research done for them.
Scraping Strategy
Try sources in this order, using the cheapest tool that works:
- WebFetch first (free) — try homepage, About page, 2-3 blog posts, LinkedIn
- If WebFetch fails (JS-heavy site, bot protection, empty content) → fall back to
tool-firecrawl-scraperskill- Check
.envforFIRECRAWL_API_KEYfirst - If missing, use the Fallback flow below.
- If present, use Firecrawl scrape endpoint with
formats=["markdown"]
- Check
Brand Asset Extraction
When a URL is provided, also run Firecrawl branding extraction (if API key available) to auto-discover visual brand assets:
formats=["branding"] → colors, fonts, logos, spacing, brand traitsReport back to the user:
Found from your site:
- Logo: [URL or "not found"]
- Primary colors: [hex values or "not found"]
- Fonts: [font names or "not found"]
- Brand traits: [if detected]
Couldn't find automatically:
- [List anything missing — social handles, brand photography, etc.]
You can add these manually to
brand_context/assets.md.
If Firecrawl isn't available, skip branding extraction and note: "I couldn't auto-detect your visual brand assets. You can add them manually to brand_context/assets.md later."
Voice Extraction Process
- Fetch content from: homepage, About page, 2-3 blog posts, LinkedIn bio + recent posts, Twitter/X
- Report what was found (pages, word count, quality signal)
- Feed all content into Extract mode (Mode 2)
- Follow up with 2-3 gap-filling questions: evolution intent, hated phrases, voice inspiration
Fallback — Never Block Brand Asset Creation
If scraping fails for any reason (missing API key, site blocks requests, JS-heavy page), always offer to build brand assets anyway. Never stop the flow because a URL couldn't be scraped.
When a URL can't be scraped, ask the user:
"I couldn't scrape that URL — [reason]. Two options:
- Add your API key now — paste your
FIRECRAWL_API_KEYand I'll retry immediately- Build your brand assets now — I'll ask you a few questions instead, and we can scrape the URL later to enrich everything"
If the user picks option 2 (or doesn't have a key), switch to Build mode (Mode 3) and complete the full voice profile, samples, and any other brand assets. The URL stays noted in the profile so it can be scraped in a future session to enrich the existing profile.
Step 5: Voice Test (All Modes)
Before saving any voice profile, test it with the user:
Write 3 samples using the extracted or built profile:
- A 3-4 sentence email opening
- A social post (match their most-used platform)
- A landing page headline + 2 supporting sentences
Ask: "Does this sound like you when you're not overthinking it?"
- Yes → save
- Close but off → ask what's wrong, adjust specific sections, retest
- Not right → ask for an example that IS right, re-extract from it
Cap at 3 rounds. If still unresolved, offer to save current version and refine over time using /brand-voice again.
Step 6: Save Output
brand_context/voice-profile.md
Read references/voice-profile-template.md for the exact format. All sections required.
Include a structured JSON data block at the end (inside a <details> tag) that conforms to references/voice-profile.schema.json. Read the schema before generating the JSON to ensure all required fields are present.
If Playbook mode was used, ensure every section in voice-profile.md is traceable to a specific answer — no templated language from the example brief. Core Voice Characteristics must be named from the user's actual words; signature phrases must be their actual phrases; the never list must reflect their Q1 anti-corporate answer.
brand_context/samples.md
5-10 sentences. For each, note: source type, and why it's representative.
## [Source] — [e.g., email to list / LinkedIn post / homepage]
"[Sentence exactly as written]"
*Why it's representative: [1 sentence]*After saving, show the user actual excerpts — not just confirmation of file paths.
Rules
Updated automatically when the user flags issues. Read before every run.
- 2026-04-29: Match output language to the user's language. If the user writes in Portuguese, produce the voice profile, samples, and all questions in Portuguese. Never default to English when the user hasn't written in English.
Self-Update
If the user flags an issue with the output, add a dated entry under ## Rules in this skill's SKILL.local.md (create it if missing) and log it to context/learnings.md under ## mkt-brand-voice. Write the general rule the correction implies, not the one-off fix.
Troubleshooting
Not enough samples: Request more content, or switch to Build mode. Voice feels generic after extraction: Website copy is often sanitised. Ask for emails or Slack messages. User can't decide on tone: Write two contrasting versions of the same sentence, ask which is closer. Positioning not loaded: Proceed, but note it would sharpen the voice positioning. Profile already exists but user wants to start over: Confirm before overwriting. Offer to save old version with a date suffix.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

