meta-ads-connect
starsforks
How to install meta-ads-connect?
leoyeai/openclaw-marketing-skills/meta-ads-connect
$npx -y skills add LeoYeAI/openclaw-marketing-skills --skill meta-ads-connectConnect 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 cre
SKILL.md
| 1 | # Meta Ads Connect |
| 2 | |
| 3 | 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. |
| 4 | |
| 5 | ## Setup (First Time) |
| 6 | |
| 7 | Check for `.agents/meta-ads-credentials.json`. If missing: |
| 8 | |
| 9 | ### Step 1: Get a Meta Access Token |
| 10 | |
| 11 | 1. Go to [Meta for Developers](https://developers.facebook.com) |
| 12 | 2. Create an App → Business type |
| 13 | 3. Add **Marketing API** product |
| 14 | 4. Generate a **System User Token** with these permissions: |
| 15 | - `ads_read` |
| 16 | - `ads_management` (only if user wants to apply changes) |
| 17 | - `business_management` |
| 18 | 5. Get your **Ad Account ID** from Meta Ads Manager (format: `act_XXXXXXXXXX`) |
| 19 | |
| 20 | ### Step 2: Save credentials |
| 21 | |
| 22 | Save to `.agents/meta-ads-credentials.json`: |
| 23 | ```json |
| 24 | { |
| 25 | "access_token": "EAAxxxxxxxxxx...", |
| 26 | "ad_account_id": "act_XXXXXXXXXX", |
| 27 | "app_id": "...", |
| 28 | "app_secret": "..." |
| 29 | } |
| 30 | ``` |
| 31 | |
| 32 | ### Token Refresh |
| 33 | |
| 34 | Meta tokens expire. For long-term use: |
| 35 | ```bash |
| 36 | python skills/meta-ads-connect/scripts/refresh_token.py |
| 37 | ``` |
| 38 | |
| 39 | --- |
| 40 | |
| 41 | ## Data Pull |
| 42 | |
| 43 | ```bash |
| 44 | python skills/meta-ads-connect/scripts/audit.py \ |
| 45 | --account act_XXXXXXXXXX \ |
| 46 | --days 30 \ |
| 47 | --output .agents/meta-ads-data.json |
| 48 | ``` |
| 49 | |
| 50 | Fetches (last 30 days default): |
| 51 | - **Campaign performance**: spend, reach, impressions, clicks, purchases, ROAS, CPM, CPC, CPP |
| 52 | - **Ad set breakdown**: performance by audience, placement, optimization goal |
| 53 | - **Ad/creative performance**: CTR, hook rate, hold rate, thumbstop ratio per creative |
| 54 | - **Frequency**: avg times each person saw each ad (fatigue indicator) |
| 55 | - **Learning Phase status**: which ad sets are in Learning / Learning Limited |
| 56 | - **Audience overlap**: ad sets targeting same users (budget competition) |
| 57 | - **Pixel health**: events firing correctly, match quality score |
| 58 | |
| 59 | --- |
| 60 | |
| 61 | ## Analysis Framework |
| 62 | |
| 63 | ### 7-Dimension Health Check (Meta-Tuned) |
| 64 | |
| 65 | | Dimension | Healthy | Warning | Critical | |
| 66 | |-----------|---------|---------|----------| |
| 67 | | Pixel + CAPI Health | All events firing, EMQ > 7 | Some events missing | Pixel broken | |
| 68 | | Attribution | Clear attribution window set | Mixed windows | No attribution setup | |
| 69 | | Campaign Structure | Clean CBO or ABO intent | Mixed structure | Fragmented budgets | |
| 70 | | Creative Health | CTR > 1%, fresh < 3 weeks | CTR declining, 3-6 weeks | Fatigued, CTR < 0.5% | |
| 71 | | Audience Strategy | Broad + LAL + retargeting | Missing retargeting | Only one audience type | |
| 72 | | Spend Efficiency | ROAS ≥ target, CPP trending down | ROAS near target | ROAS below target, rising CPP | |
| 73 | | Scaling Readiness | Learning complete, stable CPA | Still learning | Learning Limited | |
| 74 | |
| 75 | ### Creative Fatigue Diagnosis |
| 76 | |
| 77 | Flag creative fatigue when: |
| 78 | - **Frequency > 3.0** in last 7 days (same people seeing same ad too many times) |
| 79 | - **CTR declining week-over-week** for same creative (3+ weeks running) |
| 80 | - **Hook rate dropping** (fewer people watching past 3 seconds) |
| 81 | - **CPM rising** without audience size change (algorithm deprioritizing ad) |
| 82 | |
| 83 | Hook rate = 3-second video views / impressions |
| 84 | Hold rate = ThruPlay / 3-second views |
| 85 | Thumbstop ratio = 3-second views / impressions |
| 86 | |
| 87 | Healthy benchmarks: |
| 88 | | Metric | Target | |
| 89 | |--------|--------| |
| 90 | | CTR (link) | > 1.0% | |
| 91 | | Hook rate | > 25% | |
| 92 | | Hold rate | > 40% | |
| 93 | | Frequency (7d) | < 3.0 | |
| 94 | | CPM | Depends on niche, track trend | |
| 95 | |
| 96 | ### Learning Phase Triage |
| 97 | |
| 98 | - **Learning**: Normal — ad set has <50 optimization events. Don't touch it. |
| 99 | - **Learning Limited**: Problem — can't get enough events to optimize. Fix options: |
| 100 | - Broaden audience (too narrow) |
| 101 | - Increase budget (too low for events to occur) |
| 102 | - Simplify optimization goal |
| 103 | - Merge similar ad sets |
| 104 | - **Active**: Healthy — enough data, algorithm is optimizing |
| 105 | |
| 106 | ### Audience Overlap Detection |
| 107 | |
| 108 | If two ad sets share >20% audience overlap: |
| 109 | - They compete against each other in the auction |
| 110 | - You're bidding against yourself = higher CPMs |
| 111 | - Fix: Exclude audiences between ad sets, or consolidate into one ad set |
| 112 | |
| 113 | --- |
| 114 | |
| 115 | ## Output Format |
| 116 | |
| 117 | ### Account Scorecard |
| 118 | ``` |
| 119 | Account: [Name] | Ad Account: act_XXXXXXXXXX |
| 120 | Period: Last 30 days | Spend: $X,XXX | Purchases: XX | ROAS: X.Xx | CPP: $XX |
| 121 | |
| 122 | Scorecard: |
| 123 | ┌──────────────────────┬──────────┬──────────────────────────────┐ |
| 124 | │ Dimension │ Status │ Summary │ |
| 125 | ├──────────────────────┼──────────┼──────────────────────────────┤ |
| 126 | │ Pixel + CAPI healt |
People who liked this also viewed
6 picksType
- seo-auditWhen the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tagSkillsJul 2026
- copywritingWhen the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user sSkillsJul 2026
- marketing-psychologyWhen the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when the user mentions 'psychology,' 'mental models,' 'cognitive bias,' 'persuasion,'SkillsJul 2026
- content-strategyWhen the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also use when the user mentions "content strategy," "what should I write about," "conSkillsJul 2026
- programmatic-seoWhen the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions "programmatic SEO," "template pages," "pages at scale," "directory pages," "location pSkillsJul 2026
- marketing-ideasWhen the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing stratSkillsJul 2026
