Skip to content
Skills Library
Marketing & content · Automation

google-ads-scripts

/google-ads-scripts

Google Ads Scripts development - JavaScript run inside the Google Ads UI against the AdsApp API and GAQL. Use when writing a script to pause or enable keywords, adjusting bids or budgets from performance rules, pulling a GAQL report into Google Sheets, monitoring quality scores, alerting on spend or anomalies by email, or running a script across accounts from a manager (MCC) account. Do NOT use for the Google Ads API from Python, REST or gRPC - this covers Ads Scripts only. Do NOT use for Google Apps Script outside Google Ads - use google-apps-script. Do NOT use for Microsoft Ads, Meta Ads or

Licence
MIT
Last repository change
04.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
8
Scripts
3
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 04.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 3 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: assets/bid-manager-template.js, assets/campaign-optimizer-template.js, scripts/validators.py

What it does and when to use it

Google Ads Scripts development - JavaScript run inside the Google Ads UI against the AdsApp API and GAQL. Use when writing a script to pause or enable keywords, adjusting bids or budgets from performance rules, pulling a GAQL report into Google Sheets, monitoring quality scores, alerting on spend or anomalies by email, or running a script across accounts from a manager (MCC) account. Do NOT use for the Google Ads API from Python, REST or gRPC - this covers Ads Scripts only. Do NOT use for Google Apps Script outside Google Ads - use google-apps-script. Do NOT use for Microsoft Ads, Meta Ads or

Original author description

Google Ads Scripts development - JavaScript run inside the Google Ads UI against the AdsApp API and GAQL. Use when writing a script to pause or enable keywords, adjusting bids or budgets from performance rules, pulling a GAQL report into Google Sheets, monitoring quality scores, alerting on spend or anomalies by email, or running a script across accounts from a manager (MCC) account. Do NOT use for the Google Ads API from Python, REST or gRPC - this covers Ads Scripts only. Do NOT use for Google Apps Script outside Google Ads - use google-apps-script. Do NOT use for Microsoft Ads, Meta Ads or

How it works

  1. Steps
  2. Quick start
  3. Gotchas
  4. Validation
  5. References
Original SKILL.md headings · 63 lines, 626 words
SKILL.md preview
---
name: google-ads-scripts
description: Google Ads Scripts development - JavaScript run inside the Google Ads UI against the AdsApp API and GAQL. Use when writing a script to pause or enable keywords, adjusting bids or budgets from performance rules, pulling a GAQL report into Google Sheets, monitoring quality scores, alerting on spend or anomalies by email, or running a script across accounts from a manager (MCC) account. Do NOT use for the Google Ads API from Python, REST or gRPC - this covers Ads Scripts only. Do NOT use for Google Apps Script outside Google Ads - use google-apps-script. Do NOT use for Microsoft Ads, Meta Ads or other ad platforms.
---

# Google Ads Scripts

JavaScript that runs in Google Ads (Tools > Bulk actions > Scripts) on the Google Ads API. Selector conditions and reports use GAQL field names (`campaign.status`, `ad_group_criterion.quality_info.quality_score`, `metrics.cost_micros`); Google picks the API version, so scripts do not pin one.

## Steps

1. **Read with the cheapest tool.** Use selectors (`AdsApp.keywords().withCondition(...)`) when you will modify the entities you read. Use `AdsApp.search` or `AdsApp.report` with a GAQL query when you need metrics the `Stats` object lacks (conversion value, ROAS, impression share, quality-score components) or rows across many entities. Done when every metric the script uses comes from a source that actually returns it.

2. **Filter on the server.** Put every filter in `.withCondition()` or the GAQL `WHERE`, add `.forDateRange('LAST_30_DAYS')` (or another relative range) whenever a condition touches `metrics.*`, and cap with `.withLimit()`. Done when no JavaScript `if` re-filters what a condition could have filtered, and no date is hard-coded.

3. **Get the units right.** Entity methods are in account currency (`Stats.getCost()`, `Budget.setAmount(50)`, `keyword.bidding().setCpc(1.25)`); GAQL is in micros (`metrics.cost_micros > 100000000` means 100). Done when every `/ 1000000` divides a GAQL `*_micros` value and nothing else.

4. **Gate every mutation.** Ship with `DRY_RUN = true`, clamp each change (minimum and maximum bid, maximum percentage change per run), skip shared budgets unless intended (`budget.isExplicitlyShared()`), and record what changed to a Sheet or email. Done when a dry run logs exactly the changes a live run would make.

5. **Fit the 30-minute limit.** Collect the IDs to change first, then mutate; fetch entities in bulk with `.withIds([...])` (10,000 per selector). For manager accounts use `AdsManagerApp.accounts().executeInParallel(...)` (50 accounts per call). Done when the run time is bounded by `.withLimit()` or batch size, not account size.

## Quick start

Pause keywords with a low quality score and real spend:

