@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/domain/expo-native-ui/references/zoom-transitions.md

@@ -0,0 +1,161 @@
+# Apple Zoom Transitions
+
+Fluid zoom transitions for navigating between screens. iOS 18+, Expo SDK 55+, Stack navigator only.
+
+```tsx
+import { Link } from "expo-router";
+```
+
+## Basic Zoom
+
+Use `withAppleZoom` on `Link.Trigger` to zoom the entire trigger element into the destination screen:
+
+```tsx
+<Link href="/photo" asChild>
+  <Link.Trigger withAppleZoom>
+    <Pressable>
+      <Image
+        source={{ uri: "https://example.com/thumb.jpg" }}
+        style={{ width: 120, height: 120, borderRadius: 12 }}
+      />
+    </Pressable>
+  </Link.Trigger>
+</Link>
+```
+
+## Targeted Zoom with `Link.AppleZoom`
+
+Wrap only the element that should animate. Siblings outside `Link.AppleZoom` are not part of the transition:
+
+```tsx
+<Link href="/photo" asChild>
+  <Link.Trigger>
+    <Pressable style={{ alignItems: "center" }}>
+      <Link.AppleZoom>
+        <Image
+          source={{ uri: "https://example.com/thumb.jpg" }}
+          style={{ width: 200, aspectRatio: 4 / 3 }}
+        />
+      </Link.AppleZoom>
+      <Text>Caption text (not zoomed)</Text>
+    </Pressable>
+  </Link.Trigger>
+</Link>
+```
+
+`Link.AppleZoom` accepts only a single child element.
+
+## Destination Target
+
+Use `Link.AppleZoomTarget` on the destination screen to align the zoom animation to a specific element:
+
+```tsx
+// Destination screen (e.g., app/photo.tsx)
+import { Link } from "expo-router";
+
+export default function PhotoScreen() {
+  return (
+    <View style={{ flex: 1 }}>
+      <Link.AppleZoomTarget>
+        <Image
+          source={{ uri: "https://example.com/full.jpg" }}
+          style={{ width: "100%", aspectRatio: 4 / 3 }}
+        />
+      </Link.AppleZoomTarget>
+      <Text>Photo details below</Text>
+    </View>
+  );
+}
+```
+
+Without a target, the zoom animates to fill the entire destination screen.
+
+## Custom Alignment Rectangle
+
+For manual control over where the zoom lands on the destination, use `alignmentRect` instead of `Link.AppleZoomTarget`:
+
+```tsx
+<Link.AppleZoom alignmentRect={{ x: 0, y: 0, width: 200, height: 300 }}>
+  <Image source={{ uri: "https://example.com/thumb.jpg" }} />
+</Link.AppleZoom>
+```
+
+Coordinates are in the destination screen's coordinate space. Prefer `Link.AppleZoomTarget` when possible — use `alignmentRect` only when the target element isn't available as a React component.
+
+## Controlling Dismissal
+
+Zoom screens support interactive dismissal gestures by default (pinch, swipe down when scrolled to top, swipe from leading edge). Use `usePreventZoomTransitionDismissal` on the destination screen to control this.
+
+### Disable all dismissal gestures
+
+```tsx
+import { usePreventZoomTransitionDismissal } from "expo-router";
+
+export default function PhotoScreen() {
+  usePreventZoomTransitionDismissal();
+  return <Image source={{ uri: "https://example.com/full.jpg" }} />;
+}
+```
+
+### Restrict dismissal to a specific area
+
+Use `unstable_dismissalBoundsRect` to prevent conflicts with scrollable content:
+
+```tsx
+usePreventZoomTransitionDismissal({
+  unstable_dismissalBoundsRect: {
+    minX: 0,
+    minY: 0,
+    maxX: 300,
+    maxY: 300,
+  },
+});
+```
+
+This is useful when the destination contains a zoomable scroll view — the system gives that scroll view precedence over the dismiss gesture.
+
+## Combining with Link.Preview
+
+Zoom transitions work alongside long-press previews:
+
+```tsx
+<Link href="/photo" asChild>
+  <Link.Trigger withAppleZoom>
+    <Pressable>
+      <Image
+        source={{ uri: "https://example.com/thumb.jpg" }}
+        style={{ width: 120, height: 120 }}
+      />
+    </Pressable>
+  </Link.Trigger>
+  <Link.Preview />
+</Link>
+```
+
+## Best Practices
+
+**Good use cases:**
+
+- Thumbnail → full image (gallery, profile photos)
+- Card → detail screen with similar visual content
+- Source and destination with similar aspect ratios
+
+**Avoid:**
+
+- Skinny full-width list rows as zoom sources — the transition looks unnatural
+- Mismatched aspect ratios between source and destination without `alignmentRect`
+- Using zoom with sheets or popovers — only works in Stack navigator
+- Hiding the navigation bar — known issues with header visibility during transitions
+
+**Tips:**
+
+- Always provide a close or back button — dismissal gestures are not discoverable
+- If the destination has a zoomable scroll view, use `unstable_dismissalBoundsRect` to avoid gesture conflicts
+- Source view doesn't need to match the tap target — only the `Link.AppleZoom` wrapped element animates
+- When source is unavailable (e.g., scrolled off screen), the transition zooms from the center of the screen
+
+## References
+
+- Expo Router Zoom Transitions: https://docs.expo.dev/router/advanced/zoom-transition/
+- Link.AppleZoom API: https://docs.expo.dev/versions/v55.0.0/sdk/router/#linkapplezoom
+- Apple UIKit Fluid Transitions: https://developer.apple.com/documentation/uikit/enhancing-your-app-with-fluid-transitions

