[ PAID MEDIA ]

/google-ads-optimize

Full Google Ads search campaign optimization for a ACME Agency client.

Download the skill file (.md)

Google Ads Search Campaign Optimizer

Triggers

• /google-ads-optimize ACME Agency — run interactively for a specific client
• /google-ads-optimize — will prompt for client name if not given
• ClickUp task tagged claude-code with name/description matching:
• optimiz.*google, negativ.*klju, search.*term, optimiz.*bidding

What this skill does

1. Identifies the client from the argument or ClickUp context
2. Loads or builds CLIENT.md with business knowledge (Drive questionnaire + website)
3. Determines analysis period (30 days, or 14 days if any campaign is < 30 days old)
4. Pulls search terms, keywords, device, geo, and bidding strategy data
5. Auto-applies campaign-level BROAD match negative keywords
6. Reports only (no auto-apply) on bidding strategy, device, and geo opportunities
7. Posts a full structured report to the client's Slack channel

How to run

# Full execution (applies negatives, posts to Slack)
node ACME Agency/scripts/google_ads_optimize.mjs --client "ACME Agency"

# Dry run — analysis only, no writes, no Slack post
node ACME Agency/scripts/google_ads_optimize.mjs --client "ACME Agency" --dry-run

Interactive step-by-step (when running manually, not via ClickUp executor)

Step 1 — Identify client

• Look up the client in ACME Agency/clients/clients.json (by name, case-insensitive)
• Must have google_ads_id to proceed. If missing, check MCC <id> or ask the user.

Step 2 — Load or build CLIENT.md

Check ACME Agency/clients/<ClientFolder>/CLIENT.md.

If it exists: read it — it has business context, brand terms, competitors, and "never negate" list.

If it doesn't exist, fetch from:

1. Google Drive: gws drive files list --folder-id <drive_folder_id> → find file with "upitnik" in name → gws drive files get --file-id <id>
2. Client website: fetch landing_page URL from clients.json
3. Synthesize and save as ACME Agency/clients/<ClientFolder>/CLIENT.md

Note: gws CLI must be run via bash shell on Windows, not via Node execFileSync. If drive_folder_id is missing in clients.json, skip Drive step and log a warning.

CLIENT.md format:

# CLIENT.md — <ClientName>
## Business type
## Products/services
## Market/geography
## Target audience
## Competitors
## Keywords to never negate
## Brand terms

Step 3 — Determine analysis period

Pull all SEARCH campaigns and check campaign.start_date.

• If ALL enabled search campaigns have been running ≥ 30 days → use LAST_30_DAYS
• If ANY search campaign is < 30 days old → use LAST_14_DAYS for all queries

Step 4 — Pull data in parallel

• <id>() — campaign stats + bidding_strategy_type + start_date
• getSearchTerms() — actual queries users searched, by campaign and ad group
• getClientKeywords() — the client's active keywords (used as context for analysis)
• getDeviceBreakdown() — clicks/conversions segmented by MOBILE / DESKTOP / TABLET
• getGeoBreakdown() — clicks/conversions by city/region (LOCATION_OF_PRESENCE only)

Step 5 — Analyze search terms

Uses analyzeSearchTerms() from lib/google_ads.mjs plus client context:

Auto-negate (apply automatically):

