> An installable agent skill for AI Content Drop. Machine-readable copy: > https://aicontentdrop.com/skills/competitor-ad-research/SKILL.md. > Ships with the aicontentdrop package, and is listed in > /skills/index.json.
From competitor ads to a brief you can shoot
The research tools are search_competitor_ads, save_competitor_ad, list_saved_ads, get_saved_ad, decode_ad and ad_to_canvas_card. Every one needs a sign-in, because saved ads are account data. They appear on tools/list where the board surface is enabled; if they are absent, say so and stop.
Only decode_ad charges credits, and only after a quote.
1. Search
search_competitor_ads with a keyword (a product, a category or a competitor), platform (meta, the default, or tiktok), sort (impressions ranks by reach, recent by start date) and limit. Each row carries the advertiser, copy, hook, call to action, media and how long the ad has run. An ad that has run for months is usually one that pays for itself; say so when you rank them.
When live data is not available the rows are samples: the result says demo: true with a note. Tell the person the results are samples and do not describe them as real ads, rank them, or build a brief on them.
2. Keep the ones worth studying
save_competitor_ad with one row from the search, copied as returned. Saving the same ad twice returns the saved one. list_saved_ads shows what the account has kept and which ads already carry a decode; get_saved_ad reads one in full with its stored decode, and never runs a new one.
3. Decode, with a quote first
A decode turns an ad into its formula: hook, script, scenes, audio, call to action and style, plus a recreation prompt ready for generation.
estimate_ad_costwithkind: "decode". It returns a flat price and a- Ask once, with the number: "Decoding this ad uses 3 credits, charged only
decode_adwith thead_idand thequote_id.
quote_id valid for 15 minutes.
if the analysis succeeds. Go ahead?" Read the figure from the quote.
An ad decoded before returns its stored decode with cached: true and charges nothing, so check get_saved_ad first. A retry with the same quote_id returns the first result (replayed: true), never a second charge.
4. Put it on a board, then remake it
ad_to_canvas_card with the ad_id and a canvas_id (from list_canvases or create_canvas) places the ad on the board as a media card, with the decoded brief attached when it has one. From there:
- one finished ad in the same formula: the studio tools (skill
- several variations: generation cards on the same board (skill
- the whole job handed over: a drop, where the account has one (skill
marketing-studio-ad), with the decode's hook and structure in the brief and the person's own product and brand, never the competitor's;
canvas-board);
video-agent).
Remake the formula, not the ad: no competitor footage, logo, product, script lines or on-screen people in the new version.
5. Refusals
| Refusal | What it means | What to do |
|---|---|---|
QUOTE_REQUIRED / QUOTE_EXPIRED / QUOTE_MISMATCH |
No decode quote, an old one, or one for another kind | estimate_ad_cost with kind: "decode" again |
NOT_FOUND |
No saved ad or board with that id | list_saved_ads or list_canvases |
INSUFFICIENT_CREDITS |
The balance is below the quote | Say the number; nothing was charged |
ENTITLEMENT_REQUIRED |
The account cannot run this on its current plan | Give the info_url it carries (https://aicontentdrop.com/plans) and nothing else about plans |
RATE_LIMITED / UPSTREAM_TEMPORARY |
Too many calls, or the source is briefly unavailable | Wait retry_after_seconds and retry the same call |
What to hand back
The ads you ranked with advertiser, hook and run time; for each decoded ad its formula in a few lines and the credits used; and the board link, if you placed them on one.
---
Install the plugin: https://aicontentdrop.com/plugin · All skills: https://aicontentdrop.com/skills