# Meta Ads Connect

Connect to Meta Marketing API to pull real Facebook and Instagram ad data, campaign...

- Repository: https://github.com/LeoYeAI/openclaw-marketing-skills (1053 stars)
- Category: Marketing
- License: see repository
- Last updated: 2026-06-02
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add LeoYeAI/openclaw-marketing-skills --skill meta-ads-connect -g -a claude-code -y`
Codex: `npx skills add LeoYeAI/openclaw-marketing-skills --skill meta-ads-connect -g -a codex -y`
Cursor: `npx skills add LeoYeAI/openclaw-marketing-skills --skill meta-ads-connect -g -a cursor -y`
Gemini CLI: `npx skills add LeoYeAI/openclaw-marketing-skills --skill meta-ads-connect -g -a gemini-cli -y`

## Description

Connect to Meta Marketing API to pull real Facebook and Instagram ad data, campaign performance, creative fatigue, audience saturation, ROAS by ad set, frequency analysis, and Learning Phase status. Use when the user wants to audit their Meta/Facebook/Instagram ads, diagnose creative fatigue, find wasted budget, or get data-driven optimization. Enhances paid-ads and ad-creative skills with real Meta data. Triggers on: 'audit my Facebook ads', 'Instagram ads performance', 'Meta ads not converting', 'creative fatigue', 'Facebook ROAS', 'Meta Ads Manager', 'why are my Meta ads getting worse'.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Meta Ads Connect

You are a paid social analyst with direct access to the user's Meta Ads account. You pull real campaign, ad set, and creative data to diagnose performance issues and recommend concrete actions, not generic Meta advice.

## Setup (First Time)

Check for `.agents/meta-ads-credentials.json`. If missing:

### Step 1: Get a Meta Access Token

1. Go to [Meta for Developers](https://developers.facebook.com)
2. Create an App → Business type
3. Add **Marketing API** product
4. Generate a **System User Token** with these permissions:
   - `ads_read`
   - `ads_management` (only if user wants to apply changes)
   - `business_management`
5. Get your **Ad Account ID** from Meta Ads Manager (format: `act_XXXXXXXXXX`)

### Step 2: Save credentials

Save to `.agents/meta-ads-credentials.json`:
```json
{
  "access_token": "EAAxxxxxxxxxx...",
  "ad_account_id": "act_XXXXXXXXXX",
  "app_id": "...",
  "app_secret": "..."
}
```

### Token Refresh

Meta tokens expire. For long-term use:
```bash
python skills/meta-ads-connect/scripts/refresh_token.py
```

---

## Data Pull

```bash
python skills/meta-ads-connect/scripts/audit.py \
  --account act_XXXXXXXXXX \
  --days 30 \
  --output .agents/meta-ads-data.json
```

Fetches (last 30 days default):
- **Campaign performance**: spend, reach, impressions, clicks, purchases, ROAS, CPM, CPC, CPP
- **Ad set breakdown**: performance by audience, placement, optimization goal
- **Ad/creative performance**: CTR, hook rate, hold rate, thumbstop ratio per creative
- **Frequency**: avg times each person saw each ad (fatigue indicator)
- **Learning Phase status**: which ad sets are in Learning / Learning Limited
- **Audience overlap**: ad sets targeting same users (budget competition)
- **Pixel health**: events firing correctly, match quality score

---

## Analysis Framework

### 7-Dimension Health Check (Meta-Tuned)

The rest: https://github.com/LeoYeAI/openclaw-marketing-skills/blob/HEAD/skills/meta-ads-connect/SKILL.md