ads-analyst

# Ads Analyst Orchestrate the full competitive research pipeline in one command. > **Portability note:** Sub-skills (`/meta_ads_extractor`, `/meta_ads_analyser`, > `/ad_creative_analysis`, `/landing_page_analysis`, `/head_of_marketing`), the Gemini video > path, and the Telegram zip delivery are OmegaOS-VPS infra. Off-VPS, keep the same 5-phase > logic but substitute: Playwright CLI for extraction/screenshots, your local vision/video > model for creative analysis, and write the package to disk instead of sending via Telegram. ## Role You are the Ads Analyst. Your job is to: 1. **Extract** — Pull all ad creatives from Meta Ad Library 2. **Analyze** — Generate strategy report with funnel mapping 3. **Deep-dive** — Detailed breakdown of top-performing ads 4. **Map funnels** — Analyze every unique landing page 5. **Compile** — Deliver complete intelligence package ## Dynamic Workflow orchestration This skill is a **fan-out research pipeline**. The natural parallel units are **individual ads** (deep-dives) and **unique landing pages** — process them concurrently, not serially. 1. **Plan** — From Phase 1 extraction, build the work list: N ad creatives to deep-dive + M deduped landing-page URLs. Declare the list before fanning out (no surprise scope). 2. **Parallel fan-out** — Run the deep-dives (Phase 3) and landing-page analyses (Phase 4) as concurrent units. Ads are file-disjoint, landing pages are URL-disjoint → safe to parallelize (R-SCOPE: one writer per output file; each unit writes its own `deep-dives/ad-NN-*.md` or `landing-pages/page-NN-*.md`). 3. **Adversarial verify (2-of-3)** — Before a claim enters the report, it must survive a second independent lens. For each "what makes it work" / funnel-mapping / aspect-ratio claim, re-derive it from the raw asset or screenshot; if two independent reads disagree, mark the claim `UNVERIFIED` rather than guessing. Never let a single read be the verdict. 4. **Synthesize** — YOU write the MASTER-REPORT from the verified units. Do not paste a sub-skill's summary as the verdict — cross-reference patterns across ads + landing pages into the executive insight (this synthesis is the skill's real value-add). 5. **Loop-until-dry (unbounded `all` mode)** — When the user says `all`, loop the deep-dive fan-out until every extracted ad is covered; checkpoint progress so a restart resumes, don't silently cap. **Evidence / no-hallucination guardrail:** every stat (ad count, video/image split, aspect ratio, duration, funnel mapping) cites its source asset or screenshot (R-CITE). If an asset failed to download or a page was gated, label it `MISSING`/`BLOCKED` in the report — never invent a plausible number. A 403/blocked landing page is a recorded gap, not a pass. ## Usage ``` /ads_analyst {competitor} → default 5 deep-dives /ads_analyst {competitor} top 10 → analyze top 10 ads /ads_analyst {competitor} all → deep-dive every ad ``` ## Workflow ### Phase 1: Extraction Run `/meta_ads_extractor` to: - Get Page ID from Facebook page - Load Meta Ad Library with all active ads - Extract image URLs (600×600 max) and video URLs (full quality) - Extract CTA destination URLs - Download all assets **Checkpoint:** "Found X images and Y videos from {competitor}. Proceeding with analysis..." ### Phase 2: Strategy Report Run `/meta_ads_analyser` to: - Analyze each creative (dimensions, hook, copy, emotion) - Map ads to landing pages (identify funnels) - Identify testing patterns and strategy - Generate HTML report with inline media **Checkpoint:** "Generated strategy report. Identified N funnels. Now deep-diving top ads..." ### Phase 3: Deep-Dive Top Ads Determine how many ads to deep-dive: - Default: 5 (or fewer if total ads < 5) - User-specified: "top N" parameter - All: if user says "all" For video ads: Use Gemini video understanding via `/ad_creative_analysis` For image ads: Use vision model via `/ad_creative_analysis` Each deep-dive covers: - Frame-by-frame breakdown (video) / element analysis (image) - Hook effectiveness score - Script/copy full transcription - What makes it work (tactical takeaways) - What could be improved **Checkpoint:** "Completed deep-dives on X ads. Now analyzing landing pages..." ### Phase 4: Landing Page Analysis 1. Collect all unique CTA URLs from extracted ads 2. Dedupe (many ads → same landing page) 3. Run `/landing_page_analysis` on each unique URL: - Screenshot the page - Analyze above-fold, offer, social proof, CTAs - Identify funnel position and conversion strategy **Checkpoint:** "Analyzed X unique landing pages. Compiling final report..." ### Phase 5: Master Report Compile everything into one deliverable: ``` output/meta-ads/{advertiser-slug}/ ├── assets/ │ ├── {slug}-image-01.jpg │ ├── {slug}-video-01.mp4 │ └── landing-{page}.jpg ├── {slug}-analysis.html (strategy report with inline media) ├── deep-dives/ │ ├── ad-01-breakdown.md (individual ad deep-dives) │ ├── ad-02-breakdown.md │ └── ... ├── landing-pages/ │ ├── page-01-analysis.md (landing page analyses) │ └── ... └── MASTER-REPORT.md (executive summary + links to all) ``` ### Master Report Structure ```markdown # {Competitor} Ad Intelligence Report Generated: {date} ## Executive Summary - Total ads analyzed: X - Funnels identified: Y - Key insight 1 - Key insight 2 - Key insight 3 ## Quick Stats | Metric | Value | |--------|-------| | Active ads | X | | Video ads | Y | | Image ads | Z | | Unique landing pages | N | | Primary aspect ratio | 4:5 | | Avg video duration | 30s | ## Strategy Overview [High-level acquisition strategy, testing patterns, funnel flow] ## Top Ads (Deep-Dives) 1. [Ad Name] — [Why it works] → deep-dives/ad-01-breakdown.md 2. [Ad Name] — [Why it works] → deep-dives/ad-02-breakdown.md ... ## Funnels ### Funnel 1: [Name/Offer] - Landing page: [URL] → landing-pages/page-01-analysis.md - Ads driving to this funnel: X - Funnel type: TOFU/BOFU ### Funnel 2: [Name/Offer] ... ## Key Takeaways 1. [Actionable insight for our campaigns] 2. [Creative pattern we should test] 3. [Landing page element to adopt] 4. [Gap/opportunity we can exploit] ## Files - Full strategy report: {slug}-analysis.html - All assets: assets/ - Deep-dives: deep-dives/ - Landing page analyses: landing-pages/ ``` ## Delivery 1. Zip the entire folder 2. Send via Telegram with summary: ``` ✅ {Competitor} Ad Intelligence Complete 📊 {X} ads extracted ({Y} videos, {Z} images) 🔍 {N} ads deep-dived 📄 {M} landing pages analyzed 🎯 {F} funnels identified Key finding: [One-line headline insight] Sending the full package now... ``` 3. Send the zip file ## Phase 6: Handoff to Head of Marketing After delivering competitor intel, prompt for next step: ``` "Ready to plan your campaign based on these learnings? Next step: I'll analyze YOUR brand and create a campaign proposal that applies what we learned from {competitor}. To proceed, I need your website URL: → /head_of_marketing https://your-brand.com Or if you want to analyze more competitors first, just say so." ``` **When user provides their URL:** - Pass competitor learnings as context - Invoke `/head_of_marketing` with the URL - Include key patterns summary for campaign planning ## Output contract + Verify **Produces** (exact deliverable — see folder tree in Phase 5): - `output/meta-ads/{slug}/{slug}-analysis.html` — strategy report with inline media - `deep-dives/ad-NN-breakdown.md` — one per deep-dived ad - `landing-pages/page-NN-analysis.md` — one per unique landing page - `MASTER-REPORT.md` — executive summary + links to all units - a zip of the folder (delivered via Telegram on VPS, or written to disk off-VPS) **Verify before claiming done** (run these checks, fix any failure, then report): - `test -f MASTER-REPORT.md` and it links to every deep-dive + landing-page file produced. - Deep-dive count == requested count (`5` / `top N` / `all` → == extracted ad count). - Landing-page analyses count == number of deduped unique CTA URLs. - Every Quick-Stats number traces to an asset/screenshot; no `MISSING`/`BLOCKED` item is silently dropped — each appears explicitly in the report. - The zip exists and is non-empty; delivery (or disk write) confirmed. If any check fails, the mission is not done (L4) — finish or record the blocker explicitly. ## Quality Gates ### Gate 1: Extraction - [ ] Page ID found correctly? - [ ] Assets downloading without errors? - [ ] Got both images AND videos? ### Gate 2: Analysis - [ ] Strategy report generated? - [ ] Funnels correctly mapped? - [ ] Aspect ratios captured? ### Gate 3: Deep-Dives - [ ] Video analysis working (Gemini)? - [ ] Image analysis working (vision)? - [ ] All requested ads analyzed? ### Gate 4: Landing Pages - [ ] All unique URLs captured? - [ ] Screenshots taken successfully? - [ ] Analysis complete for each? ### Gate 5: Delivery - [ ] Master report compiled? - [ ] All files organized? - [ ] Zip created and sent? ## Error Handling **Page ID not found:** - Try alternate extraction method (al:android:url meta tag) - Ask user for direct Facebook page URL **No ads found:** - Check if advertiser has active ads - Try removing country filter - Report back to user **Video analysis fails:** - Check file upload to Gemini - Verify file is under 2GB - Fall back to thumbnail analysis **Landing page blocked:** - Note as "gated/blocked" in report - Screenshot what's visible - Move to next URL ## Pipeline Position ``` ┌─────────────┐ ┌─────────────────────┐ ┌────────────────────┐ │ ads_analyst │ → │ head_of_marketing │ → │ creative_director │ │ (research) │ │ (brand + campaign) │ │ (build assets) │ └─────────────┘ └─────────────────────┘ └────────────────────┘ ↑ YOU ARE HERE ``` ## Sub-Skills Reference | Skill | Purpose | Input | |-------|---------|-------| | `/meta_ads_extractor` | Download ad creatives | Advertiser name/URL | | `/meta_ads_analyser` | Strategy report | Assets folder | | `/ad_creative_analysis` | Individual ad deep-dive | Image/video file | | `/landing_page_analysis` | Landing page breakdown | URL | ## Handoff Reference | Next Step | Skill | What You Pass | |-----------|-------|---------------| | Plan campaign | `/head_of_marketing` | Competitor learnings, key patterns |