{"id":"9e9e9c2e-b96c-489a-bd0a-ada81021508c","shortId":"kw79J7","kind":"skill","title":"meta-ads-library","tagline":"Research competitor Facebook and Instagram ads from the Meta Ads Library via the Hyper MCP — search by keyword, pull full ad creative and metadata, enrich with page contact info for lead generation, and surface structured ad-intelligence summaries in chat. Use when the user wants","description":"# Meta Ads Library\n\nGuide for searching the Meta Ads Library and producing structured competitor ad intelligence.\n\nThe skill's job is to turn raw scraped ads into useful summaries: top advertisers, common CTAs, recurring hooks, recently launched creatives, and (optionally) enriched lead lists. All output is presented inline in chat — there is no database or persistence layer.\n\n## Out of scope — defer to other skills\n\n| Request | Send them to |\n| --- | --- |\n| Multi-source competitor research (site, social, search rank, etc., not just ads) | [`competitor-intel`](../competitor-intel) |\n| Generating *new* ad creative based on what you found | [`ad-creative-generation`](../ad-creative-generation) |\n\n## Requirements\n\n- **Hyper MCP installed and connected.** [https://app.hyperfx.ai/mcp](https://app.hyperfx.ai/mcp)\n- **Apify integration connected** at [https://app.hyperfx.ai/integrations](https://app.hyperfx.ai/integrations) — the Meta Ads Library tools run via Apify under the hood.\n\nIf `search_facebook_ads` is not in the tool list, stop and tell the user to enable Hyper MCP and connect Apify.\n\n## Tool surface\n\n| Tool | Purpose |\n| --- | --- |\n| `search_facebook_ads` | Search the Meta Ads Library by keyword. Returns compact results (title, body, CTA, link, page name, dates, platforms). Max 40 per call. |\n| `get_facebook_ad_details` | Get full details for a specific ad. Requires both `ad_archive_id` **and** `page_id` — both come from `search_facebook_ads` results. |\n| `search_facebook_ads_enriched` | Search + enrich each result with page contact info (email, phone, website). Slower (multiple API calls per result). Max 20 per call. |\n| `search_facebook_pages` | Search Facebook pages by category + location (not by keyword). Useful for building a lead list from a vertical. |\n| `scrape_facebook_pages` | Scrape detailed data from specific Facebook page URLs. |\n\n## Critical rules\n\n1. **Public-only data.** The Meta Ads Library is public. Don't attempt to bypass any access control or scrape private content.\n2. **Count limits differ between tools.** `search_facebook_ads` allows `count` up to 40. `search_facebook_ads_enriched` caps at 20 — exceeding this returns an error.\n3. **`get_facebook_ad_details` needs two IDs.** Both `ad_archive_id` and `page_id` are required. Both are returned in every `search_facebook_ads` result row — pass them through together.\n4. **Enriched search is slow.** It makes a Facebook page scrape per ad and optionally a website scrape. Only use it when contact info matters (lead-gen workflows). For pure ad intelligence, use the regular `search_facebook_ads`.\n5. **Apify-backed tools fail intermittently.** Expect occasional `\"fetch failed\"` responses. Retry once after a short delay before reporting the source as missing.\n6. **Don't over-interpret a single ad.** \"Brand X is running a discount\" is noise. \"5 of the top 10 advertisers in this query are running discounts\" is signal. Always aggregate before drawing conclusions.\n\n## Workflow\n\n### Phase 1 — Define the query\n\nBefore running anything, agree on:\n\n1. **The search query** — keyword(s) competitors would target. Examples: `\"meal kit delivery\"`, `\"AI marketing tools\"`, `\"skincare for sensitive skin\"`.\n2. **Country** — ISO code (e.g. `\"US\"`, `\"GB\"`, `\"AU\"`). Default to `\"ALL\"` only if the user explicitly wants global.\n3. **Active vs all** — `active_status=\"active\"` is usually what you want. Inactive ads are historical and noisier.\n4. **Time window** — `period` accepts `\"last24h\"`, `\"last7d\"`, `\"last14d\"`, `\"last30d\"`, or `\"all_time\"`. Match the window to the user's intent (weekly digest → `\"last7d\"`, trend research → `\"last30d\"`).\n5. **The job** — what is this for?\n   - **Creative trend report** → use `search_facebook_ads`, summarize patterns across hooks, CTAs, formats.\n   - **Top advertiser snapshot** → use `search_facebook_ads`, group by `page_name`.\n   - **Lead list** → use `search_facebook_ads_enriched`, filter for rows with `contact_email` or `contact_website`.\n\n### Phase 2 — Pull the ads\n\n```\nsearch_facebook_ads(\n    query=\"meal kit delivery\",\n    country=\"US\",\n    active_status=\"active\",\n    count=40,                # max for this tool\n    period=\"last30d\"\n)\n```\n\nEach result row includes: `ad_archive_id`, `page_id`, `page_name`, `is_active`, `start_date_formatted`, `end_date_formatted`, `title`, `body`, `cta_text`, `link_url`, `caption`, `ad_library_url`, `page_categories`, `publisher_platform`.\n\nFor more than 40 ads, paginate by re-calling with `offset=40`, `offset=80`, etc.\n\nFor lead-gen with contact info:\n\n```\nsearch_facebook_ads_enriched(\n    query=\"meal kit delivery\",\n    country=\"US\",\n    active_status=\"active\",\n    count=20,                # max for the enriched tool\n    scrape_websites=True,\n    filter_spam=False\n)\n```\n\nEnriched rows add: `contact_email`, `contact_phone`, `contact_website`, `page_followers`, `page_rating`, address, business hours.\n\n### Phase 3 — Get full creative for the most interesting ads (optional)\n\n`search_facebook_ads` returns truncated bodies for some ads. To get the complete creative — including video URLs and images — call `get_facebook_ad_details` on the specific ads worth a deeper look:\n\n```\nget_facebook_ad_details(\n    ad_archive_id=\"559220927273823\",      # from search results\n    page_id=\"328127803978438\"             # from search results\n)\n```\n\nBoth args come from the same row in `search_facebook_ads`. Do this for the top 3–5 ads, not all 40 — each detail call is a separate Apify run.\n\n### Phase 4 — Surface the intelligence\n\nPresent the findings inline in chat. Pick the format that matches the user's job from Phase 1.\n\n**Top advertisers (group by page):**\n\n| Page | Active ads | Categories | Notable angle |\n| --- | --- | --- | --- |\n| Brand A | 12 | Restaurant, Meal Kit | \"Skip the grocery store\" hook in 8/12 ads |\n| Brand B | 7 | Software, Subscription | Heavy on UGC video, \"$1 first week\" offer |\n\n**Common CTAs and hooks:**\n\n| Pattern | Count | Examples |\n| --- | --- | --- |\n| `Sign up` CTA | 18 | … |\n| `Shop now` CTA | 12 | … |\n| Price-anchor opener (\"From $X/week\") | 9 | … |\n| Founder-story opener | 4 | … |\n\n**Recently launched ads (last 7 days):**\n\n| Page | Started | CTA | Hook | Library URL |\n| --- | --- | --- | --- | --- |\n| Brand A | 2026-04-28 | Sign up | \"Skip the grocery run this week\" | <ad_library_url> |\n\n**Lead list (enriched only):**\n\n| Page | Email | Website | Followers | Active ads |\n| --- | --- | --- | --- | --- |\n| Brand A | hello@a.com | a.com | 12K | 7 |\n\n### Phase 5 — Recurring monitoring (optional)\n\nIf the user wants ongoing tracking:\n\n1. Save the query, country, and `active_status` settings.\n2. Re-run weekly with `period=\"last7d\"`.\n3. Brief becomes a delta report — *new* ads since the last run, advertisers that changed posting cadence, CTA / offer shifts.\n\nThis is when [`competitor-intel`](../competitor-intel) becomes the better skill — it handles multi-source diffing across many surfaces, not just Meta ads.\n\n## Output standards\n\n- **Always cite the `ad_library_url`** for any specific ad referenced in the brief — the user can click through to verify.\n- **Aggregate before quoting.** Don't paste raw ad bodies; extract the pattern and quote 1–2 representative examples.\n- **Mark interpretation explicitly.** \"Observation: 8 of 10 top advertisers use a 'first week free' offer. Possible interpretation: …\".\n- **Note the time window.** Every brief should state the search query, country, and date range it was generated from.","tags":["meta","ads","library","marketing","skills","hyperfx-ai","agent-skills","ai-agent","claude","claude-code","claude-skills","codex"],"capabilities":["skill","source-hyperfx-ai","skill-meta-ads-library","topic-agent-skills","topic-ai-agent","topic-claude","topic-claude-code","topic-claude-skills","topic-codex","topic-cursor","topic-google-ads","topic-hermes","topic-marketing","topic-mcp","topic-meta-ads"],"categories":["marketing-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/hyperfx-ai/marketing-skills/meta-ads-library","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add hyperfx-ai/marketing-skills","source_repo":"https://github.com/hyperfx-ai/marketing-skills","install_from":"skills.sh"}},"qualityScore":"0.462","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 24 github stars · SKILL.md body (7,478 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:05:16.759Z","embedding":null,"createdAt":"2026-05-07T13:06:43.717Z","updatedAt":"2026-05-18T19:05:16.759Z","lastSeenAt":"2026-05-18T19:05:16.759Z","tsv":"'-04':948 '-28':949 '/ad-creative-generation':149 '/competitor-intel':135,1028 '/integrations](https://app.hyperfx.ai/integrations)':165 '/mcp](https://app.hyperfx.ai/mcp)':158 '1':313,494,503,867,902,985,1083 '10':477,1093 '12':881,920 '12k':972 '18':916 '2':336,523,633,994,1084 '20':276,356,727 '2026':947 '3':362,541,756,831,1002 '328127803978438':811 '4':393,559,846,932 '40':225,349,650,693,702,836 '5':432,473,585,832,975 '559220927273823':805 '6':456 '7':895,937,973 '8':1091 '8/12':891 '80':704 '9':927 'a.com':971 'accept':563 'access':330 'across':601,1039 'activ':542,545,547,646,648,669,723,725,874,966,991 'ad':3,10,14,25,41,52,59,65,76,131,138,146,168,180,205,209,230,238,241,252,256,320,344,352,365,371,386,405,424,431,464,554,598,611,621,636,639,661,683,694,715,764,768,774,788,793,800,802,825,833,875,892,935,967,1009,1045,1051,1057,1076 'ad-creative-gener':145 'ad-intellig':40 'add':741 'address':752 'advertis':81,478,606,869,1014,1095 'aggreg':488,1069 'agre':501 'ai':516 'allow':345 'alway':487,1048 'anchor':923 'angl':878 'anyth':500 'api':271 'apifi':159,173,198,434,843 'apify-back':433 'app.hyperfx.ai':157,164 'app.hyperfx.ai/integrations](https://app.hyperfx.ai/integrations)':163 'app.hyperfx.ai/mcp](https://app.hyperfx.ai/mcp)':156 'archiv':242,372,662,803 'arg':816 'attempt':326 'au':530 'b':894 'back':435 'base':140 'becom':1004,1029 'better':1031 'bodi':217,677,771,1077 'brand':465,879,893,945,968 'brief':1003,1061,1109 'build':293 'busi':753 'bypass':328 'cadenc':1018 'call':227,272,278,699,785,839 'cap':354 'caption':682 'categori':286,687,876 'chang':1016 'chat':45,100,855 'cite':1049 'click':1065 'code':526 'come':248,817 'common':82,906 'compact':214 'competitor':6,64,122,133,509,1026 'competitor-intel':132,1025 'complet':778 'conclus':491 'connect':155,161,197 'contact':32,264,415,627,630,711,742,744,746 'content':335 'control':331 'count':337,346,649,726,911 'countri':524,644,721,989,1115 'creativ':26,88,139,147,592,759,779 'critic':311 'cta':218,678,915,919,941,1019 'ctas':83,603,907 'data':305,317 'databas':104 'date':222,671,674,1117 'day':938 'deeper':796 'default':531 'defer':111 'defin':495 'delay':449 'deliveri':515,643,720 'delta':1006 'detail':231,234,304,366,789,801,838 'dif':1038 'differ':339 'digest':580 'discount':470,484 'draw':490 'e.g':527 'email':266,628,743,963 'enabl':193 'end':673 'enrich':29,91,257,259,353,394,622,716,731,739,960 'error':361 'etc':128,705 'everi':383,1108 'exampl':512,912,1086 'exceed':357 'expect':439 'explicit':538,1089 'extract':1078 'facebook':7,179,204,229,251,255,280,283,301,308,343,351,364,385,401,430,597,610,620,638,714,767,787,799,824 'fail':437,442 'fals':738 'fetch':441 'filter':623,736 'find':852 'first':903,1098 'follow':749,965 'format':604,672,675,858 'found':144 'founder':929 'founder-stori':928 'free':1100 'full':24,233,758 'gb':529 'gen':420,709 'generat':36,136,148,1121 'get':228,232,363,757,776,786,798 'global':540 'groceri':887,954 'group':612,870 'guid':54 'handl':1034 'heavi':898 'hello@a.com':970 'histor':556 'hood':176 'hook':85,602,889,909,942 'hour':754 'hyper':18,151,194 'id':243,246,369,373,376,663,665,804,810 'imag':784 'inact':553 'includ':660,780 'info':33,265,416,712 'inlin':98,853 'instagram':9 'instal':153 'integr':160 'intel':134,1027 'intellig':42,66,425,849 'intent':578 'interest':763 'intermitt':438 'interpret':461,1088,1103 'iso':525 'job':70,587,864 'keyword':22,212,290,507 'kit':514,642,719,884 'last':936,1012 'last14d':566 'last24h':564 'last30d':567,584,656 'last7d':565,581,1001 'launch':87,934 'layer':107 'lead':35,92,295,419,616,708,958 'lead-gen':418,707 'librari':4,15,53,60,169,210,321,684,943,1052 'limit':338 'link':219,680 'list':93,186,296,617,959 'locat':287 'look':797 'make':399 'mani':1040 'mark':1087 'market':517 'match':571,860 'matter':417 'max':224,275,651,728 'mcp':19,152,195 'meal':513,641,718,883 'meta':2,13,51,58,167,208,319,1044 'meta-ads-librari':1 'metadata':28 'miss':455 'monitor':977 'multi':120,1036 'multi-sourc':119,1035 'multipl':270 'name':221,615,667 'need':367 'new':137,1008 'nois':472 'noisier':558 'notabl':877 'note':1104 'observ':1090 'occasion':440 'offer':905,1020,1101 'offset':701,703 'ongo':983 'open':924,931 'option':90,407,765,978 'output':95,1046 'over-interpret':459 'page':31,220,245,263,281,284,302,309,375,402,614,664,666,686,748,750,809,872,873,939,962 'pagin':695 'pass':389 'past':1074 'pattern':600,910,1080 'per':226,273,277,404 'period':562,655,1000 'persist':106 'phase':493,632,755,845,866,974 'phone':267,745 'pick':856 'platform':223,689 'possibl':1102 'post':1017 'present':97,850 'price':922 'price-anchor':921 'privat':334 'produc':62 'public':315,323 'public-on':314 'publish':688 'pull':23,634 'pure':423 'purpos':202 'queri':481,497,506,640,717,988,1114 'quot':1071,1082 'rang':1118 'rank':127 'rate':751 'raw':74,1075 're':698,996 're-cal':697 're-run':995 'recent':86,933 'recur':84,976 'referenc':1058 'regular':428 'report':451,594,1007 'repres':1085 'request':115 'requir':150,239,378 'research':5,123,583 'respons':443 'restaur':882 'result':215,253,261,274,387,658,808,814 'retri':444 'return':213,359,381,769 'row':388,625,659,740,821 'rule':312 'run':171,468,483,499,844,955,997,1013 'save':986 'scope':110 'scrape':75,300,303,333,403,410,733 'search':20,56,126,178,203,206,250,254,258,279,282,342,350,384,395,429,505,596,609,619,637,713,766,807,813,823,1113 'send':116 'sensit':521 'separ':842 'set':993 'shift':1021 'shop':917 'short':448 'sign':913,950 'signal':486 'sinc':1010 'singl':463 'site':124 'skill':68,114,1032 'skill-meta-ads-library' 'skin':522 'skincar':519 'skip':885,952 'slow':397 'slower':269 'snapshot':607 'social':125 'softwar':896 'sourc':121,453,1037 'source-hyperfx-ai' 'spam':737 'specif':237,307,792,1056 'standard':1047 'start':670,940 'state':1111 'status':546,647,724,992 'stop':187 'store':888 'stori':930 'structur':39,63 'subscript':897 'summar':599 'summari':43,79 'surfac':38,200,847,1041 'target':511 'tell':189 'text':679 'time':560,570,1106 'titl':216,676 'togeth':392 'tool':170,185,199,201,341,436,518,654,732 'top':80,476,605,830,868,1094 'topic-agent-skills' 'topic-ai-agent' 'topic-claude' 'topic-claude-code' 'topic-claude-skills' 'topic-codex' 'topic-cursor' 'topic-google-ads' 'topic-hermes' 'topic-marketing' 'topic-mcp' 'topic-meta-ads' 'track':984 'trend':582,593 'true':735 'truncat':770 'turn':73 'two':368 'ugc':900 'url':310,681,685,782,944,1053 'us':528,645,722 'use':46,78,291,412,426,595,608,618,1096 'user':49,191,537,576,862,981,1063 'usual':549 'verifi':1068 'vertic':299 'via':16,172 'video':781,901 'vs':543 'want':50,539,552,982 'websit':268,409,631,734,747,964 'week':579,904,957,998,1099 'window':561,573,1107 'workflow':421,492 'worth':794 'would':510 'x':466 'x/week':926","prices":[{"id":"b4f39444-eb44-45af-b9d0-c097916767f1","listingId":"9e9e9c2e-b96c-489a-bd0a-ada81021508c","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"hyperfx-ai","category":"marketing-skills","install_from":"skills.sh"},"createdAt":"2026-05-07T13:06:43.717Z"}],"sources":[{"listingId":"9e9e9c2e-b96c-489a-bd0a-ada81021508c","source":"github","sourceId":"hyperfx-ai/marketing-skills/meta-ads-library","sourceUrl":"https://github.com/hyperfx-ai/marketing-skills/tree/main/skills/meta-ads-library","isPrimary":false,"firstSeenAt":"2026-05-07T13:06:43.717Z","lastSeenAt":"2026-05-18T19:05:16.759Z"}],"details":{"listingId":"9e9e9c2e-b96c-489a-bd0a-ada81021508c","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"hyperfx-ai","slug":"meta-ads-library","github":{"repo":"hyperfx-ai/marketing-skills","stars":24,"topics":["agent-skills","ai-agent","claude","claude-code","claude-skills","codex","cursor","google-ads","hermes","marketing","mcp","meta-ads","openclaw","seo"],"license":"mit","html_url":"https://github.com/hyperfx-ai/marketing-skills","pushed_at":"2026-05-09T22:58:46Z","description":"Marketing skills for AI agents — paid ads, social media, SEO, competitor research, creative generation, email, analytics, and more. Powered by Hyper MCP.","skill_md_sha":"07fc99be9af6447050b7a935738f2f370fdfa99d","skill_md_path":"skills/meta-ads-library/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/hyperfx-ai/marketing-skills/tree/main/skills/meta-ads-library"},"layout":"multi","source":"github","category":"marketing-skills","frontmatter":{"name":"meta-ads-library","description":"Research competitor Facebook and Instagram ads from the Meta Ads Library via the Hyper MCP — search by keyword, pull full ad creative and metadata, enrich with page contact info for lead generation, and surface structured ad-intelligence summaries in chat. Use when the user wants to scrape the Meta Ads Library, spy on competitor ads, monitor new ads in a category, build a lead list from advertisers, or surface creative trends across an industry."},"skills_sh_url":"https://skills.sh/hyperfx-ai/marketing-skills/meta-ads-library"},"updatedAt":"2026-05-18T19:05:16.759Z"}}