Skip to content
Back to search

google-ads-doctor

MarketplaceWorks with Claude CodeGitHub

Finds where Google Ads money leaks and fixes it in order: conversions, search terms, negatives, structure.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mavrin-xv--google-ads-doctor/badge.svg)](/listings/mavrin-xv--google-ads-doctor)

HTML

<a href="/listings/mavrin-xv--google-ads-doctor"><img src="/api/listings/mavrin-xv--google-ads-doctor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

E=examples/northwind-plumbing
python3 skills/conversion-cleanup/scripts/conversions_audit.py $E/conversion-actions.csv --owner-leads 34
python3 skills/search-terms-audit/scripts/ngrams.py $E/search-terms.csv --target-cpa 60 --csv candidates.csv
python3 skills/negative-keywords/scripts/negatives_check.py candidates.csv --terms $E/search-terms.csv --keywords $E/keywords.csv
python3 skills/structure-audit/scripts/structure_audit.py --campaigns $E/campaigns-month.csv --keywords $E/keywords.csv --target-cpa 60
python3 skills/weekly-ads-check/scripts/weekly_check.py $E/campaigns-week-curr.csv $E/campaigns-week-prev.csv --target-cpa 60

On your own account, replace the example files with your downloads. The scripts read UI CSV and TSV files (including UTF-16, title rows and totals) and the API CSVs from `gaql_pull.py`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines
  1. {
  2. "name": "google-ads-doctor",
  3. "plugins": [
  4. {
  5. "name": "google-ads-doctor",
  6. "source": "./",
  7. "description": "Finds and fixes where Google Ads money leaks: search term n-gram mining, negative keyword checks that catch negatives blocking buyers, conversion action cleanup, a ten-check structure audit and a weekly check with a decisions log. Works on CSV exports, with an optional read-only API pull.",
  8. "version": "0.1.0"
  9. }
  10. ],
  11. "owner": {
  12. "name": "Artem Mavrin",
  13. "url": "https://github.com/mavrin-xv"
  14. }
  15. }
