name: google-ads-audit

description: Google Ads account audit and business context setup. Run this first — it gathers business information, analyzes account health, and saves context that all other ads skills reuse. Trigger on "audit my ads", "ads audit", "set up my ads", "onboard", "account overview", "how's my account", "ads health check", "what should I fix in my ads", or when the user is new to NotFair and hasn't run an audit before. Also trigger proactively when other ads skills detect that business-context.json is missing.

argument-hint: "<account name or 'audit my ads'>"

Google Ads Audit

Diagnose account health and persist business context for downstream skills (/google-ads, /google-ads-copy, /google-ads-landing). Read-only — never mutates the account. The user runs /google-ads to execute fixes you recommend.

Setup

Follow ../shared/preamble.md (MCP detection, account selection) and ../shared/analysis-principles.md (evidence requirement, guardrails). Both apply throughout this skill.

Filesystem contract (must persist)

These are the handoff to every other ads skill — write them even if the report is short. Otherwise /google-ads-copy and /google-ads-landing operate without business context and produce generic output.

business-context.json schema: business_name, industry, website, services[], locations[], target_audience, brand_voice{tone, words_to_use[], words_to_avoid[]}, differentiators[], competitors[], seasonality{peak_months[], slow_months[], seasonal_hooks[]}, keyword_landscape{high_intent_terms[], competitive_terms[], long_tail_opportunities[]}, social_proof[], offers_or_promotions[], landing_pages{}, unit_economics{aov_usd, profit_margin, source}, notes, audit_date, account_id.

personas JSON schema: {account_id, saved_at, personas: [{name, demographics, primary_goal, pain_points[], search_terms[], decision_trigger, value}]}. See references/persona-discovery.md.

Policy freshness check (run first)

Read ../shared/policy-registry.json. For each entry where last_verified + stale_after_days < today:

• High-volatility → WebSearch the area for recent Google Ads changes; compare to assumption. If drift, banner the report and suggest registry update.
• Moderate-volatility → one-line "may warrant a check" note.
• Stable → skip silently.

Phase 1 — Pull the audit dataset

Use a single runScript call with ads.gaqlParallel to fan out the queries an audit needs. The server's notfair://playbooks/audit-account resource has a battle-tested baseline; extend it with what your specific question needs.

You decide the exact GAQL shape, but a defensible audit needs to see, at minimum:

• Account-level rollups (customer)
• Campaign performance with bidding strategy, network, and impression-share metrics (campaign, 90-day cap for impression-share data)
• Ad-group performance (ad_group)
• Keyword performance with Quality Score and components (keyword_view)
• Search terms (search_term_view)
• Negative keywords and shared lists (campaign_criterion + shared sets)
• Conversion actions (conversion_action) — including counting type, attribution model, primary/secondary
• Network segmentation (segments.ad_network_type) when diagnosing CPA/CVR shifts or Search Partners
• RSA assets (ad_group_ad)
• Geo targeting (campaign_criterion LOCATION + PROXIMITY)
• Recent change events (change_event, last 30 days) — for explaining regressions

Aggregate inside the script. Return summarized JSON, not raw rows. The agent narrates; the script does the math.

getRecommendations and summarizeAccountSetup are useful cross-checks against Google's own and the server's structural views — call them as a separate tool turn after the runScript pass when comparison would sharpen the report.

If a critical query errors out (auth, schema), surface the error and stop — don't fall back to a degraded audit.

Skip scoring entirely if totalSpend == 0 or activeCampaigns == 0. Go straight to business context.

Phase 2 — Scope handling

If the user narrows the audit ("focus on one campaign", "campaign X", "just check waste"):

• Match campaign names by case-insensitive substring. If no match, list available campaigns and ask.
• Filter the in-memory dataset before analysis — no extra API calls.
• Account-level dimensions (conversion tracking, account guardrails) stay account-wide. Note "Scoped to: X" in the report.
• Skip Phase 4 (business context refresh) on scoped audits if business-context.json is fresh.

Phase 3 — Diagnose

The audit's headline output is three pulse metrics — Waste ($/mo), Demand captured (%), CPA ($) — each annotated with its top co