---
name: google-ads-builder-search
description: >
  Builds a standard Search campaign blueprint: ad-group structure (tight theming), keyword lists with
  match types, responsive search ads (RSAs), negative keyword lists, extensions, and bidding. Emits a human
  .xlsx plus a campaign-spec.json (ad_groups variant) the pusher can export to Google Ads Editor. Reads
  account-context.yaml; no hardcoding. Use when the user says "build search", "search campaign", "keyword
  campaign", "create search ads".
---

# Google Ads — Builder: Search

Design a launch-ready Search campaign. Unlike PMax, Search **pushes cleanly via Google Ads Editor CSV** —
so the campaign-spec maps almost 1:1 to an import file.

## Governing principle — Search is the CONTROL layer over PMax's DISCOVERY
On a PMax/Shopping-heavy account, PMax is the **discovery engine**: it serves broad and surfaces which queries
actually convert. A non-brand Search campaign exists to take **control** of those proven winners — explicit
keywords, bids, match types, and RSA messaging instead of a black box. So the keyword plan is a **harvest of
the account's whole search-term data (Search + PMax), not a catalog brainstorm.** Concretely:
- **Source from both:** `search_term_view` (exact terms + cost, Search/Shopping only) AND
  `campaign_search_term_insight` per PMax (converting *category* themes + conversions — NOT per-term cost or
  exact verbatim, so it's directional; you still choose the exact keyword from the theme).
- **Harvest into EXACT — that's the actual control lever.** An exact-match keyword identical to a query
  outranks PMax for that query; phrase/broad may not. So proven converters go in as **exact**, not phrase.
- **Harvest selectively.** Pull queries where control pays off (volume / value / margin / needs distinct
  messaging — e.g. high-AOV equipment). Leave long-tail one-off converters in PMax; thousands of exacts is
  overhead with no control gain.
- **Coordinate, don't double-pay.** Once a query is an exact in Search, PMax de-prioritizes it; judge
  **incrementality**, not shifted credit.

## Operating rules
- Read context (brand_terms, competitor_terms, guardrails, vertical, budget) + the `plan` output.
- Write to the working directory. Emit BOTH `blueprint.xlsx` (human) and `campaign-spec.json`
  (`campaign_type: "search"`, with `ad_groups[]`).
- Verify every Final URL is live. Enforce guardrails (conversion goals at campaign level; ENABLED-only).

## Model dispatch (run cheap, decide expensive) — see `${CLAUDE_PLUGIN_ROOT}/references/model-tier-dispatch.md`
- **Scout (`haiku`)** — per-URL 200 checks; the char-count validation pass; keyword dedupe.
- **Routine (`sonnet`)** — pulling the **dual-source search-term data** (`search_term_view` + `campaign_search_term_insight` per active PMax, incl. the catch-all) + catalog/services + Keyword Planner volume. Dispatch as `general-purpose`; **return raw converting terms, don't theme**.
- **Judge (main session)** — STEP 2 ad-group theming, STEP 3 match-type strategy, STEP 4 RSA copy (via `assets`), STEP 5 brand/non-brand separation. The keyword *data* is cheap; the *structure* is judgment.

## STEP 1 — Inputs (start from the harvest, not the catalog)
From `plan` + context: daily budget and bidding target. **The keyword universe is the whole-account
search-term harvest** (STEP 3), filtered to the converting queries worth controlling — the catalog/services
only *supplement* it and confirm landing pages. If there's no PMax/Search history to harvest (a true cold
launch), say so and lean on Keyword Planner + catalog, starting Phrase/Exact.

## STEP 2 — Ad-group theming (tight)
Group keywords by tight intent themes (one offer/intent per ad group) so the ad copy can match the query.
Derive themes from the catalog/services + real search terms where available. Avoid dumping unrelated
keywords together (theme coherence drives Quality Score). SKAG only if a term truly warrants isolation;
otherwise themed groups.

