Google Ads

Google Ads Skill

Use the bundled scripts to fetch Google Ads data, audit account performance, analyze keywords/search terms, inspect conversion tracking, generate reports, and propose optimization actions.

Setup Check

Before any API task, verify:

1. GOOGLE_ADS_CONFIG points to a local google-ads.yaml, or google-ads.yaml exists in this skill directory.
2. GOOGLE_ADS_CUSTOMER_ID is set, or commands pass --customer_id.
3. Dependencies are installed:

python3 -m pip install -r .agents/skills/google-ads/requirements.txt

Test access:

python3 .agents/skills/google-ads/scripts/list_accounts.py

Optional Product Profile

For product-specific recommendations, ask the user for a product profile JSON or Markdown file. If none exists, use only account data and clearly state assumptions.

Recommended JSON fields:

• product_name
• website
• value_proposition
• target_audiences
• markets
• primary_conversions
• secondary_conversions
• ideal_search_intents
• negative_intents
• target_cpa
• notes

Do not invent product positioning, audience preference, geography, device strategy, or conversion priority without this profile.

Intent Routing

| User intent | Use | |---|---| | Setup/authentication | ads-setup | | Fetch campaign/keyword/search-term data | ads-fetch | | Analyze performance and optimization opportunities | ads-analyze | | Generate weekly/monthly report | ads-report | | Conversion tracking diagnosis | list_conversion_actions.py, check_conversions.py, get_conversion_settings.py | | Device/time/quality audits | audit_device_metrics.py, audit_time_segments.py, audit_quality_score.py | | Keyword operations | add_keywords.py, add_negative_keywords.py, pause_keyword.py |

Safety Rules

1. Never commit google-ads.yaml, OAuth client secrets, refresh tokens, exported private account data, or product profiles containing confidential data.
2. All mutation scripts are dry-run by default. Only run with --apply after showing the planned change and getting clear user confirmation.
3. Recommendations must cite the metrics they depend on: spend, clicks, conversions, CPA, CTR, quality score, device/time segment, or search term evidence.
4. Google Ads data can lag by a few hours; mention this for same-day analysis.
5. For low-volume campaigns, avoid strong conclusions from tiny samples.

Common Workflow

python3 .agents/skills/google-ads/scripts/fetch_campaigns.py --date_range LAST_30_DAYS --format json
python3 .agents/skills/google-ads/scripts/fetch_keywords.py --date_range LAST_30_DAYS --min_clicks 1 --format json
python3 .agents/skills/google-ads/scripts/fetch_search_terms.py --date_range LAST_30_DAYS --min_clicks 1 --format json
python3 .agents/skills/google-ads/scripts/audit_device_metrics.py --date_range LAST_30_DAYS
python3 .agents/skills/google-ads/scripts/audit_time_segments.py --date_range LAST_30_DAYS

Then combine the exported data with the product profile to produce:

1. Account summary.
2. Campaign winners and concerns.
3. High-intent keywords/search terms.
4. Wasteful queries or negative keyword candidates.
5. Conversion tracking issues.
6. Prioritized actions, each labeled as read-only recommendation or mutation candidate.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ccccchuck
• Source: ccccchuck/google-ads-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.