Skip to content

cgallic/kai-cmo-harness / harness/skills-v2/kai-ad-library-scan

kai-ad-library-scan

Verified

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

FileKindSize
SKILL.mdskill md6.3 KB
---
name: kai-ad-library-scan
description: Find 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/`, and `scripts/` 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 a `knowledge/` 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 referenced `scripts/` 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.md` states the category sentence, searches, countries, relevance regex, spend ceiling, and what each step dropped and charged.
- `report.md` and `patterns.json` come from `survival_report` at the default thresholds, with off-category ads removed.
- `handcheck.md` shows 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.md` comes from `score_briefs` with 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-campaign` and 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 as `maxTotalChargeUsd`) and fits under `APIFY_MONTHLY_CAP_USD` in 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-scrapecreators` cost 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-untrusted` was used and why.
- **Relevance before measurement.** Political ads dropped, `--require` regex applied, and `--category` passed to `tag_ads` so Jev's `in_category` removes 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.md` and `harness/references/advertising-compliance.md` are 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`; `--model` pinned, default `jev-1.14`; `--mock` offline).
- 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 JSONL `id, hook, body, format, offer`.
- Brand file: voice, audience, and words or claims to avoid, from `MARKETING.md` or 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).
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 implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall