AuditSAFE

Open-source SEO, GEO, and marketing skills for AI agents.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: google-ads-audit
description: Google Ads account audit and business context setup. Use for account-health audits and business-context setup. 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.
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)

| Artifact | Path | When |
|---|---|---|
| Business context | `{data_dir}/business-context.json` | First full audit, or refresh when `audit_date` is >90 days old. Skip on scoped audits if file is fresh. |
| Personas | `{data_dir}/personas/{accountId}.json` | Only when the task needs them (ad copy, landing pages, audience work) or copy/landing work is next and none exist. |

Business context is the handoff to every other ads skill — write it 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}, lead_quality{primary_conversion_definition, crm_source, join_key, qualified_rate_by_campaign{}, last_confirmed}, linked_accounts[{account_id, type, note}], notes, audit_date, account_id`. See `references/business-context.md` for `lead_quality` and `linked_accounts`.

**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`:
- Any entry without a direct current first-party Google source is a hypothesis, not an audit rule or benchmark. Do not use it for a finding or recommendation without verification.
- **High-volatility** → search the official Google Ads Help, Ads & Commerce blog, or Google Ads developer documentation for the `category`; compare the source with the recorded `rule`. If it drifted, omit the stale rule and banner the limitation.
- **Moderate-volatility** → verify it when it could affect a material finding; otherwise omit it rather than repeating a stale caveat.
- **Stable** → skip silently.

## Phase 1 — Pull the audit dataset

Choose available read capabilities for the requested audit scope. Batch related reads where useful and supported; consult current server guidance for schemas and limits.

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.

Use platform recommendations or account-setup diagnostics as optional cross-checks when available and relevant to the question.

If a read fails, follow actionable recovery guidance. Clearly report missing evidence; continue independent findings only when the available data supports them.

**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 contributor and a pointer to the fix. Read `references/account-health-scoring.md` for the formula, annotation rules, signal-failure overrides, and `audit-history.json` schema. The pulse metric IS the verdict; you don't add a letter grade or 0–5 score on top.

To compute and back the pulse metrics, you'll need to look across these seven areas. They are diagnostic surface area, not graded dimensions:

1. **Signal Quality** *(account-level)* — measurement integrity. If broken, **STOP** here and recommend pausing spend until it's fixed. Pulse metrics are meaningless without measurement (apply the 

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.