# Budget Guardian

> Monitors a Google Ads MCC for monthly budget overruns and sends Slack alerts at 100% and 120% of monthly budget per account. Designed to catch hijacked accounts, runaway PMax campaigns, and pacing-sheet formula errors within 2 hours instead of 24+. Alert-only — never pauses campaigns. Runs on GitHub Actions on a 2-hour cron. Use this skill when the user asks to "set up budget guardian", "install…

- **Type:** Skill
- **Install:** `agentstack add skill-fourteenwm-ppc-ai-skills-budget-guardian`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fourteenwm](https://agentstack.voostack.com/s/fourteenwm)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [fourteenwm](https://github.com/fourteenwm)
- **Source:** https://github.com/fourteenwm/ppc-ai-skills/tree/main/budget-guardian

## Install

```sh
agentstack add skill-fourteenwm-ppc-ai-skills-budget-guardian
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Budget Guardian

A spend tripwire for your Google Ads MCC. Scans every enabled account in your MCC every 2 hours. If month-to-date spend crosses 100% or 120% of the monthly budget you set, it pings Slack. **Alert-only — never pauses campaigns.**

## Why this exists

Two threats with the same shape — a spend spike nobody noticed until the damage was done.

The first is fat-fingering: a wrong formula or stale value in a budget sheet quietly pushing the wrong number across multiple accounts. The second is the industry-wide trend of hijacked MCCs and malicious spend — unauthorized PMax campaigns at huge daily budgets, drained accounts, agency-level changes nobody approved.

Daily checks miss the first 23 hours of either one. A 2-hour cron with per-threshold dedupe gets detection to ~2 hours, with one alert per account per threshold per month so Slack doesn't get spammed.

## Architecture

```
GitHub Actions (every 2 hours)
        |
        v
  Read budget sheet     ----->  Google Sheets API
        |                       (your per-account monthly budgets)
        v
  For each account:
    Query MTD spend     ----->  Google Ads API v23
        |                       (segments.date DURING THIS_MONTH)
        v
    Compare to budget
        |
        v
    Cross threshold?    ----->  Slack webhook
        |                       (100% warning / 120% critical)
        v
    Record alert        ----->  Google Sheets API
                                (state tab — dedupe within month)
```

## When Claude should invoke this skill

- User asks to "set up budget guardian", "install spend alerts", or "deploy budget guardian"
- User asks how to monitor MCC spend or catch hijacked accounts
- User asks about per-account budget alerting via Slack
- User describes an MCC hijack scenario, runaway PMax, or fat-fingered budget concerns

## How Claude helps the user deploy this

1. Confirm prerequisites are in place (Google Ads API access, Google Sheets OAuth token, Slack workspace, GitHub repo for the cron)
2. Walk through `README.md` setup steps — copying files, setting GitHub secrets, creating the budget sheet
3. Run `setup_tabs.py` once to bootstrap the `Guardian Config` and `Guardian State` tabs
4. Trigger a manual test run via `workflow_dispatch` to confirm Slack receives the test message
5. Set the kill switch to `ENABLED` in the sheet
6. Confirm the 2-hour cron is firing in the Actions tab

## Files in this skill

| File | Purpose |
|------|---------|
| `SKILL.md` | This file |
| `README.md` | Full setup guide with step-by-step deployment |
| `requirements.txt` | Python dependencies |
| `sheet-template.md` | Google Sheet column structure |
| `.github/workflows/budget-guardian.yml` | GitHub Actions cron config (every 2 hours) |
| `workflows/budget_guardian/main.py` | Entry point — orchestrates checks |
| `workflows/budget_guardian/ads_api.py` | Google Ads API client (MCC scan + MTD spend) |
| `workflows/budget_guardian/sheets_io.py` | Sheet reads/writes for budgets + state |
| `workflows/budget_guardian/slack.py` | Slack alert formatting |
| `workflows/budget_guardian/setup_tabs.py` | One-time bootstrap of Config + State tabs |
| `workflows/_shared/google_auth.py` | Google Sheets OAuth helper |
| `workflows/_shared/google_ads_auth.py` | Google Ads API OAuth helper |
| `workflows/_shared/sheets_retry.py` | Retry helper for transient Sheets errors |

## Configuration

All identity-bearing values are loaded from environment variables. Nothing is hardcoded.

| Env var | Purpose |
|---------|---------|
| `GUARDIAN_SHEET_ID` | Google Sheet ID where budgets and state live |
| `GUARDIAN_BUDGET_TAB` | Tab name with per-account budgets (default: `Budgets`) |
| `GOOGLE_TOKEN_PATH` | Path to your Google Sheets OAuth user token JSON |
| `GOOGLE_ADS_YAML_PATH` | Path to your Google Ads API YAML config |
| `SLACK_WEBHOOK_URL` | Incoming webhook URL for the channel that should receive alerts |
| `SLACK_USER_MENTION` | Optional — Slack user/group to @-mention on alerts (e.g. ``) |

## Tested against

- Google Ads API v23
- Python 3.12
- GitHub Actions (Ubuntu)
- Slack incoming webhooks (Block Kit)
- Google Sheets API v4 with OAuth user credentials
- Portfolios of 20-90 accounts

## What this skill deliberately does NOT do

- **Does not pause campaigns.** Alert-only by design. Auto-pause has too many failure modes for a public-default skill.
- **Does not modify Google Ads.** Read-only access is sufficient.
- **Does not need Anthropic credentials.** No LLM call in the loop — pure threshold math.
- **Does not require a brain.** Runs standalone on GitHub Actions; the SKILL.md just helps Claude help you deploy it.

## Source & license

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

- **Author:** [fourteenwm](https://github.com/fourteenwm)
- **Source:** [fourteenwm/ppc-ai-skills](https://github.com/fourteenwm/ppc-ai-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-fourteenwm-ppc-ai-skills-budget-guardian
- Seller: https://agentstack.voostack.com/s/fourteenwm
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.