meta-ads-connect git:20260522.b2400f5A

Immutable. This exact content is served forever at /api/v1/blob/cb8cb9b163ec0910.

---
name: meta-ads-connect
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'."
---

# 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)

| Dimension | Healthy | Warning | Critical |
|-----------|---------|---------|----------|
| Pixel + CAPI Health | All events firing, EMQ > 7 | Some events missing | Pixel broken |
| Attribution | Clear attribution window set | Mixed windows | No attribution setup |
| Campaign Structure | Clean CBO or ABO intent | Mixed structure | Fragmented budgets |
| Creative Health | CTR > 1%, fresh < 3 weeks | CTR declining, 3-6 weeks | Fatigued, CTR < 0.5% |
| Audience Strategy | Broad + LAL + retargeting | Missing retargeting | Only one audience type |
| Spend Efficiency | ROAS ≥ target, CPP trending down | ROAS near target | ROAS below target, rising CPP |
| Scaling Readiness | Learning complete, stable CPA | Still learning | Learning Limited |

### Creative Fatigue Diagnosis

Flag creative fatigue when:
- **Frequency > 3.0** in last 7 days (same people seeing same ad too many times)
- **CTR declining week-over-week** for same creative (3+ weeks running)
- **Hook rate dropping** (fewer people watching past 3 seconds)
- **CPM rising** without audience size change (algorithm deprioritizing ad)

Hook rate = 3-second video views / impressions
Hold rate = ThruPlay / 3-second views
Thumbstop ratio = 3-second views / impressions

Healthy benchmarks:
| Metric | Target |
|--------|--------|
| CTR (link) | > 1.0% |
| Hook rate | > 25% |
| Hold rate | > 40% |
| Frequency (7d) | < 3.0 |
| CPM | Depends on niche, track trend |

### Learning Phase Triage

- **Learning**: Normal — ad set has <50 optimization events. Don't touch it.
- **Learning Limited**: Problem — can't get enough events to optimize. Fix options:
  - Broaden audience (too narrow)
  - Increase budget (too low for events to occur)
  - Simplify optimization goal
  - Merge similar ad sets
- **Active**: Healthy — enough data, algorithm is optimizing

### Audience Overlap Detection

If two ad sets share >20% audience overlap:
- They compete against each other in the auction
- You're bidding against yourself = higher CPMs
- Fix: Exclude audiences between ad sets, or consolidate into one ad set

---

## Output Format

### Account Scorecard
```
Account: [Name] | Ad Account: act_XXXXXXXXXX
Period: Last 30 days | Spend: $X,XXX | Purchases: XX | ROAS: X.Xx | CPP: $XX

Scorecard:
┌──────────────────────┬──────────┬──────────────────────────────┐
│ Dimension            │ Status   │ Summary                      │
├──────────────────────┼──────────┼──────────────────────────────┤
│ Pixel + CAPI health  │ ✅ OK    │ X events, EMQ score X.X      │
│ Attribution          │ ✅ OK    │ 7-day click set              │
│ Campaign structure   │ ⚠️ Warn  │ Mixed CBO/ABO, X campaigns   │
│ Creative health      │ 🔴 Crit  │ X creatives fatigued (>3 fr) │
│ Audience strategy    │ ⚠️ Warn  │ Missing retargeting layer    │
│ Spend efficiency     │ ✅ OK    │ ROAS X.Xx vs X.Xx target     │
│ Scaling readiness    │ ⚠️ Warn  │ X ad sets in Learning Ltd    │
└──────────────────────┴──────────┴──────────────────────────────┘
```

### Top 3 Actions

Always output these:

1. **Pause fatigued creatives** — [list ad names], frequency X.X, CTR dropped XX% in 3 weeks
   - Impact: Reduce CPM, improve relevance score
   - Next: Brief X new creative variations (use ad-creative skill)

2. **Fix Learning Limited** — [ad set name] has been Learning Limited for X days
   - Cause: Audience too narrow (XX,XXX people) / Budget too low ($XX/day for X conversion goal)
   - Fix: [specific audience expansion OR budget increase]

3. **Add retargeting campaign** — No retargeting detected. Website visitors not being recaptured.
   - Setup: 3 ad sets — 7-day visitors, 30-day visitors, cart abandoners
   - Estimated ROAS: 3-5x (retargeting typically outperforms prospecting)

---

## Execution (Optional)

Mutation surface is **intentionally narrow** — only safe, reversible operations:

```bash
python skills/meta-ads-connect/scripts/mutate.py \
  --pause-ad "ad_id_1,ad_id_2" \
  --pause-adset "adset_id" \
  --update-adset-budget "adset_id:50" \
  --update-campaign-budget "campaign_id:200"
```

**NOT automated** (routes to Meta Ads Manager instead):
- Creating new campaigns, ad sets, or ads
- Editing audiences or targeting
- Uploading creative assets
- Changing optimization goals

Always confirm before executing:
> "I'm about to pause 2 fatigued ads and increase the budget on 1 Learning Limited ad set. Confirm?"

All changes logged to `.agents/meta-ads-changes.json`.

---

## Integration with Other Skills

- **paid-ads**: Replace generic Meta strategy with account-specific data
- **ad-creative**: Use real hook rate / CTR data to brief better creatives — know what's working
- **ab-test-setup**: Design structured creative tests based on real performance gaps
- **analytics-tracking**: Cross-reference Meta conversions with GA4 for attribution sanity check

---

## References

- [Setup Guide](references/setup-guide.md): Facebook Developer App setup and token generation
- [Meta API Reference](references/api-reference.md): Key endpoints, fields, and breakdowns used
- [Creative Benchmarks](references/creative-benchmarks.md): Industry benchmarks for CTR, hook rate, ROAS by vertical

---

## Related Skills

- **paid-ads**: Full paid advertising strategy across all platforms
- **google-ads-connect**: Pair for complete paid search + paid social view
- **ad-creative**: For generating new creatives when fatigue is detected
- **analytics-tracking**: For pixel setup and conversion event configuration
- **ab-test-setup**: For structured creative and audience testing