ad-analysis
Skill1 starsChanged 3 months agoMITView on GitHub
Expert diagnosis of Meta Ads performance — interpret Ads Manager/API data, find root causes, and produce evidence-cited reports that respect Meta's delivery mechanics (breakdown effect, learning phase, auction dynamics). Use when the user asks how ads/campaigns are performing, why CPA/CPL/ROAS/CPM changed, to analyze exported Meta ads data, to run a weekly review, or to diagnose delivery problems.
- Reads credentials
In this repository4 other files it gives its agents.
- ad-optimizationSkill
- campaign-managementSkill
- opportunity-spottingSkill
- pulseSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 56
Every insight carries data evidence.
- Distinctive: line 58
No winner/loser verdicts mid-learning or under ~50 conversions per arm — say "insufficient data" and what would settle it.
- Distinctive: line 59
If Meta's own recommendations are available (Account Overview, or the API recommendations endpoint), check them.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Meta Ads Analysis
You are analyzing a machine-learning delivery system, not a spreadsheet. Meta's system optimizes for marginal efficiency (cost of the next result), dynamically. Most naive analyses fail by judging average metrics in breakdown reports and recommending changes that fight the optimizer.
Core principles
- Holistic first — evaluate at the aggregate level before drilling down; the system optimizes the whole, not the parts.
- Dynamic over static — analyze trends over time, never single snapshots.
- Marginal over average — a segment with a higher average CPA may be protecting the campaign from even higher marginal costs elsewhere. Read
references/breakdown-effect.mdbefore interpreting any breakdown.
Workflow
Step 0 — Get the data
- In a workspace with a
data/raw/convention: use the freshest matching export there. - With API access configured (
META_ACCESS_TOKEN,META_AD_ACCOUNT_ID): runpython3 "${CLAUDE_PLUGIN_ROOT}/scripts/pull_insights.py" --level adset --last 7 --daily(add--breakdownsonly for the specific question at hand).--dailymatters: marginal analysis needs time series. - Otherwise: ask for an Ads Manager export (campaign + ad set + ad level, the analysis window plus the prior comparison window).
Step 1 — Identify the correct evaluation level (do this first, always)
| Campaign setup | Evaluate at |
| Advantage+ campaign budget (CBO) | Campaign level |
| Automatic placements, no CBO | Ad set level |
| Multiple ads in one ad set | Ad set level |
Judging entities below their evaluation level is how the breakdown effect produces false conclusions.
Step 2 — Gate on learning phase
For each ad set in scope: still learning (~50 optimization events within 7 days of last significant edit)? Learning limited? Significant edit recently (budget, bid, targeting, creative, optimization goal — all reset learning)? Findings about in-learning entities are preliminary and must say so. Details: references/delivery-system.md.
Step 3 — Analyze through five lenses
- Funnel decomposition — CPA = CPM ÷ (CTR × CVR × 10). Which term moved? Fix the biggest broken term first.
- Marginal efficiency — from daily time series, is a segment's CPA rising as spend concentrates? That, not average CPA, explains budget shifts.
- Relevance diagnostics — Quality / Engagement / Conversion rankings triage creative vs. targeting vs. post-click problems:
references/diagnostics.md. - Auction overlap & pacing — ad sets competing for the same people; budget held back by pacing. Both mimic "performance problems":
references/diagnostics.md. - Fluctuation triage — 20–30% day-to-day CPA variation is normal; >50% sustained for multiple days, delivery near zero, or CVR falling while spend rises are real:
references/diagnostics.md.
Step 4 — Synthesize with the breakdown effect in mind
Before writing any "segment X is underperforming" finding, check the daily series for the marginal story. Example of a correct read: "Placement A shows $10 average CPA vs. B's $15, but A's daily CPA is rising sharply — its marginal CPA likely exceeds B's, so the system's shift toward B is correct."
Step 5 — Report
Structure every report as:
- Executive summary — 2–3 findings, verdict first
- Evaluation level used and why
- Learning phase status per ad set in scope
- Performance analysis — correct metric names, trends not snapshots
- Diagnosis — root causes with evidence (metric + comparison + date range + sample size)
- Recommendations — each framed as a testable hypothesis with expected impact on overall performance, ranked by dollar impact
- Breakdown-effect notes — any place average-vs-marginal could mislead the reader
Hard rules
- NEVER recommend pausing or cutting budget for a segment based solely on higher average CPA/CPM in a breakdown report. Frame such changes as testable hypotheses with the marginal-efficiency caveat stated.
- Every insight carries data evidence; every recommendation is actionable and verifiable.
- Disambiguate clicks: "clicks (all)" ≠ "link clicks". Never say "clicks" bare. CTR likewise: link CTR vs. CTR (all).
- No winner/loser verdicts mid-learning or under ~50 conversions per arm — say "insufficient data" and what would settle it.
- If Meta's own recommendations are available (Account Overview, or the API recommendations endpoint), check them; when you diverge, say so and justify.
- State attribution settings when comparing windows; flag platform-vs-CRM conversion gaps rather than treating either as ground truth.
Metric naming (API field → report name)
impressions→Impressions · reach→Reach · frequency→Frequency · spend→Amount Spent · cpm→CPM · clicks→Clicks (all) · ctr→CTR (all) · inline_link_clicks→Link Clicks · inline_link_click_ctr→CTR (link) · act__lead→Leads · cpa__lead→Cost per Lead · act__purchase→Purchases · val__purchase→Purchase Value · roas__omni_purchase→Purchase ROAS · thruplays→ThruPlays
References
references/breakdown-effect.md— marginal vs. average, evaluation levels, worked example. Read first for any breakdown analysis.references/delivery-system.md— auctions, pacing, bid strategies, learning phase mechanics.references/diagnostics.md— relevance rankings triage, auction overlap, fluctuation thresholds.references/audit-checklist.md— weighted full-account audit catalog (signals 30 / creative 30 / structure 20 / audience 20) with scoring. Load for "audit the account" requests; themeta-ads-auditoragent runs on it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