package/.merlin-core/skills/domain/marketing-ops/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: marketing-ops
+description: "Funnel-stage organized marketing playbook covering Foundation (product-marketing, customer-research, marketing-psychology, marketing-ideas), Acquire (paid ads, SEO/AI-SEO, content, social, video, image, outbound, launch, directories, community, free-tools, lead-magnets), Activate (CRO, signup, popups, paywalls, copy editing, A/B testing, analytics, sales enablement, pricing), Retain (onboarding, churn prevention, RevOps lifecycle), Expand (referrals, co-marketing). Use when planning, designing, or executing marketing campaigns end-to-end. For Brazilian direct-response copy methodology, paid traffic ROAS, WhatsApp formats, and Schwartz awareness, see digital-marketing. For SaaS page copy, see general/copywriting."
+license: MIT
+metadata:
+  source: "coreyhaines31/marketingskills (MIT) v2.0.1 + Merlin marketing-ops adaptation"
+  imported: 2026-05-20
+  version: "1.0.0"
+  upstream_baseline: "coreyhaines31/marketingskills v2.0.1 (2026-05-18)"
+  auto_activate:
+    [
+      marketing-ops,
+      campaign,
+      growth-marketing,
+      cro,
+      lead-magnet,
+      customer-research,
+    ]
+  file_triggers:
+    [
+      "**/landing-page/**",
+      "**/lead-magnet/**",
+      "**/funnel/**",
+      "**/cro/**",
+      "**/lifecycle-email/**",
+    ]
+  tool_reminders:
+    - "Before writing any campaign artifact, read .merlin-core/thoughts/shared/decisions/<project>-product-marketing.md if it exists; otherwise activate references/foundation/product-marketing.md to generate it"
+    - "Map every artifact to a funnel stage explicitly (Foundation/Acquire/Activate/Retain/Expand) — refuse to write generic 'marketing copy' without stage assignment"
+    - "Cross-link to digital-marketing for Brazilian DR methodology (3-Document Protocol, Schwartz, Anti-AI, ROAS, WhatsApp formats, R$ benchmarks)"
+    - "For page-level copy structure, route to general/copywriting; for delivery to general/resend-email; for visuals to general/image-gen; for decks to general/blkskrn"
+---
+
+# marketing-ops — Funnel-Stage Marketing Umbrella
+
+Full-funnel marketing playbook organized by stage: **Foundation → Acquire → Activate → Retain → Expand**. Imports 40 skills from `coreyhaines31/marketingskills` v2.0.1 (MIT), wired into the Alkimia engine. Methodology authority on Brazilian direct-response copy, ROAS, WhatsApp formats, and Schwartz awareness remains with [`digital-marketing`](../digital-marketing/SKILL.md).
+
+## Adjacency Map
+
+| Need                                                        | Skill                                                         |
+| ----------------------------------------------------------- | ------------------------------------------------------------- |
+| Brazilian DR methodology, Schwartz, Anti-AI, ROAS, WhatsApp | [`digital-marketing`](../digital-marketing/SKILL.md)          |
+| SaaS page copy (homepage, LP, pricing, feature)             | [`general/copywriting`](../../general/copywriting/SKILL.md)   |
+| Edit/refine existing copy                                   | [`general/copy-editing`](../../general/copy-editing/SKILL.md) |
+| B2B cold outreach + follow-up sequences                     | [`general/cold-email`](../../general/cold-email/SKILL.md)     |
+| Email delivery layer                                        | [`general/resend-email`](../../general/resend-email/SKILL.md) |
+| AI image generation                                         | [`general/image-gen`](../../general/image-gen/SKILL.md)       |
+| Presentation decks                                          | [`general/blkskrn`](../../general/blkskrn/SKILL.md)           |
+| Visual finishing                                            | [`general/mage-beauty`](../../general/mage-beauty/SKILL.md)   |
+
+## Funnel-Stage Map
+
+### 🏛️ Foundation — `references/foundation/`
+
+Foundation-stage skills produce the canonical project brief that every other skill reads first.
+
+- `product-marketing.md` — Positioning + ICP + market context artifact (`.merlin-core/thoughts/shared/decisions/<project>-product-marketing.md`)
+- `customer-research.md` — JTBD, VoC, Reddit/G2 mining, theme clustering
+- `marketing-psychology.md` — Fogg, EAST, COM-B, prospect theory, anchoring
+- `marketing-ideas.md` — 139-idea SaaS marketing catalog
+
+### 🎯 Acquire — `references/acquire/`
+
+Get attention. Paid traffic, SEO, content, social, video, image, outbound, launch, directories, community, partnerships, lead magnets.
+
+- `ads.md`, `ad-creative.md` — Multi-platform paid + bulk creative
+- `ai-seo.md`, `seo-audit.md`, `site-architecture.md`, `schema.md` — Discovery
+- `programmatic-seo.md` _(pointer → digital-marketing)_, `content-strategy.md` _(pointer)_, `launch.md` _(pointer)_
+- `competitors.md`, `competitor-profiling.md` — Comparison & intel
+- `social.md`, `video.md`, `image.md` — Production
+- `directory-submissions.md` — PH + G2 + AI dirs
+- `community-marketing.md`, `co-marketing.md`, `free-tools.md`, `lead-magnets.md` — Pull-based
+- `aso.md` — Mobile
+
+### 🔥 Activate — `references/activate/`
+
+Turn attention into signup/purchase. LP CRO, signup, popups, paywalls, copy editing, A/B testing, analytics, sales enablement.
+
+- `cro.md`, `signup.md`, `popups.md`, `paywalls.md`
+- `copywriting.md` _(pointer → general)_, `copy-editing.md` _(pointer → general)_
+- `emails.md` _(pointer → digital-marketing/email-sequences.md)_, `pricing.md` _(pointer)_
+- `ab-testing.md`, `analytics.md`, `sales-enablement.md`
+
+### 🔄 Retain — `references/retain/`
+
+Keep them using/paying. Onboarding, churn prevention, lifecycle.
+
+- `onboarding.md`, `churn-prevention.md`
+- `revops-lifecycle.md` _(pointer → digital-marketing)_, `revops-operations.md` _(pointer)_
+
+### 🚀 Expand — `references/expand/`
+
+Turn customers into growth.
+
+- `referrals.md`
+- `co-marketing.md`, `community-marketing.md` _(both pointers → acquire stage)_
+
+## When to Activate marketing-ops vs digital-marketing vs general
+
+Decision tree:
+
+1. **Brazilian audience + WhatsApp + info-product launch + R$ ROAS** → `digital-marketing` (it owns the methodology)
+2. **SaaS funnel design / CRO / churn / sales enablement / SEO at scale / lead magnets** → `marketing-ops` (funnel-stage router)
+3. **Need to write the page itself (homepage, LP, pricing, feature, about)** → `general/copywriting`
+4. **Need to edit existing copy** → `general/copy-editing`
+5. **B2B cold outbound prospecting** → `general/cold-email`
+6. **Production artifacts only (email blast, OG image, deck)** → general/{resend-email, image-gen, blkskrn}
+
+When both `digital-marketing` and `marketing-ops` could apply, `digital-marketing` wins on methodology (3-Document Protocol, Schwartz, Anti-AI, ROAS, WhatsApp), `marketing-ops` wins on funnel-stage navigation and skill composition.
+
+## Bundled References (40 skills, organized in `references/`)
+
+See [`references/_index.md`](references/_index.md) for the full funnel-stage map with canonical paths, source attribution, and pointer/imported status.
+
+## Provenance
+
+Imported 2026-05-20 from `coreyhaines31/marketingskills` v2.0.1 (MIT). Per-file attribution is preserved in each reference's frontmatter `metadata.source` field. The `digital-marketing` skill remains authoritative for Brazilian direct-response methodology — see its SKILL.md Integration section for the boundary statement.

