hyperfx-ai/marketing-skills

meta-ads-library

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.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/hyperfx-ai/marketing-skills --skill meta-ads-library

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

Meta Ads Library

Guide for searching the Meta Ads Library and producing structured competitor ad intelligence.

The 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.

Out of scope — defer to other skills

RequestSend them to
Multi-source competitor research (site, social, search rank, etc., not just ads)`competitor-intel`
Generating new ad creative based on what you found`ad-creative-generation`

Requirements

If meta_ad_library_ads_search is not found, the toolkit to enable is Meta Ads Library (meta_ads_library).

How to run the tools in this skill

Every tool in this skill is named by its canonical tool name. Run it with the call your surface gives you:

SurfaceFind a toolRun it
Hyper chatCall the tool by its name; search_tools(queries=["<provider> <action>"]) shows its parameters<name>(...)
MCP client (Claude, Cursor, Codex, ChatGPT)search("<what you want to do>"), then describe("<name>")call_read("<name>", {...}), call_write or call_destructive: the one that describe names in call_with
Hyper CLIhyperai search "<what you want to do>", then hyperai describe <name>hyperai call <name> --json '{...}'

If a tool is not found: in Hyper chat, find its toolkit id with discover_toolkits and pass it to enable_toolkit. On an MCP client or the CLI, tell the user which integration to connect in Hyper.

Tool surface

ToolPurpose
meta_ad_library_ads_searchSearch the Meta Ads Library by keyword. Returns compact results (title, body, CTA, link, page name, dates, platforms). Max 40 per call.
meta_ad_library_ads_getGet full details for a specific ad. Requires both ad_archive_id and page_id — both come from meta_ad_library_ads_search results.
meta_ad_library_ads_search_enrichedSearch + enrich each result with page contact info (email, phone, website). Slower (multiple API calls per result). Max 20 per call.
meta_ad_library_pages_searchSearch Facebook pages by category + location (not by keyword). Useful for building a lead list from a vertical.
meta_ad_library_pages_scrapeScrape detailed data from specific Facebook page URLs.

Critical rules

  1. Public-only data. The Meta Ads Library is public. Don't attempt to bypass any access control or scrape private content.
  2. Count limits differ between tools. meta_ad_library_ads_search allows count up to 40. meta_ad_library_ads_search_enriched caps at 20 — exceeding this returns an error.
  3. `meta_ad_library_ads_get` needs two IDs. Both ad_archive_id and page_id are required. Both are returned in every meta_ad_library_ads_search result row — pass them through together.
  4. 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 meta_ad_library_ads_search.
  5. Apify-backed tools fail intermittently. Expect occasional "fetch failed" responses. Retry once after a short delay before reporting the source as missing.
  6. 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.

Workflow

Phase 1 — Define the query

Before running anything, agree on:

  1. The search query — keyword(s) competitors would target. Examples: "meal kit delivery", "AI marketing tools", "skincare for sensitive skin".
  2. Country — ISO code (e.g. "US", "GB", "AU"). Default to "ALL" only if the user explicitly wants global.
  3. Active vs all — active_status="active" is usually what you want. Inactive ads are historical and noisier.
  4. 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").
  5. The job — what is this for?
  • Creative trend report → use meta_ad_library_ads_search, summarize patterns across hooks, CTAs, formats.
  • Top advertiser snapshot → use meta_ad_library_ads_search, group by page_name.
  • Lead list → use meta_ad_library_ads_search_enriched, filter for rows with contact_email or contact_website.

Phase 2 — Pull the ads

meta_ad_library_ads_search(
    query="meal kit delivery",
    country="US",
    active_status="active",
    count=40,                # max for this tool
    period="last30d"
)

Each 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.

For more than 40 ads, paginate by re-calling with offset=40, offset=80, etc.

For lead-gen with contact info:

meta_ad_library_ads_search_enriched(
    query="meal kit delivery",
    country="US",
    active_status="active",
    count=20,                # max for the enriched tool
    scrape_websites=True,
    filter_spam=False
)

Enriched rows add: contact_email, contact_phone, contact_website, page_followers, page_rating, address, business hours.

Phase 3 — Get full creative for the most interesting ads (optional)

meta_ad_library_ads_search returns truncated bodies for some ads. To get the complete creative — including video URLs and images — call meta_ad_library_ads_get on the specific ads worth a deeper look:

meta_ad_library_ads_get(
    ad_archive_id="559220927273823",      # from search results
    page_id="328127803978438"             # from search results
)

Both args come from the same row in meta_ad_library_ads_search. Do this for the top 3–5 ads, not all 40 — each detail call is a separate Apify run.

Phase 4 — Surface the intelligence

Present the findings inline in chat. Pick the format that matches the user's job from Phase 1.

Top advertisers (group by page):

PageActive adsCategoriesNotable angle
Brand A12Restaurant, Meal Kit"Skip the grocery store" hook in 8/12 ads
Brand B7Software, SubscriptionHeavy on UGC video, "$1 first week" offer

Common CTAs and hooks:

PatternCountExamples
Sign up CTA18…
Shop now CTA12…
Price-anchor opener ("From $X/week")9…
Founder-story opener4…

Recently launched ads (last 7 days):

PageStartedCTAHookLibrary URL
Brand A2026-04-28Sign up"Skip the grocery run this week"<adlibraryurl>

Lead list (enriched only):

PageEmailWebsiteFollowersActive ads
Brand Ahello@a.coma.com12K7

Phase 5 — Recurring monitoring (optional)

If the user wants ongoing tracking:

  1. Save the query, country, and active_status settings.
  2. Re-run weekly with period="last7d".
  3. Brief becomes a delta report — new ads since the last run, advertisers that changed posting cadence, CTA / offer shifts.

This is when `competitor-intel` becomes the better skill — it handles multi-source diffing across many surfaces, not just Meta ads.

Output standards

  • Always cite the `ad_library_url` for any specific ad referenced in the brief — the user can click through to verify.
  • Aggregate before quoting. Don't paste raw ad bodies; extract the pattern and quote 1–2 representative examples.
  • Mark interpretation explicitly. "Observation: 8 of 10 top advertisers use a 'first week free' offer. Possible interpretation: …".
  • Note the time window. Every brief should state the search query, country, and date range it was generated from.
同じリポジトリから

関連する Skills

すべての Skills
hyperfx-ai
コミュニティ

blog-generation

Generate one excellent, on-brand blog post per run for any business, built to rank on Google and get cited by AI search (ChatGPT, Claude, Perplexity, AI Overviews). A stateful engine: reads a brand strategy doc, picks a fresh topic (never repeats), researches, writes in the brand's voice, and logs the post back. Use when the user wants to write a blog post, run a daily or recurring blog task, or generate SEO / AEO / blog content. For keyword data and audits, defer to seo-research.

1時間の導入数
1
GitHub Stars
91
更新日
9月26日
hyperfx-ai
コミュニティ

reddit-ads

Plan and create Reddit Ads campaigns end-to-end via the Hyper MCP — campaign, ad group, ad build order with subreddit / interest / geo targeting, promoted posts, custom and saved audiences, Reddit pixel conversion tracking, and reporting, with micro-currency budgets. Use when the user wants to launch Reddit ads, promote a Reddit post, target subreddits, set up a Reddit pixel, or pull Reddit ad reports. Also triggers on reddit campaign, reddit ppc, or reddit ads manager.

1時間の導入数
1
GitHub Stars
91
更新日
9月26日
hyperfx-ai
コミュニティ

ad-creative-generation

Generate on-brand ad creatives — visuals + copy — for Google, Meta (Facebook / Instagram), and other paid platforms via the Hyper MCP. Extracts brand identity from a website, writes ad copy variants, and produces brand-consistent images using reference-based image generation. Use when the user asks for ad creative, ad copy variants, RSA headlines, Meta ad creative, display ads, carousel ads, or A/B test variants.

1時間の導入数
1
GitHub Stars
83
更新日
8月25日
hyperfx-ai
コミュニティ

amazon-ads

Plan and create Amazon Sponsored Products campaigns end-to-end via the Hyper MCP. Use when the user wants to launch Amazon Ads, set up Sponsored Products, manage keyword targeting and bids, configure ASIN or category product targeting, add negative keywords, automate budget rules, analyze ACoS / ROAS, or generate Sponsored Products reports. Also triggers on amazon ppc, amazon campaign, amazon keywords, or amazon report.

1時間の導入数
1
GitHub Stars
83
更新日
8月25日