Google Ads Agent Skill

A public, reusable Codex skill for Google Ads analysis and safe optimization workflows. It fetches account data through the Google Ads API, audits campaign health, analyzes keywords and search terms, reviews conversion tracking, and helps an agent produce data-backed recommendations for any product.

中文文档

Features

• Campaign, keyword, and search-term performance reports
• Device, time-of-day, campaign, and quality-score audits
• Conversion action listing, conversion breakdown, and tag snippet lookup
• Dry-run-first keyword operations:
  • add keywords
  • add campaign negative keywords
  • pause keyword criteria
  • set mobile bid modifiers
  • replace ad schedules from user-provided JSON
• Product-profile driven analysis so recommendations adapt to the user's product, market, audience, and conversion goals
• Environment-driven configuration with no hard-coded account IDs, company names, websites, or audience assumptions

Requirements

• Python 3.9+
• Google Ads API access
• A google-ads.yaml file with your developer token, OAuth client, refresh token, and optional manager-account login customer ID

Install dependencies:

python3 -m pip install -r requirements.txt

Setup

Copy the example environment file:

cp .env.example .env

Set:

export GOOGLE_ADS_CONFIG="/absolute/path/to/google-ads.yaml"
export GOOGLE_ADS_CUSTOMER_ID="YOUR_CUSTOMER_ID"
export GOOGLE_ADS_OUTPUT_DIR="./google-ads-output"
export GOOGLE_ADS_PRODUCT_PROFILE="./product_profile.example.json"

Test access:

python3 scripts/list_accounts.py

Product Profile

This skill does not assume your company, website, audience, geography, device preference, or conversion strategy. Add your own context in a product profile:

cp product_profile.example.json product_profile.json
export GOOGLE_ADS_PRODUCT_PROFILE="./product_profile.json"

The profile can include:

• product name and website
• value proposition
• target audiences
• markets
• primary and secondary conversions
• ideal search intents
• negative intents
• target CPA
• notes about funnel, seasonality, compliance, or landing pages

Agents should use this profile when interpreting search intent and prioritizing recommendations.

Quick Start

Fetch campaign data:

python3 scripts/fetch_campaigns.py --date_range LAST_30_DAYS --format table

Fetch keyword data:

python3 scripts/fetch_keywords.py --date_range LAST_30_DAYS --min_clicks 1 --format json

Fetch search terms:

python3 scripts/fetch_search_terms.py --date_range LAST_30_DAYS --min_clicks 1 --format json

Audit devices and time segments:

python3 scripts/audit_device_metrics.py --date_range LAST_30_DAYS
python3 scripts/audit_time_segments.py --date_range LAST_30_DAYS

Review conversion tracking:

python3 scripts/list_conversion_actions.py
python3 scripts/check_conversions.py --date_range LAST_30_DAYS

Safe Mutations

Mutation scripts are dry-run by default. They print the planned change and do nothing until --apply is passed.

Add keywords:

python3 scripts/add_keywords.py --ad_group_id AD_GROUP_ID --match_type PHRASE "example keyword"
python3 scripts/add_keywords.py --ad_group_id AD_GROUP_ID --match_type PHRASE --apply "example keyword"

Add negative keywords:

python3 scripts/add_negative_keywords.py --campaign_id CAMPAIGN_ID --match_type BROAD "irrelevant query"
python3 scripts/add_negative_keywords.py --campaign_id CAMPAIGN_ID --match_type BROAD --apply "irrelevant query"

Pause a keyword:

python3 scripts/pause_keyword.py --resource_name "customers/CUSTOMER_ID/adGroupCriteria/AD_GROUP_ID~CRITERION_ID"
python3 scripts/pause_keyword.py --resource_name "customers/CUSTOMER_ID/adGroupCriteria/AD_GROUP_ID~CRITERION_ID" --apply

Script Reference

Script	Purpose
list_accounts.py	List accessible Google Ads accounts
fetch_campaigns.py	Fetch campaign metrics
fetch_keywords.py	Fetch keyword metrics
fetch_search_terms.py	Fetch search-term metrics
audit_campaign_metrics.py	Review bidding, spend, conversions, and impression share
audit_device_metrics.py	Break down performance by device
audit_time_segments.py	Break down performance by hour and day
audit_quality_score.py	Review keyword quality-score components
list_conversion_actions.py	List conversion actions and settings
check_conversions.py	Show conversion breakdown by campaign/action
get_conversion_settings.py	Inspect conversion action settings
get_conversion_labels.py	Fetch webpage conversion snippets
list_custom_goals.py	List custom conversion goals
backup_conversions.py	Export conversion action metadata
add_keywords.py	Dry-run-first keyword creation
add_negative_keywords.py	Dry-run-first negative keyword creation
pause_keyword.py	Dry-run-first keyword pause
adjust_mobile_bids.py	Dry-run-first mobile bid modifier update
adjust_ad_schedules.py	Dry-run-first ad schedule replacement

Public Repo Safety

Do not commit:

• google-ads.yaml
• OAuth client secret JSON files
• refresh tokens
• exported account data
• private product profiles

The included .gitignore blocks common sensitive files, but always review commits before pushing.

License

MIT