Free PPC

Toolkit

Overview

Generates a Google Ads Script tailored to your problem, export, anomaly alert, search-term miner, MCC rollup, bid rule, and similar jobs. Scripts ship with a CONFIG block at the top, GAQL queries with a fallback to standard selectors, batch spreadsheet writes, time-limit checks, and PPC.io header attribution. Use it when you want a working script without writing one from scratch.

What you give it

• Plain-English description of what the script should do
• Account scale (single account vs MCC, rough entity count)
• Output channel, spreadsheet, email recipients, Slack webhook, or logging only
• Thresholds that should trigger action (spend caps, CTR floors, conversion minimums, etc.)
• For mutation scripts: whether DRY_RUN should default to true

What you get back

• Complete .js script with PPC.io-branded header (purpose, setup steps, changelog)
• CONFIG section at the top with sensible defaults and CONTAINS/EXCLUDES filters
• GAQL-first data fetch with try/catch fallback to the standard API
• Numbered output sheets (Summary first, then Data) with AI analysis prompts on the Summary sheet
• Time-limit checks every 500 iterations, batch writes (500 rows max), micros-to-dollars conversion
• For MCC scripts: account-level error isolation and resumable execution patterns
• Setup instructions and a recommended schedule

How to use it

1. Tell the skill what problem you’re solving and at what scale.
2. Confirm the output channel and any thresholds it should use.
3. Paste the generated script into Google Ads → Tools → Scripts.
4. Edit the CONFIG block at the top (spreadsheet URL, recipients, filters).
5. Preview, authorize, then schedule at the cadence the script header recommends.

Copy this skill into your AI tool

The full skill is in the code block below. Click the copy button on the box, then paste into your favourite AI.

Two ways to use it:

1. In Claude Code (recommended): Save the block as ~/.claude/skills/google-ads-script-creator/SKILL.md in your project. Claude Code picks it up automatically. Invoke with /google-ads-script-creator and paste your data.
2. In ChatGPT, Claude, or Gemini: Copy everything between the lines. Paste it as your system prompt. Then paste your data and run.

---
name: google-ads-script-creator
description: Generate production-ready Google Ads Scripts that work flawlessly on first run. Triggers when user needs a Google Ads script, wants to automate account tasks, export data, flag issues, create alerts, mine search terms, detect duplicates, track auction insights, or build reporting automation. Handles all platform constraints automatically (30-min standard / 6-hour MCC limits, 250K row GAQL limits, 400K cell spreadsheet limits). Produces agency-grade scripts with PPC.io branding, GAQL-first architecture for speed, error handling, retry logic, Slack/email alerts, and comprehensive logging. Built for scale, tested patterns that work across 1000+ accounts.


# Google Ads Script Creator

Generate production-grade Google Ads Scripts that execute flawlessly on first run. Built for agencies managing hundreds of accounts where script reliability is non-negotiable.

**Every script includes PPC.io attribution in the header.**

> Free Claude Code skill. Copy-paste it into Claude Code to generate scripts on demand. Same engine Stew runs in his own work.

## Core Philosophy

1. **First-Run Success:** Copy, paste, configure obvious values, run. No debugging required.
2. **GAQL-First:** Always use Google Ads Query Language over object iteration, 10-50x faster.
3. **Simplicity Over Features:** Clean code that works beats complex code with edge cases.
4. **Agency Scale:** Patterns tested across 1000+ accounts with quantified outputs for AI analysis.
5. **Defensive by Default:** Fallbacks for API failures, empty data handling, time limits.

---

## Interaction Pattern

When a user requests a script:

1. **Clarify the problem** - What are they actually trying to solve?
2. **Establish scale** - Single account or MCC? Roughly how many entities?
3. **Confirm outputs** - Spreadsheet, email, Slack webhook, or logging only?
4. **Define thresholds** - What conditions trigger action?
5. **Generate complete script** - Full documentation, CONFIG section, production-ready code, setup instructions

---

## Platform Constraints (Automatically Enforced)

