Ad Library Skills for Agentic AI

What are agent skills?

An agent skill is a folder of plain markdown that teaches an AI agent how to do a job. The format, a SKILL.md file plus optional reference docs, is an open standard introduced by Anthropic and now read by Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot and VS Code, Cursor, and 30+ other agentic tools. When a task matches the skill's description, the agent loads it and follows it like an operating manual.

The adlibrary-research skill applies that standard to ad intelligence. Install it once and your agent knows how to research competitor ads across Facebook, Instagram, Google, and LinkedIn through the AdLibrary API: which endpoints exist, what each call costs in credits, which free probes to run before spending anything, and how to read an ad object. It is markdown and curl. There is nothing to host.

Install the skill in one command

curl -fsSL https://adlibrary.com/skill/install.sh | sh

The installer drops the skill into your project's .claude/skills directory if one exists, otherwise into ~/.claude/skills. It is POSIX sh, prints exactly what it does, and touches nothing outside the skills directory. Read it before piping if you prefer.

Then connect it to your account:

1. Create an API key. With an active Business subscription, generate a key at adlibrary.com/api-access. It starts with adl_ and is shown once.
2. Export it so the skill can authenticate:

export ADLIBRARY_API_KEY=adl_your_key_here

Add that line to your shell profile to make it permanent.

1. Ask your agent something. "What ads is Gymshark running?" or "find winning video ads for protein powder in the US". The skill triggers on the task, runs the right calls, and reports back with the data and the credits it spent.

No MCP server, nothing to run

Most "connect your agent to ad data" setups mean standing up an MCP server: a Node process, a config JSON per tool, a restart every time something changes. We wrote a Meta Ads MCP setup guide, so this is not a dig at MCP. It is a different trade.

A skill has no moving parts. The agent reads the markdown, then calls the documented REST endpoints directly with curl and parses the JSON with jq. That buys you three things:

• It works in every agent that reads skills. One install covers Claude Code, Codex, Gemini CLI, Copilot, Cursor, and whatever ships skill support next month. No per-tool adapter.
• Nothing to keep alive. No server process, no port, no version drift between the server and the API.
• The agent sees the whole manual. Credit costs, rate limits, free probes, error semantics: it reads the same reference docs a developer would, so it can plan a research session instead of calling tools blind.

The data layer underneath is the same API access the rest of the platform runs on.

What the skill can do

The skill ships a decision tree with four research workflows. Each one front-loads a free probe so your agent never pays to discover something a 0-credit call would have told it.

Market sizing ("how many ads run on this keyword?") is free outright: the count probe returns the total, and you can slice it by format, recency, and country without spending a credit.

Spy on one competitor's ads

A brand name is not an advertiser ID, so the skill resolves it first, for free. One call returns the brand's Meta page ID, Google advertiser ID, and LinkedIn company ID, with a best-match confidence score.

With the IDs in hand, the agent either runs a single 1-credit Meta search scoped to that page, or saves the brand and pulls its ads from all three platforms in one curate call. Either way you get the creatives, the copy, the call-to-action, runtime, and engagement, as JSON your agent can reason over.

This is the workflow behind competitor ad research and the place most people start. Ask the question, get the portfolio.

Find winning creatives in a niche

For keyword research the skill leans on the strongest signal in ad intelligence: runtime. Advertisers kill what does not convert, so the longest-running creatives in a niche are the closest thing to a public list of what works.

The agent probes the keyword count first (free). If the niche is empty, it changes the keyword instead of paying. Then it runs a search sorted by days live, filtered to video where most spend goes, and tunes from there with the skill's filter playbook: geo, language, format, aspect ratio, engagement thresholds, e-commerce platform.

Every search costs 1 credit, and each page is a fresh search. The skill knows this and budgets accordingly instead of paginating blindly. Results land in the same unified ad search shape the app uses.

Scan a brand for its actual winners

The winners scan is the most expensive call in the API, and the skill treats it that way. Before committing, it runs a free page-scoping probe that returns the advertiser's ad count, category, follower numbers, and verification status, so you confirm it is the right brand with ads worth scanning.

The scan itself scores the advertiser's whole portfolio and returns tiers: high_confidence_winner, winner, or loser, each with a 0 to 1 composite score, plain-language reasons ("runtime 89 days, top 10% of this advertiser"), and a dna_diff that spells out what the winning variant does differently from losing variants on the same landing page.

It costs a flat 10 credits, deducted upfront and auto-refunded if the scan finds no ads or fails upstream. One scan runs at a time per user. For the analysis side, the same engine powers AI ad enrichment in the app, and we covered the agent-side workflow in Claude Code for ad creative analysis.

Track a brand across Meta, Google, and LinkedIn

For brands you watch repeatedly, the skill saves the advertiser once, with all of its platform IDs, then curates it: one call that fans out to Meta, Google, and LinkedIn in parallel, dedupes the ads, and returns per-platform results with cursors.

The first curate call in a session costs 1 credit. Continuations within the next 30 minutes are free, so the agent paginates the whole portfolio inside the window instead of paying per page. Saving, listing, and updating advertisers costs nothing.

This is the backbone of automated competitor ad monitoring: a scheduled agent that curates your watchlist every morning and flags what changed, across every major platform at once.

The credit economy: probe free, pay once

Every paid operation costs credits, and the skill's core discipline is simple: run the matching free probe before any paid call.

