/google-ads

name: google-ads
description: "Manage Google Ads accounts with safe GAQL reporting, campaign planning, guarded mutations, and gateway-proxied REST API calls."
user-invocable: true
requires:
  bins:
    - python3
metadata:
  hybridclaw:
    category: marketing
    short_description: "Google Ads reporting and safe operations."
    tags:
      - google-ads
      - gaql
      - ppc
      - marketing
      - reporting
    stakes_tiers:
      green:
        - gaql-reporting
        - schema-introspection
        - recommendation-read
        - audience-count-read
      amber:
        - ad-group-edit
        - keyword-edit
        - audience-segment-create
        - recommendation-apply
        - recommendation-dismiss
      red:
        - budget-mutation
        - campaign-enable
        - campaign-pause
        - ad-copy-submit
        - bid-strategy-switch
        - customer-match-upload
        - conversion-action-edit
    escalation:
      writes: confirm-each
      route: f14
    cost_measurement:
      system: UsageTotals
      sub_limit_contract: R5.4
      sub_limit_key: google-ads

Google Ads

Use this skill for Google Ads API work: GAQL reports, account and campaign inspection, campaign/ad group/ad/keyword planning, recommendation review, and carefully gated account mutations.

Scope

• list accessible customers and MCC children
• run GAQL reporting queries through the official Google Ads REST API
• translate common English and German reporting requests into reviewable GAQL
• reuse the R21.6 NL-to-SQL review prompt payload shape for GAQL model review
• plan campaign, ad group, keyword, budget, bid strategy, recommendation, and

audience operations with an explicit stakes tier

• execute approved campaign create/status/rename/remove/bid-strategy changes
• execute approved daily and lifetime budget updates
• execute approved ad group, keyword, and ad lifecycle changes
• execute approved Customer Match, remarketing, lookalike, and in-market/user

interest audience operations

• execute approved conversion action create/status/attribution changes
• apply or dismiss approved Google Ads recommendations
• enforce brand-voice review before any ad-copy field is submitted
• refuse budget, campaign-state, bid strategy, ad-copy submission,

conversion-action edit, and customer-match upload actions unless the user has already provided an explicit operator grant for that exact action

• measure skill run cost through normal HybridClaw `UsageTotals`

Default Workflow

1. Start with reads. For reporting, draft or generate GAQL, review it, then run it only if the query is scoped enough for the request. 2. For live read-only Google Ads API calls, use `http_request` directly. Do not run the helper through `bash` for account listing, GAQL execution, or other read-only REST calls when `http_request` is available. 3. Use the bundled helper only for offline planning/review utilities and guarded mutation commands:

   python3 skills/google-ads/scripts/google_ads.py ...

4. Use `plan` before every write-like request. The plan output carries `stakesTier`, `requiresEscalation`, `requiredGrant`, and `brandVoiceGateRequired` fields. 5. Do not execute amber or red operations from the plan unless the user has granted the exact `requiredGrant` in the same turn or through an approved F14 escalation. 6. Run `/brand-voice` before submitting any generated headline, description, sitelink, callout, or other ad-copy asset. If brand voice is not configured, keep the copy as a draft and ask for approval before submission. 7. Use `http_request` for direct query execution and the helper `report-plan` when the user asks in natural language and a GAQL query must be generated.

Secret Refs

Use `http_request` for live Google Ads HTTP calls. OAuth access tokens and the developer token are injected server-side by the gateway from secret handles, so real values never enter the model context. The helper uses the same gateway contract only for commands that explicitly require helper-side validation.

Required setup:

hybridclaw auth login google \
  --client-id "<google-oauth-client-id>" \
  --client-secret "<google-oauth-client-secret>" \
  --account you@example.com \
  --scopes "https://www.googleapis.com/auth/adwords"

hybridclaw auth status google

Set `GOOGLEADS_DEVELOPER_TOKEN` in this order:

1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets`. 2. Browser `/chat` or TUI fallback: `/secret set GOOGLEADS_DEVELOPER_TOKEN "<developer-token>"`. 3. Local console fallback: `hybridclaw secret set GOOGLEADS_DEVELOPER_TOKEN "<developer-token>"`.

Do not ask the user to add `secret route` entries for normal Google Ads skill use. The skill should pass `bearerSecretName: "GOOGLE_WORKSPACE_CLI_TOKEN"` and `secretHeaders: [{ "name": "developer-token", "secretName": "GOOGLEADS_DEVELOPER_TOKEN", "prefix": "" }]` in each `http_request` call.

Optional stored defaults use the same setup order: browser admin at `/admin/secrets`, then `/secret set` in browser `/chat` or TUI, then local console fallback.

hybridclaw secret set GOOGLEADS_CUSTOMER_ID "<customer-id-without-hyphens>"
hybridclaw secret set GOOGLEADS_LOGIN_CUSTOMER_ID "<manager-id-without-hyphens>"

If the account is managed through an MCC, include `--login-customer-id` on live commands or store `GOOGLEADS_LOGIN_CUSTOMER_ID`. Customer ids must be sent to the API without hyphens.

Command Contract

List accessible Google Ads customers:

{
  "url": "https://googleads.googleapis.com/v20/customers:listAccessibleCustomers",
  "method": "GET",
  "bearerSecretName": "GOOGLE_WORKSPACE_CLI_TOKEN",
  "secretHeaders": [
    {
      "name": "developer-token",
      "secretName": "GOOGLEADS_DEVELOPER_TOKEN",
      "prefix": ""
    }
  ],
  "skillName": "google-ads"
}

Run a GAQL report:

{
  "url": "https://googleads.googleapis.com/v20/customers/1234