google-ads-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Ads Audit

Google Ads 审计

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.

诊断账户健康状况，并为下游技能（

/google-ads

、

/google-ads-copy

、

/google-ads-landing

）持久化业务上下文。只读权限——绝不会修改账户。用户需运行

/google-ads

来执行你推荐的修复操作。

Setup

设置步骤

../shared/preamble.md

— MCP detection, API key, account selection.

遵循

../shared/preamble.md

中的指引——MCP检测、API密钥、账户选择。

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`	Every full audit.

These are the handoff to every other ads skill — write them even if the report itself 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{}, 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

工件	路径	时机
业务上下文	`{data_dir}/business-context.json`	首次完整审计时；或当 `audit_date` 超过90天时刷新。若文件为最新状态，范围限定审计时可跳过。
用户角色（Personas）	`{data_dir}/personas/{accountId}.json`	每次完整审计时。

这些文件是所有其他广告技能的交接依赖——即使报告本身篇幅较短，也必须写入这些文件。否则

/google-ads-copy

和

/google-ads-landing

将在无业务上下文的情况下运行，生成通用化输出。

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{}, notes, audit_date, account_id

。

personas JSON schema：

{account_id, saved_at, personas: [{name, demographics, primary_goal, pain_points[], search_terms[], decision_trigger, value}]}

。详见

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.

读取

../shared/policy-registry.json

。对于每个满足

last_verified + stale_after_days < today

的条目：

高波动性 → 针对
```
area
```
进行WebSearch，查找Google Ads近期变化；与
```
assumption
```
对比。若存在偏差，在报告中标记并建议更新注册表。
中等波动性 → 添加一行“可能需要检查”的备注。
稳定性 → 静默跳过。

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

adsagent://playbooks/audit-account

resource has a battle-tested baseline; extend it with what this rubric needs that isn't already there.

A complete audit needs at minimum:

Account / customer-level metrics (
```
customer
```
resource) — totalSpend, conversions, conv-value, clicks, impressions for the audit window.
Campaign-level performance (
```
campaign
```
) — id, name, status, advertising_channel_type, bidding_strategy_type, network settings, search/top/abs-top impression share, budget-lost-IS, rank-lost-IS, status-rich metrics. Cap window at 90 days (impression-share data limit).
Ad-group performance (
```
ad_group
```
) — to attach top-line metrics under each campaign.
Keyword performance with QS (
```
keyword_view
```
) — text, match type, status, quality score (and components if needed), cost, clicks, conversions. Surfaces zombie keywords (0 impressions 30d), low-QS-with-spend, zero-converters.
Search terms (
```
search_term_view
```
) — for waste detection (clicks > 10, conv = 0) and brand-leakage detection (brand terms triggered by non-brand campaigns).
Negative keywords (
```
campaign_criterion
```
where
```
type='KEYWORD'
```
and
```
negative=TRUE
```
) — for negative-conflict detection and coverage.
Conversion actions (
```
conversion_action
```
) — count, status, primary-vs-secondary, counting type. STOP-condition input.
Ad assets (
```
ad_group_ad
```
) — RSA headlines/descriptions for asset-coverage scoring and topAds extraction.
Geo targeting (
```
campaign_criterion
```
where
```
type IN ('LOCATION','PROXIMITY')
```
) — for multi-location structure scoring.
```
radius_units
```
: 0=meters, 1=km, 2=miles.
Recent change events (
```
change_event
```
, max 30 days) — to flag recent edits that might explain regressions.

Compute aggregates in the script, return summarized JSON. Don't return all rows — rank, slice, summarize. The agent narrates the result, the script does the math.

getRecommendations

is a useful cross-check for Google's own recommendation surface — call it as a separate tool after the runScript pass if you want to compare your findings to Google's.

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

activeCampaigns == 0

. Go straight to business context.

使用单次

runScript

调用并结合

ads.gaqlParallel

来分发审计所需的查询。服务器的

adsagent://playbooks/audit-account

资源包含经过实战检验的基线；可根据本规则集的需求扩展基线中未涵盖的内容。

完整审计至少需要以下数据：

账户/客户级指标（
```
customer
```
资源）——审计周期内的总花费（totalSpend）、转化量（conversions）、转化价值（conv-value）、点击量（clicks）、展示量（impressions）。
广告系列级表现（
```
campaign
```
）——ID、名称、状态、广告渠道类型、出价策略类型、网络设置、搜索/顶部/绝对顶部展示份额、因预算损失的展示份额（budget-lost-IS）、因排名损失的展示份额（rank-lost-IS）、状态相关指标。周期上限为90天（展示份额数据限制）。
广告组级表现（
```
ad_group
```
）——用于在每个广告组下关联顶级指标。
含质量得分（QS）的关键词表现（
```
keyword_view
```
）——文本、匹配类型、状态、质量得分（必要时包含组成部分）、花费、点击量、转化量。可发现僵尸关键词（30天无展示）、低QS且有花费的关键词、零转化关键词。
搜索词（
```
search_term_view
```
）——用于检测浪费（点击>10且转化=0）和品牌流量泄露（品牌词触发非品牌广告系列）。
否定关键词（
```
campaign_criterion
```
中
```
type='KEYWORD'
```
且
```
negative=TRUE
```
的条目）——用于检测否定冲突和覆盖范围。
转化操作（
```
conversion_action
```
）——数量、状态、主/次要转化、计数类型。作为STOP条件输入。
广告资产（
```
ad_group_ad
```
）——响应式搜索广告（RSA）的标题/描述，用于资产覆盖评分和优质广告提取。
地域定位（
```
campaign_criterion
```
中
```
type IN ('LOCATION','PROXIMITY')
```
的条目）——用于多地域结构评分。
```
radius_units
```
：0=米，1=千米，2=英里。
近期变更事件（
```
change_event
```
，最多30天）——用于标记可能导致业绩下滑的近期编辑操作。

在脚本中计算聚合值**，返回汇总后的JSON。不要返回所有行——需进行排名、切片、汇总。由Agent叙述结果，脚本负责计算。

getRecommendations

是一个有用的交叉检查工具，可对比Google官方推荐内容——若需将你的发现与Google的推荐对比，可在runScript调用后单独调用此工具。

若关键查询出错（认证、schema问题），需显示错误并停止——不要退化为降级审计。

若满足以下条件则完全跳过评分：

totalSpend == 0

或

activeCampaigns == 0

。直接进入业务上下文环节。

Phase 2 — Scope handling

第二阶段——范围处理

If the user narrows the audit ("focus on grooming", "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 scoring — no extra API calls.
Account-level dimensions (conversion tracking) 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.

若用户限定审计范围（如“聚焦于优化”、“广告系列X”、“仅检查浪费情况”）：

通过不区分大小写的子字符串匹配广告系列名称。若无匹配项，列出可用广告系列并询问用户。
在评分前过滤内存中的数据集——无需额外API调用。
账户级维度（转化追踪）保持全账户范围。在报告中注明“范围限定为：X”。
若
```
business-context.json
```
为最新状态，范围限定审计时跳过第四阶段（业务上下文刷新）。

Phase 3 — Score

第三阶段——评分

Score each of the 7 dimensions 0–5 using

references/account-health-scoring.md

. Overall =

round(sum × 100 / 35)

Score	Label	Meaning
0	Critical	Broken or missing — actively losing money
1	Poor	Major waste or missed opportunity
2	Needs Work	Several clear issues
3	Acceptable	Functional, room to improve
4	Good	Well-managed, minor opportunities
5	Excellent	Best-practice

Scope-aware: campaign-level dimensions reflect in-scope data; account-level dimensions (conversion tracking) score account-wide with a note on scope impact.

使用

references/account-health-scoring.md

对7个维度分别进行0–5分评分。总分 =

round(sum × 100 / 35)

。

分数	标签	含义
0	严重问题	功能损坏或缺失——正在主动亏损
1	较差	存在重大浪费或错失机会
2	需要改进	存在多个明确问题
3	可接受	功能正常，有改进空间
4	良好	管理完善，仅有少量优化机会
5	优秀	符合最佳实践

支持范围限定：广告系列级维度反映限定范围内的数据；账户级维度（转化追踪）基于全账户评分，并注明范围影响。

Encoded heuristics — apply these, they aren't obvious

内置启发式规则——请严格应用，这些规则并不直观

Weighted QS by spend, not by keyword count. A QS-3 keyword burning $2,000/mo matters infinitely more than ten QS-3 keywords burning $5/mo combined.
Brand-leakage premium. When brand campaigns are paused or starved, brand traffic leaks to non-brand at 5–10× higher CPA. Always check whether brand terms appear in non-brand campaigns' search-term reports.
Waste formula. Keyword waste = clicks > 10 AND conversions = 0 AND cost > 0. Search-term waste = same, applied to actual queries. Sum them — that's the recoverable spend.
Display + Search mixed in one campaign is structurally broken — Display dilutes Search metrics and burns budget on unintended placements. Flag any campaign where
```
network_settings.target_content_network = TRUE
```
for a SEARCH channel campaign.
Zombie keywords (0 impressions for 30+ days) clutter reporting and confuse Google's ML — recommend pause.
Counting type matters. Lead-gen should use
```
ONE
```
per click; e-commerce should use
```
EVERY
```
. Wrong setting silently inflates or deflates conversions.
STOP condition. If conversion tracking scores 0–1, recommend pausing spend until tracking is fixed. Everything downstream of measurement is unreliable.

按花费而非关键词数量加权QS。一个花费2000美元/月的QS-3关键词，比十个总花费5美元/月的QS-3关键词重要得多。
品牌流量泄露溢价。当品牌广告系列暂停或预算不足时，品牌流量会泄露到非品牌广告系列，导致CPA（单次转化成本）升高5–10倍。务必检查品牌词是否出现在非品牌广告系列的搜索词报告中。
浪费计算公式。关键词浪费 = 点击>10 且转化=0 且花费>0。搜索词浪费 = 相同规则应用于实际查询。求和即可得到可回收的花费金额。
同一广告系列混合展示与搜索渠道属于结构性问题——展示渠道会稀释搜索渠道指标，并在非预期位置消耗预算。若搜索渠道广告系列的
```
network_settings.target_content_network = TRUE
```
，需标记此问题。
僵尸关键词（30+天无展示）会扰乱报告并干扰Google的机器学习——建议暂停此类关键词。
计数类型至关重要。线索生成应使用
```
ONE
```
（每次点击计一次）；电商应使用
```
EVERY
```
（每次转化计一次）。错误设置会悄无声息地夸大或缩小转化量。
STOP条件。若转化追踪评分0–1，建议在修复追踪问题前暂停花费。没有可靠的衡量标准，后续所有操作都不可靠。

Impression Share Interpretation Matrix

展示份额解读矩阵

	Rank-Lost < 30%	Rank-Lost 30–50%	Rank-Lost > 50%
Budget-Lost < 20%	Healthy	QS / bid problem	Quality crisis
Budget-Lost 20–40%	Budget problem	Mixed (fix quality first)	Structural — too-competitive keywords
Budget-Lost > 40%	Severe budget gap (highest-ROI fix if CPA is good)	Fix rank first, then add budget	Fundamental misalignment — pause and restructure

	排名损失<30%	排名损失30–50%	排名损失>50%
预算损失<20%	健康	QS/出价问题	质量危机
预算损失20–40%	预算问题	混合问题（优先修复质量）	结构性问题——关键词竞争过于激烈
预算损失>40%	严重预算缺口（若CPA良好，是ROI最高的修复项）	先修复排名，再增加预算	根本性错位——暂停并重构

Phase 4 — Business context

第四阶段——业务上下文

Derive what you can from the data already pulled:

Field	Source
`business_name`	Account name (from `customer.descriptive_name` )
`services`	Campaign + ad-group names, top converting keywords
`locations`	`campaign_criterion` LOCATION + PROXIMITY
`brand_voice`	Top-performing RSA headlines / descriptions
`keyword_landscape.high_intent_terms`	Converting keywords with strong CVR
`keyword_landscape.competitive_terms`	Keywords in campaigns with high rank-lost-IS
`keyword_landscape.long_tail_opportunities`	Converting search terms not yet promoted to keywords
`website`	Apex domain from ad final URLs

Then crawl the website (homepage + about + services + top 3 ad landing pages, parallel

WebFetch

) and merge into the schema. See

references/business-context.md

for the full crawl procedure.

Always ask the user (it's faster than guessing): differentiators, competitors, seasonality. Ask for everything else only if the data + crawl can't answer it.

从已提取的数据中推导尽可能多的信息：

字段	来源
`business_name`	账户名称（来自 `customer.descriptive_name` ）
`services`	广告系列+广告组名称、高转化关键词
`locations`	`campaign_criterion` 中的LOCATION + PROXIMITY
`brand_voice`	表现最佳的RSA标题/描述
`keyword_landscape.high_intent_terms`	转化效果好的高意向关键词
`keyword_landscape.competitive_terms`	排名损失展示份额高的广告系列中的关键词
`keyword_landscape.long_tail_opportunities`	已转化但尚未升级为关键词的搜索词
`website`	广告最终URL中的顶级域名

然后抓取网站内容（首页+关于我们+服务页面+前3个广告落地页，并行

WebFetch

）并合并到schema中。完整抓取流程详见

references/business-context.md

。

务必询问用户（比猜测更高效）：差异化优势、竞争对手、季节性因素。仅当数据+抓取无法获取其他信息时，才询问用户。

Phase 5 — Personas

第五阶段——用户角色（Personas）

Discover 2–3 personas from search terms, top keywords, ad-group themes, landing pages, geo, and device split — all from the dataset already in memory. Persist to

{data_dir}/personas/{accountId}.json

. Each persona must be grounded in 5+ actual search terms; if not, drop it. See

references/persona-discovery.md

从搜索词、顶级关键词、广告组主题、落地页、地域、设备分布中挖掘2–3个用户角色——所有数据均来自内存中的数据集。持久化到

{data_dir}/personas/{accountId}.json

。每个用户角色必须基于5个以上实际搜索词；若不满足，放弃该角色。详见

references/persona-discovery.md

。

Phase 6 — Report

第六阶段——报告

Lead with the verdict, then the top 3 actions (with dollar impact when possible), then the scorecard, then evidence for dimensions scoring 0–2 only. Cite specific campaigns, keywords, and dollar amounts. Cap at ~80 lines.

End with a single closing line after the handoff to

/google-ads

Your audit history is saved to your NotFair account — view it at https://notfair.co.

以结论开头，然后列出前3项行动（尽可能注明美元影响），接着是评分卡，最后仅列出评分0–2的维度的证据。引用具体的广告系列、关键词和金额。报告篇幅控制在约80行以内。

在交接给

/google-ads

后，添加一句收尾语：

你的审计历史已保存到NotFair账户——可通过https://notfair.co查看。

Guardrails

约束规则

Read-only skill. Diagnose; don't mutate. Every fix routes through
```
/google-ads
```
(or
```
/google-ads-copy
```
,
```
/google-ads-landing
```
). End the report with one handoff tied to the #1 action.
STOP condition — if conversion tracking scores 0–1, recommend pausing spend until it's fixed before recommending anything else. Everything downstream is meaningless without measurement.
Always persist
```
business-context.json
```
and
```
personas/{accountId}.json
```
even if the report itself is short — downstream skills depend on them.
Name names. Every finding cites specific campaigns, keywords, search terms, and dollar amounts. "Some keywords are underperforming" is not a finding.

只读技能。仅诊断，不修改。所有修复操作需通过
```
/google-ads
```
（或
```
/google-ads-copy
```
、
```
/google-ads-landing
```
）执行。报告结尾需添加一个与首要行动相关的交接指引。
STOP条件——若转化追踪评分0–1，建议在修复追踪问题前暂停花费，再推荐其他操作。没有可靠的衡量标准，后续所有操作都毫无意义。
必须持久化
```
business-context.json
```
和
```
personas/{accountId}.json
```
，即使报告本身篇幅较短——下游技能依赖这些文件。
明确指向具体对象。每个发现都需引用具体的广告系列、关键词、搜索词和金额。“部分关键词表现不佳”不属于有效发现。