Compare commits

...
14 Commits
Author SHA1 Message Date
Corey Haines ff8cccced8 Merge pull request #478 from coreyhaines31/development
Release: attribution skill (2.10.0)
2026-07-27 11:58:32 -07:00
Corey Haines 063300710f Merge pull request #493 from coreyhaines31/sync/main-to-dev-2.9.1
sync: main → development after 2.9.1 pricing release
2026-07-27 11:55:00 -07:00
Corey Haines fc2f33beb9 sync: main -> development after 2.9.1 pricing release
Brings the pricing 2.1.0 teardown onto development and reconciles VERSIONS.md
(changelog now 2.10.0 -> 2.9.1 -> 2.9.0; pricing row 2.1.0). Repo version stays
2.10.0 on development (it's ahead of main's 2.9.1). Keeps the eventual 2.10.0
release (#478) a clean, conflict-free promotion.
2026-07-27 11:54:30 -07:00
Corey Haines 2c13accb72 Merge pull request #492 from coreyhaines31/hotfix/487-pricing-2.9.1
Release: pricing-page teardown (2.9.1)
2026-07-27 11:51:55 -07:00
Corey HainesandClaude Opus 4.8 3c51add4a6 release(2.9.1): pricing-page teardown with AI-agent-readiness axis (#487)
pricing 2.0.1 -> 2.1.0. Repo release 2.9.0 -> 2.9.1 (z: existing-skill update),
shipped ahead of the staged 2.10.0 attribution release so the teardown reaches
users without waiting on that launch. Order stays contiguous: 2.9.0 -> 2.9.1 ->
2.10.0. Content codex-reviewed twice. Closes #487.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-27 11:49:27 -07:00
Corey HainesandClaude Opus 4.8 789ef02054 feat(attribution): Tessa Kriesel production feedback → first-party runbook (1.1.0, part of 2.10.0) (#483)
* feat(attribution): incorporate Tessa Kriesel's production feedback (credited)

Four additions from Tessa's prod experience running first-party attribution;
guardrails untouched (fail-closed anonymity, UUID-vs-email, first-touch survival):
1. The last mile — Step 5 in first-party-tracking.md: sync attribution into the
   CRM per account (source field + confidence + basis, Paid-vs-Organic off the
   medium), handoff to revops. Turns a dashboard into a sales/nurture signal.
2. Connect the pillars — store the full ordered touch path (not just $initial_*)
   so the build track (B) can run the interpretation track's (A) multi-touch
   models on real data. A and B now shake hands.
3. Interim quiet part — cross-subdomain reads ~0 until the stitch is verified in
   prod; campaign-window heuristic fallback + backfill the pre-stitch cohort.
4. Account rollup — B2B fork: roll person→account (mixed work/personal emails)
   so attribution lands where sales works the buying committee.
Credited inline + in the file header + by-business-type.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(attribution): codex accuracy pass on Tessa additions

- Paid-vs-Organic: mark paid only from explicit paid mediums; classify the rest
  owned/earned/direct/unknown (configurable), not a blunt 'organic'.
- source_confidence computed from evidence QUALITY, not just basis type.
- Campaign-window fallback: use only when date+LP+UTMs uniquely narrow to one
  source; else unknown/low-confidence.
- Backfill only pre-stitch records MISSING a source; never overwrite higher
  confidence; keep heuristic history separate from verified trends.
- Account rollup: exclude free-mail domains (gmail/yahoo/outlook); use
  enrichment/CRM link/manual for personal-email signups.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(attribution): bump skill to 1.1.0, fold Tessa additions into 2.10.0 changelog

2.10 hasn't shipped yet, so this rides the 2.10.0 release rather than a separate
2.10.1. attribution 1.0.0 -> 1.1.0 (new capability: production-hardening from
Tessa Kriesel's feedback); repo release stays 2.10.0; VERSIONS.md attribution
row + 2.10.0 changelog entry updated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-23 12:41:02 -07:00
Corey HainesandClaude Opus 4.8 804c512d76 feat(attribution): new skill — models, reconciliation, and first-party attribution (2.10.0) (#473)
Two pillars: (A) interpretation — attribution models, MTA/MMM/incrementality,
self-reported, reconciling conflicting sources, the direct/branded/dark-social
blind spots; (B) own-your-attribution — first-party runbook (identity graph,
closing the identify() gap, third-party-domain conversion stitch via metadata
passthrough + webhook merge, fail-closed anonymity guards), distilled from the
Conversion Factory + Truelist builds. Credit: identify-gap method adapted from
Tessa Kriesel's PostHog approach. Codex-reviewed twice.

Four references + 7 evals. analytics (2.0.0 -> 2.0.1) hands off attribution
modeling/reconciliation. Repo release 2.9.0 -> 2.10.0 (2.9.0 = influencer).
Rebuilt onto development after the influencer 2.9.0 release.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-22 11:13:53 -07:00
coreyhaines31 c21a984a56 chore: sync skills with marketplace.json, plugin.json, and README 2026-07-22 18:09:58 +00:00
Corey Haines 140a9e327b Merge pull request #477 from coreyhaines31/development
Release: influencer-marketing skill (2.9.0)
2026-07-22 11:09:38 -07:00
Corey HainesandClaude Opus 4.8 fc3b324f1d feat: influencer-marketing skill (expanded from PR #417 contribution, standalone) (#465)
* feat: add influencer-marketing skill (1.0.0)

Influencer, creator, and ambassador partnerships end to end. Foundation
contributed by @Adi29102000-s (PR #417), expanded to house standard and
shipped standalone: the influencer<->ambassador spectrum, finding &
vetting, deal structuring + whitelisting, a full FTC disclosure section
(gap in the original), the creative brief, ROI measurement, and
structured ambassador-program design. Six evals. New skill = repo y
release 2.9.0. Closes #462.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(influencer-marketing): precise FTC liability wording per codex (can be held liable / expected to monitor)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(influencer-marketing): fold in comp benchmark table + run-of-show checklist from #460

Adapts @SamSon75's dollar-range compensation table (aligned to our tier
definitions) and 4-phase checklist into the standalone skill, so #460 can be
closed as superseded.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-22 11:05:13 -07:00
Corey Haines 67264763cb Merge pull request #467 from coreyhaines31/development
release: v2.8.12 — product-marketing context version history
2026-07-16 12:07:40 -07:00
Corey HainesandClaude Fable 5 8054011197 feat(product-marketing): version history for the context document (2.1.0) (#466)
* feat(product-marketing): version history for the context document (2.1.0)

.agents/product-marketing.md now carries a Document version header + a
newest-first Changelog section. The update flow reads the version/recent
changelog on open and, on save, bumps the version + prepends an entry
naming what changed and why (never rewriting past entries). Makes
positioning/ICP changes traceable across a project since every skill
reads this doc. New eval. Repo release 2.8.12. Closes #462... (pmm issue).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(product-marketing): clarify typo-fix exception (no version bump or changelog) + ISO dates, per codex

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-16 12:07:28 -07:00
Corey Haines 286d3718d9 Merge pull request #458 from coreyhaines31/development
release: v2.8.11 — video edit reverse-engineering (beat sheet)
2026-07-15 09:56:22 -07:00
Corey HainesandClaude Fable 5 fdff3dec99 feat(video): reverse-engineer a viral edit into a reusable edit spec (2.1.0) (#457)
* feat(video): reverse-engineer a viral edit into a reusable edit spec (2.1.0)

New references/edit-anatomy.md: decompose a reference edit into a beat
sheet (per-beat table + 3-5 signature moves) across nine edit-anatomy
dimensions, pulled via watch-video/social-fetch, reviewed once, then
executed in Remotion/CapCut/an AI editor. The tool-agnostic decomposition
half of 'copy any viral edit' (Arcads' Omni generation is proprietary).
Originality guardrail: copy editing grammar, never the reference's
footage/script/music. SKILL.md workflow + triggers + eval. Repo release
2.8.11. Closes #456.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(video): soften edit-style IP claim per codex — techniques usually reusable, finished-work reproduction still risky (§102(b)); add SFX/samples

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-15 09:56:13 -07:00
21 changed files with 1324 additions and 17 deletions
+1 -1
View File
@@ -6,7 +6,7 @@
},
"metadata": {
"description": "Marketing skills for AI agents — conversion optimization, copywriting, SEO, paid ads, and growth",
"version": "2.8.10",
"version": "2.10.0",
"repository": "https://github.com/coreyhaines31/marketingskills"
},
"plugins": [
+1 -1
View File
@@ -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.10",
"version": "2.10.0",
"author": {
"name": "Corey Haines"
},
+1
View File
@@ -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... |
+26 -4
View File
@@ -7,8 +7,9 @@ Current versions of all skills. Agents can compare against local versions to che
| ab-testing | 2.0.0 | 2026-05-05 |
| ad-creative | 2.8.0 | 2026-07-14 |
| ai-seo | 2.2.0 | 2026-07-09 |
| analytics | 2.0.0 | 2026-05-05 |
| analytics | 2.0.1 | 2026-07-22 |
| aso | 2.0.0 | 2026-05-05 |
| attribution | 1.1.0 | 2026-07-23 |
| churn-prevention | 2.0.0 | 2026-05-05 |
| co-marketing | 2.0.0 | 2026-05-05 |
| cold-email | 2.0.0 | 2026-05-05 |
@@ -24,6 +25,7 @@ Current versions of all skills. Agents can compare against local versions to che
| 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 |
@@ -36,8 +38,8 @@ Current versions of all skills. Agents can compare against local versions to che
| ads | 2.2.0 | 2026-07-05 |
| 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 |
| pricing | 2.1.0 | 2026-07-27 |
| product-marketing | 2.1.0 | 2026-07-16 |
| programmatic-seo | 2.0.0 | 2026-05-05 |
| prospecting | 1.1.0 | 2026-07-13 |
| public-relations | 1.0.0 | 2026-06-10 |
@@ -50,10 +52,30 @@ Current versions of all skills. Agents can compare against local versions to che
| site-architecture | 2.0.0 | 2026-05-05 |
| sms | 1.0.0 | 2026-05-21 |
| social | 2.2.0 | 2026-07-09 |
| video | 2.0.1 | 2026-05-18 |
| video | 2.1.0 | 2026-07-14 |
## Recent Changes
### 2.10.0 (2026-07-22)
- **attribution** (new, 1.1.0): a dedicated skill for the hardest question in marketing — which efforts actually drive conversions and revenue. Fills a real gap: attribution was scattered across analytics (UTM setup), ads (platform pixels), revops (pipeline), and ai-seo (the AI blind spot), but no skill owned the *models* or the *reconciliation problem*. Two pillars. **(A) Interpretation** — the six attribution models and when each lies; MTA vs. MMM vs. incrementality and how to choose; self-reported attribution; reconciling the platform-vs-GA-vs-CRM-vs-survey disagreement (never sum across platforms; pick one source of truth; read directional trends); and the direct / branded-search / dark-social / AI blind spots. **(B) Own your attribution (first-party)** — a build runbook for instrumenting attribution yourself when you control the site/app: the identity graph, closing the `identify()` gap (adapted from Tessa Kriesel's PostHog approach), stitching conversions on third-party domains you don't own (SavvyCal/Calendly/Stripe) via metadata passthrough + webhook identity-merge, fail-closed anonymity guards, and first-touch data-quality cleanup — distilled from real production builds (Conversion Factory + Truelist). Four references (`attribution-models.md`, `measurement-paradigms.md`, `by-business-type.md` with B2B/DTC playbooks, `first-party-tracking.md`) and 7 evals covering reconciliation, model choice, the third-party stitch, ROAS incrementality, the direct/branded blind spot, the analytics boundary, and the DTC measurement stack. Pillar B also folds in **production feedback from Tessa Kriesel** (credited): the CRM last mile (sync a `source` field with confidence + basis and a paid-vs-non-paid read onto the account → revops), storing the full ordered touch path so the build track can run Pillar A's multi-touch models on real data, the "expect ~zero until the cross-subdomain stitch is verified in prod" window with a narrowly-scoped campaign-window fallback + pre-stitch backfill, and account-level rollup (excluding free-mail domains) for B2B.
- **analytics** (2.0.0 → 2.0.1): description now hands off attribution modeling and reconciliation to the new attribution skill, keeping analytics scoped to tracking setup, event taxonomy, and UTMs.
### 2.9.1 (2026-07-27)
- **pricing** (2.0.1 → 2.1.0): added a **Pricing Page Teardown** — a two-axis audit of a live pricing page. Axis 1 is the classic human buyer experience (value-prop clarity, plan differentiation, cognitive load, trust signals, psychology, transparency); Axis 2 is the novel **AI-agent readiness** lens: whether the LLMs/agents that increasingly shortlist and compare tools can actually read and quote your pricing — machine-readable prices (not locked in an image or behind "Contact us"), extractable FAQ/objection coverage, per-tier depth in text, and structured data. Includes the memorable **"paste test"** (give the URL to a browsing-capable AI and ask for the plans and prices — if it can't answer, an AI shopping for your buyer can't either), a full 10-dimension rubric + scoring/report template in `references/pricing-page-teardown.md`, and hand-offs to `schema` (Product/Offer JSON-LD) and `ai-seo` (extractability, AI search-bot access, llms.txt). New eval (id 7). AI-agent-readiness lens adapted from Kyle Poyar / Growth Unhinged (learn-from-only, credited).
### 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).
+3 -2
View File
@@ -1,8 +1,8 @@
---
name: analytics
description: When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions "set up tracking," "GA4," "Google Analytics," "conversion tracking," "event tracking," "UTM parameters," "tag manager," "GTM," "analytics implementation," "tracking plan," "how do I measure this," "track conversions," "attribution," "Mixpanel," "Segment," "are my events firing," or "analytics isn't working." Use this whenever someone asks how to know if something is working or wants to measure marketing results. For A/B test measurement, see ab-testing.
description: When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions "set up tracking," "GA4," "Google Analytics," "conversion tracking," "event tracking," "UTM parameters," "tag manager," "GTM," "analytics implementation," "tracking plan," "how do I measure this," "track conversions," "Mixpanel," "Segment," "are my events firing," or "analytics isn't working." Use this whenever someone asks how to know if something is working or wants to measure marketing results. For choosing attribution models, comparing multi-touch/MMM/incrementality, or reconciling conflicting numbers across tools, see attribution. For A/B test measurement, see ab-testing.
metadata:
version: 2.0.0
version: 2.0.1
---
# Analytics Tracking
@@ -304,6 +304,7 @@ For implementation, see the [tools registry](../../tools/REGISTRY.md). Key analy
## Related Skills
- **ab-testing**: For experiment tracking
- **attribution**: For attribution models, multi-touch/MMM/incrementality, and reconciling conflicting numbers across tools (once tracking is live)
- **seo-audit**: For organic traffic analysis
- **cro**: For conversion optimization (uses this data)
- **revops**: For pipeline metrics, CRM tracking, and revenue attribution
+224
View File
@@ -0,0 +1,224 @@
---
name: attribution
description: When the user wants to figure out which marketing actually drives conversions and revenue, choose or interpret an attribution model, or reconcile conflicting numbers across tools. Also use when the user mentions "attribution," "attribution model," "first-touch vs last-touch," "multi-touch," "which channel drives revenue," "what's my real CAC," "my dashboards disagree," "Google/Meta says X but GA says Y," "media mix model," "MMM," "incrementality," "geo lift," "holdout test," "how did you hear about us," "self-reported attribution," "dark social," or wants to instrument attribution themselves — "stitch my bookings to their source," "SavvyCal/Calendly attribution," "close the identify gap," "track conversions on a third-party domain," "first-party / self-hosted attribution." For event tracking setup and UTMs, see analytics. For ad-platform pixels/CAPI, see ads. For pipeline and CRM revenue reporting, see revops. For the AI-search attribution blind spot, see ai-seo.
metadata:
version: 1.1.0
---
# Attribution
You help users answer the hardest question in marketing: **which of my efforts actually caused this conversion and this revenue?** Attribution is where marketers lose the most money — to channels that look good in one dashboard and terrible in another, to "direct" and "branded search" that hide the real source, and to models that quietly encode an opinion as if it were fact.
This skill has two pillars. Know which one the user needs before you dive in:
- **(A) Interpretation** — choosing an attribution model, picking a measurement approach, and *reconciling the conflicting numbers* your tools report. This applies to everyone, even with zero engineering.
- **(B) Own your attribution (first-party)** — instrumenting and stitching attribution *yourself* when you control the site/app. This is the build track. Use it when the user says "I want to track this myself" or is hitting a conversion that lives on a domain they don't own.
Most requests start with (A). Reach for (B) only when they control the surface and want to build.
Product context: check for `.agents/product-marketing.md` and read it if present — business type, sales cycle, and primary conversion drive almost every recommendation here.
## Boundaries — what this skill does NOT own
State these up front so you don't rebuild neighboring skills:
- **General event tracking, tracking plans, UTM setup, GA4/GTM** → **analytics**. Attribution *assumes tracking exists*. The line: analytics = "what events and how to fire them"; attribution = "how touches join to conversions and survive to revenue."
- **Ad-platform pixels, CAPI, server-side conversion tracking** → **ads** (`references/conversion-tracking.md`). Attribution consumes platform-reported numbers and corrects for their bias; it doesn't set up the pixels.
- **Pipeline stages, lead lifecycle, CRM revenue dashboards** → **revops**. Attribution feeds pipeline data; it doesn't define stages.
- **Showing up in / measuring AI search** → **ai-seo**. Attribution names AI traffic as a blind spot only.
---
## Pillar A — Interpretation
### 1. What attribution can and can't tell you
Set expectations before touching a number:
- **Attribution is directional, not truth.** It's a model of causality built from incomplete data (cookies expire, sessions fragment, offline touches vanish, people research on one device and buy on another). Treat it as a strong hint, never a verdict.
- **Every model is an opinion.** "First-touch" says the first ad gets all the credit; "last-touch" says the closing click does. Both are wrong in opposite directions. Choosing a model is choosing whose story to believe — say so out loud.
- **The attribution gap is normal.** The sum of channel-reported conversions almost always exceeds real conversions, because every platform claims credit for the same sale. Your job is to shrink and explain the gap, not to make the numbers tie out perfectly. They won't.
When a user demands one true number, reframe: "We can get you a *defensible, consistent* number and a read on which channels are trending up. A single objective truth doesn't exist — here's why, and here's what we use to make decisions anyway."
### 2. Attribution models
The six standard models and when each one lies:
| Model | Credit rule | Best for | How it lies |
|---|---|---|---|
| **First-touch** | 100% to the first known touch | Top-of-funnel / demand-gen valuation; short cycles | Ignores everything that closed the deal; over-credits awareness channels |
| **Last-touch** | 100% to the last touch before conversion | Direct-response, quick e-comm | Over-credits bottom-funnel + branded search/direct; ignores what created demand |
| **Last non-direct** | 100% to last touch, skipping "direct" | A cheap fix for direct pollution | Still single-touch; just moves the blind spot |
| **Linear** | Equal credit to every touch | Long, multi-touch journeys where every step matters | Treats a throwaway visit like a demo; flatters high-frequency channels |
| **Time-decay** | More credit to touches nearer conversion | Longer cycles where recency matters | Under-credits the top of funnel; still an assumption, not a measurement |
| **Position-based (U-shaped)** | 40% first, 40% last, 20% middle | B2B with clear "created" + "closed" moments | The 40/40/20 split is arbitrary; middle touches get shortchanged |
| **Data-driven (algorithmic/Shapley)** | Credit from modeled marginal contribution | High-volume accounts with enough conversions | A black box; needs volume; can't see offline/dark touches it was never fed |
**Rules of thumb:**
- Never report a single model in isolation for a long sales cycle. Show **first-touch and last-touch side by side** — the truth lives between them, and the gap between them *is* the insight.
- Data-driven attribution needs volume (Google Ads historically gated it behind ~3,000 ad interactions and ~300 conversions in 30 days; it has since relaxed the minimums and made DDA the default, but low volume still makes it noise dressed as science). Use position-based instead when you're thin.
- The model matters far less than being **consistent** and pairing it with an out-of-model sanity check (Pillar A §4, self-reported).
For the model math, worked examples of one journey scored six ways, and Shapley explained plainly, see `references/attribution-models.md`.
### 3. The three measurement paradigms
Models split credit *within* your tracked data. Paradigms are how you get at *causality* — increasingly rigorous, increasingly expensive:
| Paradigm | What it is | Answers | Needs | Watch out |
|---|---|---|---|---|
| **MTA** (multi-touch attribution) | Stitch user-level touches, apply a model | "Which touchpoints appear on converting journeys?" | Clean cross-device user-level tracking | Cookie loss + privacy have gutted user-level data; it silently under-measures |
| **MMM** (media/marketing mix modeling) | Top-down regression of spend vs. outcomes over time | "What's each channel's aggregate contribution, including offline/brand?" | 2–3 yrs of weekly data, spend variation | Correlational; slow to react; needs real budget swings to learn |
| **Incrementality** (geo holdout, PSA, ghost ads, on/off) | Controlled experiment: exposed vs. withheld | "Did this channel *cause* lift I wouldn't have gotten anyway?" | Ability to withhold; enough volume for significance | The gold standard, but you can only test a few things at a time |
**How to choose:** small budget / short cycle → good UTM + last-non-direct + a self-reported survey beats a fancy model. Mid budget, several channels → MTA for day-to-day + periodic incrementality tests on your biggest line items. Large budget, offline + brand spend → MMM for the portfolio + incrementality to validate MMM's coefficients. Incrementality is the tiebreaker whenever two channels both claim the same conversions.
Decision table by budget × sales cycle × channel count, and how to *read* a geo-holdout / PSA test (not a stats tutorial), in `references/measurement-paradigms.md`.
### 4. Self-reported attribution
The most underused signal, and often the most honest for long cycles and dark social. A post-conversion "How did you hear about us?" survey catches what tracking structurally cannot: podcasts, word of mouth, Slack communities, a founder's tweet, "a friend told me."
- **When it beats tracking:** long consideration cycles, high word-of-mouth, brand/community-led, or heavy dark-social (see §5). If a big slice of your journeys are "direct," you have a self-reported-shaped hole.
- **Ask at the moment of conversion** (signup, first purchase, demo request) — highest recall, before memory fades.
- **Wording:** open-ended ("How did you first hear about us?") captures dark social; a short pick-list is easier to quantify but pre-biases the answer. Best practice: pick-list of your known channels **plus a free-text "other/tell us more."**
- **Treat it as a triangulation input, not gospel** — recall is fuzzy and people credit the *memorable* touch, not the first. It's the out-of-model check that keeps your tracked models honest.
- On the build side, this is a form field written to your CRM/analytics as a person property — see Pillar B and `references/first-party-tracking.md`.
### 5. Reconciling conflicting sources
The request behind most attribution work: **"Google says 50, Meta says 40, GA says 60, my CRM says 35 — who's right?"** Nobody is. Here's the framework.
**Why each source systematically lies:**
| Source | Biased toward | Because |
|---|---|---|
| **Ad platforms** (Google/Meta/LinkedIn) | Over-counts *itself* | Claims view-through + click conversions in its own window; every platform counts the same sale; motivated to look good |
| **GA / web analytics** | Last non-direct click | Loses cross-device, loses cookie-blocked users, dumps the unknown into direct |
| **CRM** | Whatever the rep typed / the form captured | Human entry, lead-source overwrites, offline deals with no digital trail |
| **Self-reported survey** | The *memorable* touch | Recall bias; under-counts boring-but-real touches like retargeting |
**How to triangulate:**
1. **Pick one source of truth for the conversion count** — usually your CRM or backend (the system where money is real). Everything else explains *where those came from*, they don't get to redefine *how many*.
2. **Never sum across platforms.** If Google and Meta both claim a conversion, you have one conversion with two claimants, not two conversions. De-dupe against the source-of-truth total.
3. **Read directional agreement, not absolute match.** If every source says paid search is up and organic is down this quarter, that trend is trustworthy even though no two numbers match.
4. **Use self-reported as the tiebreaker** when platforms fight over the same conversions, and **incrementality** when the stakes justify a test.
5. **Expect and budget for the gap.** Report "platforms claim N; we can verify M; the delta is over-claiming + view-through + untracked — here's our best allocation."
The output is an honest allocation with confidence levels, not a false reconciliation to the decimal.
### 6. The blind spots
Where conversions hide, making real channels look weak:
- **Direct** — the junk drawer. Bookmarks and typed URLs, yes, but also stripped referrers, app-to-web, dark social, and any touch your tracking dropped. A large direct share is a *measurement* problem, not a channel.
- **Branded search** — people who discovered you elsewhere and Googled your name. Last-touch hands the credit to paid/organic *branded* search; the real driver was whatever made them search. Segment branded vs. non-branded or you'll defund the top of funnel.
- **Dark social** — sharing that carries no referrer: DMs, Slack/Discord, podcasts, newsletters, screenshots. Structurally invisible to tracking; self-reported is the only way to see it (§4).
- **AI traffic** — assistants and AI search increasingly influence buyers, then send them via branded search or direct, so the AI touch is invisible in analytics. Name it and hand deeper work to **ai-seo**.
The through-line: **when "direct" and "branded search" dominate, your top of funnel is working and your attribution is hiding it.** Say that explicitly — it's the single most common misread in marketing.
### 7. Business-type fork
Defaults differ sharply. Summary here; full playbooks in `references/by-business-type.md`.
- **B2B SaaS (long cycle, sales-assisted):** journeys span weeks–months and multiple people, so single-touch models mislead badly. Anchor on the **CRM as source of truth**, use **first-touch + position-based** side by side, lean hard on **self-reported at demo/signup**, and treat **pipeline/revenue** attribution (→ revops) as the real scoreboard. Offline touches (events, sales convos) make MTA weakest and self-reported strongest here.
- **Ecommerce / DTC (short cycle, self-serve):** fast journeys, high volume, spend concentrated in paid social + search. Anchor on **platform ROAS but distrust it** (iOS/CAPI inflation), validate with **MMM once spend is material** and **incrementality/geo-holdouts** on your biggest channels, and use a **post-purchase survey** to catch what pixels miss. Last-touch is defensible for quick-turn SKUs; MMM+incrementality is how you allocate the real budget.
---
## Pillar B — Own your attribution (first-party)
Use this when the user **controls the site/app** and wants to instrument attribution themselves — especially for a conversion that happens on a **domain they don't own** (a SavvyCal/Calendly/Cal.com booking, a Stripe Checkout page). This pillar is grounded in real production builds; the full runbook with code patterns is in `references/first-party-tracking.md`. The essentials:
### The identity graph
First-party attribution is one idea: **join anonymous browsing to the eventual conversion.**
1. A visitor arrives anonymously; your analytics tool assigns an **anonymous `distinct_id`** and stamps **first-touch properties** (`$initial_referrer`, `$initial_utm_*`) on their events.
2. At conversion (signup, booking, purchase) you call **`identify()`** with a stable id (email or user UUID). This **merges** the anonymous history into a known person — first-touch now survives all the way to the conversion.
3. Every conversion event can now be broken down by first-touch channel. That's the whole game.
### Closing the `identify()` gap
The most common first-party failure: **nothing ever calls `identify()`**, so conversions never join to browsing history and every customer looks like they appeared from nowhere. (Framing adapted from Tessa Kriesel's PostHog approach.) The fix is to call identify at each real conversion. **Audit first** — many SaaS apps already identify at signup; don't rebuild what works. Find the *specific* un-instrumented conversions and close only those.
### Stitching conversions on a third-party domain
The one case that needs real machinery: a conversion that completes on a domain you don't control (a booking tool, a hosted checkout). You can't run your analytics there, so:
1. **At click time**, a capture-phase link decorator appends the visitor's anonymous `distinct_id` to the outbound URL via the tool's **metadata passthrough** (e.g. `?metadata[ph_distinct_id]=<id>`). One document-level listener covers every CTA — no per-link edits.
2. The third-party tool stores that metadata and returns it in its **webhook**.
3. Your **webhook handler** fires an **identity merge** (`$identify` with the booking email as `distinct_id` and the smuggled anonymous id as `$anon_distinct_id`) plus a **conversion event** — joining the booking back onto the marketing journey.
### Guardrails (do not skip)
- **Anonymity guard — fail closed.** Only ever smuggle the *anonymous* id. After `identify()`, the current id becomes the user's email/UUID; leaking that into a third-party URL or merging on it corrupts profiles (person A's email folds into whoever books). Reject ids that look like PII (contain `@`), cap length, and when identity is ambiguous, **send nothing**. If the app identifies by UUID, test `distinct_id === device_id` rather than an `@` check.
- **First-touch data quality.** Redirects overwrite the true first touch. Exclude OAuth/checkout referrers (`accounts.google.com`, `checkout.stripe.com`, `login.*`), your own subdomains (self-referrals), and dev hosts (`localhost`) from referrer classification. This is usually a settings change, not code, and it's the highest-trust-per-effort fix.
- **Cross-subdomain stitching.** Marketing site → app on a subdomain must share one analytics project + a cross-subdomain cookie, or the journey breaks at the handoff. Expect **near-zero numbers until the stitch is verified in prod** — don't panic at empty data; use a campaign-window heuristic fallback and backfill the pre-stitch cohort in the meantime (details in the reference).
### Reporting and the last mile
The first payoff is one insight: your **conversion event broken down by first-touch channel** (`$initial_utm_source` / `$initial_referring_domain`), and — joined to revenue — **channel → conversion → revenue**. Confirm first-touch vs. last-touch config in the tool (many default to last-touch; first-party attribution wants `$initial_*`).
But first-touch alone can't run the multi-touch models from §2. **Store the full ordered touch path** (not just `$initial_*`) and the build track feeds the interpretation track — you can score your own journeys position-based / linear / time-decay instead of only reading about them.
**The last mile — get it into the CRM** (production refinement from Tessa Kriesel). A breakdown in an analytics tool is a report; sales and lifecycle act on attribution *written onto the record*. Sync a **`source` field with `confidence` and `basis`** (journey-linked vs self-reported vs campaign-window fallback) plus a **Paid-vs-Organic read** off the medium, **rolled up to the account** (not just the contact — one B2B org is several people with mixed work/personal emails). How pipeline/lifecycle then *use* it is **revops**' job.
The pattern is tool-agnostic: identify + merge exists in PostHog, Segment, Amplitude, and via user-id in GA4; the third-party stitch works with any tool that has a metadata passthrough + webhook. PostHog + SavvyCal are the worked example in `references/first-party-tracking.md`.
---
## Output format
Deliver an **attribution readout**, not a data dump:
```markdown
# Attribution Readout — [date]
## The question
[What decision this informs — e.g. "where should next quarter's budget go?"]
## Source of truth
[Which system defines the conversion count, and why]
## What each source says
| Channel | Platform-reported | GA | CRM | Self-reported | Our read |
|---------|------------------|----|----|--------------|----------|
[De-duped against source of truth; not summed]
## Model comparison (for long cycles)
[First-touch vs last-touch side by side; the gap is the insight]
## Confidence & gaps
[The attribution gap, the blind spots, what we can't see]
## Recommendation
[Allocation call with confidence levels; the tiebreaker test worth running]
```
## Tool Integrations
For implementation, see the [tools registry](../../tools/REGISTRY.md). Key tools:
| Tool | Best For | MCP | Guide |
|------|----------|:---:|-------|
| **PostHog** | First-party attribution, identify/merge, funnels | - | [posthog.md](../../tools/integrations/posthog.md) |
| **GA4** | Web analytics, model comparison, user-id stitching | ✓ | [ga4.md](../../tools/integrations/ga4.md) |
| **Dub** | Short-link + click attribution | ✓ | [dub-co.md](../../tools/integrations/dub-co.md) |
| **Segment** | CDP — route identify/track to every destination | - | [segment.md](../../tools/integrations/segment.md) |
| **HubSpot** | CRM lead-source + self-reported fields | ✓ | [hubspot.md](../../tools/integrations/hubspot.md) |
| **Salesforce** | CRM as revenue source of truth | - | [salesforce.md](../../tools/integrations/salesforce.md) |
| **Supermetrics** | Pull platform numbers into one place to reconcile | ✓ | [supermetrics.md](../../tools/integrations/supermetrics.md) |
| **RB2B** | De-anonymize B2B website visitors | - | [rb2b.md](../../tools/integrations/rb2b.md) |
---
## Related Skills
- **analytics** — event tracking, tracking plans, UTMs, GA4/GTM setup. Do this *before* attribution.
- **ads** — ad-platform pixels, CAPI, server-side conversion tracking (`references/conversion-tracking.md`).
- **revops** — pipeline stages, lead lifecycle, CRM revenue reporting. Attribution feeds it.
- **ai-seo** — the AI-search attribution blind spot in depth.
- **ab-testing** — controlled experiments; the incrementality mindset applied to on-site changes.
+102
View File
@@ -0,0 +1,102 @@
{
"skill_name": "attribution",
"evals": [
{
"id": 1,
"prompt": "Google Ads says we got 50 conversions last month, Meta says 40, GA4 says 60, and our CRM shows 35 closed deals. Which one is right? I need to know our real numbers before I set next quarter's budget.",
"expected_output": "Should explain that none is 'right' and that summing across platforms is wrong (overlapping claims for the same conversions). Should establish a single source of truth for the conversion COUNT — here the CRM/backend where revenue is real — and treat other sources as explaining where those came from, not redefining how many. Should explain why each source is biased (ad platforms over-count themselves incl. view-through; GA loses cross-device and dumps unknowns into direct; CRM depends on human/form entry; surveys have recall bias). Should recommend reading directional agreement over absolute match, de-duping against the source of truth, and using self-reported / incrementality as tiebreakers. Should set expectation that an attribution gap is normal and deliver an allocation with confidence levels, not a false reconciliation.",
"assertions": [
"States that no single source is objectively right",
"Explicitly warns against summing conversions across platforms (overlapping claims)",
"Picks one source of truth for the conversion count (CRM/backend)",
"Explains the systematic bias of at least three sources",
"Recommends reading directional trends over absolute matching",
"Mentions the attribution gap as expected and to be explained, not eliminated",
"Does not fabricate a single reconciled number as if it were truth"
],
"files": []
},
{
"id": 2,
"prompt": "Should we use first-touch or last-touch attribution? We're a B2B SaaS with a sales cycle that runs about two months and multiple people involved in each deal.",
"expected_output": "Should refuse to pick one in isolation and recommend showing first-touch and last-touch side by side, because the gap between them is the insight for a long cycle. Should explain what each model over/under-credits (first-touch ignores what closed; last-touch over-credits branded search/direct and defunds top of funnel). Should recommend position-based as a defensible primary for B2B (credits created + closed bookends), and lean on self-reported attribution at demo/signup given offline touches. Should point to CRM/pipeline as source of truth (revops) and note data-driven attribution needs volume this business likely lacks. May reference references/attribution-models.md and references/by-business-type.md.",
"assertions": [
"Does not recommend a single model in isolation",
"Recommends showing first-touch and last-touch together",
"Explains what first-touch and last-touch each distort",
"Recommends position-based as a strong B2B primary",
"Emphasizes self-reported attribution for long/offline B2B cycles",
"References pipeline/CRM as the revenue source of truth (revops boundary)"
],
"files": []
},
{
"id": 3,
"prompt": "Our biggest conversion is a sales call people book through SavvyCal, but that happens on savvycal.com so PostHog loses the whole journey. How do we connect a booking back to where the visitor originally came from? We control the marketing site.",
"expected_output": "Should recognize this as first-party attribution on a third-party domain (Pillar B) and lay out the identity-graph stitch: append the visitor's ANONYMOUS distinct_id to the SavvyCal link at click time via the metadata passthrough (metadata[ph_distinct_id]), using a capture-phase document-level listener so all CTAs are covered without per-link edits; SavvyCal returns the metadata in its booking webhook; the webhook fires an $identify merge ($anon_distinct_id = smuggled id, distinct_id = booking email) plus a conversion event. Must stress the anonymity guard — only smuggle the anonymous id, reject email-shaped/PII values, fail closed when ambiguous — and hardening (verify signature, timeout, non-fatal, log ids not emails). Should note first-touch data-quality cleanup and confirming first-touch vs last-touch config. Should point to references/first-party-tracking.md and credit that this method (closing the identify gap) is adapted from Tessa Kriesel's approach. Should suggest auditing whether the self-serve funnel already identifies before building.",
"assertions": [
"Identifies the metadata-passthrough + webhook stitch pattern",
"Describes appending the anonymous distinct_id at click time via a capture-phase listener",
"Describes the webhook $identify merge (anon id + email) plus conversion event",
"Emphasizes the fail-closed anonymity guard (never smuggle identified/PII ids)",
"Includes webhook hardening (signature, timeout, non-fatal, no email logging)",
"Recommends auditing existing identify() coverage before building",
"References first-party-tracking.md"
],
"files": []
},
{
"id": 4,
"prompt": "Meta says our retargeting campaign has a 6x ROAS so we keep scaling it, but revenue isn't really going up. What's going on?",
"expected_output": "Should explain platform-reported ROAS is systematically inflated (self-crediting, view-through, generous windows, post-ATT modeling) and that reported ROAS is not incremental ROAS — retargeting especially claims conversions that would have happened anyway. Should introduce incrementality: run a holdout (withhold retargeting from a random % or geo) and measure the lift; incremental CPA/ROAS uses only the incremental conversions. Should explain that flat revenue alongside high reported ROAS is the classic signature of low incrementality. Should recommend the on/off or holdout test as the tiebreaker. May reference references/measurement-paradigms.md.",
"assertions": [
"Explains platform ROAS is inflated / not incremental",
"Distinguishes reported conversions from incremental conversions",
"Recommends an incrementality test (holdout/geo/on-off) to measure true lift",
"Explains high reported ROAS + flat revenue indicates low incrementality (esp. retargeting)",
"Frames incremental CPA/ROAS as the number that should drive budget"
],
"files": []
},
{
"id": 5,
"prompt": "Half of our conversions show up as 'direct' in analytics and a big chunk of the rest is branded search. Does that mean direct traffic is our best channel?",
"expected_output": "Should say no — direct is the junk drawer (bookmarks/typed URLs but mostly stripped referrers, dark social, app-to-web, and dropped tracking) and branded search is people who discovered you elsewhere then searched your name. Both are where demand created upstream cashes out, not channels to invest in. Should warn that crediting them (last-touch) defunds the top of funnel that actually created the demand. Should recommend segmenting branded vs non-branded search, using self-reported attribution to surface dark social, and treating a large direct share as evidence top-of-funnel is working but under-measured. Should mention AI traffic as a growing contributor to this blind spot (hand deeper work to ai-seo).",
"assertions": [
"States direct is not a real channel (junk-drawer / measurement gap)",
"Explains branded search reflects demand created by other channels",
"Warns that crediting these defunds top-of-funnel",
"Recommends segmenting branded vs non-branded search",
"Recommends self-reported attribution to reveal dark social",
"Mentions AI traffic as part of the blind spot and points to ai-seo"
],
"files": []
},
{
"id": 6,
"prompt": "Can you set up GA4 and our event tracking plan so we can start measuring conversions? We don't have any analytics installed yet.",
"expected_output": "Should recognize this is instrumentation/tracking-plan setup, which is the analytics skill's job, not attribution. Should defer to or cross-reference analytics for GA4 install, event taxonomy, and UTM setup, explaining that attribution assumes tracking already exists and is about how touches join to conversions and survive to revenue. May note it can help with attribution modeling and reconciliation once tracking is live, but should not attempt to build the tracking plan itself under attribution.",
"assertions": [
"Recognizes this as an analytics/instrumentation task, not attribution",
"Defers to or cross-references the analytics skill",
"Explains the boundary (attribution assumes tracking exists)",
"Does not attempt to build the full GA4 tracking plan itself"
],
"files": []
},
{
"id": 7,
"prompt": "We're a DTC ecommerce brand spending about $200k/month across Meta, Google, TikTok, and some podcast sponsorships. How should we actually measure what's working so we can allocate budget?",
"expected_output": "Should give the DTC playbook: store/backend order count as source of truth (not summed platform numbers), distrust platform ROAS for cross-channel decisions, and — given material multi-channel spend including untrackable podcasts — recommend MMM to allocate the portfolio and incrementality (geo-holdouts / on-off) to validate and to test the channels platforms flatter most. Should recommend a post-purchase 'how did you hear about us' survey to catch dark social and the podcast effect that pixels miss. Should note last-touch is only defensible for quick-turn SKUs. May reference references/by-business-type.md and references/measurement-paradigms.md.",
"assertions": [
"Sets store/backend order count as the source of truth, not platform sums",
"Recommends MMM given material spend including offline/podcast channels",
"Recommends incrementality testing to validate and find true lift",
"Recommends a post-purchase self-reported survey for dark social/podcasts",
"Warns against trusting platform-reported ROAS for budget allocation",
"References the by-business-type or measurement-paradigms guidance"
],
"files": []
}
]
}
@@ -0,0 +1,72 @@
# Attribution Models — The Math, Worked
Six standard models, one journey scored six ways, and data-driven attribution explained without the black box. Use this when the user wants to understand *why* two models disagree, or needs to pick one defensibly.
## The worked journey
A single B2B buyer's path to a $12,000 annual deal, five touches over 38 days:
| # | Day | Touch | Role in the story |
|---|---|---|---|
| T1 | 0 | LinkedIn ad (paid social) | First discovered you — created awareness |
| T2 | 5 | Organic blog post (organic search) | Came back to learn — built interest |
| T3 | 12 | Retargeting ad (paid social) | Nudged back mid-consideration |
| T4 | 30 | Branded search (paid search, branded) | Ready to act — searched your name |
| T5 | 38 | Direct → demo request (direct) | Converted |
The whole point: **the touch that gets credit depends entirely on the model, and each model tells a different story about where your $12k came from.**
## The six models, applied
Credit for the $12,000 deal under each model:
| Touch | Channel | First-touch | Last-touch | Last non-direct | Linear | Time-decay | Position (U) |
|---|---|---|---|---|---|---|---|
| T1 | Paid social | **$12,000** | $0 | $0 | $2,400 | $175 | **$4,800** |
| T2 | Organic | $0 | $0 | $0 | $2,400 | $290 | $800 |
| T3 | Paid social | $0 | $0 | $0 | $2,400 | $575 | $800 |
| T4 | Paid search (branded) | $0 | $0 | **$12,000** | $2,400 | $3,415 | $800 |
| T5 | Direct | $0 | **$12,000** | $0 | $2,400 | **$7,545** | **$4,800** |
*(Time-decay uses a 7-day half-life — weight = 0.5^(days-before-conversion / 7), normalized: shares of ~1.5% / 2.4% / 4.8% / 28.5% / 62.9% (dollars rounded to sum to $12,000). With a 38-day journey the credit concentrates hard on the last two touches — which is exactly why time-decay behaves almost like last-touch on long cycles. Position-based is 40/40/20, the 20% split evenly across T2–T4.)*
**Read the disagreement:**
- **First-touch** hands everything to the **LinkedIn ad** — great for arguing paid social's demand-gen value, blind to what closed it.
- **Last-touch** hands everything to **Direct** — which is really "we don't know," the junk-drawer channel (see SKILL.md §6). This is how top-of-funnel gets defunded.
- **Last non-direct** hands it to **branded search** — but branded search only happened *because* the LinkedIn ad and blog created the demand. Crediting the closing branded click is crediting your own brand for demand someone else's channel created.
- **Linear** spreads it evenly — honest that all five mattered, useless for deciding what to cut (everything looks equally important).
- **Time-decay** favors the recent — reasonable for short cycles, but here it under-credits the LinkedIn ad that started everything.
- **Position-based** credits the **bookends** (discovered + closed) — usually the most defensible single model for B2B, because "what created this deal" and "what closed it" are the two decisions you actually make.
**The takeaway to give the user:** report **first-touch and last-touch side by side**. The LinkedIn-vs-Direct gap *is* the insight — it tells you paid social creates demand that later shows up as direct/branded. No single number captures that; the spread does.
## Data-driven / algorithmic attribution (Shapley), plainly
Data-driven attribution (Google's DDA, most MTA tools) doesn't use a fixed rule. It asks a counterfactual: **how much does each touch actually change the probability of conversion?** The formal engine is the **Shapley value** from cooperative game theory.
The plain-English version:
- Treat each touch as a "player" on a team that produced the conversion.
- Look across *all* your journeys — converting and non-converting.
- For a given touch, compare conversion rates of journeys that had it vs. otherwise-similar journeys that didn't, across every possible combination of the other touches.
- A touch's credit = its **average marginal lift** to conversion probability across all those combinations.
So if journeys with a retargeting touch convert meaningfully more often than identical journeys without it, retargeting earns real credit. If adding a channel changes nothing, it earns ~zero — even if it appears on every path.
**When it's worth it:**
- You have **volume** — the counterfactuals need enough conversions to be stable. (Google Ads historically gated data-driven attribution behind ~3,000 ad interactions and ~300 conversions in 30 days; it has since relaxed the hard minimums and made data-driven the default model, but the underlying reality is unchanged: below real volume, DDA is noise dressed as science.) Use position-based instead when you're thin.
- Your journeys are **mostly digital and tracked** — Shapley can only weigh touches it was fed. Offline events, dark social, and cookie-lost touches are invisible to it, so a high-word-of-mouth B2B motion will get a confidently-wrong DDA. Pair it with self-reported (SKILL.md §4).
**Its honest limitations:**
- **Black box** — you can't easily explain to a CFO why LinkedIn got 23%. "The model says so" is a weak budget argument on its own.
- **Correlation, not causation** — it models what *co-occurs* with conversion, not what *causes* it. That's why incrementality testing (see `measurement-paradigms.md`) exists: to validate what DDA claims.
- **Garbage in** — inherits every blind spot in your tracking. If half your journeys are "direct," DDA is confidently splitting credit on half-blind data.
## Choosing — a short decision guide
- **Short cycle, few touches, small volume** → last non-direct, plus a self-reported survey. Don't over-model.
- **Long B2B cycle, clear created/closed moments** → position-based as the primary, first-touch + last-touch shown alongside.
- **High volume, mostly-digital, need day-to-day allocation** → data-driven, validated periodically by incrementality.
- **Offline + brand-heavy, real budget** → don't rely on any user-level model; go MMM + incrementality (see `measurement-paradigms.md`).
In every case: **pick one model, stay consistent, and pair it with an out-of-model check.** Model-switching to make a channel look good is the fastest way to lose trust in the whole attribution program.
@@ -0,0 +1,54 @@
# Attribution by Business Type
Attribution defaults differ sharply by business model. The same "which channel drives revenue?" question wants a different source of truth, model, and paradigm depending on how long your cycle is, how many people are involved, and where your budget goes. Two playbooks: B2B SaaS and Ecommerce/DTC. Match the user's product to one (or blend, for PLG-with-sales).
---
## B2B SaaS (long cycle, sales-assisted)
**Shape of the problem:** journeys run weeks to months, span multiple people (champion, economic buyer, users), and include touches that never appear in web analytics — a conference conversation, a sales call, a Slack-community mention, a peer recommendation. Deal values are high and volume is low, so every deal matters and averages are noisy.
**Why single-touch models mislead badly here:** with 15 touches over 3 months across 4 people, "last-touch = direct" and "first-touch = one LinkedIn ad" are both almost useless. The middle — and the offline — is where the deal was actually won.
### The B2B playbook
1. **Source of truth = the CRM**, not any analytics tool. Revenue is real in the CRM (closed-won, ARR); everything else explains where those deals came from. Pipeline and revenue attribution live in **revops** — attribution feeds it the "source" dimension.
2. **Models: first-touch + position-based, shown together.** First-touch values demand creation (which channel *started* the accounts that became pipeline). Position-based credits the created-and-closed bookends, the two decisions you actually make. Last-touch alone will defund your top of funnel — don't lead with it.
3. **Self-reported attribution is your strongest signal, not a nice-to-have.** Ask "How did you first hear about us?" on the **demo request / signup form** and again qualitatively on sales calls. For high word-of-mouth and dark-social-heavy B2B, this catches what tracking structurally can't (podcasts, communities, "my old coworker used you"). Weight it heavily.
4. **Attribute to pipeline stages, not just the conversion.** The useful B2B question isn't "what drove the form fill" — it's "what drove *qualified pipeline* and *closed revenue*." Break down MQL→SQL→closed-won by first-touch channel; a channel that fills forms but never closes is a trap. (Stage mechanics → revops.)
5. **MTA is weakest here; incrementality is awkward but valuable.** Low volume makes data-driven attribution unreliable and geo-tests hard. Use **on/off tests** for big-ticket programs (turn off a channel for a quarter, watch pipeline) and lean on self-reported + first-touch for the rest.
6. **Account-level, not just lead-level.** Attribution should roll touches up to the *account* (all the people at the buying company), or you'll credit whichever individual happened to fill the form. In practice one org is several people signing up with **mixed work *and* personal emails**, so person-level attribution scatters the story across records — match contacts to the account (email domain, enrichment, or your CRM's contact→account link) and attribute at the **account** level. That's where the signal has to land to be useful to a rep working the whole buying committee. Exclude free-mail domains (gmail/yahoo/outlook) from domain matching — they can't identify a company; fall back to enrichment or manual matching for personal-email signups. *(Production emphasis from Tessa Kriesel; the CRM-sync mechanics live in `first-party-tracking.md` Step 5.)*
**Tooling:** CRM (HubSpot/Salesforce) as truth; a product-analytics tool identifying by user/account UUID for first-party first-touch (see `first-party-tracking.md`); self-reported fields written to the CRM; RB2B-style de-anonymization to catch un-formed account visits.
**The B2B trap to name for the user:** branded search and direct will look like your best "channels" because that's where researched buyers convert. They're not channels — they're where demand *created elsewhere* cashes out. Segment branded vs. non-branded search and treat a big direct share as evidence your top-of-funnel is working, not as a channel to invest in.
---
## Ecommerce / DTC (short cycle, self-serve)
**Shape of the problem:** journeys are fast (minutes to a few days), high-volume, and almost entirely digital and self-serve. Budget concentrates in paid social + paid search + email/SMS. The conversion is a purchase you fully control (your checkout or a hosted one). The dominant lie is **platform over-attribution** — Meta and Google each claiming the same sales.
### The DTC playbook
1. **Source of truth = your store/backend** (Shopify, your payments system) — the count of actual orders. Platform-reported conversions get de-duped *against* that total; they never define it and are never summed.
2. **Distrust platform ROAS by default.** Post-iOS ATT, platforms model and estimate conversions, count view-through, and use generous windows — reported ROAS runs well above incremental ROAS. Use it for in-platform optimization (it's fine for the algorithm) but not for cross-channel budget truth.
3. **Last-touch is defensible for quick-turn, impulse SKUs** — the closing click really is most of the story for a $30 impulse buy. It gets dangerous as consideration lengthens (higher AOV, considered purchases), where it over-credits retargeting and branded search.
4. **MMM once spend is material.** When you're spending real money across paid social, search, and offline (podcasts, TV, influencers, OOH), MMM is how you allocate — it's the only paradigm that sees the untrackable channels and the saturation curves. Below ~six figures/month of blended spend, MMM is overkill; good UTMs + a survey do more.
5. **Incrementality on your biggest channels — especially the "always credited" ones.** Geo-holdouts and on/off tests earn their keep on retargeting, branded search, and Meta prospecting, which platform reporting flatters most. Incremental CPA (spend ÷ *incremental* orders) is the number that should move budget. (See `measurement-paradigms.md`.)
6. **Post-purchase survey to catch the dark-social + brand demand.** A one-question "How did you hear about us?" on the order-confirmation page consistently reveals that podcasts, TikTok organic, and word-of-mouth drive far more than pixels credit — because those touches convert later as "direct" or branded search. Kickstarter-era DTC brands run this as standard for exactly this reason.
**Tooling:** store/backend as truth; platform pixels + CAPI for optimization (setup → ads `conversion-tracking.md`); Supermetrics/Coupler to pull platform numbers into one place for de-duping; a post-purchase survey app; MMM tooling (Robyn/Meridian or a vendor) once spend justifies it.
**The DTC trap to name for the user:** summing platform-reported conversions. If Meta claims 100 and Google claims 80 but you had 120 orders, you do **not** have 180 conversions — you have 120 with overlapping claims. Anchor on the 120 and allocate the overlap with incrementality, not by trusting whichever platform shouts loudest.
---
## Blended / PLG-with-sales
Many modern SaaS businesses are both: self-serve signups *and* a sales-assisted motion for larger accounts. Blend the playbooks:
- Use the **DTC approach for the self-serve funnel** (fast, high-volume, first-party first-touch → conversion, defensible last-non-direct + survey).
- Use the **B2B approach for the sales-assisted funnel** (CRM as truth, position-based, pipeline-stage attribution, self-reported at demo).
- **Alias identities across the two** so a self-serve signup who later becomes a sales-assisted expansion keeps one journey (email↔UUID alias at signup — see `first-party-tracking.md`).
- Report them **separately.** Blending a $50 self-serve signup and a $50k enterprise deal into one "attribution" number hides both stories.
@@ -0,0 +1,238 @@
# First-Party Attribution — The Own-Your-Attribution Runbook
How to instrument and stitch attribution yourself when you control the site/app. This is the build track (Pillar B). It's distilled from real production builds and kept tool-agnostic — **PostHog + SavvyCal are the worked example**, but the pattern maps to any product-analytics tool with `identify()`/merge (Segment, Amplitude, GA4 user-id) and any third-party conversion domain with a metadata passthrough + webhook (Calendly, Cal.com, Stripe Checkout, Typeform).
The core method — closing the `identify()` gap so conversions join to anonymous browsing history — is **adapted from Tessa Kriesel's PostHog attribution approach**. Several of the production refinements that make this operate at scale are also hers, credited inline: the full-touch-path capture that feeds the model track (Step 4), the CRM last-mile with source/confidence/basis and a Paid-vs-Organic read (Step 5), the account rollup, and the "expect ~zero until the stitch is verified, with a campaign-window fallback + backfill" window (Cross-subdomain stitching). Credit where due.
## The one idea
First-party attribution joins **anonymous browsing** to the **eventual conversion**:
```
anonymous visitor identify() at conversion breakdown
───────────────── ──────────────────────── ─────────
distinct_id = anon_uuid identify(email) conversion event
$initial_utm_source=... → merges anon history → by $initial_utm_source
$initial_referrer=... into person(email) = "where do customers come from"
```
Everything below serves that join. If `identify()` never fires, every customer looks like they appeared from nowhere — that's *the gap*.
## Step 0 — Audit before you build
The most expensive mistake is rebuilding attribution that already works. Many SaaS apps already `identify()` at signup and already carry first-touch on person profiles. **Check the live data first:**
- Do person profiles carry `$initial_utm_source` / `$initial_referring_domain`?
- Does a conversion event (`Signed up`, `Converted to paid`) break down *cleanly* by channel, or is everything "Direct"?
- Is identity keyed by **email** or by an internal **UUID**? (This changes every guard below.)
- Does cross-subdomain stitching work (marketing site → app.yourdomain.com)?
Only instrument the **specific conversions that are genuinely un-joined**. In one real audit the self-serve funnel was already solved end-to-end; the *only* gap was a booking on a third-party domain. Don't touch what works.
## Step 1 — Identify at each real conversion
At every conversion moment, call `identify()` with a stable id, and set person properties:
```js
// Normalize before use as a distinct_id — analytics tools match exact strings,
// so "Corey@x.com" and "corey@x.com" split into two people otherwise.
export function identifyUser(email) {
const normalized = email.trim().toLowerCase();
window.posthog?.identify(normalized, { email: normalized });
}
```
With `person_profiles: 'identified_only'`, this is the moment the person is created and their first-touch props are stamped. Fire it on form success, signup, first purchase — any moment you learn who the anonymous visitor actually is.
## Step 2 — Stitch conversions on a domain you don't own
When the conversion completes on a third-party domain (a booking tool, hosted checkout), you can't run your analytics there. Smuggle the anonymous id through the tool's **metadata passthrough**, then merge it back in the **webhook**.
### 2a — Capture-phase link decorator
One document-level listener rewrites every outbound booking link at click time — no per-CTA edits, and it covers plain clicks, keyboard activation, and middle-click (`auxclick`):
```js
// Append the anonymous distinct_id to any SavvyCal link at click time.
function decorate(e) {
const anchor = e.target?.closest?.("a[href]");
if (!(anchor instanceof HTMLAnchorElement)) return;
let url;
try { url = new URL(anchor.href); } catch { return; }
const host = url.hostname;
if (host !== "savvycal.com" && !host.endsWith(".savvycal.com")) return;
const distinctId = getPostHogDistinctId(); // anonymous-only — see guard
if (!distinctId) return; // fail closed
url.searchParams.set("metadata[ph_distinct_id]", distinctId);
anchor.href = url.toString();
}
document.addEventListener("click", decorate, true); // capture phase
document.addEventListener("auxclick", decorate, true);
```
For an **inline embed** (e.g. `/demo` with an embedded calendar), pass the same id in the embed's metadata config instead; poll briefly (~2s) for the id on fresh visits, but never block the calendar from rendering.
### 2b — Read the anonymous id safely
The SDK stub queues calls before it loads, so `get_distinct_id()` returns undefined early — fall back to the tool's own cookie:
```js
export function getPostHogDistinctId() {
if (typeof window === "undefined") return null;
// Prefer the loaded SDK.
try {
if (window.posthog?.__loaded) {
const id = window.posthog.get_distinct_id();
if (id) return isAnonymousDistinctId(id) ? id : null;
}
} catch {}
// Fall back to PostHog's cookie before the SDK finishes loading.
try {
const prefix = `ph_${POSTHOG_API_KEY}_posthog=`;
const cookie = document.cookie.split(/;\s*/).find(c => c.startsWith(prefix));
if (!cookie) return null;
const parsed = JSON.parse(decodeURIComponent(cookie.slice(prefix.length)));
return typeof parsed.distinct_id === "string" && isAnonymousDistinctId(parsed.distinct_id)
? parsed.distinct_id : null;
} catch { return null; }
}
```
### 2c — Merge in the webhook
The third-party tool returns your metadata in its `booking.created` (or `checkout.completed`) webhook. Fire an identity merge + a conversion event to your analytics ingestion endpoint:
```js
// Normalize the booking email the same way the app does (Step 1), or the
// booking person will split from the app-side identity for the same user.
const userId = email.trim().toLowerCase();
const events = [];
if (anonId) {
events.push({
event: "$identify",
distinct_id: userId, // the known person
properties: { $anon_distinct_id: anonId, $set: { email: userId, name } }, // merge the journey
});
}
events.push({
event: "discovery_call_booked",
distinct_id: userId,
properties: { booking_id, journey_linked: Boolean(anonId) }, // track the fallback rate
});
await fetch(`${POSTHOG_HOST}/batch/`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ api_key: POSTHOG_API_KEY, batch: events }),
signal: AbortSignal.timeout(3000), // bound it; never hang the webhook
});
```
When no id survives (link bypassed the decorator, e.g. a booking link inside a generated email/PDF), fall back to **email-only capture** with `journey_linked: false`. You still get the conversion; you just don't get the journey for that one.
**First-touch survival caveat (PostHog specifics):** the `$anon_distinct_id` merge carries the anonymous person's *event* history, but with `person_profiles: 'identified_only'` the anonymous visitor may never have had a person profile, so their `$initial_*` first-touch props aren't guaranteed to land on the merged person. Two robust fixes: call `posthog.createPersonProfile()` client-side *before* the visitor navigates off to the third-party domain (so the profile and its `$initial_*` exist to merge into), **or** capture the first-touch values client-side and pass them through the same metadata passthrough, then re-assert them in the webhook with `$set_once` (`$set_once` never overwrites an existing value, so it's safe). Without one of these, you can get the booking joined to the journey's *events* but a blank `$initial_utm_source` on the person — verify on a real booking. ([posthog-js#1524](https://github.com/PostHog/posthog-js/issues/1524).)
## Step 3 — The guardrails (do not skip)
### Anonymity guard — fail closed
Only ever smuggle the *anonymous* id. After `identify()`, the current `distinct_id` becomes the user's email/UUID — leaking that into a third-party URL, or merging on it in the webhook, folds unrelated people together and leaks PII.
**Pick the guard that matches your identity model — the two are not interchangeable.** The `@`-check below is *only* safe when your app identifies by **email**; do not copy it into a UUID-identity app.
```js
// EMAIL-IDENTITY apps only. True only for ids safe to smuggle: reject
// email-shaped values (an identified email) and cap length.
export function isAnonymousDistinctId(id) {
return id.length > 0 && id.length <= 100 && !id.includes("@");
}
```
**If the app identifies by UUID, not email**, the `@` check is useless — an identified UUID would pass it and leak. Instead test that the current `distinct_id` still equals the `device_id` (calling `identify()` changes `distinct_id` but leaves `device_id`), and **fail closed** when `device_id` is unreadable:
```js
// UUID-identity variant: only anonymous when distinct_id still == device_id.
function isAnonymous(posthog) {
const did = posthog.get_distinct_id?.();
const dev = posthog.get_property?.("$device_id");
if (!did || !dev) return false; // ambiguous → treat as identified, send nothing
return did === dev;
}
```
The rule in one line: **when identity is ambiguous, send nothing.** A missing journey is a data gap; a wrong merge is corruption.
### First-touch data quality — the cheapest big win
Redirects overwrite the true first touch, inflating "Direct"/"Referral" and hiding real acquisition. Exclude these from referrer/channel classification (usually a *settings* change in the analytics tool, not code):
- **OAuth / checkout redirects:** `accounts.google.com`, `login.microsoftonline.com`, `login.live.com`, `checkout.stripe.com`
- **Self / subdomain referrals:** `yourdomain.com`, `app.yourdomain.com`, `auth.yourdomain.com`
- **Dev/internal traffic:** `localhost`, `127.0.0.1`, test accounts
This is the **highest-trust-per-effort** fix in the whole runbook — no deploy, immediate accuracy gain. Do it first.
### Cross-subdomain stitching
Marketing site → app on a subdomain must share **one analytics project** and a **cross-subdomain cookie** (PostHog's `cross_subdomain_cookie` default handles `yourdomain.com` → `app.yourdomain.com`). Verify the journey survives the handoff, or every signup looks like it started at the app.
**Expect near-zero numbers until the stitch is verified in prod — don't panic.** (Production note from Tessa Kriesel.) Before the cross-subdomain stitch is confirmed live, first-party attribution reads *basically nothing* — journeys break at the handoff and everything looks like direct. It flips from ~0 to real numbers the week the stitch actually ships. Two things get you through that window:
- **A campaign-window heuristic fallback.** When a signup has no linked journey, attribute it to the campaign/channel that was live during its signup window — but only when **date + landing page + active UTMs uniquely narrow it to one source**. With overlapping campaigns, evergreen ads, email sends, branded/direct demand, or a shared landing page, the window can't isolate the cause — mark those `unknown` / low-confidence rather than falsely crediting whatever was live. Used narrowly, it's a real signal while the stitch stabilizes and beats a blank; used bluntly, it manufactures false attribution.
- **Backfill only the pre-stitch records that are actually missing a source.** Many pre-stitch signups already have verified or self-reported attribution — **never overwrite a higher-confidence source with the heuristic.** Backfill only the blanks (campaign-window or self-reported), tag them as such, and keep the heuristic-backfilled history visually separate from verified trends so you don't read a cliff on launch day as a real shift.
Mark these fallback-attributed conversions with a lower-confidence `basis` (see Step 5) so you never confuse a heuristic guess with a verified journey.
### Harden the webhook
- Verify the provider's **signature** (`SAVVYCAL_WEBHOOK_SECRET` etc.).
- **Validate** the smuggled id (string, ≤100 chars, no `@`) before merging.
- Run the analytics call **after** any business-critical work, bounded by a timeout, **non-fatal** on failure.
- **Log the booking id, never the email.**
## Step 4 — Report
- **Config check:** many tools default to *last-touch* (PostHog's Marketing Analytics scene does). First-party attribution wants first-touch — build insights on `$initial_*` explicitly, or switch the default.
- **The payoff insight:** conversion event broken down by `$initial_utm_source` / `$initial_referring_domain` — "where does every signup/booking come from."
- **Channel → revenue:** conversion event by channel, joined to revenue/MRR person properties. Note: some tools compute revenue props *at ingest* (person-on-events), so historical events may read 0 — use the persons table for current MRR, or tier by plan.
- **Track your own coverage:** the `journey_linked: false` rate tells you how many conversions bypassed the stitch. Watch it after launch.
- **Store the full touch path, not just `$initial_*`.** (Refinement from Tessa Kriesel.) First-touch alone lets you break conversions down by *first* channel — but it can't run the multi-touch models from the interpretation track (SKILL.md §2: position-based, linear, time-decay). If you also persist the **ordered sequence of touches** per person (channel + timestamp for each, e.g. an events-table query or a `touch_path` array on the person), the build track *feeds* the interpretation track: you can now score the same journey six ways on your own data instead of only reading about the models. This is what makes Pillar A and Pillar B shake hands — capture first-touch to ship, capture the full path to model.
## Step 5 — The last mile: get attribution into the CRM
(This whole step is a production refinement from Tessa Kriesel — it's the thing that turned first-party attribution from a dashboard into an operating signal.)
A channel breakdown living in your analytics tool is a *report*. The thing sales and lifecycle actually act on is **attribution written onto the record in the CRM**, per account. Sync it out:
- **A `source` field, plus `source_confidence` and `source_basis`.** Don't write a bare channel — write the channel *and how you know it*. `basis` is the **evidence type**: `journey_linked` (verified stitch), `self_reported` (survey), or `campaign_window` (the heuristic fallback above). `confidence` is computed from **evidence quality, not just the basis** — a journey_linked touch with clean UTMs is high, the same touch with dirty/missing UTMs is lower, and a *specific* self-report can be high while a vague one is low. Sales treats a high-confidence source very differently from a low-confidence guess — give them both fields or they'll distrust the whole thing.
- **A Paid-vs-Organic read off the medium.** The single most-used cut in practice: mark a touch **`paid`** only from explicit paid mediums (`cpc`, `ppc`, `paid-social`, `display`, `paid`), and classify the rest into a small, configurable taxonomy rather than a blunt "organic" — `owned` (email, push, SMS — though a sponsored newsletter is *paid*), `earned` (organic search/social, referral — but a partner/affiliate referral is closer to paid), `direct` (no medium — unknown, not organic), `unknown`. The fast operational question a rep or nurture flow needs is really **paid vs non-paid** (did this account cost acquisition dollars) — get that boundary right and keep the finer buckets configurable.
- **Roll up to the account, not just the contact** (B2B) — see the account-rollup note below and in `by-business-type.md`.
- **Hand the record off to revops.** Once the source/confidence/basis + paid/organic live on the account, how pipeline and lifecycle *use* them (routing, lead scoring, nurture branching, revenue attribution reporting) is the **revops** skill's job. This runbook's job is to get a trustworthy, labeled source onto the record.
**Account rollup (B2B).** One org is several people signing up with mixed work *and* personal emails, so person-level attribution scatters the story across records. Roll each person's source up to the **account** and attribute at the account level — that's where the signal has to land to be useful to a salesperson working the whole buying committee. Match on email domain, **but exclude free-mail domains** (`gmail.com`, `yahoo.com`, `outlook.com`, …) — those can't identify a company, so a domain match would collapse unrelated people into one bogus account. For personal-email signups, fall back to enrichment, your CRM's contact→account link, or manual matching.
## Verification checklist
- Click a booking CTA → URL shows `metadata[<id_param>]=<anon-uuid>`.
- In console: `posthog.identify('test@x.com')` → click again → the param must **NOT** appear (guard works). `posthog.reset()` after.
- Hand-POST a webhook `/batch/` payload → expect `{"status":"Ok"}`, person appears merged.
- Post-ship: first real webhook log shows `journey_linked: true`.
- Confirm first-touch survives cross-subdomain: start on marketing site, sign up in app, check the person carries the original `$initial_utm_source`.
## Adapting to other stacks
| Piece | PostHog (worked example) | Generalizes to |
|---|---|---|
| Anonymous id | `distinct_id` / `$device_id` | Segment `anonymousId`, Amplitude `deviceId`, GA4 client_id |
| Merge call | `$identify` + `$anon_distinct_id` | Segment `identify` (known `userId`, same `anonymousId`) + `alias` where needed; Amplitude `setUserId` on the session that still holds the anonymous `deviceId` (the stitch is deviceId↔userId — Amplitude's Identify API only sets user *properties*, it does not merge); GA4 `user_id` on the same `client_id` |
| Ingestion | `/batch/` | Segment HTTP API, Amplitude HTTP v2, GA4 Measurement Protocol |
| Third-party passthrough | SavvyCal `metadata[...]` | Calendly UTM/`salesforce_uuid`, Cal.com metadata, Stripe `client_reference_id`/metadata |
| First-touch props | `$initial_*` | Segment/Amplitude first-touch, GA4 first_user_* dimensions |
The shape never changes: **grab the anonymous id → carry it across the boundary → merge on the far side → break the conversion down by first-touch.**
@@ -0,0 +1,74 @@
# Measurement Paradigms — MTA vs. MMM vs. Incrementality
Attribution *models* (see `attribution-models.md`) split credit *within* your tracked data. They can't tell you what would have happened anyway. That's what these three paradigms are for — increasingly rigorous, increasingly expensive ways to get closer to causality. Use this reference to help a user pick, and to explain how a test *reads* (not how to run the statistics).
## The three, compared
| | **MTA** (multi-touch) | **MMM** (media mix modeling) | **Incrementality** (experiments) |
|---|---|---|---|
| **Approach** | Bottom-up: stitch user-level touches, apply a model | Top-down: regress outcomes vs. spend/factors over time | Controlled: withhold exposure from a group, measure the difference |
| **Answers** | "Which touchpoints are on converting journeys?" | "What's each channel's aggregate contribution?" | "Did this channel *cause* lift I wouldn't have gotten?" |
| **Granularity** | Per user, per touch | Per channel, per week | Per test (one channel/tactic at a time) |
| **Data needed** | Clean cross-device user-level tracking | 2–3 yrs weekly data + spend variation | Ability to withhold + enough volume for significance |
| **Reacts** | Real-time | Slowly (weeks/quarters) | Per test cycle |
| **Handles offline/brand** | No | Yes | Yes (if you can split exposure) |
| **Privacy-durable** | Weak (cookie/ID loss) | Strong (aggregate) | Strong (aggregate) |
| **Cost/effort** | Low–medium | High | Medium–high |
## MTA — multi-touch attribution
**What it is:** the user-level approach most marketers mean by "attribution" — join a person's touches, apply first/linear/position/data-driven credit.
**Where it shines:** day-to-day, tactical decisions. "Is this campaign showing up on converting journeys?" Fast, granular, cheap if your tracking exists.
**Why it's structurally weakening:** MTA depends on tracking one person across touches and devices, and that data keeps eroding — Safari/Firefox ITP-style cookie limits, iOS ATT, browser consent gating, ad blockers, and ordinary cross-device behavior (research on mobile, buy on desktop). (Chrome's third-party-cookie deprecation was announced, then walked back, so "cookies are going away" is no longer the clean story — but everything else on that list already limits user-level tracking today.) MTA doesn't announce the gap: it silently under-measures anything it can't follow (dumping it into direct) and over-measures what it *can* see. So treat MTA as **incomplete and directionally biased** — not a clean lower bound (its retargeting/branded numbers are often *over*-stated) — and never the sole basis for a big reallocation.
**Use it for:** ongoing optimization and trend-watching — never as the sole basis for a big budget reallocation.
## MMM — media/marketing mix modeling
**What it is:** a top-down statistical model (historically regression; modern open-source options like Meta's Robyn or Google's Meridian) that explains an outcome (revenue, signups) as a function of spend per channel plus controls (seasonality, promotions, price, macro). It never looks at individuals — it's all aggregate time-series, which is exactly why privacy changes don't touch it.
**What it uniquely gives you:**
- **Offline + brand + hard-to-track channels** — TV, podcasts, OOH, PR, organic — because it works on aggregate spend and outcomes, not clicks.
- **Diminishing returns / saturation curves** — where the next dollar in a channel stops paying off.
- **A portfolio view** — how the whole mix drives the outcome, not credit for one journey.
**What it costs and where it's weak:**
- Needs **2–3 years of weekly data** and **real variation in spend** — if you always spend the same on Meta, the model can't learn Meta's effect. You sometimes have to deliberately vary budgets to feed it.
- **Correlational and slow** — it sees what moved together historically; it reacts in quarters, not days. It can't tell you what to do with tomorrow's campaign.
- **Sensitive to specification** — garbage controls, garbage coefficients. It's a real modeling exercise, not a dashboard toggle.
**Use it for:** annual/quarterly budget allocation across a material, multi-channel (esp. offline-inclusive) spend. Validate its coefficients with incrementality tests — MMM says "Meta contributed X"; a holdout proves whether that's causal.
## Incrementality — the experiments
**What it is:** the only paradigm that measures *causality* directly. Split your audience into an **exposed** group and a **withheld/control** group; the difference in outcomes is the **incremental lift** — conversions you got *because of* the channel, not ones that would have happened anyway.
**Common designs:**
- **Geo holdout / geo-lift** — run the channel in some regions, hold it out of comparable ones; compare outcomes. The workhorse for channels you can't split at the user level. *(Meta's GeoLift, Google's geo experiments.)*
- **PSA tests** — the control group is shown a *public-service ad* in your ad's place, so both groups are equally targeted and "ad-exposed"; the only difference is whether they saw *your* ad. Isolates ad effect from audience-quality bias (the exposed group isn't just "people the algorithm judged likely to convert").
- **Ghost ads** — the control group is *held out of the auction* but the platform logs the ad that *would* have served them (no placeholder is shown); you compare converters among the would-have-been-exposed vs. actually-exposed. Cleaner and cheaper than PSAs (no wasted PSA spend), and the modern default where the platform supports it.
- **Intent-to-treat / on-off (pulse) tests** — turn a channel fully off for a defined window, watch what happens to total conversions. Crude but revealing, especially for "is branded search paid cannibalizing organic?"
- **Holdout audiences** — withhold a random % from a retargeting or email program; the delta is the program's true lift.
### How to *read* a test (not run the stats)
You don't need to compute significance by hand, but you must read a result honestly:
1. **Lift = exposed rate − control rate.** If exposed geos converted at 4.2% and control at 3.6%, incremental lift is ~0.6pp — the rest of that 4.2% would have converted anyway. This is why last-click ROAS is almost always *overstated*: it counts the whole 4.2%.
2. **Check the confidence interval / significance.** "5% lift, but the interval spans −2% to +12%" means you learned nothing — the test was underpowered. Insist on enough volume/duration before believing a point estimate.
3. **Watch for contamination.** Control users who were reached anyway (cross-device, spillover between geos) shrink the measured gap. A "no lift" result can be a leaky test, not a dead channel.
4. **Translate to a decision.** Incremental CPA = spend ÷ *incremental* conversions (not total). This is the number that should drive budget — and it's usually worse than the platform's reported CPA, which is the point.
**Use it for:** the highest-stakes questions and the tiebreakers — "does retargeting actually do anything?", "is branded-search paid just buying clicks we'd get free?", "which of our two biggest channels is really driving growth?" You can only test a few things at a time, so spend those tests on the decisions that matter most.
## Putting them together (the mature stack)
They're layers, not competitors:
- **MTA** for daily/weekly tactical optimization and trend-watching — cheap, granular, directional.
- **MMM** for quarterly/annual portfolio allocation across the full mix including offline — durable, holistic.
- **Incrementality** as the **calibration and tiebreaker** — the ground-truth that keeps MTA and MMM honest, run on your biggest bets.
**Scale to the user:** most SMBs need good UTMs + last-non-direct + a self-reported survey + the occasional on/off test — not an MMM. Bring MMM in when offline/brand spend is material and MTA visibly can't see it. Bring in formal incrementality when a single channel's budget is big enough that being wrong about it is expensive. Match the rigor to the size of the decision.
+197
View File
@@ -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": []
}
]
}
+19 -2
View File
@@ -1,8 +1,8 @@
---
name: pricing
description: "When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increase,' 'value metric,' 'Van Westendorp,' 'willingness to pay,' 'monetization,' 'how much should I charge,' 'my pricing is wrong,' 'pricing page,' 'annual vs monthly,' 'per seat pricing,' or 'should I offer a free plan.' Use this whenever someone is figuring out what to charge or how to structure their plans. For in-app upgrade screens, see paywalls. For offer construction (bonuses, guarantees, value framing, naming) on services/courses/coaching/high-ticket B2B, see offers."
description: "When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increase,' 'value metric,' 'Van Westendorp,' 'willingness to pay,' 'monetization,' 'how much should I charge,' 'my pricing is wrong,' 'pricing page,' 'annual vs monthly,' 'per seat pricing,' 'should I offer a free plan,' 'pricing page teardown,' 'pricing page audit,' 'is my pricing page AI-readable,' or 'can AI read my pricing.' Use this whenever someone is figuring out what to charge, how to structure their plans, or wants to audit a pricing page (for humans and for the AI agents that shortlist tools). For in-app upgrade screens, see paywalls. For offer construction (bonuses, guarantees, value framing, naming) on services/courses/coaching/high-ticket B2B, see offers."
metadata:
version: 2.0.1
version: 2.1.0
---
# Pricing Strategy
@@ -191,6 +191,21 @@ Identifies which features customers value most:
---
## Pricing Page Teardown
When someone wants to audit an existing pricing *page* for **clarity, transparency, and AI-readability** (not the pricing strategy itself, and not conversion-rate optimization — that's `cro`), run a **teardown** that scores it across two axes and returns prioritized fixes:
- **Human buyer experience** — value-prop clarity, plan differentiation, cognitive load, trust signals, pricing psychology, and price transparency.
- **AI-agent readiness** — whether the LLMs and agents that increasingly shortlist and compare tools can actually read and quote your pricing: machine-readable prices (not locked in an image or behind "Contact us"), extractable FAQ/objection coverage, per-tier depth stated in text, and structured data. Buyers now ask ChatGPT/Perplexity/Claude "what's the best X and what does it cost?" *before* visiting — a pricing page an agent can't parse loses deals you never see.
**Fast check — the "paste test":** give the pricing URL to a browsing-capable AI (Perplexity, ChatGPT with search, Claude with web) — or paste the rendered page text — and ask "what are the plans and prices?" A clean miss means agents fetching your page will struggle too (a heuristic, not proof every agent fails).
The AI-readiness fixes are usually high-impact, low-effort (put prices in text, add `Offer` schema). Hand implementation to **schema** (Product/Offer JSON-LD) and **ai-seo** (extractability, AI-bot access, `llms.txt`).
**For the full 10-dimension rubric, scoring, and report template:** See [references/pricing-page-teardown.md](references/pricing-page-teardown.md). *(AI-agent-readiness lens adapted from Kyle Poyar / Growth Unhinged.)*
---
## Pricing Checklist
### Before Setting Prices
@@ -224,6 +239,8 @@ Identifies which features customers value most:
- **churn-prevention**: For cancel flows, save offers, and reducing revenue churn
- **cro**: For optimizing pricing page conversion
- **ai-seo**: For making the pricing page extractable/citable by AI (the teardown's AI-agent-readiness axis)
- **schema**: For Product/Offer structured data so machines can read your tiers and prices
- **copywriting**: For pricing page copy
- **marketing-psychology**: For pricing psychology principles
- **ab-testing**: For testing pricing changes
+14
View File
@@ -85,6 +85,20 @@
"Does not attempt full page CRO audit"
],
"files": []
},
{
"id": 7,
"prompt": "Can you tear down our pricing page? I want to know if it is clear for buyers, and also whether AI tools like ChatGPT or Perplexity can actually read our prices when someone asks them to compare tools in our category.",
"expected_output": "Should run the two-axis pricing page teardown (references/pricing-page-teardown.md), not a generic CRO audit. Axis 1 (human buyer experience): value-prop clarity, plan differentiation, cognitive load, trust signals, pricing psychology, price transparency. Axis 2 (AI-agent readiness): machine-readable pricing (real numbers in HTML/text, not locked in an image, JS-only render, or behind Contact us), extractable FAQ/objection coverage, per-tier depth stated in text, and structured data (Product/Offer schema) + AI-bot crawlability. Should recommend the paste test (paste the URL into an LLM and ask for plans and prices; if it cannot answer, an AI shopping for the buyer cannot either). Should prioritize fixes by impact x effort and note AI-readiness fixes are often high-impact/low-effort. Should hand implementation to schema (Product/Offer JSON-LD) and ai-seo (extractability, AI-bot access, llms.txt). May credit the AI-agent-readiness lens to Kyle Poyar.",
"assertions": [
"Runs the two-axis teardown (human buyer experience AND AI-agent readiness)",
"Checks machine-readable pricing (not locked in an image / JS-only / behind Contact us)",
"Recommends the paste test (an LLM can correctly quote plans and prices)",
"Hands off to schema (Product/Offer structured data) and ai-seo (extractability / AI-bot access / llms.txt)",
"Prioritizes fixes by impact x effort; flags AI-readiness fixes as often high-impact low-effort",
"Does not treat this as pure conversion-rate CRO"
],
"files": []
}
]
}
@@ -0,0 +1,85 @@
# Pricing Page Teardown
A structured way to score a live pricing page and return prioritized fixes. It grades **two axes**: the classic **human buyer experience**, and — the newer, higher-leverage lens — **AI-agent readiness**: whether the LLMs and agents that increasingly shortlist and compare tools can actually read, quote, and recommend your pricing.
> **Framework credit:** the two-axis structure and especially the AI-agent-readiness lens are adapted from **Kyle Poyar's** (Growth Unhinged) pricing-page teardown. Learn-from-only — this rubric is authored independently; credit the framing to Poyar.
## Why the second axis matters now
Buyers increasingly ask ChatGPT, Perplexity, and Claude *"what's the best [category] tool and what does it cost?"* before they ever hit your site. If your price is trapped in an image, rendered only by JavaScript, or missing from the page's text, a text-fetching agent often can't read it — some agents render JS or fall back to vision/OCR, but many don't, so don't count on it. And a "Contact us" tier gives an agent no public number to quote at all. When the agent can't read your price, it recommends and quotes the competitor whose pricing it *can*. This axis is the pricing-page complement to `ai-seo` and `schema` — neither *guarantees* a citation, but a page a fetcher can't parse makes one much less likely.
**The 30-second test — the "paste test":** give the pricing URL to a **browsing-capable** AI (Perplexity, ChatGPT with search, or Claude with web) — or paste the page's *rendered* text — and ask *"What are the plans and prices?"* If it can't answer correctly and completely, agents fetching your page the same way will struggle too. It's a heuristic, not proof every agent fails (some render JS or use vision), but a clean miss is a real finding worth fixing.
## The rubric
Score each dimension **Pass / Partial / Gap** (or 1–5 if you want a number). Two sub-scores (one per axis) plus a prioritized fix list is the deliverable — not a single vanity number.
### Axis 1 — Human buyer experience
| # | Dimension | Passing looks like | Common gaps |
|---|---|---|---|
| 1 | **Value-prop clarity** | Above the fold: what you get + why it's worth it, in the buyer's words | Feature list with no outcome; "flexible plans for every team" |
| 2 | **Plan clarity / differentiation** | Obvious which plan is for whom and exactly how they differ | Feature-soup tables; tiers that blur together; no "who it's for" |
| 3 | **Cognitive load** | A buyer can decide in <30s | Too many tiers (5+), unexplained jargon, decision paralysis |
| 4 | **Trust signals** | Logos, testimonials, security/compliance, a guarantee near the CTA | No proof; trust content buried below the fold |
| 5 | **Pricing psychology** | A recommended/anchor tier, sensible anchoring, coherent charm vs. round pricing | No recommended tier; highest price hidden last; random price endings |
| 6 | **Transparency** | The actual price is shown; what's in/out is clear; no surprise fees | "Contact us" on every tier; hidden overages; usage limits omitted |
### Axis 2 — AI-agent readiness (the novel lens)
| # | Dimension | Passing looks like | Common gaps |
|---|---|---|---|
| 7 | **Machine-readable pricing** | The real numbers are in the page's HTML/text | Price in an image/SVG, JS-only render, or a PDF — text-fetching crawlers get nothing reliable; "Contact sales" leaves no public number to quote |
| 8 | **FAQ / objection coverage** | Extractable answers to "does it do X," "what's the limit," "can I cancel," "is there a free trial" | No FAQ, or answers only in a support portal an agent won't reach |
| 9 | **Per-tier depth in text** | Each plan's inclusions, limits, and quotas stated in words | Differences shown only as checkmark columns in an image; limits unnamed |
| 10 | **Structured data & extractability** | `Product`/`Offer` schema markup, clean semantic HTML, AI search/agent bots allowed to crawl (`llms.txt` is a nice-to-have, not yet a standard) | No schema; pricing behind auth/interaction; AI *search* bots blocked in robots.txt |
Dimensions 7 and 10 hand off to **`schema`** (Product/Offer JSON-LD) and **`ai-seo`** (extractability, AI-bot access, `llms.txt`) for implementation.
## How to run it
1. **Load context** — read `.agents/product-marketing.md` (ICP, positioning) so "clarity" is judged against the *right* buyer.
2. **Fetch the page as an agent would** — get the rendered text/HTML, not a screenshot. Note immediately whether prices appear in the text (that's dimension 7).
3. **Run the paste test** — ask an LLM for the plans and prices from the URL; record what it gets wrong or misses.
4. **Score all 10 dimensions** Pass/Partial/Gap with a one-line reason each.
5. **Prioritize fixes** by impact × effort. AI-readiness gaps are often *high impact, low effort* (add text prices, add Offer schema) — surface those first.
## Output template
```markdown
# Pricing Page Teardown — [url] — [date]
## Scores
- Human buyer experience: [X/6 passing]
- AI-agent readiness: [X/4 passing]
## Paste test
[What an LLM returned for "plans and prices" — and what it got wrong/missed]
## Dimension-by-dimension
| # | Dimension | Verdict | Note |
|---|-----------|---------|------|
| 1 | Value-prop clarity | Pass/Partial/Gap | ... |
| … | … | … | … |
## Prioritized fixes (impact × effort)
1. [High/low] — [fix] — [why it matters] — [→ schema / ai-seo / cro if handing off]
2. ...
## The one thing
[The single highest-leverage fix — often "put your actual prices in text + add Offer schema so AI can quote you."]
```
## Common failure patterns
- **The image-price** — a beautiful pricing graphic with the numbers baked in. Humans love it; text-fetching agents (and screen readers) usually can't read it. Put prices in text; the image can stay as decoration.
- **"Contact us" everywhere** — sometimes right for true enterprise, but if *all* tiers hide price, both humans and agents bounce to a competitor with numbers. Show at least a starting price or a representative range.
- **Checkmark-only tables** — feature differences shown only as ✓/✗ columns in an image or icon font. State the actual limits and inclusions in words.
- **JS-only render / auth wall** — if the price only appears after interaction or login, most fetchers won't see it (only JS-rendering agents might).
- **Blocked AI *search* bots** — the crawlers that feed AI *answers* are the search agents, not the training crawlers: OpenAI's `OAI-SearchBot`, Anthropic's `Claude-SearchBot` / `Claude-User`, Perplexity's `PerplexityBot`. Blocking `GPTBot` only opts out of model *training*, not ChatGPT Search — so check which bots your robots.txt actually blocks. (Bot access is `ai-seo`'s domain — hand it off there.)
## Related
- `schema` — Product/Offer JSON-LD so machines read your tiers and prices.
- `ai-seo` — extractability, AI-bot access, `llms.txt`, getting cited by AI answers.
- `cro` — converting the human once the page is clear.
- `copywriting` — the value-prop and tier copy the teardown flags.
+19 -5
View File
@@ -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."
---
+13
View File
@@ -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": []
}
]
}
+6 -2
View File
@@ -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
+15
View File
@@ -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": []
}
]
}
+84
View File
@@ -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.