README.md · README · 121 lines
  1. ![google-ads-doctor](assets/banner.png)
  2. # google-ads-doctor
  3. **Find where Google Ads money leaks and fix it in the right order: conversion tracking, search terms, negatives, structure, then a weekly check that keeps it fixed.**
  4. The account says 90 conversions and the business got 30 leads, a third of the spend goes to "jobs" and "how to" searches, and one negative added last spring quietly blocks your best keyword.
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  6. ![Works with](https://img.shields.io/badge/works%20with-Claude%20Code%20%7C%20Codex%20%7C%20any%20SKILL.md%20agent-black)
  7. ![Python](https://img.shields.io/badge/scripts-Python%203.8%2B%20stdlib-green)
  8. ![Example output](assets/example.png)
  9. ```bash
  10. git clone https://github.com/mavrin-xv/google-ads-doctor && cd google-ads-doctor
  11. ./install.sh # or: ./install.sh --project
  12. ```
  13. <!-- install-notes:start -->
  14. Other ways in: as a Claude Code plugin, run `/plugin marketplace add mavrin-xv/google-ads-doctor` and then `/plugin install google-ads-doctor@google-ads-doctor`. For Codex or another agent that reads `SKILL.md`, copy the folders under `skills/` into its skills directory. On Windows, run `install.sh` from Git Bash or WSL and type `py -3` where these docs say `python3`.
  15. <!-- install-notes:end -->
  16. Then download your reports and say "audit my Google Ads".
  17. ---
  18. ## What it solves
  19. | Pain | Fix in this repo |
  20. |---|---|
  21. | Ads reports far more conversions than the business has leads | `conversions_audit.py` finds duplicates (Ads tag plus GA4 import), careers forms set primary, leads counted Every, directions clicks counted as leads |
  22. | Waste is spread over thousands of cheap search terms | `ngrams.py` groups terms by the words they share and ranks the patterns that never convert |
  23. | A negative keyword blocks buyers and nobody notices | `negatives_check.py` tests every negative against converting terms and your own keywords before upload |
  24. | "Should we raise the budget?" | Structure check S06 separates budget-limited from rank-limited campaigns |
  25. | Broad match burning money on manual bidding | S02 flags broad keywords in campaigns without conversion-based bidding |
  26. | Conversions drop to 0 and bids get changed first | The weekly check raises TRACKING before CPA, so the tag gets tested first |
  27. | Nobody remembers why a change was made | Every weekly run appends a dated entry with Decision, Why and Check again on |
  28. ## What's inside
  29. | Skill | What it does | Say |
  30. |---|---|---|
  31. | `ads-data-pull` | Gets the reports: UI download steps, or a read-only API pull with GAQL | "export my Google Ads data", "pull search terms from the API" |
  32. | `conversion-cleanup` | Ten checks on conversion actions so bidding optimises for real leads | "conversions look too high", "which conversions should be primary" |
  33. | `search-terms-audit` | N-gram waste mining with verdicts, intent classes and a candidates file | "where is my ad money going", "mine my search terms" |
  34. | `negative-keywords` | Simulates negative matching, flags harmful negatives, writes an upload file | "check these negatives", "did a negative block my leads" |
  35. | `structure-audit` | Ten structure checks with pass, fail, warn or unknown and evidence coverage | "audit my account", "should I raise the budget" |
  36. | `weekly-ads-check` | Week over week flags in action order plus a decisions log | "weekly ads check", "what changed this week" |
  37. Also: `examples/northwind-plumbing/` (an invented account with planted problems), `templates/` (decisions log, lead paths map), `docs/how-it-works.md`.
  38. ## Quick start
  39. ```bash
  40. E=examples/northwind-plumbing
  41. python3 skills/conversion-cleanup/scripts/conversions_audit.py $E/conversion-actions.csv --owner-leads 34
  42. python3 skills/search-terms-audit/scripts/ngrams.py $E/search-terms.csv --target-cpa 60 --csv candidates.csv
  43. python3 skills/negative-keywords/scripts/negatives_check.py candidates.csv --terms $E/search-terms.csv --keywords $E/keywords.csv
  44. python3 skills/structure-audit/scripts/structure_audit.py --campaigns $E/campaigns-month.csv --keywords $E/keywords.csv --target-cpa 60
  45. python3 skills/weekly-ads-check/scripts/weekly_check.py $E/campaigns-week-curr.csv $E/campaigns-week-prev.csv --target-cpa 60
  46. ```
  47. On your own account, replace the example files with your downloads. The scripts read UI CSV and TSV files (including UTF-16, title rows and totals) and the API CSVs from `gaql_pull.py`.
  48. ## How it works
  49. ```text
  50. reports (UI CSV or gaql_pull.py) ─► adsreport.py: maps column names, parses numbers
  51. │
  52. 1 conversion-cleanup ─► is the conversion count true? (every CPA below depends on it)
  53. 2 search-terms-audit ─► which word patterns cost money and never convert
  54. 3 negative-keywords ─► which negatives are safe; HARMFUL ones never reach the upload file
  55. 4 structure-audit ─► where setup loses money: bidding, kill rule, budget vs rank
  56. 5 weekly-ads-check ─► flags every week ─► decisions.md
  57. ```
  58. Order matters. Search term and structure verdicts use CPA, and CPA is only as true as the conversion count, so tracking comes first. Every script proposes; the account owner approves and makes each change. Nothing here writes to Google Ads.
  59. ## Configure
  60. | Setting | Where | Default |
  61. |---|---|---|
  62. | Target CPA | `--target-cpa` on every audit | account CPA when not given (weaker, the report says so) |
  63. | Brand and competitor words | `ngrams.py --brand --competitors` | none |
  64. | Kill line | `ngrams.py --kill-multiple`, S03 in `structure_audit.py` | 3x target CPA |
  65. | Report period | `--days` | 30 (audits), 7 (weekly) |
  66. | API credentials | environment variables, see `skills/ads-data-pull/references/api-setup.md` | none; the API path is optional |
  67. | API version | `GOOGLE_ADS_API_VERSION` | v26 |
  68. ## Honest limits
  69. - Search terms that Google hides for privacy are not in the report, so the audit covers the visible part of spend only.
  70. - Performance Max is mostly out of scope: no keywords, search term insights come as categories.
  71. - Negative matching is simulated from Google's documented rules. It cannot see searches that have not happened yet.
  72. - Thresholds (3x CPA kill line, 15% lost budget share, about 15 to 30 conversions a month before smart bidding) are practitioner rules, not Google limits.
  73. - The Editor upload file's column names differ between Editor versions; map them on import.
  74. - Tested: every script on the invented example data, UTF-16 and API-shaped CSVs, and `gaql_pull.py` against a local mock of the search endpoint. Not tested by us: a real Google Ads API call, a real Editor import, accounts in UI languages other than English.
  75. - Tested with Claude Code. Other agents that read SKILL.md files should work; not tested.
  76. ## Credits
  77. - https://github.com/boringmarketer/boring-marketing-skills (MIT, Copyright (c) 2026 Boring Marketing, LLC): adapted the judge-after-2x-CPA rule, the 3-day minimum, slow scaling steps, one-campaign-on-small-budgets and the biddable-goal trap in the API. Rewritten, no text copied.
  78. - https://github.com/AgriciDaniel/claude-ads: the idea of checks with pass, fail and unknown states plus an evidence coverage score.
  79. - https://github.com/themattberman/google-ads-copilot: n-gram based search term mining as the first waste lens.
  80. - https://github.com/googleads/google-ads-mcp and https://github.com/cohnen/mcp-google-ads: read-only GAQL access patterns.
  81. - Google Ads Help, "About negative keywords" and the conversion action and impression share articles, for matching rules and column meanings.
  82. ## Contributing
  83. See `CONTRIBUTING.md`. Coding agents should read `AGENTS.md` first.
  84. <!-- author:start -->
  85. ## Author
  86. Built and maintained by [Artem Mavrin](https://github.com/mavrin-xv). This repo is one of a set of agent skill packs for marketing and operations work. Each one installs on its own; the full list is in [agent-skill-packs](https://github.com/mavrin-xv/agent-skill-packs). If a pack saved you an afternoon, a star helps other people find it.
  87. <!-- author:end -->
  88. ## License
  89. MIT, see `LICENSE`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.