google-ads-query

name	google-ads-query
description	Query Google Ads data and save to CSV. AUTO-ACTIVATE for: search terms, campaigns, keywords, ad groups, conversions, budgets, assets, geo performance. Also triggered by account names or "get/pull/show me" + Google Ads resource.
allowed-tools	["Read","Bash","Glob"]

Google Ads Query Skill

Query Google Ads API data, save to CSV, and return minimal output (file path + row count only).

Purpose

This skill implements the CSV-first pattern for context-efficient analysis:

1. Query API data
2. Save to CSV file (data stays outside context)
3. Return only file path + row count
4. Use csv-analyzer skill for analysis (separate step)

CRITICAL: Profile Lock Required

Before ANY query execution, verify profile is locked.

If no profile locked, respond:

Profile lock required. Say "agency_1" or "agency_2" to select profile.

Command Format

Get [resource] for [account] [days]d

Examples:

• Get search terms for Example Account → 30 days (default)
• Get campaigns for Example Account 60d → 60 days
• Get keywords for Example Account 90d sort:clicks

Defaults:

• Days: 30
• Sort: cost DESC

Process

Step 1: Verify Profile Lock

Check if profile is locked. If not, ask user to lock profile first.

Step 2: Parse Request

Extract:

1. Resource - Short name (see references/resources.md)
2. Account - Name or alias
3. Days - Time period (default 30)

Step 3: Resolve Account

Read credentials/[profile]/accounts.json:

• Match by key, name, or alias (case-insensitive)
• If no match, list similar accounts and ask

Step 4: Execute Query

python scripts/query.py \
  --profile [profile] \
  --account [account-key] \
  --resource [resource] \
  --days [days] \
  --output ./data/[profile]/[YYYYMMDD]-[account]-[resource].csv

Step 5: Return Minimal Output

Only return:

[PROFILE: agency_1]

Query complete.
File: data/google-ads/agency_1/20260109-example-account-search-terms.csv
Rows: 3,847

Say "analyze it" to run insights, or ask another query.

DO NOT:

• Display raw data in conversation
• Show sample rows
• Auto-analyze (wait for user to request)

Resources

See references/resources.md for resource mappings.

Short Name	Description	GAQL Template
search-terms	Search query report	search-terms.gaql
campaigns	Campaign performance	campaigns.gaql
keywords	Keyword performance	keywords.gaql
ad-groups	Ad group performance	ad-groups.gaql
conversions	Conversion tracking	conversions.gaql
budgets	Budget utilization	budgets.gaql
assets	Asset performance (PMAX)	assets.gaql
geo	Geographic performance	geo.gaql

File Naming Convention

data/google-ads/[profile]/[YYYYMMDD]-[account-slug]-[resource].csv

Examples:

• data/google-ads/agency_1/20260109-example-account-search-terms.csv
• data/google-ads/agency_1/20260109-example-campaigns.csv
• data/google-ads/agency_2/20260109-example-keywords.csv

Error Handling

Account not found:

Account "example-search" not found.

Similar matches:
- example-account (Example Account) - Portfolio 1

Did you mean example-account?

Query fails:

• Show error message
• Suggest common fixes (invalid date range, permissions)

Integration

After query completes, user can:

1. Say "analyze it" → triggers csv-analyzer skill
2. Ask for different resource/account
3. Re-query with different date range

Files

.claude/skills/google-ads-query/
├── SKILL.md                    ← This file
├── scripts/
│   └── query.py                ← Unified query→CSV script
└── references/
    ├── resources.md            ← Resource mappings
    └── *.gaql                  ← 8 query templates