package/.merlin-core/skills/domain/marketing-ops/references/_index.md

@@ -0,0 +1,78 @@
+# marketing-ops References — Funnel-Stage Index
+
+Full map of all 40 imported skills from `coreyhaines31/marketingskills` v2.0.1 (MIT), organized by funnel stage. Status legend: **IMPORTED** = upstream body imported here; **POINTER → path** = canonical body lives elsewhere; **POINTER → general/X** = production utility skill in general/.
+
+## 🏛️ Foundation (4 skills)
+
+| Skill                | Canonical path                       | Status   |
+| -------------------- | ------------------------------------ | -------- |
+| product-marketing    | `foundation/product-marketing.md`    | IMPORTED |
+| customer-research    | `foundation/customer-research.md`    | IMPORTED |
+| marketing-psychology | `foundation/marketing-psychology.md` | IMPORTED |
+| marketing-ideas      | `foundation/marketing-ideas.md`      | IMPORTED |
+
+## 🎯 Acquire (20 skills)
+
+| Skill                 | Canonical path                     | Status                                                             |
+| --------------------- | ---------------------------------- | ------------------------------------------------------------------ |
+| ads                   | `acquire/ads.md`                   | IMPORTED                                                           |
+| ad-creative           | `acquire/ad-creative.md`           | IMPORTED                                                           |
+| ai-seo                | `acquire/ai-seo.md`                | IMPORTED                                                           |
+| seo-audit             | `acquire/seo-audit.md`             | IMPORTED                                                           |
+| site-architecture     | `acquire/site-architecture.md`     | IMPORTED                                                           |
+| competitors           | `acquire/competitors.md`           | IMPORTED                                                           |
+| competitor-profiling  | `acquire/competitor-profiling.md`  | IMPORTED                                                           |
+| social                | `acquire/social.md`                | IMPORTED                                                           |
+| video                 | `acquire/video.md`                 | IMPORTED                                                           |
+| image                 | `acquire/image.md`                 | IMPORTED                                                           |
+| directory-submissions | `acquire/directory-submissions.md` | IMPORTED                                                           |
+| community-marketing   | `acquire/community-marketing.md`   | IMPORTED                                                           |
+| co-marketing          | `acquire/co-marketing.md`          | IMPORTED                                                           |
+| free-tools            | `acquire/free-tools.md`            | IMPORTED                                                           |
+| lead-magnets          | `acquire/lead-magnets.md`          | IMPORTED                                                           |
+| aso                   | `acquire/aso.md`                   | IMPORTED                                                           |
+| content-strategy      | `acquire/content-strategy.md`      | POINTER → `../../digital-marketing/references/content-strategy.md` |
+| programmatic-seo      | `acquire/programmatic-seo.md`      | POINTER → `../../digital-marketing/references/programmatic-seo.md` |
+| schema                | `acquire/schema.md`                | POINTER → `../../digital-marketing/references/schema-markup.md`    |
+| launch                | `acquire/launch.md`                | POINTER → `../../digital-marketing/references/launch-strategy.md`  |
+
+## 🔥 Activate (11 skills)
+
+| Skill            | Canonical path                 | Status                                                             |
+| ---------------- | ------------------------------ | ------------------------------------------------------------------ |
+| cro              | `activate/cro.md`              | IMPORTED                                                           |
+| signup           | `activate/signup.md`           | IMPORTED                                                           |
+| popups           | `activate/popups.md`           | IMPORTED                                                           |
+| paywalls         | `activate/paywalls.md`         | IMPORTED                                                           |
+| ab-testing       | `activate/ab-testing.md`       | IMPORTED                                                           |
+| analytics        | `activate/analytics.md`        | IMPORTED                                                           |
+| sales-enablement | `activate/sales-enablement.md` | IMPORTED                                                           |
+| pricing          | `activate/pricing.md`          | POINTER → `../../digital-marketing/references/pricing-strategy.md` |
+| copywriting      | `activate/copywriting.md`      | POINTER → general/copywriting                                      |
+| copy-editing     | `activate/copy-editing.md`     | POINTER → general/copy-editing                                     |
+| emails           | `activate/emails.md`           | POINTER → `../../digital-marketing/references/email-sequences.md`  |
+
+## 🔄 Retain (4 skills)
+
+| Skill             | Canonical path                | Status                                                              |
+| ----------------- | ----------------------------- | ------------------------------------------------------------------- |
+| onboarding        | `retain/onboarding.md`        | IMPORTED                                                            |
+| churn-prevention  | `retain/churn-prevention.md`  | IMPORTED                                                            |
+| revops-lifecycle  | `retain/revops-lifecycle.md`  | POINTER → `../../digital-marketing/references/revops-lifecycle.md`  |
+| revops-operations | `retain/revops-operations.md` | POINTER → `../../digital-marketing/references/revops-operations.md` |
+
+## 🚀 Expand (3 skills)
+
+| Skill               | Canonical path                  | Status                                                               |
+| ------------------- | ------------------------------- | -------------------------------------------------------------------- |
+| referrals           | `expand/referrals.md`           | IMPORTED                                                             |
+| co-marketing        | `expand/co-marketing.md`        | POINTER → `../acquire/co-marketing.md` (canonical in Acquire)        |
+| community-marketing | `expand/community-marketing.md` | POINTER → `../acquire/community-marketing.md` (canonical in Acquire) |
+
+## Summary
+
+- **Total skills:** 40 (matches upstream v2.0.1 count)
+- **IMPORTED bodies:** 32 (canonical upstream content lives here under `marketing-ops/references/`)
+- **POINTER files:** 8 (canonical bodies live in `digital-marketing/references/` or `general/`)
+- **Source:** `coreyhaines31/marketingskills` v2.0.1 (MIT), 2026-05-18 upstream baseline
+- **Imported:** 2026-05-20

