How the skill works: your agent reads 29 days of campaign metrics from Google Ads; google ads customer id from What you tell it, every day at 9:00, and gives you a question for you and a telegram ping and the report in the chat.
Reads
Google Ads29 days of campaign metrics
What you tell itGoogle Ads customer ID
reads
Your agentClaude Code, Codex, Cursor or GeminiEvery day at 9:00
posts
You get
A question for youOn your board, answered with a tap
A Telegram pingOnly when it needs your answer, if you connect Telegram
The report in the chatEvery run, with or without Briefkin
What you get
Anomalies: campaign, metric, yesterday's value, the 28-day mean and the score.
Likely cause from the change history, when there is one.
Direction: spending more for the same result, or delivering less than usual.
The ask: which campaign to look into first.
The card on the right is a sample. Yours shows your own numbers and updates in place every run.
What lands on your board
Your boardEvery day at 9:00
Acme StoreGoogle Ads anomaly alert · Claude Code
2 campaigns out of pattern yesterday
Brand spend tripled after its bid strategy changed to Maximize clicks at 14:20. Want me to dig into either campaign?
Brand - Search spent $1,240 against a 28-day mean of $410. Shopping - Bestsellers recorded 3 conversions against a usual 19 while clicks held steady.
Campaign
Metric
Yesterday
28-day mean
Score
Brand - Search
Cost
$1,240
$410
+4.1
Brand - Search
Clicks
1,890
820
+4.1
Shopping - Bestsellers
Conversions
3
19
-2.9
Change history: Brand - Search bid strategy set to Maximize clicks by j.lee@acme.com yesterday at 14:20.
An example with made-up numbers. Your agent posts your real ones.
What it does
A bid strategy that runs hot, a broad match keyword that wakes up, a feed error that quietly starves Shopping: in Google Ads these show up as one strange day, and the account overview averages them away. Most people find out at the end of the week, after the money is spent.
This skill compares yesterday with each campaign's own last 28 days, metric by metric, and only speaks up when a number sits well outside its usual spread. It also reads the account's change history for that campaign, so the alert arrives with the likely reason attached instead of a bare "spend is up".
How it works
1Pull 29 days of campaign metrics
Run GAQL with the MCP server's search tool or googleAds:searchStream: SELECT campaign.id, campaign.name, segments.date, metrics.cost_micros, metrics.clicks, metrics.impressions, metrics.conversions FROM campaign WHERE campaign.status = 'ENABLED' AND segments.date BETWEEN '<29 days ago>' AND '<yesterday>'. GAQL leaves out rows where every metric is zero, so fill missing dates with 0.
2
2Build each campaign's baseline
For each campaign and metric, take the mean and standard deviation of the 28 days before yesterday, and score yesterday as (yesterday - mean) / sd. Skip campaigns with fewer than 14 days of data or under $20 of average daily spend; their spread is too noisy to judge.
3
3Keep the anomalies that matter
Flag a metric when the score is 2 or more either way and the gap is material: at least $50 of spend, 30 clicks or 3 conversions. A spike in spend with flat conversions ranks above a spike in both.
4Look for the cause
For each flagged campaign, query change_event (change_event.change_date_time, change_event.change_resource_type, change_event.changed_fields, change_event.user_email) for the last two days. It needs a date filter within the past 30 days and a LIMIT. Name the change if one lines up.
5
5Ask, or stay quiet
With anomalies, post an action card: campaign, metric, yesterday against the mean, the score, and any matching change. On a normal day, update the same card with "all campaigns within range" and no question.
Post it to the board
With BRIEFKIN_TOKEN set, the agent sends the result as one card that updates in place every run. Without it, you get the report in the chat.
Install and run it
Pick your agent, where the data comes from and how to schedule it; the commands below follow.
Agent
Data
Schedule
Install the skill
One command. It puts the SKILL.md in ~/.claude/skills and in ~/.agents/skills, which Codex, Cursor, Gemini CLI, Copilot CLI and OpenCode read too.
shellcurl -fsSL https://briefkin.dev/skills/google-ads-anomaly-alert/install | sh
Run it
Ask Claude Code:
promptRun the google-ads-anomaly-alert skill
Or paste the prompt instead of installing:
promptUsing the Google Ads API (GAQL on the campaign resource), get daily cost, clicks, impressions and conversions for every enabled campaign from 29 days ago to yesterday, filling missing days with 0. For each campaign and metric, compare yesterday with the mean and standard deviation of the 28 days before it. Flag anything 2 or more standard deviations away where the gap is at least $50, 30 clicks or 3 conversions, and skip campaigns averaging under $20 a day. For each flagged campaign, check change_event for the last two days and name any change that explains it. Show a table of campaign, metric, yesterday, mean and score, then ask me which one to look into. If nothing is flagged, say all campaigns are within range.
Put it on a schedule
Every day at 9:00, from cron on any machine where Claude Code is signed in:
crontab0 9 * * * claude -p "Run the google-ads-anomaly-alert skill"
Add it with crontab -e. A laptop asleep at that time runs it when it wakes if you use launchd or Task Scheduler instead; GitHub Actions works for the API route.
Send it to your board
Connect Briefkin once with curl -fsSL https://briefkin.dev/install | sh and every run lands on your board as a question for you. How setup works
SKILL.md---
name: google-ads-anomaly-alert
description: "Every morning: the Google Ads campaigns whose spend, clicks or conversions yesterday sat more than two standard deviations from their 28-day norm. Use when the user asks for this, or when it runs on a schedule."
---
# Google Ads anomaly alert
Every morning: the Google Ads campaigns whose spend, clicks or conversions yesterday sat more than two standard deviations from their 28-day norm.
A bid strategy that runs hot, a broad match keyword that wakes up, a feed error that quietly starves Shopping: in Google Ads these show up as one strange day, and the account overview averages them away. Most people find out at the end of the week, after the money is spent.
This skill compares yesterday with each campaign's own last 28 days, metric by metric, and only speaks up when a number sits well outside its usual spread. It also reads the account's change history for that campaign, so the alert arrives with the likely reason attached instead of a bare "spend is up".
## Two ways to get the data
Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used.
## Route A: API or MCP server
### What you need
- Read access to the Google Ads account and its customer ID; through a manager account, its ID as `GOOGLE_ADS_LOGIN_CUSTOMER_ID`.
- Google's read-only Google Ads MCP server (`googleads/google-ads-mcp`), whose `search` tool runs GAQL, or Google Ads API OAuth credentials for a user with Read only access.
If something is missing, say what and stop; do not invent numbers.
### Steps
1. **Pull 29 days of campaign metrics** (Google Ads): Run GAQL with the MCP server's `search` tool or `googleAds:searchStream`: `SELECT campaign.id, campaign.name, segments.date, metrics.cost_micros, metrics.clicks, metrics.impressions, metrics.conversions FROM campaign WHERE campaign.status = 'ENABLED' AND segments.date BETWEEN '<29 days ago>' AND '<yesterday>'`. GAQL leaves out rows where every metric is zero, so fill missing dates with 0.
2. **Build each campaign's baseline**: For each campaign and metric, take the mean and standard deviation of the 28 days before yesterday, and score yesterday as `(yesterday - mean) / sd`. Skip campaigns with fewer than 14 days of data or under $20 of average daily spend; their spread is too noisy to judge.
3. **Keep the anomalies that matter**: Flag a metric when the score is 2 or more either way and the gap is material: at least $50 of spend, 30 clicks or 3 conversions. A spike in spend with flat conversions ranks above a spike in both.
4. **Look for the cause** (Google Ads): For each flagged campaign, query `change_event` (`change_event.change_date_time`, `change_event.change_resource_type`, `change_event.changed_fields`, `change_event.user_email`) for the last two days. It needs a date filter within the past 30 days and a `LIMIT`. Name the change if one lines up.
5. **Ask, or stay quiet**: With anomalies, post an action card: campaign, metric, yesterday against the mean, the score, and any matching change. On a normal day, update the same card with "all campaigns within range" and no question.
## Route B: the browser
### What you need
- Signed in to Google with a user that has at least Read only access to the Google Ads account; through a manager account, pick the client account first.
If something is missing, say what and stop; do not invent numbers.
### Steps
Start at https://ads.google.com/aw/campaigns. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears.
1. **Open the campaigns table for the last 29 days**: In Google Ads, open **Campaigns** and pick the account if more than one is listed. In the date picker, choose **Custom** from 29 days ago to yesterday. Set **Filter** to `Campaign status: Enabled`.
2. **Split the table by day**: Click **Segment** and choose **Time > Day**. Under **Columns**, make sure `Cost`, `Clicks`, `Impr.` and `Conversions` are shown. The table is now one row per campaign per day.
3. **Download instead of scrolling**: With more than a handful of campaigns the segmented table runs to hundreds of rows, so click **Download** and choose `.csv`, then read the file. Days with no activity are missing from the export; treat them as 0.
4. **Score yesterday against the 28 days before**: For each campaign and metric, take the mean and standard deviation of the 28 earlier days and score yesterday as `(yesterday - mean) / sd`. Skip campaigns averaging under $20 a day. Flag scores of 2 or more either way when the gap is at least $50, 30 clicks or 3 conversions.
5. **Check the change history**: For each flagged campaign, open **Campaigns > Change history** (`https://ads.google.com/aw/changehistory`), set the date range to the last 2 days and filter by that campaign. Note the change, who made it and when.
Note: The campaigns table cannot compute a standard deviation, so this route depends on the CSV download. Google Ads attributes conversions to the click date and keeps updating recent days, so yesterday's conversions read low in both routes. The web interface loads fully only on desktop.
## The report
- **Anomalies**: campaign, metric, yesterday's value, the 28-day mean and the score.
- **Likely cause** from the change history, when there is one.
- **Direction**: spending more for the same result, or delivering less than usual.
- The ask: which campaign to look into first.
## Post it to Briefkin
When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on.
```bash
[ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env
curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
-H "authorization: Bearer $BRIEFKIN_TOKEN" \
-H "content-type: application/json" \
-d @- <<'JSON'
{
"v": 1,
"event_id": "google-ads-anomaly-alert/<date of this run, e.g. 2026-10-16>",
"item_key": "google-ads-anomaly-alert",
"project": "Acme Store",
"source": "Google Ads anomaly alert skill",
"kind": "action",
"title": "2 campaigns out of pattern yesterday",
"summary": "**Brand - Search** spent **$1,240** against a 28-day mean of $410. **Shopping - Bestsellers** recorded **3 conversions** against a usual 19 while clicks held steady.",
"action": {
"request": "Brand spend tripled after its bid strategy changed to Maximize clicks at 14:20. Want me to dig into either campaign?",
"options": [
"Look into Brand",
"Look into Shopping",
"Both",
"Known, skip today"
]
},
"widget": [
{
"type": "Table",
"props": {
"columns": [
"Campaign",
"Metric",
"Yesterday",
"28-day mean",
"Score"
],
"align": [
"left",
"left",
"right",
"right",
"right"
],
"rows": [
[
"Brand - Search",
"Cost",
"$1,240",
"$410",
"+4.1"
],
[
"Brand - Search",
"Clicks",
1890,
820,
"+4.1"
],
[
"Shopping - Bestsellers",
"Conversions",
3,
19,
"-2.9"
]
]
}
},
{
"type": "Callout",
"props": {
"text": "Change history: Brand - Search bid strategy set to Maximize clicks by j.lee@acme.com yesterday at 14:20.",
"tone": "warn"
}
}
]
}
JSON
```
Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report.
## Run it on a schedule
Suggested: Every day at 9:00 (`0 9 * * *`). From cron, with the agent signed in on that machine:
```bash
0 9 * * * claude -p "Run the google-ads-anomaly-alert skill"
# Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run
```
Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/google-ads-anomaly-alert#schedule
Source: https://briefkin.dev/skills/google-ads-anomaly-alert
What your agent needs
Read access to the Google Ads account and its customer ID; through a manager account, its ID as GOOGLE_ADS_LOGIN_CUSTOMER_ID.
Google's read-only Google Ads MCP server (googleads/google-ads-mcp), whose search tool runs GAQL, or Google Ads API OAuth credentials for a user with Read only access.
Connecting Google Ads
Google Ads MCP server, Google's open-source, read-only server (google-ads-mcp, source). Run it locally with pipx run --spec git+https://github.com/googleads/google-ads-mcp.git google-ads-mcp, or deploy it to Cloud Run for remote clients. Its tools are list_accessible_customers, search for GAQL and get_resource_metadata (docs).
Google Ads API with OAuth. Enable the Google Ads API in a Google Cloud project, sign in with Application Default Credentials (gcloud auth application-default login with the adwords scope) or an OAuth client, and set GOOGLE_PROJECT_ID. Add GOOGLE_ADS_LOGIN_CUSTOMER_ID when you reach client accounts through a manager account, and write customer IDs without dashes.
The adwords scope can't be narrowed, so sign in as a Google Ads user with Read only access; the MCP server has no write tools either way.
Questions
Why standard deviations instead of a fixed percentage?
A 40% swing is normal for a campaign spending $30 a day and alarming for one spending $3,000. Scoring each campaign against its own spread adapts to both. If your account has a strong weekly cycle, switch the baseline to the same weekday over the last 8 weeks so Mondays are compared with Mondays.
Won't yesterday's conversions always look low?
Partly. Google Ads credits a conversion to the day of the click, and late conversions keep arriving for days. That is why a conversion drop only counts when clicks held steady, and why the threshold is 3 conversions. For accounts with long conversion lags, run the check on the day before yesterday instead.
Do I need Briefkin to use the Google Ads anomaly alert skill?
No. The skill runs with your own agent and gives you the report in the chat. With a Briefkin token set, each run also posts it to your board as a asks you, so you can glance at it instead of asking again.
Which agents can run it?
Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot CLI, OpenCode, Windsurf and Amp all read SKILL.md files. The install command puts it in ~/.claude/skills and ~/.agents/skills, where they look. ChatGPT, the Claude app and Grok take the prompt instead. Pick your agent under "Install and run it" and the commands change to match.
Can it work without an API or MCP server, from my browser?
Yes. Switch the data source to "Your browser" and the steps change to the Google Ads pages themselves: the agent opens ads.google.com/aw/campaigns in a browser you are signed in to and reads the numbers off the page. Claude Code, Codex, Cursor, Claude app and ChatGPT can drive a browser out of the box; Gemini CLI, Copilot CLI and OpenCode need a Playwright or Chrome DevTools MCP server first. It is slower than the API and needs you signed in, so it suits a report you run by hand or from a scheduler on your own computer.
Answer your agents from one board, or from Telegram
Skills are free to use with any agent. Briefkin is where their results land: one board for every report, number and question your agents send, with a ping when something needs you.