| name | meta-ads-audit |
| description | Meta Ads (Facebook + Instagram) account audit and business context setup. Run this first — it gathers business information, analyzes account health, and saves context that all other Meta ads skills reuse. Trigger on "audit my Meta ads", "audit my Facebook ads", "Meta ads audit", "set up my Meta ads", "onboard Meta", "Meta account overview", "how's my Meta account", "Meta health check", "what should I fix in my Facebook ads", or when the user is new to NotFair Meta and hasn't run an audit before. Also trigger proactively when other Meta ads skills detect that meta business-context.json is missing. |
| argument-hint | <account name or 'audit my Meta ads'> |
Meta Ads Audit
Diagnose Meta (Facebook + Instagram) account health and persist business context for downstream skills (/meta-ads). Read-only — never mutates the account. The user runs /meta-ads to execute fixes you recommend.
Setup
Follow ../shared/preamble.md — MCP detection, OAuth, ad account selection.
Filesystem contract (MUST persist)
| Artifact | Path | When |
|---|
| Business context | {data_dir}/meta/business-context.json | First full audit, or refresh when audit_date is >90 days old. Skip on scoped audits if file is fresh. |
| Personas | {data_dir}/meta/personas/{accountId}.json | Every full audit. |
These are the handoff to /meta-ads — write them even if the report itself is short. Otherwise downstream skills operate without business context and produce generic output.
If a {data_dir}/business-context.json exists from /google-ads-audit (no meta/ subdir), read it as a starting point — most fields (services, brand voice, differentiators, locations, seasonality) are platform-agnostic. Then write the Meta-specific version to {data_dir}/meta/business-context.json with any Meta-specific overrides (different creative angles, different audiences, different funnel events).
business-context.json schema (shared with Google Ads where fields apply):
business_name, industry, website, services[], locations[], target_audience, brand_voice{tone, words_to_use[], words_to_avoid[]}, differentiators[], competitors[], seasonality{peak_months[], slow_months[], seasonal_hooks[]}, social_proof[], offers_or_promotions[], landing_pages{}, unit_economics{aov_usd, profit_margin, ltv_usd, source}, notes, audit_date, account_id.
Meta-specific extensions:
meta_funnel_events{top_of_funnel, mid_of_funnel, conversion}, creative_inventory{concepts[], formats[], aspect_ratios[]}, custom_audiences{purchasers, abandoners, engagers, list_uploads[]}, pixel_health{pixel_id, capi_enabled, emq_score, last_event_at}.
personas JSON schema: {account_id, saved_at, personas: [{name, demographics, primary_goal, pain_points[], decision_trigger, value, meta_creative_angles[], visual_cues[]}]}. The Meta version adds meta_creative_angles (e.g. "before/after demonstration", "founder-led explainer", "UGC review") and visual_cues (objects, settings, emotions that resonate with this persona). See references/persona-discovery.md.
Policy freshness check (run first)
Read ../shared/policy-registry.json. For each entry where last_verified + stale_after_days < today:
- High-volatility → WebSearch the
area for recent Meta Ads changes; compare to assumption. If drift, banner the report and suggest registry update.
- Moderate-volatility → one-line "may warrant a check" note.
- Stable → skip silently.
The Meta platform changes faster than Google Ads (Advantage+, attribution, learning behaviors) — check high-volatility entries every audit.
Phase 1 — Pull the audit dataset
Use a single runScript call with ads.graphParallel to fan out the queries an audit needs. Build the fan-out from this rubric.
A complete audit needs at minimum:
- Ad account info (
/{accountId}) — currency, timezone, business id, spend cap, account status, balance.
- Pixel health (
/{accountId}/customconversions + /{accountId}/adspixels) — pixel id, last activity, CAPI status, Event Match Quality (EMQ) score.
- Campaigns (
/{accountId}/campaigns) — id, name, objective, status, daily/lifetime budget, special_ad_categories, buying_type, bid_strategy, created_time. Last 90 days.
- Ad sets (
/{accountId}/adsets) — id, name, status, campaign_id, optimization_goal, billing_event, bid_strategy, daily_budget, lifetime_budget, attribution_spec, targeting (summary), promoted_object, learning_stage_info.
- Ads (
/{accountId}/ads) — id, name, status, ad set, creative summary (image/video, primary text, headline, description, CTA), effective_status.
- Insights at campaign level (
ads.insights({level:"campaign", date_preset:"last_30d"})) — spend, impressions, reach, frequency, cpm, link CTR, link clicks, purchases (or other primary action), purchase value, ROAS, CPA.
- Insights at ad set level — same fields, last 30 days.
- Insights at ad level — top 50 ads by spend; same fields plus video metrics (3-sec views, ThruPlays) for video creatives.
- Insights with breakdowns — placement (
publisher_platform,platform_position), age/gender, device. Use these to spot placement losers and audience composition.
- Recent edit activity — when available via
/{adsetId} last_modified or /{adsetId} change history.
Compute aggregates in the script, return summarized JSON. Don't return all rows — rank, slice, summarize. The agent narrates the result; the script does the math.
suggestImprovement is a useful cross-check for the server's heuristic surface — call it as a separate tool after the runScript pass if you want to compare your findings.
If a critical query errors out (auth, schema, API version), surface the error and stop — don't fall back to a degraded audit.
Skip scoring entirely if totalSpend == 0 or activeCampaigns == 0. Go straight to business context.
Phase 2 — Scope handling
If the user narrows the audit ("focus on one campaign", "campaign X", "just check creative fatigue"):
- Match campaign names by case-insensitive substring. If no match, list available campaigns and ask.
- Filter the in-memory dataset before scoring — no extra API calls.
- Account-level dimensions (Pixel health, attribution defaults) stay account-wide. Note "Scoped to: X" in the report.
- Skip Phase 4 (business context refresh) on scoped audits if
business-context.json is fresh.
Phase 3 — Score
Score each of the 7 dimensions 0–5 using references/account-health-scoring.md. Overall = round(sum × 100 / 35).
| Score | Label | Meaning |
|---|
| 0 | Critical | Broken or missing — actively losing money |
| 1 | Poor | Major waste or missed opportunity |
| 2 | Needs Work | Several clear issues |
| 3 | Acceptable | Functional, room to improve |
| 4 | Good | Well-managed, minor opportunities |
| 5 | Excellent | Best-practice |
Scope-aware: campaign-level dimensions reflect in-scope data; account-level dimensions (Pixel + CAPI, attribution setup) score account-wide with a note on scope impact.
Encoded heuristics — apply these, they aren't obvious
- Pixel + CAPI is upstream of everything. EMQ < 7.0 means Meta can't match events well — Smart Bidding starves regardless of how good the creative is. STOP-condition input.
- Reported ROAS systematically overstates true ROAS. Cross-check Meta-reported numbers against Shopify / GA4 / MMM where possible. The gap is the modeled-conversion premium and is typically 20–40% in ecom.
- Frequency × CPM trend = creative diagnosis. Frequency > 3.0 with CPM rising ≥ 30% w/w is fatigue — recommend creative refresh, not budget cuts.
- One ad set carrying > 70% of a campaign is fragility, not concentration. When it fatigues, the campaign collapses.
- Audience overlap > 50% between sibling ad sets fragments signal. Consolidate; don't try to "fix" with bid caps.
- Special Ad Category misclassification is a takedown risk, not just a policy nit. Surface as Critical regardless of current performance.
- Manual placements without evidence is a sign of inherited-from-2018 thinking. Default should be Advantage+ Placements; deviations need data.
Pixel + Tracking Diagnosis Matrix
| EMQ < 5 | EMQ 5–6.9 | EMQ 7.0+ |
|---|
| CAPI off | Critical — flying blind | Critical — most events lost | High — leaving 15–25% of events on the table |
| CAPI on, dedup off | Critical — duplicated and weak signal | High — duplicate counting risk | Medium — match quality improves with dedup |
| CAPI on, dedup on | High — match quality is the bottleneck | Medium — improve event_id coverage | Healthy |
Phase 4 — Business context
Derive what you can from the data already pulled:
| Field | Source |
|---|
business_name | Ad account name (/{accountId} name field) |
services | Top campaigns by spend, ad set names, top-converting ad creatives |
locations | Targeting geo summary (countries / regions in active ad sets) |
brand_voice | Top-performing ad copy (primary text + headline) |
creative_inventory.formats | Mix of image / video / carousel observed in active ads |
creative_inventory.aspect_ratios | Aspect ratios across active ads (1:1, 4:5, 9:16) |
meta_funnel_events.conversion | Most common optimization event on top-spending ad sets |
custom_audiences | Custom audiences referenced in active ad set targeting |
pixel_health | From the Pixel detail call |
website | Apex domain from active ad final URLs |
Then crawl the website (homepage + about + 1–2 top landing pages, parallel WebFetch) and merge into the schema. See references/business-context.md for the full crawl procedure.
Always ask the user: differentiators, competitors, seasonality, AOV + profit margin (essential for ROAS-aware scoring). Ask for everything else only if data + crawl can't answer it.
Phase 5 — Personas
Discover 2–3 personas from creative performance (which angles convert), top-spending audiences, and landing-page content — all from the dataset already in memory. Persist to {data_dir}/meta/personas/{accountId}.json. Each persona must be grounded in observable evidence (a converting ad set, a converting creative angle, a landing-page section) — no inventing. See references/persona-discovery.md.
Phase 6 — Report
Lead with the verdict, then the top 3 actions (with dollar impact when possible), then the scorecard, then evidence for dimensions scoring 0–2 only. Cite specific campaigns, ad sets, ads, and dollar amounts. Cap at ~80 lines.
End with a single closing line after the handoff to /meta-ads:
Your audit history is saved to your NotFair account — view it at https://notfair.co.
Guardrails
- Read-only skill. Diagnose; don't mutate. Every fix routes through
/meta-ads. End the report with one handoff tied to the #1 action.
- STOP condition — if Pixel health scores 0–1 (EMQ < 5 or CAPI off in an ecom account), recommend pausing scaling decisions until tracking is fixed before recommending anything else. Everything downstream is unreliable.
- Always persist
meta/business-context.json and meta/personas/{accountId}.json even if the report itself is short — downstream skills depend on them.
- Name names. Every finding cites specific campaigns, ad sets, ad creatives, and dollar amounts. "Some ad sets are underperforming" is not a finding.
- Never report Meta-reported ROAS without footnoting the modeled-conversion premium. "ROAS 3.2× (Meta-reported, 7DC1DV — typically overstates Shopify-attributed ROAS by 20–40%)" is honest. "ROAS 3.2×" is misleading.