package/.merlin-core/skills/domain/marketing-ops/references/acquire/ad-creative/references/generative-tools.md

@@ -0,0 +1,19 @@
+---
+source: coreyhaines31/marketingskills (MIT) v2.0.1
+imported: 2026-05-20 (stub) — full body deferred to follow-up cleanup
+stage: acquire
+skill: ad-creative
+upstream_path: skills/ad-creative/references/generative-tools.md
+---
+
+# generative-tools — reference stub
+
+This is a thin pointer to an upstream reference. The full verbatim body is **deferred** to a future cleanup phase to manage context budget.
+
+**Upstream URL (canonical body):** https://github.com/coreyhaines31/marketingskills/blob/main/skills/ad-creative/references/generative-tools.md
+
+**Raw fetch URL:** https://raw.githubusercontent.com/coreyhaines31/marketingskills/main/skills/ad-creative/references/generative-tools.md
+
+**Parent skill:** [`../ad-creative.md`](../ad-creative.md) (stage: acquire)
+
+**To import the full body** (future task): `curl -sSL <raw URL> -o references/acquire/ad-creative/references/generative-tools.md`, then prepend the standard Adjacency header.

package/.merlin-core/skills/domain/marketing-ops/references/acquire/ad-creative/references/platform-specs.md

@@ -0,0 +1,19 @@
+---
+source: coreyhaines31/marketingskills (MIT) v2.0.1
+imported: 2026-05-20 (stub) — full body deferred to follow-up cleanup
+stage: acquire
+skill: ad-creative
+upstream_path: skills/ad-creative/references/platform-specs.md
+---
+
+# platform-specs — reference stub
+
+This is a thin pointer to an upstream reference. The full verbatim body is **deferred** to a future cleanup phase to manage context budget.
+
+**Upstream URL (canonical body):** https://github.com/coreyhaines31/marketingskills/blob/main/skills/ad-creative/references/platform-specs.md
+
+**Raw fetch URL:** https://raw.githubusercontent.com/coreyhaines31/marketingskills/main/skills/ad-creative/references/platform-specs.md
+
+**Parent skill:** [`../ad-creative.md`](../ad-creative.md) (stage: acquire)
+
+**To import the full body** (future task): `curl -sSL <raw URL> -o references/acquire/ad-creative/references/platform-specs.md`, then prepend the standard Adjacency header.

