budget-guardian
Skill72 starsChanged 4 months agoMITView on GitHub
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 spend alerts", monitor MCC spend, or build a tripwire against unauthorized PMax campaigns.
In this repository41 other files it gives its agents.
- account-diagnosticSkill
- ad-copy-generation-frameworkSkill
- ad-copy-verification-standardSkill
- add-account-negative-keywordsSkill
- ads-checkerSkill
- budget-recommendation-calculatorSkill
- change-history-checkerSkill
- client-communication-standardsSkill
- competitor-analysis-v2Skill
- conversion-tracking-healthSkill
- dgen-automation-disableSkill
- fair-housing-complianceSkill
- ga4-campaign-cross-referenceSkill
- ga4-cross-analysisSkill
- ga4-lead-quality-investigationSkill
- gaql-query-patternsSkill
- geo-conflict-analyzerSkill
- google-ads-api-setupSkill
- google-ads-querySkill
- google-ads-samplesSkill
- impression-share-diagnosticsSkill
- investigation-methodologySkill
- lead-quality-pattern-analysisSkill
- lead-quality-recommendation-prioritizationSkill
- markdown-to-sheets-presenterSkill
- mcc-hack-auditSkill
- mutation-safetySkill
- neg-conflict-finderSkill
- non-serving-keyword-scannerSkill
- pmax-asset-automationSkill
- pmax-builderSkill
- portfolio-health-prioritizationSkill
- portfolio-pacing-rulesSkill
- rsa-bulk-editSkill
- rsa-refreshSkill
- rsa-single-accountSkill
- shared-budget-updaterSkill
- sqr-classifierSkill
- sqr-pipelineSkill
- underspending-investigationSkill
- youtube-placement-auditSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 55
Run setup_tabs.py once to bootstrap the Guardian Config and Guardian State tabs
- Very specific: line 101
All identity-bearing values are loaded from environment variables — nothing identity-bearing is hardcoded.
- Distinctive: line 119
Does not modify Google Ads: Read-only access is sufficient.
- Distinctive: line 120
Does not need Anthropic credentials: No LLM call in the loop — pure threshold math.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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.
Pairs with Shared Budget Updater — the execution arm: it pushes sheet-approved budgets; the Guardian is the tripwire watching what gets spent against them.
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
- Confirm prerequisites are in place (Google Ads API access, Google Sheets OAuth token, Slack workspace, GitHub repo for the cron)
- Walk through
README.mdsetup steps — copying files, setting GitHub secrets, creating the budget sheet - Run
setup_tabs.pyonce to bootstrap theGuardian ConfigandGuardian Statetabs - Trigger a manual test run via
workflow_dispatchto confirm Slack receives the test message - Set the kill switch to
ENABLEDin the sheet - Confirm the 2-hour cron is firing in the Actions tab
Once deployed, the work shifts from setup to triage: every alert gets read
per rules.md before anyone acts on it.
When an alert fires — where it routes
Triage itself lives in rules.md (read it before acting on any
alert; examples.md shows worked reads). What triage
surfaces routes to siblings:
| Trigger | Load |
| 120% incident — need who/what/when on recent changes | change-history-checker |
| Change history shows actors or campaigns nobody authorized | mcc-hack-audit — sweep the whole MCC, not just the alerting account |
| "What should this account's budget actually be?" | budget-recommendation-calculator — its answer goes in the Budgets tab |
| "Is this spend pace normal?" — variance context for the book | portfolio-pacing-rules |
| A human approved a budget change and wants it executed via sheet | shared-budget-updater — the execution arm; the Guardian never writes |
| "Why did/didn't this alert fire?" — exact thresholds, dedupe, parse rules | references/alert-contract.md |
Files in this skill
| File | Purpose |
SKILL.md | This file |
README.md | Full setup guide with step-by-step deployment |
rules.md | Judgment layer: triage table, false-alarm classes, threshold tuning, kill-switch guidance, roster rules |
examples.md | Worked triage decisions, including the edge cases |
references/alert-contract.md | Exact thresholds, alert shapes, state/dedupe semantics, parse rules, env vars, parity set |
requirements.txt | Python dependencies |
sheet-template.md | Google Sheet tab structure — copy this to build your sheet |
.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
identity-bearing is hardcoded. The full env-var table lives in
references/alert-contract.md; README.md
Step 5 maps each one to a GitHub Actions secret. (The alert thresholds are
constants in the code, not env vars — tuning logic in rules.md.)
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.
Production twin & behavior parity
This bundle is the generic replica of a production automation running on the
same architecture. The two stay in behavioral sync on the
parity set — the exact set, and the by-design divergences (ingestion halves,
env names, branding), are defined in
references/alert-contract.md § Parity with
the production twin. Drift between the two is reviewed against that set,
never byte-synced.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

