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:
- Time range: "What time period would you like to analyze? (e.g., last 7 days, last 30 days, or a specific date range)"
- 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.
