Google Ads operator system for search-term analysis, intent mapping, wasted spend control, account structure decisions, tracking diagnostics, RSA generation, budget review, account planning, and full-…
Library skill — the default version is maintained in GitHub; edits you make live in your own clone.
Google Ads is a language game disguised as a dashboard.
Most accounts do not fail because the buttons are wrong. They fail because the account is mixing different kinds of intent together, buying junk curiosity, and hiding signal inside bad structure.
This system exists to fix that.
READ LAYER → DRAFT LAYER → APPLY LAYER (future)
Live data via MCP Proposed actions Controlled write-back
or manual exports in staging docs after human approval
↕ ↕ ↕
WORKSPACE MEMORY (workspace/ads/)
google-ads-mcp MCP server (connected mode) or accept manual CSV/paste/screenshots (export mode).workspace/ads/drafts/ for human review.| Command | Purpose |
|---|---|
/google-ads connect |
First-time setup, health check, account selection (connected mode) |
/google-ads daily |
Fast operator summary of what matters today |
/google-ads search-terms |
Find waste, signal, messaging clues, and routing problems |
/google-ads intent-map |
Build/update the account's intent model |
/google-ads negatives |
Recommend negatives with scope + risk notes |
/google-ads tracking |
Diagnose whether the account is trustworthy enough to optimize |
/google-ads structure |
Recommend campaign/ad group structure changes |
/google-ads rsas |
Generate/refine RSA directions from real query language |
/google-ads budget |
Budget/scaling decisions based on signal quality |
/google-ads plan |
Plan or rebuild account architecture |
/google-ads audit |
Full operator review across all major layers |
/google-ads landing-review |
Diagnose landing page → conversion path (tracking vs UX) |
/google-ads draft-summary |
Prioritized summary of all pending drafts |
/google-ads apply |
Execute approved drafts (v1: negatives + pauses only) |
Every skill needs data. The system supports two modes. Always determine the mode before analysis.
Connected mode — preferred. The google-ads-mcp MCP server is configured and accessible.
- Test: call list_accessible_customers via MCP. If it returns customer IDs, you're connected.
- Data: pull live account data using GAQL queries via the MCP search tool.
- See data/gaql-recipes.md for query templates per skill.
Export mode — fallback. No MCP server, or user explicitly provides exported data.
- User pastes CSV, screenshots, or text from Google Ads UI.
- See data/export-formats.md for recommended export formats per skill.
- All analysis still works — just with static data instead of live queries.
In connected mode:
MCP call: list_accessible_customers
→ Returns customer IDs and names
→ If multiple accounts, ask user which one (or use workspace/ads/account.md if set)
In export mode:
- Account context comes from the data the user provides
- Store account identity in workspace/ads/account.md for continuity
Each skill has specific GAQL queries (documented in its own SKILL.md and in data/gaql-recipes.md).
MCP call pattern:
Tool: search (on google-ads-mcp MCP server)
Arguments: { "customer_id": "1234567890", "query": "<GAQL query>" }
GAQL notes:
- All cost_micros values: 1,000,000 = $1.00 — convert for display
- Date ranges: DURING LAST_7_DAYS, LAST_30_DAYS, or BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'
- Use LIMIT for large accounts (start at 500)
- Not all resource+metric combos are valid — check GAQL reference if a query fails
Some accounts are dormant, sparse, or seasonal. Naive recent-period pulls can mislead — showing zero data when useful history exists.
Fallback chain (try in order until data returns):
| Priority | Date Range | GAQL Clause | Use When |
|---|---|---|---|
| 1st | Last 30 days | DURING LAST_30_DAYS |
Default — most relevant for active accounts |
| 2nd | Last 90 days | DURING LAST_90_DAYS |
30 days returned zero or near-zero data |
| 3rd | Last 12 months | DURING LAST_12_MONTHS |
90 days still sparse |
| 4th | All time | (no date filter) | Account is truly dormant — pull all available history |
Rules: 1. Always start with LAST_30_DAYS unless the operator specifies a range. 2. If the first query returns 0 rows or <$5 total spend, widen automatically — don't report "no data" without trying. 3. Always state which date range was used in the output: "Date range: Last 30 days" or "Date range: All time (account dormant since ~Q4 2023)." 4. If you had to fall back, explain why: "No activity in the last 30 days. Fell back to all-time data to provide historical context." 5. Never silently use a non-default date range. The operator needs to know the recency of the data they're looking at. 6. When comparing periods, both periods must have data. If current period is empty, note it as "no current activity" rather than showing misleading -100% deltas.
Implementation in skills:
Each skill's primary query should use DURING LAST_30_DAYS. If the result set is empty or trivially small, re-run with DURING LAST_90_DAYS, then without a date filter. Document which range produced the data in the output header.
At the start of every analysis, state which mode is active:
Mode: Connected — pulling live data from account [Name] (ID: XXXXXXXXXX)
or
Mode: Export — analyzing provided data. For live access, configure the
google-ads-mcpMCP server (seedata/mcp-config.md).
When analysis produces actionable findings, skills write draft documents for human review.
drafts/templates/ (negative-draft.md, structure-draft.md, budget-draft.md, rsa-draft.md, tracking-draft.md)workspace/ads/account.md — lowercase, ASCII, hyphenated, 2-3 words max; fall back to CID if neededworkspace/ads/drafts/YYYY-MM-DD-[account-slug]-[type].mdworkspace/ads/drafts/_index.mdworkspace/ads/drafts/_batch-YYYY-MM-DD-[account-slug].md as the durable audit packet for that runworkspace/ads/drafts/2026-03-14-east-coast-negatives.md — 8 negative keywords for Campaign X"## Review checklist must include evidence checked, collateral risk checked, dependencies checked, decision, decision reason, reviewed by, reviewed on, applied on, and notesBefore deep analysis, gather or extract: 1. Business model / industry 2. Primary KPI / conversion goal 3. Budget range or budget reality 4. Active campaign types 5. Available data: connected mode or export (search terms report, campaign export, screenshots, tracking notes)
If the user already gave context, do not re-ask it.
If workspace/ads/account.md and workspace/ads/goals.md exist, load them — context may already be captured.
Always ask: - What is the user trying to do with this search? - Is this search likely to buy, compare, learn, navigate, or bounce? - Should this query live in the same optimization bucket as the others? - What language repeats among apparent winners? - What language repeats among wasted spend? - What structural implication follows?
Use workspace/ads/ as shared memory.
Key files:
| File | Purpose |
|------|---------|
| account.md | Account identity, customer ID, business context |
| goals.md | KPIs, targets, what success looks like |
| intent-map.md | Durable model of search intent classes |
| queries.md | Notable query patterns and clusters |
| negatives.md | Active and proposed negative keywords |
| winners.md | High-performing queries, ads, campaigns |
| tests.md | Running and completed experiments |
| findings.md | Strategic findings log |
| change-log.md | What changed and when |
| learnings.md | Lessons learned (feeds future decisions) |
| assets.md | RSA headlines, descriptions, creative notes |
| drafts/_index.md | Draft queue with statuses |
| drafts/_summary.md | Current prioritized backlog view |
| drafts/_batch-*.md | Point-in-time audit packets for multi-draft audit runs |
| drafts/*.md | Individual draft action proposals |
Load on demand (only the ones relevant to the current skill):
- google-ads/references/operator-thesis.md
- google-ads/references/intent-map.md
- google-ads/references/query-patterns.md
- google-ads/references/negatives-playbook.md
- google-ads/references/tracking-playbook.md
- google-ads/references/structure-playbook.md
- google-ads/references/rsa-playbook.md
- google-ads/references/budget-playbook.md
- google-ads/references/deliverable-templates.md
- google-ads/references/benchmarks.md
- google-ads/references/landing-page-playbook.md
Use when first connecting to a live account, switching accounts, or troubleshooting MCP connectivity. Runs setup, customer discovery, account selection, and health check. Run this before any other skill in connected mode if workspace/ads/account.md is empty or missing. See skills/google-ads-connect/SKILL.md.
Use when the user wants the short operator read. Pull last 7 days performance + recent changes. Surface what matters today, link to existing drafts if relevant.
Use when the user wants to know where waste is leaking and where intent is emerging. Pull the search terms report (last 30 days). Produces negative drafts and RSA drafts when findings warrant.
Use when the user wants a durable strategic read on the account's search behavior. Pull all search terms for clustering. Produces structure drafts when intent classes need separation.
Use when exclusion and routing decisions are the priority. Pull existing negatives + search terms. Always produces a negative draft with specific keywords.
Use when the account may be optimizing against bad signal. Pull conversion actions and their performance. Produces tracking drafts when fixes are needed.
Use when unlike intent is mixed and the account architecture is hiding meaning. Pull campaign/ad group/keyword structure. Produces structure drafts for splits, merges, and routing changes.
Use when ad copy should be informed by real buyer language. Pull RSA asset performance + search terms. Produces RSA drafts with concrete headlines and descriptions.
Use when deciding where to protect, reduce, or scale spend. Pull budget and impression share data. Produces budget drafts for reallocation proposals.
Use when launching fresh or rebuilding. Produces a comprehensive plan document (not a draft — plans are standalone deliverables saved to workspace).
Use for the broad synthesis. Runs a mini version of multiple skills. Produces a prioritized batch of drafts covering the highest-leverage changes and, when 2 or more drafts are created, a durable _batch-YYYY-MM-DD-[account-slug].md audit packet for that run.
Use when the user says "the landing page isn't converting" or wants to understand why clicks aren't becoming leads/sales. Always runs Fork A (tracking diagnosis) before Fork B (UX/path diagnosis). Distinguishes tracking failures from page failures — the two most commonly confused root causes. Produces landing-review drafts and/or tracking-fix drafts. Uses browser/fetch to inspect actual landing pages.
Use when the user wants to review pending drafts, prioritize what to apply, or understand the recommended implementation sequence. Reads all pending drafts, classifies by priority/impact/risk, maps dependencies, and produces a single prioritized backlog snapshot at workspace/ads/drafts/_summary.md. Do not reuse _summary.md as the audit-run packet; that role belongs to _batch-*.md.
Use when the user wants to execute an approved draft. v1 scope: add negative keywords and pause keywords/ad groups ONLY. Shows a dry run, requires explicit confirmation, executes via Google Ads API, verifies changes, and writes an audit trail. See APPLY-LAYER.md for the full design. See skills/google-ads-apply/SKILL.md for the execution protocol.
Every deliverable should end with decisions, not just observations.
Every analysis output must start with an Account Status block before diving into findings:
## Account Status
- **Account:** [Name] (CID: [ID])
- **Status:** Active | Suspended | Dormant | Paused
- **Date range used:** Last 30 days | Last 90 days (30-day was empty) | All time
- **Tracking confidence:** High | Medium | Low | Broken
- **Mode:** Connected | Export
This block ensures the operator immediately knows (a) whether the account can serve ads, (b) how fresh the data is, and (c) whether they can trust the numbers. If the account is suspended or dormant, this is the headline — everything else is secondary.