claude-google-ads

Find where your Google Ads budget leaks, cut the waste, and scale your store with ads — safely.

A Claude Code plugin that operates Google Ads end-to-end for ecommerce advertisers — any niche,
brand, or store (retail B2C, wholesale/B2B2C, DTC), not tied to one. It runs on your real account data
(never guesses), hunts the money leaks most accounts never see, and never touches your account without your
approval — it creates campaigns paused, caps spend, and respects bidding cooldowns.

Built by Khue Tran.

Scope: built for ecommerce / Shopping advertisers — it assumes a product catalog, store revenue,
AOV, and ROAS/value-based bidding (PMax/Shopping, Merchant Center). It is not built for leadgen, SaaS,
or local-service accounts (no CPA/CRM/lead-value paths). Within ecommerce it is brand- and niche-agnostic.

Design principle: every store is just one account-context.yaml. All business-specific facts
(accounts, data source, brand terms, margins, guardrails, retail-vs-wholesale model) live in that file. The
skills stay generic across ecommerce — fill a new context file and the whole suite works for a new store.

Status

Published and stable (v0.1.0). Installable from GitHub — see Install below. Active
development continues; see CHANGELOG.md for release history and what's new in each version.

Architecture

/google-ads  ->  ROUTER skill (reads account-context, routes to the right sub-skill)
│
├─ PIPELINE (campaign lifecycle)
│   ├─ setup         -> produces account-context.yaml (MCP-agnostic; shared vs per-site)
│   ├─ measurement   -> validates conversion tracking            [GATE before plan/build]
│   ├─ audit         -> scores the account (forked from ads-google)
│   ├─ plan          -> budget + campaign mix + full launch roadmap
│   ├─ builder-*     -> per type: search / branded-search / pmax / demand-gen
│   ├─ pusher        -> Editor CSV export + approval gate + spend cap   [SAFETY]
│   ├─ tracker       -> monitor learning phase, pacing, anomalies (observe only)
│   └─ optimizer     -> act: search-term mining, budget/tROAS, asset refresh
│
├─ CROSS-CUTTING (shared by multiple skills)
│   ├─ assets        -> RSA / PMax asset group / image-video briefs
│   └─ experiments   -> A/B split design (campaign level + asset-group level)
│
├─ references/       -> ecommerce KB (brand/niche-agnostic): benchmarks, policy, char limits, bidding playbooks
└─ templates/account-context.yaml  -> the reusable backbone

The skills (15) — what each one does

Each is a standalone slash command (e.g. /google-ads-audit); /google-ads routes you to the right one.

① Start here (2):

② Diagnose & fix waste (the core value) (3):

③ Plan & build campaigns (6):

④ Push, monitor & operate (4):

Locked structural decisions

1. Distribution = plugin (multiple independently-invokable skills), not a single mega-skill.
2. tracker (observe) and optimizer (act) are separate skills — different responsibilities.
3. pusher v1 = Google Ads Editor CSV + human approval gate. Auto-create via API is v2, gated on
   google_ads.api_write: true in the context. Most Google Ads MCPs are read-only.
4. account-context.yaml is the single source of business truth. No business detail is hardcoded
   in any skill.

Prerequisites — connect your data FIRST

The suite runs on real account data, never guesses. Set these up before using the skills (setup
inventories them and tells you what's missing). It works on what you connect and flags the rest
UNVERIFIED — it will not fabricate a number to fill a gap.

Without Google Ads nothing runs. Without Store / Merchant / GA4 the core audit still works (off the
Google Ads MCP), but AOV, true-ROAS, feed health, and the value cross-check render UNVERIFIED until you
connect them. /google-ads checks this up front and guides you.

Install

/plugin install claude-google-ads@chanktb/claude-google-ads

How to run it (you don't memorize anything)

Plugin commands are namespaced under claude-google-ads. Three ways to use them — pick whichever:

1. Type /claude-google-ads → the menu lists every command; arrow down and pick. This is the normal way —
   no need to remember names.
2. Just describe what you want in plain language — "audit my Google Ads", "set up Google Ads for my
   store", "build a PMax campaign" — and the matching skill runs automatically.
3. Type the exact command if you know it:

First run: /claude-google-ads:setup (creates your working folder + account-context.yaml), then
/claude-google-ads:audit.

Full usage guide (what to prepare, the command for each job, a first-run walkthrough):
docs/USAGE.md.