claude-ads

<p align="center">
  <img src="assets/banner.svg" alt="Claude Ads: Paid Advertising Audit Skill for Claude Code. Animated terminal-style banner with breathing gradient logo, scanning command palette, and pulsing status indicators" width="100%">
</p>

# Claude Ads: Paid Advertising Audit Skill for Claude Code

A manual audit of a single Google Ads account takes 4-6 hours of senior PPC time. **Claude Ads runs the same audit in 10-15 minutes**, scores it on a 0-100 weighted scale, and outputs a prioritized action plan across Google, Meta, YouTube, LinkedIn, TikTok, Microsoft, Apple, and Amazon Ads. Built for **PPC agencies, in-house marketers, and freelance ad consultants**. Local, deterministic, MIT-licensed.

[![Agent Skill](https://img.shields.io/badge/Agent%20Skills-Compatible-blue)](https://agentskills.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Version](https://img.shields.io/github/v/release/AgriciDaniel/claude-ads?label=public%20release)](https://github.com/AgriciDaniel/claude-ads/releases)
[![CI](https://img.shields.io/github/actions/workflow/status/AgriciDaniel/claude-ads/ci.yml?branch=main&label=public%20CI)](https://github.com/AgriciDaniel/claude-ads/actions)
[![Community](https://img.shields.io/badge/AI%20Marketing%20Hub-Pro%20community-purple)](https://www.skool.com/ai-marketing-hub-pro)
[![GitHub org](https://img.shields.io/badge/AI%20Marketing%20Hub-GitHub-181717?logo=github&logoColor=white)](https://github.com/AI-Marketing-Hub)

**Host support:**
[![Claude Code](https://img.shields.io/badge/Claude%20Code-Verified-brightgreen)](https://claude.ai/claude-code)
[![Codex CLI](https://img.shields.io/badge/Codex%20CLI-Experimental-yellow)](https://github.com/openai/codex)
[![Cursor](https://img.shields.io/badge/Cursor-Experimental-yellow)](https://cursor.sh)
[![Windsurf](https://img.shields.io/badge/Windsurf-Experimental-yellow)](https://codeium.com/windsurf)
[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Experimental-yellow)](https://github.com/google-gemini/gemini-cli)
[![Goose](https://img.shields.io/badge/Goose-Experimental-yellow)](https://block.github.io/goose/)

> **Last updated:** 2026-05-18 · **Version:** v1.7.1 · [CHANGELOG](CHANGELOG.md) · [Blog: full ad audit breakdown](https://agricidaniel.com/blog/claude-code-ad-agency)

> **Two versions of this skill.**
> - 🌐 **Public open-source** → [`AgriciDaniel/claude-ads`](https://github.com/AgriciDaniel/claude-ads): MIT, public releases, no membership. Best if you want stable + downloadable.
> - 🔒 **Community private mirror** → [`AI-Marketing-Hub/claude-ads`](https://github.com/AI-Marketing-Hub/claude-ads): early access to upcoming features and direct collaboration with the [AI Marketing Hub Pro](https://www.skool.com/ai-marketing-hub-pro) community. Requires membership.

## Who this is for

- **PPC agencies running 5+ accounts**: audit every account weekly instead of once a quarter. Same time budget.
- **In-house marketers owning paid across 4+ platforms**: second-pair-of-eyes before exec reviews. No human bias on which platform you favor.
- **Freelance PPC consultants**: anchor day-1 client scope with a 10-minute audit. Win the engagement before you spend an hour on diagnostic.

## What's new in v1.7.0 (Wave 2)

- **3 new sub-skills**: `/ads amazon` (Sponsored Products/Brands/Display, ACOS/TACOS), `/ads attribution` (AdAttributionKit + GA4 + Consent Mode V2), `/ads tracking` (sGTM + CAPI Gateway + dedup + hashing).
- **41-test pytest eval harness** in `tests/`: routing snapshots, bidirectional 209-check catalog coverage, scoring math determinism, SSRF regression. Runs in CI on every commit.
- **Cross-runtime install matrix**: `install.sh` / `install.ps1 --target=<host>` with whitelist validation for Claude Code, Codex CLI, Cursor, Windsurf, Gemini CLI, Goose.
- **Deep platform rewrites**: `/ads google` for the AI Max era (`ai_max_setting.enable_ai_max`, AI Brief, FUE, brand exclusions). `/ads meta` for the Andromeda + GEM + Lattice era with Entity-ID clustering detection.
- **10-Principle Thinking Framework**: every audit, plan, and creative output runs under a shared cognitive discipline. See [`ads/references/thinking-framework.md`](ads/references/thinking-framework.md).

Full release notes: [CHANGELOG.md](CHANGELOG.md).

## Demo

<p align="center">
  <img src="assets/demo.gif" alt="Claude Ads in action: /ads audit dispatching 6 parallel subagents, returning Ads Health Score with platform breakdown and prioritized action plan" width="100%">
</p>

### Sample output

What `/ads audit` actually returns (truncated for brevity):

```json
{
  "ads_health_score": 73,
  "grade": "C",
  "audit_date": "2026-05-18",
  "platforms": {
    "google_ads": { "score": 78, "grade": "B", "checks_run": 80, "critical": 2, "high": 5 },
    "meta_ads":   { "score": 64, "grade": "C", "checks_run": 50, "critical": 4, "high": 7 },
    "linkedin":   { "score": 81, "grade": "B", "checks_run": 27, "critical": 0, "high": 3 }
  },
  "top_findings": [
    {
      "id": "M-AND-01",
      "severity": "critical",
      "platform": "meta",
      "title": "Andromeda creative similarity > 60%: retrieval suppression risk",
      "impact": "Estimated 20-35% reach loss; 4 ad sets affected",
      "action": "Replace 7 near-duplicate creatives with concept-diverse variants",
      "owner": "creative",
      "eta_days": 7
    },
    {
      "id": "G-AIM-03",
      "severity": "high",
      "platform": "google",
      "title": "AI Max enabled without negative keyword discipline",
      "impact": "Wasted spend ~$1,400/mo on irrelevant queries",
      "action": "Build negative list from 30d search term report",
      "owner": "search",
      "eta_days": 2
    }
  ],
  "quick_wins": [
    "Enable Consent Mode V2 (Privacy Sandbox compatible, ~1 hr)",
    "Pause 3 ad groups failing 3x Kill Rule (saves ~$420/mo)"
  ]
}
```

Plus a PDF version (`/ads report`) with health score gauge, platform comparison charts, and zero-overlap layout for client delivery.

## Contents

- [Installation: 3 ways to add Claude Ads](#installation-3-ways-to-add-claude-ads)
- [Quick Start](#quick-start)
- [Commands](#commands)
- [Features: what 250+ audit checks cover](#features-what-250-audit-checks-cover)
- [Compared to manual / agency / commercial tools](#compared-to-manual--agency--commercial-tools)
- [Use cases](#use-cases)
- [Eval harness: verified rigor](#eval-harness-verified-rigor)
- [Architecture](#architecture)
- [How it analyzes your ads](#how-it-analyzes-your-ads)
- [FAQ](#faq)
- [Requirements](#requirements)
- [Uninstall](#uninstall)
- [Roadmap](#roadmap)
- [Project info](#project-info)
- [Related projects](#related-projects)
- [Maintainer](#maintainer)
- [License](#license)

## Installation: 3 ways to add Claude Ads

> ℹ️ **Two install paths — pick the one that matches your access.**
>
> The commands below default to the **community private mirror** at `AI-Marketing-Hub/claude-ads` (early access for Pro members). To use the **public release** at `AgriciDaniel/claude-ads` (MIT, no membership), swap `AI-Marketing-Hub/claude-ads` for `AgriciDaniel/claude-ads` and the plugin slug `claude-ads@ai-marketing-hub-claude-ads` for `claude-ads@agricidaniel-claude-ads` in every command.
>
> Pro members: requires `gh auth login` (or PAT) with access to the `AI-Marketing-Hub` org. If `/plugin marketplace add` 404s, DM in the [Skool community](https://www.skool.com/ai-marketing-hub-pro) to get added.

### 1. Plugin install (Claude Code, recommended)

```shell
/plugin marketplace add AI-Marketing-Hub/claude-ads
/plugin install claude-ads@ai-marketing-hub-claude-ads
```

Registers claude-ads as a native plugin with auto-updates, namespace isolation, and version tracking.

### 2. One-command install (Unix/macOS/Linux)

```bash
curl -fsSL https://raw.githubusercontent.com/AI-Marketing-Hub/claude-ads/main/install.sh | bash
```

### 2. One-command install (Windows PowerShell)

```powershell
irm https://raw.githubusercontent.com/AI-Marketing-Hub/claude-ads/main/install.ps1 | iex
```

### 3. Cross-host install (Codex CLI / Cursor / Windsurf / Gemini CLI / Goose)

```bash
# Unix/macOS/Linux
bash install.sh --target=codex      # OpenAI Codex CLI       (experimental)
bash install.sh --target=cursor     # Cursor IDE              (experimental)
bash install.sh --target=windsurf   # Windsurf IDE            (experimental)
bash install.sh --target=gemini     # Gemini CLI              (experimental)
bash install.sh --target=goose      # Goose CLI               (experimental)
```

```powershell
# Windows PowerShell
.\install.ps1 -Target codex
.\install.ps1 -Target cursor
.\install.ps1 -Target windsurf
.\install.ps1 -Target gemini
.\install.ps1 -Target goose
```

**Per-host install path table:**

| Target     | Skills root                                     | Agents root                                | Python deps |
|------------|-------------------------------------------------|--------------------------------------------|-------------|
| `claude`   | `~/.claude/skills`                              | `~/.claude/agents`                         | ✓           |
| `codex`    | `~/.codex/skills`                               | `~/.codex/agents`                          | ✓           |
| `cursor`   | `~/.cursor/extensions/claude-ads/skills`        | `~/.cursor/extensions/claude-ads/agents`   | skipped     |
| `windsurf` | `~/.windsurf/skills`                            | `~/.windsurf/agents`                       | skipped     |
| `gemini`   | `~/.gemini/extensions/claude-ads/skills`        | `~/.gemini/extensions/claude-ads/agents`   | skipped     |
| `goose`    | `~/.config/goose/skills`                        | `~/.config/goose/agents`                   | skipped     |

**Path overrides:**

```bash
bash install.sh --target=claude --skill-dir=~/custom/skills --agent-dir=~/custom/agents
```

Targets and override paths are strictly whitelist-validated: no shell injection, no flag confusion