/meta-ads

name: meta-ads
description: Run Meta ads end to end like a PPC specialist: install and verify the pixel on a funnel, launch Sales campaigns, read the data, find where the funnel leaks, fix campaigns live, build stage-by-stage remarketing, and monitor daily. Pull, analyze, manage, and CREATE Meta ads (Facebook, Instagram, Messenger, Threads, Click-to-WhatsApp) via the Marketing API. Use when the user mentions Meta/FB/IG ads, Ads Manager, ROAS, CPA, CPM, CTR, ad spend, campaign or ad set performance, creative fatigue, frequency, CTWA, audience/placement breakdowns, A/B ad tests, or wants to pause an ad, change a budget, duplicate a winner, or launch a new campaign from scratch, install or debug a Meta pixel (פיקסל), set up remarketing (רימרקטינג, קהלים מותאמים, מי שביקר ולא קנה), or wants ongoing monitoring of a live campaign. Also covers reconciling ads with real sales from the checkout/course platform (Schooler MCP, סקולר, רב מסר) and turning past buyers, sign-ups that didn't pay and non-starters into cross-sell and recovery campaigns. Runs in Claude and in Grok Bot (גרוק בוט): install into a bot, run the daily check as a routine, alert on Telegram/WhatsApp. Trigger on Hebrew terms like פרסום בפייסבוק/באינסטגרם, פרסומות מטא, ביצועי קמפיין, פרסומות, צור קמפיין, השק קמפיין, A/B טסט. Trigger on questions like how are my ads doing, which creative is winning, is my ad fatigued, what's my CPA, drop a 30-day report, launch an A/B test for my course, build a campaign with these 3 angles. Trigger even if auth isn't set up - the skill walks through one-time setup. Do NOT use for organic Instagram analytics, Reels view counts on non-promoted posts, or organic Threads engagement; those need the Instagram Graph API.

Meta Ads (Marketing API)

Pull ad performance data from Meta (Facebook, Instagram, Messenger, Click-to-WhatsApp, Threads), run analyses, and, with explicit confirmation, write changes back (pause, budget change, duplicate, full campaign creation with images, copy or existing Instagram posts).

Beyond reporting, this skill is meant to act as the user's **PPC operator**: get the pixel right on every page of the funnel, launch a Sales campaign that can actually learn, read the numbers stage by stage, change things rarely and for a reason, and keep watching. The operator loop below is the main workflow for anyone who sells something online.

When to consult this skill

Any question about Meta ad performance, creative health, audience/placement mix, or campaign management. If the user asks "how are my ads doing" without specifying a platform, ask whether they mean Meta or Google before defaulting.

Three things to internalize before touching any script

**1. Where the scripts run matters.** The scripts call `graph.facebook.com` over the open internet. Some execution environments (including Claude's Linux sandbox in certain configurations) block this endpoint via proxy. If you hit a `ProxyError` / `Tunnel connection failed: 403` on the first call, run the scripts from the **user's host machine** - macOS, Windows, or Linux - using that machine's Python. Per-OS commands:

• **macOS:** `python3 scripts/auth_check.py`, deps via `python3 -m pip install --user requests`
• **Windows:** `python scripts/auth_check.py` (or `py scripts/auth_check.py` if `python` isn't on PATH), deps via `python -m pip install --user requests`
• **Linux:** `python3 scripts/auth_check.py`, deps via `python3 -m pip install --user requests` (add `--break-system-packages` on Debian/Ubuntu 22+)

The scripts themselves are pure Python with one dependency (`requests`) and no shell/OS assumptions, so they run identically everywhere once dependencies are installed.

**2. WhatsApp is not a separate ad surface.** Click-to-WhatsApp ads run on Facebook and Instagram placements. They show up in the Marketing API as regular ads with `destination_type=WHATSAPP` and conversion events under `actions` (look for `onsite_conversion.messaging_conversation_started_7d` and similar). Don't promise the user a "WhatsApp ads dashboard" - there isn't one.

**3. Read is safe, write is not.** Insights endpoints (GET) are idempotent and harmless. Pause / budget / duplicate (POST) actions touch real money. The write rules in `references/write-actions.md` are non-negotiable - read that file before any write call.

The operator loop (the main workflow for selling)

When the user wants sales, not just a report, run these phases in order. Each has its reference file; read it when you reach that phase. **The system that ties them together is `references/full-funnel-system.md`**: signal inventory, the intent ladder (who is at which stage and what stops them), audiences per rung with exclusions, campaign architecture (prospecting / re-engage / close), creative per rung, the testing order and the keep/kill/scale/shift rules. Read it before designing audiences or campaigns, and again whenever you analyse results.

1. **Map the funnel and settle the account** (`references/pixel-setup.md` steps 0-1). Where does each step happen (landing page, checkout platform, payment)? Which ad account pays, does it have a payment method, is it in a Business? Decide ONE ad account and ONE pixel before anything else; switching later costs a re-install everywhere and resets learning. 2. **Install the pixel and verify it in three layers** (`references/pixel-setup.md`): installed on every page (`check_pixel.py`), calls made, events received in Test events, then a real ~99%-coupon purchase. Find out what events the checkout platform already sends by reading its JS, and give every funnel step a unique standard event. 3. **Write down the economics** (`references/ppc-operator-playbook.md`): price, break-even CPA, target CPA. Every later recommendation is phrased against them. 4. **Launch** with `create_campaign.py` (`references/campaign-creation.md`): Sales objective, optimization event chosen by volume, Facebook + Instagram placements (`"placements": "fb_ig_all"`), CBO