Skill: elias-didoo/meta-ads-analysis (version 1.2.0)

--- name: meta-ads-analysis description: "[Didoo AI] Analyzes Meta Ads campaign performance in depth — metrics, funnel, trends, and anomalies. Use when user wants to understand how a campaign is performing, identify weak points, or get data before receiving recommendations. Outputs structured analysis only; never provides recommendations. Triggers on: \"analyze\", \"deep dive\", \"why is performance\", \"diagnose\", \"full audit\"." homepage: https://didoo.ai/blog metadata: { "openclaw": { "requires": { "env": ["META_ACCESS_TOKEN", "META_AD_ACCOUNT_ID"] }, }, } --- ## Required Credentials | Credential | Where to Get | Used For | OAuth Scope | |-----------|-------------|---------|-------------| | META_ACCESS_TOKEN | Meta Developer Console → Graph API Explorer → Generate Token | All Meta Marketing API calls | `ads_read` (read-only, least-privilege) | | META_AD_ACCOUNT_ID | Ads Manager URL: `adsmanager.facebook.com/act_XXXXXXXXX` | Identifying which account to query | — | ## When to Use Loaded when user wants to understand how their Meta Ads campaign is performing — either a specific aspect (audience, creative, overall) or a full diagnostic. Can run standalone or as prerequisite for meta-ads-recommendation. --- ## Step 0: Understand the Campaign Before pulling any data, get context on what this campaign is trying to do. Ask 1–2 quick questions if not already clear from conversation: - "Is this an always-on campaign, or tied to a specific promotion?" - "Are you testing new things, or trying to scale what's already working?" Keep it conversational. If META_ACCESS_TOKEN or META_AD_ACCOUNT_ID is not available, tell the user exactly what is needed and do not proceed with API calls. --- ## Step 1: Gather Campaign Structure Ask the user for their Meta Ads account access. Use the Meta Marketing API to fetch: ### Campaign level - Campaign name, ID, status (is it ACTIVE?) - Objective (what counts as a "result" — leads, purchases, clicks?) - Budget type (CBO = campaign-level budget optimization, or ABO = adset-level) - Bid strategy, daily budget, start date ### Adset level - Adset name, ID, status - Optimization goal (this determines what "results" means for this adset) - Targeting countries, budget, bid amount ### Ad level - Ad name, ID, status - Which adset it belongs to Store this as `campaign_context`. Reuse across the session — don't re-fetch. --- ## Step 2: Confirm Time Range and Attribution Window Always confirm the time period and attribution window before pulling performance data: 1. Time range: "What time period would you like to analyze? (e.g., last 7 days, last 30 days, or a specific date range)" 2. Attribution window: "What attribution window are you using? Default in Meta is 7-day click. For e-commerce, 1-day click often gives a clearer signal. For lead gen, 7-day click is usually better." | Campaign type | Recommended attribution window | |--------------|--------------------------------| | E-commerce / purchase | 1-day click | | Lead generation | 7-day click | | App installs | 7-day click | | Brand awareness | 28-day view | Convert to `YYYY-MM-DD,YYYY-MM-DD` format. Default granularity: - ≤14 days → daily - 15–60 days → weekly --- ## Step 3: Route the Analysis | User is asking about | What to analyze | |----------------------|-----------------| | Overall / general health | Campaign-level metrics, no breakdown | | Audience / country / platform / age / gender | Adset or ad level with breakdowns | | Creative / which ad is better | Ad-level metrics | | Everything / full diagnostic | All three in sequence | | Follow-up on existing data | Use data already in session — don't re-fetch | --- ## Step 4: Pull and Interpret Performance Data Use the Meta Marketing API to fetch metrics for the relevant level and time range. ### Key Metrics to Collect **At campaign or adset level:** - Spend, impressions, frequency - CPM (cost per 1,000 impressions) - CPC (cost per link click) - CTR (link click rate) - LPV rate (landing page view rate = landing page views / link clicks) - Results, cost per result - Conversion rate (results / landing page views) **At ad level, add:** - Individual ad performance - Creative elements if identifiable ### What Each Metric Tells You | Metric | Declining = | Growing = | |--------|-------------|-----------| | CPM | Cheaper reach | Competition up | | CPC / cost_per_result | More efficient | Less efficient | | CTR / LPV rate / conversion_rate | Problem | Healthy | | Results volume | Dropping | Growing | | Frequency | — | Fatigue risk if > 3 | ### Understanding "Results" The meaning of "results" depends on the optimization goal: - LEAD_GENERATION → results = leads - LINK_CLICKS → results = link clicks - LANDING_PAGE_VIEWS → results = landing page views - PURCHASE / CONVERSIONS → results = purchases Always clarify what "results" means when discussing cost_per_result. ### Campaign Structure Matters - CBO (campaign-level budget): Evaluate at campaign level first - ABO (adset-level budget): Evaluate at adset level - Multiple ads in one adset: Evaluate at adset level, not individual ads - Active but less than 7 days old + less than 50 results since last significant edit: Treat as still in learning phase — data is unstable - Breakdown Effect: Meta optimizes for marginal CPA (cost of the next result), not average CPA. A segment showing higher average CPA may be protecting overall campaign efficiency. Do not judge system decisions by average CPA in breakdown reports alone. --- ## Step 4b: Lead Generation Campaigns > Use **meta-ads-lead-gen-analysis** instead — it has dedicated LPV benchmarks for lead gen, form friction analysis, CAPI verification, and lead quality diagnosis. --- ## Step 4c: Landing Page Diagnostic > This section has moved to **meta-ads-recommendation → Step 4**. Landing page diagnosis is now part of the recommendation workflow for better action alignment. --- ## Step 5: Check Ad Relevance Diagnostics When an ad's cost_per_result is elevated and basic metrics (CTR, LPV rate) don't fully explain it, check the Ad Relevance Diagnostics in Meta Ads Manager. | Diagnostic | What it measures | Low ranking suggests | |-------------|-------------------|-----------------------| | Quality Ranking | Perceived ad quality vs. competitors | Improve creative | | Engagement Rate Ranking | Expected engagement vs. competitors | Test new angles, improve hook | | Conversion Rate Ranking | Expected conversion vs. competitors with same optimization goal | Check landing page or audience-offer fit | **Usage rules:** - Requires 500+ impressions to be available — below that, diagnostics are not meaningful - These are diagnostic tools only, not auction inputs - When all three rankings are low simultaneously → strong audience-creative mismatch --- ## Step 6: Assess for Problems Flag these when you see them: - Frequency > 3 → Audience fatigue risk - CTR less than 1% → Weak creative hook or audience mismatch - LPV rate less than 70% → Ad-to-landing-page disconnect - cost_per_result rising → Efficiency problem - Status is not ACTIVE → Explain impact - Learning / Learning Limited → Warn: data not yet stable - Spend less than 50% of budget → Delivery problem — audience may be too narrow or bid too low - One segment vastly outperforming others → System is correctly finding winners --- ## Step 7: Structure Your Output - **Campaign Context**: one sentence covering objective, budget type, and status. - **Summary**: Spend, impressions, results, cost per result, CTR, CPM. - **Funnel**: Impressions → Link Clicks → Landing Page Views → Results, with rates at each stage. - **Trend Analysis**: Key metrics with direction and what it means for the business. - **Key Issues**: Specific problems and why they matter. - **Data Notes**: Any caveats — learning phase, insufficient data, zero-spend entities excluded. --- ## Tone and Language - Match the language the user speaks (English or Chinese) - Speak as a professional growth partner — translate numbers into business insights - Every judgment must cite specific data. Never say "performance is bad" without a number - When data is insufficient, say so: "2 days isn't enough for reliable trends — let's revisit in a week" --- ## Restrictions - Analysis only — never output recommendations in this skill - Do not recalculate metrics already computed by Meta (CTR, CPM, CPC are already calculated) - Never conclude an ad or adset is "underperforming" based on CPA alone without comparing to its own historical baseline and the account average --- ## Session Context — What This Skill Writes After completing analysis, store the following in session context: | Key | Description | Example | |-----|-------------|---------| | funnel_weak_points | Where the biggest funnel drop-off occurs | "LPV rate 58%, well below 70% benchmark" | | trend_signals | Direction of key metrics | "CPM up 18% WoW; CTR down 0.4pp" | | anomalies | Anything unusual or unexpected | "Frequency 4.2 with CPL still at target" | | data_quality | Whether there's enough data to act | "Only 2 days — too early to judge" | | lp_diagnosis_general | Is the problem ad-side or landing page-side? | "Ad side — CTR declining, frequency stable" | > **Routing:** If the campaign is Lead Gen, route to meta-ads-lead-gen-analysis and preserve these keys. meta-ads-recommendation reads these keys to produce the action plan.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)