cgallic/kai-cmo-harness / harness/skills-v2/kai-ad-library-scan
kai-ad-library-scan
VerifiedFind which ad patterns keep getting paid for in a category. Scans the Meta Ad Library (Apify or ScrapeCreators, under a spend cap), computes days running in code, has Jev tag each ad's hook, offer, angle, proof and format, drops off-category ads, measures advertiser-weighted 60+ day survival per tag, then scores LLM-written briefs against the surviving patterns and the brand file. Read-only. Use when "ad library", "competitor ads", "what ads are working in my category", "long-running ads", "winning ad patterns", "swipe file", "which hooks work", "score these ad briefs", or before writing a paid creative bench.
/kai-ad-library-scan — What a Category Pays to Keep Running
Kai root note:
knowledge/,harness/, andscripts/paths in this skill live in the Kai install, not the user's project. Resolve them against the first ancestor directory of this SKILL.md that contains aknowledge/folder (the Kai plugin root,~/.claude/kai, or the kai-cmo-harness repo).MARKETING.md,memory/, and any output files live in the current project. If a referencedscripts/command is not available in this install, say so, skip it, and continue with the file-based guidance — never fabricate its output.
Objective
The owner knows which hooks, offers, angles, proof types and formats survive 60+ days in their category (advertiser-weighted, trusted cells only), which ones die early, and which of their candidate briefs use the survivors while fitting the brand. They end with a survival report, a hand-checked tag set, a ranked brief list with a computed score and reasons per brief, and the exact spend.
Doctrine: knowledge/playbooks/ad-library-survival-scan.md. Output: workspace/ad-library-scan/<category-slug>/<YYYY-MM-DD>/.
Done when
Work type internal-research (E2/C2/O0) for an internal scan; audit-report (E3/C4/O1) when delivered to a client as a competitor section, with every number citing the scan files. Briefs that ship are judged under paid-ad-campaign (harness/eco-floors.yaml).
RUN.mdstates the category sentence, searches, countries, relevance regex, spend ceiling, and what each step dropped and charged.report.mdandpatterns.jsoncome fromsurvival_reportat the default thresholds, with off-category ads removed.handcheck.mdshows 20 random in-category ads checked label by label: at least 85% of confident labels right and no more than 2/20 off-category. Below that, the regex or category sentence is fixed and the ads re-tagged before the report is used.ranked.mdcomes fromscore_briefswith the brand file, includes at least one negative control, and every "check by hand" brief has been checked by a human. The top briefs pass/kai-gate(10/16 Four U's for ads).
Constraints
- Read-only. Public ad archives only. No ad account is created, edited, paused or uploaded to. Production goes through
/kai-ad-campaignand its approval gate, with the playbook's pre-flight yes/no checks run before upload. - Spend cap. Every Apify run passes
--max-usd(sent to Apify asmaxTotalChargeUsd) and fits underAPIFY_MONTHLY_CAP_USDin the fail-closed ledger (python -m scripts.ads.ad_library.budget status). The owner hears the ceiling before the first paid run. Imports via--from-apify/--from-scrapecreatorscost nothing extra. - Counts in code, features from Jev. Days running, advertiser weights, lifts and the 0–100 brief score come from
scripts/ads/ad_library/. Jev answers only visible-feature questions through the harness client (scripts/autonomy/decision_log.py); unsure answers are excluded, never guessed. Never hand-estimate a lift. - Thresholds hold. Survivor 60+ days, short = stopped under 21 days, active-and-younger-than-60 left out, trusted cell = 10+ ads from 3+ advertisers. Untrusted cells are reported as hypotheses and are not used to score unless the report says
--include-untrustedwas used and why. - Relevance before measurement. Political ads dropped,
--requireregex applied, and--categorypassed totag_adsso Jev'sin_categoryremoves keyword bleed before survival is measured. - Brand safety fails closed. An unsure "uses something to avoid" answer earns no brand points and needs a human check.
- No fabricated proof. A surviving proof pattern (reviews, testimonials, experts, user counts) is used only with proof on record; otherwise it is a data gap.
- Policy before copy.
harness/references/meta-ads-rules.mdandharness/references/advertising-compliance.mdare loaded before any brief is written.
Context
- Collect:
python -m scripts.ads.ad_library.collect_ads --apify-run --search-terms "<term>" --countries US --max 500 --max-usd 0.50 --require "<regex>" --out <dir>/raw/<term>.jsonl, or--from-apify <export>/--from-scrapecreators <file>, or--meta-api(EU-delivered commercial ads only,META_ACCESS_TOKEN). - Tag:
python -m scripts.ads.ad_library.tag_ads --in <ads.jsonl> --out <tagged.jsonl> --category "<category sentence>"(OPENROUTER_API_KEY;--modelpinned, defaultjev-1.14;--mockoffline). - Survival:
python -m scripts.ads.ad_library.survival_report --in <tagged.jsonl> --report <report.md> --patterns <patterns.json>. - Score:
python -m scripts.ads.ad_library.score_briefs --briefs <briefs.jsonl> --patterns <patterns.json> --brand <brand.txt> --out <ranked.jsonl> --report <ranked.md>. Briefs are JSONLid, hook, body, format, offer. - Brand file: voice, audience, and words or claims to avoid, from
MARKETING.mdor the owner. - Where the results go next:
knowledge/playbooks/combinatorial-creative-bench.md(angle and format axes),knowledge/playbooks/meta-creative-testing-decision-framework.md(the test still decides),knowledge/playbooks/ad-creative-best-practices.md(copy). - Worked example and failure modes (template ads, keyword bleed, political ads): the playbook.
Escalate when
- The first paid run would exceed the remaining monthly cap, or the owner has not agreed a ceiling.
- No cell is trusted after a full collection: the category may be too thin for this method.
- The hand check stays below 85% agreement or above 2/20 off-category after one fix.
- The strongest surviving patterns need proof the brand does not have.
- A top brief carries a claim the platform policy reference flags (income, health, before/after, personal attributes).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |