/brand-context

name: brand-context
description: "Create and maintain a single brand-context.md — positioning, audience, personas, pain points, customer language, voice, proof points — that every other marketing skill reads before asking the user to re-explain their business. Auto-drafts from the brand's site via Firecrawl, or builds the doc through a short interview. Use when the user wants to set up brand context, onboard a new brand, define positioning / brand voice / ICP, or complains about re-answering the same brand questions."
metadata:
  version: 1.0.0
icon: hyper
short_description: One brand-context.md per brand — the shared positioning, audience, and voice doc every other skill reads first.

Brand Context

Build and maintain **one `brand-context.md` file per brand**: the single source of truth for what the business sells, who it sells to, how it talks, and what it can prove. Every other skill in this collection reads this file before asking the user brand questions, so the user explains their business once — not once per task.

This is the hub in a hub-and-spoke model. Ad copy, blog posts, cold email, social content, and landing-page work are all downstream of the same positioning and voice; when those live in one maintained doc, every downstream skill starts warm and stays consistent.

> **The file contract.** The doc lives in persistent storage at a stable path — `/files/<brand-slug>/brand-context.md` — and is reused at that SAME path every time. Create it once, then **update it in place**; never recreate it from scratch when it already exists (you would destroy verbatim customer language and proof points the user curated). If a run touches the doc, bump the `Last updated` line.

Requirements

• **Hyper MCP connected.** https://app.hyperfx.ai/mcp — needed for the file tools that persist the doc, and for auto-draft.
• **Recommended for auto-draft**, enabled at https://app.hyperfx.ai/apps: **Firecrawl** (read the brand's site and extract visual identity). Without it, skip auto-draft and use the interview path — the skill still works.
• **Optional enrichment:** the Apify scrapers used by `customer-research` (verbatim customer language) and **HyperSEO** (competitive landscape). Both are nice-to-have; mark any section built without real data as unverified rather than inventing content.

How to run the tools in this skill

Every tool in this skill is named by its canonical tool name. Run it with the call your surface gives you:

| Surface | Find a tool | Run it | | --- | --- | --- | | Hyper chat | Call the tool by its name; `search_tools(queries=["<provider> <action>"])` shows its parameters | `<name>(...)` | | MCP client (Claude, Cursor, Codex, ChatGPT) | `search("<what you want to do>")`, then `describe("<name>")` | `call_read("<name>", {...})`, `call_write` or `call_destructive`: the one that `describe` names in `call_with` | | Hyper CLI | `hyperai search "<what you want to do>"`, then `hyperai describe <name>` | `hyperai call <name> --json '{...}'` |

If a tool is not found: in Hyper chat, find its toolkit id with `discover_toolkits` and pass it to `enable_toolkit`. On an MCP client or the CLI, tell the user which integration to connect in Hyper.

Tool surface

| Job | Tools | | --- | --- | | Read, create, update `brand-context.md` | your file tools (`read_file`, `create_file`, `edit_file`) | | Auto-draft from the brand's site | `firecrawl_urls_scrape` (homepage, about, pricing, product pages), `web_pages_fetch` fallback | | Visual identity (colors, logo, typography) | `firecrawl_branding_extract` | | Verbatim customer language (optional) | defer to `customer-research` | | Competitive landscape (optional) | defer to `competitor-intel`, `seo-research` |

Out of scope: defer to other skills

| Request | Send them to | | --- | --- | | Deep voice-of-customer mining (Reddit, reviews, social) | `customer-research` | | Full competitor research, battle cards, monitoring | `competitor-intel` | | Blog topic strategy and the published-post log | `blog-generation` (its `blog-strategy.md` **Brand brief** should be seeded from this doc, not rebuilt) | | Extracting brand assets for image generation | `ad-creative-generation` (`firecrawl_branding_extract` at creative time) | | Keyword or SERP research | `seo-research` |

The document

The full template with per-section guidance lives in `references/brand-context-template.md`. The sections, in order:

1. **Product overview** — what it is, what it does, category, one-liner. 2. **Target audience / ICP** — the specific customer, firmographics or demographics, who it is NOT for. 3. **Personas** — 2–4 buyer/user personas with role, trigger, and success criteria. 4. **Pain points** — the problems that drive purchase, ranked. 5. **Competitive landscape** — direct and indirect alternatives, including "do nothing" / spreadsheets / status quo. 6. **Differentiation** — why customers pick this brand over each alternative; what only this brand can claim. 7. **Objections & switching** — what stalls deals, what prospects fear, what switching costs them. 8. **Customer language** — verbatim quotes: how customers describe the problem and the product in their own words. The most valuable section in the doc. 9. **Brand voice** — tone, reading level, point of view, words to use, words to ban. 10. **Proof points** — real numbers, named customers, credentials, data. Only verified items belong here. 11. **Goals & current focus** — what marketing is trying to move this quarter, priority channels. 12. **Assets & channels** — site URL, blog, social handles, ad accounts in play, visual identity notes.

Building the doc

**Step 0: check for an existing doc.** Look for `brand-context.md` at the brand's path (and reasonable legacy locations). If one exists, this is an **update** run: read it fully, then only revise the sections the user wants changed or that new evidence contradicts. Only when nothing exists do you build fresh.

**Path A — auto-draft (default wh