google-ads-builder-search

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.