BrightSite

View saved version →

---
name: blog-post-from-outline
description: Turn an outline (bullet points, headings, or a rough brief) into a full BrightSite blog post draft with proper structure, meta title, meta description, and excerpt. Always creates as `draft` — never publishes. Use when the user mentions "draft a blog post," "write a post from this outline," "turn this into a blog post," "blog draft," "post from brief," or has a structured outline they want fleshed out.
---

# Blog Post from Outline

Take a structured outline and produce a publishable-quality draft post in BrightSite. The agency reviews and edits before publishing.

This skill is intentionally NOT a "generate me a blog post from a topic" prompt. That produces generic, low-value content. This skill requires the user to have already done the thinking — outline, key points, target keyword — and turns that thinking into a clean draft.

## When to use this

- Agency has a content brief from a client and needs a fast draft.
- Subject matter expert recorded a voice memo / Loom and the agency has a transcript outline.
- Writer has a structured outline but doesn't want to write the connective prose.

Do NOT use this for:
- Generating posts from just a title or topic (output will be generic).
- Long-form pillar content (>2000 words) — the model produces better results with more iteration; do it in pieces.

## Inputs you need from the user

1. **Account ID**
2. **Outline** — bullet points, H2/H3 headings, key claims. The more structured, the better.
3. **Target keyword** — the primary phrase the post should rank for.
4. **Audience** — one sentence on who this is written for (e.g. "small business owners evaluating CRMs," "homeowners considering solar").
5. **Voice/tone reference** — link to or paste an existing post the client has written, OR describe the tone ("conversational, no fluff, US English").
6. **Word count target** — default 800-1200 words.
7. **CTA** — what action should the reader take at the end?

## Workflow

### Step 1: Confirm understanding

Before drafting, parrot back to the user:
- The H2 structure you'll use
- The target keyword and where you'll place it (title, H1, first 100 words, one H2, meta)
- The CTA
- The voice you're targeting

Wait for confirmation. Don't draft if any of those are unclear — go back and ask.

### Step 2: Draft the post

Write the post following these constraints:

- **Title**: under 60 chars, includes the target keyword naturally, action/benefit-oriented (not "How to do X" if there's a better angle).
- **First paragraph**: hook the reader in 2-3 sentences, mention the target keyword once, set up what the rest of the post delivers. No "In today's fast-paced world" openers.
- **H2 structure**: matches the outline. Each H2 should contain at least one tangible takeaway, example, or piece of evidence — not just transitional copy.
- **Voice**: match the reference. If no reference, default to: short sentences, active voice, no buzzwords (utilize, leverage, synergy), no AI tells ("dive in," "unleash," "in conclusion").
- **CTA**: one paragraph at the end. Direct ask, not a soft "let us know what you think."
- **Internal links**: if the user mentioned related posts or pages, work in 1-2 natural internal links.
- **Length**: hit the word count target ±15%.

### Step 3: Generate the metadata

- `meta_title` — under 60 chars. Often the same as the post title, but can be tighter for search.
- `meta_description` — 130-155 chars. Includes the target keyword. Reads like a benefit, not a summary.
- `excerpt` — 1-2 sentences, used on the blog listing page. Should make someone want to click. Different from meta_description (meta is for Google, excerpt is for humans browsing your blog).
- `slug` — kebab-case version of the title, but trim stop words. Under 60 chars.

### Step 4: Show the user the draft before creating

Output the full post in markdown to the user with a clear delineation:

```
--- DRAFT PREVIEW ---
Title: ...
Slug: ...
Meta title: ...
Meta description:

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: bulk-seo-audit
description: Audit every page and post on a BrightSite site for on-page SEO issues. Checks title length, meta description length and presence, H1 presence and uniqueness, canonical URLs, og:image, robots directives, and slug quality. Outputs a prioritized fix list grouped by severity. Use when the user mentions "SEO audit," "on-page SEO," "check my pages for SEO," "find SEO issues," "before launch SEO check," or wants a pre-handoff QA pass on a client site.
---

# Bulk SEO Audit

Walk every page and post on a BrightSite site, evaluate on-page SEO basics, and produce a triaged report. This is for catching common issues at scale — it does NOT replace a real SEO audit that includes backlinks, Core Web Vitals, or rank tracking.

## When to use this

- Agency is about to hand off a client site and wants a final QA pass.
- Client's traffic has dropped and you want to rule out on-page issues.
- After a migration (e.g. after running the `migrate-wordpress-blog` skill).
- Periodic check on a live site every 30-90 days.

## Inputs you need from the user

1. **Account ID** — the BrightSite account to audit.
2. **Scope** — pages only, posts only, or both? Default: both.
3. **Severity threshold** — show all issues, or only critical + warnings? Default: all.

## Workflow

### Step 1: Pull the inventory

- `mcp__brightsite__list_pages` for all pages
- `mcp__brightsite__list_posts` for all posts

Note the counts and tell the user how many entities you're about to audit. If it's >200, ask for confirmation to proceed.

### Step 2: Fetch and evaluate each entity

For each page or post, call `mcp__brightsite__get_page` or `mcp__brightsite__get_post`. Pages return both `heex` (live) and `heex_staged` (latest unpublished); posts return `content` and `content_staged`. **Audit both** — issues in `*_staged` will go live the next time the user publishes. Group findings by which version is affected so the user knows whether to publish a fix or just edit the live entity.

Evaluate against these checks:

**Critical** (must fix — actively hurts SEO)
- `meta_title` empty or > 60 chars → truncated in SERPs
- `meta_description` empty → Google generates one, often badly
- `slug` contains spaces, capital letters, or special chars
- Two or more entities share the same slug
- HEEx/content body is empty or under 300 chars (check both live and staged)

**Warning** (should fix)
- `meta_title` < 30 chars (too short, missing keywords)
- `meta_description` < 70 chars or > 155 chars
- No H1 in the HEEx/content (check both live and staged)
- More than one H1 in the HEEx/content (check both live and staged)
- `canonical_url` set but points off-domain (suspicious — usually means duplicate content)
- `og_image_id` missing → poor social sharing previews. Note: most BrightSite templates fall back to the post's `feature_image_id` (or the site identity logo) when `og_image_id` is null, so only flag this if neither fallback exists. For pages, flag any page where `og_image_id` is null AND the site has no logo.
- Title and meta_title are identical (missed opportunity to differentiate for search vs. display)
- `meta_robots` contains `noindex` — could be intentional (a thank-you page, an internal tool page). Surface each match and ask the user to confirm whether it's deliberate.

**Info** (nice to fix)
- Slug is very long (> 60 chars)
- Slug contains stop words (`the`, `a`, `and`, `of`)
- `meta_description` doesn't mention any word from the title
- Post missing both `feature_image_url` and `feature_image_id`

### Step 3: Output the report

Format as a markdown table grouped by severity, then by entity type. For each issue, include:

- Severity marker (use `[!]` for critical, `[~]` for warning, `[i]` for info — no emojis unless user asked)
- Entity type and title
- The specific issue
- Suggested fix
- Page/post ID (so the user can jump to it in the editor)

End with a summary block:

```
Audit summary
-------------
Pages audited: 42
Posts audited: 118
Critica

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: client-handoff-checklist
description: Pre-launch QA pass for a BrightSite site before handing it to a client or going live. Verifies site identity, error pages, blog settings, forms, redirects, analytics, and meta defaults are all configured. Outputs a checklist with green/yellow/red status. Use when the user mentions "client handoff," "pre-launch checklist," "launch QA," "going live," "ready to ship," "is this site ready," or wants a final QA pass before publishing a site.
---

# Client Handoff Checklist

Every agency forgets something. This is the "before you push the launch button" QA pass for a BrightSite site. Run it the day before going live.

> If the launch is a **redesign built on a staging site**, run this checklist against the
> staging site (pass `site: "staging"` on the read tools below, or point at the staging
> `preview_url`) *before* you `promote_staging`. See the `staging-redesign` skill.

## When to use this

- About to point the domain at a BrightSite site.
- About to email the client login credentials.
- Just finished a site build and want to know what you missed.

## Inputs you need from the user

1. **Account ID**
2. **Public URL** — what URL will visitors hit? (Used to validate canonical URLs.)
3. **Anything skip-worthy?** — e.g. "no blog on this site, skip blog checks" or "no contact form, skip form checks."

## Workflow

Run through every check below. For each, report `[OK]`, `[WARN]`, or `[FAIL]` and a one-line summary. Use plain text markers — no emojis unless the user explicitly asked for them.

### 1. Site identity (`mcp__brightsite__get_site_identity`)

- `[FAIL]` if `title` is empty or still "Untitled Site" / default
- `[FAIL]` if `logo_id` is null
- `[WARN]` if `icon_id` (favicon) is null
- `[FAIL]` if `business_type` is null (hurts schema/structured data)
- `[WARN]` if `business_description` is missing
- `[WARN]` if `email` or `phone` is missing (clients usually want at least one contact method)
- For local businesses: `[WARN]` if address fields are missing or `geo_lat`/`geo_lng` is null
- `[WARN]` if `social_profiles` is empty

### 2. Pages (`mcp__brightsite__list_pages` + `mcp__brightsite__get_page` on each)

- `[FAIL]` if no page has `is_home_page: true`
- `[FAIL]` if any page has `status` of `draft` and is linked from the homepage (sanity-check by scanning the home page HEEx for internal links)
- `[WARN]` if any page has `has_unpublished_changes: true` — those staged changes won't be live
- `[FAIL]` for any page missing `meta_title` or `meta_description`
- `[WARN]` for pages where `canonical_url` is set to a different domain than the public URL

Run a mini-version of `bulk-seo-audit` inline — count and report total SEO issues across all pages.

### 3. Error pages (`mcp__brightsite__list_error_pages`)

The returned rows expose the HTTP status as `status_code` (integer), so filter on that field.

- `[FAIL]` if no row with `status_code: 404` exists
- `[WARN]` if no row with `status_code: 500` exists
- `[WARN]` if any error page has `has_unpublished_changes: true`

### 4. Blog settings (`mcp__brightsite__get_blog_settings`) — skip if user said no blog

- `[OK]` to skip if `enabled: false` and user confirmed no blog
- `[FAIL]` if `enabled: true` but `blog_title` is empty
- `[WARN]` if `blog_url` or `listing_url` are missing or do not start with `/`. These are path settings, not full domains.
- `[WARN]` if `posts_per_page` is null or absurd (< 3 or > 50)
- `[WARN]` if `enable_open_graph` is `false` (poor social sharing)

### 5. Posts (`mcp__brightsite__list_posts` + `mcp__brightsite__get_post` on each) — skip if no blog

- `[WARN]` if zero published posts (clients usually want at least 1-3 launch posts)
- `[WARN]` if any post has `has_unpublished_changes: true`
- Inline mini-audit: fetch each post with `mcp__brightsite__get_post`, then count posts missing `meta_description` or both `feature_image_url` and `feature_image_id`

### 6. Forms (`mcp__brightsite__list_forms`) — skip if user sa

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: staging-redesign
description: Build a BrightSite redesign or large change safely on a staging site, preview it, then promote it live in one atomic flip — instead of editing the live site directly. Use when the user wants a "staging site," "redesign safely," "build a new version without breaking the live site," "preview before it goes live," "rebuild the homepage," "flip the whole site at once," "a safe place to work," or is doing a full visual rebuild (new fonts/layout/multiple pages) they don't want visitors to see until it's ready. For per-entity staged edits on the live site (a single page's unpublished draft), the normal `*_staged` + `publish_page` flow is enough — use this skill only when you want a full isolated copy.
---

# Build a Redesign on a Staging Site, Then Promote

A **staging site** is a full, independent, editable copy of the live site's content
(pages, layouts, components, forms, blog, media, global CSS/JS, Tailwind config, site
identity, redirects) that lives under the same account. You build the redesign on it
invisibly, preview it at a gated subdomain, then **promote** it — one atomic flip that
makes the staging content live and archives the old live site (restorable). Account-level
data (custom domain, analytics, form submissions, team, billing, tracking IDs) is shared
and never touched by a promote.

Use this instead of editing the live site directly whenever the change is big enough that
you don't want visitors seeing a half-finished state, or you need to flip several entities
(global code + a layout swap + N pages) at the same moment.

## When to use this vs. the normal staged-fields flow

| Situation | Use |
|---|---|
| One page's copy tweak, a new draft page, a blog post | Normal flow: `update_page` writes `*_staged`, `publish_page` ships it. Live stays as-is until you publish. |
| Full redesign, new global fonts/layout, multi-page rebuild, "flip it all at once", "let me preview the whole thing first" | **This skill** — a staging site. |

The staged-fields flow only stages *content* fields (`heex_staged`, `css_staged`, …).
Structural fields — `layout_id`, `slug`, `status`, `is_home_page`, `meta_*`, and anything
`update_site_identity` sets — take effect on the **live** site immediately, with no staged
variant. A staging site stages *everything*, which is why it's the right tool for a rebuild.

## Key mechanic: the `site` param

Every content tool (`create_page`, `update_page`, `update_layout`, `update_global_code`,
`create_component`, `request_upload`, `update_site_identity`, `list_pages`, `get_page`, …)
takes an optional **`site`** param:

- **omitted** or `"live"` → the live site (default, backwards-compatible).
- `"staging"` → the account's staging site.
- an explicit **site ID** (from `list_staging_sites`) → that specific site, as long as it's
  **active** (`live` or `staging`). Archived sites (rollback snapshots) are rejected —
  they're immutable history; `restore_staging_site` first if you need to edit one.

Authorization is still by `account_id` — you must be a member of the org, and the target
site must belong to it. Passing a staging site ID as `account_id` does **not** work (it's a
site, not an account); always pass `account_id` = the org and select the site with `site`.

## Workflow

### 1. Create the staging site

```
mcp__brightsite__create_staging_site { account_id: "<ORG_ID>" }
  → { id, name, slug, type: "staging", preview_url, ... }
```

This clones the live site synchronously (content + media). It is **plan-gated** — it fails
with a "plan" / "limit" message if staging isn't on the account's plan or a staging site
already exists. If one already exists, either reuse it or `discard_staging_site` first.

Keep the returned `id` and `preview_url`. You can also fetch them any time with
`mcp__brightsite__list_staging_sites` or `mcp__brightsite__get_staging_status`.

### 2. Author into staging — pass `site: "staging"` on every write

Build the redesign exactly as you normally would

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: visual-editor-audit
description: Audit an existing BrightSite site for visual-editor editability — walk every page, component, and layout and flag what a non-technical user cannot edit (no data-bs-edit markers, components with empty props_schema, bare loops for repeating content, hardcoded internal links), then optionally fix it. Use when the user says "check what's editable," "the client can't edit X in the editor," "why can't I edit this," "audit the site for the visual editor," "make the existing site editable," "fix editability," or wants a pre-handoff QA pass on whether the site is editable. For authoring new content correctly the first time, use the visual-editor-authoring skill instead.
---

# Visual Editor Editability Audit

Walk every page, component, and layout on a BrightSite site and report what is **not
editable in the visual editor** — the things a non-technical client can't click and change
— then optionally fix them. This is the reactive counterpart to `visual-editor-authoring`
(which prevents the problem at create time).

The rules this audit enforces live in
**[editability-contract.md](editability-contract.md)** (in this skill's directory).
Read that file first; it is the source of truth for every check below.

## When to use this

- A client says they can't edit something in the visual editor.
- Pre-handoff QA: confirm the site is actually self-editable before giving it to the client.
- After a site was built quickly (or by another tool) and you suspect it's full of raw HTML.
- After running `visual-editor-authoring` on a large build, as a verification pass.

If you're creating new content, don't audit after — author it right the first time with the
`visual-editor-authoring` skill.

## Inputs you need from the user

1. **Account ID** — the BrightSite account to audit.
2. **Scope** — pages, components, layouts, or all. Default: all.
3. **Fix mode** — report only, or report then offer to fix? Default: report, then offer.

## The contract in one sentence

> The editor sees exactly two editable things: elements tagged `data-bs-edit="field"`, and
> `component()` instances whose component has a **non-empty `props_schema`**. Everything
> else is invisible.

Every check below is a way the authored content fails that rule.

## Workflow

### Step 1: Pull the inventory

- `mcp__brightsite__list_pages`
- `mcp__brightsite__list_components`
- `mcp__brightsite__list_layouts`

Report the counts before you start. If it's a large site (>150 entities), audit in batches
(≤5 concurrent) and tell the user you're throttling.

### Step 2: Fetch and evaluate each entity

For each entity, fetch with `get_page` / `get_component` / `get_layout`. Pages and layouts
return both live (`heex`) and staged (`heex_staged`) bodies — **audit both**, because a
staged body goes live on the next publish. Components return their `heex` and `props_schema`.

Evaluate against these checks:

**Critical** (the user genuinely cannot edit this content)

- **Page/layout has zero editable nodes** — no `data-bs-edit` anywhere AND no embedded
  `component(...)`. The whole body is one opaque "Page Content" block.
- **Component has an empty `props_schema` (`{}`)** but its `heex` contains content/props.
  The editor shows "no editable properties." (Caused by `create_component` without the
  follow-up `update_component`.)
- **Repeating content rendered with a bare `:for`** (a `:for` with no surrounding
  `data-bs-collection`/`data-bs-item` and not driven by a component `item_schema`). Items
  can't be added, removed, reordered, or individually edited.
- **A collection prop's rendered loop has no `data-bs-collection`/`data-bs-item`/
  `data-bs-edit` markers** — even when the component's `props_schema` has a populated
  `item_schema`. Symptom: the panel shows empty placeholder fields for each item, and the
  cards on the canvas don't hover-highlight or click-select. The `item_schema` makes the prop
  appear; the rendered markers make it editable. Fix: add 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: visual-editor-authoring
description: Author BrightSite pages, components, and layouts whose content is editable in the visual editor — so a non-technical user can click and change text, images, links, and component props without a second pass. Use when creating or editing a page/component/layout via the BrightSite MCP (create_page, update_page, create_component, create_layout), when building a site or template, or when the user says "make this editable," "the client should be able to edit this," "build the site so they can change it themselves," or "use the visual editor / components properly." Load this BEFORE writing HEEx, not after.
---

# Author Visual-Editor-Editable Content

BrightSite content authored as plain HEEx renders fine on the public site but is often
**not editable in the visual editor** — the user can't click an element to change its text,
swap an image, or edit a component's props. They then have to come back and ask for it to
be "made editable." This skill makes you author it correctly the first time.

Read **[editability-contract.md](editability-contract.md)** (in this skill's directory) in
full before authoring. It is the source of truth for every rule below. This file is the
how-to; the contract is the reference.

## When to use this

- You are about to call `create_page`, `update_page`, `create_component`,
  `update_component`, or `create_layout` and the content should be client-editable.
- You're building a whole site, a template, or a default/starter layout.
- The user wants non-technical end users (small-business owners) to self-edit content.

If you're only auditing or fixing an **existing** site for editability, use the
`visual-editor-audit` skill instead.

If you're doing a **full redesign or large rebuild** that shouldn't be visible on the live
site until it's ready, build it on a **staging site** — load the `staging-redesign` skill
and pass `site: "staging"` on the authoring calls below (it composes with every rule here).

## The rule that prevents 90% of second passes

> The editor sees exactly two editable things: elements tagged `data-bs-edit="field"`, and
> `component()` instances whose component has a **non-empty `props_schema`**. Raw HTML is
> invisible.

So before you write any HEEx, decide for each meaningful piece of content: is it a
`data-bs-edit` field, part of a component's `props_schema`, or a collection? If it's none
of those, the user can't edit it.

## Workflow

### Step 1: Read the contract

Read `editability-contract.md` in this directory. Internalize the decision rule and the
four silent traps.

### Step 2: Plan the editable surface before writing HEEx

For the page/component you're about to build, list the content the user will want to
change, and assign each a mechanism:

- **One-off scalar** (a heading, a single image, one button) → inline `data-bs-edit`.
- **A reused section** (hero, CTA band, footer block) → a `component()` with `props_schema`.
- **Repeating content** (pricing tiers, gallery, team, FAQ) → a collection (component
  `item_schema`, or inline `data-bs-collection`/`data-bs-item` **+ `data-bs-item-schema`**
  for the rich editor). Never a bare `:for`. Auto-number ordered items with `bs_index(idx)`.
  Put the `data-bs-collection`/`data-bs-item`/`data-bs-edit` markers on the rendered DOM too.
- **Shared design, per-page data** (related-card grids, page-specific lists) → a reusable
  component bound to a **page `@params` collection** (`%{cards: @params.related_cards}`),
  with the data + `item_schema` in the page's `params_schema`. **Never** pass the editable
  items as an inline literal in the `component(...)` call — the props panel can't read a
  literal, so the fields show empty.

### Step 3: Author with the markers

Apply the contract. The high-frequency rules:

- Add `data-bs-edit="field_name"` to every editable element.
- Use `data-bs-edit-type="richtext"` for any text with `<br>` or inline formatting — and
  inside richtext use inline `style="…"`, 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.