## STEP 3 — Keywords & match types (the core of a Search campaign — get this right)
Keyword identification + match type is where Search wins or wastes money. Do it deliberately:
- **Ground keywords in the account's REAL search-term data — both sources, MANDATORY. Do NOT invent keywords
  from the catalog alone.** This is the #1 builder-search mistake. `search_term_view` covers only Search/
  Branded; on a PMax-heavy account it returns almost nothing (or only brand terms), so you MUST ALSO pull
  `campaign_search_term_insight` looped **per active PMax campaign** — especially the generic/catch-all PMax,
  which is where non-brand intent actually lives (brand-specific PMax campaigns return only their own brand's
  terms). Build ad groups around what genuinely CONVERTS in that data, not category names you guessed.
  (Same dual-source rule the optimizer uses — see `${CLAUDE_PLUGIN_ROOT}/references/optimization-playbook.md`.)
  Then supplement with Keyword Planner volume and catalog/services. Group tightly by intent (one theme per AG).
  - *Worked example:* on one live account, catalog-derived ad groups MISSED the highest-AOV real intent — a
    high-ticket equipment category ($500+/conv) — while over-weighting a thin low-volume theme. The PMax
    catch-all's `campaign_search_term_insight` surfaced the equipment + attribute demand the catalog guess
    never would. Let the converting data, not the catalog, decide the ad groups.
  - **Resold-brand category terms** that already convert in PMax (e.g. a specific third-party brand's product
    line) are usually PMax's job — don't rebuild them as non-brand Search ad groups (you'd cannibalize PMax).
    Non-brand Search should target the GENERIC / ATTRIBUTE / EQUIPMENT intent PMax under-serves.
- **Match-type strategy**: **Exact** for proven converters — *especially queries harvested from PMax, where
  exact is what wrests control back from the black box*; **Phrase** for controlled expansion; **Broad ONLY
  with Smart Bidding** (never broad on Manual CPC — the legacy-BMM trap). Don't over-rely on broad.
  **Smart Bidding is necessary but not sufficient for broad** — broad needs *conversion history* to steer, so
  a brand-new campaign with zero converters starts Phrase/Exact even on Maximize Conversions, and opens broad
  only after it has data. (Live example: a PMax-heavy account's `search_term_view` showed zero non-brand converters →
  Phrase/Exact, not broad.)
- Dedupe by (ad_group + text + match_type).
- **Match type is ALWAYS output ready-to-copy** — wrapped `[exact]` / `"phrase"` / broad — so it pastes
  straight into the UI/Editor with no re-formatting (`spec_to_paste.py`; `${CLAUDE_PLUGIN_ROOT}/references/google-ads-formatting.md`).

## STEP 4 — RSAs (via `assets`)
One strong RSA per ad group: up to **15 headlines (≤30 chars)** and **4 descriptions (≤90 chars)**, themed
to the ad group. Pin discipline: pin only must-include/legal claims; over-pinning kills RSA flexibility.
Include the keyword intent in headlines + a clear CTA and value prop. Aim for "Good/Excellent" ad strength.

## STEP 5 — Negatives & brand separation
- Campaign + **shared negative lists** (themed: informational/DIY, job-seeker, location, cross-brand,
  irrelevant). Source from real irrelevant search terms; prefer Exact/Phrase, never broad negatives.
- **Separate brand vs non-brand**: keep brand_terms out of non-brand ad groups (route brand to
  `builder-branded-search`). Respect the "what NOT to block" rules (store/coupon/cheap-brand) from the
  optimization playbook.

## STEP 6 — Bidding ramp
From `campaign_defaults.bidding_ramp`: typically Maximize Conversions (no target) during learning →
tCPA/tROAS once volume matures. Respect step-up discipline + change-event cooldown.

## STEP 7 — Extensions
Sitelinks (≥4, with descriptions), callouts (≥4), structured snippets, and image/call/location assets where
relevant. Don't claim an extension is absent without proof (GUARD-6).

## STEP 8 — Output + verification
Emit `blueprint.xlsx` (campaign overview + per-ad-group keywords/RSA/negatives + extensions + bidding +
checklist) and `campaign-spec.json` with `ad_groups[]` (name, theme, keywords[{text,match_type}],
negatives[], rsa{final_url, headlines[{text,pinned}], descriptions[{text,pinned}], paths[]}, extensions).
Set `campaign.status: "paused"`, `conversion_goals.scope: "campaign"`. Put any sitelinks/callouts/snippets in
the campaign-level `extensions` block (not per ad group). Render the workbook with the shared renderer (it
handles `ad_groups` → one AG sheet per ad group with keywords/RSA/negatives/paths):
`python ${CLAUDE_PLUGIN_ROOT}/skills/builder-pmax/scripts/spec_to_xlsx.py <campaign-spec.json> --output blueprint.xlsx`
Verify with `validate_spec.py`: RSA char limits + counts (≤15/≤4) using **Google-accurate counting**
(`${CLAUDE_PLUGIN_ROOT}/references/google-ads-formatting.md`), keyword match types valid, every Final URL live (200, no
redirect, group-specific), negatives Exact/Phrase. Hand the JSON to `pusher` → Editor CSV
(`spec_to_editor_csv.py`) + ready-to-copy keyword/negative blocks (`spec_to_paste.py`).

## To build / refine later
- [ ] Shared the RSA generator with `assets`; Editor CSV mapping lives in `pusher`.