• Competitor brands (global blacklist + client's competitors from CLIENT.md)
• Retail/DIY stores
• Informational intent (test, forum, vergleich, recenzije, etc.)
• Wrong product type (cabrio, markise, wintergarten, etc.)
• Low-value intent (gebraucht, billig, gratis, etc.)

Competitor campaign rule:

• Campaigns whose name matches /(konkur|competitor)/i → still add informational/retail/wrong_product negatives, but skip competitor-brand terms

Protect via CLIENT.md:

• Keywords to never negate → added to safe list before analysis
• Brand terms → treated as client's own keywords, never negated

Suggest for ACME Agencyw (don't auto-apply):

• High cost (>3x avg CPC), 0 conversions, no keyword overlap → flag for human

Step 6 — Apply negatives

• Campaign-level BROAD match via addNegativeKeywords() in lib/google_ads.mjs
• The function auto-deduplicates against existing negatives
• Add the marker (e.g., artosi) not the full search term (e.g., artosi pergola preisvergleich)
• Skip if --dry-run

Step 7 — Bidding strategy analysis (report only)

For each SEARCH campaign:

• If conversions ≥ 30 AND strategy = MAXIMIZE_CLICKS → recommend switching to MAXIMIZE_CONVERSIONS or Target CPA
• Suggested tCPA = total cost / total conversions

Step 8 — Device analysis (report only, 100+ clicks threshold)

Aggregate all SEARCH campaign data by device across the period:

• If device has 100+ clicks AND conv rate < 50% of account average → recommend bid adjustment down
• If device has 100+ clicks AND 0 conversions AND cost > €20 → recommend exclusion consideration

Step 9 — Geo analysis (report only, 100+ clicks threshold)

Aggregate geographic data:

• If city/region has 100+ clicks AND conv rate < 30% of average → recommend bid adjustment
• If city/region has 100+ clicks AND 0 conversions AND cost > €30 → recommend exclusion

Step 10 — Save raw output to JSON

Before delegating, save the full data payload to:

ACME Agency/clients/<ClientFolder>/<id>.json

Contains: campaign summary, raw search terms, applied negatives, suggested negatives, device data, geo data, bidding diagnostics. The analyst reads from this file in the next step.

Step 11 — Delegate analysis to the analyst agent

Invoke the analyst subagent via the Task tool with subagent_type: "analyst". Pass:

client: <client name>
data_source: <absolute path to <id>.json from Step 10>
data_type: google-ads
period: last 30 days (or whatever window was analyzed)
compare_to: previous 30 days (if comparison data is in the file)
focus: search-term waste + bidding/device/geo opportunities
output_format: sections

The analyst returns summary (Slack-ready), details (for thread), and <id>. Do NOT analyze the JSON yourself in the main context.

Step 12 — Deliver via slack-reporter

Invoke the slack-reporter subagent via the Task tool with subagent_type: "slack-reporter". Pass:

client: <client name>
channel: <channel ID resolved via getClientChannel(clientName)>
type: google-ads-optimize
headline: "*Google Ads — <ClientName> — <YYYY-MM-DD>*"
sections: <derived from analyst's summary block>
extra_sections:
  - title: "Negatives applied"
    bullets: <list from Step 6>
  - title: "Suggested for ACME Agencyw"
    bullets: <list from Step 6>
links:
  - label: "Detalji"
    url: <Drive doc URL if generated>
thread_details: <analyst's details + device/geo breakdowns>
language: <client's language from clients.json>

Do NOT call <id>() or any helper from lib/slack.mjs directly. The slack-reporter agent owns Slack delivery.

Verification (run AFTER Step 12 — prove it shipped, don't assume)

Rubric: verify.md. The mutation check is now enforced in google_ads_optimize.mjs: after applying negatives it re-fetches each campaign's live negative list (getExistingNegatives) and confirms every intended term is present — a 200 from the write is not proof. Watch the run for [optimize] Verify: N/M confirmed live; any miss is logged per-campaign with the API errors (result.errors, previously ignored) and lands in reportData.negativesVerification. A miss usually means a policy-exemptible keyword (e.g. <id>) was dropped — do NOT report those as applied; resubmit with <id> (see createSearchKeywords).

Then check the rest before declaring done:

• [ ] Raw JSON saved at ACME Agency/clients/<folder>/<id>.json with non-empty campaigns[] and searchTerms[]
• [ ] negativesVerification shows 0 missing (all intended negatives confirmed live) — if not, list them, don't hide them
• [ ] No negatives applied to wildcard wrongly (cross-check against CLIENT.md "Keywords to never negate" list — if any match, flag as a potential rollback)
• [ ] Analyst's summary block has the 3 expected sections (Top-line, What changed, Recommendations)
• [ ] Summary mentions specific search terms by name in the waste analysis
• [ ] Slack post via slack-reporter returned ts non-null AND posted in last 5 min
• [ ] Channel matches clients.json[client].slack_channel
• [ ] Slack message body uses * bold, • bullets, zero emojis
• [ ] If CLIENT.md had [Fill in] placeholders, this is explicitly noted in the report
• [ ] Bidding/device/geo recommendations match what the data actually shows (no hallucinated cities or device IDs)

If any check fails, name the gap explicitly. Never claim success when verification fails — for Google Ads especially, wrong negatives can take down a real account.

Key files

Important rules

• NEVER auto-apply: bidding strategy changes, device bid adjustments, geo exclusions, budget changes
• NEVER add competitor-brand negatives to competitor campaigns (but DO add informational/retail/wrong_product)
• Check CLIENT.md first — the "Keywords to never negate" section prevents wrong negations
• If CLIENT.md has [Fill in] placeholders, knowledge hasn't been ACME Agencywed — note this in the analyst's findings
• Delegate analysis to the analyst agent — never crunch the raw search-term JSON in the main context
• Delegate Slack output to slack-reporter — never call <id>() directly anymore
• If a Google Ads API call fails twice with the same error (<id>, OAuthException, INVALID_CUSTOMER_ID), invoke the diagnostician subagent before retrying. These almost always have UI/permission/MCC-linkage root causes — don't loop on code workarounds.
• gws on Windows: always use bash shell, not Node.js execFileSync
• API version: v20, MCC: <id>
• LAST_7_DAYS does NOT include today — always use LAST_14_DAYS, LAST_30_DAYS, or DURING TODAY

Example ClickUp tasks that trigger this skill

• "Optimiziraj Google search kampanje za ACME Agency"
• "Dodaj negativne ključne riječi — ACME Agency"
• "Google Ads optimize — bidding strategy check ACME Agency"
• "Search term audit ACME Agency"