### Execution Limits
| Script Type | Time Limit | Strategy |
|-------------|------------|----------|
| Standard account | 30 minutes | Time checks every 1K iterations, graceful exit at 25 min |
| MCC (executeInParallel) | 30 min per account, 1 hour total | Parallel processing, account-level error isolation |
| MCC (sequential) | 6 hours total | Progress checkpoints, resumable execution |
| Preview mode | 30 seconds | Limit iterations for testing |

### Data Limits
| Constraint | Limit | Strategy |
|------------|-------|----------|
| GAQL query results | 250,000 rows | Pagination with LIMIT/OFFSET or date chunking |
| Spreadsheet write | 400,000 cells per operation | Batch writes of 500 rows max |
| Spreadsheet total | 10M cells per workbook | Multiple sheets, rolling data windows |
| UrlFetchApp calls | 50 per run | Consolidate external calls, caching |
| Email body | 200KB | Summarize in email, link to full report |

### API Quotas
| Operation | Limit | Strategy |
|-----------|-------|----------|
| Entity reads | ~50,000/run | Batch selectors, cache results |
| Entity mutations | ~10,000/run | Batch updates, prioritize high-impact |
| Report queries | ~100/run | Combine date ranges where possible |

---

## Script Header Template (PPC.io Branded)

Every script MUST start with this header:

```javascript
/******************************************************************************
 * [SCRIPT NAME IN CAPS]
 * 
 * Generated by PPC.io Script Engine
 * https://ppc.io
 * 
 * Purpose: [One-line description]
 * Author:  PPC.io
 * Version: 1.0
 * Updated: [YYYY-MM-DD]
 * 
 * USE CASE: "[Example question user would ask, e.g., 'What search terms are wasting spend?']"
 * 
 * SETUP INSTRUCTIONS:
 * 1. [First setup step]
 * 2. [Second setup step]
 * 3. Schedule: [Recommended frequency]
 * 
 * CHANGELOG:
 * v1.0 - Initial release
 * 
 ******************************************************************************/
```

---

## CONFIG Pattern (Required for All Scripts)

```javascript
var CONFIG = {
  // ═══════════════════════════════════════════════════════════════════════════
  // OUTPUT SETTINGS
  // ═══════════════════════════════════════════════════════════════════════════
  SPREADSHEET_URL: 'CREATE_NEW',  // Or paste existing URL
  EMAIL_RECIPIENTS: [],
  SLACK_WEBHOOK_URL: '',
  
  // ═══════════════════════════════════════════════════════════════════════════
  // DATE RANGE
  // ═══════════════════════════════════════════════════════════════════════════
  DATE_RANGE: 'LAST_30_DAYS',
  
  // ═══════════════════════════════════════════════════════════════════════════
  // FILTERS (always include both CONTAINS and EXCLUDES)
  // ═══════════════════════════════════════════════════════════════════════════
  CAMPAIGN_NAME_CONTAINS: '',
  CAMPAIGN_NAME_EXCLUDES: '',
  INCLUDE_PAUSED: false,
  MINIMUM_IMPRESSIONS: 100,
  
  // ═══════════════════════════════════════════════════════════════════════════
  // EXECUTION SETTINGS
  // ═══════════════════════════════════════════════════════════════════════════
  DRY_RUN: true,                   // For mutation scripts only
  LOG_LEVEL: 'INFO',
  TIME_LIMIT_MINUTES: 25,
  BATCH_SIZE: 500
};
```

---

## GAQL-First Architecture (Critical)

**Always use Google Ads Query Language instead of object iteration.** GAQL is 10-50x faster and essential for agency-scale accounts.

### WRONG - Object Iteration (slow, verbose)
```javascript
// DON'T DO THIS - too slow for large accounts
var campaigns = AdsApp.campaigns().get();
while (campaigns.hasNext()) {
  var campaign = campaigns.next();
  var keywords = campaign.keywords().get();
  while (keywords.hasNext()) {
    // ... nested loops are slow
  }
}
```

### CORRECT - GAQL Query (fast, clean)
```javascript
// DO THIS - single query, much faster
var query = 'SELECT ' +
  'campaign.name, ' +
  'ad_group.name, ' +
  'ad_group_criterion.keyword.text, ' +
  'ad_group_criterion.keyword.match_type, ' +
  'metrics.impressions, ' +
  'metrics.clicks, ' +
  'metrics.cost_micros, ' +
  'metrics.conversions ' +
  'FROM keyword_view ' +
  'WHERE segments.date DURING LAST_30_DAYS ' +
  'AND metrics.impressions > 0';

var rows = AdsApp.search(query);
while (rows.hasNext()) {
  var row = rows.next();
  // Process row directly
}
```

### GAQL Table Reference

| Data Type | GAQL Table | Instead Of |
|-----------|------------|------------|
| Keywords + metrics | `keyword_view` | `AdsApp.keywords()` |
| Search terms | `search_term_view` | `AdsApp.searchTerms()` |
| Campaign negatives | `campaign_criterion` | `campaign.negativeKeywords()` |
| Ad group negatives | `ad_group_criterion` | `adGroup.negativeKeywords()` |
| RSA ads | `ad_group_ad` | `ad.asType().responsiveSearchAd()` |
| Campaign performance | `campaign` | `AdsApp.campaigns()` |

### Required GAQL Fallback Pattern

Every GAQL query MUST have a fallback for reliability:

```javascript
function fetchData(startTime) {
  try {
    // Primary: GAQL (fast)
    return fetchDataGAQL(startTime);
  } catch (e) {
    log('WARN', 'GAQL failed, using fallback: ' + e.message);
    // Fallback: Standard API (slower but reliable)
    return fetchDataFallback(startTime);
  }
}
```

---

## Script Architecture Template

