PAID ADS SKILL PACK BY ADDITION
Google Ads experiments without fooling yourself
One treatment, one metric, a fixed analysis date and a decision rule written before launch; a helper that describes the arms and refuses to call a winner.
For Google Ads practitioners running a budget, bidding or creative experiment. Install with Node.js and npm; the reading helper runs on Python 3.10 or newer.
npx skills add addition-labs/skills --skill google-ads-experiments
google-ads-experimentsby Additionv2.0.0released 2026-09-15commit 931d10bMIT licencereport a problem
Google Ads can split-test a budget, a bidding target or a creative change against a copy of the campaign. The tool is fine; the reading mistakes are old: a winner on day four, a percentage rounded into a story, a metric nobody chose before launch. This pack fixes the decisions before the experiment exists and keeps the reading descriptive until the pre-registered rule and the scorecard’s own interval say otherwise.
Before launch: campaign and experiment type, one treatment, the decision metric (CPA or ROAS), the effect size worth acting on, allocation, start date, a fixed analysis date after two full weekly cycles plus the conversion-lag cutoff, the confidence setting and decision rule, and a freeze list for the base campaign. During: no peeking, no edits, external events logged with dates.
After: a small helper takes cost, conversions and value per arm and prints per-arm CPA or ROAS with the relative difference, then says that aggregate totals do not provide an uncertainty estimate. The decision comes from the rule and the experiment’s reported interval, not from the helper.
When to use it
Ask for the review you need
Ask in your own words or name the installed skill explicitly. Requests like these load it:
- test a budget change
- set up a bidding experiment
- read this experiment
- is the trial arm winning
What you can review
Plan the experiment, then read it against the plan
Pre-registration
The record written before the experiment exists: type, one treatment, metric, effect size, allocation, dates, lag cutoff, confidence and decision rule, freeze list. The 50 and 100 conversion minimums are Addition screening heuristics, not power calculations.
Setup
Which Experiments page path to use, what to record about type, allocation and reporting normalisation, and when to stop because the intended treatment is not available for that campaign type.
Reading helper
read_experiment.py with --control and --trial as cost,conversions,value[,clicks], --metric and --days. Validates the arms (finite, non-negative, cost above zero) and prints a descriptive line; fractional conversions print as supplied.
Allowed and forbidden sentences
Allowed: the helper’s line, and a decision phrased against the pre-registered rule and the scorecard interval. Forbidden: "already showing", rounded percentages, "significant" from totals alone, any metric that was not pre-registered.
What the inputs cannot establish
- Significance from arm totals: cost, conversions and value do not carry an uncertainty estimate; only the scorecard’s interval for the chosen metric does.
- Whether the base campaign was left alone: the helper reads totals, not the change history.
- The split Google delivered against the setting, and the effect of conversion lag on the last days of the window.
- Anything about a metric that was not pre-registered, including clicks and CPC.
See it in action
One real run, in full
Executed on synthetic arm totals for a fictional budget experiment; the pre-registration record was written for the run. No live experiment has been read with this version.
Start with the request, then read the complete result. The input and output files are linked below the run.
The budget experiment on Generic - Search reached its analysis date. Control: 4200 cost, 63 conversions, 5100 value, 3000 clicks. Trial: 4150, 81, 5900, 3100. 28 days. Metric CPA. The pre-registration record is attached. Read it and tell me whether we apply.
$ python3 scripts/read_experiment.py --control 4200,63,5100,3000 --trial 4150,81,5900,3100 --metric cpa --days 28
Trial CPA 51.23 vs control 66.67 over 28 days, with 81 and 63 conversions (-23.1%). Descriptive comparison only. These aggregate totals do not provide a valid uncertainty estimate for CPA. No apply decision is supported by this calculation alone.
Reading the experiment against its pre-registration record
What was pre-registered (from the record supplied with the ask): campaign type Search, experiment type custom experiment on a copy of the base campaign; one treatment, daily budget raised from 150 to 200 in the trial arm; decision metric CPA; effect worth acting on, a CPA at least 10% below control; allocation 50/50 by search traffic; start 2026-08-18; fixed analysis date 2026-09-14, after two full weekly cycles plus a 7-day conversion-lag cutoff; decision rule, apply only if the scorecard's interval for CPA at the account's selected confidence setting excludes zero and the observed difference clears 10%; freeze list, bidding strategy, ad copy, keywords, negatives and schedules on the base campaign.
What the helper says: trial CPA 51.23 against control 66.67 over 28 days, 81 and 63 conversions, a relative difference of −23.1%. Descriptive comparison only.
Decision: No apply decision. The pre-registered rule needs the experiment scorecard's reported interval for CPA at the selected confidence setting, and that interval was not supplied with the arm totals. The observed difference clears the 10% threshold, but aggregate totals do not provide an uncertainty estimate, so the rule's first condition cannot be evaluated. Next step: open the experiment's scorecard in Google Ads, record the CPA interval and the confidence setting as shown, and re-read against the rule. Do not edit the base campaign in the meantime.
Checked before reading: the analysis date has passed (2026-09-14) and the conversion-lag cutoff of 7 days is complete as of 2026-09-21; the external-events log for the window records no promotion, stockout or price change. Both are taken from the supplied record, not verified against the account.
Not measured: the scorecard interval; whether the base campaign was edited during the run; the actual split delivered by Google against the 50/50 setting.
Files from this run
- command.txt The exact command, helper version and environment.
- arms.csv Input: the two arm totals as supplied to the helper.
What this run could not do
A scorecard interval, so no apply decision; a live experiment read.
Before you install
Files you can inspect before installing
The agent loads this skill when your task matches its description. Supporting files are read when the workflow calls for them.
google-ads-experiments/SKILL.md- The SKILL.md: the pre-registration record, setup in the Experiments page, the rules while it runs, the reading, and the sentences the agent may and may not write.
scripts/read_experiment.py- Per-arm CPA or ROAS and the relative difference from validated totals; standard library only; writes nothing.
PROMPTS.md- The prompts for the pre-registration record, the setup check, the running log and the reading.
CHECKLIST.md- Before launch, while it runs, and on the analysis date.
README.md- What it does, inside, needs, safety, example run and limits, in one page.
LICENSE- MIT licence text as installed with the folder.
CHANGELOG.md- What changed in each version.
First run
- Install the pack into your agent from the account’s working folder.
npx skills add addition-labs/skills --skill google-ads-experiments - Write the pre-registration record with the first prompt in PROMPTS.md before creating anything in Google Ads; keep it beside the account files.
- On the analysis date, after the lag cutoff, export both arms and run the helper with the pre-registered metric.
python3 "/path/to/google-ads-experiments/scripts/read_experiment.py" --control 4200,63,5100,3000 --trial 4150,81,5900,3100 --metric cpa --days 28 - Ask the agent to read the result against the record and the scorecard interval; it decides only when the rule can be evaluated.
Reading the results
What you can conclude from these results
An experiment answers one question that was written down before it started. Read the record first, then the scorecard’s interval for the metric it names, then the helper’s line; in that order the helper cannot become the decision. A difference that clears the threshold without an interval is a reason to fetch the interval, not to apply.
The pack stops at the reading. In an engagement the next step is the second experiment: the winning setting becomes the new base only after a pre-registered follow-up confirms it on a different window.
Google’s Recommendations tab is never the source of a treatment; the Experiments page is used directly.
Background: A/B testing
SKILL.md
The file the agent reads
MIT licence, copyright Addition Labs LLC; the file as it is in addition-labs/skills, commit 931d10b.
Open SKILL.md (711 words)
---
name: google-ads-experiments
description: >-
Plan and review a Google Ads experiment for a specific campaign type and
business decision. Use when the user wants to test a bidding, budget or
creative change, or interpret a completed experiment. Define the treatment,
metric, allocation, analysis date and decision rule; summarize CPA or ROAS
from validated arm totals and use the chosen metric's reported uncertainty.
Aggregate totals alone cannot establish significance. Produces a plan or
review; does not create or apply an account experiment.
metadata:
version: 2.0.0
released: 2026-09-15
author: addition-labs.com
---
# Google Ads experiments: plan first, then read, in that order
## Before you create the experiment (the pre-registration record)
Record the campaign type and supported experiment type; the single treatment; the business decision metric; the effect
size worth acting on; the randomization and reporting unit; traffic or budget allocation; start date; fixed analysis
date; conversion-lag cutoff; confidence setting and decision rule; and the settings that must remain unchanged. Record
the sample-size rationale separately. The historical 50/100-conversion rules are Addition screening heuristics, not
power calculations, Google requirements or proof of significance. A low-volume result is inconclusive unless the
pre-registered rule says otherwise.
- **One treatment.** Budget, or bidding target, or creative, or match type. Not two.
- **Decision metric.** Cost divided by conversions (CPA), or conversion value divided by cost (ROAS). Not clicks, not CPC.
- **Fixed analysis date**, set before launch, after at least two full weekly cycles plus the conversion-lag cutoff.
- **Allocation and experiment type**, recorded as Google shows them, with the reporting normalization.
- **Freeze list.** Every setting on the base campaign that will not be touched during the test.
## Setting it up in Google Ads
Open Campaigns, then Experiments, then create an experiment using the type supported for the selected campaign. Record
the campaign and experiment type, eligible treatment settings, split type and reporting normalization before creating
it. If the intended budget or bidding treatment is not available for that type, stop and report that limitation. Do not
substitute a different experiment without changing the plan. Use the Experiments page directly; do not use Google's
Recommendations tab.
## While it runs
- Do not read the result before the analysis date. A "winner" on day four is a coin flip with a chart.
- Do not edit the base campaign. Every edit is an edit to the control.
- Log external events with dates: promo, stockout, price change, Google update. Concurrent randomization helps both arms
experience the same external conditions. An even split does not guarantee balance, and an unequal split does not by
itself create seasonal bias. Record allocation, experiment type, conversion lag and any reporting normalization before
comparing arms.
## Reading it (analysis date, after the conversion-lag cutoff)
Export both arms: cost, conversions, conversion value, optionally clicks. Then:
```bash
python3 "/absolute/path/to/installed/google-ads-experiments/scripts/read_experiment.py" \
--control 4200,63,5100,3000 --trial 4150,81,5900,3100 --metric cpa --days 28
```
The helper calculates observed CPA or ROAS and relative difference. It does not test significance. For a decision, use
the experiment's reported interval for the pre-registered metric and confidence setting, together with the planned
decision rule and completed conversion-lag window. If the required interval or suitable underlying data is unavailable,
report a descriptive comparison and no statistical decision. Google's experiment scorecard reports metric-specific
confidence; preserve its selected setting rather than replacing it with a different threshold. The checklist controls
when to analyze; the helper does not verify the experiment's history. Commas delimit the arm fields, so thousands
separators are not accepted.
## Sentences you are allowed to write
- The helper's line: "Trial CPA X vs control Y over N days, with A and B conversions (Z%). Descriptive comparison only."
- "Apply / retain control / inconclusive, by the pre-registered rule, using the scorecard interval for <metric> at
<confidence>."
## Sentences you are not allowed to write
- "The test is already showing" (before the analysis date)
- "Roughly a 20% improvement" (rounded; use the number)
- "Significant" from arm totals alone, or anything about a metric that was not the pre-registered decision metric
- An extension decided after inspecting results, unless the pre-registered design specifies that procedure
## Safety
The helper reads command-line numbers only: no network, no files, no credentials, no subprocesses. It creates or
applies nothing in the account.
Questions
Requirements and troubleshooting
What do I install first?
Node.js with npm for the installer and Python 3.10 or newer for the helper. The installer adds the instructions and the helper to your agent; it does not create the experiment in Google Ads.
Why does the helper refuse to say who won?
Because it cannot know. Arm totals carry no uncertainty estimate; the experiment scorecard reports an interval for the metric at your selected confidence setting, and the decision rule you wrote before launch is evaluated against that.
Why did the helper stop?
It names the reason: a missing field, a fifth field, a zero cost, a duration that is not positive, or an arm with zero conversions when the metric is CPA. Fix the export; do not pad it.
What does a difference of zero mean?
That the arms produced the same observed metric over the window. It is still a descriptive result; whether the treatment had no effect is a question for the interval and the rule.
Will installing this connect my Google Ads account?
No. Installation adds files. The experiment is created and read in the Google Ads interface by you; the pack plans and reads, it applies nothing.