google-ads

Files (4)

• SKILL.md
• scenarios.json · evals/
• setup-and-operations.md · references/
• google_ads.py · scripts/

SKILL.md (first lines)

# 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:
   ```bash
   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:

```bash
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.

```bash
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:

```json
{
  "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:

```json

From HybridAIOne/hybridclaw, MIT.

More from HybridAIOne/hybridclaw