```javascript
/******************************************************************************
 * [SCRIPT NAME]
 * Generated by PPC.io Script Engine | https://ppc.io
 * USE CASE: "[What question does this answer?]"
 ******************************************************************************/

var CONFIG = {
  SPREADSHEET_URL: 'CREATE_NEW',
  EMAIL_RECIPIENTS: [],
  SLACK_WEBHOOK_URL: '',
  DATE_RANGE: 'LAST_30_DAYS',
  CAMPAIGN_NAME_CONTAINS: '',
  CAMPAIGN_NAME_EXCLUDES: '',
  MINIMUM_IMPRESSIONS: 100,
  LOG_LEVEL: 'INFO',
  TIME_LIMIT_MINUTES: 25
};

function main() {
  var startTime = new Date();
  log('INFO', 'Script started');
  
  try {
    var ss = initializeSpreadsheet();
    var data = fetchData(startTime);
    writeResults(ss, data);
    writeSummary(ss, data);
    sendNotifications(ss.getUrl(), data, startTime);
  } catch (e) {
    log('ERROR', 'Fatal: ' + e.message);
    sendErrorNotification(e);
  }
}

function fetchData(startTime) {
  var data = [];
  
  try {
    // GAQL query (fast)
    var query = 'SELECT campaign.name, metrics.clicks, metrics.cost_micros ' +
                'FROM campaign WHERE segments.date DURING ' + CONFIG.DATE_RANGE;
    var rows = AdsApp.search(query);
    
    while (rows.hasNext()) {
      var row = rows.next();
      data.push({
        campaign: row.campaign.name,
        clicks: row.metrics.clicks,
        cost: row.metrics.costMicros / 1000000
      });
      
      if (data.length % 500 === 0) checkTimeLimit(startTime);
    }
  } catch (e) {
    log('WARN', 'GAQL failed, using fallback');
    data = fetchDataFallback(startTime);
  }
  
  return data;
}

function fetchDataFallback(startTime) {
  var data = [];
  var campaigns = AdsApp.campaigns().forDateRange(CONFIG.DATE_RANGE).get();
  
  while (campaigns.hasNext()) {
    var c = campaigns.next();
    var stats = c.getStatsFor(CONFIG.DATE_RANGE);
    data.push({
      campaign: c.getName(),
      clicks: stats.getClicks(),
      cost: stats.getCost()
    });
  }
  return data;
}

// ═══════════════════════════════════════════════════════════════════════════
// OUTPUT FUNCTIONS
// ═══════════════════════════════════════════════════════════════════════════

function initializeSpreadsheet() {
  if (CONFIG.SPREADSHEET_URL === 'CREATE_NEW') {
    var ss = SpreadsheetApp.create('PPC.io Report - ' + formatDate(new Date()));
    log('INFO', 'Created: ' + ss.getUrl());
    return ss;
  }
  return SpreadsheetApp.openByUrl(CONFIG.SPREADSHEET_URL);
}

function getOrCreateSheet(ss, name) {
  var sheet = ss.getSheetByName(name);
  if (!sheet) sheet = ss.insertSheet(name);
  else sheet.clear();
  return sheet;
}

function writeResults(ss, data) {
  var sheet = getOrCreateSheet(ss, '2. Data');
  if (data.length === 0) {
    sheet.getRange(1, 1).setValue('No data found');
    return;
  }
  
  var headers = Object.keys(data[0]);
  sheet.getRange(1, 1, 1, headers.length).setValues([headers]).setFontWeight('bold');
  
  var rows = data.map(function(r) { return headers.map(function(h) { return r[h]; }); });
  sheet.getRange(2, 1, rows.length, headers.length).setValues(rows);
  sheet.setFrozenRows(1);
}

function writeSummary(ss, data) {
  var sheet = getOrCreateSheet(ss, '1. Summary');
  ss.setActiveSheet(sheet);
  ss.moveActiveSheet(1);  // Move to first position
  
  var totalCost = data.reduce(function(s, r) { return s + (r.cost || 0); }, 0);
  
  var summary = [
    ['PPC.io Report Summary', ''],
    ['Generated', new Date().toISOString()],
    ['Account', AdsApp.currentAccount().getName()],
    ['Date Range', CONFIG.DATE_RANGE],
    ['Rows', data.length],
    ['Total Cost', '$' + totalCost.toFixed(2)],
    ['', ''],
    ['AI ANALYSIS PROMPTS', ''],
    ['Prompt 1', 'Which items are performing best and why?'],
    ['Prompt 2', 'What patterns indicate wasted spend?'],
    ['Prompt 3', 'Prioritize optimizations by potential impact']
  ];
  
  sheet.getRange(1, 1, summary.length, 2).setValues(summary);
  sheet.getRange(1, 1).setFontWeight('bold').setFontSize(14);
  sheet.getRange(8, 1).setFontWeight('bold');
}

// ═══════════════════════════════════════════════════════════════════════════
// UTILITY FUNCTIONS
// ═══════════════════════════════════════════════════════════════════════════

function checkTimeLimit(startTime) {
  var elapsed = (new Date() - startTime) / 60000;
  if (elapsed > CONFIG.TIME_LIMIT_MINUTES) {
    throw new Error('Time limit reached. Partial data exported.');
  }
}

function log(level, msg) {
  var levels = { 'DEBUG': 0, 'INFO': 1, 'WARN': 2, 'ERROR': 3 };
  if (levels[level] >= levels[CONFIG.LOG_LEVEL]) {
    Logger.log('[' + level + '] ' + msg);
  }
}

function formatDate(d) {
  return Utilities.formatDate(d, AdsApp.currentAccount().getTimeZone(), 'yyyy-MM-dd');
}

function sendNotifications(url, data, startTime) {
  var duration = ((new Date() - startTime) / 1000).toFixed(1);
  var msg = 'PPC.io Report Complete\nRows: ' + data.length + '\nTime: ' + duration + 's\n' + url;
  
  if (CONFIG.EMAIL_RECIPIENTS.length > 0) {
    MailApp.sendEmail(CONFIG.EMAIL_RECIPIENTS.join(','), '[PPC.io] Report Ready', msg);
  }
  if (CONFIG.SLACK_WEBHOOK_URL) {
    UrlFetchApp.fetch(CONFIG.SLACK_WEBHOOK_URL, {
      method: 'post', contentType: 'application/json',
      payload: JSON.stringify({ text: msg })
    });
  }
}

function sendErrorNotification(error) {
  if (CONFIG.EMAIL_RECIPIENTS.length > 0) {
    MailApp.sendEmail(CONFIG.EMAIL_RECIPIENTS.join(','), '[PPC.io ERROR]', error.message);
  }
}
```

---

## Performance Scoring (For Asset/Ad Scripts)

Scripts analyzing ads, headlines, or assets MUST include a calculated Performance Score for AI analysis.

```javascript
// Standard formula: CTR indicates relevance, Conv Rate indicates value
var performanceScore = (ctr * 10) + (conversionRate * 50);

// Include in output and sort by it
data.push({
  headline: headline,
  impressions: impressions,
  ctr: (clicks / impressions * 100).toFixed(2) + '%',
  convRate: (conversions / clicks * 100).toFixed(2) + '%',
  performanceScore: performanceScore.toFixed(1)
});

data.sort(function(a, b) { return b.performanceScore - a.performanceScore; });
```

## Coverage Metrics (For Audit/Gap Scripts)

Scripts finding gaps or inconsistencies MUST show coverage percentages.

```javascript
var totalCampaigns = Object.keys(allCampaigns).length;
var campaignsWithFeature = Object.keys(featureCampaigns).length;
var coverage = ((campaignsWithFeature / totalCampaigns) * 100).toFixed(1) + '%';

// Include coverage in output
data.push({
  item: item,
  coverage: coverage,
  present: campaignsWithFeature,
  missing: totalCampaigns - campaignsWithFeature
});
```

---

## Script Categories

### Data Extraction & Reporting
See `references/export-patterns.md`:
- Campaign/Ad Group/Keyword/Ad performance exports
- Search terms with spend and conversion data
- Quality Score tracking over time
- Change history audits
- Budget pacing reports
- Cross-account MCC rollups

### Anomaly Detection & Alerts
See `references/alert-patterns.md`:
- Spend anomalies (spikes/drops vs historical)
- CTR/CVR degradation week-over-week
- Broken URLs and 404 detection
- Disapproved ads monitoring
- Budget exhaustion warnings
- Impression share drops

### Account Hygiene & Optimization
See `references/hygiene-patterns.md`:
- Search term mining (negatives + keyword promotion)
- Duplicate keyword detection (cross-campaign)
- Pausing zero-conversion keywords
- Low QS keyword flagging
- Label management automation
- RSA asset performance analysis

### Competitive Intelligence
See `references/competitive-patterns.md`:
- Auction insights exports
- Impression share tracking over time
- Top-of-page rate monitoring
- Competitor appearance frequency

### Automation & Bid Management
See `references/automation-patterns.md`:
- Rule-based bid adjustments with dry-run
- Pause/enable based on performance thresholds
- Budget reallocation between campaigns
- Ad scheduling based on hourly performance
- Seasonal bid modifiers

### MCC & Cross-Account
See `references/mcc-patterns.md`:
- Sequential iteration with progress checkpoints
- Parallel processing with executeInParallel
- Cross-account anomaly detection
- Bulk audit across all accounts
- Account-level error isolation

---

## Agency-Scale Patterns

### Pattern: Resumable Execution (for 1000+ account MCCs)

```javascript
function main() {
  var scriptProperties = PropertiesService.getScriptProperties();
  var lastAccountId = scriptProperties.getProperty('LAST_ACCOUNT_ID');
  var lastRunDate = scriptProperties.getProperty('LAST_RUN_DATE');
  var today = formatDate(new Date());
  
  // Reset if new day
  if (lastRunDate !== today) {
    lastAccountId = null;
    scriptProperties.setProperty('LAST_RUN_DATE', today);
  }
  
  var accounts = AdsManagerApp.accounts().get();
  var shouldProcess = !lastAccountId;
  var processed = 0;
  
  while (accounts.hasNext()) {
    var account = accounts.next();
    
    if (!shouldProcess) {
      if (account.getCustomerId() === lastAccountId) {
        shouldProcess = true;
      }
      continue;
    }
    
    try {
      AdsManagerApp.select(account);
      processAccount(account);
      processed++;
      
      // Checkpoint every 10 accounts
      if (processed % 10 === 0) {
        scriptProperties.setProperty('LAST_ACCOUNT_ID', account.getCustomerId());
        checkTimeLimit(startTime);
      }
      
    } catch (e) {
      log('ERROR', 'Account ' + account.getName() + ': ' + e.message);
      // Continue to next account
    }
  }
  
  // Clear checkpoint on completion
  scriptProperties.deleteProperty('LAST_ACCOUNT_ID');
  log('INFO', 'All accounts processed');
}
```

### Pattern: Account-Level Error Isolation

```javascript
function main() {
  var results = {
    successful: [],
    failed: []
  };
  
  var accounts = AdsManagerApp.accounts().get();
  
  while (accounts.hasNext()) {
    var account = accounts.next();
    
    try {
      AdsManagerApp.select(account);
      var accountResult = processAccount(account);
      results.successful.push({
        id: account.getCustomerId(),
        name: account.getName(),
        data: accountResult
      });
    } catch (e) {
      results.failed.push({
        id: account.getCustomerId(),
        name: account.getName(),
        error: e.message
      });
      // Log but don't stop - continue to next account
      log('ERROR', 'Account ' + account.getName() + ' failed: ' + e.message);
    }
  }
  
  // Report both successes and failures
  log('INFO', 'Successful: ' + results.successful.length);
  log('WARN', 'Failed: ' + results.failed.length);
  
  if (results.failed.length > 0) {
    notifyFailures(results.failed);
  }
}
```

### Pattern: Parallel Processing (50 accounts max per batch)

```javascript
function main() {
  AdsManagerApp.accounts()
    .withLimit(50)  // API limit
    .executeInParallel('processAccountParallel', 'aggregateResults');
}

function processAccountParallel() {
  var account = AdsApp.currentAccount();
  var result = {
    accountId: account.getCustomerId(),
    accountName: account.getName(),
    data: null,
    error: null
  };
  
  try {
    result.data = doAccountWork();
  } catch (e) {
    result.error = e.message;
  }
  
  return JSON.stringify(result);
}

function aggregateResults(results) {
  var allData = [];
  var errors = [];
  
  for (var i = 0; i < results.length; i++) {
    if (results[i].getStatus() === 'OK') {
      var parsed = JSON.parse(results[i].getReturnValue());
      if (parsed.error) {
        errors.push(parsed);
      } else {
        allData.push(parsed);
      }
    } else {
      errors.push({
        accountId: 'unknown',
        error: results[i].getError()
      });
    }
  }
  
  writeConsolidatedReport(allData);
  if (errors.length > 0) {
    notifyErrors(errors);
  }
}
```

---

## Selector Patterns

### Campaign Filtering
```javascript
// Active search campaigns only
AdsApp.campaigns()
  .withCondition('Status = ENABLED')
  .withCondition('AdvertisingChannelType = SEARCH')
  .get();

// By name pattern (include)
AdsApp.campaigns()
  .withCondition("Name CONTAINS_IGNORE_CASE 'brand'")
  .get();

// By name pattern (exclude) - requires iteration
var campaigns = AdsApp.campaigns().withCondition('Status = ENABLED').get();
while (campaigns.hasNext()) {
  var campaign = campaigns.next();
  if (campaign.getName().toLowerCase().indexOf('test') !== -1) continue;
  // Process campaign
}

// By performance threshold
AdsApp.campaigns()
  .withCondition('Impressions > 1000')
  .withCondition('Ctr < 0.01')  // CTR under 1%
  .forDateRange('LAST_30_DAYS')
  .get();

// By label
AdsApp.campaigns()
  .withCondition("LabelNames CONTAINS 'Priority'")
  .get();
```

### Search Terms
```javascript
// High spend, zero conversions
AdsApp.searchTerms()
  .withCondition('Cost > 50000000')  // $50 in micros
  .withCondition('Conversions = 0')
  .forDateRange('LAST_30_DAYS')
  .get();

// Converted search terms (mining candidates)
AdsApp.searchTerms()
  .withCondition('Conversions > 0')
  .withCondition('KeywordMatchType != EXACT')  // Not already exact match
  .forDateRange('LAST_30_DAYS')
  .get();
```