Two guarantees keep spend honest. A failed winners scan refunds its 10 credits automatically, so an empty result never bills. And an ad you have already paid to enrich is free every time after, so re-analysis costs nothing.

The skill reads your remaining balance off every response and reports it, so you always know where the budget stands. Full costs live in the skill's own reference/credit-costs.md, which your agent reads before it spends.

What to ask your agent

The skill triggers on plain research questions. No syntax to learn, no endpoints to memorize:

• "What ads is Gymshark running in the US?"
• "Find winning video ads for protein powder, last 90 days"
• "Resolve Glossier to its Meta, Google, and LinkedIn advertiser IDs"
• "Scan Ridge Wallet for winners and tell me what the top creative does differently"
• "How big is the ad market for cold plunge tubs?"
• "Track Loop Earplugs across all platforms and save them for next week"
• "Pull the detail on this ad and break down its hook"

Behind each question the agent picks the workflow, runs the free probe, makes the paid call only when it is justified, and quotes the credits it used. For more patterns like these, we keep a Claude Code prompt library for marketing.

Honest constraints

The skill documents its own limits, and so do we:

• API keys are Business tier only. There is no free or lower-tier key. The skill is free markdown; the data behind it is a paid product on the Business plan.
• E-commerce ads only, for now. API keys are pinned to the e-commerce vertical. Gaming and app-install ads are not searchable through the API today, so the skill will not promise them. It pairs naturally with e-commerce product research.
• 10 requests per minute on search. The skill backs off on a 429 and honors the Retry-After header, but a high-volume pipeline should budget around the ceiling.
• One winners scan at a time. Scans serialize per user; a second concurrent scan waits 30 seconds.
• LinkedIn returns at most 25 results per response. A hard upstream limit, not ours.

If any of those is a dealbreaker, the API landing page covers the full parameter and limit reference so you can judge before paying.

Where it fits in an agentic stack

Agent skills are the thin end of a bigger shift: research that used to be a person with twelve browser tabs is becoming a scheduled agent with an API key. We have written about that shift from several angles, and the skill is the shortest path into it.

• Media buyers wire the skill into a morning routine: curate the watchlist, diff against yesterday, flag new concepts. See Claude Code agents for media buyers and the media buyer daily workflow.
• Creative strategists use the winners scan as the research half of the creative strategist workflow: find the proven concept, read its dna_diff, brief the rebuild.
• Agencies and ops teams chain it with other skills into full pipelines. The deeper builds are in Claude Code + adlibrary API workflows, agentic marketing workflows with Claude Code, and building agentic marketing workflows that ship.
• New to agentic tools? Start with Claude Code for marketers, then come back for the competitor research automation patterns this skill packages up.

The common thread: ad data for AI agents only works when the agent knows the cost model. That knowledge is exactly what the skill encodes.

Frequently asked questions

What is an agent skill? An agent skill is a folder of plain markdown, anchored by a SKILL.md file, that teaches an AI agent how to perform a task. The format is an open standard introduced by Anthropic and supported by Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot, Cursor, and 30+ other agentic tools.

Which AI agents support the adlibrary-research skill? Any tool that reads the SKILL.md standard: Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot and VS Code, Cursor, and dozens more. The skill is plain markdown plus curl commands, so it needs no per-tool adapter or plugin.

How do I install the ad library skill? Run curl -fsSL https://adlibrary.com/skill/install.sh | sh. It installs into your project’s .claude/skills directory if one exists, otherwise into ~/.claude/skills. Then create an API key at adlibrary.com/api-access and export it as ADLIBRARY_API_KEY.

Do I need an MCP server to use it? No. The skill is markdown the agent reads; the agent then calls the AdLibrary REST API directly with curl. There is no server to install, configure, or keep running, and it works identically in every skill-compatible tool.

What API key does the skill need? A Business-tier AdLibrary API key, format adl_..., exported as the env var ADLIBRARY_API_KEY. Keys are created at adlibrary.com/api-access with an active Business subscription. There is no free or lower-tier key.

What can the skill research? Four workflows: spy on a competitor’s ads, discover winning creatives by keyword, scan an advertiser’s portfolio for scored winners, and track a brand across Meta, Google, and LinkedIn. It also sizes ad markets by keyword for free and deep-analyzes single ads.

How much do the API calls cost? Searches cost 1 credit per call, curate sessions 1 credit per 30 minutes, and a winners scan a flat 10 credits. Brand resolution, keyword counts, page scoping, and single-ad detail are free probes the skill always runs first.

Does the winners scan refund credits if it fails? Yes. The 10 credits are deducted upfront and automatically refunded if the scan finds no ads or fails upstream before producing results. The fee only sticks once real results stream back.

Can the skill search gaming or app ads? Not currently. API keys are pinned to the e-commerce vertical, so the API returns e-commerce ads only. The skill documents this and will not promise gaming or app-install results.

What are the rate limits? Search is limited to 10 requests per minute per key; ad detail allows 60 per minute and the free probes 30 per minute. Winners scans run one at a time per user. The skill backs off automatically on a 429.

Is the skill itself free? Yes. The skill is open markdown you can read before installing, and the installer touches nothing outside your skills directory. What costs money is the API usage behind it, billed in credits on the Business plan.

Does it work with Claude Code specifically? Yes, Claude Code is the primary target: it picks the skill up from .claude/skills automatically and triggers it on research questions like "what ads is Gymshark running?". The same folder works in Codex, Gemini CLI, Copilot, and Cursor.