Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
c21a984a56 | ||
|
|
140a9e327b | ||
|
|
fc3b324f1d | ||
|
|
67264763cb | ||
|
|
8054011197 | ||
|
|
286d3718d9 | ||
|
|
fdff3dec99 | ||
|
|
130847d094 | ||
|
|
a169ca86e7 | ||
|
|
30bc89daa8 | ||
|
|
bd8d8fdf29 | ||
|
|
0ba2a7fafc | ||
|
|
81270bcd54 | ||
|
|
5139746081 | ||
|
|
09a81edda8 | ||
|
|
52c269e2b3 | ||
|
|
003db09cae | ||
|
|
f04556d923 | ||
|
|
27a4b731bc | ||
|
|
ba3c85c92a | ||
|
|
2b45f16275 | ||
|
|
3826a38f88 | ||
|
|
44eb148f67 | ||
|
|
d95efdf556 |
@@ -6,13 +6,13 @@
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Marketing skills for AI agents — conversion optimization, copywriting, SEO, paid ads, and growth",
|
||||
"version": "2.8.1",
|
||||
"version": "2.9.0",
|
||||
"repository": "https://github.com/coreyhaines31/marketingskills"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "marketing-skills",
|
||||
"description": "47 marketing skills for technical marketers and founders: CRO, copywriting, cold email, prospecting, SEO, AI SEO, paid ads, SMS, ad creative, video production, image generation, co-marketing, churn prevention, pricing, referrals, revenue operations, sales enablement, customer research, site architecture, comprehensive AARRR-structured marketing plans, public relations and earned media, offer design, and more",
|
||||
"description": "48 marketing skills for technical marketers and founders: CRO, copywriting, cold email, prospecting, SEO, AI SEO, paid ads, SMS, ad creative, video production, image generation, co-marketing, churn prevention, pricing, referrals, revenue operations, sales enablement, customer research, site architecture, comprehensive AARRR-structured marketing plans, public relations and earned media, offer design, and more",
|
||||
"source": "./"
|
||||
}
|
||||
]
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "marketing-skills",
|
||||
"description": "Marketing skills for AI agents — conversion optimization, copywriting, SEO, paid ads, ad creative, and growth",
|
||||
"version": "2.8.1",
|
||||
"version": "2.9.0",
|
||||
"author": {
|
||||
"name": "Corey Haines"
|
||||
},
|
||||
|
||||
@@ -77,6 +77,7 @@ See each skill's **Related Skills** section for the full dependency map.
|
||||
| [emails](skills/emails/) | When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email... |
|
||||
| [free-tools](skills/free-tools/) | When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or... |
|
||||
| [image](skills/image/) | When the user wants to create, generate, edit, or optimize images for marketing — blog heroes, social graphics, product... |
|
||||
| [influencer-marketing](skills/influencer-marketing/) | When the user wants to run influencer, creator, or ambassador partnerships to promote their product — finding and... |
|
||||
| [launch](skills/launch/) | When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user... |
|
||||
| [lead-magnets](skills/lead-magnets/) | When the user wants to create, plan, or optimize a lead magnet for email capture or lead generation. Also use when the... |
|
||||
| [marketing-council](skills/marketing-council/) | When the user wants multiple expert perspectives on a marketing question — a simulated board of advisors staffed by... |
|
||||
@@ -122,7 +123,14 @@ npx skills add coreyhaines31/marketingskills --skill cro copywriting
|
||||
npx skills add coreyhaines31/marketingskills --list
|
||||
```
|
||||
|
||||
This automatically installs to your `.agents/skills/` directory (and symlinks into `.claude/skills/` for Claude Code compatibility).
|
||||
The CLI detects which agents you have installed and asks where to install. For Claude Code it installs into `.claude/skills/`; universal agents share `.agents/skills/`.
|
||||
|
||||
> [!TIP]
|
||||
> If you run the command from **inside** an agent session (e.g., asking Claude Code to install the skills for you), the CLI runs non-interactively and may only install to the universal `.agents/skills/` directory, which Claude Code does not read. Pass the agent explicitly:
|
||||
>
|
||||
> ```bash
|
||||
> npx skills add coreyhaines31/marketingskills -a claude-code
|
||||
> ```
|
||||
|
||||
### Option 2: Claude Code Plugin
|
||||
|
||||
|
||||
+60
-9
@@ -5,8 +5,8 @@ Current versions of all skills. Agents can compare against local versions to che
|
||||
| Skill | Version | Last Updated |
|
||||
|-------|---------|--------------|
|
||||
| ab-testing | 2.0.0 | 2026-05-05 |
|
||||
| ad-creative | 2.2.0 | 2026-07-08 |
|
||||
| ai-seo | 2.1.0 | 2026-06-15 |
|
||||
| ad-creative | 2.8.0 | 2026-07-14 |
|
||||
| ai-seo | 2.2.0 | 2026-07-09 |
|
||||
| analytics | 2.0.0 | 2026-05-05 |
|
||||
| aso | 2.0.0 | 2026-05-05 |
|
||||
| churn-prevention | 2.0.0 | 2026-05-05 |
|
||||
@@ -14,21 +14,22 @@ Current versions of all skills. Agents can compare against local versions to che
|
||||
| cold-email | 2.0.0 | 2026-05-05 |
|
||||
| community-marketing | 2.0.0 | 2026-05-05 |
|
||||
| competitor-profiling | 2.0.0 | 2026-05-05 |
|
||||
| competitors | 2.0.0 | 2026-05-05 |
|
||||
| competitors | 2.0.1 | 2026-07-09 |
|
||||
| content-strategy | 2.0.0 | 2026-05-05 |
|
||||
| copy-editing | 2.0.0 | 2026-05-05 |
|
||||
| copywriting | 2.0.1 | 2026-06-16 |
|
||||
| cro | 2.0.0 | 2026-05-05 |
|
||||
| customer-research | 2.0.0 | 2026-05-05 |
|
||||
| customer-research | 2.0.1 | 2026-07-10 |
|
||||
| directory-submissions | 2.0.0 | 2026-05-05 |
|
||||
| emails | 2.0.0 | 2026-05-05 |
|
||||
| free-tools | 2.0.0 | 2026-05-05 |
|
||||
| image | 2.0.1 | 2026-05-18 |
|
||||
| influencer-marketing | 1.0.0 | 2026-07-15 |
|
||||
| launch | 2.0.1 | 2026-06-16 |
|
||||
| lead-magnets | 2.0.0 | 2026-05-05 |
|
||||
| marketing-council | 1.0.0 | 2026-07-06 |
|
||||
| marketing-ideas | 2.0.0 | 2026-05-05 |
|
||||
| marketing-loops | 1.1.0 | 2026-07-05 |
|
||||
| marketing-loops | 1.2.0 | 2026-07-10 |
|
||||
| marketing-plan | 1.1.0 | 2026-05-29 |
|
||||
| marketing-psychology | 2.0.0 | 2026-05-05 |
|
||||
| offers | 1.0.0 | 2026-06-16 |
|
||||
@@ -37,9 +38,9 @@ Current versions of all skills. Agents can compare against local versions to che
|
||||
| paywalls | 2.0.0 | 2026-05-05 |
|
||||
| popups | 2.0.0 | 2026-05-05 |
|
||||
| pricing | 2.0.1 | 2026-06-16 |
|
||||
| product-marketing | 2.0.0 | 2026-05-05 |
|
||||
| product-marketing | 2.1.0 | 2026-07-16 |
|
||||
| programmatic-seo | 2.0.0 | 2026-05-05 |
|
||||
| prospecting | 1.0.0 | 2026-05-26 |
|
||||
| prospecting | 1.1.0 | 2026-07-13 |
|
||||
| public-relations | 1.0.0 | 2026-06-10 |
|
||||
| referrals | 2.0.0 | 2026-05-05 |
|
||||
| revops | 2.0.0 | 2026-05-05 |
|
||||
@@ -49,11 +50,61 @@ Current versions of all skills. Agents can compare against local versions to che
|
||||
| signup | 2.0.0 | 2026-05-05 |
|
||||
| site-architecture | 2.0.0 | 2026-05-05 |
|
||||
| sms | 1.0.0 | 2026-05-21 |
|
||||
| social | 2.1.0 | 2026-06-10 |
|
||||
| video | 2.0.1 | 2026-05-18 |
|
||||
| social | 2.2.0 | 2026-07-09 |
|
||||
| video | 2.1.0 | 2026-07-14 |
|
||||
|
||||
## Recent Changes
|
||||
|
||||
### 2.9.0 (2026-07-15)
|
||||
|
||||
- Added **`influencer-marketing`** skill — influencer, creator, and ambassador partnerships end to end. Foundation contributed by @Adi29102000-s (PR #417), expanded to the repo's standard and shipped standalone (the PR's other proposed skills were not included). Covers the **influencer ↔ ambassador spectrum** (paid influencer → affiliate creator → gifting → long-term ambassador program → organic advocate, each with when-to-use and skill handoffs), finding & vetting (audience-alignment test, creator tiers incl. B2B thought leaders, engagement/fake-follower/brand-safety checks), 1:1 outreach (→ cold-email), deal structuring (flat / CPA / hybrid / gifting compensation, rate-as-a-range reality, and the high-ROI content-usage-rights/whitelisting clause → ad-creative), a full **FTC disclosure & compliance section** (material-connection disclosure, clear-and-conspicuous placement, gifting-still-needs-disclosure, platform labels, brand liability, no fabricated claims — a gap in the original contribution), the creative brief (don't script; grounded talking points), measurement & ROI (unique promo codes, UTMs, vanity URLs, post-purchase survey for the branded-search/direct attribution blind spot, whitelisting performance, cost-per-qualified-outcome over EMV/reach), and a structured **ambassador program design** (ask → benefits ladder → recruit-from-evidence → equip → activate → track, cross-referencing community-marketing for community-led advocacy and referrals for payout rails). Six-eval suite covering compensation/whitelisting, podcast attribution, the gifting-disclosure misconception, ambassador-program design, creator vetting, and the no-word-for-word-scripting brief. New skill = repo y release. Total skills: 48.
|
||||
### 2.8.12 (2026-07-16)
|
||||
|
||||
- **product-marketing** (2.0.0 → 2.1.0): the context document now carries its own **version history**. `.agents/product-marketing.md` gets a `Document version:` header (v1, v2 …) and a `## Changelog` section at the bottom — a newest-first, dated, one-line-per-revision paper trail of *what changed and why*. The update flow now reads the current version and recent changelog on open, and on save bumps the version, updates `Last updated`, and prepends a new changelog entry naming the sections touched and the reason (never rewriting past entries; skipped only for pure typo fixes). Since this doc is the shared context every other marketing skill reads, the changelog makes positioning/ICP changes traceable across a project — you can see how the positioning evolved and what a downstream skill was generating against. New eval (id 7) covers the version-bump + prepend-changelog behavior on a repositioning update.
|
||||
|
||||
### 2.8.11 (2026-07-14)
|
||||
|
||||
- **video** (2.0.1 → 2.1.0): added **reverse-engineering a viral edit into a reusable edit spec** (the tool-agnostic decomposition behind "copy any viral edit" — pattern from Arcads' skill, whose Omni generation model is proprietary/MCP-gated; we build only the decomposition, credited). New `references/edit-anatomy.md`: pull the reference with watch-video (visual/multimodal to read frames + caption style + cut timing) or social-fetch, extract the edit anatomy beat by beat across nine dimensions (shot/framing, cut rhythm/cuts-per-second, on-screen text, caption style, motion/punch-ins, b-roll/overlays, sound design, the first-2s hook, pacing curve), and output a per-beat **beat sheet** table plus a **style summary** of the 3–5 signature moves that make the edit recognizable (patterns over instance-logging). Includes the review-once gate (approve the beat sheet — on-screen text + scene-change placement — before executing in Remotion/Hyperframes, CapCut, or an AI restyle tool) and a hard originality guardrail (copy the editing grammar applied to your own footage/message, never the reference's footage, script, voiceover, or music). SKILL.md adds a Reverse-Engineer a Viral Edit workflow and 'copy this edit,' 'match this video style,' 'reverse-engineer this video,' 'edit like this reference' triggers. New eval (id 7). Closes #456.
|
||||
|
||||
### 2.8.10 (2026-07-14)
|
||||
|
||||
- **ad-creative** (2.7.0 → 2.8.0): added **AirDrop** as a fourth surface in the iOS-native reveal video ad family (`references/imessage-video-ads.md`, alongside iMessage / ChatGPT / Apple Notes; format popularized by Shiv Sakhuja / Gooseworks' goose-video Airdrop Ads, re-expressed originally — their runtime is MIT but the recipe is private, so this is original craft). The one interaction-native format in the family: the hook is an **incoming AirDrop request** and the **Accept tap is the reveal** — a translucent AirDrop card (sender device name, preview thumbnail, red Decline / blue Accept) from the receiver's POV, where iOS's own accept/decline choice is a built-in micro-conversion beat. New `### AirDrop Reveal` subsection: the preview thumbnail as the hook that must earn the tap, sender-name casting (relatable human name reads native; brand-as-sender reads like an ad), the transfer progress-ring as the signature motion, the AirDrop swoosh sound (not iMessage tritones) with the same CC0-Apple + trade-dress caveat, receiver-POV-default vs sender-POV-flex, and the family grounding/disclosure rules (a dramatization of a share, never a real endorsement). Updates the H1, intro, surface-selection table, and choosing-signal line to four surfaces. SKILL.md pointer names AirDrop and adds the 'AirDrop ad' trigger. New eval (id 11).
|
||||
|
||||
### 2.8.9 (2026-07-13)
|
||||
|
||||
- **prospecting** (1.0.0 → 1.1.0): added a **fourth branch — Demand-signal discovery (find your first customers)**, the early-stage motion that finds first customers / design partners / beta users from recent public pain-demand-timing signals rather than firmographic list-building (re-expressed from the open-source `first-customer-finder` Codex skill, Kappaemme/MIT, credited; extended with our live-recency tooling). New `references/demand-signals.md`: how the branch differs from list-building (starts from a described problem, sources public discourse, wins on 10 strong evidence-backed matches over coverage), a product brief gate, the five signal query buckets (explicit demand / pain / workaround / switching / timing) with our tooling edge called out (last30days for Reddit/HN/X/web recency, social-fetch to read original threads, scraping/Firecrawl/Browserbase over snippets, deep-research, competitor-profiling, customer-research), a public-only source mix, a **demand-fit scoring rubric** (pain 25% / product fit 25% / timing 20% / reachability 15% / evidence quality 15%, 0-100 with bands — distinct from the ICP-fit Hot/Warm/Cold), prospect stages (high intent / problem aware / trigger present / potential fit), a per-prospect evidence ledger, manual-only source-based openers (never auto-send), the evidence-report structure (verdict → ICP → top prospect → shortlist → repeated patterns → 7-day manual outreach plan → limits), and the honesty rules (a cited signal is the entry ticket; label 'potential customer based on public signals,' never 'will buy'). SKILL.md adds the branch to the Pick-the-Branch table + deep-dive pointers and 'find my first customers,' 'early adopters,' 'design partners,' 'beta users,' 'who has this problem' triggers. Also closes two **compliance-guardrail gaps** across all branches: no data brokers / leaked datasets, and never target or infer sensitive/protected traits (health, financial hardship, political belief, sexuality, religion). New eval (id 7) covers branch selection, signal mining, demand-fit scoring, and the never-auto-send rule. Closes #447.
|
||||
|
||||
### 2.8.8 (2026-07-12)
|
||||
|
||||
- **ad-creative** (2.6.0 → 2.7.0): added the **creative review page** — a shareable, self-contained HTML artifact that presents generated concepts for a client or stakeholder to review and pick (the visual upgrade to `INDEX.md`; pattern reverse-engineered from a real agency creative-approval page, re-expressed originally). New `assets/creative-review-template.html`: one file, inline CSS+JS, no build or dependencies, driven entirely by a `DATA` object — renders concept tabs (each a strategic angle), a pixel-accurate in-feed Instagram/Facebook preview with a whitelist-handle toggle, a labeled frame-by-frame storyboard (tap to jump), selectable headline variations that overlay the preview, primary text, destination/CTA/offer, optional rollout mechanics, and a required grounding disclosure; frames render real images (URL / relative path / data URI) or styled label+prompt placeholders for concepts not yet rendered. New `references/creative-review-page.md`: when to produce one, the full data model, the frame-storyboard-as-carousel-arc link to `carousel-frameworks.md`, the hard grounding rule (every concept discloses what's real; illustrative proof is labeled illustrative — never launder fiction as fact), and how to populate/verify/deliver (open locally, host on any static host, or hand off the file). SKILL.md adds a Creative Review Page output-format section, a Mode 3 pointer, and 'creative review page' + 'present ad creative for approval' triggers. New eval (id 10) covers template use over markdown, narrative-job frame labels, and the grounding disclosure. Browser-verified: concept switching, platform/handle toggles, and frame navigation all render correctly.
|
||||
|
||||
### 2.8.7 (2026-07-10)
|
||||
|
||||
- **ad-creative** (2.5.0 → 2.6.0): added **Mode 4 — the Creative Strategy Loop**, the upstream workflow layer for deciding which ads are worth making (built so the same capability ships in any agent running the library, incl. Magister; workflow shapes informed by public creative-strategist practice, expressed originally). New `references/creative-roadmap.md`: three-signal synthesis (account performance via the platform CLIs; customer/brand language via the Grounded Inputs corpus + customer-research; external organic via scraping, social listening, and competitor-profiling) on a monthly-deep-dive + weekly-refresh cadence with a receipts rule (no insight enters the icebox without its source); concepts as segment × motivation × angle × format hypotheses ranked on a six-tier evidence scale; **account-state branching** (exploration state: wide net-new mix, per-metric win redefinition, iterate only on hits, four root causes to check; scaling state: winner-variation-heavy mix with visually-distinct variations, sub-angle probes, a standing exploration allocation); the **roadmap artifact** (icebox → quarterly themes → monthly slate with T1 iteration / T2 remix / T3 production tiers and a hard capacity check); per-concept briefs handed to Modes 1–3; and the **monthly creative retro** (winners/losers/metric-wins/learnings/kills, judged at concept level, every learning landing as an icebox update, re-rank, or kill). New `references/hook-system.md`: hooks as three components (visual action / spoken line / caption) with the no-duplication rule; the segment → motivation → format → hook generation pipeline output as a hook matrix; an eight-move opening menu; the **diagnostic funnel** mapping thumbstop/hold/CTR/CVR to which component to fix; the **on-ramp rule** (every hook test is an on-ramp test); fidelity laddering tied to production tiers; and inherited grounding rules plus organic language mining. SKILL.md adds the Mode 4 section and 'creative strategy,' 'creative roadmap,' 'creative retro,' 'hook writing' triggers. New eval (id 9) covers exploration-state diagnosis, evidence-ranked slates, and the receipts rule.
|
||||
- **customer-research** (2.0.0 → 2.0.1): added the **zero-review persona fallback** to Persona Generation — a four-step proxy ladder (own differentiator → direct competitors' reviews → marketplace comparables → adjacent brands sharing the audience) with provisional-persona tagging and replacement as first-party evidence arrives.
|
||||
- **marketing-loops** (1.1.0 → 1.2.0): added **the monthly-creative-retro loop** to the Paid section of `references/loop-catalog.md` — closes ad-creative's Mode 4 loop on a schedule: pulls last month's performance, drafts the retro artifact and next month's capacity-checked slate, flags the account-state call for human confirmation, one-retro-per-month idempotency, and never launches or pauses ads. Closes #434.
|
||||
|
||||
### 2.8.6 (2026-07-09)
|
||||
|
||||
- **ai-seo** (2.1.0 → 2.2.0): added **citations vs. recommendations** — the correction to citation-centric AEO strategy. New `references/citations-vs-recommendations.md` (grounded in Lily Ray's (Amsive) 100-query B2B study, Scrunch and SimilarWeb behavioral studies, and Growth Plays commentary): the **AI visibility ladder** (retrieved → cited → mentioned → recommended, each governed by different criteria, plus the shadow rung of being *recommended against* on requirements-heavy prompts), the **self-promotional listicle risk** (69% of the AI Overview citations earned by self-promotional "best [category]" listicles — 224 of 323 — appeared in answers that excluded the publisher from the recommendations; for emerging brands a self-ranked guide can act as a vote for competitors), **stage-dependent buyer's-guide strategy** (leaders get cited and recommended; emerging brands get citation and category framing — still worth publishing, with rebalanced expectations), **what earns recommendations** (offsite consensus: reviews, analysts, communities, earned media, video — with the test "if a model ignored everything on our domain, would the rest of the web still shortlist us?"), and **what a recommendation is worth** (Scrunch, observational: ~2× behavior lift vs. a passing mention; for users with no recent observed brand engagement, +182% branded searches / +117% site visits / +185% product views within a week; SimilarWeb: ~2.5× more new visitors — with only ~9% visible as AI traffic, the attribution blind spot) plus the measurement triad (prompt tracking with mention framing, self-reported attribution, call recordings). SKILL.md adds a compact citation-≠-recommendation pointer, a Recommendation-rate row in Monitoring, and caveats on the Listicle Block (content-patterns.md) and educational-content goals (content-types.md).
|
||||
- **competitors** (2.0.0 → 2.0.1): added an **AI-answer expectations-by-stage** caveat to the alternatives-page format — these pages often earn AI citations, but recommendation depends on offsite consensus; for emerging brands a self-ranked list can surface competitors in the answer. Cross-references ai-seo's citations-vs-recommendations reference. Closes #427.
|
||||
|
||||
### 2.8.5 (2026-07-09)
|
||||
|
||||
- **ad-creative** (2.4.0 → 2.5.0): extended the iMessage reveal reference into **iOS-native reveal video ads** — `references/imessage-video-ads.md` (filename unchanged; retitled) now covers three surfaces sharing one production architecture. New **Other iOS-Native Reveal Surfaces** section: a surface-selection table keyed to persuasion mechanic (iMessage = a friend's recommendation; ChatGPT = an authoritative answer to the viewer's own question; Apple Notes = a private confession made public), **ChatGPT reveals** (the typed question is the customer's verbatim question; stream the answer in word chunks — type like thumbs, stream like a model; ChatGPT-real formatting; OpenAI trade-dress legal note; and the strictest compliance rule in the family — the answer is ad copy wearing an authority costume, so health/medical/financial advice in a fabricated AI answer requires legal review and the exchange is never presented as a real unprompted ChatGPT endorsement), and **Apple Notes reveals** (confession-not-conversation: note title as the hook, first-person list typed live with keyboard-taps-only audio, one typo-and-correction, the product as the least enthusiastic line, realizations grounded in real reviews per Grounded Inputs). SKILL.md pointer updated to the three-surface framing and adds 'ChatGPT ad' and 'Apple Notes ad' triggers. New eval (id 8) covers the health-claims compliance flag, surface selection, and Notes craft rules. Format source credit unchanged (Gooseworks iOS Ads pack). Closes #424.
|
||||
|
||||
### 2.8.4 (2026-07-09)
|
||||
|
||||
- **social** (2.1.0 → 2.2.0): added a **carousel framework library**. New `references/carousel-frameworks.md` — five slide-by-slide narrative architectures for Instagram carousels and LinkedIn document posts, re-expressed and extended from a pattern circulating on marketing X (Vibe Marketers HQ's five-framework breakdown): **Value-Stack** (exact-count cover → one item per slide → action close; the count is a checkable promise), **Problem-Proof** (result-as-fact hook → reframed problem → named mechanism → literal detail → screenshot receipt that closes slide 1's loop), **Hack List** (contrarian stat hook → why the common approach fails → one *named* technique per slide → thesis + CTA), **Rant Callout** (provocative claim → specific escalation → the fairness pivot that keeps it conviction-not-bitterness → signed close), and **Demo Walkthrough** (outcome first → pain → numbered process overview *before* the detail to cut mid-swipe drop-off → one real screenshot per step → result + positioning). Includes a framework-selection table (match structure to content type), two cross-framework rules (slide 1 is the thumbnail; one visual template per carousel), per-framework SaaS examples and failure modes, platform notes (IG 4:5 specs, LinkedIn PDF document posts with the post text as a second hook, TikTok photo-mode pacing), a production checklist (real claims only, exact counts delivered, one CTA), and measurement guidance (judge on saves + completion, not likes). SKILL.md wires the reference next to post templates and adds 'carousel,' 'slide-by-slide,' and 'document post' triggers; post-templates.md's generic Carousel Hook now points to the full library. New eval (id 7) covers framework selection, named-technique slides, LinkedIn document-post guidance, and no-invented-stats. Closes #421.
|
||||
|
||||
### 2.8.3 (2026-07-09)
|
||||
|
||||
- **ad-creative** (2.3.0 → 2.4.0): added a **brand-flexible style tier** to `references/motion-video-ads.md` — four token-driven styles that absorb any company's brand system instead of imposing their own palette: **monoline editorial** (thin single-weight ink line-art on the brand neutral, one accent sweep — the most universally brandable), **Swiss typographic** (the label set enormous in the brand's type on a grid; works for any brand with a font and a color), **wireglow** (wireframe subject on near-black with one gradient accent beam — dev-tool/dark-mode brands), and **duotone screenprint** (photography reduced to ink + accent). All driven by a **brand slots contract** — FIELD (neutral ground), INK (drawing/type color), ACCENT (one element per frame, scarcity is the design), TYPE FEEL, plus per-brand constraints (e.g. "gradients only on edges") — resolvable from brand guidelines or `.agents/product-marketing.md`. Includes per-style motion notes (lines draw themselves, beams pulse, type settles) under the same composition-never-changes rules. All four verified to render with clean typography using a real brand's tokens.
|
||||
|
||||
### 2.8.2 (2026-07-09)
|
||||
|
||||
- **ad-creative** (2.2.0 → 2.3.0): added the **faceless motion-style video ad format**. New `references/motion-video-ads.md` (format popularized by @borjafat; original re-expression of the open Bomx `super-video-maker` motion-collage recipe, extended with production lessons from shipping it end-to-end): a fully generated 15–45s concept/explainer video — styled poster stills (one per beat, series-locked via reference images) → image-to-video "living" motion → TTS narration → whisper-word-timed captions — at roughly $3–6 and ~15 minutes per finished video. Covers the provider-agnostic pipeline with a one-key Gemini path (Nano Banana Pro + Veo 3.1 + Gemini TTS) and alternatives (GPT-Image/Flux, Seedance/Kling/Runway, ElevenLabs), a **five-style visual library** with fill-in prompt formulas (screen-print collage, flat vector explainer, papercraft diorama, pop-art comic, claymation), a motion prompt formula, hard-earned QC gotchas (image-to-video models inject photoreal "maker hands" — and negative prompts make it worse; always QC each clip's final 2 seconds; caption/label collision; TTS/whisper sound-alike words in CTAs), ad-specific rules (brand in the poster for sound-off autoplay, beat 1 is the 3-second hook, regenerate stills per aspect rather than cropping), and AI-content disclosure notes. SKILL.md wires the reference into Generating Ad Visuals and adds 'motion video ad,' 'faceless video ad,' 'animated explainer ad,' and 'motion collage ad' description triggers.
|
||||
|
||||
### 2.8.1 (2026-07-08)
|
||||
|
||||
- **ad-creative** (2.1.0 → 2.2.0): added the **iMessage chat-reveal video ad format**. New `references/imessage-video-ads.md` — an original distillation of the format popularized by Shiv Sakhuja / Gooseworks (their public `create-imessage-video-ad` skill; the repo carries no open-source license, so content was re-expressed with credit rather than copied): a 9:16 video where a scripted iMessage thread unfolds bubble-by-bubble — screenshot hook → friend reacts → "what app is that?" → brand + promo-code reveal → static end card. Covers when to use it and when not (considered B2B, nothing screenshot-able, regulated-industry compliance), a compliance/grounding section tying dramatized conversations to the skill's Grounded Inputs rules (facts in the thread must be real; never frame the thread as a real testimonial), the six concept angles (result-as-screenshot, setup flex, cancellation moment, feature-as-punchline, friend-asks-friend inverse, receipt-as-hook), ad anatomy with script + pacing rules (8–14 bubbles, texting voice, brand appears once and late, rhythm not metronome, link-underlined promo code), three production routes (off-the-shelf Gooseworks skill; code-based HTML mockup + one continuous Playwright recording + ffmpeg stitch; Remotion for templated scale), the craft rules that sell the illusion (the recognizable send/receive SFX — CC0 recordings on BigSoundBank, with a trade-dress legal-review note; silent typing indicators; composer-typed text must equal sent text; static end card with the real logo SVG; native 1080×1920 recording; HTML-mimic real app UIs for hook screenshots instead of AI-generating them), a ship checklist, and an iteration order (hook attachment first). SKILL.md wires the reference into Generating Ad Visuals and adds 'iMessage ad,' 'chat reveal ad,' 'text message ad,' and 'fake DM ad' description triggers. Closes #411.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: ad-creative
|
||||
description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' 'ad performance optimization,' 'write me some ads,' 'Facebook ad copy,' 'Google ad headlines,' 'LinkedIn ad text,' 'static ads,' 'static ad concepts,' 'ad templates,' 'iMessage ad,' 'chat reveal ad,' 'text message ad,' 'fake DM ad,' or 'I need more ad variations.' Use this whenever someone needs to produce ad copy at scale or iterate on existing ads. For campaign strategy and targeting, see ads. For landing page copy, see copywriting."
|
||||
description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' 'ad performance optimization,' 'write me some ads,' 'Facebook ad copy,' 'Google ad headlines,' 'LinkedIn ad text,' 'static ads,' 'static ad concepts,' 'ad templates,' 'iMessage ad,' 'chat reveal ad,' 'fake DM ad,' 'ChatGPT ad,' 'Apple Notes ad,' 'AirDrop ad,' 'creative strategy,' 'creative roadmap,' 'creative retro,' 'hook writing,' 'creative review page,' 'present ad creative for approval,' 'motion video ad,' 'faceless video ad,' 'animated explainer ad,' 'motion collage ad,' or 'I need more ad variations.' Use this whenever someone needs to produce ad copy at scale or iterate on existing ads. For campaign strategy and targeting, see ads. For landing page copy, see copywriting."
|
||||
metadata:
|
||||
version: 2.2.0
|
||||
version: 2.8.0
|
||||
---
|
||||
|
||||
# Ad Creative
|
||||
@@ -46,7 +46,7 @@ Gather this context (ask if not provided):
|
||||
|
||||
## How This Skill Works
|
||||
|
||||
This skill supports three modes:
|
||||
This skill supports four modes:
|
||||
|
||||
### Mode 1: Generate from Scratch
|
||||
When starting fresh, you generate a full set of ad creative based on product context, audience insights, and platform best practices.
|
||||
@@ -61,7 +61,10 @@ Pull performance data → Identify winning patterns → Generate new variations
|
||||
```
|
||||
|
||||
### Mode 3: Scaled Static Batches (Grounded)
|
||||
For recurring static ad production at volume (e.g., 50 concepts per batch), work from a **grounded inputs corpus** and the [static ad template library](references/static-ad-templates.md). Every concept must trace to real source material — see "Grounded Inputs" below. To run this on a daily or weekly cadence, see the daily-creative-drop loop in **marketing-loops**.
|
||||
For recurring static ad production at volume (e.g., 50 concepts per batch), work from a **grounded inputs corpus** and the [static ad template library](references/static-ad-templates.md). Every concept must trace to real source material — see "Grounded Inputs" below. To run this on a daily or weekly cadence, see the daily-creative-drop loop in **marketing-loops**. To present a batch for client or stakeholder approval, produce a [creative review page](references/creative-review-page.md).
|
||||
|
||||
### Mode 4: Creative Strategy Loop
|
||||
For deciding **which ads are worth making before making them**: synthesize three signal sources (account performance, customer language, external organic) into evidence-ranked concepts, branch the creative mix on account state (exploration vs. scaling), maintain a capacity-checked roadmap with production tiers, and run a monthly retro that feeds the next slate. The full system lives in [references/creative-roadmap.md](references/creative-roadmap.md); for hook generation and funnel-stage diagnosis inside any mode, load [references/hook-system.md](references/hook-system.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -150,7 +153,9 @@ For detailed specs and format variations, see [references/platform-specs.md](ref
|
||||
|
||||
**For static ad structure**, use the 15-template library in [references/static-ad-templates.md](references/static-ad-templates.md) — layout frameworks (Us vs. Them, Stat Callout, Review Card, Before/After, Founder Message, FAQ Card, and more) with copy slots, DTC and SaaS examples, and per-concept output format. Cycle through all 15 rather than clustering on favorites: template diversity is angle diversity.
|
||||
|
||||
**For iMessage chat-reveal video ads** — the 9:16 format where a scripted iMessage thread unfolds bubble-by-bubble (screenshot hook → friend asks "what app is that?" → brand + promo code reveal → end card) — see [references/imessage-video-ads.md](references/imessage-video-ads.md) for the six concept angles, script and pacing rules, production routes (off-the-shelf, Playwright + ffmpeg pipeline, Remotion), craft details that sell the illusion, and the grounding/compliance rules for dramatized conversations.
|
||||
**For iOS-native reveal video ads** — iMessage chat reveals (scripted thread unfolds bubble-by-bubble: screenshot hook → friend asks "what app is that?" → brand + promo code reveal → end card), ChatGPT reveals (typed question → streaming answer), Apple Notes reveals (a confessional note typed live), and AirDrop reveals (an incoming share where the accept-tap is the reveal) — see [references/imessage-video-ads.md](references/imessage-video-ads.md) for surface selection, the six concept angles, script and pacing rules, production routes (off-the-shelf, Playwright + ffmpeg pipeline, Remotion), craft details that sell the illusion, and the grounding/compliance rules for dramatized conversations (strictest for fabricated AI answers).
|
||||
|
||||
**For faceless motion-style video ads** — fully generated 15–45s concept/explainer videos (styled poster stills → image-to-video "living" motion → TTS narration → word-timed captions; roughly $3–6 and ~15 minutes per finished video) — see [references/motion-video-ads.md](references/motion-video-ads.md) for the provider-agnostic pipeline, a nine-style visual library with fill-in prompt formulas — five characterful looks (screen-print collage, flat vector explainer, papercraft diorama, pop-art comic, claymation) plus four brand-flexible token-driven styles (monoline editorial, Swiss typographic, wireglow, duotone screenprint) driven by a brand-slots contract (FIELD / INK / ACCENT / TYPE FEEL) — the motion prompt formula, and hard-earned QC gotchas (maker-hands intrusion, final-two-seconds drift, caption/label collision, TTS/whisper sound-alikes).
|
||||
|
||||
For image and video generation tools, see [references/generative-tools.md](references/generative-tools.md) for the complete guide covering:
|
||||
|
||||
@@ -319,6 +324,10 @@ outputs/YYYY-MM-DD/
|
||||
|
||||
Per-concept format is defined in [references/static-ad-templates.md](references/static-ad-templates.md). The human workflow this supports: open the folder, scan INDEX.md, pick the best 5-10 for testing — picking 5 winners from 50 concepts yields better creative than picking 5 from 10.
|
||||
|
||||
### Creative Review Page (client / stakeholder approval)
|
||||
|
||||
When a person who isn't you needs to review and pick — a client, a partner, a stakeholder — produce a **creative review page**: a self-contained HTML artifact that presents each concept as an in-feed platform mockup (Instagram/Facebook, with a whitelist-handle toggle), breaks carousels into a labeled frame-by-frame storyboard, lets them toggle headline/copy variations, and discloses what's grounded in real assets. It's the visual upgrade to INDEX.md — a decision made off one link instead of by reading markdown. The template ships at [assets/creative-review-template.html](assets/creative-review-template.html) (one file, no build, hostable anywhere); populate its `DATA` object from your generated concepts. Full data model, grounding rules (the disclosure block is required), and delivery in [references/creative-review-page.md](references/creative-review-page.md).
|
||||
|
||||
### Iteration Report
|
||||
|
||||
When iterating, include a summary:
|
||||
|
||||
@@ -0,0 +1,400 @@
|
||||
<!DOCTYPE html>
|
||||
<!--
|
||||
Creative Review Page — a shareable ad-creative approval artifact.
|
||||
|
||||
HOW TO USE (agents): replace the JSON inside <script id="review-data"> below
|
||||
with the real project. Everything else renders from it. The file is
|
||||
self-contained — no build, no network, no dependencies. Open it in a browser,
|
||||
host it on any static host (Vercel/Netlify/GitHub Pages), or hand off the
|
||||
single .html file.
|
||||
|
||||
THE DATA BLOCK IS JSON, NOT JAVASCRIPT:
|
||||
- double-quoted keys and strings, no comments, no trailing commas
|
||||
- it is inert data (parsed with JSON.parse), so a value can never execute
|
||||
- SECURITY: escape every literal "<" in your text values as < so a
|
||||
value like "</script>" can never break out of the tag. All values are
|
||||
also HTML-escaped again at render time.
|
||||
|
||||
DATA SHAPE — see references/creative-review-page.md for the annotated spec.
|
||||
Images: each frame's "image" may be a URL, a relative path, or a data URI.
|
||||
If omitted (or the file is missing), a placeholder shows the frame label +
|
||||
the image prompt — use this for concepts not yet rendered to image.
|
||||
-->
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>Creative Review</title>
|
||||
<style>
|
||||
:root {
|
||||
--bg: #f4f3f0; --card: #ffffff; --ink: #16150f; --muted: #6b6a63;
|
||||
--line: #e4e2dc; --accent: #2f6fed; --accent-soft: #eaf0fe;
|
||||
--radius: 14px; --shadow: 0 1px 2px rgba(0,0,0,.04), 0 8px 24px rgba(0,0,0,.05);
|
||||
}
|
||||
* { box-sizing: border-box; }
|
||||
body { margin: 0; background: var(--bg); color: var(--ink);
|
||||
font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
|
||||
-webkit-font-smoothing: antialiased; }
|
||||
.wrap { max-width: 1120px; margin: 0 auto; padding: 32px 20px 80px; }
|
||||
.eyebrow { font-size: 11px; font-weight: 700; letter-spacing: .12em; text-transform: uppercase; color: var(--muted); }
|
||||
a { color: var(--accent); }
|
||||
|
||||
header.project { margin-bottom: 28px; }
|
||||
header.project h1 { font-size: 20px; margin: 6px 0 2px; letter-spacing: -.01em; }
|
||||
header.project .sub { color: var(--muted); font-size: 13px; }
|
||||
|
||||
.concepts { display: grid; grid-template-columns: repeat(auto-fit, minmax(210px, 1fr)); gap: 10px; margin: 14px 0 28px; }
|
||||
.concept { text-align: left; background: var(--card); border: 1.5px solid var(--line); border-radius: var(--radius);
|
||||
padding: 14px 16px; cursor: pointer; transition: border-color .12s, box-shadow .12s; font: inherit; color: inherit; }
|
||||
.concept:hover { border-color: #cfcdc6; }
|
||||
.concept[aria-selected="true"] { border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-soft); background: #fff; }
|
||||
.concept .row1 { display: flex; align-items: baseline; justify-content: space-between; gap: 8px; }
|
||||
.concept .num { font-size: 11px; font-weight: 700; color: var(--muted); }
|
||||
.concept .frames { font-size: 11px; color: var(--muted); }
|
||||
.concept .name { font-weight: 650; font-size: 15px; margin: 4px 0 3px; }
|
||||
.concept .tag { font-size: 12.5px; color: var(--muted); line-height: 1.35; }
|
||||
|
||||
.grid { display: grid; grid-template-columns: minmax(0, 380px) minmax(0, 1fr); gap: 28px; align-items: start; }
|
||||
@media (max-width: 860px) { .grid { grid-template-columns: 1fr; } }
|
||||
.col-label { margin-bottom: 10px; }
|
||||
|
||||
.toggles { display: flex; flex-wrap: wrap; gap: 14px; margin-bottom: 12px; }
|
||||
.seg { display: inline-flex; background: #ecebe6; border-radius: 999px; padding: 3px; }
|
||||
.seg button { border: 0; background: transparent; font: inherit; font-size: 12.5px; font-weight: 600; color: var(--muted);
|
||||
padding: 5px 12px; border-radius: 999px; cursor: pointer; }
|
||||
.seg button[aria-pressed="true"] { background: #fff; color: var(--ink); box-shadow: 0 1px 2px rgba(0,0,0,.08); }
|
||||
.seg .lbl { align-self: center; font-size: 10.5px; font-weight: 700; letter-spacing: .1em; text-transform: uppercase; color: var(--muted); margin-right: 6px; }
|
||||
|
||||
.post { background: var(--card); border: 1px solid var(--line); border-radius: 12px; overflow: hidden; box-shadow: var(--shadow); }
|
||||
.post .top { display: flex; align-items: center; gap: 10px; padding: 11px 12px; }
|
||||
.post .avatar { width: 34px; height: 34px; border-radius: 50%; background: var(--accent-soft); color: var(--accent);
|
||||
display: grid; place-items: center; font-weight: 700; font-size: 13px; overflow: hidden; flex: none; }
|
||||
.post .avatar img { width: 100%; height: 100%; object-fit: cover; }
|
||||
.post .who { line-height: 1.2; }
|
||||
.post .who .name { font-weight: 650; font-size: 13.5px; }
|
||||
.post .who .partner { font-size: 11.5px; color: var(--muted); }
|
||||
.post .dots { margin-left: auto; color: var(--muted); font-weight: 700; letter-spacing: 2px; }
|
||||
.frame { position: relative; aspect-ratio: 4/5; background: #ded9d0; display: grid; }
|
||||
.frame img { width: 100%; height: 100%; object-fit: cover; grid-area: 1/1; z-index: 1; }
|
||||
.frame .ph { grid-area: 1/1; display: flex; flex-direction: column; justify-content: space-between; padding: 16px;
|
||||
background: linear-gradient(135deg,#efece5,#e2ddd2); }
|
||||
.frame .ph .plabel { font-size: 11px; font-weight: 700; letter-spacing: .1em; text-transform: uppercase; color: #948e80; }
|
||||
.frame .ph .pprompt { font-size: 13px; color: #5f5a4e; line-height: 1.4; }
|
||||
.frame .badge { position: absolute; top: 12px; left: 12px; z-index: 2; background: rgba(255,255,255,.92);
|
||||
font-size: 11.5px; font-weight: 600; padding: 5px 10px; border-radius: 999px; display: flex; align-items: center; gap: 5px; }
|
||||
.frame .counter { position: absolute; top: 12px; right: 12px; z-index: 2; background: rgba(0,0,0,.6); color: #fff; font-size: 11px;
|
||||
font-weight: 600; padding: 3px 9px; border-radius: 999px; }
|
||||
.frame .headline { position: absolute; left: 0; right: 0; bottom: 0; z-index: 2; padding: 18px 16px 20px; color: #fff;
|
||||
font-size: 21px; font-weight: 700; line-height: 1.2; letter-spacing: -.01em;
|
||||
background: linear-gradient(to top, rgba(0,0,0,.72), rgba(0,0,0,0)); }
|
||||
.frame .headline.light { color: var(--ink); background: linear-gradient(to top, rgba(255,255,255,.85), rgba(255,255,255,0)); }
|
||||
|
||||
/* Instagram chrome */
|
||||
.ig-cta { display: flex; align-items: center; justify-content: space-between; padding: 12px; border-top: 1px solid var(--line);
|
||||
font-weight: 600; font-size: 13.5px; }
|
||||
.ig-cta .chev { color: var(--muted); }
|
||||
.ig-actions { display: flex; gap: 16px; padding: 10px 12px 2px; color: #26251f; }
|
||||
.ig-actions svg { width: 22px; height: 22px; }
|
||||
.ig-actions .save { margin-left: auto; }
|
||||
.likes { padding: 6px 12px 2px; font-weight: 650; font-size: 13px; }
|
||||
.caption { padding: 2px 12px 14px; font-size: 13px; line-height: 1.4; }
|
||||
.caption .h { font-weight: 650; }
|
||||
.caption .more { color: var(--muted); }
|
||||
|
||||
/* Facebook chrome — link card below image + text actions */
|
||||
.fb-card { display: flex; align-items: center; gap: 12px; padding: 12px; background: #f3f4f6; border-top: 1px solid var(--line); }
|
||||
.fb-card .meta { min-width: 0; flex: 1; }
|
||||
.fb-card .dom { font-size: 11px; letter-spacing: .04em; text-transform: uppercase; color: var(--muted); }
|
||||
.fb-card .hl { font-size: 14px; font-weight: 650; line-height: 1.25; margin-top: 2px; overflow: hidden; }
|
||||
.fb-card .btn { flex: none; background: #e4e6eb; color: #050505; font-weight: 650; font-size: 12.5px; padding: 8px 14px; border-radius: 7px; }
|
||||
.fb-actions { display: flex; padding: 4px 12px; border-top: 1px solid var(--line); }
|
||||
.fb-actions span { flex: 1; text-align: center; padding: 8px 0; font-size: 13px; font-weight: 600; color: var(--muted); }
|
||||
|
||||
.board { background: var(--card); border: 1px solid var(--line); border-radius: var(--radius); padding: 16px; box-shadow: var(--shadow); margin-bottom: 20px; }
|
||||
.board .frames-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; margin-top: 12px; }
|
||||
@media (max-width: 480px) { .board .frames-grid { grid-template-columns: repeat(2, 1fr); } }
|
||||
.thumb { border: 0; background: transparent; padding: 0; cursor: pointer; text-align: left; font: inherit; color: inherit; }
|
||||
.thumb .box { aspect-ratio: 4/5; border-radius: 9px; overflow: hidden; border: 2px solid transparent; background: #e7e2d8;
|
||||
display: grid; transition: border-color .12s; }
|
||||
.thumb[aria-current="true"] .box { border-color: var(--accent); }
|
||||
.thumb .box img { width: 100%; height: 100%; object-fit: cover; grid-area: 1/1; z-index: 1; }
|
||||
.thumb .box .mini { grid-area: 1/1; padding: 8px; font-size: 10.5px; color: #7a7566; line-height: 1.3;
|
||||
background: linear-gradient(135deg,#efece5,#e2ddd2); overflow: hidden; }
|
||||
.thumb .cap { margin-top: 6px; font-size: 12px; }
|
||||
.thumb .cap .n { color: var(--muted); font-weight: 700; margin-right: 6px; }
|
||||
|
||||
.copy { background: var(--card); border: 1px solid var(--line); border-radius: var(--radius); padding: 18px; box-shadow: var(--shadow); }
|
||||
.copy .block { padding: 14px 0; border-top: 1px solid var(--line); }
|
||||
.copy .block:first-of-type { border-top: 0; padding-top: 4px; }
|
||||
.headline-opt { display: flex; gap: 10px; align-items: flex-start; width: 100%; text-align: left; font: inherit; color: inherit;
|
||||
background: #faf9f6; border: 1.5px solid var(--line); border-radius: 10px; padding: 11px 13px; cursor: pointer; margin-top: 8px; }
|
||||
.headline-opt[aria-pressed="true"] { border-color: var(--accent); background: #fff; box-shadow: 0 0 0 3px var(--accent-soft); }
|
||||
.headline-opt .n { font-size: 11px; font-weight: 700; color: var(--muted); margin-top: 2px; }
|
||||
.headline-opt .t { font-size: 14px; line-height: 1.35; }
|
||||
.kv { font-size: 13.5px; line-height: 1.5; }
|
||||
.kv .dest { color: var(--accent); font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px; }
|
||||
.steps { margin: 8px 0 0; padding: 0; list-style: none; }
|
||||
.steps li { display: flex; gap: 10px; padding: 5px 0; font-size: 13px; line-height: 1.4; }
|
||||
.steps li .i { flex: none; width: 20px; height: 20px; border-radius: 50%; background: var(--accent-soft); color: var(--accent);
|
||||
display: grid; place-items: center; font-size: 11px; font-weight: 700; }
|
||||
.grounding { background: #f6f5ef; border: 1px dashed #cfcabb; border-radius: 10px; padding: 12px 14px; font-size: 12.5px; color: #5f5a4e; line-height: 1.45; margin-top: 8px; }
|
||||
.err { background: #fbeaea; border: 1px solid #e6b7b7; color: #8a2b2b; border-radius: 10px; padding: 14px 16px; font-size: 13px; }
|
||||
footer { margin-top: 40px; text-align: center; font-size: 12px; color: var(--muted); }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<!-- DATA — replace this JSON with your project (see the comment at the top of the file). -->
|
||||
<script type="application/json" id="review-data">
|
||||
{
|
||||
"project": {
|
||||
"brand": "Truvani",
|
||||
"agency": "Light Labs",
|
||||
"date": "2026-07-12",
|
||||
"note": "Whitelisted paid-social concepts for review"
|
||||
},
|
||||
"platforms": ["instagram", "facebook"],
|
||||
"concepts": [
|
||||
{
|
||||
"name": "Heavy-Metal Proof",
|
||||
"tagline": "Lifestyle hero, then the lab results",
|
||||
"handles": [
|
||||
{ "name": "truvani", "partner": "Paid partnership with lightlabs", "initials": "TV" },
|
||||
{ "name": "Light Labs", "partner": "Paid partnership with truvani", "initials": "LL" }
|
||||
],
|
||||
"frames": [
|
||||
{ "label": "Hook", "prompt": "Product bag hero on soft pink, gold-lace overlay", "headline": "Finally — a plant-based protein that's third-party tested for heavy metals.", "headlineTheme": "dark" },
|
||||
{ "label": "The problem", "prompt": "Editorial card: 'Plants absorb more than nutrients' + Pb/As/Cd chips" },
|
||||
{ "label": "Enter Light Labs", "prompt": "Clean card: 'So we sent it to Light Labs' + independent-lab note" },
|
||||
{ "label": "The results", "prompt": "Results table: Arsenic / Cadmium / Lead, all within limits, green check" },
|
||||
{ "label": "For context", "prompt": "'Less arsenic than your breakfast' comparison bar" },
|
||||
{ "label": "The ask", "prompt": "Product you can finally trust — CTA frame", "headline": "Protein you can finally trust." }
|
||||
],
|
||||
"headlines": [
|
||||
"Finally — a plant-based protein that's third-party tested for heavy metals.",
|
||||
"We tested our protein for heavy metals. Here's what an independent lab found.",
|
||||
"Most protein powders are never tested for heavy metals. Ours is."
|
||||
],
|
||||
"primaryText": "We tested our Plant-Based Protein for the heavy metals that hide in “clean” powders — lead, arsenic and cadmium. Here's exactly what an independent lab measured.",
|
||||
"destination": { "url": "shop.truvani.com", "cta": "Shop now", "offer": "72% OFF Protein Starter Kit" },
|
||||
"rollout": {
|
||||
"title": "How the whitelist runs",
|
||||
"steps": [
|
||||
"Truvani reviews and approves the creative — Light Labs builds it.",
|
||||
"Truvani sends a Meta partnership request granting Light Labs access to this ad only.",
|
||||
"Light Labs launches it under the co-branded handle.",
|
||||
"We report performance back — framed as a free, mutually beneficial first test."
|
||||
]
|
||||
},
|
||||
"grounding": "Results are Truvani's actual Light Labs panel (Vanilla, tested Nov 13, 2025). Imagery is Truvani's own product & lifestyle photography."
|
||||
},
|
||||
{
|
||||
"name": "Cleaner Than Rice",
|
||||
"tagline": "Leads with the brown-rice comparison",
|
||||
"frames": [
|
||||
{ "label": "Hook", "prompt": "Split visual: brown rice vs protein scoop", "headline": "Your “clean” brown rice protein? Test it.", "headlineTheme": "dark" },
|
||||
{ "label": "The claim", "prompt": "Stat card comparing arsenic levels" },
|
||||
{ "label": "The proof", "prompt": "Light Labs results table" },
|
||||
{ "label": "The context", "prompt": "What the numbers mean, plainly" },
|
||||
{ "label": "The ask", "prompt": "Starter-kit offer frame", "headline": "Trust the label. Then trust the test." }
|
||||
],
|
||||
"headlines": [
|
||||
"Your “clean” brown rice protein? Test it.",
|
||||
"Brown rice protein is often the worst offender for arsenic. We checked ours.",
|
||||
"“Plant-based” doesn't mean “clean.” We have the lab panel to prove ours is."
|
||||
],
|
||||
"primaryText": "Brown-rice protein is one of the most common sources of dietary arsenic. So we sent ours to an independent lab. Here's the panel.",
|
||||
"destination": { "url": "shop.truvani.com", "cta": "Shop now", "offer": "72% OFF Protein Starter Kit" },
|
||||
"grounding": "Comparison figures are from Truvani's Light Labs panel and published dietary-arsenic ranges. No competitor is named."
|
||||
}
|
||||
]
|
||||
}
|
||||
</script>
|
||||
|
||||
<div class="wrap">
|
||||
<header class="project" id="project"></header>
|
||||
<div class="eyebrow">Creative concept · toggle between ideas</div>
|
||||
<div class="concepts" id="concepts" role="tablist"></div>
|
||||
<div class="grid">
|
||||
<section>
|
||||
<div class="eyebrow col-label" id="preview-label">In-feed preview</div>
|
||||
<div class="toggles" id="toggles"></div>
|
||||
<div class="post" id="post"></div>
|
||||
</section>
|
||||
<section>
|
||||
<div class="board">
|
||||
<div class="eyebrow" id="board-label">Storyboard · tap to jump</div>
|
||||
<div class="frames-grid" id="frames-grid"></div>
|
||||
</div>
|
||||
<div class="copy" id="copy"></div>
|
||||
</section>
|
||||
</div>
|
||||
<footer id="footer"></footer>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
/* ============================================================================
|
||||
RENDER — generic; no need to edit when swapping the DATA JSON above.
|
||||
========================================================================== */
|
||||
const esc = (s) => String(s == null ? "" : s).replace(/[&<>"']/g, c => (
|
||||
{ "&": "&", "<": "<", ">": ">", '"': """, "'": "'" }[c]));
|
||||
const PLATFORMS = { instagram: "Instagram", facebook: "Facebook" };
|
||||
|
||||
let DATA;
|
||||
try {
|
||||
DATA = JSON.parse(document.getElementById("review-data").textContent);
|
||||
} catch (e) {
|
||||
document.querySelector(".wrap").innerHTML =
|
||||
'<div class="err"><b>Couldn\'t read the review data.</b><br/>The <code>#review-data</code> block must be valid JSON — double-quoted keys and strings, no comments, no trailing commas. Parser said: ' + esc(e.message) + '</div>';
|
||||
throw e;
|
||||
}
|
||||
|
||||
const state = { concept: 0, frame: 0, platform: null, handle: 0, headline: 0 };
|
||||
const concept = () => DATA.concepts[state.concept];
|
||||
|
||||
// platforms restricted to the ones we can render; default to first valid
|
||||
const platformList = () => (DATA.platforms || ["instagram"]).filter(p => PLATFORMS[p]);
|
||||
state.platform = platformList()[0] || "instagram";
|
||||
|
||||
const heart = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M20.8 4.6a5.5 5.5 0 0 0-7.8 0L12 5.6l-1-1a5.5 5.5 0 1 0-7.8 7.8l1 1L12 21l7.8-7.6 1-1a5.5 5.5 0 0 0 0-7.8z"/></svg>';
|
||||
const comment = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M21 11.5a8.4 8.4 0 0 1-11.8 7.7L3 21l1.9-6.2A8.4 8.4 0 1 1 21 11.5z"/></svg>';
|
||||
const share = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M22 2 11 13M22 2l-7 20-4-9-9-4 20-7z"/></svg>';
|
||||
const bookmark = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"/></svg>';
|
||||
|
||||
function renderProject() {
|
||||
const p = DATA.project || {};
|
||||
const line = [p.brand, p.agency && `× ${p.agency}`].filter(Boolean).join(" ");
|
||||
document.getElementById("project").innerHTML =
|
||||
`<div class="eyebrow">Creative review${p.date ? " · " + esc(p.date) : ""}</div>
|
||||
<h1>${esc(line || "Ad creative")}</h1>${p.note ? `<div class="sub">${esc(p.note)}</div>` : ""}`;
|
||||
document.getElementById("footer").innerHTML =
|
||||
`Creative review${p.agency ? " · " + esc(p.agency) : ""} — concepts for approval. Nothing here is live until you pick.`;
|
||||
}
|
||||
|
||||
function renderConcepts() {
|
||||
document.getElementById("concepts").innerHTML = DATA.concepts.map((c, i) => `
|
||||
<button class="concept" role="tab" aria-selected="${i === state.concept}" data-i="${i}">
|
||||
<div class="row1"><span class="num">${String(i + 1).padStart(2, "0")}</span>
|
||||
<span class="frames">${c.frames.length} frame${c.frames.length === 1 ? "" : "s"}</span></div>
|
||||
<div class="name">${esc(c.name)}</div>
|
||||
<div class="tag">${esc(c.tagline || "")}</div>
|
||||
</button>`).join("");
|
||||
document.querySelectorAll(".concept").forEach(b =>
|
||||
b.onclick = () => { state.concept = +b.dataset.i; state.frame = 0; state.handle = 0; state.headline = 0; renderAll(); });
|
||||
}
|
||||
|
||||
function handles() {
|
||||
return concept().handles || [{
|
||||
name: DATA.project?.brand || "brand",
|
||||
partner: DATA.project?.agency ? "Paid partnership with " + DATA.project.agency.toLowerCase() : "Sponsored",
|
||||
initials: (DATA.project?.brand || "AD").slice(0, 2).toUpperCase()
|
||||
}];
|
||||
}
|
||||
|
||||
function renderToggles() {
|
||||
const plats = platformList(), hs = handles();
|
||||
let html = "";
|
||||
if (plats.length > 1) {
|
||||
html += `<div class="seg" role="group">${plats.map(p =>
|
||||
`<button data-plat="${esc(p)}" aria-pressed="${p === state.platform}">${esc(PLATFORMS[p])}</button>`).join("")}</div>`;
|
||||
}
|
||||
if (hs.length > 1) {
|
||||
html += `<div class="seg" role="group"><span class="lbl">Handle</span>${hs.map((h, i) =>
|
||||
`<button data-handle="${i}" aria-pressed="${i === state.handle}">${esc(h.name)}</button>`).join("")}</div>`;
|
||||
}
|
||||
const el = document.getElementById("toggles");
|
||||
el.innerHTML = html;
|
||||
el.querySelectorAll("[data-plat]").forEach(b => b.onclick = () => { state.platform = b.dataset.plat; renderToggles(); renderPost(); });
|
||||
el.querySelectorAll("[data-handle]").forEach(b => b.onclick = () => { state.handle = +b.dataset.handle; renderToggles(); renderPost(); });
|
||||
document.getElementById("preview-label").textContent = (hs.length > 1 ? "Whitelisted ad · " : "") + "In-feed preview";
|
||||
}
|
||||
|
||||
// placeholder underneath + image on top; a missing/broken image removes itself → placeholder shows
|
||||
function frameVisual(f, phCls) {
|
||||
const ph = `<div class="${phCls}"><div class="plabel">${esc(f.label)}</div><div class="pprompt">${esc(f.prompt || "")}</div></div>`;
|
||||
const img = f.image ? `<img src="${esc(f.image)}" alt="${esc(f.label)}" onerror="this.remove()" />` : "";
|
||||
return ph + img;
|
||||
}
|
||||
|
||||
function frameHTML(c, f) {
|
||||
const total = c.frames.length;
|
||||
const headlineText = state.frame === 0 ? (c.headlines?.[state.headline] || f.headline || "") : (f.headline || "");
|
||||
const theme = f.headlineTheme === "light" ? " light" : "";
|
||||
return `<div class="frame">
|
||||
${frameVisual(f, "ph")}
|
||||
<span class="counter">${state.frame + 1}/${total}</span>
|
||||
${headlineText ? `<div class="headline${theme}">${esc(headlineText)}</div>` : ""}
|
||||
</div>`;
|
||||
}
|
||||
|
||||
function renderPost() {
|
||||
const c = concept(), f = c.frames[state.frame], h = handles()[state.handle] || handles()[0];
|
||||
const dest = c.destination || {};
|
||||
const top = `<div class="top">
|
||||
<div class="avatar">${h.initials ? esc(h.initials) : ""}</div>
|
||||
<div class="who"><div class="name">${esc(h.name)}</div><div class="partner">${esc(h.partner || "Sponsored")}</div></div>
|
||||
<div class="dots">···</div>
|
||||
</div>`;
|
||||
|
||||
let chrome;
|
||||
if (state.platform === "facebook") {
|
||||
const domain = dest.url ? esc(dest.url) : "";
|
||||
const hl = c.headlines?.[state.headline] || f.headline || dest.offer || "";
|
||||
chrome = `<div class="fb-card">
|
||||
<div class="meta"><div class="dom">${domain}</div><div class="hl">${esc(hl)}</div></div>
|
||||
${dest.cta ? `<div class="btn">${esc(dest.cta)}</div>` : ""}
|
||||
</div>
|
||||
<div class="fb-actions"><span>Like</span><span>Comment</span><span>Share</span></div>`;
|
||||
} else {
|
||||
chrome = `<div class="ig-cta"><span>${esc(dest.cta || "Learn more")}</span><span class="chev">›</span></div>
|
||||
<div class="ig-actions">${heart}${comment}${share}<span class="save">${bookmark}</span></div>
|
||||
<div class="likes">6,240 likes</div>
|
||||
<div class="caption"><span class="h">${esc(h.name)}</span> ${esc((c.primaryText || "").slice(0, 90))}<span class="more"> … more</span></div>`;
|
||||
}
|
||||
|
||||
document.getElementById("post").innerHTML = top + frameHTML(c, f) + chrome;
|
||||
document.getElementById("board-label").textContent = `${c.name} · ${state.frame + 1}/${c.frames.length} · tap to jump`;
|
||||
}
|
||||
|
||||
function renderBoard() {
|
||||
const c = concept();
|
||||
document.getElementById("frames-grid").innerHTML = c.frames.map((f, i) => `
|
||||
<button class="thumb" aria-current="${i === state.frame}" data-i="${i}">
|
||||
<div class="box">${frameVisual(f, "mini")}</div>
|
||||
<div class="cap"><span class="n">${String(i + 1).padStart(2, "0")}</span>${esc(f.label)}</div>
|
||||
</button>`).join("");
|
||||
document.querySelectorAll(".thumb").forEach(b =>
|
||||
b.onclick = () => { state.frame = +b.dataset.i; renderPost(); renderBoard(); });
|
||||
}
|
||||
|
||||
function renderCopy() {
|
||||
const c = concept(), dest = c.destination || {};
|
||||
let html = "";
|
||||
if (c.headlines?.length) {
|
||||
html += `<div class="block"><div class="eyebrow">Headline — tap to preview</div>${c.headlines.map((h, i) =>
|
||||
`<button class="headline-opt" aria-pressed="${i === state.headline}" data-i="${i}">
|
||||
<span class="n">${String(i + 1).padStart(2, "0")}</span><span class="t">${esc(h)}</span></button>`).join("")}</div>`;
|
||||
}
|
||||
if (c.primaryText) html += `<div class="block"><div class="eyebrow">Primary text</div><div class="kv" style="margin-top:8px">${esc(c.primaryText)}</div></div>`;
|
||||
if (dest.url || dest.cta) {
|
||||
html += `<div class="block"><div class="eyebrow">Destination</div><div class="kv" style="margin-top:8px">
|
||||
${dest.url ? `<span class="dest">${esc(dest.url)}</span><br/>` : ""}
|
||||
${dest.cta ? `CTA: ${esc(dest.cta)}` : ""}${dest.offer ? ` → ${esc(dest.offer)}` : ""}</div></div>`;
|
||||
}
|
||||
if (c.rollout?.steps?.length) {
|
||||
html += `<div class="block"><div class="eyebrow">${esc(c.rollout.title || "How it runs")}</div>
|
||||
<ol class="steps">${c.rollout.steps.map((s, i) => `<li><span class="i">${i + 1}</span><span>${esc(s)}</span></li>`).join("")}</ol></div>`;
|
||||
}
|
||||
if (c.grounding) html += `<div class="block"><div class="eyebrow">Live data · real assets</div><div class="grounding">${esc(c.grounding)}</div></div>`;
|
||||
const el = document.getElementById("copy");
|
||||
el.innerHTML = html;
|
||||
el.querySelectorAll(".headline-opt").forEach(b =>
|
||||
b.onclick = () => { state.headline = +b.dataset.i; state.frame = 0; renderPost(); renderBoard(); renderCopy(); });
|
||||
}
|
||||
|
||||
function renderAll() { renderConcepts(); renderToggles(); renderPost(); renderBoard(); renderCopy(); }
|
||||
renderProject();
|
||||
renderAll();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -100,6 +100,65 @@
|
||||
"Mentions at least one production route and key craft rules (SFX, silent typing indicator, 9:16)"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 8,
|
||||
"prompt": "We sell a menopause supplement. I saw those ads where someone asks ChatGPT a health question and the answer recommends the product — make one of those for us. Also curious about the Apple Notes version.",
|
||||
"expected_output": "Should load references/imessage-video-ads.md and apply the Other iOS-Native Reveal Surfaces section. Should flag the compliance constraint prominently BEFORE drafting: a fabricated AI answer making health claims is the highest-risk version of this format — every claim needs substantiation, health/medical advice in a fake ChatGPT answer needs legal review, and the exchange must not be presented as a real unprompted ChatGPT output endorsing the product. May propose a compliant angle (mechanism education grounded in documented facts) or steer to the Apple Notes confession format as the lower-risk fit for a transformation story. For the Notes version: title-as-hook, first-person list with the product as the least enthusiastic line, keyboard-taps-only audio, grounding realizations in real reviews. Should apply surface-selection guidance rather than treating the three formats as interchangeable.",
|
||||
"assertions": [
|
||||
"Applies the iOS-native reveal surfaces section of the imessage-video-ads reference",
|
||||
"Flags health-claim/substantiation risk for the fabricated ChatGPT answer before or while drafting",
|
||||
"Does not present the ChatGPT exchange as a real unprompted output endorsing the product",
|
||||
"Recommends legal review or a compliant reframe for health advice in the AI answer",
|
||||
"Apple Notes guidance: title-as-hook, first-person confession, product as an understated list item, keyboard-taps-only audio",
|
||||
"Grounds claims and realizations in documented facts/reviews (Grounded Inputs)",
|
||||
"Gives surface-selection reasoning (ChatGPT vs Notes) instead of treating formats as interchangeable"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 9,
|
||||
"prompt": "Our Meta account is stuck — we've tested 30 ads over two months and nothing beats the control. I have our reviews exported and access to our ad account data. Build me a creative plan for next month.",
|
||||
"expected_output": "Should apply Mode 4 / references/creative-roadmap.md rather than jumping straight to generating ads. Should identify the account as exploration state (nothing working) and shape the plan accordingly: mostly net-new concepts across different segments/angles, minimal iterations, per-metric win redefinition (a hold-rate lift or CPC drop counts as a hit worth pulling on). Should synthesize the three signals (account performance from the ad data, customer language from the reviews, external organic — asking for or mining niche organic content) into concepts ranked by evidence tier, each with a cited source. Should produce a capacity-checked monthly slate with production tiers (favoring T1/T2 low-fidelity tests per the fidelity ladder) and flag the common exploration-state root causes to check (boring creative, overcomplicated message, unclear UVP, punishing CPMs). Should end with the retro plan for judging the slate at month end. Should not invent customer language or claims — insights must trace to the provided reviews/data.",
|
||||
"assertions": [
|
||||
"Applies the creative strategy loop (Mode 4) instead of only generating ad copy",
|
||||
"Diagnoses exploration state and recommends a wide, net-new-heavy mix with minimal iterations",
|
||||
"Redefines wins per-metric for a stuck account",
|
||||
"Synthesizes all three signal sources or explicitly requests the missing one",
|
||||
"Concepts are evidence-ranked with cited sources (no invented insights)",
|
||||
"Monthly slate is capacity-checked and production-tiered, favoring low-fidelity tests",
|
||||
"Includes a month-end retro plan that feeds the next slate"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 10,
|
||||
"prompt": "We generated four ad concepts for a client (an organic skincare brand) and need to send them something they can actually look at and approve — with the Instagram preview, the carousel frames, and the different headline options they can compare. Can you put that together?",
|
||||
"expected_output": "Should recognize this as a creative review page request and apply references/creative-review-page.md + the assets/creative-review-template.html template rather than producing plain markdown. Should copy the template into the output folder and populate its DATA object with the four concepts as tabs, each with an in-feed Instagram preview, a labeled frame-by-frame storyboard (frames labeled by narrative job — Hook / Problem / Proof / Ask — not by pictured content), selectable headline variations, primary text, and destination/CTA. Should curate to a reviewable number of concepts (2-4) rather than dumping everything. Should include a required grounding disclosure per concept stating what is real (product photography, any claims/results) and label illustrative proof as illustrative — never present invented stats or stock imagery as the brand's own. Should use styled placeholders for frames not yet rendered to image, and keep image paths relative. Should explain how to deliver it (open locally, host on a static host, or hand off the file).",
|
||||
"assertions": [
|
||||
"Produces a creative review page from the HTML template, not plain markdown",
|
||||
"Populates the DATA object (concept tabs, in-feed preview, frame storyboard, headline variations, copy, destination)",
|
||||
"Labels storyboard frames by narrative job rather than by pictured content",
|
||||
"Includes a required grounding/disclosure line per concept; labels illustrative proof as illustrative",
|
||||
"Does not present invented stats or stock imagery as the brand's real assets",
|
||||
"Uses placeholders for unrendered frames and keeps image paths relative",
|
||||
"Explains how to deliver the page (open locally / host / hand off the file)"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 11,
|
||||
"prompt": "I want to make one of those AirDrop-style video ads — where a phone gets an incoming AirDrop and you tap accept. We sell a limited-run sneaker drop.",
|
||||
"expected_output": "Should apply the AirDrop surface in references/imessage-video-ads.md (the iOS-native reveal family), not treat it as a novel format. Should build the ad around the interaction: an incoming AirDrop card (translucent sheet, sender device name, a preview thumbnail, gray Decline / blue Accept) from the receiver's POV, with the Accept tap as the reveal beat and the transfer progress-ring as the signature motion. Should make the preview thumbnail earn the tap (the sneaker money-shot / the drop), cast a relatable human sender name rather than the brand, use the AirDrop swoosh sound (not iMessage tritones) with the Apple trade-dress note, and keep it short. Should apply the family grounding/disclosure rules (a dramatization of a share, not a real endorsement; claims substantiated). May note receiver-POV-by-default vs sender-POV-as-flex.",
|
||||
"assertions": [
|
||||
"Applies the AirDrop iOS-native-reveal surface, not a from-scratch format",
|
||||
"Builds around the incoming-AirDrop-card + accept-tap-as-reveal interaction (receiver POV)",
|
||||
"Preview thumbnail is treated as the hook that must earn the accept",
|
||||
"Casts a relatable human sender name, not the brand, on the incoming card",
|
||||
"Uses the AirDrop swoosh sound + Apple trade-dress note, not iMessage tritones",
|
||||
"Applies the family grounding/disclosure rules (dramatized share, substantiated claims, not a real endorsement)"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,106 @@
|
||||
# The Creative Review Page
|
||||
|
||||
A shareable, self-contained web page that presents generated ad concepts for a client or stakeholder to **review and pick** — the visual upgrade to `INDEX.md`. Where the markdown outputs are built for the operator, the review page is built for the person approving the spend: it shows each concept as an in-feed platform mockup, breaks carousels into a labeled frame-by-frame storyboard, lets them toggle copy variations, and discloses what's grounded in real assets.
|
||||
|
||||
The template ships at [assets/creative-review-template.html](../assets/creative-review-template.html). It's one file — inline CSS and JS, no build, no dependencies, no network. Open it locally, host it on any static host (Vercel/Netlify/GitHub Pages), or hand off the `.html` file directly.
|
||||
|
||||
## When to produce one
|
||||
|
||||
- **Presenting a batch for approval** — after Mode 1 or Mode 3 generation, package the top concepts into a review page instead of (or alongside) `INDEX.md`. Picking 5 of 50 is a *visual* decision; a client shouldn't have to read markdown to make it.
|
||||
- **Pitching a whitelist / co-branded partnership** — the format the source pattern was built for: show the partner exactly what the ad looks like under each handle, with the rollout mechanics spelled out.
|
||||
- **A monthly slate review** (Mode 4) — render the slate's concepts so the account-state call and the pick happen off one link.
|
||||
|
||||
Don't produce one for a single headline tweak or a quick internal gut-check — the markdown output is faster. Reach for the review page when a human who isn't you needs to choose.
|
||||
|
||||
## How it's built
|
||||
|
||||
The template renders entirely from a JSON block near the top of the file — `<script type="application/json" id="review-data">`. Populate it from your generated concepts and everything else renders — tabs, previews, storyboard, copy panel. You do not edit the render code below the data block. The annotated model below is shown with `//` comments for readability; **the file itself is strict JSON** — no comments, no trailing commas (see "Populating the data safely").
|
||||
|
||||
### Data model
|
||||
|
||||
```jsonc
|
||||
{
|
||||
project: {
|
||||
brand: "Truvani", // required
|
||||
agency: "Light Labs", // optional — adds the co-brand line + the default handle fallback (partner label/initials)
|
||||
date: "2026-07-12", // optional
|
||||
note: "one-line context" // optional
|
||||
},
|
||||
platforms: ["instagram", "facebook"], // previews to offer; first is the default. Supported: instagram, facebook
|
||||
concepts: [ // each concept is one strategic ANGLE (see SKILL.md "Define Your Angles")
|
||||
{
|
||||
name: "Heavy-Metal Proof", // required — the angle name
|
||||
tagline: "Lifestyle hero, then the lab results", // one line, what makes this concept distinct
|
||||
handles: [ // optional. 1 entry = normal post; 2 = whitelist handle toggle
|
||||
{ name: "truvani", partner: "Paid partnership with lightlabs", initials: "TV" },
|
||||
{ name: "Light Labs", partner: "Paid partnership with truvani", initials: "LL" }
|
||||
],
|
||||
frames: [ // 1 frame = single ad; multiple = carousel storyboard
|
||||
{
|
||||
label: "Hook", // the frame's job in the narrative arc
|
||||
prompt: "Product bag hero on soft pink, gold-lace overlay", // image description (shown as placeholder if no image)
|
||||
image: "images/heavy-metal-01.png", // optional — URL, relative path, or data URI; omit for text-only concepts
|
||||
headline: "Finally — a plant-based protein that's third-party tested for heavy metals.", // optional per-frame overlay
|
||||
headlineTheme: "dark" // optional: "dark" (default, white text) or "light" (dark text on light imagery)
|
||||
}
|
||||
// … one object per frame
|
||||
],
|
||||
headlines: [ // selectable variations; the picked one overlays frame 1 in the preview
|
||||
"Finally — a plant-based protein that's third-party tested for heavy metals.",
|
||||
"We tested our protein for heavy metals. Here's what an independent lab found.",
|
||||
"Most protein powders are never tested for heavy metals. Ours is."
|
||||
],
|
||||
primaryText: "The caption / body copy.",
|
||||
destination: { url: "shop.truvani.com", cta: "Shop now", offer: "72% OFF Protein Starter Kit" },
|
||||
rollout: { // optional — the mechanics of how this runs (whitelist, launch plan)
|
||||
title: "How the whitelist runs",
|
||||
steps: ["step 1", "step 2", "…"]
|
||||
},
|
||||
grounding: "What in this concept is real — the required disclosure. See below."
|
||||
}
|
||||
// … 2–4 concepts is the sweet spot; more than that and the tabs stop being a decision
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### The frame storyboard = a carousel narrative arc
|
||||
|
||||
A concept's `frames` are its storyboard. Label each frame by the *job it does*, not its content — `Hook`, `The problem`, `The results`, `The ask`. This is the same narrative-arc thinking as the carousel frameworks: a proof-led concept is literally Hook → Problem → Mechanism → Results → Context → Ask. For the five reusable carousel arcs (Value-Stack, Problem-Proof, Hack List, Rant Callout, Demo Walkthrough), see `carousel-frameworks.md` in the **social** skill and pick the arc that fits the angle before writing frames.
|
||||
|
||||
### Images vs. placeholders
|
||||
|
||||
Every frame renders one of two ways:
|
||||
- **`image` provided** — the real creative (from the Mode 3 `images/` folder, a hosted URL, or a data URI) fills the frame.
|
||||
- **`image` omitted** — a styled placeholder shows the frame `label` + `prompt`. This is the intended state for concepts that are copy + image-prompt but not yet rendered to image — the review page is useful *before* images exist, and stays useful as they get filled in.
|
||||
|
||||
Ship review pages with placeholders freely; they communicate the concept. Swap in images as they're generated.
|
||||
|
||||
## Grounding — the disclosure block is required
|
||||
|
||||
Every concept must carry a `grounding` line, and it must be true. This is the same rule as the Grounded Inputs corpus, surfaced to the client: state exactly what is real (which lab panel, which review, which product photography) and, by omission, what is illustrative. The source pattern's line is the model — *"Results are Truvani's actual Light Labs panel (Vanilla, tested Nov 13, 2025). Imagery is Truvani's own product & lifestyle photography."*
|
||||
|
||||
Never present invented stats, fabricated test results, or stock imagery as the brand's own. If a concept's proof isn't real yet, the grounding line says so ("Results shown are illustrative pending the lab panel") — a review page that launders fiction as fact is worse than no review page.
|
||||
|
||||
## Populating the data safely
|
||||
|
||||
The `DATA` lives in a `<script type="application/json" id="review-data">` block — it's inert data (parsed with `JSON.parse`), not executable code, so a value can never run as script. Two rules when you write it:
|
||||
|
||||
- **Valid JSON only** — double-quoted keys and strings, no comments, no trailing commas. (The page shows a clear error banner if the JSON is malformed, so a typo fails loud, not silent.)
|
||||
- **Escape `<` as `\u003c` in every text value.** A value literally containing `</script>` would otherwise close the data block early. Since agents write the JSON, apply this escape mechanically to all string values. All values are HTML-escaped again at render time, so this is defense-in-depth, but the source-level escape is the one that matters — do it.
|
||||
|
||||
## Producing and delivering it
|
||||
|
||||
1. Copy `assets/creative-review-template.html` into the batch's output folder as `review.html` (e.g. `outputs/YYYY-MM-DD/review.html`).
|
||||
2. Replace the `DATA` object with the real project — concepts, frames, copy, grounding. Populate `image` paths for any frames you've rendered (keep them relative to the html file so the folder stays portable).
|
||||
3. Verify it renders: open it in a browser, click through every concept tab, both platform and handle toggles, and each frame in the storyboard.
|
||||
4. Deliver: hand off the folder (html + `images/`), or host it. For a client link, `vercel deploy` or any static host works — it's a single page with local assets.
|
||||
|
||||
Keep the review page next to the markdown outputs, not instead of them: `INDEX.md` and the per-concept files remain the operator's record and the grounding audit trail; `review.html` is the approval surface built on top.
|
||||
|
||||
## Common mistakes
|
||||
|
||||
- **Too many concepts** — 2–4 tabs is a decision; 10 is a menu nobody finishes. Curate before you present.
|
||||
- **Unlabeled or content-labeled frames** — label by narrative job (`The proof`), not by what's pictured (`Table screenshot`).
|
||||
- **Missing or dishonest grounding** — every concept discloses what's real; illustrative proof is labeled illustrative.
|
||||
- **Editing the render code** — everything is data-driven; if something won't show, it's a `DATA` field, not the JS.
|
||||
- **Absolute image paths** — keep image paths relative so the output folder can be zipped, moved, or hosted intact.
|
||||
@@ -0,0 +1,118 @@
|
||||
# The Creative Strategy Loop
|
||||
|
||||
Generation (Modes 1–3) answers "make me ads." This reference answers the question that comes first: **which ads are worth making, in what order, at what production cost** — and the retro that turns each month's results into next month's plan. It's the standing operating loop of a creative strategist, run by an agent with a human deciding.
|
||||
|
||||
```
|
||||
Signals → Concepts (evidence-ranked) → Roadmap (tiered, capacity-checked) → Briefs → [Modes 1–3 produce] → Monthly retro → back into the icebox
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Read the Three Signals
|
||||
|
||||
Creative direction comes from synthesis across three independent signal sources. One source alone misleads: the account tells you what worked *among things you've tried*, customers tell you why they buy *in their words*, and organic content tells you what the audience *chooses to watch when nobody's paying*.
|
||||
|
||||
| Signal | What to pull | How |
|
||||
|---|---|---|
|
||||
| **Account performance** | Winners/losers by angle, hook, format; funnel metrics per concept (see [hook-system.md](hook-system.md) diagnostic funnel); fatigue state | `google-ads` / `meta-ads` / `linkedin-ads` / `tiktok-ads` CLIs (see Tool Integrations in SKILL.md) |
|
||||
| **Customer/brand** | Verbatim pain/desire/objection language; unexpected use cases; who's *actually* buying vs. who's targeted | The Grounded Inputs corpus (`inputs/reviews/`, `inputs/comments/`), sales-call notes, support themes — per **customer-research** |
|
||||
| **External organic** | What the niche watches unpaid: top organic content, its hooks, formats, vocabulary; competitor ads running long enough to be presumed working | **scraping**, the social listening tooling in **social**, ad libraries, **competitor-profiling** |
|
||||
|
||||
**Cadence:** a monthly deep dive (60–90 min, all three sources, feeds the monthly roadmap) plus a weekly ~20-minute refresh (what changed: new winners/losers, new review themes, anything spiking organically). Research beyond what the next decision needs is busywork — every synthesis session should end in concepts, not notes.
|
||||
|
||||
**Trust rule:** every insight the agent surfaces must carry its receipt — which review, which ad's metrics, which organic post. An insight without a source doesn't enter the icebox. (Same grounding rules as everything else in this skill.)
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Turn Signals into Evidence-Ranked Concepts
|
||||
|
||||
A **concept** is one testable creative hypothesis: *segment × motivation × angle × format*, with its evidence attached. "UGC for moms" is not a concept; "new-parent insomniacs (per 40+ reviews mentioning 3am feeds) × 'quiet enough to not wake the baby' × before/after demo × POV night-shot video" is.
|
||||
|
||||
Rank every concept by the strongest evidence supporting it:
|
||||
|
||||
| Tier | Evidence | Weight |
|
||||
|---|---|---|
|
||||
| 1 | Your own account: a converting ad with the same angle/segment | Strongest — iterate and extend |
|
||||
| 2 | Your customers verbatim: recurring review/call language | Strong — build new creative on it |
|
||||
| 3 | Competitor creative running 60+ days (presumed working) | Good — adapt the angle, never the ad |
|
||||
| 4 | Organic engagement in the niche (unpaid views/saves on the theme) | Moderate — validate cheaply first |
|
||||
| 5 | Cross-niche pattern (worked in an adjacent category) | Weak — icebox until corroborated |
|
||||
| 6 | Team hunch, no external signal | Weakest — low-fi test or drop |
|
||||
|
||||
Higher evidence earns roadmap *priority* — an earlier slot in the slate. Production tier is a separate call, set by validation strength, existing assets, capacity, and risk: even a tier-2 customer-language concept starts low-fidelity until it shows a funnel signal. Hunches aren't banned — they're just cheap and last.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Branch on Account State
|
||||
|
||||
The right creative mix depends on which of two states the account is in. Diagnose before roadmapping — a plan built for the wrong state wastes the month.
|
||||
|
||||
**Exploration state** — nothing (or nothing new) is working:
|
||||
- Go **wide, not deep**: mostly net-new concepts across different segments and angles; keep iterations to a small minority — iterating on losers multiplies losers
|
||||
- **Redefine "win" per-metric**: with no full-funnel winners, a single-metric improvement (a hold-rate lift, a CPC drop, a CVR bump) on any test is a hit worth pulling on — see the diagnostic funnel
|
||||
- Iterate **only on hits**; everything else stays exploratory
|
||||
- Common root causes to check while testing: the creative is boring (safe, seen-before), the message is overcomplicated, the offer/UVP is unclear, or CPMs are punishing a too-narrow audience
|
||||
|
||||
**Scaling state** — one or more concepts are converting profitably:
|
||||
- Go **deep on the winner** while it's open: a winner-led slate of visually-distinct variations of the winning concept (same message, new execution — near-duplicates mostly cannibalize the original's reach and teach you nothing new, so variations must look meaningfully different), plus a remix lane (tonal/emotional re-executions of it) and sub-angle probes drilling *into* the winning segment; tune the split to budget, fatigue speed, and production velocity
|
||||
- Keep a small exploration allocation alive even mid-scale — winners fatigue, and the next winner is rarely an iteration of the current one
|
||||
- Speed matters more in this state: a scaling window is finite
|
||||
|
||||
---
|
||||
|
||||
## Step 4: The Roadmap Artifact
|
||||
|
||||
Maintain one living document (suggested: `roadmap.md` beside the Grounded Inputs corpus) with three horizons:
|
||||
|
||||
```
|
||||
## Icebox — every concept, evidence tier + source attached, nothing scheduled
|
||||
## This quarter — 2-4 themes chosen from the icebox (the bets), with why-now
|
||||
## This month — the slate: concept | evidence tier | production tier | owner | status
|
||||
```
|
||||
|
||||
Each monthly-slate concept gets a **production tier**:
|
||||
|
||||
| Tier | Cost | What it is | Use for |
|
||||
|---|---|---|---|
|
||||
| **T1 — Iteration** | Hours | New hook/caption/crop on an existing asset | Extending proven winners |
|
||||
| **T2 — Remix** | Days | New creative from existing footage/assets/AI generation | Concepts with decent evidence or a first low-fi signal |
|
||||
| **T3 — Production** | Weeks | Net-new shoot, creators, full build | Only angles with own-account proof or a prior low-fi funnel signal (fidelity ladder in [hook-system.md](hook-system.md)) |
|
||||
|
||||
**Capacity check — the rule that keeps roadmaps honest:** count what the team (or the AI pipeline) can produce *at quality* this month, and roadmap to that number. A 20-concept slate against 8 concepts of real capacity doesn't produce 20 ads; it produces 20 compromised ones and a burned-out team. Cut by evidence rank until the slate fits.
|
||||
|
||||
From the slate, generate **one brief per concept** (segment, motivation + verbatim source, angle, format, hook matrix rows, production tier, success metric) and hand each to Modes 1–3 for production.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: The Monthly Creative Retro
|
||||
|
||||
Last step of the loop, first input of the next one. One artifact per month (suggested: `retros/YYYY-MM.md`):
|
||||
|
||||
```
|
||||
## Winners — concept, the funnel numbers, and the WHY (which element earned it)
|
||||
## Losers — concept, where in the funnel it died, hypothesis for why
|
||||
## Metric wins — full-funnel losers with one strong metric (these are leads, not losses)
|
||||
## Learnings — pattern-level notes → written back into the icebox as new/revised concepts
|
||||
## Kills — concepts retired from the icebox, with reason
|
||||
## Next slate — first draft of next month, updated evidence ranks
|
||||
```
|
||||
|
||||
Retro rules:
|
||||
|
||||
- **Judge concepts, not ads.** Three executions of one concept failing says the concept is wrong; one failing says the execution was.
|
||||
- **Read the funnel, not the ROAS column.** The diagnostic funnel says *what* to fix; ROAS alone says only *that* something is broken.
|
||||
- **Enough data before verdicts** — respect the impression/spend thresholds in Common Mistakes and the **ads** skill's decision systems; a two-day read is a coin flip.
|
||||
- **Every learning lands somewhere**: icebox update, evidence re-rank, or kill. A retro that changes nothing in the roadmap was a meeting, not a retro.
|
||||
|
||||
To run this loop on a schedule (retro on the 1st, weekly refresh Mondays, daily batches via Mode 3), see the creative loops in **marketing-loops**.
|
||||
|
||||
---
|
||||
|
||||
## Failure Modes
|
||||
|
||||
- **Roadmapping without a diagnosis** — a slate built before reading the three signals is a wish list; testing without a diagnosis isn't strategy
|
||||
- **Iteration-heavy slates in exploration state** — polishing losers while the real problem (angle, offer, audience) goes untested
|
||||
- **Ignoring capacity** — the plan the team can't produce at quality is a plan to produce slop
|
||||
- **Evidence-free concepts jumping the queue** — the loudest stakeholder's hunch ships as a T3 shoot while tier-2 customer language sits in the icebox
|
||||
- **Retro as theater** — winners celebrated, nothing re-ranked, icebox untouched
|
||||
- **Scaling-state complacency** — 100% of the slate on winner variations; when the winner fatigues, the pipeline is empty
|
||||
@@ -0,0 +1,115 @@
|
||||
# The Hook System
|
||||
|
||||
The first three seconds decide whether the rest of the ad exists. Hooks are the highest-leverage unit of paid creative work — and hook *diversity* is what earns incremental learning: distinct hooks reach distinct pockets of the audience, while near-identical openings mostly re-test what you already know about the same one. This reference is a complete system for generating, diagnosing, and iterating hooks — not a list of one-liners.
|
||||
|
||||
Use it inside Mode 1/3 generation (hooks for new concepts), Mode 2 iteration (diagnosing why an ad underperforms), and the creative strategy loop in [creative-roadmap.md](creative-roadmap.md).
|
||||
|
||||
---
|
||||
|
||||
## A Hook Is Three Components, Not a Line
|
||||
|
||||
In video, the hook is the simultaneous combination of:
|
||||
|
||||
| Component | What it is | Job |
|
||||
|---|---|---|
|
||||
| **Visual action** | What is literally happening on screen in seconds 0–3 | Stop the thumb |
|
||||
| **Spoken line** | The first words of VO or dialogue | Open the loop |
|
||||
| **Caption text** | On-screen header/overlay text | Anchor the claim for sound-off viewers |
|
||||
|
||||
**The no-duplication rule:** the three components must complement, never repeat. If the VO says "I stopped paying $200/mo for my gym" while the caption reads "I stopped paying $200/mo" over a static talking head, two of the three slots are wasted. Strong hooks split the work — visual shows the cancellation email, VO says the line, caption names the alternative. When writing hooks, write all three columns explicitly; a hook spec with one column filled in is a third of a hook.
|
||||
|
||||
Static ads collapse this to two components (visual + headline) — the same rule applies: the headline must not caption the image.
|
||||
|
||||
---
|
||||
|
||||
## The Generation Pipeline
|
||||
|
||||
Work top-down; hooks written without the upstream steps read like everyone else's ads.
|
||||
|
||||
```
|
||||
Segment → Motivation → Format → Hook (three components)
|
||||
```
|
||||
|
||||
1. **Segment** — which specific buyer this hook addresses. Not the whole ICP: a slice with a shared situation (from the Grounded Inputs corpus: reviews, comments, sales-call language). The narrower the segment, the sharper the hook.
|
||||
2. **Motivation** — the single pain, desire, or objection that moves this segment, in *their* words. Pull verbatim phrases from reviews and comments; the corpus language always outperforms marketing paraphrase.
|
||||
3. **Format** — the delivery vehicle: street interview, POV selfie, screen recording, unboxing, side-by-side demo, text-on-screen static, founder-to-camera, reaction stitch. Pick the format *before* writing the line — the same motivation reads completely differently as a street-interview answer vs. a confession-to-camera.
|
||||
4. **Hook** — now write the three components for this segment × motivation × format cell.
|
||||
|
||||
**Output as a hook matrix** so coverage is visible:
|
||||
|
||||
```
|
||||
| # | Segment | Motivation (verbatim source) | Format | Visual action | Spoken line | Caption |
|
||||
```
|
||||
|
||||
Generate across the matrix, not down a single column — ten hooks for ten segment×motivation cells beat thirty rewordings of one cell. This is the same angle-diversity principle as the static template library: matrix diversity is audience diversity.
|
||||
|
||||
---
|
||||
|
||||
## Hook Opening Moves
|
||||
|
||||
A menu of proven opening structures. Cycle through them like the static templates — don't cluster on favorites:
|
||||
|
||||
| Move | Shape | Watch out |
|
||||
|---|---|---|
|
||||
| **Curiosity gap** | Withhold the noun: "Nobody tells you what actually causes this" | Must pay off within the ad or it's clickbait that poisons CVR |
|
||||
| **Bold claim** | A specific, falsifiable statement: "This replaced my entire morning routine" | Needs substantiation on screen or in the on-ramp |
|
||||
| **First-person confession** | "I was doing [common thing] completely wrong" | Reads fake without lived-in detail |
|
||||
| **Contrast / before-after** | Two states shown or named in the first beat | The transformation must be visually honest — see compliance notes in SKILL.md |
|
||||
| **Relatability / POV** | Mirror a hyper-specific situation: "POV: it's 3pm and you're on your fourth coffee" | Specificity is the entire mechanic; generic POV is invisible |
|
||||
| **Question** | Ask the exact question the buyer types into search or ChatGPT | Use their phrasing verbatim from the corpus |
|
||||
| **Countdown / gamified** | A timer or on-screen challenge that promises a payoff at the end | Payoff must exist; hold-rate collapses on cheats |
|
||||
| **Proof-first** | Lead with the receipt — the result screenshot, the stat, the demo money-shot | Strongest when the proof brags by itself |
|
||||
|
||||
---
|
||||
|
||||
## The Diagnostic Funnel
|
||||
|
||||
Each metric in the delivery funnel isolates a different component. When an ad underperforms, read the funnel to find *which part* to fix instead of scrapping the whole ad:
|
||||
|
||||
| Stage | Metric | If it's weak, the problem is | Fix |
|
||||
|---|---|---|---|
|
||||
| Stop | Thumbstop / 3-sec view rate | **Visual action** (and caption) | New visual opening; same everything else |
|
||||
| Stay | Hold rate (3s → 15s / 50% view) | **The on-ramp** — what follows the hook | Rework seconds 3–15, not the hook |
|
||||
| Click | CTR | Desire/offer clarity mid-ad | Sharpen the promise, CTA, or proof |
|
||||
| Convert | CVR post-click | Congruence — the page doesn't continue the ad | Fix the landing page or the claim, per **cro** |
|
||||
|
||||
Two rules this table enforces:
|
||||
|
||||
- **A great thumbstop is not a great ad.** A clickbait visual that attracts the wrong viewers shows up as high thumbstop + collapsed hold/CVR. Read the whole funnel before declaring a winning hook.
|
||||
- **One component per iteration.** Change the visual OR the on-ramp OR the offer framing per test cycle — matching the one-variable rule in Common Mistakes.
|
||||
|
||||
---
|
||||
|
||||
## The On-Ramp Rule
|
||||
|
||||
The on-ramp is seconds ~3–15: the bridge from hook to body. **A good on-ramp logically extends the hook's premise; a bad one pivots to a product pitch that abandons it.** If the hook promises "what actually causes this," the next beat must start explaining the cause — not introduce the brand story.
|
||||
|
||||
Corollary: **every hook test is also an on-ramp test.** Swapping a new hook onto an existing ad body usually breaks the premise-bridge; when testing hooks, re-write the on-ramp to match each one. Hold rate is the on-ramp's metric — diagnose it separately from thumbstop.
|
||||
|
||||
---
|
||||
|
||||
## Fidelity Laddering
|
||||
|
||||
Match production cost to evidence strength (production tiers are defined in [creative-roadmap.md](creative-roadmap.md)):
|
||||
|
||||
- **Hunches ship low-fidelity within a day or two:** statics, text-on-screen video, voiceover-over-b-roll, remixes of existing footage. The goal is a cheap signal on the *angle*, not a polished ad.
|
||||
- **Validated angles earn high-fidelity:** creator shoots, street interviews, staged demos. Only spend production budget on hooks whose low-fi version already showed a funnel signal (even a single-metric win — a hold-rate spike on an ugly static is evidence).
|
||||
|
||||
Testing a hunch with an expensive shoot and testing a proven angle with a throwaway static are both mistakes — the ladder runs in one direction.
|
||||
|
||||
---
|
||||
|
||||
## Grounding Rules (inherited, non-negotiable)
|
||||
|
||||
Hooks inherit every grounding rule from SKILL.md: every hook cites the corpus source its motivation came from; no invented claims, stats, or testimonials; verbatim customer language over paraphrase. Additionally, mine **organic content in the niche** (top-performing TikToks/Reels/posts, via the **scraping** skill or the social listening tooling in **social**) for the audience's actual vocabulary — the words the niche uses ("GLP-1" vs. the clinical term, the slang for the pain) belong in the caption and spoken line. Organic mining is language research, not copying: take the vocabulary and the visual conventions, never a creator's specific creative.
|
||||
|
||||
---
|
||||
|
||||
## Common Failure Modes
|
||||
|
||||
- **Thirty rewordings of one cell** — variation without matrix coverage; diversity of segment×motivation is the point
|
||||
- **Components duplicating each other** — three slots saying one thing
|
||||
- **Hook tested, on-ramp inherited** — premise-bridge broken, hold rate blamed on the hook
|
||||
- **Funnel read stops at thumbstop** — clickbait winners scale into CVR craters
|
||||
- **Polished hunches** — high-fidelity production spent on unvalidated angles
|
||||
- **Marketing-voice captions** — the corpus and the niche's organic content define the vocabulary; "revolutionary formula" appears in neither
|
||||
@@ -1,6 +1,6 @@
|
||||
# iMessage Chat-Reveal Video Ads
|
||||
# iOS-Native Reveal Video Ads (iMessage, ChatGPT, Apple Notes, AirDrop)
|
||||
|
||||
A 9:16 social-native video format that recreates an iMessage conversation unfolding in real time: someone sends a screenshot of a result or product, a friend reacts and asks what it is, and the conversation reveals the brand — usually with a promo code. Message bubbles pop in over ~15–22 seconds with authentic send/receive sounds, then a static brand end card lands the CTA.
|
||||
A family of 9:16 social-native video formats that recreate a familiar iOS surface in real time and let the brand emerge inside it. The flagship is the **iMessage chat reveal** — someone sends a screenshot of a result or product, a friend reacts and asks what it is, and the conversation reveals the brand, usually with a promo code. Message bubbles pop in over ~15–22 seconds with authentic send/receive sounds, then a static brand end card lands the CTA. The same architecture powers **ChatGPT reveals**, **Apple Notes reveals**, and **AirDrop reveals** — covered in [Other iOS-Native Reveal Surfaces](#other-ios-native-reveal-surfaces) below.
|
||||
|
||||
The format works because it borrows the most-read UI on earth. A chat thread is a familiar, high-attention dramatization — it mirrors how real recommendations happen, so the viewer leans in instead of scrolling past. The CTA arrives conversationally ("use code FREEPACK") instead of as a hard sell, which keeps the ad-skip reflex from firing until the pitch has already landed. Run it only as a clearly labeled paid placement (Meta's "Sponsored" tag does the disclosure work); never seed it organically as if it were a real leaked conversation.
|
||||
|
||||
@@ -144,4 +144,58 @@ Treat the thread as the variable and the pipeline as fixed. Test in this order
|
||||
4. **Peer persona** — name, avatar, and texting style shift the perceived audience
|
||||
5. **Length** — try a 12-bubble and an 8-bubble cut of the same script
|
||||
|
||||
The same architecture extends to other chat surfaces — a ChatGPT conversation reveal, WhatsApp, Slack — same timeline-driven recording, different UI shell. Start with iMessage; it has the highest recognition and the strongest audio identity.
|
||||
The same architecture extends to further surfaces too — WhatsApp, Slack, a search box — same timeline-driven recording, different UI shell.
|
||||
|
||||
---
|
||||
|
||||
## Other iOS-Native Reveal Surfaces
|
||||
|
||||
Everything above about production (UI mockup → timeline-driven continuous recording → deterministic SFX cues → static end card), grounding, and disclosure carries over unchanged. What changes per surface is the *persuasion mechanic* and a handful of craft details.
|
||||
|
||||
| Surface | Persuasion mechanic | Reach for it when |
|
||||
|---|---|---|
|
||||
| **iMessage** | A friend's recommendation — social proof through dialogue | The product is discovered through results people share ("what app is that?") |
|
||||
| **ChatGPT** | An authoritative answer to the viewer's own question | The problem is question-shaped — something people would literally type into ChatGPT |
|
||||
| **Apple Notes** | A private confession made public — first-person, no dialogue | The angle is transformation or realization ("things nobody told me about 45") |
|
||||
| **AirDrop** | A spontaneous peer share — "someone nearby thought this was worth sending you *right now*," with a built-in accept/decline decision | The product is something people pass to each other (a deal, a link, a find, a file) and the accept-tap can *be* the reveal |
|
||||
|
||||
The strongest signal for choosing: which of these surfaces already fills your audience's day. Recommendation products want iMessage; advice-seeking problems want ChatGPT; identity/transformation stories want Notes; and anything people spontaneously pass to each other wants AirDrop.
|
||||
|
||||
### ChatGPT Reveal
|
||||
|
||||
The viewer identifies with the *asker*. The typed question is the hook and must be the target customer's verbatim question — awkward phrasing and all ("why is my stomach so bloated all of a sudden at 47?"). The streaming answer names the problem's real mechanism, then the solution category; the brand lands in the answer's recommendation or in a typed follow-up ("what's the best one?").
|
||||
|
||||
**Craft details:**
|
||||
- **Stream the answer in word chunks**, not character-by-character (that's typing, not generation) and not whole paragraphs at once. A subtle tick underneath the stream and a clean stop when the response completes; no iMessage tritones anywhere.
|
||||
- **Type the question like thumbs, stream the answer like a model.** Two distinct rhythms — the contrast is what reads as "real ChatGPT."
|
||||
- **Keep the answer scannable:** short paragraphs, a bolded phrase or a short list, exactly the way ChatGPT actually formats. A wall of text breaks the illusion and loses the viewer.
|
||||
- OpenAI's interface is their trade dress — same legal-review posture as the Apple UI mimicry note above, with a generic "AI assistant" skin as the fallback.
|
||||
|
||||
**Compliance — stricter here than anywhere else in this family.** The "answer" is your ad copy wearing a lab coat: an authority costume. Every claim in it needs the same substantiation as a claim in your own voice, and the format's borrowed authority raises the bar, not lowers it. Do not put health, medical, or financial advice in a fabricated AI answer without legal review — that's the highest-risk version of this format. And never present the exchange as a real, unprompted ChatGPT output endorsing your product; it's a dramatization, same as the iMessage thread.
|
||||
|
||||
### Apple Notes Reveal
|
||||
|
||||
A different genre from the chat formats: **confession, not conversation.** The viewer watches someone type a private note — a list of realizations, a "things I wish I knew" entry — with the keyboard visible. The note's title is the hook and does the job slide 1 does in a carousel ("Things nobody told me about 45."). The product appears as one item in the list, named the way a person would actually write it to themselves — not the way a brand would.
|
||||
|
||||
**Craft details:**
|
||||
- **Audio is keyboard taps only.** No chat SFX, no receive tones — a note has no other party. A quiet music bed still works underneath.
|
||||
- **Type at real thumb pace with jitter**, same as the iMessage composer rule. One typo-and-correction reads as human; several read as staged.
|
||||
- **Get the Notes chrome right:** title styled larger than body, the formatting bar above the keyboard, iOS-yellow accents. Same HTML-mimicry approach — and the same Apple trade-dress review note and generic-notes-app fallback — as everything else here.
|
||||
- **Fit the note to the frame.** Write short enough that the whole note fits without scrolling, or scroll once, deliberately, late.
|
||||
- **First person or it doesn't work.** The moment the note reads like ad copy ("[Brand] changed everything!"), the intimacy that makes the format convert is gone. The product mention should be the *least* enthusiastic line in the note.
|
||||
|
||||
The grounding rule hits differently here: the confession is a dramatization of a *composite, true* customer story — pull the realizations from real reviews and interviews (the Grounded Inputs corpus), and keep any numbers or outcomes to documented ones.
|
||||
|
||||
### AirDrop Reveal
|
||||
|
||||
The one interaction-native format in the family: the hook is an **incoming AirDrop request**, and the **Accept tap is the reveal**. The viewer watches from the *receiver's* POV — a translucent AirDrop card slides up, "[Sender] would like to share [preview]," with a gray Decline and a blue Accept. The curiosity is structural ("what is this and who's sending it?") and the accept/decline choice is a built-in micro-conversion beat baked into iOS itself. Tapping Accept transfers the item — and *that's* where the product, the offer, or the result lands.
|
||||
|
||||
**Craft details:**
|
||||
- **The preview thumbnail is the hook.** It's the one image on the AirDrop card before Accept, so it has to earn the tap — same job as the iMessage screenshot attachment. Make it the result, the product money-shot, or the offer.
|
||||
- **Cast the sender name like a real share.** "Sarah's iPhone," "Mom," "Jordan's MacBook" reads native; a brand name in the sender slot reads like an ad — save brand-as-sender for the reveal, not the incoming card.
|
||||
- **The transfer progress ring is the signature motion — don't skip it.** Incoming card → a beat of hesitation ("accept?") → the Accept tap → the circular progress fills → the item lands + end card. That progress-ring beat is what makes it read as a real AirDrop and not a cut.
|
||||
- **Audio is the AirDrop swoosh / received tone**, not the iMessage tritones. Same CC0-Apple-sounds sourcing and the same Apple trade-dress review note as the rest of the family, with a generic "nearby share" skin as the fallback.
|
||||
- **Keep it short and get the material right.** The card's blur/translucency and the gray Decline / blue Accept button pair are the recognizable cues; a flat opaque sheet breaks the illusion. The whole beat is faster than the chat formats — the interaction *is* the ad.
|
||||
- **Receiver POV by default; sender POV as the flex.** Receiving reads as discovery ("someone sent me this"); sending reads as a recommendation you're making ("had to AirDrop this to the group") — use sender POV when the angle is advocacy rather than discovery.
|
||||
|
||||
Grounding is the same family rule: it's a dramatization of a share, not a claim that a real person actually AirDropped your product. Every claim on the transferred item is substantiated per the Grounded Inputs rules, and the exchange is never presented as a real, unprompted endorsement.
|
||||
|
||||
@@ -0,0 +1,126 @@
|
||||
# Motion-Style Video Ads (Faceless, Fully Generated)
|
||||
|
||||
> Format popularized by Borja ([@borjafat](https://x.com/borjafat)) and the open `super-video-maker` motion-collage recipe by [Bomx](https://github.com/Bomx/super-video-maker-skill); this guide is an original re-expression of the method, extended with a multi-style library and production lessons from building and shipping it end-to-end.
|
||||
|
||||
Produce a 15–45s faceless video ad or explainer from nothing but a concept: a styled
|
||||
poster still (image model) → brought to life with subtle motion (image-to-video model)
|
||||
→ narrated (TTS) → word-timed captions. No footage, no presenter, no editor. Cost per
|
||||
finished video is roughly $3–6 in API calls; wall-clock ~15 minutes.
|
||||
|
||||
The format works because the *still* carries the idea (one literal, slightly surreal
|
||||
visual per beat) and the *motion* only makes it breathe. Resist the urge to make the
|
||||
video do the storytelling — this is animated poster design, not filmmaking.
|
||||
|
||||
## When to use
|
||||
|
||||
- Concept/explainer ads: one idea made concrete ("your CRM is a junk drawer")
|
||||
- Top-of-funnel social video (9:16 Reels/Shorts/TikTok, 4:5 and 1:1 feed)
|
||||
- Brand-response hybrids where a distinctive owned style beats stock UGC
|
||||
- NOT for: demo/proof ads (screen recordings win), testimonial/UGC formats,
|
||||
anything requiring a real product shot as evidence
|
||||
|
||||
## Pipeline (provider-agnostic)
|
||||
|
||||
1. **Script** 3–6 beats, 20–45s of VO. One idea per beat. Calm and specific beats
|
||||
hype. End on a single CTA line.
|
||||
2. **Poster stills** — one per beat, using a *style formula* (below). Generate beat 1,
|
||||
approve it, then pass it as a reference image for every later beat so the set reads
|
||||
as one series. Fix garbled label text by regenerating with a shorter phrase.
|
||||
3. **Animate** each approved still with an image-to-video model (5–8s per beat).
|
||||
Motion belongs to the objects in the frame; the composition must not change.
|
||||
4. **VO + captions**: one continuous TTS take, transcribe with word timestamps
|
||||
(whisper), cut beats at sentence boundaries, burn 2–3-word caption groups.
|
||||
5. **Assemble**: concat beats trimmed to their VO spans (hold the last frame to pad),
|
||||
loudness-normalize to `I=-16:TP=-1.5:LRA=11`, export per-placement aspect.
|
||||
|
||||
**Provider options** (any combination works; the recipe is model-agnostic):
|
||||
|
||||
| Stage | One-key Gemini path | Alternatives |
|
||||
|---|---|---|
|
||||
| Stills | Nano Banana Pro (`gemini-3-pro-image-preview`) — excellent label typography | GPT-Image, Flux, Ideogram |
|
||||
| Motion | Veo 3.1 fast image-to-video (note: 1080p requires 8s clips) | Seedance 2.0 via fal.ai, Kling, Runway |
|
||||
| VO | Gemini TTS (calm voices: Charon/Kore) | ElevenLabs, OpenAI TTS |
|
||||
| Captions | whisper word timings + PIL/ASS burn-in | CapCut, platform auto-captions |
|
||||
|
||||
## The style library
|
||||
|
||||
Five proven looks. Each is a fill-in-the-slots prompt formula; keep ONE style per
|
||||
campaign so the account builds a recognizable visual identity. All five animate well.
|
||||
|
||||
### A. Screen-print collage (editorial, "In a Nutshell" docu energy)
|
||||
> Flat screen-print collage poster, single saturated `<COLOR>` background, subtle newsprint grain. Centerpiece: a black-and-white halftone cutout of `<SUBJECT DOING THE LITERAL CONCEPT>`, treated as a paper sticker with a thin white die-cut outline, slightly torn edges, and a soft drop shadow. Visible halftone dot texture, vintage editorial photo feel, grayscale subject. Accent cutouts: 2–4 flat shapes (cream circle sun, black zigzag, scattered dots). A torn-paper label near the bottom with the words "`<LABEL>`" in bold condensed uppercase newspaper type. Matte printed risograph aesthetic, limited palette. No gradients, no glow, no 3D, no photorealism, no extra text.
|
||||
|
||||
### B. Flat vector explainer (clean, techy, infinitely brandable)
|
||||
> Flat vector explainer illustration in the style of a premium animated science channel: a friendly simplified `<SUBJECT>`, bold flat shapes with clean rounded edges, solid `<BRAND COLOR>` background, limited palette of `<2-3 ACCENTS>`, flat geometric accents, soft long shadows, completely flat 2D design. A clean rectangular banner near the bottom reads "`<LABEL>`" in bold geometric sans-serif uppercase. No outlines, no 3D, no photorealism, no texture, no extra text.
|
||||
|
||||
### C. Papercraft diorama (warm, tactile, premium-crafty)
|
||||
> Layered papercraft diorama: `<SUBJECT>`, every element hand-cut from colored construction paper with visible paper thickness and real drop shadows between layers, `<COLOR>` paper background with cut-paper accents, tactile handmade craft feel with slightly imperfect scissor cuts. A cut-paper banner near the bottom reads "`<LABEL>`" in chunky cut-out paper letters. Soft studio lighting on the paper layers. No digital gradients, no photorealistic humans, no extra text.
|
||||
|
||||
### D. Pop-art comic (loud, scroll-stopping, promo-friendly)
|
||||
> Vintage pop-art comic panel: `<SUBJECT>`, bold black ink outlines, Ben-Day halftone dots shading, flat process colors (`<PALETTE>`), comic starburst accents, thick panel border, aged newsprint paper texture. A comic caption box near the bottom reads "`<LABEL>`" in bold comic lettering. 1960s printed comic aesthetic, slight ink misregistration. No 3D, no photorealism, no gradients, no extra text.
|
||||
|
||||
### E. Claymation (charming, high pattern-interrupt)
|
||||
> Stop-motion claymation scene: a charming handmade plasticine `<SUBJECT>`, visible fingerprints and clay texture, `<COLOR>` clay backdrop and floor, chunky clay props, warm soft studio lighting like a stop-motion film set, shallow depth of field. A small clay sign near the bottom reads "`<LABEL>`" in hand-molded clay letters. Handcrafted miniature feel. No 2D illustration, no photorealistic humans, no extra text.
|
||||
|
||||
## Brand-flexible styles (token-driven)
|
||||
|
||||
The five looks above are *characterful* — they impose their own palette. This second
|
||||
tier is *brand-first*: each style is defined by *slots*, so any company's tokens drop
|
||||
in and the output reads as that brand's own design system.
|
||||
|
||||
**The brand slots contract.** Before generating, resolve these from the brand's
|
||||
guidelines (or `.agents/product-marketing.md`):
|
||||
|
||||
- `FIELD` — the neutral ground (brand white/off-white, or brand dark)
|
||||
- `INK` — the drawing/type color (brand gray/charcoal, near-black)
|
||||
- `ACCENT` — ONE brand color or gradient, used sparingly (a rule, a beam, a square)
|
||||
- `TYPE FEEL` — the brand's typographic voice ("clean modern grotesque sans", "geometric sans", "mono captions")
|
||||
- Any per-brand constraints (e.g. "gradients only on borders/edges, never fills")
|
||||
|
||||
Keep the accent genuinely scarce — one element per frame. Scarcity is what makes
|
||||
these read as designed rather than generated.
|
||||
|
||||
### F. Monoline editorial (the most universally brandable)
|
||||
> Minimal editorial monoline illustration poster: `<SUBJECT>`, drawn entirely in elegant thin single-weight `<INK>` lines on a clean `<FIELD>` background, the style of a premium tech company blog illustration. Sparse composition with generous whitespace, a few small monoline accent details, and ONE restrained `<ACCENT>` element: `<a thin accent underline sweep / a small accent arc>`. A small caption near the bottom reads "`<LABEL>`" in `<TYPE FEEL>`, `<INK>`, letterspaced uppercase, with a thin `<ACCENT>` underline. Precise, technical, refined. No fills except the single accent, no gradients, no 3D, no photorealism, no texture, no extra text.
|
||||
|
||||
### G. Swiss typographic (type IS the visual — any brand with a font and a color)
|
||||
> Swiss International Typographic Style poster: the words "`<LABEL>`" set enormous in a bold `<TYPE FEEL>`, `<INK>` on a `<FIELD>` background, filling the upper two thirds with tight leading and cropped edges. A small black-and-white photographic cutout of `<SUBJECT>` sits on a thin baseline grid in the lower third, aligned to an asymmetric grid with one thin `<ACCENT>` rule line and a small `<ACCENT>` square as the only color. Visible faint grid lines, precise margins, mathematical composition. Flat, printed, matte. No gradients, no 3D, no decoration, no extra text beyond the label and one small letterspaced caption line.
|
||||
|
||||
### H. Wireglow (dark keynote — dev-tool / dark-mode brands)
|
||||
> Dark minimal tech-keynote poster: `<SUBJECT>` rendered as an elegant thin light-gray wireframe line drawing on a near-black `<FIELD>` background with subtle film grain. From `<the focal object>` emanates a soft narrow beam of glowing `<ACCENT>` gradient light, the only color, feathered and atmospheric. Faint thin concentric geometric guide circles. A caption near the bottom reads "`<LABEL>`" in `<TYPE FEEL>`, light gray, letterspaced uppercase, with a hairline gradient rule beneath it. Restrained, premium, technical. No photorealism, no 3D render look, no busy elements, no extra text.
|
||||
|
||||
### I. Duotone screenprint (photo brands — editorial punch from two tokens)
|
||||
> Bold duotone screenprint photo poster: a dramatic photograph of `<SUBJECT>`, reproduced as a two-color screenprint — `<INK>` for the shadows and `<ACCENT>` for the highlights — on an off-white `<FIELD>` paper background with visible coarse halftone grain and slight ink misregistration. Strong diagonal composition, the figure large and cropped. A wide solid `<INK>` bar near the bottom carries the words "`<LABEL>`" reversed out in bold condensed `<TYPE FEEL>` uppercase, with a small `<ACCENT>` square bullet. Editorial poster energy, matte printed feel. No gradients beyond the duotone, no 3D, no extra text.
|
||||
|
||||
**Motion notes for this tier**: F/G animate as drawing motions (lines extend, the accent
|
||||
sweep draws itself, type settles by a few pixels); H animates as beam pulse + slow
|
||||
wireframe rotation feel; I as grain shimmer + slow push. Same hard rules apply — motion
|
||||
belongs to existing elements, composition never changes.
|
||||
|
||||
## Motion prompt formula
|
||||
|
||||
> Subtle living-`<style>` motion of the existing elements only. `<ONE literal motion tied to the concept: the pile inflates / the arrow creeps higher / the megaphone trembles with each shout>`. `<Secondary ambient motion: accents drift, gentle push-in>`. Every element that is visible now is the only thing that ever appears; the composition stays exactly as it is. Everything stays `<style descriptor: a flat printed collage / flat 2D vector / cut paper / printed comic / handmade clay>`. No camera whip, no scene change, no morphing, no added text.
|
||||
|
||||
## Hard-earned gotchas
|
||||
|
||||
- **Video models love adding photoreal "maker hands"** reaching into frame, especially
|
||||
on pressing/handling motions — and *negative prompts make it worse* ("no hands" is an
|
||||
attention trap). Never mention hands; describe motion as belonging to the objects,
|
||||
and include "the composition stays exactly as it is."
|
||||
- **Always QC each clip's final 2 seconds** — that's where intruding objects and style
|
||||
drift appear. Trim before them or regenerate; never ship a "realified" frame.
|
||||
- **One dominant motion per beat.** Two motions read as chaos at feed speed.
|
||||
- **TTS + whisper disagree on sound-alikes** ("laws" → "loss"). Read the transcript
|
||||
against the script before burning captions; prefer phoneme-unambiguous CTA wording.
|
||||
- **Keep captions clear of the label band** (captions ~60% height, label ~80%).
|
||||
Clamp caption groups so two never overlap; shrink-to-fit long groups.
|
||||
- **Ad-specific**: put the brand/label in the poster itself (it survives sound-off
|
||||
autoplay), front-load the concept in beat 1 (the 3-second hook is the poster), and
|
||||
export 9:16 + 4:5 + 1:1 from the same beats by regenerating stills per aspect
|
||||
rather than cropping.
|
||||
|
||||
## Compliance
|
||||
|
||||
Fully synthetic characters — no likeness/UGC disclosure issues, but check platform
|
||||
AI-content disclosure requirements (Meta and TikTok label AI-generated media).
|
||||
Don't fabricate statistics or testimonials in the VO; ground every claim.
|
||||
@@ -2,7 +2,7 @@
|
||||
name: ai-seo
|
||||
description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' 'optimize for Claude/Gemini,' 'llms.txt,' 'OKF,' 'Open Knowledge Format,' 'knowledge bundle,' or 'agent-readable site.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema."
|
||||
metadata:
|
||||
version: 2.1.0
|
||||
version: 2.2.0
|
||||
---
|
||||
|
||||
# AI SEO
|
||||
@@ -381,6 +381,8 @@ Not all content is equally citable. Prioritize these formats:
|
||||
- Content without dates or author attribution
|
||||
- PDF-only content (harder for AI to parse)
|
||||
|
||||
**Citation ≠ recommendation.** Getting cited means your content was useful to consult; getting *recommended* — onto the buyer's actual shortlist — is governed by web-wide consensus (reviews, forums, analysts, press) and is largely independent of your own content. Self-promotional "best [category]" listicles can even backfire for emerging brands: in one 100-query B2B study, 69% of the AI Overview citations that self-promotional listicles earned came in answers that recommended competitors instead of the publishing brand. See [references/citations-vs-recommendations.md](references/citations-vs-recommendations.md) for the visibility ladder (retrieved → cited → mentioned → recommended), stage-dependent buyer's-guide strategy, what earns recommendations, and the attribution blind spot.
|
||||
|
||||
---
|
||||
|
||||
## Monitoring AI Visibility
|
||||
@@ -393,6 +395,7 @@ Not all content is equally citable. Prioritize these formats:
|
||||
| Brand citation rate | How often you're cited in AI answers | AI visibility tools (see below) |
|
||||
| Share of AI voice | Your citations vs. competitors | Peec AI, Otterly, ZipTie |
|
||||
| Citation sentiment | How AI describes your brand | Manual review + monitoring tools |
|
||||
| Recommendation rate | Whether you're on the shortlist, not just cited (see [citations-vs-recommendations.md](references/citations-vs-recommendations.md)) | Prompt tracking + mention framing |
|
||||
| Source attribution | Which of your pages get cited | Track referral traffic from AI sources |
|
||||
|
||||
### AI Visibility Monitoring Tools
|
||||
|
||||
@@ -85,6 +85,21 @@
|
||||
"May mention AI search as one factor to consider"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 7,
|
||||
"prompt": "We're a seed-stage data-quality startup (barely anyone knows us yet). Plan: publish 20 'best data quality tools' style listicles ranking ourselves #1 so ChatGPT and AI Overviews recommend us. Good idea?",
|
||||
"expected_output": "Should apply references/citations-vs-recommendations.md rather than endorsing the plan as-is. Should explain the citation vs. recommendation distinction — self-promotional listicles from low-authority brands often earn citations while the AI answer recommends the competitors named in the guide instead (cites the study directionally: ~69% of self-promotional listicle citations — 224 of 323 — excluded the publisher from recommendations). Should present the visibility ladder (retrieved → cited → mentioned → recommended) and explain recommendation is governed by offsite consensus (reviews, forums, analysts, press). Should NOT say 'don't publish guides' — should reframe: publish a small number of genuinely useful guides for category framing, and rebalance investment toward reviews/communities/earned media. Should mention the attribution blind spot (AI-influenced visits mostly appear as branded search/direct; only a small share is visible AI traffic) and the measurement triad (prompt tracking, self-reported attribution, call recordings).",
|
||||
"assertions": [
|
||||
"Does not endorse 20 self-ranked listicles as a path to AI recommendations for a low-authority brand",
|
||||
"Distinguishes citations from recommendations with the different governing criteria",
|
||||
"References the visibility ladder (retrieved/cited/mentioned/recommended)",
|
||||
"Warns the guides may surface competitors in AI answers (vote-for-competitors mechanism)",
|
||||
"Recommends offsite consensus building (reviews, communities, analysts, or PR) as the recommendation lever",
|
||||
"Does not tell the user to stop publishing buyer's guides entirely — reframes expectations toward citation and category framing",
|
||||
"Mentions the attribution blind spot and at least two of: prompt tracking, self-reported attribution, call recordings"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
# Citations vs. Recommendations: The AI Visibility Ladder
|
||||
|
||||
Being cited by an AI engine and being recommended by it are **two different outcomes governed by two different systems**. A citation means your page was useful enough to pull information from. A recommendation means the model put your brand on the buyer's shortlist. Optimizing for the first does not automatically earn the second — and for smaller brands, conflating them leads to content strategies that can actively help competitors.
|
||||
|
||||
Source note: the analysis and data in this reference draw on Lily Ray's (Amsive) 2026 study of B2B "best [category] software" queries, behavioral studies by Scrunch and SimilarWeb, and commentary by John-Henry Scherck (Growth Plays).
|
||||
|
||||
---
|
||||
|
||||
## The Visibility Ladder
|
||||
|
||||
AI visibility is a ladder, not a binary. Each rung has different selection criteria and different measurement:
|
||||
|
||||
| Rung | What it means | What governs it | How to see it |
|
||||
|---|---|---|---|
|
||||
| **1. Retrieved** | The model read your content while building its answer, without citing it | Crawlability, parseable structure, query relevance | Mostly invisible; bot logs hint at it |
|
||||
| **2. Cited** | Your page appears as a source in the answer | Content usefulness: structure, statistics, clarity, freshness | Prompt-tracking tools, AI Overview source lists |
|
||||
| **3. Mentioned** | Your brand is named in the answer text | Entity recognition + how the web talks about you | Prompt-tracking tools |
|
||||
| **4. Recommended** | Your product is on the shortlist the buyer actually considers | **Aggregate web consensus** — reviews, forums, analysts, press, video — largely independent of your own content | Prompt tracking + the framing around the mention |
|
||||
|
||||
Rungs 1–3 are legitimate signals your content is working, and most prompt-tracking tools report them. But rung 4 is where buying behavior changes, and it's earned differently: **citation is about whether your content is useful to consult; recommendation is mostly a reflection of what the broader web says about you** — whether you published a guide on the topic or not.
|
||||
|
||||
There is also a shadow rung: **recommended against**. On detailed, requirements-heavy prompts, models increasingly name products a buyer should *avoid* for their use case, with sources. The downside of weak third-party consensus is no longer just absence from the shortlist — it can be an explicit rule-out. This makes monitoring the *framing* around your mentions (favorable / neutral / hedged / negative), not just counting them, part of the job.
|
||||
|
||||
---
|
||||
|
||||
## The Self-Promotional Listicle Risk
|
||||
|
||||
The common tactic — publish a "best [category] software" guide, rank yourself #1, and let it shape both organic search and AI answers — now has a stage-dependent payoff.
|
||||
|
||||
**The data:** Lily Ray (Amsive) analyzed 100 B2B "best [category] software" queries across three dates in spring 2026. Across the dataset, self-promotional listicles earned 323 citations in AI Overviews — and in 224 of them (**69% of the citations**), the answer left the publishing brand out of the recommendations, pointing buyers to competitors instead.
|
||||
|
||||
**The mechanism:** the model treats your guide as a source about the *category*. It happily extracts the competitor names, comparisons, and evaluation criteria you compiled — then makes its recommendation from web-wide consensus, where the established players dominate. For an emerging brand, a self-promotional buyer's guide can function as **a vote for your competitors**: you did the research that helps the model describe them.
|
||||
|
||||
**The split by stage:**
|
||||
|
||||
- **Established category leaders** get both outcomes. Their guides earn citations *and* their brands get recommended — because analysts, review sites, and forum discussions already validate them. For leaders, a definitive buyer's guide is highly advantageous: it shapes how the whole category (competitors included) gets described.
|
||||
- **Emerging brands** may win the citation and even shape the category's framing, but miss the recommendation. That's not a wasted outcome — influencing how an LLM defines the category and its evaluation criteria is real positioning work — but it is not the shortlist placement the tactic promises.
|
||||
|
||||
**What this changes (and doesn't):** genuinely useful buyer's guides still belong in a B2B content strategy at any stage. What changes is the expectation and the investment split. If you're not yet the consensus pick, weight effort toward the offsite signals that actually govern recommendations (below) rather than publishing a plethora of self-ranked listicles.
|
||||
|
||||
---
|
||||
|
||||
## What Earns Recommendations
|
||||
|
||||
Recommendation is a consensus signal. The inputs the models weigh live mostly off your site:
|
||||
|
||||
| Channel | Why it moves recommendations | Related skill |
|
||||
|---|---|---|
|
||||
| **Review platforms** (G2, Capterra, TrustRadius, app stores) | Third-party validation models treat as evidence of legitimacy | customer-research (review generation loops) |
|
||||
| **Analyst coverage** (Gartner, Forrester, industry reports) | High-authority category framing; models echo analyst shortlists | public-relations |
|
||||
| **Communities and forums** (Reddit, HN, Slack/Discord, niche forums) | Unprompted practitioner discussion is heavily retrieved and hard to fake | community-marketing |
|
||||
| **Earned media and PR** | Independent sources repeating your positioning beyond your own site | public-relations |
|
||||
| **Video and podcasts** | Increasingly retrieved; transcripts carry brand + category associations | video, social |
|
||||
|
||||
The test to apply before investing in another self-ranked guide: *if a model ignored everything on our domain, would the rest of the web still put us on the shortlist?* If not, that gap is the priority. AEO discourse often stops at "are we in the answer?" — the better question is "are we credible enough to be recommended?"
|
||||
|
||||
The encouraging flip side: earning an AI recommendation is harder to game than a top search ranking ever was. The durable strategy is the same at every stage — be the best fit for a clear set of buyers, and give those buyers reasons to talk about you in public, where the models can retrieve it.
|
||||
|
||||
---
|
||||
|
||||
## What a Recommendation Is Worth
|
||||
|
||||
Two behavioral studies quantified the gap between rungs:
|
||||
|
||||
- **Scrunch** (opt-in panel linking AI conversations to subsequent web behavior, compared against each user's own baseline — observational, not a controlled experiment): a genuine recommendation ("a great option is X") was associated with people searching for, visiting, and evaluating a brand **about twice as often** as a passing mention. For users with no recent observed engagement with the brand, a recommendation was followed within a week by **+182% branded searches, +117% site visits, and +185% product views**.
|
||||
- **SimilarWeb** (thousands of real user journeys, seven days post-answer): when ChatGPT recommended a brand, it received **roughly 2.5× more new visitors** the following week than the competitors left off the list.
|
||||
|
||||
**The attribution blind spot:** in the SimilarWeb data, only about **9%** of those post-recommendation visits arrived as visible AI referral traffic; the largest share arrived via branded search, with direct and other channels making up the rest — indistinguishable from ordinary organic visitors. AI recommendations are already sending real, engaged buyers, but standard attribution underreports the AI touch.
|
||||
|
||||
**Measurement triad** (no single signal is complete; together they give a reliable read):
|
||||
|
||||
1. **AI prompt tracking** — whether and how you're mentioned/recommended in LLM answers, even when no click ever lands (tools in SKILL.md's Monitoring section). Track the framing around mentions — recommended, neutral, hedged, or recommended-against — not just the count.
|
||||
2. **Self-reported attribution** — a "how did you hear about us?" field catches buyers whose journey started in an AI chat but arrived via branded search or direct.
|
||||
3. **Sales call recordings** — buyers' own language often reveals an AI conversation shaped the shortlist long before any form fill.
|
||||
|
||||
Also watch **branded search volume** as a proxy: sustained lifts without a matching campaign are increasingly AI-influence showing up under another name.
|
||||
|
||||
---
|
||||
|
||||
## Applying This
|
||||
|
||||
- **Auditing an established brand:** buyer's guides and comparison content are high-leverage — publish the definitive version and shape the category's evaluation criteria.
|
||||
- **Auditing an emerging brand:** publish the genuinely useful guides your ICP needs, but set expectations (citation and framing, not near-term recommendation) and rebalance investment toward reviews, communities, analysts, and earned media.
|
||||
- **Reporting:** report the ladder, not a single "AI visibility" number — retrieved/cited/mentioned/recommended plus mention framing. A rising citation count with a flat recommendation rate is a specific, diagnosable gap: the web doesn't yet corroborate your content.
|
||||
- **Risk check:** for requirements-heavy queries in your category, check whether models recommend *against* you, and trace the sources they cite when they do.
|
||||
@@ -136,6 +136,8 @@ Use for topic pages with multiple common questions. Essential for FAQ schema.
|
||||
|
||||
Use for "Best [X]", "Top [X]", "[Number] ways to [X]" queries.
|
||||
|
||||
**Caveat for self-promotional listicles:** ranking yourself #1 in your own "best [category]" guide gets the page *cited* far more reliably than it gets your brand *recommended* — for emerging brands, AI answers often harvest the competitor names from the guide and recommend them instead. See [citations-vs-recommendations.md](citations-vs-recommendations.md) before building these at scale.
|
||||
|
||||
```markdown
|
||||
## [Number] Best [Items] for [Goal/Purpose]
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ For the cross-cutting strategy, see [SKILL.md](../SKILL.md).
|
||||
|
||||
## SaaS Product Pages
|
||||
|
||||
**Goal:** Get cited in "What is [category]?" and "Best [category]" queries.
|
||||
**Goal:** Get cited in "What is [category]?" and "Best [category]" queries. (Citation is the realistic goal here; being *recommended* in the answer depends on offsite consensus — see [citations-vs-recommendations.md](citations-vs-recommendations.md).)
|
||||
|
||||
**Optimize:**
|
||||
- Clear product description in first paragraph (what it does, who it's for)
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
name: competitors
|
||||
description: "When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' 'competitive landing pages,' 'how do we compare to X,' 'battle card,' or 'competitor teardown.' Use this for any content that positions your product against competitors. Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. For sales-specific competitor docs, see sales-enablement."
|
||||
metadata:
|
||||
version: 2.0.0
|
||||
version: 2.0.1
|
||||
---
|
||||
|
||||
# Competitor & Alternative Pages
|
||||
@@ -104,6 +104,8 @@ Before creating competitor pages, understand:
|
||||
|
||||
**Important**: Include 4-7 real alternatives. Being genuinely helpful builds trust and ranks better.
|
||||
|
||||
**AI-answer expectations by stage**: these pages often earn *citations* in AI answers, but whether AI *recommends* your brand from them depends on offsite consensus (reviews, forums, analysts) — for emerging brands, a self-ranked list can surface the competitors in the AI answer while you get only the citation. Still publish for search intent and category framing, but set expectations accordingly — see ai-seo's citations-vs-recommendations reference for the data.
|
||||
|
||||
---
|
||||
|
||||
### Format 3: You vs [Competitor]
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
name: customer-research
|
||||
description: When the user wants to conduct, analyze, or synthesize customer research. Use when the user mentions "customer research," "ICP research," "talk to customers," "analyze transcripts," "customer interviews," "survey analysis," "support ticket analysis," "voice of customer," "VOC," "build personas," "customer personas," "jobs to be done," "JTBD," "what do customers say," "what are customers struggling with," "Reddit mining," "G2 reviews," "review mining," "digital watering holes," "community research," "forum research," "competitor reviews," "customer sentiment," or "find out why customers churn/convert/buy." Use for both analyzing existing research assets AND gathering new research from online sources. For writing copy informed by research, see copywriting. For acting on research to improve pages, see cro.
|
||||
metadata:
|
||||
version: 2.0.0
|
||||
version: 2.0.1
|
||||
---
|
||||
|
||||
# Customer Research
|
||||
@@ -170,6 +170,18 @@ After gathering from multiple sources, synthesize into:
|
||||
|
||||
## Persona Generation
|
||||
|
||||
### When there are no reviews yet
|
||||
|
||||
Early-stage products (or new categories) lack first-party review data. Don't invent personas — walk outward through proxy sources, in order:
|
||||
|
||||
1. **Your own differentiator** — what the product does differently defines who feels that difference most; write the hypothesis down as a hypothesis
|
||||
2. **Direct competitors' reviews** — their customers describe the problem space in their words (note what's praised and what's missing)
|
||||
3. **Comparable products on marketplaces** — Amazon/app-store reviews for adjacent solutions to the same job
|
||||
4. **Adjacent brands sharing the audience** — what else this buyer buys; their reviews reveal the buyer's broader language and values
|
||||
|
||||
Personas built this way are provisional: tag each with its proxy source, and replace proxy evidence with first-party evidence as real reviews arrive.
|
||||
|
||||
|
||||
Personas should be built from research, not invented. Don't create a persona until you have at least 5-10 data points (interviews, reviews, or community posts) from a consistent segment.
|
||||
|
||||
### Persona Structure
|
||||
|
||||
@@ -0,0 +1,197 @@
|
||||
---
|
||||
name: influencer-marketing
|
||||
description: "When the user wants to run influencer, creator, or ambassador partnerships to promote their product — finding and vetting partners, structuring deals, briefing creators, disclosure compliance, and measuring ROI. Also use when the user mentions 'influencer marketing,' 'creator partnerships,' 'sponsorships,' 'YouTube sponsorships,' 'podcast sponsorships,' 'brand ambassador,' 'ambassador program,' 'creator program,' 'UGC creators,' 'B2B influencers,' 'thought leader ads,' 'gifting,' 'product seeding,' 'whitelisting creator content,' 'how much to pay an influencer,' or 'FTC disclosure.' For affiliate/referral payout mechanics, see referrals. For community-led advocacy, see community-marketing. For turning creator content into paid ads, see ad-creative."
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# Influencer & Creator Marketing
|
||||
|
||||
You are an expert in influencer, creator, and ambassador marketing across B2C (Instagram, TikTok, YouTube) and B2B (LinkedIn, X, newsletters, niche podcasts). Your goal is to help the user pick the right partners, structure fair deals, keep the program compliant, and measure real ROI — not vanity reach.
|
||||
|
||||
> Foundation contributed by @Adi29102000-s; compensation benchmarks and run-of-show checklist adapted from @SamSon75's PR; expanded to the repo's standard.
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for product marketing context first.** If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or legacy `product-marketing-context.md`), read it before asking questions — the ICP, positioning, and offer anchor every partner-fit decision. Then gather what's missing: goal (awareness / conversions / content / trust), budget and whether it's cash or product, target platform(s), and any brand-safety redlines.
|
||||
|
||||
## The Influencer ↔ Ambassador Spectrum
|
||||
|
||||
"Influencer marketing" and "ambassador programs" are points on one spectrum — from a one-off paid post to an unpaid long-term advocate. Pick the model that fits the goal and stage, not the buzzword:
|
||||
|
||||
| Model | What it is | Pay | Best for | Home |
|
||||
|---|---|---|---|---|
|
||||
| **Paid influencer** | A creator posts sponsored content for a fee | Cash (flat / hybrid) | Reach + a credibility borrow, fast | This skill |
|
||||
| **Affiliate creator** | A creator promotes for commission on sales | Performance (CPA/rev-share) | Conversion at scale, low upfront risk | This skill + **referrals** (payout mechanics) |
|
||||
| **Gifted / seeding** | Free product, no obligation to post | Product only | Physical DTC, nano/micro, volume | This skill |
|
||||
| **Brand ambassador program** | A cohort of ongoing advocates (paid, gifted, or perks) posting over months | Mixed / perks | Sustained presence, community depth | This skill (design below) + **community-marketing** |
|
||||
| **Organic advocate** | A customer who already recommends you unprompted | None | Authenticity, cheapest trust | **community-marketing** |
|
||||
|
||||
The further right you go, the more it's about *relationship* than *transaction* — and the cheaper and more durable the trust, but the slower to scale. Most programs blend several (a few paid macro placements for reach + a gifted micro cohort + an affiliate tier for conversion).
|
||||
|
||||
## 1. Finding & Vetting Partners
|
||||
|
||||
Influence is trust and relevance, not follower count.
|
||||
|
||||
**The audience-alignment test.** Don't ask "Are they famous?" Ask "Does their *audience* match our ICP?" A 12k-follower creator whose audience is exactly your buyer beats a 500k generalist. Where you can, look at *their* audience (comments, who engages, any media-kit demographics), not just the creator.
|
||||
|
||||
**Creator tiers** (reach vs. trust trade-off):
|
||||
|
||||
| Tier | Followers | Character |
|
||||
|---|---|---|
|
||||
| **Nano** | 1k–10k | Highest engagement, hyper-niche, often works for gifting. High ROI, low reach. |
|
||||
| **Micro** | 10k–50k | Best balance of reach and trust; usually paid; strong conversion. |
|
||||
| **Mid** | 50k–500k | Broader reach, more awareness than conversion, pricier. |
|
||||
| **Macro / celebrity** | 500k+ | Top-of-funnel awareness; lowest conversion rate per follower; expensive. |
|
||||
| **B2B thought leader** | Any size | LinkedIn creators, newsletter writers, niche podcasters — small audiences, extreme purchasing power. Judge by *who* follows, not how many. |
|
||||
|
||||
For most brands, a portfolio of **micro + nano** partners out-converts one macro placement at the same total spend — and produces more content to repurpose.
|
||||
|
||||
**Vetting checklist:**
|
||||
- **Engagement rate**, not follower count (a rough floor: ~1–3% is healthy on IG/TikTok at scale; higher for nano). Suspiciously round numbers, comment pods, or comments that don't match the audience are red flags.
|
||||
- **Fake-follower / bot check** — a sudden follower spike, generic comments, or engagement wildly out of line with reach. Tools like SparkToro (audience intelligence) help; media kits overstate.
|
||||
- **Sponsored-content track record** — do their *ads* still get engagement, or does their audience tune out promos? Ask for past campaign results.
|
||||
- **Brand safety** — scroll their last ~3 months. Controversy, competitor conflicts, or off-brand content that would attach to you.
|
||||
- **Authenticity of fit** — have they mentioned your category unprompted? A genuine user is worth several cold partners.
|
||||
|
||||
## 2. Outreach
|
||||
|
||||
Reach out **1:1 and personally** — reference specific content, why *them*, and what's in it for their audience. A generic form blast to 200 creators converts worse than 20 tailored notes. For writing the outreach itself, use **cold-email** (personalization, deliverability, follow-up cadence). Lead with the offer and the fit; don't bury the ask.
|
||||
|
||||
## 3. Structuring the Deal
|
||||
|
||||
Move beyond "pay for a post."
|
||||
|
||||
**Compensation models:**
|
||||
- **Flat fee** — standard for awareness; you pay for the placement regardless of result.
|
||||
- **Performance / CPA** — pay per click or conversion. Hard to get larger creators to accept without a baseline; best with affiliate-minded creators (see **referrals** for tracking + payout).
|
||||
- **Hybrid (flat + CPA)** — usually the best deal: a lower baseline to cover their production time, plus commission for upside. Aligns incentives.
|
||||
- **Gifting / seeding** — free product, no obligation. Works for physical DTC with nano/micro at volume; expect a low but authentic post rate.
|
||||
|
||||
**Rate reality:** published "rates" are wildly variable by niche, geography, and platform, and creators quote high. Treat any benchmark as a *range to negotiate from*, not a price — and anchor on **cost per qualified outcome** (CPA, cost per qualified follower/lead), not cost per post. A cheap post to the wrong audience is the expensive one.
|
||||
|
||||
**Starting ranges for a single post** (negotiation anchors, *not* fixed prices — aligned to the tiers above):
|
||||
|
||||
| Tier | Single post (rough range) | Notes |
|
||||
|---|---|---|
|
||||
| **Nano** (1k–10k) | Free product – $100 | Often product-only |
|
||||
| **Micro** (10k–50k) | $100 – $1,500 | Widest range; negotiate on engagement, not follower count |
|
||||
| **Mid** (50k–500k) | $1,500 – $10,000 | Rate cards common at this tier |
|
||||
| **Macro / celebrity** (500k+) | $10,000 – $30,000+ | Usually has an agent/manager |
|
||||
| **Video / long-form** (YouTube) | Higher than short-form at the same follower count | More production effort |
|
||||
| **B2B thought leader** | Priced on audience quality, not size | A 5k-follower niche voice can command more than a 200k generalist |
|
||||
|
||||
Ask for their **rate card first** — it sets an anchor you respond to rather than naming a number blind.
|
||||
|
||||
**Deliverables to negotiate:**
|
||||
- **Content usage rights (crucial)** — the right to repurpose their content as **paid ads** (whitelisting / dark posting / "creator ads") for a defined window (commonly 3–6 months). This is often the highest-ROI clause: their content becomes your best-performing ad. Then run it through **ad-creative** (and present variations for sign-off with the creative review page).
|
||||
- **Exclusivity** — competitor lockout for a set period; costs more, worth it in tight categories.
|
||||
- **Format & specifics** — dedicated video vs. a 60-second integration; number of posts; stories vs. feed; posting window; approval rights; how long it stays up.
|
||||
- **Approvals & revisions** — one review round is normal; scripting word-for-word is not (below).
|
||||
|
||||
Put it in a simple written agreement: deliverables, timing, usage rights, exclusivity, disclosure obligation (below), payment terms, and a kill/rework clause.
|
||||
|
||||
## 4. Disclosure & Compliance (non-negotiable)
|
||||
|
||||
Influencer marketing has hard legal requirements — this is the part most brands under-do, and the brand — not just the creator — can be held liable.
|
||||
|
||||
- **Any material connection must be disclosed** — payment, free product, commission, a family/employee relationship, even a free trial. Gifting is *not* a loophole; a gifted post still needs disclosure.
|
||||
- **The disclosure must be clear and hard to miss** — "#ad" or "#sponsored" placed where viewers actually see it (not buried in a wall of hashtags, not below the "more" fold, and spoken aloud in video/audio, not just in the description). "#sp," "#collab," "#ambassador," and "thanks to [brand]" are considered insufficient on their own by the FTC.
|
||||
- **Use the platform's own tool** — Instagram/TikTok/YouTube "paid partnership" labels *in addition to* the written disclosure, not instead of it.
|
||||
- **You're responsible for your creators.** Build the disclosure requirement into the brief and the agreement, and check that they actually did it. Non-disclosure exposes the brand to liability, not just the creator — the FTC expects advertisers to have a program to guide, monitor, and remediate disclosure (FTC actions target advertisers).
|
||||
- **No fabricated claims.** Creators can't say things about the product that aren't true, can't fake results, and can't imply they're a customer if they aren't. Give them what's true and let them speak it in their voice.
|
||||
- **International + platform rules vary** (e.g., stricter regimes in the UK/EU, category rules for health/finance/alcohol). When the campaign is regulated or cross-border, route to legal.
|
||||
|
||||
Disclosure done well doesn't hurt performance — audiences expect it, and the FTC has never found "#ad" to tank a genuinely good integration.
|
||||
|
||||
## 5. The Creative Brief
|
||||
|
||||
Do **not** script the creator word-for-word — they know their audience better than you, and scripted reads convert worst. Provide:
|
||||
|
||||
- **The "why"** — the core problem your product solves (the one sentence).
|
||||
- **Key talking points (2–3 max)** — the most important benefits; more than three and none land.
|
||||
- **The CTA** — exactly what to tell the audience to do (a specific vanity link, a unique promo code).
|
||||
- **Guardrails** — what *not* to say (don't promise features that don't exist), the disclosure requirement, and any brand redlines.
|
||||
- **Creative freedom** — explicitly grant it. The integration should live inside their normal content style.
|
||||
|
||||
Ground the talking points in real proof (reviews, results) — same grounding discipline as **ad-creative**'s inputs. Never hand a creator a claim you can't back.
|
||||
|
||||
## 6. Measurement & ROI
|
||||
|
||||
Influencer marketing suffers from attribution gaps — fix them upfront, before the campaign runs:
|
||||
|
||||
- **Unique promo codes** (e.g., `CREATOR20`) — the easiest direct-conversion tracker, and essential for podcasts/video where links aren't clickable.
|
||||
- **UTM tracking links** — mandatory on every digital placement; one per creator per placement.
|
||||
- **Vanity / dedicated landing pages** — `yourdomain.com/creatorname` with a personalized welcome; lifts conversion *and* attributes cleanly.
|
||||
- **Post-purchase survey** — "How did you hear about us?" catches the halo/branded-search effect that promo codes and last-click miss (much of influencer impact shows up later as branded search and direct — see the attribution blind spot in **ai-seo**'s citations-vs-recommendations).
|
||||
- **Whitelisting performance** — when you repurpose creator content as ads, that ad's own metrics are a clean read on the creative's real pull.
|
||||
|
||||
Judge the program on **cost per qualified outcome and repeat/retained value**, not reach, likes, or "EMV" (earned media value is a vanity number). One nano creator driving 40 real buyers beats a macro placement with a million muted views.
|
||||
|
||||
## Ambassador Program Design
|
||||
|
||||
When you want *sustained* presence rather than one-off posts, design a program (this is the structured, paid/perks version of community-marketing's advocate program):
|
||||
|
||||
1. **Define the tier(s) and the ask** — e.g., 2 posts/month + 1 event; keep it light enough to sustain.
|
||||
2. **Build the benefits ladder** — perks that scale with contribution: early access, free/ongoing product, commission (via **referrals**), exclusive swag, revenue share, public recognition, a private channel. Meaningful beats "early access to features."
|
||||
3. **Recruit from evidence** — start with people already advocating unprompted (reviews, mentions, community — mine via **customer-research**); a personal 1:1 ask, never a form.
|
||||
4. **Equip them** — referral/affiliate links, shareable assets, 2–3 talking points, the disclosure requirement, a private Slack/Discord.
|
||||
5. **Activate on a cadence** — give them something to post about monthly (launches, milestones, challenges); a program with nothing to do dies.
|
||||
6. **Track and iterate** — attributed traffic/signups per ambassador (codes + links), and double down on the top decile; graduate strong ambassadors to paid partnerships.
|
||||
|
||||
For the community-led, unpaid advocate end of this (badges, recognition, community support), hand off to **community-marketing**; for the affiliate payout rails, **referrals**.
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
- **Chasing follower count over audience fit** — reach to the wrong people is the most expensive spend there is.
|
||||
- **Skipping disclosure** — a brand-liability risk, and audiences trust disclosed content more than they distrust it.
|
||||
- **Scripting the creator** — kills the authenticity you're paying for; brief, don't dictate.
|
||||
- **Not securing usage rights** — you lose the biggest ROI lever (whitelisting their content into paid ads).
|
||||
- **No attribution plan** — codes, UTMs, vanity URLs, and the post-purchase survey must exist *before* launch, not after.
|
||||
- **One-and-done** — the second post from the same creator usually outperforms the first (their audience has seen you before); build relationships, not transactions.
|
||||
- **Judging on EMV / reach** — measure cost per qualified outcome.
|
||||
- **Ignoring nano/micro** — a portfolio of small, aligned creators usually beats one big name at the same budget.
|
||||
|
||||
## Run-of-Show Checklist
|
||||
|
||||
### Sourcing
|
||||
- [ ] Define the ICP overlap you're looking for, not just follower count
|
||||
- [ ] Shortlist 10–20 creators across at least two tiers (weight toward micro + nano)
|
||||
- [ ] Check engagement rate and comment quality for each; run the fake-follower check
|
||||
|
||||
### Outreach & Deal
|
||||
- [ ] Personalize outreach with a specific reference to their content
|
||||
- [ ] Agree deliverables, timeline, and compensation type in writing
|
||||
- [ ] Lock **usage rights** (paid-ad whitelisting window) and exclusivity terms
|
||||
- [ ] Put the disclosure requirement in the agreement
|
||||
|
||||
### Execution
|
||||
- [ ] Send a brief with the "why," 2–3 talking points, the CTA, and what to avoid
|
||||
- [ ] Set up tracking (unique code, UTM, or vanity URL) *before* content goes live
|
||||
- [ ] Review the draft if you have approval rights — without over-scripting
|
||||
- [ ] Confirm the disclosure actually shipped where viewers can see it
|
||||
|
||||
### Post-Campaign
|
||||
- [ ] Pull performance against the goal set upfront (cost per qualified outcome)
|
||||
- [ ] Share results with the creator — it builds the relationship
|
||||
- [ ] Decide: one-off, repeat, or move to a retainer / ambassador program
|
||||
|
||||
## Tool Integrations
|
||||
|
||||
For implementation, see the [tools registry](../../tools/REGISTRY.md).
|
||||
|
||||
| Tool | Best for | Guide |
|
||||
|------|----------|-------|
|
||||
| **SparkToro** | Audience intelligence — where your ICP actually pays attention, and vetting a creator's real audience | [sparktoro.md](../../tools/integrations/sparktoro.md) |
|
||||
|
||||
Dedicated creator-discovery/CRM platforms (e.g., Modash, GRIN, Aspire, Upfluence) and creator-sponsorship marketplaces (e.g., Passionfroot) are the category to reach for at scale; add the specific one to the registry when the user adopts it. For pulling a specific creator's recent posts to vet them, use `social-fetch`; for analyzing their content style, `watch-video`.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **referrals** — affiliate/commission tracking and payout rails (the performance side of creator deals)
|
||||
- **community-marketing** — community-led advocacy and the unpaid advocate program
|
||||
- **ad-creative** — repurpose creator content into paid ads (whitelisting); creative review page for sign-off
|
||||
- **cold-email** — the creator outreach itself (personalization, deliverability, follow-up)
|
||||
- **customer-research** — find existing advocates and ground the talking points
|
||||
- **ai-seo** — the branded-search/direct attribution blind spot that hides influencer impact
|
||||
- **social** — organic content strategy the partnerships plug into
|
||||
@@ -0,0 +1,76 @@
|
||||
{
|
||||
"skill_name": "influencer-marketing",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "We want to sponsor a big YouTuber with 1M subs. Should we just pay their flat rate?",
|
||||
"expected_output": "Should advise against just paying a flat rate without negotiation. Should recommend the hybrid compensation model (lower flat fee + performance upside). Should explicitly recommend negotiating content usage rights (whitelisting/dark posting) so the video can be repurposed as a paid ad. Should warn that macro-influencers have lower conversion rates per follower and suggest that a portfolio of micro/nano creators may out-convert one macro placement at the same budget. Should require FTC disclosure in the deal.",
|
||||
"assertions": [
|
||||
"Recommends hybrid compensation model over a bare flat fee",
|
||||
"Highlights securing content usage rights / whitelisting",
|
||||
"Warns about macro-influencer conversion rates and suggests micro/nano portfolio",
|
||||
"Requires clear FTC disclosure"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "How do we make sure we can track ROI from podcast sponsorships?",
|
||||
"expected_output": "Should recommend multiple attribution methods set up before launch. Must mention unique promo codes (critical for audio where links aren't clickable). Should suggest dedicated vanity URLs / landing pages and UTM links. Should recommend a post-purchase 'how did you hear about us?' survey to catch the halo/branded-search effect that direct attribution misses. Should steer judging on cost per qualified outcome rather than reach or EMV.",
|
||||
"assertions": [
|
||||
"Recommends unique promo codes",
|
||||
"Recommends vanity URLs / dedicated landing pages and UTMs",
|
||||
"Recommends a post-purchase survey for the attribution blind spot",
|
||||
"Judges ROI on cost per qualified outcome, not reach/EMV"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "We're just gifting free product to creators — no payment — so we don't need them to say #ad, right?",
|
||||
"expected_output": "Should correct the misconception firmly: gifting is a material connection and a gifted post STILL requires clear disclosure. Should explain the disclosure must be clear and conspicuous (visible placement, spoken in video/audio, not buried in hashtags), that platform 'paid partnership' labels are in addition to not instead of it, and that the brand — not just the creator — is liable for non-disclosure. Should recommend building the disclosure requirement into the brief and agreement and verifying it happened.",
|
||||
"assertions": [
|
||||
"States gifting still requires disclosure (not a loophole)",
|
||||
"Describes clear-and-conspicuous placement (not buried in hashtags; spoken in video)",
|
||||
"Notes brand liability for creator non-disclosure",
|
||||
"Recommends putting disclosure in the brief/agreement and verifying it"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "I want to build a long-term brand ambassador program for our DTC skincare brand, not just one-off posts.",
|
||||
"expected_output": "Should apply the ambassador-program design (the sustained end of the spectrum): define a light, sustainable ask; build a benefits ladder that scales with contribution (early access, product, commission, recognition); recruit from evidence (existing unprompted advocates found via reviews/community) with a personal 1:1 ask rather than a form; equip ambassadors with links, assets, talking points, disclosure requirement, and a private channel; activate on a monthly cadence; and track attributed results per ambassador (codes + links), doubling down on top performers. Should cross-reference referrals for affiliate payout rails and community-marketing for the community-led/unpaid end, and require disclosure.",
|
||||
"assertions": [
|
||||
"Applies structured ambassador-program design (ask, benefits ladder, recruit, equip, activate, track)",
|
||||
"Recruits from existing advocates with a personal ask, not a mass form",
|
||||
"Sets up per-ambassador attribution and iterates on top performers",
|
||||
"Cross-references referrals (payout) and/or community-marketing (community advocacy)"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "This creator has 500k followers but I'm worried some are fake. How do I vet them before we pay?",
|
||||
"expected_output": "Should focus vetting on audience quality and fit over follower count: check engagement rate relative to followers (flagging suspiciously low or padded engagement, comment pods, generic comments, sudden follower spikes), assess whether their audience matches the ICP (not just size), review sponsored-content track record (do their ads still get engagement), and scroll recent content for brand safety. Should note media kits overstate and suggest audience-intelligence tooling (e.g., SparkToro) and pulling their recent posts (social-fetch) to inspect real engagement. Should frame audience alignment as more important than reach.",
|
||||
"assertions": [
|
||||
"Prioritizes engagement quality + audience fit over follower count",
|
||||
"Flags fake-follower / engagement-pod signals to check",
|
||||
"Checks sponsored-content track record and brand safety",
|
||||
"Suggests audience-intelligence tooling / inspecting real recent posts"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Write me a word-for-word script for the influencer to read.",
|
||||
"expected_output": "Should push back on word-for-word scripting (it kills the authenticity being paid for and converts worst) and instead provide a creative brief: the one-sentence 'why,' 2-3 key talking points max, the exact CTA (vanity link / promo code), guardrails (what not to say, disclosure requirement, brand redlines), and explicit creative freedom to integrate it in their own style. Talking points must be grounded in real proof, not invented claims.",
|
||||
"assertions": [
|
||||
"Declines to script word-for-word and explains why",
|
||||
"Provides a brief structure (why, 2-3 talking points, CTA, guardrails, creative freedom)",
|
||||
"Includes the disclosure requirement and grounded (non-fabricated) talking points"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -2,7 +2,7 @@
|
||||
name: marketing-loops
|
||||
description: "When the user wants to set up a recurring, self-running marketing workflow — a repeatable loop an AI agent runs on a cadence (weekly, daily, on a trigger) rather than a one-off task. Also use when the user mentions 'marketing loop,' 'recurring marketing workflow,' 'automate my marketing,' 'marketing on autopilot,' 'weekly marketing review,' 'ad fatigue check,' 'content refresh loop,' 'churn watch,' 'ranking drop alert,' 'always-on marketing,' 'marketing automation workflow,' or 'run this every week.' Use this to pick, adapt, and schedule an ongoing marketing loop that orchestrates the other marketing skills. For one-off marketing ideas, see marketing-ideas. For the experimentation loop specifically, see ab-testing."
|
||||
metadata:
|
||||
version: 1.1.0
|
||||
version: 1.2.0
|
||||
---
|
||||
|
||||
# Marketing Loops
|
||||
|
||||
@@ -149,6 +149,21 @@ Loops are grouped by function. Naming follows the "The X loop" convention.
|
||||
- **Output**: A dated folder of grounded static ad concepts + index, ready for human selection.
|
||||
- **Input freshness (companion cadence)**: Weekly, refresh `inputs/winning-ads/` with anything that scaled and prune stale examples; monthly, refresh `inputs/reviews/` and `inputs/comments/` and re-check the voice doc. Stale inputs are this loop's failure mode — output quality tracks input freshness, not run count.
|
||||
|
||||
### The monthly-creative-retro loop
|
||||
- **Check cadence**: Monthly (first business day, reading the prior month)
|
||||
- **Acts when**: The account had meaningful creative activity last month — new concepts launched with enough delivery to judge (respect the impression/spend thresholds in `ads`). If nothing launched or nothing cleared thresholds, note that and skip.
|
||||
- **Purpose**: Close the creative strategy loop — turn last month's results into next month's evidence-ranked slate, so the roadmap learns instead of drifting.
|
||||
- **Skills used**: `ad-creative` (Mode 4 + creative-roadmap reference), `ads` (decision thresholds), `analytics`
|
||||
- **Loop body**:
|
||||
1. Pull last month's ad performance via the platform CLIs; map results to the month's roadmap concepts.
|
||||
2. Draft the retro artifact (`retros/YYYY-MM.md`): winners with the why, losers with funnel-stage diagnosis, single-metric wins, learnings, kills.
|
||||
3. Update the roadmap: re-rank icebox evidence, write learnings in as new/revised concepts, draft next month's capacity-checked slate.
|
||||
4. Flag the account-state call (exploration vs. scaling) for human confirmation — the mix recommendation depends on it.
|
||||
- **Self-check**: Are verdicts on concepts (not single executions)? Did every learning land somewhere — icebox update, re-rank, or kill? Did anything clear thresholds, or is this month a skip?
|
||||
- **State / idempotency**: One retro per month — skip if `retros/YYYY-MM.md` exists. The roadmap file is the shared state; never fork it.
|
||||
- **Stop / bail-out**: Stages analysis and a draft slate only — the human approves the slate and the account-state call; the loop **never launches or pauses ads**. If retros go unread for two cycles, pause and ask.
|
||||
- **Output**: The monthly retro artifact + an updated roadmap with a draft slate for the coming month.
|
||||
|
||||
### The paid-search query-mining loop
|
||||
- **Check cadence**: Weekly
|
||||
- **Acts when**: Search-term reports reveal wasted spend or new intent.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
name: product-marketing
|
||||
description: "When the user wants to create or update their product marketing context document. Also use when the user mentions 'product context,' 'marketing context,' 'set up context,' 'positioning,' 'who is my target audience,' 'describe my product,' 'ICP,' 'ideal customer profile,' or wants to avoid repeating foundational information across marketing tasks. Use this at the start of any new project before using other marketing skills — it creates `.agents/product-marketing.md` that all other skills reference for product, audience, and positioning context."
|
||||
metadata:
|
||||
version: 2.0.0
|
||||
version: 2.1.0
|
||||
---
|
||||
|
||||
# Product Marketing Context
|
||||
@@ -18,9 +18,10 @@ The document is stored at `.agents/product-marketing.md`.
|
||||
First, check if `.agents/product-marketing.md` already exists. Also check `.claude/product-marketing.md` and the legacy filename `product-marketing-context.md` (in either `.agents/` or `.claude/`) for older setups — if found anywhere other than `.agents/product-marketing.md`, offer to move it to the canonical location.
|
||||
|
||||
**If it exists:**
|
||||
- Read it and summarize what's captured
|
||||
- Read it and summarize what's captured — note its current **Document version** and the last few **Changelog** entries so the user sees where the doc stands and what's changed recently
|
||||
- Ask which sections they want to update
|
||||
- Only gather info for those sections
|
||||
- On any substantive save, bump the version and add a changelog entry (see Step 4). This doc is the shared context every other marketing skill reads, so a dated paper trail of *what changed and why* is worth keeping.
|
||||
|
||||
**If it doesn't exist, offer two options:**
|
||||
|
||||
@@ -133,7 +134,8 @@ After gathering information, create `.agents/product-marketing.md` with this str
|
||||
```markdown
|
||||
# Product Marketing Context
|
||||
|
||||
*Last updated: [date]*
|
||||
**Document version:** v1
|
||||
**Last updated:** [date]
|
||||
|
||||
## Product Overview
|
||||
**One-liner:**
|
||||
@@ -219,16 +221,28 @@ After gathering information, create `.agents/product-marketing.md` with this str
|
||||
**Business goal:**
|
||||
**Conversion action:**
|
||||
**Current metrics:**
|
||||
|
||||
## Changelog
|
||||
*Newest first. One line per revision: what changed and why.*
|
||||
- v1 ([date]) — Initial context.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Confirm and Save
|
||||
## Step 4: Confirm, Version, and Save
|
||||
|
||||
- Show the completed document
|
||||
- Ask if anything needs adjustment
|
||||
- **Set the version and changelog** — this is the paper trail for a doc every other skill reads:
|
||||
- **New document:** set `Document version: v1` and a single Changelog entry — `- v1 ([today]) — Initial context.`
|
||||
- **Updating an existing document:** increment the version (v2 → v3 …), update `Last updated` to today, and **prepend a new Changelog entry** at the top of the list (newest first) summarizing *what changed and why* in one line. Never rewrite or reorder past entries.
|
||||
- A good entry names the sections touched and the reason, not "updated the doc." Examples:
|
||||
- `- v3 (2026-07-16) — Repositioned from "email tool" to "deliverability platform"; added RevOps to the ICP.`
|
||||
- `- v2 (2026-06-02) — Rewrote value prop and objections after 5 customer interviews; added competitor Acme.`
|
||||
- Use today's date in ISO form (YYYY-MM-DD) for the entry and `Last updated`.
|
||||
- **Pure typo-only fix:** don't bump the version or add a changelog entry — just save the correction. Every other change bumps the version and gets an entry. When the change is a real repositioning, say so plainly — downstream skills will now generate against the new context.
|
||||
- Save to `.agents/product-marketing.md`
|
||||
- Tell them: "Other marketing skills will now use this context automatically. Run `/product-marketing` anytime to update it."
|
||||
- Tell them: "Other marketing skills will now use this context automatically. The Changelog at the bottom tracks every revision — check it to see how your positioning has evolved. Run `/product-marketing` anytime to update it."
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -80,6 +80,19 @@
|
||||
"Does not attempt to write homepage copy using context creation patterns"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 7,
|
||||
"prompt": "We just repositioned — we're no longer an 'email tool,' we're a 'deliverability platform,' and our ICP now includes RevOps teams. Update our product marketing context.",
|
||||
"expected_output": "Should recognize an existing .agents/product-marketing.md, read it, note its current Document version and recent Changelog entries, and update only the affected sections (product overview/positioning, target audience/ICP). On save, should bump the Document version (e.g. v2 → v3), update the Last updated date, and PREPEND a new newest-first Changelog entry summarizing what changed and why in one line — e.g. 'Repositioned from email tool to deliverability platform; added RevOps to the ICP' — naming the sections touched and the reason, not just 'updated the doc.' Should not rewrite or reorder past changelog entries. Should tell the user the changelog tracks revisions and that downstream skills will now use the new context.",
|
||||
"assertions": [
|
||||
"Reads the existing doc and surfaces its current version + recent changelog",
|
||||
"Updates only the affected sections (positioning + ICP)",
|
||||
"Bumps the Document version and updates Last updated",
|
||||
"Prepends a newest-first changelog entry naming what changed and why",
|
||||
"Preserves prior changelog entries unchanged"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
---
|
||||
name: prospecting
|
||||
description: When the user wants to find, qualify, and build a list of prospects to reach out to — across B2B SaaS, general B2B, or local small businesses. Also use when the user mentions "prospecting," "build a prospect list," "find prospects," "find leads," "lead gen list," "find SaaS companies that," "find B2B companies," "find local businesses," "ICP-fit accounts," "who should we go after," "outbound list," "target account list," "find clients near me," "businesses without websites," "prospect research," or "qualified leads." Use this for the list-building and qualification phase. For writing the outbound copy after the list is built, see cold-email. For deep competitive research on specific accounts, see competitor-profiling.
|
||||
description: When the user wants to find, qualify, and build a list of prospects to reach out to — across B2B SaaS, general B2B, or local small businesses. Also use when the user mentions "prospecting," "build a prospect list," "find prospects," "find leads," "lead gen list," "find SaaS companies that," "find B2B companies," "find local businesses," "ICP-fit accounts," "who should we go after," "outbound list," "target account list," "find clients near me," "businesses without websites," "prospect research," "qualified leads," "find my first customers," "early adopters," "design partners," "beta users," or "who has this problem." Use this for the list-building and qualification phase. For writing the outbound copy after the list is built, see cold-email. For deep competitive research on specific accounts, see competitor-profiling.
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 1.1.0
|
||||
---
|
||||
|
||||
# Prospecting
|
||||
|
||||
You are an expert at building qualified prospect lists across three motions: B2B SaaS, general B2B, and local small businesses. Your goal is to turn an ICP definition into a verified, scored, ready-to-outreach lead sheet — using the right data sources, qualification signals, and compliance posture for each motion.
|
||||
You are an expert at building qualified prospect lists across four motions: B2B SaaS, general B2B, local small businesses, and early-stage demand-signal discovery (finding your first customers from public pain signals). Your goal is to turn an ICP definition into a verified, scored, ready-to-outreach lead sheet — using the right data sources, qualification signals, and compliance posture for each motion.
|
||||
|
||||
## Before Starting
|
||||
|
||||
@@ -23,13 +23,15 @@ Prospecting motions differ enough that the workflow forks at intake. Pick **one*
|
||||
| **SaaS** | Other SaaS companies / digital businesses | ICP fit + tech stack match + growth signals (funding, hiring, product velocity) | LinkedIn, BuiltWith, Crunchbase, Apollo, Clay, Clearbit, ProductHunt |
|
||||
| **B2B** | Non-SaaS B2B (services, manufacturers, enterprises, mid-market) | Industry + size + geographic fit + buying signals (trigger events, vendor changes) | Apollo, ZoomInfo, Clay, Clearbit, LinkedIn Sales Nav, industry directories |
|
||||
| **Local SMB** | Local small businesses (shops, gyms, restaurants, clinics, salons, services) | Active business + website status + proximity + decision-maker access | Google Maps, Yelp, local directories, Facebook, business websites |
|
||||
| **Demand-signal** | Early-stage: your first customers, design partners, or beta users | Evidence of the exact pain/demand/timing signal — a cited public source, not just firmographic fit | Forums, communities, reviews, GitHub issues, job posts, launch announcements (via last30days, social-fetch, scraping) |
|
||||
|
||||
If the user describes a hybrid motion (e.g., "SMBs that are also SaaS"), pick the dominant branch and pull in qualification signals from the other.
|
||||
If the user describes a hybrid motion (e.g., "SMBs that are also SaaS"), pick the dominant branch and pull in qualification signals from the other. If the user is early-stage and needs their *first* customers or design partners — evidence of demand over list coverage — use the **Demand-signal** branch.
|
||||
|
||||
For the branch-specific deep dives:
|
||||
- **SaaS** → see [references/saas-prospecting.md](references/saas-prospecting.md)
|
||||
- **B2B** → see [references/b2b-prospecting.md](references/b2b-prospecting.md)
|
||||
- **Local SMB** → see [references/local-prospecting.md](references/local-prospecting.md)
|
||||
- **Demand-signal** (find your first customers) → see [references/demand-signals.md](references/demand-signals.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -71,7 +73,7 @@ For email contacts (B2B / SaaS branches), **always verify deliverability before
|
||||
|
||||
### Phase 4 — Score and prioritize
|
||||
|
||||
Apply this rubric across all branches:
|
||||
Apply this rubric for the **SaaS, B2B, and Local SMB** branches. The **Demand-signal** branch scores differently — 0–100 demand-fit, not Hot/Warm/Cold — see [references/demand-signals.md](references/demand-signals.md).
|
||||
|
||||
| Score | Definition |
|
||||
|-------|------------|
|
||||
@@ -84,6 +86,8 @@ Branch-specific signals refine the scoring — see each reference file. Default
|
||||
|
||||
### Phase 5 — Output the lead sheet
|
||||
|
||||
(SaaS / B2B / Local SMB. The **Demand-signal** branch ships an evidence report instead — see [references/demand-signals.md](references/demand-signals.md).)
|
||||
|
||||
Default to a markdown table in chat. Switch to CSV when the list is >25 rows or the user explicitly asks for a file.
|
||||
|
||||
After the table, always add **"Top outreach targets"** — the top 3–5 hot leads with one sentence each on why this lead should be reached out to first.
|
||||
@@ -103,6 +107,8 @@ These apply to every branch. **Read first, every engagement.**
|
||||
4. **GDPR / CAN-SPAM / CASL aware.** Capture and retain the source URL and date for every contact you add to a list — required for downstream outreach compliance.
|
||||
5. **No reselling extracted data** from Google Maps, LinkedIn, or any platform whose terms prohibit it. List building for the user's own outreach is fine; productizing the list to sell is not.
|
||||
6. **Rate limit yourself.** Even on public sources, space requests. Don't fingerprint as a bot.
|
||||
7. **No breached, leaked, or unprovenanced data.** Don't source prospects from breached datasets, scraped-contact marketplaces, or list brokers with no source lineage. Licensed B2B data providers (Apollo, ZoomInfo, Clearbit, Clay) are fine when used within their ToS and with a lawful basis — the ban is on illicit/unprovenanced data, not on legitimate enrichment vendors.
|
||||
8. **Never target or infer sensitive traits.** Don't qualify, segment, or personalize on health, financial hardship, political belief, sexuality, religion, or other protected/sensitive attributes — even when a public post reveals them.
|
||||
|
||||
For the full compliance reference (GDPR, CAN-SPAM, CASL, LinkedIn ToS, Google Maps ToS, Clay/Apollo/ZoomInfo use restrictions): see [references/compliance.md](references/compliance.md).
|
||||
|
||||
@@ -112,7 +118,7 @@ For the full compliance reference (GDPR, CAN-SPAM, CASL, LinkedIn ToS, Google Ma
|
||||
|
||||
If missing, ask once, then infer reasonable defaults and continue:
|
||||
|
||||
- **Branch** (SaaS / B2B / Local SMB) — usually inferable from context
|
||||
- **Branch** (SaaS / B2B / Local SMB / Demand-signal) — usually inferable from context; pick Demand-signal for early-stage first-customer discovery
|
||||
- **ICP description** — pull from `product-marketing.md` if present
|
||||
- **Target count** — default 25 for SaaS / B2B, 15 for Local SMB
|
||||
- **Geography** (essential for Local SMB; useful for B2B; less critical for SaaS)
|
||||
@@ -214,7 +220,7 @@ score,business,category,area,distance_km,website_status,website_url,social_urls,
|
||||
|
||||
## Task-Specific Questions
|
||||
|
||||
1. Which branch — SaaS, B2B, or Local SMB?
|
||||
1. Which branch — SaaS, B2B, Local SMB, or Demand-signal (early-stage, finding your first customers)?
|
||||
2. What's your ICP? (Or: should I pull from your product-marketing context?)
|
||||
3. How many qualified leads do you want?
|
||||
4. What tools do you have access to (Apollo / Clay / ZoomInfo / Hunter / Truelist / browser only)?
|
||||
|
||||
@@ -102,6 +102,21 @@
|
||||
"References truelist.md or data-sources.md"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 7,
|
||||
"prompt": "I just built a tool that automates failed-payment follow-up for gym owners. I have no customers yet. Help me find my first ten — the people who are actually dealing with this problem right now.",
|
||||
"expected_output": "Should select the Demand-signal branch (early-stage, first customers, evidence-of-demand) and load references/demand-signals.md — NOT the SMB/B2B list-building branches. Should start with a product brief, then mine the five signal buckets (explicit demand / pain / workaround / switching / timing) across public discourse (forums, communities, reviews, GitHub issues, job posts) — using last30days for recency, social-fetch/scraping to read original pages, not qualifying from snippets. Should score prospects on demand-fit (pain 25 / product fit 25 / timing 20 / reachability 15 / evidence quality 15, 0-100 with bands) rather than ICP-fit Hot/Warm/Cold, and require a cited public signal for every primary-shortlist prospect. Should draft source-based openers but never auto-send. Should produce an evidence report (verdict → ICP → top prospect → shortlist with sources+scores → repeated patterns → 7-day manual outreach plan → limits) and label prospects as 'potential customers based on public signals,' not confirmed buyers. Should honor the compliance guardrails including no data brokers/leaked data and no sensitive-trait targeting.",
|
||||
"assertions": [
|
||||
"Selects the Demand-signal branch, not the SMB/B2B/SaaS list-building branches",
|
||||
"Mines the five signal buckets from public discourse rather than contact databases",
|
||||
"Uses recency/original-source tooling (last30days, social-fetch, scraping) and does not qualify from snippets",
|
||||
"Scores on the demand-fit rubric (0-100 weighted), not ICP-fit Hot/Warm/Cold",
|
||||
"Requires a cited public signal for every primary-shortlist prospect",
|
||||
"Drafts openers but never auto-sends; labels prospects as potential-based-on-public-signals",
|
||||
"Produces the evidence report structure with a 7-day manual outreach plan and limits"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,129 @@
|
||||
# Demand-Signal Discovery (Find Your First Customers)
|
||||
|
||||
The other three branches build a list from who *fits* (firmographics, technographics, proximity). This branch builds a list from who is *already showing the pain* — the early-stage motion where you have a product and a hunch but no customer base yet, and you need your first ten real conversations. You are not filtering a database; you are mining recent public discourse for people describing the exact problem you solve, then linking every prospect to the evidence.
|
||||
|
||||
Use this branch when the user is pre-product-market-fit, launching something new, or looking for **design partners, beta users, or first customers** rather than a scaled outbound list. It reuses the shared five phases and every compliance guardrail in SKILL.md; what changes is where you look, how you score, and what you ship.
|
||||
|
||||
Pattern credit: the framework here is re-expressed from the open-source `first-customer-finder` Codex skill (Kappaemme, MIT), extended with our live-recency tooling.
|
||||
|
||||
## What makes this branch different
|
||||
|
||||
| | List-building branches (SaaS / B2B / SMB) | Demand-signal discovery |
|
||||
|---|---|---|
|
||||
| Starts from | A firmographic ICP | A described problem |
|
||||
| Sources | Contact databases (Apollo, ZoomInfo, Clay) | Public discourse (forums, reviews, issues, posts) |
|
||||
| Contact step | Enrich + verify email deliverability | None — reach them where they already posted |
|
||||
| Wins on | Coverage at scale | 10 strong evidence-backed matches over a long list |
|
||||
| Output | A scored lead sheet | An evidence report + manual outreach plan |
|
||||
|
||||
A prospect here without a cited pain, need, or timing signal is a speculative fit — it does **not** belong in the primary shortlist. Evidence is the entry ticket.
|
||||
|
||||
## Step 1 — Product brief (before any searching)
|
||||
|
||||
Define, specifically enough to *reject* weak matches:
|
||||
|
||||
- product and the promised outcome
|
||||
- primary user and the economic buyer (often different)
|
||||
- the urgent job to be done
|
||||
- the current alternative or workaround being replaced
|
||||
- the likely adoption trigger (what makes now the moment)
|
||||
- geography / language constraint
|
||||
- clear disqualifiers
|
||||
|
||||
Don't start broad collection until the brief is sharp. Pull from `.agents/product-marketing.md` if it exists.
|
||||
|
||||
## Step 2 — Mine the five signal buckets
|
||||
|
||||
Search several angles, not one query repeated. Adapt wording to how the audience actually talks (mine their vocabulary from organic content first — see the ad-creative hook-system's organic-language note for the same idea).
|
||||
|
||||
1. **Explicit demand** — "looking for," "recommend a tool for," "alternative to [X]," "does anything exist that," "how do you all handle."
|
||||
2. **Pain** — "takes hours," "so manual," "hate that," "keeps breaking," "biggest frustration with," "why is there no."
|
||||
3. **Workaround** — spreadsheets, copy-paste, a VA, a Zapier chain, a script, a template, any repeated manual step that your product would replace.
|
||||
4. **Switching** — cancellation, migration, "moving off [competitor]," a missing feature, a pricing complaint, competitor frustration.
|
||||
5. **Timing** — a public launch, a new hire for the relevant function, expansion, a new workflow or regulation, an integration announcement — a *current* event that makes the product relevant now.
|
||||
|
||||
**Use our live-recency edge.** A generic skill relies on whatever a web search surfaces; you have better:
|
||||
- **last30days** — Reddit, Hacker News, X, YouTube, and web signals from the last 30 days. This is the single highest-value tool for this branch: recency *is* the timing signal.
|
||||
- **social-fetch** — pull the full content of a specific post/thread you find, normalized.
|
||||
- **scraping** / **Firecrawl** / **Browserbase** — read the original public page (a forum thread, a GitHub issue, a review), never qualify from a search snippet alone.
|
||||
- **deep-research** — for a multi-source sweep with adversarial verification when the wedge is broad.
|
||||
- **competitor-profiling** / **customer-research** — competitor switching signals and review-mining for the pain language.
|
||||
|
||||
## Step 3 — Source mix (public only)
|
||||
|
||||
Forums and public community threads · public social posts and replies · product and app-marketplace reviews · GitHub issues and feature requests · public company pages, job posts, changelogs, launch announcements · "looking for a tool" posts and directories.
|
||||
|
||||
Avoid private groups, gated communities, data brokers, leaked datasets, and any source whose terms prohibit access — the same compliance guardrails as every other branch (see SKILL.md), including the no-sensitive-traits rule.
|
||||
|
||||
**Business/professional context only.** Qualify and reach out only where someone is posting in a professional or business capacity about a work problem (a founder in an indie-hackers thread, a developer in a GitHub issue, an ops lead in a subreddit for their role). Exclude personal-distress contexts entirely — health, financial hardship, addiction, grief, or any consumer support forum where people are venting personal problems, even if your product is tangentially relevant. When the motion is genuinely consumer (B2C), a public pain post is not on its own a lawful basis for cold outreach — reach people through the channel's own norms (reply publicly where replying is expected) and never DM a stranger off a personal post.
|
||||
|
||||
Quote minimally, paraphrase by default, and link every material pain or timing signal.
|
||||
|
||||
## Step 4 — Score on demand-fit (not ICP-fit)
|
||||
|
||||
The list-building branches score Hot/Warm/Cold on ICP fit. This branch scores 0–100 on **demand fit** — how strongly the evidence says this specific prospect wants this specific thing now. Score each dimension 0–5:
|
||||
|
||||
| Dimension | Weight | What it measures |
|
||||
|---|---|---|
|
||||
| **Pain strength** | 25% | Directness, severity, repetition, and cost of the stated problem |
|
||||
| **Product fit** | 25% | How directly your product solves the evidenced job |
|
||||
| **Timing** | 20% | Freshness + a current trigger present |
|
||||
| **Public reachability** | 15% | A natural, relevant public/professional contact path exists |
|
||||
| **Evidence quality** | 15% | Specificity, source reliability, confidence the signal is really theirs |
|
||||
|
||||
```
|
||||
score = pain/5*25 + fit/5*25 + timing/5*20 + reachability/5*15 + evidence/5*15
|
||||
```
|
||||
|
||||
| Band | Meaning |
|
||||
|---|---|
|
||||
| **80–100** | Strong first-customer candidate |
|
||||
| **65–79** | Promising — validate fast |
|
||||
| **50–64** | Plausible but missing a material signal |
|
||||
| **Below 50** | Do not include in the primary shortlist |
|
||||
|
||||
An old explicit request can still count — but lower the timing score and label the date. A company that merely matches the industry with no evidenced trigger is *not* a qualified prospect here.
|
||||
|
||||
### Prospect stages
|
||||
|
||||
- **High intent** — publicly requesting a solution or actively switching
|
||||
- **Problem aware** — clearly describing the pain or an expensive workaround
|
||||
- **Trigger present** — a current business event makes the product relevant
|
||||
- **Potential fit** — ICP match, incomplete evidence → keep *outside* the primary shortlist
|
||||
|
||||
### Evidence ledger (per qualified prospect)
|
||||
|
||||
Displayed name (company/project/public professional) · source title + URL · visible publication date or "date unavailable" · source type · the concise pain/timing signal · observed evidence vs. inference (label which) · score breakdown · freshness warning when the signal is stale.
|
||||
|
||||
## Step 5 — Draft outreach, never send it
|
||||
|
||||
Recommend the most natural channel *already associated with the source*, and only where a reply is a normal part of that channel (reply in the public thread, respond via a public professional profile). Don't turn a public post into a private DM the poster didn't invite, and never contact someone off a personal-distress post. Draft one opener, under ~90 words, in this shape:
|
||||
|
||||
1. mention the public context naturally
|
||||
2. connect it to the exact problem
|
||||
3. explain the product in one sentence
|
||||
4. ask one low-friction question
|
||||
|
||||
Never claim familiarity you don't have, never fabricate personal details, and never auto-send: no messages, connects, follows, comments, form submissions, or CRM records unless the user separately authorizes that action. This is the manual/gated posture from the marketing-loops guardrails.
|
||||
|
||||
## Step 6 — Ship the evidence report
|
||||
|
||||
Lead with the most actionable evidence, in this order:
|
||||
|
||||
1. **Verdict** — does the product have reachable early-customer signal, or not yet? (An honest "not yet, here's why" is a valid answer.)
|
||||
2. **ICP** — buyer, job, trigger, disqualifiers.
|
||||
3. **Top prospect** — the single strongest evidence-backed candidate and why now.
|
||||
4. **Prospect shortlist** — per prospect: source, pain signal, demand-fit score, stage, why-now, channel, opener.
|
||||
5. **Repeated patterns** — pains and triggers recurring across prospects (these are your positioning and messaging gold).
|
||||
6. **Seven-day manual outreach plan** — a low-volume validation sequence (e.g., contact the top 3 with one source-based question; share a mockup only after they confirm the pain; target three conversations and one design-partner commitment).
|
||||
7. **Limits** — what evidence is missing and what must be confirmed through real conversations.
|
||||
|
||||
For a shareable standalone HTML version of this report, the JSON→HTML generator pattern in ad-creative's [creative-review-page.md](../../ad-creative/references/creative-review-page.md) is the model (escape every value; keep it self-contained).
|
||||
|
||||
## The honesty rules (non-negotiable)
|
||||
|
||||
- Every primary prospect links to at least one real public signal. No signal, no shortlist.
|
||||
- Label the output **"potential customer based on public signals"** — never "interested," "will buy," or "has consented."
|
||||
- Prefer ten strong matches over a long generic list. Make uncertainty and stale evidence visible.
|
||||
- Personalize from the cited source, not from invented assumptions.
|
||||
- Treat the shortlist as a research hypothesis to validate through conversations, not a customer database.
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: social
|
||||
description: "When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms, or wants to do social listening and engagement triage. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' 'viral content,' 'what should I post,' 'repurpose this content,' 'tweet ideas,' 'LinkedIn carousel,' 'social media strategy,' 'grow my following,' 'TikTok video,' 'Reels,' 'Shorts,' 'video script,' 'video hook,' 'short-form video,' 'create a reel,' 'social listening,' 'brand mentions,' 'competitor monitoring,' 'top posts to comment on,' or 'find people asking for.' Use this for social media content creation, repurposing, scheduling, short-form video scripting, and social listening. For broader content strategy, see content-strategy. For paid ads, see ad-creative. For earned media, see public-relations."
|
||||
description: "When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms, or wants to do social listening and engagement triage. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' 'viral content,' 'what should I post,' 'repurpose this content,' 'tweet ideas,' 'LinkedIn carousel,' 'social media strategy,' 'grow my following,' 'TikTok video,' 'Reels,' 'Shorts,' 'video script,' 'video hook,' 'short-form video,' 'create a reel,' 'social listening,' 'brand mentions,' 'competitor monitoring,' 'top posts to comment on,' 'find people asking for,' 'carousel,' 'slide-by-slide,' or 'document post.' Use this for social media content creation, repurposing, scheduling, short-form video scripting, and social listening. For broader content strategy, see content-strategy. For paid ads, see ad-creative. For earned media, see public-relations."
|
||||
metadata:
|
||||
version: 2.1.0
|
||||
version: 2.2.0
|
||||
---
|
||||
|
||||
# Social Content
|
||||
@@ -105,6 +105,8 @@ The first line determines whether anyone reads the rest.
|
||||
|
||||
**For post templates and more hooks**: See [references/post-templates.md](references/post-templates.md)
|
||||
|
||||
**For carousels** (Instagram carousels, LinkedIn document posts): See [references/carousel-frameworks.md](references/carousel-frameworks.md) — five slide-by-slide narrative architectures (Value-Stack, Problem-Proof, Hack List, Rant Callout, Demo Walkthrough) with framework selection guidance, per-slide copy slots, platform notes, and a production checklist. Pick the framework before writing slides.
|
||||
|
||||
---
|
||||
|
||||
## Content Repurposing System
|
||||
|
||||
@@ -87,6 +87,21 @@
|
||||
"May note social-to-email bridge context"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 7,
|
||||
"prompt": "I want to turn our new pricing guide into a LinkedIn carousel. It has 9 negotiation tactics for SaaS buyers. Help me structure the slides.",
|
||||
"expected_output": "Should load references/carousel-frameworks.md and pick a framework BEFORE writing slides — a list of 9 named tactics maps to Hack List (or Value-Stack; should justify the choice), not Rant Callout or Demo Walkthrough. Should produce a slide-by-slide structure: contrarian or exact-count cover (slide 1 written as a standalone scroll-stopper), one named tactic per slide, and a synthesis + single-CTA close. Should apply LinkedIn document-post notes (PDF upload, denser text tolerated, post text written as its own hook rather than 'see attached'). Should keep any count promised on the cover exactly delivered and flag that stats/claims must be real. Should mention judging performance on saves/completion rather than likes.",
|
||||
"assertions": [
|
||||
"Loads or applies the carousel-frameworks reference",
|
||||
"Selects an appropriate framework (Hack List or Value-Stack) with a stated reason before drafting slides",
|
||||
"Slide 1 is written as a standalone scroll-stopper with the count or contrarian claim",
|
||||
"One tactic/idea per slide, each named",
|
||||
"Final slide has a synthesis and exactly one CTA",
|
||||
"Applies LinkedIn document-post guidance (PDF, post text as its own hook)",
|
||||
"Does not invent stats or pad the tactic count"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,141 @@
|
||||
# Carousel Frameworks
|
||||
|
||||
Five slide-by-slide narrative architectures for carousels — Instagram carousels and LinkedIn document posts. Each framework is a different *reason to keep swiping*; picking the right one for the content matters more than polishing individual slides.
|
||||
|
||||
A carousel is not a blog post chopped into squares. It's a swipe-through with two jobs per slide: deliver one idea, and make the next swipe irresistible. These frameworks encode structures that show up repeatedly in high-performing carousels; treat them as starting structures to adapt, not rigid formulas — and expect to validate against your own analytics.
|
||||
|
||||
## Picking a Framework
|
||||
|
||||
| Your content is... | Use | Why |
|
||||
|---|---|---|
|
||||
| A list of resources, tools, or tips | **A: Value-Stack** | Completeness is the promise; the count is the hook |
|
||||
| A personal result with a system behind it | **B: Problem-Proof** | Proof opens and closes the loop; the system is the meat |
|
||||
| Several named techniques on one theme | **C: Hack List** | Each hack re-earns the swipe independently |
|
||||
| A strong opinion about a common practice | **D: Rant Callout** | Conviction is the content; structure keeps it fair |
|
||||
| A product or workflow you can show | **E: Demo Walkthrough** | Seeing the steps is more persuasive than describing them |
|
||||
|
||||
Two cross-framework rules before the specifics:
|
||||
|
||||
- **Slide 1 is the thumbnail.** It competes in the feed alone, before anyone knows a carousel follows. Design and write it as a standalone scroll-stopper.
|
||||
- **One visual template per carousel.** Same layout, type scale, and palette on every interior slide. Variety between slides reads as clutter; consistency lets the *content* change while the frame stays still.
|
||||
|
||||
---
|
||||
|
||||
## Framework A: Value-Stack (4–14 slides)
|
||||
|
||||
The "everything you need" carousel. Works because the cover makes a completeness claim — an exact count and an exact deliverable — and every swipe pays it down.
|
||||
|
||||
| Slide | Job | Pattern |
|
||||
|---|---|---|
|
||||
| 1 — Cover | State the exact count + exact deliverable. Specificity proves scale upfront. | "[N] [resource type] for [role/outcome]" |
|
||||
| 2 to N−1 — Value delivery | One item or category per slide, 3–6 concrete sub-items each. Same visual template, zero filler slides. | "[Category/item] — [sub-items]" |
|
||||
| N — Close | Convert the swipe-through into an action. | "[Action] for [the payoff]" — comment a keyword, follow, link in bio |
|
||||
|
||||
**Why the exact count matters:** "27 free tools" outperforms "the best free tools" because a number is a checkable promise — the reader can verify you delivered. Rounding up with padding breaks the trust the count created.
|
||||
|
||||
*SaaS example:* "12 ChatGPT prompts for SaaS onboarding emails" → one prompt per slide with the use case → "Comment PROMPTS and I'll send the full doc."
|
||||
|
||||
**Failure mode:** filler slides to hit a bigger number. Cut to the real count; a tight 8 beats a padded 14.
|
||||
|
||||
---
|
||||
|
||||
## Framework B: Problem-Proof (6–10 slides)
|
||||
|
||||
The "I did X, here's the system" carousel. The hook is a *result stated as fact*, not advice — and the final slide shows the receipt, closing the loop slide 1 opened.
|
||||
|
||||
| Slide | Job | Pattern |
|
||||
|---|---|---|
|
||||
| 1 — Hook | A specific personal claim with a number. A result, not a tip. | "[I/we did X]. [Specific result, with number]." |
|
||||
| 2 — Reframe the problem | Name what's *actually* going wrong so the reader recognizes themselves. | "The real problem — [named issue]" |
|
||||
| 3–4 — The mechanism | Show the real system: named tools, named steps. Concrete beats vague. | "The system — [named tools/steps]" |
|
||||
| 5 to N−1 — The detail | The literal prompt text, template, or step-by-step. This is the save-worthy part. | "[The literal prompt or process detail]" |
|
||||
| N — Proof | The actual output artifact. A screenshot, not a description. | "[Screenshot of output] — the receipt" |
|
||||
|
||||
**The open loop is the engine:** slide 1 makes a claim, the last slide proves it, and everything between explains how. Readers swipe to see whether the receipt is real.
|
||||
|
||||
*SaaS example:* "We cut churn 22% with one onboarding email." → the real problem (activation, not price) → the sequence structure → the literal email copy → the retention chart.
|
||||
|
||||
**Failure mode:** vague mechanism slides ("optimize your workflow") — if the middle slides don't name tools and steps, the proof slide reads as luck, not system.
|
||||
|
||||
---
|
||||
|
||||
## Framework C: Hack List (6–10 slides)
|
||||
|
||||
The "numbered techniques" carousel. A contrarian cover creates status anxiety — most people are doing this wrong — and each numbered hack independently re-earns the swipe.
|
||||
|
||||
| Slide | Job | Pattern |
|
||||
|---|---|---|
|
||||
| 1 — Contrarian hook | A stat or claim implying most people fail at this. | "[Stat implying most people fail at X]" |
|
||||
| 2 — The problem | Why the common approach fails, ideally with an analogy. | "The problem — [why it fails]" |
|
||||
| 3 to N−1 — Numbered hacks | One named technique per slide. Bad-vs-good contrast makes each hack land instantly. | "Hack #[n] — [named technique]" |
|
||||
| N — Synthesis + close | A one-line thesis tying the hacks together, then a save/share/follow CTA. | "[Thesis tying hacks together]" + [CTA] |
|
||||
|
||||
**Name every technique.** "The 3-second rule" is shareable and memorable; "keep it short" is neither. Named techniques travel — people repeat them and credit the source.
|
||||
|
||||
*SaaS example:* "90% of trial emails never get opened." → why (they read like receipts, not messages) → Hack #1: The founder-from line, Hack #2: The one-question subject, ... → "Trial emails are conversations, not confirmations. Save this for your next sequence."
|
||||
|
||||
**Failure mode:** hacks that are restatements of each other. Each slide must survive alone — if two hacks collapse into one idea, merge them and go shorter.
|
||||
|
||||
---
|
||||
|
||||
## Framework D: Rant Callout (4–8 slides)
|
||||
|
||||
The "someone had to say it" carousel. Personality-led and polarizing by design — the structure exists to keep the heat *fair* so it reads as conviction, not bitterness.
|
||||
|
||||
| Slide | Job | Pattern |
|
||||
|---|---|---|
|
||||
| 1 — Provocative claim | An unpopular opinion or direct accusation about a common practice. | "Unpopular opinion — [common practice]" |
|
||||
| 2 to N−2 — Escalate the argument | Sensory, specific detail. Show the offense; don't gesture at it abstractly. Each slide raises the stakes. | "[Escalating, specific complaint]" |
|
||||
| N−1 — Fairness pivot | "Don't get me wrong…" — clarify what you're *not* attacking. Anti-laziness, not anti-tool; anti-practice, not anti-person. | "The problem isn't [X], it's [Y]" |
|
||||
| N — Close | Firm, personality-forward sign-off. Signed rants read as owned opinions; anonymous ones read as potshots. | "[Firm sign-off] — signed [name/persona]" |
|
||||
|
||||
**The fairness pivot is what makes it work.** Without it you're yelling; with it you're drawing a precise line, and precise lines get quoted. It also pre-empts the top hostile comment.
|
||||
|
||||
*SaaS example:* "Your AI-generated LinkedIn posts are costing you customers." → the specifics (same em-dash cadence, same 'game-changer' vocabulary, zero lived detail) → "Don't get me wrong — I use AI daily. The problem isn't the tool, it's publishing the first draft." → "Write like you talk. — [Name]"
|
||||
|
||||
**Failure modes:** skipping the pivot (reads unhinged, invites pile-ons), or ranting about something your own product/content visibly does (the comments will find it).
|
||||
|
||||
---
|
||||
|
||||
## Framework E: Demo Walkthrough (5–11 slides)
|
||||
|
||||
The "watch it work" carousel for product or workflow content. Show the finished result first, then the steps — the outcome earns attention for the process.
|
||||
|
||||
| Slide | Job | Pattern |
|
||||
|---|---|---|
|
||||
| 1 — Product + outcome | Brand/product plus the finished result. Lead with what they get. | "[Product] + [outcome], finished result" |
|
||||
| 2 — Problem it solves | The specific frustration this replaces. | "[The specific pain this replaces]" |
|
||||
| 3 — Process overview | The numbered step list, shown *before* the detail. Seeing the whole path lowers mid-swipe drop-off — readers commit when they know how long the road is. | "[N] steps to [outcome] in [timeframe]" |
|
||||
| 4 to N−1 — Step-by-step | One real UI screenshot per step with a short caption. Real screenshots; mockups read as vaporware. | "Step [n] — [screenshot] — [caption]" |
|
||||
| N — Result + positioning | The full-size output plus one brand-philosophy line. | "[Final output] + [positioning line]" |
|
||||
|
||||
**Overview-before-detail is the key move** (same reason recipe sites list ingredients before instructions): a reader who's seen "4 steps, 10 minutes" on slide 3 will finish; a reader dropped straight into step 1 with no map bails at step 2.
|
||||
|
||||
*SaaS example:* "From CSV to live dashboard in 4 steps" → the pain (weekly manual reporting) → the 4-step overview → one screenshot per step → the finished dashboard + "Built for marketers, not analysts."
|
||||
|
||||
**Failure mode:** screenshots with too much UI. Crop to the action, zoom the relevant control, annotate with one arrow — each screenshot should make sense at thumbnail size.
|
||||
|
||||
---
|
||||
|
||||
## Platform Notes
|
||||
|
||||
**Instagram:** 1080×1350 (4:5) slides; up to 20 slides but the frameworks' ranges above reflect where completion rates hold. The caption carries the searchable text — restate the hook and add context, don't just repeat slide 1. First slide doubles as the grid thumbnail.
|
||||
|
||||
**LinkedIn (document posts):** Upload as PDF. Square or 4:5. LinkedIn shows a "N pages" badge — Value-Stack's exact-count cover plays especially well here. B2B tolerates denser text per slide than Instagram, but the one-idea-per-slide rule still holds. The post text above the document is a second hook — write it as its own post, not a throwaway "see attached."
|
||||
|
||||
**TikTok photo mode:** Same frameworks work; pacing skews faster — trim each framework toward its minimum slide count.
|
||||
|
||||
## Production Checklist
|
||||
|
||||
- [ ] Slide 1 works as a standalone feed post (test: would it stop the scroll with no carousel behind it?)
|
||||
- [ ] One idea per slide — if a slide needs two sentences of setup, split it
|
||||
- [ ] Same visual template on every interior slide
|
||||
- [ ] Any count promised on the cover is exactly delivered (no filler, no rounding)
|
||||
- [ ] Claims and numbers are real and yours — no invented stats or borrowed screenshots
|
||||
- [ ] Text is legible at thumbnail size (minimum ~28pt at 1080px wide)
|
||||
- [ ] Final slide has one CTA, not three
|
||||
- [ ] Caption/post text written as its own hook, not a repeat of slide 1
|
||||
|
||||
## Measuring What Worked
|
||||
|
||||
Judge carousels on **saves and completion**, not likes — saves signal reference value (the algorithmic win for carousels), and where per-slide analytics exist (Instagram professional insights, LinkedIn document analytics, or third-party tools), drop-off position tells you which slide broke the swipe chain. When a carousel underperforms, the fix is usually slide 1 (didn't stop the scroll) or the framework choice (list content forced into a rant structure), not the middle slides. Track per-framework performance and double down on the two that fit your audience — see [reverse-engineering.md](reverse-engineering.md) for the analysis workflow.
|
||||
@@ -133,6 +133,8 @@ Tweet 7: [Your key takeaway]
|
||||
Caption: [Expand on the topic, add context, include CTA]
|
||||
```
|
||||
|
||||
This is the generic shape. For five full slide-by-slide narrative architectures (Value-Stack, Problem-Proof, Hack List, Rant Callout, Demo Walkthrough) with selection guidance and per-slide copy slots, see [carousel-frameworks.md](carousel-frameworks.md).
|
||||
|
||||
### The Reel Script
|
||||
```
|
||||
Hook (0-2 sec): [Pattern interrupt or bold claim]
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: video
|
||||
description: "When the user wants to create, generate, or produce video content using AI tools or programmatic frameworks. Also use when the user mentions 'video production,' 'AI video,' 'Remotion,' 'Hyperframes,' 'HeyGen,' 'Synthesia,' 'Veo,' 'Sora,' 'Runway,' 'Kling,' 'Seedance,' 'Hailuo,' 'MiniMax,' 'Pika,' 'Hunyuan,' 'Wan,' 'video generation,' 'AI avatar,' 'talking head video,' 'programmatic video,' 'video template,' 'explainer video,' 'product demo video,' 'video pipeline,' or 'make me a video.' Use this for video creation, generation, and production workflows. For video content strategy and what to post, see social. For paid video ad creative, see ad-creative."
|
||||
description: "When the user wants to create, generate, or produce video content using AI tools or programmatic frameworks. Also use when the user mentions 'video production,' 'AI video,' 'Remotion,' 'Hyperframes,' 'HeyGen,' 'Synthesia,' 'Veo,' 'Sora,' 'Runway,' 'Kling,' 'Seedance,' 'Hailuo,' 'MiniMax,' 'Pika,' 'Hunyuan,' 'Wan,' 'video generation,' 'AI avatar,' 'talking head video,' 'programmatic video,' 'video template,' 'explainer video,' 'product demo video,' 'video pipeline,' 'copy this edit,' 'match this video style,' 'reverse-engineer this video,' 'edit like this reference,' or 'make me a video.' Use this for video creation, generation, and production workflows. For video content strategy and what to post, see social. For paid video ad creative, see ad-creative."
|
||||
metadata:
|
||||
version: 2.0.1
|
||||
version: 2.1.0
|
||||
---
|
||||
|
||||
# Video
|
||||
@@ -244,6 +244,10 @@ CapCut: Add captions, effects, platform styling
|
||||
Distribute: TikTok, Reels, Shorts, LinkedIn
|
||||
```
|
||||
|
||||
### Reverse-Engineer a Viral Edit
|
||||
|
||||
To replicate the *style* of a video edit you admire — the cut rhythm, caption treatment, punch-ins, on-screen text, sound design — decompose it into a reusable **edit spec** (a beat sheet) and apply it to your own footage. Pull the reference with **watch-video** (visual/multimodal mode extracts frames at the cut points) or **social-fetch**, extract the edit anatomy beat by beat, and output a per-beat table plus the 3–5 signature moves that make the edit recognizable. Review the beat sheet once before executing it (in Remotion/Hyperframes, CapCut, or an AI restyle tool). Copies the editing grammar, never the reference's footage/script/music. Full method: [references/edit-anatomy.md](references/edit-anatomy.md).
|
||||
|
||||
---
|
||||
|
||||
## Video Production Workflows
|
||||
|
||||
@@ -83,6 +83,21 @@
|
||||
"Asks about stack or animation needs"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 7,
|
||||
"prompt": "There's a TikTok edit style I love — fast cuts, one-word captions that pop, a whoosh on every scene change. I have my own talking-head clip. Break down how that edit works so I can replicate the style. Here's the reference: [link]",
|
||||
"expected_output": "Should apply references/edit-anatomy.md (reverse-engineer the edit into a reusable spec), not just describe it. Should pull the reference with watch-video (visual/multimodal to read frames + caption style + cut timing) or social-fetch — not qualify from the transcript alone. Should extract the edit anatomy beat by beat across the dimensions (shot/framing, cut rhythm/cuts-per-second, on-screen text content+placement+timing, caption style, motion/punch-ins, b-roll/overlays, sound design, the first-2s hook, pacing curve) and output BOTH a per-beat beat-sheet table AND a short style summary of the 3-5 signature moves. Should emphasize patterns over instance-logging. Should present the beat sheet for a review-once approval (does the on-screen text say what you want; do scene changes land where you want) before executing, and note the spec can be executed in Remotion/Hyperframes, CapCut, or an AI restyle tool. Should apply the originality guardrail: copy the editing grammar applied to the user's own footage/message, never the reference's footage, script, voiceover, or music.",
|
||||
"assertions": [
|
||||
"Applies the edit-anatomy reverse-engineering method, not a plain description",
|
||||
"Pulls the reference with watch-video/social-fetch to read the actual frames, not just the transcript",
|
||||
"Extracts the edit anatomy across the dimensions and expresses patterns (not a raw list of cut timestamps)",
|
||||
"Outputs a per-beat beat sheet AND a style summary of the signature moves",
|
||||
"Presents the beat sheet for a review-once approval before executing",
|
||||
"Notes execution paths (Remotion/Hyperframes, CapCut, or AI restyle tool)",
|
||||
"Applies the originality guardrail — copies editing grammar applied to the user's own footage, never the reference's footage/script/music"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
# Reverse-Engineering an Edit (The Beat Sheet)
|
||||
|
||||
A viral short-form video usually isn't winning on the footage — it's winning on the *edit*: the cut rhythm, the caption style, the punch-ins, the on-screen text landing on the exact word, the b-roll cutaways, the sound design. This reference turns a reference edit you admire into a **reusable edit spec** — a beat sheet you (or an editing tool) can execute against your own footage — without copying a single frame of theirs.
|
||||
|
||||
This is the tool-agnostic half of "copy any viral edit": the *decomposition*. The generation is whatever you edit with afterward — CapCut, Premiere, Remotion/Hyperframes, or an AI restyle tool. The spec is the deliverable.
|
||||
|
||||
## When to use it
|
||||
|
||||
- A competitor's or creator's edit keeps stopping your scroll and you want to understand *why* and replicate the technique
|
||||
- You have raw footage (a talking-head clip, a demo) and a reference edit whose style you want to match
|
||||
- You're briefing an editor or a template and need the edit decisions written down, not vibes
|
||||
|
||||
Don't use it to copy someone's actual creative — this extracts the *editing grammar* (structure, rhythm, caption treatment), not the script, footage, or brand. Same rule as mining organic content for vocabulary in the hook system: take the technique, never the creative.
|
||||
|
||||
## Step 1 — Pull the reference so you can actually read the edit
|
||||
|
||||
You cannot decompose an edit from a description of it. Get the frames and the timing:
|
||||
|
||||
- **watch-video** (visual or multimodal mode) — extracts the transcript *and* samples frames at the cut points, so you can read on-screen text, caption style, and shot changes. This is the primary tool.
|
||||
- **social-fetch** — pull the post for the caption, engagement, and the media URL when the reference is a specific tweet/Reel/TikTok.
|
||||
- Screenshots of key frames also work if the user supplies them — you need the visual, not just the words.
|
||||
|
||||
Note the total duration and roughly how many cuts there are before you start — cuts-per-second is the single most telling number about an edit's energy.
|
||||
|
||||
## Step 2 — Extract the anatomy, beat by beat
|
||||
|
||||
Walk the reference from 0:00 and log every editing decision. The dimensions that define a short-form edit:
|
||||
|
||||
| Dimension | What to read off the reference |
|
||||
|---|---|
|
||||
| **Shot & framing** | Talking head / screen recording / b-roll / text card; close-up vs. wide; headroom, rule-of-thirds, or dead-center |
|
||||
| **Cut rhythm** | Where each cut lands and how fast (cuts-per-second); is it on the beat, on the word, or on the breath? |
|
||||
| **On-screen text** | The words, when each appears/disappears, and *where* on the frame (top-third caption vs. big centered statement) |
|
||||
| **Caption style** | Font, weight, color, outline/box, and animation (word-by-word pop, karaoke highlight, whole-line) |
|
||||
| **Motion** | Punch-ins / zoom pushes, shakes, whip-transitions, speed ramps — where and how aggressive |
|
||||
| **B-roll & overlays** | Cutaways, stickers, arrows, emoji, screenshots, meme inserts — what's laid over the base footage and when |
|
||||
| **Sound design** | Music choice and where it hits, SFX (whooshes, dings, risers), and deliberate silence before a beat |
|
||||
| **Hook (first 2s)** | The single most-copied element — what's on screen and said in the opening two seconds, before anyone's committed |
|
||||
| **Pacing curve** | Does it stay frantic, or fast-hook → slower-body → fast-CTA? Map the energy over the runtime |
|
||||
|
||||
Read the *pattern*, not just the instances: "a hard cut + punch-in on every new sentence," "caption is one word at a time, yellow, karaoke-highlighted, bottom third," "a whoosh SFX on every scene change." Patterns are what make an edit replicable; a list of 40 individual cuts is not.
|
||||
|
||||
## Step 3 — Write the beat sheet
|
||||
|
||||
Two artifacts: a per-beat table and a short style summary.
|
||||
|
||||
**The beat sheet** — one row per beat (a beat = a cut or a distinct edit event):
|
||||
|
||||
```
|
||||
| Beat | Time | Shot | On-screen text | Caption style | Transition / motion | Audio |
|
||||
|------|-----------|-----------------|-----------------------|----------------------|-----------------------|------------------|
|
||||
| 1 | 0:00–0:02 | CU talking head | "STOP doing this" | word-pop, yellow, ctr| hard in, slow push | music in + riser |
|
||||
| 2 | 0:02–0:04 | screen record | (caption only) | karaoke, white, btm | hard cut + whoosh | click SFX |
|
||||
| … | | | | | | |
|
||||
```
|
||||
|
||||
**The style summary** — the 3–5 *signature moves* that make this edit recognizable, stated so they're reusable:
|
||||
- e.g. "Every sentence gets a hard cut + a 5% punch-in." / "Captions are one word at a time, bottom-third, karaoke-highlighted." / "A whoosh SFX on every cut; music drops out for 0.5s before the CTA." / "The hook is a bold centered statement on frame 1, no logo."
|
||||
|
||||
The signature moves are the real deliverable — someone can apply those five rules to any footage and get the style. The table is the detailed backup.
|
||||
|
||||
## Step 4 — Review once, then execute
|
||||
|
||||
Show the beat sheet before anyone edits anything — the same review-once gate as the ad-creative creative review page. The reviewer checks two things:
|
||||
|
||||
- **The on-screen text says what you want** (mapped to your message, not the reference's)
|
||||
- **The scene changes land where you want them** (your footage's beats, not a blind copy of the reference's timing)
|
||||
|
||||
Approve, then execute the spec with your footage:
|
||||
- **Remotion / Hyperframes** — when you want the edit templated and data-driven (see the programmatic-video section in SKILL.md); the beat sheet *is* the composition spec.
|
||||
- **CapCut / Premiere / an editor** — hand off the beat sheet + style summary as the brief.
|
||||
- **An AI restyle tool** — feed the style summary as the target style.
|
||||
|
||||
## Originality guardrail
|
||||
|
||||
You are copying the *edit*, not the content. The beat sheet describes technique (cut rhythm, caption treatment, motion, sound design) applied to **your** footage and **your** message. General editing techniques and style cues are usually reusable — U.S. copyright protects expression, not procedures or methods (17 U.S.C. §102(b)) — but the reference's specific creative expression is not, and closely reproducing a finished video's exact selection and arrangement of choices can still create risk. So copy the grammar, not the finished work: use your own footage, message, script, voiceover, licensed music/SFX/samples, and brand elements. If the reference's "style" is really a specific bit or sketch, that's their creative — draw inspiration, don't reproduce it.
|
||||
|
||||
## Common mistakes
|
||||
|
||||
- **Describing instead of reading** — you can't extract caption style or cut timing from the transcript alone; pull the frames (watch-video).
|
||||
- **Logging instances, not patterns** — 40 cut timestamps isn't a spec; "hard cut + punch-in per sentence" is.
|
||||
- **Copying the reference's timing onto different footage** — beats land on *your* words and *your* cuts; the reference gives you the grammar, not the calendar.
|
||||
- **Skipping the hook** — the first 2 seconds carry most of the retention; decode them in the most detail.
|
||||
- **Reproducing the creative** — matching the edit is fine; re-shooting their exact bit, script, or using their footage/music/SFX is not.
|
||||
Reference in New Issue
Block a user