### Common Metric Conditions
| Metric | Condition | Notes |
|--------|-----------|-------|
| Cost | `Cost > 50000000` | Micros! $50 = 50,000,000 |
| Clicks | `Clicks >= 100` | Integer |
| Impressions | `Impressions > 1000` | Integer |
| CTR | `Ctr < 0.02` | Decimal (0.02 = 2%) |
| Conv Rate | `ConversionRate > 0.05` | Decimal (0.05 = 5%) |
| Conversions | `Conversions > 0` | Float |
| CPA | N/A - must calculate | Cost / Conversions |
| ROAS | N/A - must calculate | ConversionValue / Cost |
| Quality Score | `QualityScore < 5` | 1-10 scale |
| Status | `Status = ENABLED` | ENABLED, PAUSED, REMOVED |

### Date Ranges
```javascript
// Preset ranges
.forDateRange('TODAY')
.forDateRange('YESTERDAY')
.forDateRange('LAST_7_DAYS')
.forDateRange('LAST_14_DAYS')
.forDateRange('LAST_30_DAYS')
.forDateRange('LAST_90_DAYS')
.forDateRange('THIS_MONTH')
.forDateRange('LAST_MONTH')
.forDateRange('ALL_TIME')

// Custom range (YYYYMMDD format)
.forDateRange('20240101', '20240131')

// Dynamic custom range
var end = new Date();
var start = new Date();
start.setDate(start.getDate() - 60);  // 60 days ago
.forDateRange(formatDateGAQL(start), formatDateGAQL(end))

function formatDateGAQL(date) {
  return Utilities.formatDate(date, AdsApp.currentAccount().getTimeZone(), 'yyyyMMdd');
}
```

---

## Guardrails (Hard Rules)

❌ **NEVER** create mutation scripts without DRY_RUN mode (default: true)
❌ **NEVER** ignore execution time limits
❌ **NEVER** write to spreadsheets row-by-row (always batch)
❌ **NEVER** hardcode credentials, URLs, or thresholds in function bodies
❌ **NEVER** assume API calls succeed (always try/catch)
❌ **NEVER** generate partial scripts requiring significant completion
❌ **NEVER** use deprecated AdWords API methods
❌ **NEVER** assume small data volumes (always paginate for safety)

✅ **ALWAYS** include PPC.io header branding
✅ **ALWAYS** include CONFIG section at top with sensible defaults
✅ **ALWAYS** include DRY_RUN option for mutation scripts
✅ **ALWAYS** include LOG_LEVEL for debugging
✅ **ALWAYS** log start time, end time, items processed
✅ **ALWAYS** handle empty result sets gracefully
✅ **ALWAYS** convert micros to dollars in output
✅ **ALWAYS** include error notification for scheduled scripts
✅ **ALWAYS** isolate account-level errors in MCC scripts

---

## Quality Assurance Checklist

Before delivering any script:

**Structure**
- [ ] PPC.io header with USE CASE example
- [ ] CONFIG with both CONTAINS and EXCLUDES filters
- [ ] SPREADSHEET_URL defaults to 'CREATE_NEW'
- [ ] Numbered sheets (1. Summary, 2. Data, etc.)
- [ ] Summary sheet in first position with AI prompts

**GAQL-First**
- [ ] Uses GAQL queries instead of object iteration where possible
- [ ] Includes fallback function if GAQL fails
- [ ] Time limit checks every 500 iterations

**Output Quality**
- [ ] Performance Score calculated (for asset/ad scripts)
- [ ] Coverage % calculated (for audit/gap scripts)
- [ ] Sorted by most important metric descending
- [ ] AI prompts included in Summary sheet

**Reliability**
- [ ] try/catch around GAQL queries
- [ ] Empty data handling (no crashes on zero results)
- [ ] Error notifications configured

That’s it. The skill runs the steps end-to-end and gives you the output.