```javascript
const DRY_RUN = true;

function main() {
  const keywords = AdsApp.keywords()
    .withCondition('ad_group_criterion.status = ENABLED')
    .withCondition('ad_group_criterion.quality_info.quality_score < 4')
    .withCondition('metrics.cost_micros > 100000000')   // 100 in account currency
    .forDateRange('LAST_30_DAYS')
    .get();

  let count = 0;
  while (keywords.hasNext()) {
    const keyword = keywords.next();
    Logger.log(`${DRY_RUN ? '[dry run] ' : ''}Pause ${keyword.getText()} (QS ${keyword.getQualityScore()})`);
    if (!DRY_RUN) keyword.pause();
    count++;
  }
  Logger.log(`${count} keywords matched`);
}
```

## Gotchas

- **Removed since 14 July 2025:** `AdsApp.AdCustomizerSource`, `newAdCustomizerSourceBuilder()` and `withOnlyLegacy()` on extension selectors throw sunset errors. Use asset-based customizers (`{CUSTOMIZER.name:default}`) in Responsive Search Ads, set up in the Google Ads UI or API.
- **No campaign creation** from scripts - use Bulk Uploads or the Google Ads API. Expanded Text Ads cannot be created; build Responsive Search Ads.
- **No `getMaxCpc` / `setMaxCpc` / `getReturnOnAdSpend`.** Bids go through `entity.bidding().getCpc()` / `setCpc()`, and ROAS is `metrics.conversions_value / (metrics.cost_micros / 1e6)` from GAQL. Keyword CPC bids only bite under manual CPC.
- **`AdsApp.search` rows are lowerCamelCase** (`row.metrics.costMicros`) even though the query is snake_case; int64 values may be strings, so wrap in `Number()`.
- **Spreadsheets:** there is no active spreadsheet - open by URL or ID. Logs view under the script's run history; output past 100 KB is truncated.

## Validation

`scripts/validators.py` checks campaign names, keyword text (80 characters, 10 words), match types, campaign types, bids, budgets and currency/micros conversion before you hard-code them. Run `python3 "${CLAUDE_SKILL_DIR}/scripts/validators.py"` for a self-test, or import its functions.

## References

- [references/ads-api-reference.md](references/ads-api-reference.md) - read when you need a method signature, a GAQL field prefix for a selector, targeting/bid-modifier calls, manager-account patterns, or the limits table.
- [references/examples.md](references/examples.md) - read when building a keyword pauser, ROAS bid adjuster or Sheets performance export from scratch.
- [references/patterns.md](references/patterns.md) - read when adding day-of-week budget changes or quality-score alerting.
- [references/best-practices.md](references/best-practices.md) - read when reviewing an existing script for filtering, error handling, unit or audit-log problems.
- `assets/bid-manager-template.js` and `assets/campaign-optimizer-template.js` - copy as the starting point for a keyword bid manager or campaign budget optimiser; both default to dry run.
Files in this package (8)
  • SKILL.md 5 KB
  • assets/bid-manager-template.js 14 KB
  • assets/campaign-optimizer-template.js 10 KB
  • references/ads-api-reference.md 13 KB
  • references/best-practices.md 3 KB
  • references/examples.md 4 KB
  • references/patterns.md 2 KB
  • scripts/validators.py 12 KB

Versions

The database has no other skills named google-ads-scripts.

Database snapshot: 13.11.2026 · package version 16bdee44d59d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100google-ads
    Query Google Ads campaigns, ad groups, keywords and spend via the Google Ads API (GAQL searchStream). Use when the user mentions Google Ads, ad campaigns, ad spend / cost, impressions / clicks / conversions on ads, or campaign performance.
  • 100google-ads-analyst
    Analyze Google Ads accounts through the Google Ads MCP server (googleads/google-ads-mcp, e.g. deployed with mcp-googleads-open). Use whenever the user asks about Google Ads performance, campaigns, spend, conversions, keywords, search terms, budgets, impression share, devices,…
  • 100google-ads-scripts-rules-writer
    Writes, explains and fixes Google Ads scripts and automated rules for budget caps, broken URL checks, zero-conversion keywords, search terms to Sheets and spend jump alerts. Use when asking for a Google Ads script or rule, or pasting a script error. Not for GAQL reports (use gaql-report-builder).
  • 100gaql-report-builder
    Writes and fixes GAQL (Google Ads Query Language) queries from a plain reporting question, runs them read-only when Google Ads is connected, and adds API, Google Ads script and BigQuery versions. Use when asking for a GAQL query, a custom Google Ads report, GAQL examples, or a query that errors.
  • 100google-ads-write
    Use when ANY change needs to be made to a Google Ads account — pausing campaigns, changing budgets, adding negative keywords, updating bids, enabling/disabling ad groups, modifying targeting, or any mutate operation. ALWAYS use this skill before making changes. Never modify a…
  • 100google-ads-custom-gaql
    Use this skill when the user needs Google Ads data that no packaged report type carries, or asks for a Custom GAQL source. Triggers include: 'I need a Google Ads field that isn't in any report', 'can I get hourly Google Ads data', 'break conversions down by action at ad group…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.