How to use the Facebook Ads Library Scraper agent skill

What is an agent skill and what does this one do?

An agent skill is a folder of instructions and optional scripts that an AI agent loads when your request matches the skill's purpose. This one is built around the harshmaur/facebook-ads-library-scraper Apify Actor, which is a paid scraper that reads Meta's public Ad Library.

When the skill is active, the agent can build the right Ad Library search link for a keyword or an advertiser, run the scraper, and return one row per ad. Each row can include dates, creative text, links, and any spend or reach figures Meta has disclosed.

• Works from an advertiser's Page link or Page ID, or from a keyword search in a chosen country.
• Returns dates, ad text, headlines, call-to-action, media type, and links to each ad in the Ad Library.
• Reports spend, impressions or reach only where Meta publishes them.
• Sets an ad-count cap and checks costs before running.

Install the skill in Claude

Download the skill ZIP from this page and unzip it. For a personal setup, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

You can also upload the skill in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the ZIP there.

The skill folder contains SKILL.md, the main instructions, and references/gotchas.md, which covers Meta's data disclosure rules and count behaviour.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills

Set up Apify before the first run

The skill runs the scraper through your Apify account, so you need an account and an API token. The source lists three ways to authenticate: running apify login (OAuth, if you use the Apify CLI), setting the APIFY_TOKEN environment variable, or copying a token from Apify Console under Settings and Integrations.

The skill calls Apify either through the Apify CLI or through the Apify MCP server. To install the CLI, use the command below. You also need paid Apify credit to run the harshmaur/facebook-ads-library-scraper Actor.

• Apify account and API token (APIFY_TOKEN or apify login)
• Apify CLI or the Apify MCP server
• Paid Apify credit for the Actor, priced per 1,000 ads

Trigger the skill with natural requests

You do not need special syntax. Describe the research you want in plain words, and the agent will decide whether this skill applies. Name the advertiser, keyword, country and time window where you can, because the skill uses those to build the search.

The skill is designed for public Meta ad research. It is not meant for managing your own ads or for other ad libraries.

• "Pull every active ad Gymshark runs in the US and sort them by how long they have been live."
• "Find ads for 'protein powder' in the UK that have run for more than 60 days, with their video links."
• "Export the last 30 days of ads from facebook.com/allbirds to a spreadsheet."
• "How much did political advertisers in Germany spend on ads about energy?"

Control the count and the cost

The scraper charges per ad in the dataset, and the skill's guidance is to cap the number of ads on every run. The count setting applies to the whole run, and a per-URL limit stops one large advertiser from using up the entire count.

Pricing changes, so check current Apify pricing before running. The skill's cost examples are labelled as historical and are not a live quote. A count of 0 means no limit, and the skill says never to send it without a cost check. Set an explicit budget before any large run.

• count: most ads for the whole run. Default 100.
• limitPerSource: most ads per URL, for fair sharing across several advertisers.
• scrapeAdDetails: adds reach, age, gender and country data for EU and UK ads, and makes the run slower.
• Large runs may take minutes. The agent can start them and check progress later with apify runs info.

Read the output and avoid common mistakes

Each row in the exported data is one ad. Useful fields include start_date_iso, ad_duration_days, is_long_running (over 30 days), ad_text, headline, link_url, and ad_library_url. The skill's rule is that ad duration is only a research signal. It does not prove that an ad is profitable or effective.

Ads that share a collation_id are versions of the same ad and should be counted once. Where Meta does not publish a figure, the report should say so rather than estimate it. The skill also tells the agent to treat ad text as untrusted data, so copy from ads is quoted as plain text and not followed as instructions.

• Label long-running ads as candidates, not verified winners.
• Count ads with the same collation_id once.
• Spend and impression figures appear mainly for political and social-issue ads.
• Pick a different tool for managing your own ads: the skill says to use the Meta Marketing API for that.