package/.merlin-core/skills/domain/marketing-ops/references/acquire/ad-creative.md

@@ -0,0 +1,251 @@
+---
+source: coreyhaines31/marketingskills (MIT) v2.0.1
+imported: 2026-05-20
+stage: acquire
+upstream_path: skills/ad-creative/SKILL.md
+---
+
+> **Adjacency:** Part of the [`marketing-ops`](../../SKILL.md) umbrella. For Brazilian-DR creative angles + Anti-AI Copy Detection + 7-part Video Ad Script + Image Ad 4-block templates, see [`digital-marketing/references/copy-formats.md`](../../../digital-marketing/references/copy-formats.md). For campaign strategy, see sibling [`ads.md`](ads.md). For visual production, see [`image.md`](image.md), [`video.md`](video.md), and [`general/image-gen`](../../../../general/image-gen/SKILL.md).
+
+---
+
+# Ad Creative
+
+You are an expert performance creative strategist. Your goal is to generate high-performing ad creative at scale — headlines, descriptions, and primary text that drive clicks and conversions — and iterate based on real performance data.
+
+## Before Starting
+
+**Check for product marketing context first:**
+If `.merlin-core/thoughts/shared/decisions/<project>-product-marketing.md` exists (or legacy `.agents/product-marketing.md`), read it before asking questions.
+
+Gather this context (ask if not provided):
+
+### 1. Platform & Format
+
+- What platform? (Google Ads, Meta, LinkedIn, TikTok, Twitter/X)
+- What ad format? (Search RSAs, display, social feed, stories, video)
+- Are there existing ads to iterate on, or starting from scratch?
+
+### 2. Product & Offer
+
+- What are you promoting?
+- What's the core value proposition?
+- What makes this different from competitors?
+
+### 3. Audience & Intent
+
+- Who is the target audience?
+- What stage of awareness? (Problem-aware, solution-aware, product-aware)
+- What pain points or desires drive them?
+
+### 4. Performance Data (if iterating)
+
+- What creative is currently running?
+- Which headlines/descriptions are performing best? (CTR, conversion rate, ROAS)
+- Which are underperforming?
+- What angles or themes have been tested?
+
+### 5. Constraints
+
+- Brand voice guidelines or words to avoid?
+- Compliance requirements?
+- Any mandatory elements? (Brand name, trademark symbols, disclaimers)
+
+---
+
+## How This Skill Works
+
+### Mode 1: Generate from Scratch
+
+Generate a full set of ad creative based on product context, audience insights, and platform best practices.
+
+### Mode 2: Iterate from Performance Data
+
+Analyze what's working, identify patterns in top performers, and generate new variations that build on winning themes while exploring new angles.
+
+Core loop: Pull performance data → Identify winning patterns → Generate new variations → Validate specs → Deliver
+
+---
+
+## Platform Specs
+
+### Google Ads (Responsive Search Ads)
+
+| Element          | Limit              | Quantity |
+| ---------------- | ------------------ | -------- |
+| Headline         | 30 characters      | Up to 15 |
+| Description      | 90 characters      | Up to 4  |
+| Display URL path | 15 characters each | 2 paths  |
+
+**RSA rules:**
+
+- Headlines must make sense independently and in any combination
+- Pin headlines to positions only when necessary
+- Include at least one keyword-focused, one benefit-focused, one CTA headline
+
+### Meta Ads (Facebook/Instagram)
+
+| Element      | Limit                           | Notes               |
+| ------------ | ------------------------------- | ------------------- |
+| Primary text | 125 chars visible (up to 2,200) | Front-load the hook |
+| Headline     | 40 characters recommended       | Below the image     |
+| Description  | 30 characters recommended       | Below headline      |
+
+### LinkedIn Ads
+
+| Element     | Limit                           | Notes           |
+| ----------- | ------------------------------- | --------------- |
+| Intro text  | 150 chars recommended (600 max) | Above the image |
+| Headline    | 70 chars recommended (200 max)  | Below the image |
+| Description | 100 chars recommended (300 max) | Some placements |
+
+### TikTok Ads
+
+| Element      | Limit                          | Notes           |
+| ------------ | ------------------------------ | --------------- |
+| Ad text      | 80 chars recommended (100 max) | Above the video |
+| Display name | 40 characters                  | Brand name      |
+
+### Twitter/X Ads
+
+| Element     | Limit          | Notes            |
+| ----------- | -------------- | ---------------- |
+| Tweet text  | 280 characters | The ad copy      |
+| Headline    | 70 characters  | Card headline    |
+| Description | 200 characters | Card description |
+
+---
+
+## Generating Ad Copy
+
+### Step 1: Define Your Angles
+
+Before writing individual headlines, establish 3-5 distinct **angles** — different reasons someone would click. Each angle should tap into a different motivation.
+
+**Common angle categories:**
+
+| Category     | Example Angle                        |
+| ------------ | ------------------------------------ |
+| Pain point   | "Stop wasting time on X"             |
+| Outcome      | "Achieve Y in Z days"                |
+| Social proof | "Join 10,000+ teams who..."          |
+| Curiosity    | "The X secret top companies use"     |
+| Comparison   | "Unlike X, we do Y"                  |
+| Urgency      | "Limited time: get X free"           |
+| Identity     | "Built for [specific role/type]"     |
+| Contrarian   | "Why [common practice] doesn't work" |
+
+### Step 2: Generate Variations per Angle
+
+For each angle, generate multiple variations. Vary:
+
+- **Word choice** — synonyms, active vs. passive
+- **Specificity** — numbers vs. general claims
+- **Tone** — direct vs. question vs. command
+- **Structure** — short punch vs. full benefit statement
+
+### Step 3: Validate Against Specs
+
+Before delivering, check every piece of creative against the platform's character limits.
+
+### Step 4: Organize for Upload
+
+Present creative in a structured format that maps to the ad platform's upload requirements.
+
+---
+
+## Iterating from Performance Data
+
+When the user provides performance data:
+
+### Step 1: Analyze Winners
+
+- **Winning themes** — What topics or pain points appear in top performers?
+- **Winning structures** — Questions? Statements? Commands? Numbers?
+- **Winning word patterns** — Specific words or phrases that recur?
+- **Character utilization** — Are top performers shorter or longer?
+
+### Step 2: Analyze Losers
+
+- **Themes that fall flat** — What angles aren't resonating?
+- **Common patterns in low performers** — Too generic? Too long? Wrong tone?
+
+### Step 3: Generate New Variations
+
+- **Doubles down** on winning themes with fresh phrasing
+- **Extends** winning angles into new variations
+- **Tests** 1-2 new angles not yet explored
+- **Avoids** patterns found in underperformers
+
+---
+
+## Writing Quality Standards
+
+### Headlines That Click
+
+**Strong headlines:**
+
+- Specific ("Cut reporting time 75%") over vague ("Save time")
+- Benefits ("Ship code faster") over features ("CI/CD pipeline")
+- Active voice ("Automate your reports") over passive ("Reports are automated")
+- Include numbers when possible ("3x faster," "in 5 minutes," "10,000+ teams")
+
+**Avoid:**
+
+- Jargon the audience won't recognize
+- Claims without specificity ("Best," "Leading," "Top")
+- All caps or excessive punctuation
+- Clickbait that the landing page can't deliver on
+
+### Descriptions That Convert
+
+Use descriptions to:
+
+- Add proof points (numbers, testimonials, awards)
+- Handle objections ("No credit card required")
+- Reinforce CTAs ("Start your free trial today")
+- Add urgency when genuine ("Limited to first 500 signups")
+
+---
+
+## Generating Ad Visuals
+
+For image and video ad creative, use generative AI tools and code-based video rendering:
+
+- **Image generation** — Nano Banana Pro (Gemini), Flux, Ideogram for static ad images
+- **Video generation** — Veo, Kling, Runway, Sora, Seedance, Higgsfield for video ads
+- **Voice & audio** — ElevenLabs, OpenAI TTS, Cartesia for voiceovers, cloning, multilingual
+- **Code-based video** — Remotion for templated, data-driven video at scale
+
+**Recommended workflow:**
+
+1. Generate hero creative with AI tools (exploratory, high-quality)
+2. Build Remotion templates based on winning patterns
+3. Batch produce variations with Remotion using data feeds
+4. Iterate — AI for new angles, Remotion for scale
+
+For Brazilian-DR Anti-AI Visual Protocol (rejects generic gradients, symmetric compositions, template-like layouts), see [`digital-marketing/SKILL.md`](../../../digital-marketing/SKILL.md#anti-ai-visual-protocol).
+
+---
+
+## Common Mistakes
+
+- **Writing headlines that only work together** — RSA headlines get combined randomly
+- **Ignoring character limits** — Platforms truncate without warning
+- **All variations sound the same** — Vary angles, not just word choice
+- **No CTA headlines** — Include at least 2-3 action-oriented headlines
+- **Generic descriptions** — "Learn more about our solution" wastes the slot
+- **Iterating without data** — Gut feelings are less reliable than metrics
+- **Testing too many things at once** — Change one variable per test cycle
+- **Retiring creative too early** — Allow 1,000+ impressions before judging
+
+---
+
+## Related Skills
+
+- **ads** (sibling): Campaign strategy, targeting, budgets, optimization
+- **copywriting** (general): Landing page copy
+- **ab-testing** (activate): Structuring creative tests with statistical rigor
+- **marketing-psychology** (foundation): Psychological principles behind high-performing creative
+- **copy-editing** (general): Polishing ad copy before launch
+- **digital-marketing/copy-formats**: Brazilian-DR 7-part Video Ad + Image Ad 4-block templates + Creative Angle Matrix

package/.merlin-core/skills/domain/marketing-ops/references/acquire/ads/references/ad-copy-templates.md

@@ -0,0 +1,19 @@
+---
+source: coreyhaines31/marketingskills (MIT) v2.0.1
+imported: 2026-05-20 (stub) — full body deferred to follow-up cleanup
+stage: acquire
+skill: ads
+upstream_path: skills/ads/references/ad-copy-templates.md
+---
+
+# ad-copy-templates — reference stub
+
+This is a thin pointer to an upstream reference. The full verbatim body is **deferred** to a future cleanup phase to manage context budget.
+
+**Upstream URL (canonical body):** https://github.com/coreyhaines31/marketingskills/blob/main/skills/ads/references/ad-copy-templates.md
+
+**Raw fetch URL:** https://raw.githubusercontent.com/coreyhaines31/marketingskills/main/skills/ads/references/ad-copy-templates.md
+
+**Parent skill:** [`../ads.md`](../ads.md) (stage: acquire)
+
+**To import the full body** (future task): `curl -sSL <raw URL> -o references/acquire/ads/references/ad-copy-templates.md`, then prepend the standard Adjacency header.