Google Ads

Query, audit, and optimize Google Ads campaigns. Supports two modes: (1) API mode for bulk operations with google-ads Python SDK, (2) Browser automation mode for users without API access - just attach a browser tab to ads.google.com. Use when asked to check ad performance, pause campaigns/keywords, find wasted spend, audit conversion tracking, or optimize Google Ads accounts.

Security Scan

The skill's requirements and instructions align with its Google Ads auditing/automation purpose; it is instruction-only and reasonably scoped, but it will read local Google Ads credentials/config and needs a browser relay for browser-mode interactions so users should be cautious with secrets and trust the skill source.

Purpose & Capability

Name/description match what the SKILL.md actually instructs: API mode uses the google-ads Python SDK and a google-ads.yaml config; browser mode uses a browser relay to operate on ads.google.com. Declared dependency on python3 and required config path (~/.google-ads.yaml) are appropriate for the stated features.

Instruction Scope

The runtime instructions explicitly tell the agent to read ~/.google-ads.yaml (or google-ads.yaml) and to run python snippets that use the google-ads SDK, and to snapshot/click within the user's browser session. Reading the config is expected for API mode, but it means the agent will access sensitive API credentials/refresh tokens. The skill also references environment variables (GOOGLE_ADS_*) as an alternative, but those env vars are not declared in the registry metadata — a minor mismatch.

Install Mechanism

This is an instruction-only skill with no install spec or code files. That minimizes footprint — the SKILL.md suggests installing the google-ads Python package if needed, but no automatic downloads or archive extraction are declared.

Credentials

The skill requests access to ~/.google-ads.yaml (which contains developer_token, client_id/secret, refresh_token) — this is proportional to API-mode functionality but is sensitive. The registry lists no required env vars, while the docs mention GOOGLE_ADS_* env variables as alternatives; the discrepancy should be resolved. There are no unrelated credentials requested.

Persistence & Privilege

always:false and no install behavior means the skill does not demand permanent presence or elevated platform privileges. It does require an interactive browser relay for browser mode, which is expected and limited to the Google Ads UI context.

Assessment

This skill appears coherent for managing Google Ads, but it will read your local google-ads.yaml (or expect env vars) which contains sensitive tokens (developer token, client_secret, refresh_token). Only install/use it if you trust the skill source (source/homepage are unknown). If you prefer not to expose API credentials, use the browser automation mode (which operates on your logged-in browser session) but ensure the browser relay/extension is trustworthy. Avoid running sample commands that print tokens to stdout; verify any outputs before sharing. If you do provide API credentials and later doubt the skill, rotate the credentials/refresh tokens. Finally, prefer installing the google-ads SDK yourself in a controlled environment rather than letting untrusted code request you to pip-install packages.

Google Ads Skill

Manage Google Ads accounts via API or browser automation.

Mode Selection

Check which mode to use:

1. API Mode - If user has google-ads.yaml configured or GOOGLE_ADS_* env vars
2. Browser Mode - If user says "I don't have API access" or just wants quick checks

# Check for API config
ls ~/.google-ads.yaml 2>/dev/null || ls google-ads.yaml 2>/dev/null

If no config found, ask: "Do you have Google Ads API credentials, or should I use browser automation?"

---

Browser Automation Mode (Universal)

Requirements: User logged into ads.google.com in browser

Setup

1. User opens ads.google.com and logs in
2. User clicks Clawdbot Browser Relay toolbar icon (badge ON)
3. Use browser tool with profile="chrome"

Common Workflows

Get Campaign Performance

1. Navigate to: ads.google.com/aw/campaigns
2. Set date range (top right date picker)
3. Snapshot the campaigns table
4. Parse: Campaign, Status, Budget, Cost, Conversions, Cost/Conv

Find Zero-Conversion Keywords (Wasted Spend)

1. Navigate to: ads.google.com/aw/keywords
2. Click "Add filter" → Conversions → Less than → 1
3. Click "Add filter" → Cost → Greater than → [threshold, e.g., $500]
4. Sort by Cost descending
5. Snapshot table for analysis

Pause Keywords/Campaigns

1. Navigate to keywords or campaigns view
2. Check boxes for items to pause
3. Click "Edit" dropdown → "Pause"
4. Confirm action

Download Reports

1. Navigate to desired view (campaigns, keywords, etc.)
2. Click "Download" icon (top right of table)
3. Select format (CSV recommended)
4. File downloads to user's Downloads folder

For detailed browser selectors: See references/browser-workflows.md

---

API Mode (Power Users)

Requirements: Google Ads API developer token + OAuth credentials

Setup Check

# Verify google-ads SDK
python -c "from google.ads.googleads.client import GoogleAdsClient; print('OK')"

# Check config
cat ~/.google-ads.yaml

Common Operations

Query Campaign Performance

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()
ga_service = client.get_service("GoogleAdsService")

query = """
    SELECT campaign.name, campaign.status,
           metrics.cost_micros, metrics.conversions,
           metrics.cost_per_conversion
    FROM campaign
    WHERE segments.date DURING LAST_30_DAYS
    ORDER BY metrics.cost_micros DESC
"""

response = ga_service.search(customer_id=CUSTOMER_ID, query=query)

Find Zero-Conversion Keywords

query = """
    SELECT ad_group_criterion.keyword.text,
           campaign.name, metrics.cost_micros
    FROM keyword_view
    WHERE metrics.conversions = 0
      AND metrics.cost_micros > 500000000
      AND segments.date DURING LAST_90_DAYS
    ORDER BY metrics.cost_micros DESC
"""

Pause Keywords

operations = []
for keyword_id in keywords_to_pause:
    operation = client.get_type("AdGroupCriterionOperation")
    operation.update.resource_name = f"customers/{customer_id}/adGroupCriteria/{ad_group_id}~{keyword_id}"
    operation.update.status = client.enums.AdGroupCriterionStatusEnum.PAUSED
    operations.append(operation)

service.mutate_ad_group_criteria(customer_id=customer_id, operations=operations)

For full API reference: See references/api-setup.md

---

Audit Checklist

Quick health check for any Google Ads account:

Check	Browser Path	What to Look For
Zero-conv keywords	Keywords → Filter: Conv<1, Cost>$500	Wasted spend
Empty ad groups	Ad Groups → Filter: Ads=0	No creative running
Policy violations	Campaigns → Status column	Yellow warning icons
Optimization Score	Overview page (top right)	Below 70% = action needed
Conversion tracking	Tools → Conversions	Inactive/no recent data

---

Output Formats

When reporting findings, use tables:

## Campaign Performance (Last 30 Days)
| Campaign | Cost | Conv | CPA | Status |
|----------|------|------|-----|--------|
| Branded  | $5K  | 50   | $100| ✅ Good |
| SDK Web  | $10K | 2    | $5K | ❌ Pause |

## Recommended Actions
1. **PAUSE**: SDK Web campaign ($5K CPA)
2. **INCREASE**: Branded budget (strong performer)

---

Troubleshooting

Browser Mode Issues

• Can't see data: Check user is on correct account (top right account selector)
• Slow loading: Google Ads UI is heavy; wait for tables to fully load
• Session expired: User needs to re-login to ads.google.com

API Mode Issues

• Authentication failed: Refresh OAuth token, check google-ads.yaml
• Developer token rejected: Ensure token is approved (not test mode)
• Customer ID error: Use 10-digit ID without dashes