From eaf3bb87f11c069ac21eeb3933c282292643aaf9 Mon Sep 17 00:00:00 2001 From: Tessa Kriesel Date: Thu, 28 May 2026 11:29:52 -0500 Subject: [PATCH] feat(skills): upgrade marketingskills to v2.2.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add `sms` skill (SMS/MMS marketing, compliance-forward, B2C/DTC/SaaS) - Add `prospecting` skill (SaaS + B2B + local SMB, 5-phase ICP→output framework) - Update `ads` skill with Google RSA output spec and hard character-count limits - Update `ai-seo`, `image`, `video` skills with model/guide refresh from v2.0.1 - Wire `sms_campaign` and `prospect_list` artifact types to new skills in skills.ts - Add `sms_campaign` and `prospect_list` to ArtifactType union and ARTIFACT_TYPES - Sync CLAUDE.md and AGENTS.md with v2.2.0 skill names (40 → 42 skills) - Update tests: artifact-patch count 16 → 18, skills.test mappings + disk coverage PINNED_VERSION: 692b76118c6b379f89c0fba987a228a40f58b418 (v2.2.0) --- AGENTS.md | 6 +- CLAUDE.md | 4 +- __tests__/artifact-patch.test.ts | 4 +- __tests__/skills.test.ts | 4 + lib/ai/skills.ts | 2 + skills/PINNED_VERSION | 2 +- skills/ads/SKILL.md | 93 ++++- skills/ads/evals/evals.json | 90 +++++ skills/ads/references/ad-copy-templates.md | 207 ++++++++++ skills/ads/references/audience-targeting.md | 243 ++++++++++++ skills/ads/references/conversion-tracking.md | 361 ++++++++++++++++++ .../references/platform-setup-checklists.md | 277 ++++++++++++++ skills/ai-seo/SKILL.md | 128 ++++--- skills/ai-seo/evals/evals.json | 4 +- skills/ai-seo/references/content-types.md | 71 ++++ skills/image/SKILL.md | 39 +- skills/image/evals/evals.json | 89 +++++ skills/image/references/ai-image-prompting.md | 229 +++++++++++ skills/prospecting/SKILL.md | 256 +++++++++++++ skills/prospecting/evals/evals.json | 107 ++++++ .../prospecting/references/b2b-prospecting.md | 106 +++++ skills/prospecting/references/compliance.md | 123 ++++++ skills/prospecting/references/data-sources.md | 287 ++++++++++++++ .../references/local-prospecting.md | 165 ++++++++ .../references/saas-prospecting.md | 123 ++++++ skills/sms/SKILL.md | 338 ++++++++++++++++ skills/sms/evals/evals.json | 100 +++++ skills/sms/references/compliance.md | 202 ++++++++++ skills/sms/references/platforms.md | 318 +++++++++++++++ skills/sms/references/sequence-templates.md | 282 ++++++++++++++ skills/video/SKILL.md | 28 +- skills/video/evals/evals.json | 88 +++++ skills/video/references/ai-video-prompting.md | 175 +++++++++ types/index.ts | 4 +- 34 files changed, 4474 insertions(+), 81 deletions(-) create mode 100644 skills/ads/evals/evals.json create mode 100644 skills/ads/references/ad-copy-templates.md create mode 100644 skills/ads/references/audience-targeting.md create mode 100644 skills/ads/references/conversion-tracking.md create mode 100644 skills/ads/references/platform-setup-checklists.md create mode 100644 skills/ai-seo/references/content-types.md create mode 100644 skills/image/evals/evals.json create mode 100644 skills/image/references/ai-image-prompting.md create mode 100644 skills/prospecting/SKILL.md create mode 100644 skills/prospecting/evals/evals.json create mode 100644 skills/prospecting/references/b2b-prospecting.md create mode 100644 skills/prospecting/references/compliance.md create mode 100644 skills/prospecting/references/data-sources.md create mode 100644 skills/prospecting/references/local-prospecting.md create mode 100644 skills/prospecting/references/saas-prospecting.md create mode 100644 skills/sms/SKILL.md create mode 100644 skills/sms/evals/evals.json create mode 100644 skills/sms/references/compliance.md create mode 100644 skills/sms/references/platforms.md create mode 100644 skills/sms/references/sequence-templates.md create mode 100644 skills/video/evals/evals.json create mode 100644 skills/video/references/ai-video-prompting.md diff --git a/AGENTS.md b/AGENTS.md index 64325c3..9bc594a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,7 +42,7 @@ Do not introduce additional dependencies without a clear reason. If a new librar ## Skill names — authoritative list -The `/skills` directory contains a pinned copy of `coreyhaines31/marketingskills` (v2.0.0). Only use skill names that actually exist in this repo. +The `/skills` directory contains a pinned copy of `coreyhaines31/marketingskills` (v2.2.0). Only use skill names that actually exist in this repo. - `customer-research` exists and is valid. - `vbf-messaging` does not exist and must never be referenced. Use `product-marketing` instead. @@ -58,9 +58,9 @@ The `/skills` directory contains a pinned copy of `coreyhaines31/marketingskills | `analyze` | `analytics`, `ab-testing` | | `optimize` | `cro`, `copy-editing`, `ab-testing`, `signup`, `onboarding` | -### Valid skill names (complete list from `/skills`, v2.0.0) +### Valid skill names (complete list from `/skills`, v2.2.0) -`ab-testing`, `ad-creative`, `ads`, `ai-seo`, `analytics`, `aso`, `churn-prevention`, `co-marketing`, `cold-email`, `community-marketing`, `competitor-profiling`, `competitors`, `content-strategy`, `copy-editing`, `copywriting`, `cro`, `customer-research`, `directory-submissions`, `emails`, `free-tools`, `image`, `launch`, `lead-magnets`, `marketing-ideas`, `marketing-psychology`, `onboarding`, `paywalls`, `popups`, `pricing`, `product-marketing`, `programmatic-seo`, `referrals`, `revops`, `sales-enablement`, `schema`, `seo-audit`, `signup`, `site-architecture`, `social`, `video` +`ab-testing`, `ad-creative`, `ads`, `ai-seo`, `analytics`, `aso`, `churn-prevention`, `co-marketing`, `cold-email`, `community-marketing`, `competitor-profiling`, `competitors`, `content-strategy`, `copy-editing`, `copywriting`, `cro`, `customer-research`, `directory-submissions`, `emails`, `free-tools`, `image`, `launch`, `lead-magnets`, `marketing-ideas`, `marketing-psychology`, `onboarding`, `paywalls`, `popups`, `pricing`, `product-marketing`, `programmatic-seo`, `prospecting`, `referrals`, `revops`, `sales-enablement`, `schema`, `seo-audit`, `signup`, `site-architecture`, `sms`, `social`, `video` --- diff --git a/CLAUDE.md b/CLAUDE.md index 4e36e1b..1e31af9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -53,9 +53,9 @@ The `/skills` directory contains a pinned copy of `coreyhaines31/marketingskills | `analyze` | `analytics`, `ab-testing` | | `optimize` | `cro`, `copy-editing`, `ab-testing`, `signup`, `onboarding` | -### Valid skill names (complete list from `/skills`, v2.0.0) +### Valid skill names (complete list from `/skills`, v2.2.0) -`ab-testing`, `ad-creative`, `ads`, `ai-seo`, `analytics`, `aso`, `churn-prevention`, `co-marketing`, `cold-email`, `community-marketing`, `competitor-profiling`, `competitors`, `content-strategy`, `copy-editing`, `copywriting`, `cro`, `customer-research`, `directory-submissions`, `emails`, `free-tools`, `image`, `launch`, `lead-magnets`, `marketing-ideas`, `marketing-psychology`, `onboarding`, `paywalls`, `popups`, `pricing`, `product-marketing`, `programmatic-seo`, `referrals`, `revops`, `sales-enablement`, `schema`, `seo-audit`, `signup`, `site-architecture`, `social`, `video` +`ab-testing`, `ad-creative`, `ads`, `ai-seo`, `analytics`, `aso`, `churn-prevention`, `co-marketing`, `cold-email`, `community-marketing`, `competitor-profiling`, `competitors`, `content-strategy`, `copy-editing`, `copywriting`, `cro`, `customer-research`, `directory-submissions`, `emails`, `free-tools`, `image`, `launch`, `lead-magnets`, `marketing-ideas`, `marketing-psychology`, `onboarding`, `paywalls`, `popups`, `pricing`, `product-marketing`, `programmatic-seo`, `prospecting`, `referrals`, `revops`, `sales-enablement`, `schema`, `seo-audit`, `signup`, `site-architecture`, `sms`, `social`, `video` --- diff --git a/__tests__/artifact-patch.test.ts b/__tests__/artifact-patch.test.ts index 4c81a0e..5f37210 100644 --- a/__tests__/artifact-patch.test.ts +++ b/__tests__/artifact-patch.test.ts @@ -129,8 +129,8 @@ describe('PATCH /api/artifacts/[id] — type validation', () => { } }); - it('ARTIFACT_TYPES covers all 16 supported types', () => { - expect(ARTIFACT_TYPES).toHaveLength(16); + it('ARTIFACT_TYPES covers all 18 supported types', () => { + expect(ARTIFACT_TYPES).toHaveLength(18); }); }); diff --git a/__tests__/skills.test.ts b/__tests__/skills.test.ts index b9719ac..e1e7b7b 100644 --- a/__tests__/skills.test.ts +++ b/__tests__/skills.test.ts @@ -204,6 +204,8 @@ describe('getSkillNamesForMode', () => { ['competitor_analysis', ['competitors', 'competitor-profiling']], ['seo', ['seo-audit', 'ai-seo']], ['cro', ['cro']], + ['sms_campaign', ['sms']], + ['prospect_list', ['prospecting']], ]; for (const [artifactType, expectedSkills] of mappings) { @@ -291,6 +293,8 @@ describe('loadSkillsForMode', () => { 'competitor_analysis', 'seo', 'cro', + 'sms_campaign', + 'prospect_list', ]; for (const at of artifactTypes) { await loadSkillsForMode('create', at); diff --git a/lib/ai/skills.ts b/lib/ai/skills.ts index 9b09b54..94c288f 100644 --- a/lib/ai/skills.ts +++ b/lib/ai/skills.ts @@ -65,6 +65,8 @@ const ARTIFACT_TYPE_SKILLS: Partial> = { competitor_analysis: ['competitors', 'competitor-profiling'], seo: ['seo-audit', 'ai-seo'], cro: ['cro'], + sms_campaign: ['sms'], + prospect_list: ['prospecting'], }; const DEFAULT_CREATE_SKILLS = ['copywriting']; diff --git a/skills/PINNED_VERSION b/skills/PINNED_VERSION index ebf3dc8..4a63791 100644 --- a/skills/PINNED_VERSION +++ b/skills/PINNED_VERSION @@ -1 +1 @@ -bd8eb1a0e5a82379537298c0570e85279ca27337 +692b76118c6b379f89c0fba987a228a40f58b418 diff --git a/skills/ads/SKILL.md b/skills/ads/SKILL.md index 7d9c4e6..89ba47b 100644 --- a/skills/ads/SKILL.md +++ b/skills/ads/SKILL.md @@ -2,7 +2,7 @@ name: ads description: "When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' 'audience targeting,' 'Google Ads,' 'Facebook ads,' 'LinkedIn ads,' 'ad budget,' 'cost per click,' 'ad spend,' or 'should I run ads.' Use this for campaign strategy, audience targeting, bidding, and optimization. For bulk ad creative generation and iteration, see ad-creative. For landing page optimization, see cro." metadata: - version: 2.0.0 + version: 2.0.1 --- # Paid Ads @@ -257,6 +257,97 @@ Before launching campaigns, ensure proper tracking and account setup. --- +## Google RSA Output Spec (mandatory when generating RSAs) + +When the user requests Google Ads RSAs (Responsive Search Ads), output MUST comply with these platform limits and structural requirements. Do not output any RSA that violates them. + +### Hard limits per RSA (enforce before responding) + +- **Headlines:** exactly **15** per RSA, each **≤ 30 characters** (count characters, including spaces). Render as `1. ... (NN chars)` so the reader can verify. +- **Descriptions:** exactly **4** per RSA, each **≤ 90 characters**. +- **Paths:** up to 2 path fields, each **≤ 15 characters**. +- **Final URL:** present, https. +- **Pinning:** state any pinned positions explicitly. Default = unpinned unless user asks. +- **Per-account guardrail:** Google enforces **3 RSAs max per ad group**. When the user asks for >3, group them by ad group. + +### Required sidecar artifacts (always include with RSA request) + +1. **Ad group structure**, labeled `Ad group structure:` — list each ad group with its theme, target keywords (match types), and which RSAs map to it. +2. **Negative keyword list**, labeled `Negative keywords:` — minimum **8** entries, group-level vs campaign-level called out. +3. **Sitelinks** (≥ 4), **Callouts** (≥ 4 ≤25 chars), **Structured snippets** if relevant. + +### Medical / CFM compliance (when product context indicates pt-BR medical practice) + +If `.agents/product-marketing.md` indicates a Brazilian medical practice (CFM-regulated), the following terms are **forbidden** in headlines, descriptions, sitelinks, and callouts: + +- Superlatives: `#1`, `melhor`, `o melhor`, `melhor do brasil`, `top`, `referência` +- Outcome promises: `garantido`, `garantia`, `cura`, `cura definitiva`, `100%`, `resultado garantido`, `livre da dor` +- Comparative claims vs other doctors/clinics + +Use neutral framing: `atendimento`, `consulta`, `avaliação`, `segunda opinião`, `agende sua consulta`, `tire suas dúvidas`. Geo modifier (`Porto Alegre`, `POA`, `Zona Sul POA`) required where the prompt specifies a region. + +### Output ORDER (mandatory — emit in this order to avoid truncation) + +1. **Ad group structure** (short) +2. **Negative keywords** (≥8, MANDATORY — emit BEFORE RSAs so it isn't dropped if output runs long) +3. **Sitelinks** (≥4) +4. **Callouts** (≥4) +5. **RSA1, RSA2, RSA3** (largest section, last — safe to truncate gracefully) + +### Output template (mandatory shape) + +``` +Ad group structure: +- AG1 [theme]: keywords (match types) → RSA1, RSA2 +- AG2 [theme]: ... + +Negative keywords: + Campaign-level: + - + - + (≥4 here) + Ad-group level: + - AG1: , + - AG2: , + (≥4 more here — TOTAL ≥8 entries) + +Sitelinks (≥4): + - | <desc1 (≤35)> | <desc2 (≤35)> | URL + +Callouts (≥4, each ≤25 chars): + - <callout> + +RSA1 — [ad group name] + Final URL: https://... + Path1: ... Path2: ... + Headlines (15, each ≤30 chars): + 1. <headline> (NN chars) + ... + 15. <headline> (NN chars) + Descriptions (4, each ≤90 chars): + 1. <description> (NN chars) + ... + 4. <description> (NN chars) + Pinning: H1=none; H2=none; ... (or explicit pins) + +RSA2 — ... +RSA3 — ... +``` + +### Self-check before responding + +Before sending the output, run this checklist mentally: + +- [ ] Each RSA has exactly 15 headlines, exactly 4 descriptions. +- [ ] Every headline is ≤30 chars; every description is ≤90 chars. Character counts printed. +- [ ] Negative keyword list labeled and ≥8 entries. +- [ ] Ad group structure labeled. +- [ ] If medical (CFM): no forbidden superlative/outcome words; geo modifier present where required; language is pt-BR. + +If any check fails, rewrite before responding. Do not ship partial RSAs. + +--- + ## Common Mistakes to Avoid ### Strategy diff --git a/skills/ads/evals/evals.json b/skills/ads/evals/evals.json new file mode 100644 index 0000000..17c11eb --- /dev/null +++ b/skills/ads/evals/evals.json @@ -0,0 +1,90 @@ +{ + "skill_name": "ads", + "evals": [ + { + "id": 1, + "prompt": "Help me plan a paid advertising strategy. We're a B2B SaaS tool for HR teams, selling at $99/month per seat. We have $15k/month to spend on ads and want to generate demo requests. Where should we advertise?", + "expected_output": "Should check for product-marketing.md first. Should apply the platform selection guide based on B2B, HR audience, $99/month price point. Should recommend LinkedIn (B2B targeting by job title/industry), Google Ads (search intent for HR software keywords), and potentially Meta (retargeting). Should recommend campaign structure with naming conventions. Should define audience targeting strategy for each platform. Should set budget allocation across platforms. Should define success metrics and attribution approach. Should recommend starting structure and scaling plan.", + "assertions": [ + "Checks for product-marketing.md", + "Applies platform selection guide", + "Recommends platforms appropriate for B2B HR audience", + "Recommends campaign structure with naming conventions", + "Defines audience targeting per platform", + "Sets budget allocation across platforms", + "Defines success metrics", + "Recommends starting structure and scaling plan" + ], + "files": [] + }, + { + "id": 2, + "prompt": "Our Google Ads CPC is $12 and our cost per lead is $180. Is that good? We're getting about 80 leads/month from a $15k budget.", + "expected_output": "Should evaluate the metrics in context. Should assess: $12 CPC for B2B (reasonable depending on industry), $180 CPL (depends on LTV — need to compare against customer lifetime value), 80 leads/month from $15k (math checks out). Should apply the campaign optimization framework: check quality score, search term relevance, landing page conversion rate, negative keywords. Should recommend specific optimization levers to reduce CPC and CPL. Should frame performance against industry benchmarks if applicable. Should ask about downstream conversion rates (lead → demo → customer).", + "assertions": [ + "Evaluates metrics in context", + "Compares CPL against LTV considerations", + "Applies campaign optimization framework", + "Recommends specific optimization levers", + "Asks about downstream conversion rates", + "Provides industry context for benchmarking" + ], + "files": [] + }, + { + "id": 3, + "prompt": "we want to run retargeting ads for people who visited our site but didn't convert. how should we set this up?", + "expected_output": "Should trigger on casual phrasing. Should apply the retargeting strategies section, specifically the funnel-based approach. Should recommend audience segments: all visitors (broad), pricing page visitors (high intent), blog readers (lower intent), and cart/signup abandoners (highest intent). Should recommend different messaging and offers for each segment. Should address frequency capping to avoid ad fatigue. Should recommend retargeting platforms (Meta, Google Display, LinkedIn). Should include duration windows for each audience.", + "assertions": [ + "Triggers on casual phrasing", + "Applies funnel-based retargeting approach", + "Recommends audience segments by intent level", + "Recommends different messaging per segment", + "Addresses frequency capping", + "Recommends retargeting platforms", + "Includes audience duration windows" + ], + "files": [] + }, + { + "id": 4, + "prompt": "Should we advertise on TikTok? We sell accounting software to small businesses. Our current ads are on Google and Meta.", + "expected_output": "Should apply the platform selection guide for TikTok specifically. Should evaluate TikTok fit for accounting software + small business audience: likely a weaker fit than Google/Meta for this category (lower purchase intent, younger skewing audience, less B2B targeting). Should discuss when TikTok CAN work for B2B (brand awareness, creative content, younger business owners). Should provide an honest recommendation with caveats. Should suggest a small test budget approach if they want to try.", + "assertions": [ + "Applies platform selection guide for TikTok", + "Evaluates fit for accounting + small business audience", + "Provides honest assessment of likely weaker fit", + "Discusses when TikTok can work for B2B", + "Suggests small test budget if proceeding", + "Compares to their existing Google/Meta performance" + ], + "files": [] + }, + { + "id": 5, + "prompt": "How do we structure our Google Ads campaigns? We have 50+ keywords we want to target for our CRM product.", + "expected_output": "Should apply the campaign structure and naming conventions framework. Should recommend organizing campaigns by theme/intent (brand, competitor, product features, pain points). Should recommend ad group structure (tightly themed, 5-15 keywords per group). Should define naming conventions for campaigns and ad groups. Should recommend match types strategy. Should include negative keyword lists. Should provide a sample campaign structure.", + "assertions": [ + "Applies campaign structure framework", + "Organizes campaigns by theme/intent", + "Recommends tight ad group structure", + "Defines naming conventions", + "Recommends match types strategy", + "Includes negative keyword lists", + "Provides sample campaign structure" + ], + "files": [] + }, + { + "id": 6, + "prompt": "Can you write some ad copy for our Facebook ads? We need headlines and descriptions for 5 different angles.", + "expected_output": "Should recognize this is an ad creative generation task, not campaign strategy. Should defer to or cross-reference the ad-creative skill, which handles platform-specific ad copy generation with character limits, angle-based variation, and batch generation. May provide brief ad copy framework guidance but should make clear that ad-creative is the right skill for generating ad copy at scale.", + "assertions": [ + "Recognizes this as ad creative generation", + "References or defers to ad-creative skill", + "Does not attempt bulk ad copy generation using campaign strategy patterns" + ], + "files": [] + } + ] +} diff --git a/skills/ads/references/ad-copy-templates.md b/skills/ads/references/ad-copy-templates.md new file mode 100644 index 0000000..0481840 --- /dev/null +++ b/skills/ads/references/ad-copy-templates.md @@ -0,0 +1,207 @@ +# Ad Copy Templates Reference + +Detailed formulas and templates for writing high-converting ad copy. + +## Contents +- Primary Text Formulas (Problem-Agitate-Solve, Before-After-Bridge, Social Proof Lead, Feature-Benefit Bridge, Direct Response) +- Headline Formulas (For Search Ads, For Social Ads) +- CTA Variations (Soft CTAs, Hard CTAs, Urgency CTAs, Action-Oriented CTAs) +- Platform-Specific Copy Guidelines (Google Search Ads, Meta Ads, LinkedIn Ads) +- Copy Testing Priority + +## Primary Text Formulas + +### Problem-Agitate-Solve (PAS) + +``` +[Problem statement] +[Agitate the pain] +[Introduce solution] +[CTA] +``` + +**Example:** +> Spending hours on manual reporting every week? +> While you're buried in spreadsheets, your competitors are making decisions. +> [Product] automates your reports in minutes. +> Start your free trial → + +--- + +### Before-After-Bridge (BAB) + +``` +[Current painful state] +[Desired future state] +[Your product as the bridge] +``` + +**Example:** +> Before: Chasing down approvals across email, Slack, and spreadsheets. +> After: Every approval tracked, automated, and on time. +> [Product] connects your tools and keeps projects moving. + +--- + +### Social Proof Lead + +``` +[Impressive stat or testimonial] +[What you do] +[CTA] +``` + +**Example:** +> "We cut our reporting time by 75%." — Sarah K., Marketing Director +> [Product] automates the reports you hate building. +> See how it works → + +--- + +### Feature-Benefit Bridge + +``` +[Feature] +[So that...] +[Which means...] +``` + +**Example:** +> Real-time collaboration on documents +> So your team always works from the latest version +> Which means no more version confusion or lost work + +--- + +### Direct Response + +``` +[Bold claim/outcome] +[Proof point] +[CTA with urgency if genuine] +``` + +**Example:** +> Cut your reporting time by 80% +> Join 5,000+ marketing teams already using [Product] +> Start free → First month 50% off + +--- + +## Headline Formulas + +### For Search Ads + +| Formula | Example | +|---------|---------| +| [Keyword] + [Benefit] | "Project Management That Teams Actually Use" | +| [Action] + [Outcome] | "Automate Reports \| Save 10 Hours Weekly" | +| [Question] | "Tired of Manual Data Entry?" | +| [Number] + [Benefit] | "500+ Teams Trust [Product] for [Outcome]" | +| [Keyword] + [Differentiator] | "CRM Built for Small Teams" | +| [Price/Offer] + [Keyword] | "Free Project Management \| No Credit Card" | + +### For Social Ads + +| Type | Example | +|------|---------| +| Outcome hook | "How we 3x'd our conversion rate" | +| Curiosity hook | "The reporting hack no one talks about" | +| Contrarian hook | "Why we stopped using [common tool]" | +| Specificity hook | "The exact template we use for..." | +| Question hook | "What if you could cut your admin time in half?" | +| Number hook | "7 ways to improve your workflow today" | +| Story hook | "We almost gave up. Then we found..." | + +--- + +## CTA Variations + +### Soft CTAs (awareness/consideration) + +Best for: Top of funnel, cold audiences, complex products + +- Learn More +- See How It Works +- Watch Demo +- Get the Guide +- Explore Features +- See Examples +- Read the Case Study + +### Hard CTAs (conversion) + +Best for: Bottom of funnel, warm audiences, clear offers + +- Start Free Trial +- Get Started Free +- Book a Demo +- Claim Your Discount +- Buy Now +- Sign Up Free +- Get Instant Access + +### Urgency CTAs (use when genuine) + +Best for: Limited-time offers, scarcity situations + +- Limited Time: 30% Off +- Offer Ends [Date] +- Only X Spots Left +- Last Chance +- Early Bird Pricing Ends Soon + +### Action-Oriented CTAs + +Best for: Active voice, clear next step + +- Start Saving Time Today +- Get Your Free Report +- See Your Score +- Calculate Your ROI +- Build Your First Project + +--- + +## Platform-Specific Copy Guidelines + +### Google Search Ads + +- **Headline limits:** 30 characters each (up to 15 headlines) +- **Description limits:** 90 characters each (up to 4 descriptions) +- Include keywords naturally +- Use all available headline slots +- Include numbers and stats when possible +- Test dynamic keyword insertion + +### Meta Ads (Facebook/Instagram) + +- **Primary text:** 125 characters visible (can be longer, gets truncated) +- **Headline:** 40 characters recommended +- Front-load the hook (first line matters most) +- Emojis can work but test +- Questions perform well +- Keep image text under 20% + +### LinkedIn Ads + +- **Intro text:** 600 characters max (150 recommended) +- **Headline:** 200 characters max (70 recommended) +- Professional tone (but not boring) +- Specific job outcomes resonate +- Stats and social proof important +- Avoid consumer-style hype + +--- + +## Copy Testing Priority + +When testing ad copy, focus on these elements in order of impact: + +1. **Hook/angle** (biggest impact on performance) +2. **Headline** +3. **Primary benefit** +4. **CTA** +5. **Supporting proof points** + +Test one element at a time for clean data. diff --git a/skills/ads/references/audience-targeting.md b/skills/ads/references/audience-targeting.md new file mode 100644 index 0000000..00dc42b --- /dev/null +++ b/skills/ads/references/audience-targeting.md @@ -0,0 +1,243 @@ +# Audience Targeting Reference + +Detailed targeting strategies for each major ad platform. + +## Contents +- Google Ads Audiences (Search Campaign Targeting, Display/YouTube Targeting) +- Meta Audiences (Core Audiences, Custom Audiences, Lookalike Audiences) +- LinkedIn Audiences (Job-Based Targeting, Company-Based Targeting, High-Performing Combinations) +- Twitter/X Audiences +- TikTok Audiences +- Audience Size Guidelines +- Exclusion Strategy + +## Google Ads Audiences + +### Search Campaign Targeting + +**Keywords:** +- Exact match: [keyword] — most precise, lower volume +- Phrase match: "keyword" — moderate precision and volume +- Broad match: keyword — highest volume, use with smart bidding + +**Audience layering:** +- Add audiences in "observation" mode first +- Analyze performance by audience +- Switch to "targeting" mode for high performers + +**RLSA (Remarketing Lists for Search Ads):** +- Bid higher on past visitors searching your terms +- Show different ads to returning searchers +- Exclude converters from prospecting campaigns + +### Display/YouTube Targeting + +**Custom intent audiences:** +- Based on recent search behavior +- Create from your converting keywords +- High intent, good for prospecting + +**In-market audiences:** +- People actively researching solutions +- Pre-built by Google +- Layer with demographics for precision + +**Affinity audiences:** +- Based on interests and habits +- Better for awareness +- Broad but can exclude irrelevant + +**Customer match:** +- Upload email lists +- Retarget existing customers +- Create lookalikes from best customers + +**Similar/lookalike audiences:** +- Based on your customer match lists +- Expand reach while maintaining relevance +- Best when source list is high-quality customers + +--- + +## Meta Audiences + +### Core Audiences (Interest/Demographic) + +**Interest targeting tips:** +- Layer interests with AND logic for precision +- Use Audience Insights to research interests +- Start broad, let algorithm optimize +- Exclude existing customers always + +**Demographic targeting:** +- Age and gender (if product-specific) +- Location (down to zip/postal code) +- Language +- Education and work (limited data now) + +**Behavior targeting:** +- Purchase behavior +- Device usage +- Travel patterns +- Life events + +### Custom Audiences + +**Website visitors:** +- All visitors (last 180 days max) +- Specific page visitors +- Time on site thresholds +- Frequency (visited X times) + +**Customer list:** +- Upload emails/phone numbers +- Match rate typically 30-70% +- Refresh regularly for accuracy + +**Engagement audiences:** +- Video viewers (25%, 50%, 75%, 95%) +- Page/profile engagers +- Form openers +- Instagram engagers + +**App activity:** +- App installers +- In-app events +- Purchase events + +### Lookalike Audiences + +**Source audience quality matters:** +- Use high-LTV customers, not all customers +- Purchasers > leads > all visitors +- Minimum 100 source users, ideally 1,000+ + +**Size recommendations:** +- 1% — most similar, smallest reach +- 1-3% — good balance for most +- 3-5% — broader, good for scale +- 5-10% — very broad, awareness only + +**Layering strategies:** +- Lookalike + interest = more precision early +- Test lookalike-only as you scale +- Exclude the source audience + +--- + +## LinkedIn Audiences + +### Job-Based Targeting + +**Job titles:** +- Be specific (CMO vs. "Marketing") +- LinkedIn normalizes titles, but verify +- Stack related titles +- Exclude irrelevant titles + +**Job functions:** +- Broader than titles +- Combine with seniority level +- Good for awareness campaigns + +**Seniority levels:** +- Entry, Senior, Manager, Director, VP, CXO, Partner +- Layer with function for precision + +**Skills:** +- Self-reported, less reliable +- Good for technical roles +- Use as expansion layer + +### Company-Based Targeting + +**Company size:** +- 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5000+ +- Key filter for B2B + +**Industry:** +- Based on company classification +- Can be broad, layer with other criteria + +**Company names (ABM):** +- Upload target account list +- Minimum 300 companies recommended +- Match rate varies + +**Company growth rate:** +- Hiring rapidly = budget available +- Good signal for timing + +### High-Performing Combinations + +| Use Case | Targeting Combination | +|----------|----------------------| +| Enterprise sales | Company size 1000+ + VP/CXO + Industry | +| SMB sales | Company size 11-200 + Manager/Director + Function | +| Developer tools | Skills + Job function + Company type | +| ABM campaigns | Company list + Decision-maker titles | +| Broad awareness | Industry + Seniority + Geography | + +--- + +## Twitter/X Audiences + +### Targeting options: +- Follower lookalikes (accounts similar to followers of X) +- Interest categories +- Keywords (in tweets) +- Conversation topics +- Events +- Tailored audiences (your lists) + +### Best practices: +- Follower lookalikes of relevant accounts work well +- Keyword targeting catches active conversations +- Lower CPMs than LinkedIn/Meta +- Less precise, better for awareness + +--- + +## TikTok Audiences + +### Targeting options: +- Demographics (age, gender, location) +- Interests (TikTok's categories) +- Behaviors (video interactions) +- Device (iOS/Android, connection type) +- Custom audiences (pixel, customer file) +- Lookalike audiences + +### Best practices: +- Younger skew (18-34 primarily) +- Interest targeting is broad +- Creative matters more than targeting +- Let algorithm optimize with broad targeting + +--- + +## Audience Size Guidelines + +| Platform | Minimum Recommended | Ideal Range | +|----------|-------------------|-------------| +| Google Search | 1,000+ searches/mo | 5,000-50,000 | +| Google Display | 100,000+ | 500K-5M | +| Meta | 100,000+ | 500K-10M | +| LinkedIn | 50,000+ | 100K-500K | +| Twitter/X | 50,000+ | 100K-1M | +| TikTok | 100,000+ | 1M+ | + +Too narrow = expensive, slow learning +Too broad = wasted spend, poor relevance + +--- + +## Exclusion Strategy + +Always exclude: +- Existing customers (unless upsell) +- Recent converters (7-14 days) +- Bounced visitors (<10 sec) +- Employees (by company or email list) +- Irrelevant page visitors (careers, support) +- Competitors (if identifiable) diff --git a/skills/ads/references/conversion-tracking.md b/skills/ads/references/conversion-tracking.md new file mode 100644 index 0000000..1817f46 --- /dev/null +++ b/skills/ads/references/conversion-tracking.md @@ -0,0 +1,361 @@ +# Conversion Tracking Setup + +How to set up conversion tracking pixels across ad platforms. This guide covers installation, event configuration, and validation — everything a marketer needs to ensure ad spend is properly attributed. + +--- + +## Why This Matters + +Without conversion tracking: +- Ad platforms can't optimize for your actual goals +- You're flying blind on ROAS and CPA +- Retargeting audiences can't be built +- You'll waste budget on impressions that don't convert + +Get tracking right before spending a dollar on ads. + +--- + +## Platform Pixels Overview + +| Platform | Pixel/Tag Name | Events API | Key Events | +|----------|---------------|:----------:|------------| +| **Google Ads** | Google tag (gtag.js) | Enhanced Conversions | purchase, sign_up, generate_lead | +| **Meta** | Meta Pixel + CAPI | Conversions API | Purchase, Lead, ViewContent, AddToCart | +| **LinkedIn** | Insight Tag | Conversions API | conversion (URL or event-based) | +| **TikTok** | TikTok Pixel | Events API | Purchase, ViewContent, AddToCart, CompleteRegistration | +| **Twitter/X** | Twitter Pixel | - | Purchase, SignUp, Download | + +--- + +## Google Ads + +### Install the Google tag + +Add to every page, in `<head>`: + +```html +<script async src="https://www.googletagmanager.com/gtag/js?id=AW-XXXXXXXXX"></script> +<script> + window.dataLayer = window.dataLayer || []; + function gtag(){dataLayer.push(arguments);} + gtag('js', new Date()); + gtag('config', 'AW-XXXXXXXXX'); +</script> +``` + +Replace `AW-XXXXXXXXX` with your Conversion ID from Google Ads > Tools > Conversions. + +### Set up conversion actions + +In Google Ads > Goals > Conversions > New conversion action: + +| Conversion | Category | Value | Count | +|-----------|----------|-------|-------| +| Purchase | Purchase | Dynamic (order value) | Every | +| Sign up / Lead | Sign-up | Fixed ($X estimated value) | One | +| Demo request | Lead | Fixed ($X estimated value) | One | +| Free trial start | Sign-up | Fixed ($X estimated value) | One | + +### Fire conversion events + +```javascript +// Purchase +gtag('event', 'conversion', { + 'send_to': 'AW-XXXXXXXXX/CONVERSION_LABEL', + 'value': 99.00, + 'currency': 'USD', + 'transaction_id': 'ORDER-123' +}); + +// Lead / Sign up +gtag('event', 'conversion', { + 'send_to': 'AW-XXXXXXXXX/CONVERSION_LABEL', + 'value': 50.00, + 'currency': 'USD' +}); +``` + +### Enhanced Conversions + +Sends hashed first-party data (email, phone) to improve attribution after cookie restrictions. Enable in Google Ads > Goals > Settings > Enhanced conversions. + +```javascript +gtag('set', 'user_data', { + 'email': 'user@example.com', // auto-hashed by gtag + 'phone_number': '+11234567890' +}); +``` + +### Google Tag Manager alternative + +If using GTM instead of inline gtag.js: +1. Install GTM container on all pages +2. Create Google Ads conversion tags in GTM +3. Set triggers for conversion events (form submissions, purchases) +4. Use the Data Layer to pass dynamic values (order amount, transaction ID) +5. Test with GTM Preview mode before publishing + +--- + +## Meta (Facebook/Instagram) + +### Install the Meta Pixel + +Add to every page, in `<head>`: + +```html +<script> + !function(f,b,e,v,n,t,s) + {if(f.fbq)return;n=f.fbq=function(){n.callMethod? + n.callMethod.apply(n,arguments):n.queue.push(arguments)}; + if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0'; + n.queue=[];t=b.createElement(e);t.async=!0; + t.src=v;s=b.getElementsByTagName(e)[0]; + s.parentNode.insertBefore(t,s)}(window, document,'script', + 'https://connect.facebook.net/en_US/fbevents.js'); + fbq('init', 'YOUR_PIXEL_ID'); + fbq('track', 'PageView'); +</script> +``` + +Replace `YOUR_PIXEL_ID` from Meta Events Manager. + +### Standard events + +```javascript +// View a product or key page +fbq('track', 'ViewContent', { + content_name: 'Pro Plan', + content_category: 'Pricing', + value: 29.00, + currency: 'USD' +}); + +// Lead capture (form submit, demo request) +fbq('track', 'Lead', { + content_name: 'Demo Request', + value: 50.00, + currency: 'USD' +}); + +// Purchase +fbq('track', 'Purchase', { + value: 99.00, + currency: 'USD', + content_type: 'product', + contents: [{ id: 'pro-plan', quantity: 1 }] +}); + +// Add to cart (e-commerce) +fbq('track', 'AddToCart', { + content_ids: ['SKU-123'], + content_type: 'product', + value: 49.00, + currency: 'USD' +}); +``` + +### Conversions API (CAPI) + +Server-side tracking that works alongside the pixel. Required for accurate tracking after iOS 14+ and cookie restrictions. + +Set up via: +- **Direct integration** — send events from your server to Meta's API +- **Partner integrations** — Shopify, WooCommerce, Segment, etc. have built-in CAPI support +- **Conversions API Gateway** — Meta's managed solution via AWS + +Key: send the same events from both pixel (browser) AND CAPI (server), with a shared `event_id` for deduplication. + +### Aggregated Event Measurement + +Required for iOS 14+ tracking. In Events Manager > Aggregated Event Measurement: +1. Verify your domain +2. Configure and prioritize your top 8 events in order of business importance +3. Purchase should typically be #1, Lead #2 + +--- + +## LinkedIn + +### Install the Insight Tag + +Add to every page, before `</body>`: + +```html +<script type="text/javascript"> + _linkedin_partner_id = "YOUR_PARTNER_ID"; + window._linkedin_data_partner_ids = window._linkedin_data_partner_ids || []; + window._linkedin_data_partner_ids.push(_linkedin_partner_id); + (function(l) { + if (!l){window.lintrk = function(a,b){window.lintrk.q.push([a,b])}; + window.lintrk.q=[]} + var s = document.getElementsByTagName("script")[0]; + var b = document.createElement("script"); + b.type = "text/javascript";b.async = true; + b.src = "https://snap.licdn.com/li.lms-analytics/insight.min.js"; + s.parentNode.insertBefore(b, s);})(window.lintrk); +</script> +``` + +### Conversion tracking + +LinkedIn supports two methods: + +**URL-based**: Fires when someone visits a specific URL (e.g., `/thank-you`). +Set up in Campaign Manager > Analyze > Conversion Tracking > Create Conversion. + +**Event-based**: Fire manually on specific actions: + +```javascript +window.lintrk('track', { conversion_id: YOUR_CONVERSION_ID }); +``` + +### LinkedIn CAPI + +For server-side tracking, LinkedIn offers a Conversions API. Set up via partner integrations (Segment, Tealium) or direct API calls. Deduplicates with the Insight Tag automatically when configured correctly. + +--- + +## TikTok + +### Install the TikTok Pixel + +Add to every page, in `<head>`: + +```html +<script> + !function (w, d, t) { + w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[]; + ttq.methods=["page","track","identify","instances","debug","on","off", + "once","ready","alias","group","enableCookie","disableCookie","holdConsent", + "revokeConsent","grantConsent"],ttq.setAndDefer=function(t,e) + {t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}; + for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]); + ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0; + n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e}; + ttq.load=function(e,n){var r="https://analytics.tiktok.com/i18n/pixel/events.js", + o=n&&n.partner;ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=r, + ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{}, + ttq._o[e]=n||{};var s=document.createElement("script"); + s.type="text/javascript",s.async=!0,s.src=r+"?sdkid="+e+"&lib="+t; + var a=document.getElementsByTagName("script")[0]; + a.parentNode.insertBefore(s,a)}; + ttq.load('YOUR_PIXEL_ID'); + ttq.page(); + }(window, document, 'ttq'); +</script> +``` + +### Standard events + +```javascript +// View content +ttq.track('ViewContent', { + content_id: 'pro-plan', + content_type: 'product', + content_name: 'Pro Plan', + value: 29.00, + currency: 'USD' +}); + +// Complete registration / sign up +ttq.track('CompleteRegistration', { + content_name: 'Free Trial' +}); + +// Purchase +ttq.track('Purchase', { + content_id: 'pro-plan', + content_type: 'product', + value: 99.00, + currency: 'USD', + quantity: 1 +}); + +// Add to cart +ttq.track('AddToCart', { + content_id: 'SKU-123', + content_type: 'product', + value: 49.00, + currency: 'USD' +}); +``` + +### Events API (server-side) + +TikTok's Events API works like Meta's CAPI — send the same events from your server for better attribution. Use `event_id` for deduplication with browser pixel events. + +### Advanced Matching + +Pass hashed user data for better attribution: + +```javascript +ttq.identify({ + email: 'user@example.com', // auto-hashed + phone_number: '+11234567890' +}); +``` + +--- + +## Validation Checklist + +After installing any pixel, verify before going live: + +### Browser-side checks + +- [ ] Pixel fires on every page (check via browser extension) +- [ ] Conversion events fire at the right moment (after confirmed action, not on button click) +- [ ] Event parameters contain correct values (currency, amount, content IDs) +- [ ] No duplicate events firing on the same action +- [ ] Events fire on both desktop and mobile + +### Platform-side checks + +- [ ] Events appear in the platform's event manager/diagnostics +- [ ] Test conversions show correct values +- [ ] Event match quality is acceptable (Meta: score > 6) +- [ ] Server-side events are deduplicating with browser events (not double-counting) + +### Debugging tools + +| Platform | Tool | +|----------|------| +| Google | Google Tag Assistant, Chrome DevTools Network tab | +| Meta | Meta Pixel Helper (Chrome extension), Events Manager Test Events | +| LinkedIn | Insight Tag Validator in Campaign Manager | +| TikTok | TikTok Pixel Helper (Chrome extension), Events Manager | +| All | GTM Preview Mode (if using Google Tag Manager) | + +--- + +## Common Mistakes + +- **Firing purchase events on button click instead of confirmed payment** — always fire on the success/thank-you page or after server confirmation +- **Missing deduplication between pixel and server events** — without a shared `event_id`, you'll double-count conversions +- **Not testing on mobile** — many pixels break on mobile browsers or in-app webviews +- **Hardcoded test values** — remove test transaction amounts before going live +- **Forgetting to exclude internal traffic** — your team's visits inflate conversion data +- **Installing pixels without consent management** — GDPR/CCPA require user consent before firing tracking pixels in applicable regions +- **Pixel installed but no conversion actions created** — the pixel collects data, but the ad platform won't optimize without defined conversion actions + +--- + +## When to Use Server-Side Tracking + +Browser-only tracking is increasingly unreliable due to: +- iOS 14+ App Tracking Transparency +- Third-party cookie deprecation +- Ad blockers (30%+ of tech audiences) + +**Use server-side (CAPI/Events API) when:** +- Running Meta or TikTok ads (strongly recommended) +- Your audience is tech-savvy (higher ad blocker usage) +- You need accurate purchase/revenue attribution +- You're spending >$5K/month on any platform + +**Server-side is optional when:** +- Running Google Ads only (Enhanced Conversions covers most gaps) +- Low ad spend / testing phase +- B2B with LinkedIn only (Insight Tag is still reliable) diff --git a/skills/ads/references/platform-setup-checklists.md b/skills/ads/references/platform-setup-checklists.md new file mode 100644 index 0000000..5e663a5 --- /dev/null +++ b/skills/ads/references/platform-setup-checklists.md @@ -0,0 +1,277 @@ +# Platform Setup Checklists + +Complete setup checklists for major ad platforms. + +## Contents +- Google Ads Setup (Account Foundation, Conversion Tracking, Analytics Integration, Audience Setup, Campaign Readiness, Ad Extensions, Brand Protection) +- Meta Ads Setup (Business Manager Foundation, Pixel & Tracking, Domain & Aggregated Events, Audience Setup, Catalog, Creative Assets, Compliance) +- LinkedIn Ads Setup (Campaign Manager Foundation, Insight Tag & Tracking, Audience Setup, Lead Gen Forms, Document Ads, Creative Assets, Budget Considerations) +- Twitter/X Ads Setup (Account Foundation, Tracking, Audience Setup, Creative) +- TikTok Ads Setup (Account Foundation, Pixel & Tracking, Audience Setup, Creative) +- Universal Pre-Launch Checklist + +## Google Ads Setup + +### Account Foundation + +- [ ] Google Ads account created and verified +- [ ] Billing information added +- [ ] Time zone and currency set correctly +- [ ] Account access granted to team members + +### Conversion Tracking + +- [ ] Google tag installed on all pages +- [ ] Conversion actions created (purchase, lead, signup) +- [ ] Conversion values assigned (if applicable) +- [ ] Enhanced conversions enabled +- [ ] Test conversions firing correctly +- [ ] Import conversions from GA4 (optional) + +### Analytics Integration + +- [ ] Google Analytics 4 linked +- [ ] Auto-tagging enabled +- [ ] GA4 audiences available in Google Ads +- [ ] Cross-domain tracking set up (if multiple domains) + +### Audience Setup + +- [ ] Remarketing tag verified +- [ ] Website visitor audiences created: + - All visitors (180 days) + - Key page visitors (pricing, demo, features) + - Converters (for exclusion) +- [ ] Customer match lists uploaded +- [ ] Similar audiences enabled + +### Campaign Readiness + +- [ ] Negative keyword lists created: + - Universal negatives (free, jobs, careers, reviews, complaints) + - Competitor negatives (if needed) + - Irrelevant industry terms +- [ ] Location targeting set (include/exclude) +- [ ] Language targeting set +- [ ] Ad schedule configured (if B2B, business hours) +- [ ] Device bid adjustments considered + +### Ad Extensions + +- [ ] Sitelinks (4-6 relevant pages) +- [ ] Callouts (key benefits, offers) +- [ ] Structured snippets (features, types, services) +- [ ] Call extension (if phone leads valuable) +- [ ] Lead form extension (if using) +- [ ] Price extensions (if applicable) +- [ ] Image extensions (where available) + +### Brand Protection + +- [ ] Brand campaign running (protect branded terms) +- [ ] Competitor campaigns considered +- [ ] Brand terms in negative lists for non-brand campaigns + +--- + +## Meta Ads Setup + +### Business Manager Foundation + +- [ ] Business Manager created +- [ ] Business verified (if running certain ad types) +- [ ] Ad account created within Business Manager +- [ ] Payment method added +- [ ] Team access configured with proper roles + +### Pixel & Tracking + +- [ ] Meta Pixel installed on all pages +- [ ] Standard events configured: + - PageView (automatic) + - ViewContent (product/feature pages) + - Lead (form submissions) + - Purchase (conversions) + - AddToCart (if e-commerce) + - InitiateCheckout (if e-commerce) +- [ ] Conversions API (CAPI) set up for server-side tracking +- [ ] Event Match Quality score > 6 +- [ ] Test events in Events Manager + +### Domain & Aggregated Events + +- [ ] Domain verified in Business Manager +- [ ] Aggregated Event Measurement configured +- [ ] Top 8 events prioritized in order of importance +- [ ] Web events prioritized for iOS 14+ tracking + +### Audience Setup + +- [ ] Custom audiences created: + - Website visitors (all, 30/60/90/180 days) + - Key page visitors + - Video viewers (25%, 50%, 75%, 95%) + - Page/Instagram engagers + - Customer list uploaded +- [ ] Lookalike audiences created (1%, 1-3%) +- [ ] Saved audiences for common targeting + +### Catalog (E-commerce) + +- [ ] Product catalog connected +- [ ] Product feed updating correctly +- [ ] Catalog sales campaigns enabled +- [ ] Dynamic product ads configured + +### Creative Assets + +- [ ] Images in correct sizes: + - Feed: 1080x1080 (1:1) + - Stories/Reels: 1080x1920 (9:16) + - Landscape: 1200x628 (1.91:1) +- [ ] Videos in correct formats +- [ ] Ad copy variations ready +- [ ] UTM parameters in all destination URLs + +### Compliance + +- [ ] Special Ad Categories declared (if housing, credit, employment, politics) +- [ ] Landing page complies with Meta policies +- [ ] No prohibited content in ads + +--- + +## LinkedIn Ads Setup + +### Campaign Manager Foundation + +- [ ] Campaign Manager account created +- [ ] Company Page connected +- [ ] Billing information added +- [ ] Team access configured + +### Insight Tag & Tracking + +- [ ] LinkedIn Insight Tag installed on all pages +- [ ] Tag verified and firing +- [ ] Conversion tracking configured: + - URL-based conversions + - Event-specific conversions +- [ ] Conversion values set (if applicable) + +### Audience Setup + +- [ ] Matched Audiences created: + - Website retargeting audiences + - Company list uploaded (for ABM) + - Contact list uploaded +- [ ] Lookalike audiences created +- [ ] Saved audiences for common targeting + +### Lead Gen Forms (if using) + +- [ ] Lead gen form templates created +- [ ] Form fields selected (minimize for conversion) +- [ ] Privacy policy URL added +- [ ] Thank you message configured +- [ ] CRM integration set up (or CSV export process) + +### Document Ads (if using) + +- [ ] Documents uploaded (PDF, PowerPoint) +- [ ] Gating configured (full gate or preview) +- [ ] Lead gen form connected + +### Creative Assets + +- [ ] Single image ads: 1200x627 (1.91:1) or 1080x1080 (1:1) +- [ ] Carousel images ready +- [ ] Video specs met (if using) +- [ ] Ad copy within character limits: + - Intro text: 600 max, 150 recommended + - Headline: 200 max, 70 recommended + +### Budget Considerations + +- [ ] Budget realistic for LinkedIn CPCs ($8-15+ typical) +- [ ] Audience size validated (50K+ recommended) +- [ ] Daily vs. lifetime budget decided +- [ ] Bid strategy selected + +--- + +## Twitter/X Ads Setup + +### Account Foundation + +- [ ] Ads account created +- [ ] Payment method added +- [ ] Account verified (if required) + +### Tracking + +- [ ] Twitter Pixel installed +- [ ] Conversion events created +- [ ] Website tag verified + +### Audience Setup + +- [ ] Tailored audiences created: + - Website visitors + - Customer lists +- [ ] Follower lookalikes identified +- [ ] Interest and keyword targets researched + +### Creative + +- [ ] Tweet copy within 280 characters +- [ ] Images: 1200x675 (1.91:1) or 1200x1200 (1:1) +- [ ] Video specs met (if using) +- [ ] Cards configured (website, app, etc.) + +--- + +## TikTok Ads Setup + +### Account Foundation + +- [ ] TikTok Ads Manager account created +- [ ] Business verification completed +- [ ] Payment method added + +### Pixel & Tracking + +- [ ] TikTok Pixel installed +- [ ] Events configured (ViewContent, Purchase, etc.) +- [ ] Events API set up (recommended) + +### Audience Setup + +- [ ] Custom audiences created +- [ ] Lookalike audiences created +- [ ] Interest categories identified + +### Creative + +- [ ] Vertical video (9:16) ready +- [ ] Native-feeling content (not too polished) +- [ ] First 3 seconds are compelling hooks +- [ ] Captions added (most watch without sound) +- [ ] Music/sounds selected (licensed if needed) + +--- + +## Universal Pre-Launch Checklist + +Before launching any campaign: + +- [ ] Conversion tracking tested with real conversion +- [ ] Landing page loads fast (<3 sec) +- [ ] Landing page mobile-friendly +- [ ] UTM parameters working +- [ ] Budget set correctly (daily vs. lifetime) +- [ ] Start/end dates correct +- [ ] Targeting matches intended audience +- [ ] Ad creative approved +- [ ] Team notified of launch +- [ ] Reporting dashboard ready diff --git a/skills/ai-seo/SKILL.md b/skills/ai-seo/SKILL.md index 2f60334..320a51c 100644 --- a/skills/ai-seo/SKILL.md +++ b/skills/ai-seo/SKILL.md @@ -2,7 +2,7 @@ name: ai-seo description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' or 'optimize for Claude/Gemini.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema." metadata: - version: 2.0.0 + version: 2.0.1 --- # AI SEO @@ -66,6 +66,45 @@ In traditional search, you need to rank on page 1. In AI search, a well-structur - Optimized content gets cited 3x more often than non-optimized - Statistics and citations boost visibility by 40%+ across queries +### Google's Official Stance vs. Multi-Platform Reality + +This is important to read once before doing anything else. + +**Google's position** ([AI features optimization guide](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)): +> "The best practices for SEO continue to be relevant because our generative AI features on Google Search are rooted in our core Search ranking and quality systems." + +Google explicitly says: +- **No special markup or files are required** for AI Overviews or AI Mode +- **Don't chunk content for AI** — write for people, organize with normal headings and paragraphs +- **Don't write separate content for AI** — that risks "scaled content abuse" spam policy +- **Helpful, reliable, people-first content** wins — same E-E-A-T standards as regular Search +- **No AI-specific Search Console reporting** — use standard SEO metrics + +**Other AI engines (ChatGPT, Claude, Perplexity, Copilot) behave differently:** +- They actively reward extractable structure — passages, FAQs, comparison tables, definition blocks +- They parse `llms.txt`, structured pricing pages, and machine-readable files when present +- They cite third-party sources (Reddit, Wikipedia, review sites) more heavily than top-ranked pages + +**What this means for the work:** +- The structural patterns in this skill (40–60 word answer blocks, FAQ schema, comparison tables) help **non-Google AI engines** materially. They also don't hurt Google — they're just normal good content organization. +- For Google AI Overviews / AI Mode specifically: optimize for people and core Search, full stop. Strong E-E-A-T, original information, semantic HTML, clean indexability. +- For ChatGPT/Claude/Perplexity: layer on the extractable structure + llms.txt + machine-readable files. + +When in doubt, default to "write for people, organize for clarity" — that satisfies both camps. + +### Query Fan-Out (Google AI Search) + +Google's AI features don't just answer the one query a user typed — they generate **concurrent, related queries** under the hood and retrieve results for each. + +Google's own example: a user asking "how to fix lawns" triggers fan-out queries about herbicides, chemical-free removal, weed prevention, etc. The AI synthesizes across all of them. + +**Implications:** +- Single-page-per-keyword targeting is less effective. Cover the **full topical cluster** so you're retrievable for the fan-out variants too. +- Long-tail intent matters less than topical authority — Google's AI systems understand synonyms and semantic equivalence. +- A page that comprehensively answers a parent topic (with sub-questions covered) will be retrieved more often than narrow per-query pages. + +**Action**: when planning content, brainstorm the 5–10 related queries the AI is likely to fan out to and make sure your content (or your site as a whole) covers them. + --- ## AI Visibility Audit @@ -228,6 +267,10 @@ AI systems don't just cite your website — they cite where you appear. ### Machine-Readable Files for AI Agents +> **Google's stance**: not required for AI Overviews or AI Mode. Their guide explicitly says you don't need new markup, AI files, or markdown to appear in generative AI search. +> +> **Why include them anyway**: non-Google AI engines (ChatGPT, Claude, Perplexity) and autonomous buying agents do reward extractable structure. The files below help with those engines without harming Google. + AI agents aren't just answering questions — they're becoming buyers. When an AI agent evaluates tools on behalf of a user, it needs structured, parseable information. If your pricing is locked in a JavaScript-rendered page or a "contact sales" wall, agents will skip you and recommend competitors whose information they can actually read. Add these machine-readable files to your site root: @@ -284,7 +327,32 @@ Structured data helps AI systems understand your content. Key schemas: | Reviews | `Review`, `AggregateRating` | Trust signals | | Organization | `Organization` | Entity recognition | -Content with proper schema shows 30-40% higher AI visibility. For implementation, use the **schema** skill. +Content with proper schema shows 30-40% higher AI visibility on non-Google AI engines. **Google's note**: structured data is "not required for generative AI search" but is recommended for overall SEO strategy. For implementation, use the **schema** skill. + +--- + +## Agentic Experiences + +Beyond AI search engines summarizing content, autonomous agents are starting to access sites directly — clicking, reading, comparing, even buying on behalf of users. Google's guide flags this as an emerging category to plan for. + +**How agents access your site:** +- **Visual rendering** — they screenshot/read the page like a user would +- **DOM inspection** — they parse the page's HTML structure +- **Accessibility tree** — they rely on the same semantic information assistive tech uses (labels, roles, landmarks, headings) + +**What to do:** +- **Render meaningful content without heavy JS gymnastics** — if the page is blank until 4 frameworks finish loading, agents see blank +- **Semantic HTML** — use `<main>`, `<nav>`, `<article>`, `<button>`, proper heading hierarchy, `alt` text on images +- **Clean accessibility tree** — every interactive element labelled; ARIA used correctly (or not at all when native HTML suffices) +- **Stable selectors / predictable layouts** — agents struggle with sites that re-render every interaction +- **Visible pricing, specs, contact info** — anything an agent would need to make a buying recommendation should be on a public, indexable page (this is where `/pricing.md` and similar files help) + +**Emerging — Universal Commerce Protocol (UCP):** +Google references UCP as a forthcoming protocol that will give agents standardized hooks for commerce interactions (catalog discovery, pricing, checkout). Watch for adoption; for now, the structural recommendations above are the precursor. + +For ecom and local business specifically, Google highlights: +- **Merchant Center feeds** + **Google Business Profile** for product/service visibility in AI Search +- **Business Agent** for conversational customer engagement (where applicable) --- @@ -340,55 +408,29 @@ Monthly manual check: 3. Record: Are you cited? Who is? What page? 4. Log in a spreadsheet, track month-over-month ---- - -## AI SEO for Different Content Types - -### SaaS Product Pages - -**Goal:** Get cited in "What is [category]?" and "Best [category]" queries. - -**Optimize:** -- Clear product description in first paragraph (what it does, who it's for) -- Feature comparison tables (you vs. category, not just competitors) -- Specific metrics ("processes 10,000 transactions/sec" not "blazing fast") -- Customer count or social proof with numbers -- Pricing transparency (AI cites pages with visible pricing) — add a `/pricing.md` file so AI agents can parse your plans without rendering your page (see "Machine-Readable Files" above) -- FAQ section addressing common buyer questions +### Search Console expectations -### Blog Content +Google's guide is explicit: **there is no AI-specific Search Console reporting**. AI Overviews and AI Mode use core Search ranking, so the standard Search Console reports (Performance, Coverage, Core Web Vitals) are still what you measure with for Google. The third-party tools above are the only way to see cross-platform AI citation behavior. -**Goal:** Get cited as an authoritative source on topics in your space. - -**Optimize:** -- One clear target query per post (match heading to query) -- Definition in first paragraph for "What is" queries -- Original data, research, or expert quotes -- "Last updated" date visible -- Author bio with relevant credentials -- Internal links to related product/feature pages +--- -### Comparison/Alternative Pages +## What NOT to Do -**Goal:** Get cited in "[X] vs [Y]" and "Best [X] alternatives" queries. +Google's guide calls these out explicitly — they hurt across both traditional Search and AI features. -**Optimize:** -- Structured comparison tables (not just prose) -- Fair and balanced (AI penalizes obviously biased comparisons) -- Specific criteria with ratings or scores -- Updated pricing and feature data -- Cite the competitors skill for building these pages +1. **Write separate content "for AI"**. Same content should serve people and AI. Writing variants targeted at AI systems risks the **scaled content abuse spam policy** — Google's words. +2. **Chunk pages into AI-bait fragments**. Google's guide is direct: *"Don't break your content into tiny pieces for AI to better understand it."* Use normal paragraph + heading structure. +3. **Generate at scale for ranking manipulation**. AI-generated content is fine *if* it meets Search Essentials and spam policies. Mass-producing thin variations does not. +4. **Pursue inauthentic mentions**. Don't fabricate citations or bulk-spam Reddit/Wikipedia for AI visibility. Real participation only. +5. **Block AI crawlers if you want citation**. Blocking GPTBot, PerplexityBot, ClaudeBot, Google-Extended means those engines literally cannot cite you. Block training-only crawlers (CCBot) if you must, not the search-and-cite ones. +6. **Hide your main content behind JS that doesn't render**. Both core Search and AI agents need to see your content; JS-only rendering loses both audiences. +7. **Skip E-E-A-T fundamentals**. Author identity, first-hand experience, expertise signals, transparent sourcing — Google's guide leans heavily on these for AI features. -### Documentation / Help Content +--- -**Goal:** Get cited in "How to [X] with [your product]" queries. +## AI SEO by Content Type -**Optimize:** -- Step-by-step format with numbered lists -- Code examples where relevant -- HowTo schema markup -- Screenshots with descriptive alt text -- Clear prerequisites and expected outcomes +For tactical guidance on SaaS product pages, blog content, comparison/alternative pages, documentation, and local/ecom (Google's emphasis on Merchant Center + Business Profile), see [references/content-types.md](references/content-types.md). --- diff --git a/skills/ai-seo/evals/evals.json b/skills/ai-seo/evals/evals.json index 327ade3..57ab7c1 100644 --- a/skills/ai-seo/evals/evals.json +++ b/skills/ai-seo/evals/evals.json @@ -4,9 +4,9 @@ { "id": 1, "prompt": "How do I make sure our SaaS product shows up in AI search results? We're a project management tool and we keep getting left out of ChatGPT and Perplexity recommendations when people ask about project management software.", - "expected_output": "Should check for product-marketing-context.md first. Should apply the three pillars framework: Structure (make content extractable), Authority (make content citable), Presence (be where AI looks). Should run through the AI Visibility Audit checklist across platforms (Google AI Overviews, ChatGPT, Perplexity, etc.). Should check content extractability (clear definitions, structured comparisons, statistics). Should reference Princeton GEO research findings (citations improve visibility +40%, statistics +37%). Should check AI bot access in robots.txt. Should provide a prioritized action plan.", + "expected_output": "Should check for product-marketing.md first. Should apply the three pillars framework: Structure (make content extractable), Authority (make content citable), Presence (be where AI looks). Should run through the AI Visibility Audit checklist across platforms (Google AI Overviews, ChatGPT, Perplexity, etc.). Should check content extractability (clear definitions, structured comparisons, statistics). Should reference Princeton GEO research findings (citations improve visibility +40%, statistics +37%). Should check AI bot access in robots.txt. Should provide a prioritized action plan.", "assertions": [ - "Checks for product-marketing-context.md", + "Checks for product-marketing.md", "Applies three pillars framework (Structure, Authority, Presence)", "Runs AI Visibility Audit across platforms", "Checks content extractability", diff --git a/skills/ai-seo/references/content-types.md b/skills/ai-seo/references/content-types.md new file mode 100644 index 0000000..12c0f99 --- /dev/null +++ b/skills/ai-seo/references/content-types.md @@ -0,0 +1,71 @@ +# AI SEO by Content Type + +Tactical guidance for optimizing specific content types for AI search citation. These tactics work for non-Google AI engines (ChatGPT, Claude, Perplexity, Copilot) and don't hurt Google AI Overviews / AI Mode. + +For the cross-cutting strategy, see [SKILL.md](../SKILL.md). + +--- + +## SaaS Product Pages + +**Goal:** Get cited in "What is [category]?" and "Best [category]" queries. + +**Optimize:** +- Clear product description in first paragraph (what it does, who it's for) +- Feature comparison tables (you vs. category, not just competitors) +- Specific metrics ("processes 10,000 transactions/sec" not "blazing fast") +- Customer count or social proof with numbers +- Pricing transparency (AI cites pages with visible pricing) — add a `/pricing.md` file so AI agents can parse your plans without rendering your page (see "Machine-Readable Files" in the main skill) +- FAQ section addressing common buyer questions + +--- + +## Blog Content + +**Goal:** Get cited as an authoritative source on topics in your space. + +**Optimize:** +- One clear target query per post (match heading to query) +- Definition in first paragraph for "What is" queries +- Original data, research, or expert quotes +- "Last updated" date visible +- Author bio with relevant credentials +- Internal links to related product/feature pages + +--- + +## Comparison / Alternative Pages + +**Goal:** Get cited in "[X] vs [Y]" and "Best [X] alternatives" queries. + +**Optimize:** +- Structured comparison tables (not just prose) +- Fair and balanced (AI penalizes obviously biased comparisons) +- Specific criteria with ratings or scores +- Updated pricing and feature data +- Cite the `competitors` skill for building these pages + +--- + +## Documentation / Help Content + +**Goal:** Get cited in "How to [X] with [your product]" queries. + +**Optimize:** +- Step-by-step format with numbered lists +- Code examples where relevant +- HowTo schema markup +- Screenshots with descriptive alt text +- Clear prerequisites and expected outcomes + +--- + +## Local Business / Ecom (Google emphasis) + +Google's AI features pull from product feeds and business profiles for local + ecom queries. Optimize: + +- **Merchant Center feeds** kept current with accurate inventory, pricing, attributes +- **Google Business Profile** complete with hours, services, photos, posts, Q&A answered +- **Reviews** — recent + sufficient volume; respond to reviews to signal active management +- **Service area schema** for local services +- **Business Agent** (where available) for conversational customer engagement diff --git a/skills/image/SKILL.md b/skills/image/SKILL.md index 99cadeb..4ec0142 100644 --- a/skills/image/SKILL.md +++ b/skills/image/SKILL.md @@ -1,8 +1,8 @@ --- name: image -description: "When the user wants to create, generate, edit, or optimize images for marketing — blog heroes, social graphics, product mockups, profile banners, listing visuals, or brand assets. Also use when the user mentions 'AI image generation,' 'generate an image,' 'create a graphic,' 'product mockup,' 'hero image,' 'social media graphic,' 'banner image,' 'cover photo,' 'profile banner,' 'listing screenshot,' 'Flux,' 'Midjourney,' 'DALL-E,' 'GPT Image,' 'Ideogram,' 'Gemini image,' 'Canva,' 'Figma,' 'image optimization,' 'compress images,' 'WebP,' or 'OG image.' Use this for general-purpose marketing image creation and optimization. For paid ad image creative and platform-specific ad specs, see ad-creative. For video production, see video." +description: "When the user wants to create, generate, edit, or optimize images for marketing — blog heroes, social graphics, product mockups, profile banners, listing visuals, or brand assets. Also use when the user mentions 'AI image generation,' 'generate an image,' 'create a graphic,' 'product mockup,' 'hero image,' 'social media graphic,' 'banner image,' 'cover photo,' 'profile banner,' 'listing screenshot,' 'Flux,' 'Flux Kontext,' 'Midjourney,' 'DALL-E,' 'GPT Image,' 'ChatGPT Images,' 'Ideogram,' 'Gemini image,' 'Nano Banana,' 'Recraft,' 'Stable Diffusion,' 'Canva,' 'Figma,' 'image optimization,' 'compress images,' 'WebP,' or 'OG image.' Use this for general-purpose marketing image creation and optimization. For paid ad image creative and platform-specific ad specs, see ad-creative. For video production, see video." metadata: - version: 2.0.0 + version: 2.0.1 --- # Image @@ -55,36 +55,41 @@ Generate original images from text prompts. The fastest way to create unique mar | Model | Best For | Text in Images | API | Cost | |-------|----------|:-:|-----|------| -| **Gemini Image** (Google) | All-around, editing, text rendering | Good | [Gemini API](https://ai.google.dev/gemini-api/docs/image-generation) | Check [pricing](https://ai.google.dev/gemini-api/docs/pricing) | -| **Flux** (Black Forest Labs) | Photorealism, brand consistency, batch | Limited | [BFL API](https://docs.bfl.ai/), Replicate, fal.ai | Check [pricing](https://docs.bfl.ai/quick_start/pricing) | -| **Ideogram** | Typography, branded graphics | Best | [Ideogram API](https://developer.ideogram.ai/) | Check [pricing](https://about.ideogram.ai/api-pricing) | -| **GPT Image** (OpenAI) | General purpose, ChatGPT integration | Good | [OpenAI API](https://platform.openai.com/docs/guides/image-generation) | Check [pricing](https://platform.openai.com/docs/pricing) | -| **Midjourney** | Artistic, high-aesthetic | Poor | No official API | Subscription-based | -| **Stable Diffusion** | Self-hosted, customizable | Varies | Open source | Free (GPU costs) | +| **Gemini Image** (Google, "Nano Banana" / Nano Banana Pro) | All-around, editing, multi-image reference, text rendering | Good | [Gemini API](https://ai.google.dev/gemini-api/docs/image-generation) | Check [pricing](https://ai.google.dev/gemini-api/docs/pricing) | +| **Flux** (Black Forest Labs — Pro 1.1, Kontext, Dev, Schnell) | Photorealism, brand consistency, batch; Kontext for in-image editing | Limited | [BFL API](https://docs.bfl.ai/), Replicate, fal.ai | Check [pricing](https://docs.bfl.ai/quick_start/pricing) | +| **Ideogram 3.0** | Typography, branded graphics, accurate text rendering | Best | [Ideogram API](https://developer.ideogram.ai/) | Check [pricing](https://about.ideogram.ai/api-pricing) | +| **ChatGPT Images 2.0 / GPT Image** (OpenAI) | General purpose, ChatGPT integration, native editing | Good | [OpenAI API](https://platform.openai.com/docs/guides/image-generation) | Check [pricing](https://platform.openai.com/docs/pricing) | +| **Midjourney v7** | Artistic, high-aesthetic, art-directed visuals | Improved | No official API; Discord + Web | Subscription-based | +| **Recraft V3** | Vector + brand-consistent illustrations, design assets | Strong | [Recraft API](https://www.recraft.ai/docs) | Per-credit | +| **Stable Diffusion 3.5 / SDXL** | Self-hosted, customizable, fine-tunable | Varies | Open source | Free (GPU costs) | -**Note:** DALL-E 3 is deprecated. OpenAI's current image models are the GPT Image family (`gpt-image-1`, etc.). +**Note:** DALL-E 3 is fully deprecated. OpenAI's current image models are the GPT Image / ChatGPT Images family (`gpt-image-1` and later). ### When to Use Which ``` Need text/headlines in the image? -├── Yes → Ideogram (best), Gemini (good), GPT Image (decent) +├── Yes → Ideogram 3.0 (best), Gemini (good), GPT Image / ChatGPT Images (decent) └── No ↓ -Need product/brand consistency across images? -├── Yes → Flux (multi-image reference) +Need product/brand consistency across many images? +├── Yes → Flux (multi-image reference), Gemini Nano Banana Pro, Recraft V3 └── No ↓ -Need to edit an existing image? -├── Yes → Gemini (native editing), Flux Flex +Need to edit an existing image (in-place)? +├── Yes → Gemini (native editing), Flux Kontext, ChatGPT Images └── No ↓ -Need highest visual quality? -├── Yes → Flux Pro, Midjourney +Need vector / illustrative brand assets? +├── Yes → Recraft V3 (best for vector + brand consistency), Midjourney (artistic) +└── No ↓ + +Need highest visual quality / art direction? +├── Yes → Flux Pro 1.1, Midjourney v7 └── No ↓ Need volume at low cost? -└── Flux Klein, Gemini Flash +└── Flux Schnell, Gemini Flash, Stable Diffusion (self-hosted) ``` ### Prompting Basics diff --git a/skills/image/evals/evals.json b/skills/image/evals/evals.json new file mode 100644 index 0000000..b3922b2 --- /dev/null +++ b/skills/image/evals/evals.json @@ -0,0 +1,89 @@ +{ + "skill_name": "image", + "evals": [ + { + "id": 1, + "prompt": "I need a hero image for a blog post about email deliverability. Make it visually striking.", + "expected_output": "Should check for product-marketing.md first. Should recommend AI generation as the approach for a one-off blog hero. Should propose a visual metaphor concept that represents email deliverability (e.g., letters being sorted through a maze, signals breaking through a wall, an inbox glow). Should specify 1200x630 (works for both hero and OG image). Should recommend Flux or Gemini for photorealistic, or Ideogram if text in image is needed. Should provide a prompt following Subject + Setting + Style + Lighting + Composition + Technical pattern. Should mention WebP optimization (target <200KB, JPEG fallback). Should not suggest using AI for product UI screenshots.", + "assertions": [ + "Checks for product-marketing.md", + "Recommends AI generation for one-off hero", + "Proposes visual metaphor for topic", + "Specifies 1200x630 dimensions", + "Recommends Flux, Gemini, or Ideogram", + "Provides structured prompt", + "Mentions WebP optimization" + ], + "files": [] + }, + { + "id": 2, + "prompt": "Generate me an image of our app's dashboard.", + "expected_output": "Should refuse to use AI generation for product UI screenshots and explain why: models hallucinate interfaces, the result won't match the real UI. Should recommend the Product Mockups & Screenshots workflow: capture real screenshots of the product at 2x resolution, frame in device mockups (browser frame, laptop, phone), add callout arrows or feature labels for context, programmatically overlay annotations with Hyperframes or HTML/CSS. Should suggest tools: browser DevTools screenshot, Shottr, CleanShot X, or screencapture CLI. Should warn this is Common Mistake #1: using AI for product UI.", + "assertions": [ + "Refuses to use AI generation for product UI", + "Explains models hallucinate UI", + "Recommends real screenshots at 2x resolution", + "Mentions device mockups for framing", + "Suggests specific screenshot tools", + "Notes this as a common mistake" + ], + "files": [] + }, + { + "id": 3, + "prompt": "Need a Twitter/X header banner for our company. We just want to show our product and tagline.", + "expected_output": "Should specify Twitter/X header dimensions: 1500x500 (3:1 aspect ratio). Should warn the banner is partially obscured by the avatar — center critical content and avoid important elements near the avatar overlap area. Should recommend keeping text minimal (seen at small sizes on mobile). Should suggest design tools (Canva or Figma) over AI generation since brand consistency matters. Should recommend Ideogram if heavy text rendering is needed since other AI models butcher text. Should suggest using brand colors + tagline + optional product shot. Should remind to test at actual display size by zooming out.", + "assertions": [ + "Specifies 1500x500 dimensions", + "Warns about avatar overlap area", + "Recommends minimal text", + "Suggests Canva or Figma over AI", + "Mentions Ideogram for text-heavy designs", + "Recommends testing at display size" + ], + "files": [] + }, + { + "id": 4, + "prompt": "I need 5 versions of the same hero image for Twitter, LinkedIn, Instagram feed, Instagram stories, and Facebook. What's the fastest way?", + "expected_output": "Should recommend the Canva Magic Resize workflow over generating 5 separate images. Should list dimensions: Twitter/X 1200x675 (16:9), LinkedIn 1200x627 (1.91:1), Instagram feed 1080x1080 (1:1 — note 1080x1350 / 4:5 also strong), Instagram Stories 1080x1920 (9:16), Facebook 1200x630 (1.91:1). Should explain workflow: create the hero concept at highest resolution needed, use Canva Magic Resize for variants, manually crop if needed, add text overlays programmatically if required (Ideogram or post-processing), export at each platform's specs. Should note this is what Canva Magic Resize is specifically designed for.", + "assertions": [ + "Recommends Canva Magic Resize", + "Lists dimensions for all 5 platforms", + "Notes Instagram 4:5 variant", + "Suggests programmatic text overlays for variants", + "Says start at highest resolution" + ], + "files": [] + }, + { + "id": 5, + "prompt": "What's the best image format for our website?", + "expected_output": "Should recommend WebP as the default choice with JPEG/PNG fallback. Should explain the format guide: WebP for photos and graphics (lossy + lossless, ~96% browser support), AVIF for highest compression (~94% support, newer), JPEG as universal fallback (lossy only), PNG for transparency and screenshots (lossless, universal), SVG for logos and icons (vector, scales, universal). Should reference the optimization checklist: resize to display size, compress (target quality 75-85% for photos), lazy load below-the-fold, set explicit width/height attributes (prevents CLS), use a CDN with auto-optimization (Cloudflare, Vercel, Imgix, Cloudinary), add descriptive alt text. Should provide a quick cwebp or mogrify command. Should note skipping image optimization is the #1 page speed killer.", + "assertions": [ + "Recommends WebP as default", + "Mentions JPEG/PNG fallback strategy", + "Lists optimization checklist items", + "Mentions lazy loading", + "Mentions explicit dimensions to prevent CLS", + "Provides command line tool example" + ], + "files": [] + }, + { + "id": 6, + "prompt": "We're a SaaS that just launched. Need OG images for every blog post we ship — about 2 per week. Doing it manually is killing us.", + "expected_output": "Should recommend Dynamic OG Images programmatic approach. Should explain options: Vercel OG (@vercel/og) generates images at the edge using JSX — best for programmatic SEO since you can dynamically pull post title, author, image into a template; Satori converts HTML/CSS to SVG (powers Vercel OG); Cloudinary for URL-based text overlay on template images. Should explain you build the template once with your branding then it generates unique OG images per page using post metadata. Should mention required meta tags: og:image (1200x630), og:image:width, og:image:height, twitter:card summary_large_image, twitter:image. Should note this is best for programmatic SEO.", + "assertions": [ + "Recommends programmatic OG image generation", + "Names Vercel OG, Satori, or Cloudinary", + "Mentions template + dynamic data approach", + "Lists required og:image meta tags", + "Specifies 1200x630 dimensions", + "Notes this is best for high-volume blogs" + ], + "files": [] + } + ] +} diff --git a/skills/image/references/ai-image-prompting.md b/skills/image/references/ai-image-prompting.md new file mode 100644 index 0000000..3f6fa39 --- /dev/null +++ b/skills/image/references/ai-image-prompting.md @@ -0,0 +1,229 @@ +# AI Image Prompting Guide + +How to write effective prompts for AI image generation models (Gemini/Nano Banana, Flux, Ideogram, DALL-E, Midjourney). + +--- + +## Prompt Structure + +A strong image prompt follows this formula: + +``` +[Subject] + [Setting/context] + [Visual style] + [Lighting] + [Composition] + [Technical specs] +``` + +### Example Prompts by Use Case + +**Blog hero — SaaS product:** +``` +A clean workspace with a laptop displaying a colorful analytics dashboard, +minimalist desk with a coffee cup and notebook, +bright natural window lighting from the right, +shallow depth of field, commercial photography style, +1200x630, high resolution +``` + +**Social media graphic — announcement:** +``` +Abstract flowing gradient in deep purple and electric blue, +geometric shapes forming a network pattern, +dramatic rim lighting on edges, +modern tech aesthetic, clean and minimal, +1080x1080, vibrant colors +``` + +**Product lifestyle shot:** +``` +A person in a modern office smiling while looking at a tablet, +showing a project management interface on screen, +warm candid photography, natural lighting, +medium shot, shallow depth of field, editorial style +``` + +**Profile banner — professional:** +``` +Wide panoramic abstract background in navy blue and teal, +subtle geometric grid pattern with soft gradient, +clean corporate aesthetic, muted lighting, +1584x396, no text, space for logo overlay on left third +``` + +**Directory listing — Product Hunt:** +``` +Product screenshot on a clean gradient background, +soft shadow underneath, slight 3D perspective tilt, +modern SaaS product presentation style, +1270x760, bright and professional +``` + +--- + +## Style Keywords + +### Photorealistic +- "commercial photography" +- "shot on Canon EOS R5" +- "editorial style" +- "natural lighting" +- "shallow depth of field" + +### Clean/Corporate +- "clean modern aesthetic" +- "minimal design" +- "professional corporate style" +- "bright and airy" +- "white background" + +### Illustrative +- "flat vector illustration" +- "isometric 3D render" +- "hand-drawn sketch style" +- "watercolor illustration" +- "line art" + +### Abstract/Brand +- "flowing gradient" +- "geometric pattern" +- "abstract data visualization" +- "particle effects" +- "holographic iridescent" + +### Tech/SaaS +- "dark mode UI aesthetic" +- "neon accent lighting" +- "glassmorphism" +- "futuristic minimal" +- "developer-focused" + +--- + +## Lighting Keywords + +| Term | Effect | Best For | +|------|--------|----------| +| **Natural light** | Warm, organic feel | Lifestyle, editorial | +| **Studio lighting** | Even, controlled | Product shots | +| **Rim lighting** | Edge highlights, dramatic | Hero images, abstract | +| **Soft directional** | Gentle shadows, dimensional | Blog headers | +| **Volumetric** | Light rays, atmospheric | Dramatic, cinematic | +| **Flat/even** | No shadows, clean | Icons, diagrams | +| **Golden hour** | Warm orange tones | Lifestyle, outdoor | +| **High key** | Bright, minimal shadows | Clean, corporate | + +--- + +## Composition Keywords + +| Term | Effect | Best For | +|------|--------|----------| +| **Rule of thirds** | Subject off-center | Editorial, lifestyle | +| **Centered** | Subject in middle | Product shots, icons | +| **Wide/panoramic** | Expansive view | Banners, headers | +| **Close-up/macro** | Detail focus | Texture, product detail | +| **Bird's eye/overhead** | Top-down view | Desk setups, flat lays | +| **Negative space** | Room for text overlay | Blog headers, banners | +| **Symmetrical** | Balanced, formal | Corporate, luxury | + +--- + +## Model-Specific Tips + +### Gemini Image (Google) + +- Best all-around for marketing images — good quality, reasonable cost +- Supports **image editing** — upload an existing image and describe changes +- Decent text rendering — can handle short headlines +- Specify "high resolution" for best output +- Works well with detailed, descriptive prompts +- Same API as text generation — easy to integrate + +### Flux (Black Forest Labs) + +- **Multi-image reference** is the killer feature — upload product screenshots, brand assets, or style references +- Best for **brand consistency** across a set of images +- Use Flux Pro for final assets, Flux Dev for rapid iteration +- Flux Klein for high-volume batch generation (cheapest) +- Style transfer via reference images > style keywords in prompt +- Prompts can be shorter than other models — the references do heavy lifting + +### Ideogram + +- **Best text rendering** of any model (industry-leading accuracy) +- Use when you need headlines, taglines, or brand names in the image +- Style reference system (up to 3 images) for brand consistency +- Supports "Magic Prompt" auto-enhancement +- Keep text requests simple — 3-5 words max for reliability +- Best for social graphics and banners that need text baked in + +### GPT Image (OpenAI) + +- Current models: `gpt-image-1` and variants (DALL-E 3 is deprecated) +- Integrated with ChatGPT — conversational image generation +- Good at following detailed prompts +- Decent text rendering (behind Ideogram, comparable to Gemini) +- Automatic prompt rewriting — may deviate from exact request +- Best for quick one-offs through ChatGPT interface +- API gives more control than ChatGPT interface + +### Midjourney + +- Highest aesthetic quality for artistic/editorial images +- No official API — Discord-based or web interface +- **Not agent-friendly** — use for manual creative exploration only +- Style flags: `--style raw` for less stylized, `--ar 16:9` for aspect ratio +- Best for hero images where pure visual quality matters most +- V6+ has improved text rendering but still unreliable + +--- + +## Common Prompt Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|-----| +| "A professional image" | No visual detail | Describe subject, setting, style, lighting | +| Long paragraph of text in image | Models can't render paragraphs | 3-5 words max; add text in post | +| "Make it look good" | Not actionable | Specify style: "commercial photography, bright" | +| 200+ word prompts | Models lose focus | 40-80 words, specific over comprehensive | +| No aspect ratio | Random output size | Always specify dimensions or ratio | +| "Logo in bottom right" | Unreliable placement | Add logos in post-processing | +| "Make it viral" | Not a visual instruction | Describe the aesthetic you want | +| Requesting UI screenshots | AI hallucinates interfaces | Capture real screenshots instead | + +--- + +## Batch Generation Workflow + +When you need multiple images with consistent style (e.g., a blog series or social campaign): + +1. **Generate 3-4 test images** with different style prompts +2. **Pick the winning style** based on brand fit +3. **Save the exact prompt** as your template +4. **Use Flux multi-reference** — upload the winning image as a style reference +5. **Batch generate** variations with the same style, different subjects +6. **Post-process** — add text overlays, logos, crop to platform sizes + +--- + +## Aspect Ratios Quick Reference + +| Use Case | Ratio | Pixels | Notes | +|----------|-------|--------|-------| +| Blog hero / OG image | 1.91:1 | 1200x630 | Universal web standard | +| Full-width hero | 16:9 | 1920x1080 | Website headers | +| Instagram Feed | 1:1 | 1080x1080 | Square | +| Instagram Feed (tall) | 4:5 | 1080x1350 | More screen real estate | +| Stories / Reels | 9:16 | 1080x1920 | Vertical full screen | +| LinkedIn cover | 4:1 | 1584x396 | Personal profile | +| Twitter/X header | 3:1 | 1500x500 | Profile banner | +| Product Hunt gallery | 5:3 | 1270x760 | Launch page | +| GitHub social preview | 2:1 | 1280x640 | Repo link card | + +--- + +## Cost Optimization + +- **Iterate at low quality first** — use Flux Dev or Gemini Flash for drafts, upgrade for finals +- **Use references over long prompts** — Flux multi-reference produces more consistent results with fewer retries +- **Batch similar requests** — generate all blog headers in one session with the same style +- **Cache and reuse** — abstract backgrounds, patterns, and textures can be reused across multiple images +- **Post-process instead of re-generate** — crop, overlay text, and adjust color in code rather than generating new images diff --git a/skills/prospecting/SKILL.md b/skills/prospecting/SKILL.md new file mode 100644 index 0000000..0ddbdb2 --- /dev/null +++ b/skills/prospecting/SKILL.md @@ -0,0 +1,256 @@ +--- +name: prospecting +description: When the user wants to find, qualify, and build a list of prospects to reach out to — across B2B SaaS, general B2B, or local small businesses. Also use when the user mentions "prospecting," "build a prospect list," "find prospects," "find leads," "lead gen list," "find SaaS companies that," "find B2B companies," "find local businesses," "ICP-fit accounts," "who should we go after," "outbound list," "target account list," "find clients near me," "businesses without websites," "prospect research," or "qualified leads." Use this for the list-building and qualification phase. For writing the outbound copy after the list is built, see cold-email. For deep competitive research on specific accounts, see competitor-profiling. +metadata: + version: 1.0.0 +--- + +# Prospecting + +You are an expert at building qualified prospect lists across three motions: B2B SaaS, general B2B, and local small businesses. Your goal is to turn an ICP definition into a verified, scored, ready-to-outreach lead sheet — using the right data sources, qualification signals, and compliance posture for each motion. + +## Before Starting + +**Check for product marketing context first:** +If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. + +## Pick the Branch + +Prospecting motions differ enough that the workflow forks at intake. Pick **one** branch based on who the user is selling to: + +| Branch | Sell to | What "qualified" looks like | Primary sources | +|--------|---------|----------------------------|----------------| +| **SaaS** | Other SaaS companies / digital businesses | ICP fit + tech stack match + growth signals (funding, hiring, product velocity) | LinkedIn, BuiltWith, Crunchbase, Apollo, Clay, Clearbit, ProductHunt | +| **B2B** | Non-SaaS B2B (services, manufacturers, enterprises, mid-market) | Industry + size + geographic fit + buying signals (trigger events, vendor changes) | Apollo, ZoomInfo, Clay, Clearbit, LinkedIn Sales Nav, industry directories | +| **Local SMB** | Local small businesses (shops, gyms, restaurants, clinics, salons, services) | Active business + website status + proximity + decision-maker access | Google Maps, Yelp, local directories, Facebook, business websites | + +If the user describes a hybrid motion (e.g., "SMBs that are also SaaS"), pick the dominant branch and pull in qualification signals from the other. + +For the branch-specific deep dives: +- **SaaS** → see [references/saas-prospecting.md](references/saas-prospecting.md) +- **B2B** → see [references/b2b-prospecting.md](references/b2b-prospecting.md) +- **Local SMB** → see [references/local-prospecting.md](references/local-prospecting.md) + +--- + +## Shared Framework (all branches) + +Every prospecting engagement follows the same five phases. Tools and qualification signals change per branch; the phases don't. + +### Phase 1 — Define the ICP + +Pull from `product-marketing.md` if available. Otherwise, gather: + +1. **Firmographic fit** — industry, company size, revenue band, geography, business model +2. **Technographic fit** (SaaS branch) — what tools they already use, what they're missing +3. **Buying signal** — why now? (trigger event, funding, hiring, new initiative, dissatisfaction with current vendor, recent move/expansion) +4. **Decision-maker profile** — role, seniority, what they care about +5. **Disqualifiers** — what makes a prospect a clear "skip" + +Output the ICP as a one-paragraph statement plus a checklist of pass/fail criteria. Don't move to discovery without this. + +### Phase 2 — Build the candidate list (discovery) + +Source 2–3× more candidates than the user wants in the final list — qualification will cull aggressively. + +- **SaaS / B2B**: combine 2–3 sources for cross-verification. Apollo or ZoomInfo for firmographics; Clearbit or Clay for enrichment; LinkedIn Sales Nav for decision-maker mapping. +- **Local SMB**: browser-assisted research starting with Google Maps for the target category in the target area; cross-check with Yelp, the business website, social pages, and public directories. + +If the user's list quality bar is high, smaller is better. 25 verified leads beats 250 mostly-junk ones. + +### Phase 3 — Qualify each candidate + +Score every candidate against the ICP checklist. Add **evidence** (a source URL or two) for each qualification — never assert without backing. + +**Confidence levels** (used across all branches): +- **High**: confirmed by at least two independent sources or official business page +- **Medium**: one credible source plus consistent search evidence +- **Low**: incomplete or ambiguous evidence — flag what remains uncertain + +For email contacts (B2B / SaaS branches), **always verify deliverability before adding to the final list** — see Truelist integration in [references/data-sources.md](references/data-sources.md). Don't ship leads with invalid or risky emails. + +### Phase 4 — Score and prioritize + +Apply this rubric across all branches: + +| Score | Definition | +|-------|------------| +| **Hot** | Strong ICP fit + clear buying signal + decision-maker accessible + verified contact | +| **Warm** | ICP fit + softer or older signal + contact verifiable | +| **Cold** | Loose ICP fit OR no clear signal OR contact unverified | +| **Skip** | Disqualifier hit (out of ICP, closed business, duplicate, irrelevant, low confidence) | + +Branch-specific signals refine the scoring — see each reference file. Default ratio target: ~20% Hot, ~30% Warm, rest Cold/Skip. + +### Phase 5 — Output the lead sheet + +Default to a markdown table in chat. Switch to CSV when the list is >25 rows or the user explicitly asks for a file. + +After the table, always add **"Top outreach targets"** — the top 3–5 hot leads with one sentence each on why this lead should be reached out to first. + +Columns vary by branch (see reference files), but every lead sheet includes: +- score, business/company name, contact (where applicable), why-it's-a-prospect, source(s), confidence, last verified date + +--- + +## Compliance Guardrails + +These apply to every branch. **Read first, every engagement.** + +1. **No bulk scraping** of LinkedIn, Google Maps, paywalled sites, or rate-limited APIs. Browser is an assisted research tool, not a scraper. +2. **No CAPTCHA, login wall, or bot protection bypass.** If a site requires it, work with what's publicly visible. +3. **Public business contact channels only.** Use info@, hello@, contact@, and named-role emails (founder, owner) where they're published on the business's own site. Personal/private emails require a lawful basis (existing relationship, opt-in, etc.). +4. **GDPR / CAN-SPAM / CASL aware.** Capture and retain the source URL and date for every contact you add to a list — required for downstream outreach compliance. +5. **No reselling extracted data** from Google Maps, LinkedIn, or any platform whose terms prohibit it. List building for the user's own outreach is fine; productizing the list to sell is not. +6. **Rate limit yourself.** Even on public sources, space requests. Don't fingerprint as a bot. + +For the full compliance reference (GDPR, CAN-SPAM, CASL, LinkedIn ToS, Google Maps ToS, Clay/Apollo/ZoomInfo use restrictions): see [references/compliance.md](references/compliance.md). + +--- + +## Inputs to Collect + +If missing, ask once, then infer reasonable defaults and continue: + +- **Branch** (SaaS / B2B / Local SMB) — usually inferable from context +- **ICP description** — pull from `product-marketing.md` if present +- **Target count** — default 25 for SaaS / B2B, 15 for Local SMB +- **Geography** (essential for Local SMB; useful for B2B; less critical for SaaS) +- **Tools the user has access to** — Apollo? Clay? ZoomInfo? Hunter? Truelist? Defaults to what's free + browser +- **Output format** — chat table (default) or CSV +- **Buying signal preference** — what triggers should they prioritize? (funding rounds, hiring, recent move, etc.) + +--- + +## Tool Selection Quick Picks + +Full breakdown in [references/data-sources.md](references/data-sources.md). Quick picks: + +| If the user has access to... | Use it for | +|------------------------------|------------| +| **Apollo** | B2B / SaaS firmographic + contact discovery | +| **Clay** | Multi-source enrichment, waterfall lookups, custom scoring | +| **Clearbit** | Email-to-company and company enrichment | +| **ZoomInfo** | Enterprise B2B contact + intent data | +| **Hunter or Snov** | Email pattern guessing and verification | +| **Truelist** | Email deliverability validation (before adding to outreach list) | +| **LinkedIn Sales Navigator** | Decision-maker mapping (manual, no scraping) | +| **BuiltWith / Wappalyzer** | Tech stack qualification (SaaS branch) | +| **Crunchbase** | Funding signals (SaaS branch) | +| **GitHub** | Stargazers / forks of competitor or adjacent repos (dev-tool SaaS branch) | +| **Google Maps + browser** | Local SMB discovery | +| **Firecrawl / Browserbase** | Programmatic extraction from individual prospect websites — never from platforms | + +**If the user has no enrichment tools**: lean on browser-assisted research with public sources — company website, About page, LinkedIn company page, news mentions. Slower but works. + +--- + +## Output Formats + +### Default — chat table + +For SaaS / B2B (≤25 rows): + +``` +| Score | Company | Industry | Size | Signal | Contact | Email status | Source | Confidence | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +``` + +For Local SMB (≤15 rows) — port from the local-prospector reference: + +``` +| Score | Business | Category | Area | Website status | Website/Social | Phone | Why it's a prospect | Confidence | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +``` + +### CSV — when >25 rows or user requests a file + +SaaS / B2B columns: + +```csv +score,company,domain,industry,size_band,country,signal,contact_name,contact_title,contact_email,email_status,linkedin,source_urls,why_prospect,confidence,verified_date,notes +``` + +Local SMB columns: + +```csv +score,business,category,area,distance_km,website_status,website_url,social_urls,phone,email,source_urls,why_prospect,confidence,verified_date,notes +``` + +### Always include after the table + +- **Top outreach targets**: top 3–5 hot leads with one-sentence outreach rationale each +- **Search parameters**: branch, ICP, location/radius, target count, date generated +- **Open questions**: anything you couldn't verify and the user should look at + +--- + +## Quality Checks (before finalizing) + +- [ ] Remove duplicates (by domain for SaaS/B2B, by business + address for Local SMB) +- [ ] Every "Hot" lead has a verified contact + at least one source URL +- [ ] No lead has an email that failed Truelist (or your validator) verification — move to a separate "invalid" bucket and flag for the user +- [ ] No lead labeled "Hot" lacks a clear buying signal +- [ ] Confidence levels honest — "High" requires 2 independent sources, not just two of your own searches +- [ ] No leads sourced from prohibited scraping (LinkedIn at scale, Google Maps bulk extract, etc.) +- [ ] Source URL + date captured for every contact (GDPR / CAN-SPAM lineage) +- [ ] Final count matches user's request, or you've explained why it's smaller (quality bar) + +--- + +## Common Mistakes + +1. **Starting discovery without an ICP**. Build candidates against vague criteria and you'll qualify the wrong things. +2. **Treating data sources as authoritative without cross-checks**. Apollo and ZoomInfo are out of date often; verify before scoring as "Hot." +3. **Adding contacts without email verification**. Cold email reputation tanks fast with bounces — always validate. +4. **Bulk scraping LinkedIn or Google Maps**. Real risk: account suspension + ToS violation. Browser as an assisted tool only. +5. **Mixing branches**. Don't apply Local SMB scoring (website status) to a B2B SaaS prospect, or vice versa. +6. **"Hot" labels without buying signals**. ICP fit alone is not enough — the signal is what makes the timing right. +7. **No source URLs**. Every claim should be traceable to a public source. Future outreach depends on this lineage. +8. **Ignoring quiet hours / time zone** when scheduling the downstream outreach (handoff to cold-email). +9. **Forgetting to retain consent / lineage records**. Required for GDPR DSARs and CAN-SPAM audits. + +--- + +## Task-Specific Questions + +1. Which branch — SaaS, B2B, or Local SMB? +2. What's your ICP? (Or: should I pull from your product-marketing context?) +3. How many qualified leads do you want? +4. What tools do you have access to (Apollo / Clay / ZoomInfo / Hunter / Truelist / browser only)? +5. What's the triggering buying signal you care most about? +6. Geography or radius (Local SMB / B2B)? +7. Chat table or CSV? + +--- + +## Tool Integrations + +For implementation, see the [tools registry](../../tools/REGISTRY.md). Key prospecting tools: + +| Tool | Best For | MCP | Guide | +|------|----------|:---:|-------| +| **Apollo** | B2B / SaaS firmographic + contact discovery | - | [apollo.md](../../tools/integrations/apollo.md) | +| **Clay** | Multi-source enrichment + waterfall | ✓ | [clay.md](../../tools/integrations/clay.md) | +| **Clearbit** | Email-to-company enrichment | - | [clearbit.md](../../tools/integrations/clearbit.md) | +| **ZoomInfo** | Enterprise B2B contact + intent | ✓ | [zoominfo.md](../../tools/integrations/zoominfo.md) | +| **Hunter** | Email pattern + verification | - | [hunter.md](../../tools/integrations/hunter.md) | +| **Snov** | Email finder + verifier | - | [snov.md](../../tools/integrations/snov.md) | +| **Truelist** | Email deliverability validation | - | [truelist.md](../../tools/integrations/truelist.md) | +| **Outreach** | Sales engagement (post-list) | ✓ | [outreach.md](../../tools/integrations/outreach.md) | +| **RB2B** | Visitor identification (warm intent) | - | [rb2b.md](../../tools/integrations/rb2b.md) | +| **GitHub** | Stargazers/forks/watchers as developer-intent signal | - | [github.md](../../tools/integrations/github.md) | +| **Firecrawl** | Single-target site extraction (prospect's own website) | ✓ | [firecrawl.md](../../tools/integrations/firecrawl.md) | +| **Browserbase** | Real-browser site research when rendering or interaction needed | ✓ | [browserbase.md](../../tools/integrations/browserbase.md) | + +--- + +## Related Skills + +- **cold-email**: For writing outbound sequences against the qualified list (the natural next step after prospecting) +- **customer-research**: For understanding why current customers buy — informs the ICP definition +- **competitor-profiling**: For deeper research on individual accounts (different from list-building qualification) +- **revops**: For lead routing, lifecycle, and CRM handoff after prospecting +- **sales-enablement**: For battle cards and one-pagers used in the outreach +- **directory-submissions**: For inbound discovery surfaces (the prospects might find you back) +- **product-marketing**: For the ICP definition that anchors every prospecting engagement diff --git a/skills/prospecting/evals/evals.json b/skills/prospecting/evals/evals.json new file mode 100644 index 0000000..f47b97b --- /dev/null +++ b/skills/prospecting/evals/evals.json @@ -0,0 +1,107 @@ +{ + "skill_name": "prospecting", + "evals": [ + { + "id": 1, + "prompt": "We're a B2B SaaS selling RevOps tooling at $30K ACV. Build me a list of 25 prospects.", + "expected_output": "Should check for product-marketing.md first. Should identify this as the SaaS branch. Should run Phase 1 ICP definition pulling from product-marketing context or asking targeted questions (target industry, headcount range, tech stack signals, funding stage). Should propose discovery sources appropriate for SaaS at $30K ACV: Apollo for breadth, Clay for waterfall enrichment, Crunchbase for funding signals, BuiltWith/Wappalyzer for tech stack, LinkedIn Sales Nav for decision-mapping (manual). Should ask about user's tool access before assuming. Should source 50-75 candidates (2-3x target) before qualifying. Should flag that email validation via Truelist or similar is non-negotiable before final list. Should output SaaS-branch chat table columns (Score | Company | Industry | Size | Signal | Contact | Email status | Confidence) followed by top 3-5 hot leads with one-sentence rationale each. Should reference references/saas-prospecting.md.", + "assertions": [ + "Checks for product-marketing.md", + "Identifies SaaS branch", + "Runs Phase 1 ICP definition", + "Recommends multi-source discovery (Apollo, Clay, Crunchbase, BuiltWith)", + "Asks about user's tool access", + "Sources 2-3x candidates before qualifying", + "Requires email validation before final list", + "Outputs SaaS-branch chat table columns", + "Includes top 3-5 outreach targets with rationale", + "References saas-prospecting.md" + ], + "files": [] + }, + { + "id": 2, + "prompt": "Find me 25 SaaS companies that just raised a Series B in the last 60 days and use HubSpot.", + "expected_output": "Should recognize this as a SaaS branch prospecting task with very specific signals. Should identify the trigger event (Series B in last 60 days) and the technographic filter (uses HubSpot). Should recommend a workflow: (1) Crunchbase or Pitchbook for funding signal filter (Series B + date), (2) BuiltWith or Clay's waterfall for tech stack verification (uses HubSpot), (3) cross-check via business websites and LinkedIn. Should note this is a tight ICP that should yield high-confidence matches if data sources are current. Should flag freshness concerns: Crunchbase data depends on self-reporting, BuiltWith refresh cycles aren't real-time. Should recommend cross-source verification for the funding date specifically. Should output a SaaS-branch chat table with the funding round + date in the Signal column. Should include verified email validation before delivering.", + "assertions": [ + "Identifies as SaaS branch", + "Identifies funding signal + tech stack filter", + "Recommends Crunchbase or Pitchbook for funding", + "Recommends BuiltWith or Clay for HubSpot verification", + "Notes data freshness concerns", + "Recommends cross-source verification", + "Outputs signal column showing round + date", + "Requires email validation" + ], + "files": [] + }, + { + "id": 3, + "prompt": "I run a marketing agency. Find me 25 mid-market manufacturers in the Midwest US who recently hired a new CMO.", + "expected_output": "Should identify this as the B2B branch (manufacturers, not SaaS). Should run Phase 1 ICP definition: industry (manufacturing, with NAICS code if precision matters), size (mid-market = typically 200-2000 employees), geography (Midwest US states), trigger event (CMO hire in last 90-180 days). Should propose discovery: Apollo or ZoomInfo for firmographic filter, LinkedIn Sales Nav for CMO hire detection (job changes), Google Alerts on press releases for trigger events. Should warn that CMO hires aren't always in public databases — LinkedIn Sales Nav alerts on job changes is the most reliable source. Should output B2B-branch chat table with the CMO trigger as the signal. Should reference references/b2b-prospecting.md. Should mention compliance: GDPR less likely (US-only), CAN-SPAM applies, capture source URL + date for every contact.", + "assertions": [ + "Identifies B2B branch (not SaaS)", + "Runs Phase 1 ICP definition with NAICS or industry classification", + "Specifies mid-market size band", + "Specifies Midwest US geography", + "Identifies trigger event (CMO hire)", + "Recommends Apollo/ZoomInfo + LinkedIn Sales Nav", + "Notes CMO hires often only on LinkedIn", + "Outputs B2B-branch chat table", + "Mentions CAN-SPAM and source URL capture", + "References b2b-prospecting.md" + ], + "files": [] + }, + { + "id": 4, + "prompt": "We sell to industrial distributors. Build a list of 25 prospects.", + "expected_output": "Should identify this as the B2B branch. Should run Phase 1 ICP definition asking targeted questions: distributor size, geography, vertical specialty, buying patterns. Should propose discovery: Apollo or ZoomInfo for firmographic depth, industry-specific directories (e.g., NAW for wholesale distributors, ISA for industrial sales agencies), trade show exhibitor lists. Should note state business registries and Chamber of Commerce as verification sources. Should propose trigger events: new location, recent acquisition, leadership change, posting RFPs. Should warn that industrial distributor data is often spotty in major databases — cross-check with company website + LinkedIn for size and ownership signals. Should output B2B-branch chat table. Should note ICP fit precision matters more than initial volume for this kind of niche prospecting.", + "assertions": [ + "Identifies B2B branch", + "Runs Phase 1 ICP definition asking targeted questions", + "Recommends industry-specific directories beyond Apollo/ZoomInfo", + "Mentions trade show exhibitor lists", + "Identifies relevant trigger events", + "Warns about data spottiness for industrial", + "Recommends cross-verification with business websites + LinkedIn", + "Notes ICP fit precision over volume" + ], + "files": [] + }, + { + "id": 5, + "prompt": "I build websites for local businesses. Find me 15 prospects near Austin, TX who don't have a website.", + "expected_output": "Should identify as Local SMB branch. Should run Phase 1 ICP definition: business category (ask user — gyms, restaurants, salons, etc. matter), radius (default 20 km from Austin), target count (15). Should run the browser research workflow: search Google Maps for category + Austin, build candidate list from visible results, cross-check via business name + city web search to verify website status. Should apply the 4-tier website status classification (No site found / Social only / Weak site / Has site) — prioritize No site + Social only as Hot. Should score: Hot (no site + active + phone + within radius), Warm (weak site), Cold (has site), Skip (closed/duplicate/out of scope). Should output Local SMB chat table (Score | Business | Category | Area | Distance | Website status | Website/Social | Phone | Why prospect | Confidence). Should add 'Best first outreach targets' top 3 with reasoning. Should reference references/local-prospecting.md. Should warn against bulk-scraping Google Maps (ToS violation) — browser-assisted research only.", + "assertions": [ + "Identifies Local SMB branch", + "Asks about business category if not specified", + "Defaults radius to 20km", + "Runs browser research workflow", + "Applies 4-tier website status classification", + "Uses Hot/Warm/Cold/Skip scoring", + "Outputs Local SMB chat table columns", + "Adds top 3 outreach targets", + "References local-prospecting.md", + "Warns against bulk-scraping Google Maps" + ], + "files": [] + }, + { + "id": 6, + "prompt": "I have a list of 200 prospect emails from Apollo. How do I know which ones are deliverable before I start outreach?", + "expected_output": "Should explain the deliverability validation step in Phase 3. Should recommend Truelist (the integration in this pack) for bulk validation. Should explain the email_state classification output: ok (deliverable), email_invalid (bounces, exclude), risky (deliverable with risk like role or disposable, include cautiously), unknown (couldn't determine, skip or re-verify), accept_all (catch-all domain, include cautiously). Should warn that Apollo data accuracy is typically 60-80% — sending without validation will tank sender reputation (bounce rate >2% triggers ISP throttling and reputation damage). Should recommend the workflow: bulk POST to /api/v1/verify or CSV upload → keep ok, include risky/accept_all cautiously, exclude email_invalid, re-verify unknown → hand off to outreach. Should note Truelist also has an official MCP server for agent-driven validation. Should note cold email reputation is hard to recover once damaged — validation is non-negotiable, not optional. Should mention Hunter and Snov as alternatives with built-in verification. Should reference truelist.md integration guide.", + "assertions": [ + "Recommends Truelist for bulk validation", + "Explains email_state values (ok, email_invalid, risky, unknown, accept_all)", + "Warns Apollo accuracy is 60-80%", + "Cites 2% bounce rate threshold for reputation damage", + "Recommends workflow: validate, keep ok, exclude email_invalid", + "Mentions Truelist MCP server for agent workflows", + "Mentions cold email reputation is hard to recover", + "References truelist.md or data-sources.md" + ], + "files": [] + } + ] +} diff --git a/skills/prospecting/references/b2b-prospecting.md b/skills/prospecting/references/b2b-prospecting.md new file mode 100644 index 0000000..6fdfd71 --- /dev/null +++ b/skills/prospecting/references/b2b-prospecting.md @@ -0,0 +1,106 @@ +# B2B Prospecting Reference + +For when the user sells to non-SaaS B2B — services, agencies, manufacturers, mid-market and enterprise companies, professional services firms. + +--- + +## ICP Signals That Matter (B2B branch) + +### Firmographic signals + +- **Industry / vertical** — NAICS or SIC codes if precision matters +- **Company size** — headcount band, revenue band, location count +- **Geography** — relevant for time zones, regulations, on-site requirements +- **Business model** — service vs product vs distribution; B2B vs B2B2C +- **Ownership** — independent, PE-backed, public, family-owned — affects buying motion + +### Buying signals + +- **Trigger events**: new C-level hire, recent acquisition or divestiture, IPO/funding, opening a new location, recent rebrand, expansion announcement +- **Vendor signals**: posting RFPs publicly, switching costs in last quarterly report, contract renewal windows +- **Operational signals**: recent layoffs (cost pressure) or rapid hiring (capacity pressure) +- **News mentions**: launching new initiative, entering new market, regulatory change forcing action +- **PR / press**: anything that signals "this company is changing right now" + +### Decay signals + +- Multiple bankruptcies or PE-stripped operations +- Negative growth + cost-cutting headlines +- Ownership stagnation (small family-owned, no growth incentive) +- Buyer turnover (3+ Marketing Directors in 2 years) + +--- + +## Discovery Sources (B2B branch) + +### Tier 1 — primary discovery + +- **Apollo**: best general B2B firmographic + contact discovery +- **ZoomInfo**: enterprise B2B + intent signals (mid-market+) +- **LinkedIn Sales Navigator**: industry + role + signal search; the gold standard for decision-maker mapping (manual) +- **Clay**: when you need custom waterfall lookups (e.g., enrich Apollo records with Hunter + Clearbit) + +### Tier 2 — industry-specific directories + +- **Crunchbase / Pitchbook**: funded businesses +- **D&B Hoovers**: large traditional B2B firmographics +- **State / national business registries**: for verified incorporation data +- **Industry association membership rosters**: trade groups often publish member lists +- **Trade show exhibitor lists**: signals active participation in a vertical +- **Procurement databases** (Procore for construction, e.g.): vertical-specific signals + +### Tier 3 — trigger event monitoring + +- **Google Alerts / Feedly**: trigger keywords ("acquired," "hires," "expansion," "raises," "announces") +- **PR Newswire / Business Wire**: company-controlled announcements +- **SEC filings** (public companies): material change disclosures +- **State filings**: new entity formation, dissolution + +--- + +## Qualification Checklist (B2B branch) + +- [ ] Industry / vertical matches ICP (use a recognized classification if possible) +- [ ] Company size within range (employees or revenue) +- [ ] Geography fits +- [ ] At least one trigger event in last 90–180 days +- [ ] Decision-maker role exists (CEO, COO, VP Operations, Director of X — match buyer profile) +- [ ] Email contact verifiable (named role > info@ catchall) +- [ ] Source URLs captured for firmographic claims +- [ ] No disqualifiers (closed, acquired-paused, multi-bankrupt, off-ICP) + +--- + +## Output Columns (B2B branch) + +Recommended CSV columns: + +```csv +score,company,domain,industry,naics_code,size_band,revenue_band,country,city,trigger_event,trigger_date,contact_name,contact_title,contact_email,email_status,linkedin_url,source_urls,why_prospect,confidence,verified_date,notes +``` + +For chat table, condense to: Score | Company | Industry | Size | Trigger | Contact | Email status | Confidence. + +--- + +## Top Outreach Targets Selection (B2B) + +Prioritize for the top 3–5 hot leads: + +1. **Trigger event recency** — 30 days beats 6 months +2. **Trigger event specificity** — new CMO hire in your buyer's role beats "company in the news" +3. **Decision-maker access** — named contact with verified email + LinkedIn beats role-only +4. **Vertical fit precision** — exact NAICS match beats "adjacent industry" + +Each top target rationale names the trigger and decision-maker: "Hired new VP of Marketing 14 days ago; verified email; mid-market manufacturer matching ICP." + +--- + +## Common Mistakes (B2B) + +1. **Treating B2B like SaaS** — funding rounds matter less; PE ownership and acquisition activity matter more. +2. **Trying to verify private company revenue precisely** — most public databases approximate. Use size bands, not point estimates. +3. **Ignoring procurement complexity** at enterprise scale — your prospect contact list may not include the actual approver. +4. **Cold-emailing executive assistants** — they're not the buyer and they will flag your outreach as spam. +5. **Source URL hygiene** — without source lineage, you can't defend a contact under GDPR DSAR or CAN-SPAM challenge. +6. **Stopping at one source** — Apollo can be 60% accurate on small businesses. Cross-verify with LinkedIn or the business website. diff --git a/skills/prospecting/references/compliance.md b/skills/prospecting/references/compliance.md new file mode 100644 index 0000000..34123d3 --- /dev/null +++ b/skills/prospecting/references/compliance.md @@ -0,0 +1,123 @@ +# Prospecting Compliance Reference + +The legal and platform-ToS constraints that apply to prospect list building. Read first, every engagement. + +> Operational guidance, not legal advice. For high-volume programs or programs touching EU/UK residents, run your setup past a privacy attorney. + +--- + +## United States — CAN-SPAM (downstream) + +CAN-SPAM regulates the cold email **send**, not the list build. But the list build matters because: + +- You must be able to identify the source of every email address you contact (required if challenged) +- The "from" line and email content rules apply at send time — but you can't lie about how you got the contact +- Opt-out requests must be honored within 10 business days and tracked + +**For prospecting specifically**: capture and retain the source URL + date for every contact you add to a list. CAN-SPAM doesn't require it explicitly, but defending your sender practices does. + +--- + +## EU / UK — GDPR + +The strictest applicable framework. Triggers when: + +- Your prospect resides in EU/UK +- You're processing personal data (any identifiable info, including business emails tied to a named person) + +### Lawful bases for cold B2B outreach + +You have three credible options: + +1. **Legitimate interest** (most common for B2B). Requires: + - The contact is in a business role likely to be interested in your offer + - The data was collected from a public, business-context source + - You provide a clear opt-out + - You can articulate the legitimate interest test in writing + +2. **Consent** — typically not feasible for cold outreach (you don't have consent before first contact) + +3. **Existing customer relationship** — only applies to current customers, not prospects + +### What you must do + +- Capture **source + date + lawful basis** for every contact +- Honor data subject access requests (DSARs) — you must be able to disclose, correct, or delete on request +- Include a privacy notice / opt-out in the first outreach +- Don't store personal data longer than necessary for the legitimate interest + +### What disqualifies a list + +- Bulk-scraped LinkedIn data — explicit ToS violation + GDPR risk +- Email addresses purchased from a list broker without source provenance +- "Anyone @ this domain" guessed emails sent without verification (multiplies risk + bounces) + +--- + +## Canada — CASL + +Stricter than CAN-SPAM. Cold B2B outreach requires: + +- **Express consent** (explicit opt-in) — typically not present for cold prospecting +- **OR implied consent** — existing business relationship within 24 months, OR business address publicly published on the company's own site for the purpose of receiving such communications + +**Practical implication for Canadian prospects**: relying on the publicly-published-address exception is the most defensible cold prospecting basis in Canada. You must include sender identification, mailing address, and an unsubscribe mechanism in every message. + +--- + +## Platform Terms of Service + +### LinkedIn + +- **Sales Navigator** as a research tool: fine +- **Scraping LinkedIn at any scale**: explicit ToS violation. Banned accounts are permanent. Don't. +- **Apollo, Clay, and ZoomInfo** claim LinkedIn-overlap data through various legitimate channels — verify their data sources before assuming compliance +- **InMail and Connection Requests**: governed by LinkedIn's own messaging rules, not by CAN-SPAM/GDPR (because LinkedIn-internal) + +### Google Maps + +- ToS prohibits bulk extraction or productizing Maps data +- Browser-assisted research as a discovery aid: acceptable +- Storing Place IDs or large structured Maps data in your CRM: explicit ToS prohibition +- Use Maps to **find** local businesses, then cross-source from the business's own site for the data you retain + +### Apollo / ZoomInfo / Clearbit + +- All have their own ToS limiting reselling, downstream sharing, and use cases +- Read your contract — typically you can use the data for your own outreach but not productize it +- Don't share extracts publicly (e.g., on a leaderboard, in a public report) + +### Crunchbase + +- Free tier is read-only for personal use +- Paid tier permits broader use within contractual scope +- API access requires paid Pro+ tier + +--- + +## Anti-Patterns (Don't Do These) + +1. **Bulk-scraping LinkedIn / Google Maps / Yelp**. Browser-assisted research is OK; automated scrapers pointed at these platforms are not. **Firecrawl and Browserbase are fine for an individual prospect's own website** (the URL you found through manual discovery) — not for the platforms hosting prospects. +2. **Buying lists from random vendors** without source provenance. You inherit their legal exposure. +3. **Guessing emails and sending unverified**. Bounce rates over 2% destroy sender reputation; legally, you can't claim a "legitimate interest" basis for an email you fabricated. +4. **Harvesting personal email addresses** (Gmail, personal Outlook, etc.) from public profiles. Personal addresses raise GDPR risk significantly. +5. **Storing data you don't need**. Minimize retention. Don't keep prospect lists forever — GDPR right to deletion applies. +6. **Skipping the lawful basis documentation**. If challenged, you need to show your work. Capture source URL + collection date for every contact. +7. **Reselling prospect lists**. You may not have the right to share them downstream. Read your data provider contracts. +8. **CAPTCHA bypass / login wall bypass**. Even if technically possible, this signals bot behavior and violates virtually every ToS. + +--- + +## Quick Audit Checklist + +Before shipping a list to the user (or downstream to cold-email): + +- [ ] Every contact has a source URL + collection date +- [ ] No contacts sourced from scraped LinkedIn data +- [ ] No Google Maps Place IDs or large Maps-structured data retained +- [ ] Lawful basis documented (legitimate interest test for B2B, or relevant alternative) +- [ ] Email addresses validated (deliverability check before outreach) +- [ ] Personal addresses (Gmail, etc.) flagged or excluded +- [ ] Source provider contracts permit the intended use case +- [ ] Retention plan documented (when to delete) +- [ ] First outreach will include unsubscribe + privacy notice (downstream concern for cold-email skill, but mention it now) diff --git a/skills/prospecting/references/data-sources.md b/skills/prospecting/references/data-sources.md new file mode 100644 index 0000000..7581967 --- /dev/null +++ b/skills/prospecting/references/data-sources.md @@ -0,0 +1,287 @@ +# Prospecting Data Sources + +Tool selection guide for prospecting across all three branches. + +--- + +## Tool selection by goal + +| Goal | Primary tools | Notes | +|------|--------------|-------| +| **Build initial firmographic list (B2B / SaaS)** | Apollo, ZoomInfo, Clay | Apollo for breadth, ZoomInfo for enterprise + intent, Clay for custom workflows | +| **Decision-maker mapping** | LinkedIn Sales Navigator (manual), Apollo, ZoomInfo | Sales Nav is the gold standard. Never bulk scrape it. | +| **Tech stack qualification (SaaS)** | BuiltWith, Wappalyzer | BuiltWith has wider coverage + paid plans for bulk; Wappalyzer is lighter + free for small use | +| **Funding signals (SaaS)** | Crunchbase, Pitchbook | Crunchbase free tier sufficient for early signals; Pitchbook for deeper investor data | +| **Email pattern discovery** | Hunter, Snov, Apollo | Pattern guessing — followed by verification | +| **Email deliverability verification** | Truelist, Hunter, NeverBounce, ZeroBounce | Always verify before adding to outreach lists | +| **Visitor identification (warm intent)** | RB2B, Clearbit Reveal | Anonymous traffic → company identification | +| **Intent data** | ZoomInfo Intent, 6sense, Bombora | Pre-warmed signals; mid-market+ pricing | +| **Trigger event monitoring** | Google Alerts, Feedly, LinkedIn Sales Nav alerts | Free options are sufficient for most | +| **Local business discovery** | Google Maps (manual), Yelp, Facebook Pages | Browser-assisted, not bulk-extracted | + +--- + +## Apollo + +**Use for**: General B2B / SaaS firmographic + contact data. Best starting point if you don't already have a list. + +**Strengths**: +- Large database (>200M contacts, >60M companies) +- Strong filtering UI (industry, size, technologies, signals) +- Integrated email + LinkedIn finder +- Pay-as-you-go and tiered plans + +**Watch out for**: +- Data freshness varies — re-verify before scoring as "Hot" +- Email accuracy ~60–80% — always validate +- Bulk export limits apply + +**Integration**: see [apollo.md](../../../tools/integrations/apollo.md) + +--- + +## Clay + +**Use for**: Multi-source enrichment, waterfall lookups, custom scoring logic. When list quality matters more than list size. + +**Strengths**: +- Waterfall logic: try Apollo first → fallback to ZoomInfo → fallback to Clearbit +- 100+ data provider integrations +- AI-powered enrichment (LLM-driven extraction from URLs) +- Custom columns + scoring formulas +- Native MCP server + +**Watch out for**: +- Per-credit pricing can spike on large lists +- Complexity overhead — easy to over-engineer workflows + +**Integration**: see [clay.md](../../../tools/integrations/clay.md) + +--- + +## ZoomInfo + +**Use for**: Enterprise B2B + intent data. Mid-market+ buyer profiles. + +**Strengths**: +- Enterprise-grade firmographic depth +- Intent signals (companies searching topics relevant to your offer) +- Best-in-class for >$50K ACV B2B sales +- Native MCP server + +**Watch out for**: +- Expensive ($15K+/yr starter) +- Overkill for SMB prospecting +- Locked into multi-year contracts typically + +**Integration**: see [zoominfo.md](../../../tools/integrations/zoominfo.md) + +--- + +## Clearbit + +**Use for**: Email → company enrichment, anonymous visitor identification (Clearbit Reveal). + +**Strengths**: +- Strong company enrichment (industry, size, funding, tech stack) +- Email lookup by domain +- Reveal: identify anonymous site visitors at company level +- API-first + +**Watch out for**: +- HubSpot acquisition (2023) — bundled into HubSpot Breeze Intelligence now +- Standalone API still available but pricing/access depends on tier + +**Integration**: see [clearbit.md](../../../tools/integrations/clearbit.md) + +--- + +## Hunter / Snov + +**Use for**: Email pattern discovery + lightweight verification on small lists. + +**Hunter strengths**: +- Domain-based email discovery +- Built-in deliverability verification +- Free tier reasonable for occasional use + +**Snov strengths**: +- Email finder + drip campaigns (overlap with outreach tooling) +- Bulk verification +- Cheaper than Hunter at scale + +**Watch out for**: +- Both are pattern-guessing tools — accuracy depends on the target company's email pattern being inferable +- Always run results through a dedicated validator (Truelist or similar) before outreach + +**Integrations**: see [hunter.md](../../../tools/integrations/hunter.md), [snov.md](../../../tools/integrations/snov.md) + +--- + +## Truelist + +**Use for**: Email deliverability validation before adding contacts to outreach lists. Critical safety step. + +**Strengths**: +- Single-email sync verification (`/api/v1/verify_inline`) + bulk async (`/api/v1/verify`) +- Returns `email_state` (ok / email_invalid / risky / unknown / accept_all) + `email_sub_state` (email_ok / is_disposable / is_role / unknown_error / failed_smtp_check) + did-you-mean typo suggestions +- Catches catch-all domains, role accounts, spam traps, disposable providers +- Official MCP server for agent-driven workflows (Claude, Cursor, VS Code) +- Official SDKs in 7 languages + framework integrations (Django, Laravel, Next.js, Rails, React, Svelte, Vue, WordPress) +- Native integrations with Mailchimp, Klaviyo, HubSpot, Zapier, Make, n8n, Clay, Salesforce, more +- Pay-per-email pricing + +**Why this matters**: Cold email reputation craters when bounce rates exceed 2%. Validating before sending is non-negotiable. Apollo/ZoomInfo/Hunter data is often 60–80% accurate — Truelist catches the rest. + +**Integration**: see [truelist.md](../../../tools/integrations/truelist.md) + +--- + +## LinkedIn Sales Navigator + +**Use for**: Manual decision-maker discovery. The gold standard for B2B / SaaS prospecting but only when used as a research tool. + +**Strengths**: +- Most accurate decision-maker data in the industry +- Real-time job changes, posts, signals +- Lead lists, alerts, saved searches +- Inmail credits (separate channel from cold email) + +**Hard rules**: +- **Never bulk scrape**. LinkedIn aggressively bans scrapers. Account ban risk is real and permanent. +- Use Sales Nav as a research interface — open profiles, read, take notes, capture key data manually. +- Apollo and other tools claim LinkedIn data via partnerships / public mirroring — verify the source legitimacy before assuming compliance. + +**Integration**: no MCP or API access at consumer level. Manual research only. + +--- + +## BuiltWith / Wappalyzer + +**Use for**: Tech stack qualification (SaaS branch). + +**BuiltWith**: +- ~50K+ technologies tracked +- API + bulk lookups (paid) +- Historical data (when stack changed) + +**Wappalyzer**: +- Free browser extension; paid API +- Lighter coverage than BuiltWith +- Faster for one-off lookups + +Cross-reference both for high-confidence tech stack signals. + +--- + +## Crunchbase + +**Use for**: Funding signals (SaaS branch). + +**Strengths**: +- Free tier shows recent funding events +- Paid (Pro / Enterprise) unlocks alerts and deep history +- API access for paid users + +**Watch out for**: +- Coverage is best for VC-backed companies; bootstrapped + small businesses underrepresented +- Self-reported data — verify funding amounts independently + +--- + +## GitHub (stargazers / forks / watchers) + +**Use for**: Developer-intent prospecting. Especially powerful for dev-tool SaaS — stargazers of competitor or category-defining repos are in-market signal. + +**Strengths**: +- Public API, no scraping concerns +- High signal quality (a starred repo = explicit interest) +- Forks are an even stronger signal (intent to modify, not just bookmark) +- Bundled `github-prospects.js` CLI handles pagination + enrichment + CSV output +- Free with 5,000 req/hr authenticated rate limit + +**Watch out for**: +- Only ~5–20% of users publish email — pair with Apollo/Clay/Hunter for enrichment +- Very-popular repos (100K+ stars) are mostly noise; smaller targeted repos (5K–25K) give better signal density +- Most prospects are individuals, not company contacts directly — need to figure out their company from `company` field or LinkedIn + +**Integration**: see [github.md](../../../tools/integrations/github.md) + +--- + +## Firecrawl / Browserbase (single-target site research) + +**Use for**: Programmatically extracting content from a **prospect's own website** that you already found via discovery on platforms like Google Maps, Yelp, or LinkedIn. Not for scraping those platforms themselves. + +### Firecrawl + +- **Best for**: "Just give me the page as markdown" — Local SMB website status checks, B2B company about/team page extraction, structured field extraction +- **Strengths**: Low overhead, returns clean LLM-ready markdown, handles most JS-rendered sites, has an MCP server +- **API + MCP + SDKs**: Node, Python, Go, Rust + +### Browserbase + +- **Best for**: When you need real Chromium — JS-heavy pages, cookie consent dialogs, form submission to reach a contact page, session state +- **Strengths**: Full browser control via Playwright/Puppeteer; Stagehand provides AI-friendly natural-language extraction; session recordings for debugging +- **API + MCP (Stagehand) + SDKs**: Node, Python + +### Critical compliance line + +Both tools can technically point at any URL. The hard rule: + +- ✓ **OK**: extracting content from a single business's own website (`joescoffeeshop.com`) that you found through manual discovery +- ✗ **NOT OK**: pointing them at `google.com/maps`, LinkedIn search results, Yelp listings, or any platform whose ToS prohibits bulk extraction + +Discovery happens on platforms (manual browser-assisted research). Extraction happens on individual public business sites. + +**Integrations**: see [firecrawl.md](../../../tools/integrations/firecrawl.md), [browserbase.md](../../../tools/integrations/browserbase.md) + +--- + +## RB2B / Clearbit Reveal + +**Use for**: Identifying anonymous site visitors as warm intent signals. + +**Strengths**: +- Pixel-based visitor → company identification +- High-intent: they came to your site, they're already in research mode +- Slack / email alerts on key visits + +**Watch out for**: +- Privacy/GDPR considerations — verify your privacy policy disclosures +- Person-level identification raises higher concerns than company-level + +**Integration**: see [rb2b.md](../../../tools/integrations/rb2b.md) + +--- + +## Free / browser-only fallbacks + +When the user has no paid tools, lean on: + +- **Google Search** — exact business name + city + role searches +- **LinkedIn** (manual, no scraping) — company pages, employee lookups +- **Crunchbase free tier** — funding events +- **Wappalyzer browser extension** — tech stack at a glance +- **Hunter.io free tier** — 25 lookups/month +- **Google Maps** — for Local SMB discovery +- **Business websites + About pages** — primary source for any claim +- **News sites + press releases** — trigger event monitoring via Google Alerts + +Slower than tooled-up workflows, but produces high-quality smaller lists if the user is willing to do the work. + +--- + +## Sequencing recommendations + +A typical full-stack prospecting workflow: + +1. **Define ICP** from product-marketing context (no tools needed) +2. **Initial list** from Apollo or ZoomInfo (firmographic filter) +3. **Enrich** with Clay (waterfall: tech stack, funding, trigger events) +4. **Decision-maker mapping** in LinkedIn Sales Nav (manual) +5. **Email pattern discovery** with Hunter or Apollo's built-in +6. **Email validation** with Truelist before final list +7. **Hand off** to cold-email skill for outreach copy + +Adapt this sequence based on which tools the user actually has. diff --git a/skills/prospecting/references/local-prospecting.md b/skills/prospecting/references/local-prospecting.md new file mode 100644 index 0000000..a1bae41 --- /dev/null +++ b/skills/prospecting/references/local-prospecting.md @@ -0,0 +1,165 @@ +# Local SMB Prospecting Reference + +For when the user sells to local small businesses — shops, gyms, restaurants, salons, clinics, professional services, contractors, real estate, fitness studios, dental practices. + +Adapted from and generalized beyond the local-client-prospector pattern (browser-assisted discovery + website status classification + proximity scoring). + +--- + +## ICP Signals That Matter (Local SMB branch) + +### Operational signals + +- **Active business** — Google Business Profile updated, recent reviews, recent hours updates +- **Recent activity** — open right now, regular hours posted, recent photos uploaded by owner +- **Customer engagement** — owner responding to reviews, posts on social, active calendar (for service businesses) + +### Online presence signals (the core SMB qualification axis) + +The reference local-client-prospector skill uses **website status** as the primary qualification — port this directly. Four classifications: + +| Status | Definition | Typical outcome | +|--------|-----------|-----------------| +| **No site found** | No credible standalone website after cross-checked search | **Hot prospect** for web/marketing service | +| **Social only** | Facebook, Instagram, WhatsApp, Linktree, booking portal, marketplace page only — no standalone site | **Hot prospect** for web/marketing service | +| **Weak site** | Standalone site exists but outdated, broken, very thin, non-mobile-friendly, or missing clear contact/conversion flow | **Warm prospect** for refresh / rebuild service | +| **Has site** | Credible, modern standalone site exists | **Low prospect** unless other signals apply (e.g., poor SEO, weak conversion design) | + +### Proximity signals + +- **Distance** from the user's location or service area +- **Density** — clusters of similar businesses in one area = neighborhood targeting opportunity +- **Travel time** — useful when in-person discovery, install, or service delivery is required + +### Decay signals + +- Closed permanently (Google Maps banner) +- Reviews paused or business listing reported as closed +- Last activity (review, post) >12 months ago + +--- + +## Discovery Sources (Local SMB branch) + +### Primary + +- **Google Maps** (browser, manual) — search "category near [location]" and walk the visible results. Cross-check details. Don't bulk-extract. +- **Yelp** — secondary verification; complementary categories +- **Bing Local / Apple Maps** — different coverage on smaller businesses +- **Facebook Pages search** — many SMBs are Facebook-only + +### Cross-verification + +- **Business's own website** (if any) +- **Industry directories** (e.g., Healthgrades for medical, OpenTable for restaurants, Avvo for legal) +- **Local Chamber of Commerce listings** +- **State business registries** for incorporation status +- **Search results for "[business name] [city]"** to discover non-Maps presence + +--- + +## Browser Research Workflow + +1. Open a browser and search Google Maps for the category near `base_location` +2. Build a candidate list from visible local results, search results, and public directories +3. For each candidate, inspect public sources to fill required fields +4. Search the exact business name plus city/town to check whether a standalone website exists +5. Classify website status per the table above +6. Mark confidence: High (2+ sources), Medium (1 source + consistent evidence), Low (incomplete/ambiguous) + +When the user explicitly asks for subagents AND subagents are available, split candidates into non-overlapping batches and ask each subagent to verify only website/social/contact status. Don't use subagents for the primary search if it slows progress. + +### Optional: programmatic verification with Firecrawl or Browserbase + +Once you have a candidate's website URL (found via manual Maps/Yelp discovery), you can speed up website-status classification by hitting the URL programmatically: + +- **Firecrawl** for simple "is this site live, modern, mobile-friendly, conversion-flow-equipped" reads — returns clean markdown you can inspect +- **Browserbase** when the candidate site requires JS rendering, has a cookie consent dialog, or you need session state + +**Strict line**: use these on the individual business's URL. **Don't** point them at Google Maps, Yelp, or any platform whose ToS prohibits bulk extraction — discovery stays manual. + +See [data-sources.md](data-sources.md) for setup details. + +--- + +## Qualification Checklist (Local SMB branch) + +- [ ] Business is active (recent reviews or activity in last 6 months) +- [ ] Category matches user's service offering +- [ ] Distance / proximity within target radius +- [ ] Website status classified +- [ ] Phone or contact channel verified +- [ ] At least one cross-source confirms business operates at the listed address +- [ ] Not a duplicate / chain location / out-of-scope category +- [ ] Not closed permanently + +--- + +## Lead Scoring (Local SMB) + +Use this simple rubric (matches local-client-prospector pattern): + +| Score | Criteria | +|-------|----------| +| **Hot** | No site found OR social-only + phone present + active business + within target radius | +| **Warm** | Weak site, poor online presentation, or marketplace/booking-page only | +| **Cold** | Good website already present OR low confidence | +| **Skip** | Closed, duplicate, outside radius, irrelevant category, or not a business prospect | + +--- + +## Output Columns (Local SMB branch) + +Chat table (≤15 rows): + +``` +| Score | Business | Category | Area | Distance | Website status | Website/Social | Phone | Why it's a prospect | Confidence | +``` + +CSV: + +```csv +score,business,category,area,distance_km,website_status,website_url,social_urls,phone,email,source_urls,why_prospect,confidence,verified_date,notes +``` + +Rules: +- Keep "Why it's a prospect" short and actionable +- Use `Not found` instead of leaving blank fields +- Include source links sparingly, not all of them +- After the table, add **Best first outreach targets** with the top 3 leads and one practical reason each +- If confidence is low, state exactly what remains uncertain + +--- + +## Top Outreach Targets Selection (Local SMB) + +Prioritize for the top 3 hot leads: + +1. **No site / social only + phone present** = clearest service opportunity +2. **High review count** = active, established business with real customers +3. **Owner-responded reviews** = engaged owner = more likely to evaluate a vendor +4. **Industry alignment with your service specialty** beats generic category match + +Each top target rationale should be one sentence naming the gap and the signal: "No standalone website (cross-checked); 80+ Google reviews with owner replies; 2 km from target area." + +--- + +## Compliance Notes (Local SMB-specific) + +The local branch is the most scraping-sensitive of the three motions. Specifically: + +- **Google Maps Terms of Service** prohibit bulk extraction. Treat browser visits as research, not as data acquisition. +- **Don't store full Google Maps Place IDs in your CRM** — the ToS limits storage of Maps data. +- **Public business contact channels only**: published phone, contact form, info@ email. Don't reach individual employees through their personal channels. +- **Owner/operator name when published on the business's own site** is OK to use. If you only got it from LinkedIn, mark the source. + +--- + +## Common Mistakes (Local SMB) + +1. **Bulk-scraping Google Maps** — fastest way to violate ToS and lose the research channel. +2. **Treating Google Maps data as truth** — listings go stale. Cross-check hours, status, and reviews. +3. **Skipping the website status cross-check** — finding "no site" on Maps doesn't mean no site exists; do an exact-name web search before classifying. +4. **Targeting only the largest businesses** — they're already covered by other providers. The 2–5 employee SMBs are the under-served opportunity. +5. **Generic outreach to all hot leads** — local SMBs respond better to outreach that names their specific gap ("I noticed your menu isn't visible on mobile") than generic pitches. +6. **Ignoring chains and franchises** as Skip — sometimes the franchisee is the buyer and they have local marketing authority. Verify before skipping. diff --git a/skills/prospecting/references/saas-prospecting.md b/skills/prospecting/references/saas-prospecting.md new file mode 100644 index 0000000..491d64a --- /dev/null +++ b/skills/prospecting/references/saas-prospecting.md @@ -0,0 +1,123 @@ +# SaaS Prospecting Reference + +For when the user sells SaaS or digital services to other SaaS companies / digital businesses. + +--- + +## ICP Signals That Matter (SaaS branch) + +Beyond standard firmographics (industry, size, geography), SaaS prospects are qualified by: + +### Technographic signals + +- **Tech stack** — do they use complementary tools (your integration target) or competing tools (a switch opportunity)? +- **Recent stack changes** — adding/removing tools signals active vendor evaluation +- **Custom-built vs off-the-shelf** — DIY tooling often means a buyer who'd benefit from your product +- **Free/freemium plan signals** — using a free competitor means they may be ready to upgrade + +### Growth signals + +- **Funding round** — Series A / B / C in last 6 months = budget + new hires + tool needs +- **Headcount growth** — 10%+ growth in last quarter signals scaling pressure +- **Hiring signals** — specific role openings (e.g., "Head of RevOps" → ICP for revops tooling) +- **Product velocity** — frequent shipping, new features, blog posts = healthy growth motion +- **Open positions for your buyer's role** — if you sell to Marketing Ops and they're hiring one, that's a signal + +### Decay signals (downgrade scoring) + +- Layoffs in target department +- Funding round >2 years ago with no follow-up +- Product hasn't shipped in 6+ months +- Team page shows founders only (very early — may not have budget) + +--- + +## Discovery Sources (SaaS branch) + +Combine 2+ sources for cross-verification. + +### Tier 1 — primary discovery + +- **Apollo**: firmographic + technographic + contact data. Good for building large initial lists. +- **Clay**: waterfall enrichment, custom scoring, multi-source merges. Best for high-quality smaller lists. +- **ZoomInfo**: enterprise-grade firmographic + intent signals. Expensive; mid-market+. +- **LinkedIn Sales Navigator**: decision-maker mapping. Use manually, never bulk scrape. + +### Tier 2 — technographic / growth signals + +- **BuiltWith**: tech stack lookups, find sites using specific tools +- **Wappalyzer**: free browser extension + API; lighter tech stack signal +- **Crunchbase**: funding rounds, headcount, founders +- **Pitchbook**: deeper investor data (enterprise/paid) +- **ProductHunt**: recent launches, builder audience +- **Hacker News / Show HN**: technical builders launching products + +### Tier 3 — buying signals + +- **Job boards** (LinkedIn Jobs, Indeed, AngelList): role openings as signals +- **RB2B / Clearbit Reveal**: visitor identification (warm anonymous traffic) +- **GitHub stars/forks of competitor or adjacent repos**: developer-level intent signal (see `tools/integrations/github.md` and the `github-prospects.js` CLI). Especially strong for dev-tool SaaS — a developer who starred `vercel/next.js` last week is in-market for adjacent Next.js infrastructure. +- **Recent blog posts / changelog**: product direction signals +- **G2 reviews mentioning competitor switches**: explicit dissatisfaction signal + +#### GitHub prospecting pattern (when audience is developers) + +For dev-tool SaaS, GitHub is one of the highest-quality discovery channels: + +1. Identify 3–5 "anchor" repos: your direct competitors, your category leader, complementary tools your buyer uses +2. Pull stargazers (or forks for stronger intent) via `node tools/clis/github-prospects.js stargazers <owner/repo> --enrich --with-company --format csv` +3. Filter to users with `company` set — these are the easiest to enrich downstream +4. Pair with Apollo/Clay/Hunter to lookup email by name + company +5. Validate with Truelist before adding to outreach list + +Tradeoffs: GitHub yields email for only ~5–20% of users directly. The strength is the signal quality — a stargazer of a niche dev tool is genuinely in-market in a way Apollo firmographics alone can't tell you. + +--- + +## Qualification Checklist (SaaS branch) + +For each candidate, verify: + +- [ ] Industry vertical matches ICP +- [ ] Company size (headcount) within range +- [ ] Tech stack includes (or notably excludes) a target technology +- [ ] Funding stage matches buyer maturity +- [ ] At least one growth signal in last 90 days (funding, hiring, product velocity) +- [ ] Decision-maker role exists at the company (named or inferable from job listings) +- [ ] Email contact verifiable +- [ ] No disqualifiers (closed, acquired-and-paused, layoffs, ICP miss) + +--- + +## Output Columns (SaaS branch) + +Recommended CSV columns: + +```csv +score,company,domain,industry,size_band,country,funding_stage,last_round_date,tech_stack_match,signal,signal_date,contact_name,contact_title,contact_email,email_status,linkedin_url,source_urls,why_prospect,confidence,verified_date,notes +``` + +For chat table, condense to: Score | Company | Industry | Size | Signal | Contact | Email status | Confidence. + +--- + +## Top Outreach Targets Selection (SaaS) + +Prioritize for the top 3–5 hot leads: + +1. **Strongest signal recency** — funding 30 days ago beats funding 9 months ago +2. **Tech stack match strength** — known integration partner beats inferred fit +3. **Decision-maker named with verified email** — beats role-pattern-guessed email +4. **Multi-source confidence** — both Apollo + Crunchbase agree beats one source + +Each top target gets a one-sentence outreach rationale that names the specific signal: "Raised Series B 30 days ago; hiring Head of RevOps; verified VP of Ops email." + +--- + +## Common Mistakes (SaaS) + +1. **Buying lists from Apollo wholesale** without re-verifying email and re-checking firmographics. Stale data is the norm. +2. **Treating tech stack data as 100% accurate**. BuiltWith and Wappalyzer miss things; Clay's waterfalls miss things. Cross-check. +3. **Targeting Series C+ for early-stage SaaS sellers**. The buyer profile is wrong — too many procurement hoops, too much red tape. +4. **Targeting Series Pre-Seed seed** for products requiring meaningful budget. They have neither budget nor evaluator bandwidth. +5. **Ignoring intent data when it exists** (ZoomInfo Intent, 6sense, etc.) — pre-warm signals beat cold every time. diff --git a/skills/sms/SKILL.md b/skills/sms/SKILL.md new file mode 100644 index 0000000..50cfa8d --- /dev/null +++ b/skills/sms/SKILL.md @@ -0,0 +1,338 @@ +--- +name: sms +description: When the user wants to plan, build, or optimize SMS or MMS marketing — including welcome flows, abandoned cart texts, post-purchase, win-back, promotional sends, or transactional/auth SMS. Also use when the user mentions "SMS marketing," "text message campaigns," "SMS sequence," "SMS automation," "abandoned cart text," "post-purchase SMS," "Klaviyo SMS," "Postscript," "Attentive," "Twilio," "A2P 10DLC," "TCPA," "SMS compliance," "short code," "toll-free SMS," "MMS campaign," "should I do SMS," or "SMS vs email." For email sequences, see emails. For SMS copy framing, see copywriting. For opt-in popups that capture phone numbers, see popups. +metadata: + version: 1.0.0 +--- + +# SMS Marketing + +You are an expert in SMS and MMS marketing for direct-to-consumer brands, mobile apps, and SaaS products with high-engagement use cases. Your goal is to help plan, build, and optimize SMS programs that drive measurable revenue or activation while staying fully compliant with TCPA and carrier rules. + +## Before Starting + +**Check for product marketing context first:** +If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. + +Gather this context (ask if not provided): + +### 1. Business Type +- B2C ecom / DTC, B2B SaaS, mobile app, services, fintech +- Order volume or list size (SMS economics depend on scale) +- Geographic mix (US, EU, both — compliance differs dramatically) + +### 2. Current State +- Existing SMS program (platform, list size, opt-in rate, opt-out rate, revenue/send) +- Email program (SMS works best as a layer on top, not a replacement) +- Phone number type: short code, toll-free, long code (10DLC) + +### 3. Compliance Posture +- US: A2P 10DLC registration complete? (Required since 2022 — without it, your messages get filtered) +- Opt-in mechanism in use? (Checkbox, keyword opt-in, double opt-in) +- Privacy policy + terms include SMS disclosures? + +### 4. Goal +- Drive revenue (promotional, cart recovery, post-purchase) +- Drive activation (welcome, onboarding, milestone nudges) +- Transactional (order updates, auth codes, alerts) + +--- + +## When SMS Beats Email + +SMS is not "another email." Use it where the channel's properties win: + +| Use Case | SMS or Email? | Why | +|----------|---------------|-----| +| Abandoned cart recovery | **SMS first** | 98% open rate within 3 min vs 20% for email in 24h | +| Order/shipping updates | **SMS** | Customers want it now, on their phone | +| Flash sale / limited drop | **SMS** | Urgency channel; immediate read | +| Auth codes / 2FA | **SMS** (or app) | Latency-sensitive, must arrive in seconds | +| Welcome series | **Email primary, SMS layer** | Email carries the long-form content | +| Educational nurture | **Email** | Too much text for SMS, costs add up | +| Newsletter | **Email** | Wrong channel for SMS | +| Win-back lapsed customers | **Both** | SMS for the strong nudge, email for the offer detail | +| Post-purchase upsell | **SMS** | High open rate, ride the purchase momentum | + +**General rule**: SMS earns the right to interrupt because of opt-in. Use it for messages that genuinely benefit from immediacy. If it could wait 24 hours, send it via email. + +--- + +## Compliance — Read First + +**Compliance is the foundation, not an afterthought.** A single TCPA class-action settlement runs $5M–$40M. The basics: + +### US — TCPA (Telephone Consumer Protection Act) + +1. **Express written consent** required for marketing SMS. Implied consent doesn't count. +2. **Clear disclosure at opt-in** must include: program name, frequency expectation ("up to 4 msgs/month"), STOP/HELP instructions, "Msg & data rates may apply," link to terms. +3. **Honor STOP/UNSUBSCRIBE within seconds**, every time, no exceptions, on every keyword variant (STOP, END, CANCEL, UNSUBSCRIBE, QUIT). +4. **Honor HELP** with a response containing brand name + STOP info + support contact. +5. **Quiet hours**: no marketing sends before 8am or after 9pm in the recipient's local time. Carrier rules and state laws (e.g., Florida, Oklahoma, Washington) are stricter than federal — default to 9am–8pm recipient-local. +6. **Keep written consent records** with timestamp, opt-in source, and exact disclosure text shown. Auditable. + +### US — A2P 10DLC Registration (required since 2022) + +Application-to-Person 10-digit long codes must be registered through The Campaign Registry (TCR) via your SMS platform. Without registration: +- Throughput is throttled (or zero) +- Carriers filter your messages +- You'll see "delivered" status but recipients won't get them + +**Registration covers**: brand identity verification, campaign use case (marketing, account notification, OTP, etc.), sample messages, opt-in mechanism, opt-out language. Sample message text from registration must match what you actually send. + +### EU/UK — GDPR-derived consent + +- Explicit opt-in required (no pre-checked boxes) +- Right to withdraw consent must be as easy as giving it +- Data subject access requests apply to SMS records +- ePrivacy Directive layered on top of GDPR + +### Canada — CASL + +- Express consent + sender identification + unsubscribe in every message +- Implied consent allowed for existing business relationships within 24 months +- Penalties up to CAD $10M per violation + +**For full compliance details, edge cases, opt-in copy templates, and STOP/HELP response templates**: see [references/compliance.md](references/compliance.md). + +--- + +## Phone Number Types (US) + +| Type | Throughput | Cost | Use Case | Trust | +|------|-----------|------|----------|-------| +| **Short code (5-6 digit)** | 100+ msg/sec | $500–$1,000/mo + setup | High-volume marketing | Highest (carrier-vetted) | +| **Toll-free (1-8XX)** | ~3 msg/sec | $10–$30/mo | Mid-volume, B2C support | Medium-high (carrier-verified) | +| **10DLC (regular long code)** | 1–250 msg/sec | $2–$10/mo | SMB, conversational, transactional | Medium (requires A2P 10DLC reg) | + +**Rule of thumb**: list <10K = 10DLC. List 10K–100K = toll-free. List 100K+ = short code. + +--- + +## Core Principles + +### 1. Every send has a real cost +SMS isn't free. At $0.0075–$0.04 per send + carrier fees, a 100K send costs $750–$4,000. This forces relevance — you can't "blast." Segment hard. + +### 2. Opt-in is your most valuable asset +Opt-in rate from email → SMS is typically 5–25%. A high-quality SMS list of 10K beats a low-quality list of 100K. Optimize opt-in quality, not volume. + +### 3. Each message must justify itself +The recipient gave you their phone number. Every send should pass: "would I be glad I got this text?" If no, don't send. + +### 4. Brevity + clarity +160 GSM-7 characters = 1 SMS segment. 161+ chars = 2 segments (you're billed for 2). Emojis force UCS-2 encoding (70 chars per segment). Plan for segment count. + +### 5. One CTA, one link +Short links are mandatory (`klvy.co`, `txt.attn.tv`, branded short domain). Track UTM params on every link. + +### 6. Sender identity, every send +"From [Brand]:" or branded short code at the start of every message. Even on automated flows. Recipients can't see "from" address — they need it inline. + +--- + +## SMS Sequence Types + +### Welcome / Opt-In Confirmation (immediate) + +Send 1: Confirmation + reward (immediate) +> From Acme: Thanks for joining! Here's 10% off: ACME10. Use at checkout: acme.co/sale. Reply STOP to opt out. + +Optional Send 2 (24h later): Reminder + best-seller showcase + +### Abandoned Cart (highest-ROI flow for ecom) + +- Send 1 (30 min after abandon): "Forget something? Your cart's still here: [short link]" +- Send 2 (4 hours later): Soft urgency + social proof +- Send 3 (24 hours later, optional): Discount offer (only if margin allows) + +**Note**: Discount on first message trains customers to abandon. Reserve discount for Send 2 or 3. + +### Browse Abandonment + +- Send 1 (1 hour after browse): Product + "Thinking it over?" + link + +### Post-Purchase + +- Send 1 (immediate): Order confirmation + delivery ETA (transactional, separate consent OK) +- Send 2 (after delivery + 2 days): "How are you liking [product]?" + review prompt + cross-sell + +### Win-Back (lapsed) + +- Send 1 (60–90 days after last purchase): "We miss you" + curated picks +- Send 2 (14 days later): Discount offer +- Send 3 (final, 14 days later): Opt-out warning + last chance + +### Promotional / Campaign Sends + +- Flash sales, drops, launches, BFCM +- 1–2 sends max per campaign +- Stack against email send schedule to avoid same-day double-tap + +### Transactional (separate compliance bucket) + +- Order updates, shipping, delivery, auth codes, account alerts +- Generally OK without separate marketing consent if directly related to a transaction the user initiated +- Still subject to A2P 10DLC registration in US + +**For full sequence templates with copy and timing**: see [references/sequence-templates.md](references/sequence-templates.md). + +--- + +## SMS Copy Guidelines + +### Structure +1. **Sender ID** ("From Acme:" or brand short code) — required +2. **Hook** — first 5 words decide if they read on +3. **Value** — what's in it for them, specifically +4. **CTA + short link** — single action, single URL +5. **Compliance footer** — "Reply STOP to opt out" (required on opt-in confirmation and at least quarterly thereafter; carrier-recommended on every promotional message) + +### Length + +- **160 chars (GSM-7)** = 1 segment. Aim here. +- **70 chars (UCS-2)** if you use emojis, accented characters, or curly quotes — you'll pay for more segments. +- **161–306 chars** = 2 segments (concatenated SMS). Acceptable for richer messages, but you're paying double per send. +- **MMS** (image + up to 1,600 chars) = 3–5× the SMS cost. Use sparingly for high-impact moments. + +### Voice + +- Conversational, not corporate. SMS feels personal — write like you're texting a friend. +- No subject line, no formatting, no marketing-speak. +- Emojis are fine in moderation (one per message, situationally). +- ALL CAPS reads as shouting. Avoid except for explicit codes (e.g., "Use ACME10"). + +### Personalization + +- First name token if available (boosts CTR ~20%) +- Recent product/category browse-based +- Location-based offers (where applicable) +- Don't fake intimacy ("Hey friend!") — it backfires + +**For complete copy patterns by sequence type with character counts**: see [references/sequence-templates.md](references/sequence-templates.md). + +--- + +## Platform Selection + +| Platform | Best For | Native MCP | Cost Tier | +|----------|----------|:---:|-----------| +| **Klaviyo SMS** | DTC ecom already on Klaviyo email | ✓ | $$ | +| **Postscript** | DTC Shopify ecom, deep integration | - | $$ | +| **Attentive** | Mid-market+ ecom, full-service | - | $$$ | +| **Twilio** | Custom builds, transactional, devs | - | $ (raw API) | +| **Brevo SMS** | EU-focused, email + SMS combo | ✓ | $ | +| **SimpleTexting** | SMB, simple needs, ease of use | - | $ | +| **Customer.io** | Behavior-based automation + SMS | - | $$ | + +**Quick picks**: +- Already on Klaviyo for email + DTC/ecom → **Klaviyo SMS** (no second platform to learn) +- Shopify ecom, want deeper SMS-specific features → **Postscript** +- Building custom SMS into a product → **Twilio** +- B2B SaaS doing transactional/auth → **Twilio** or **Customer.io** + +**For platform deep-dives (features, pricing, integration paths, A2P registration)**: see [references/platforms.md](references/platforms.md). + +--- + +## Measurement + +### Key Metrics + +| Metric | What it tells you | Healthy range (ecom DTC) | +|--------|-------------------|--------------------------| +| **Opt-in rate** | Top of funnel health | 5–25% of email subscribers | +| **CTR** | Message relevance | 8–15% (vs ~3% email) | +| **Conversion rate (per send)** | Revenue impact | 1–5% per promotional send | +| **Revenue per send (RPS)** | Channel economics | $0.20–$2.00 | +| **Opt-out rate per send** | Audience fatigue | <2% per send, <0.5% for promotional | +| **Cost per send** | Channel cost discipline | $0.0075–$0.04 | +| **List growth rate** | Audience momentum | 5–15%/month early, 1–3% steady-state | + +### What to track in analytics + +- UTM tag every link: `utm_source=sms&utm_medium=sms&utm_campaign=[campaign-name]` +- Conversion attribution: SMS-driven sessions, last-click revenue, assisted conversions +- LTV impact: SMS subscribers vs email-only subscribers (typically 1.5–3× LTV for SMS opt-ins) + +### What to A/B test + +- Send time (afternoon vs evening, local time) +- Copy length (short SMS vs MMS with image) +- Discount amount and trigger (immediate vs delayed) +- Personalization tokens (with first name vs without) +- CTA copy ("Shop now" vs "See it" vs "Last chance") + +Cross-reference **ab-testing** skill for proper test design and **analytics** for attribution setup. + +--- + +## Output Format + +When the user asks for an SMS plan, return: + +1. **Compliance check**: Are they registered for A2P 10DLC (if US)? Is the opt-in mechanism compliant? Flag blockers first. +2. **Strategy**: Which SMS flows to build first, ranked by ROI for their business model. +3. **Sequence designs**: For each priority flow, specify trigger, delay, copy with character counts, CTA, segmentation. +4. **Platform recommendation**: Based on stack, list size, and complexity. +5. **Measurement plan**: KPIs, benchmarks, A/B test queue. +6. **Compliance footer**: Required disclosures, STOP/HELP response templates. + +Keep recommendations specific. Don't say "send an SMS at the right time" — say "send 30 min after cart abandon, 4 hours later if no purchase, 24 hours later with discount." + +--- + +## Task-Specific Questions + +1. Are you US, EU, or both? (Changes compliance approach entirely.) +2. Is A2P 10DLC registration complete (US)? +3. What platform are you on or considering? +4. Email list size and SMS opt-in rate (if any)? +5. What sequences do you already have running? +6. Are you DTC ecom, mobile app, B2B SaaS, services? +7. What's the primary goal: revenue, activation, retention, or transactional? + +--- + +## Common Mistakes + +1. **Skipping A2P 10DLC registration** — your messages get filtered into oblivion. Register first, send second. +2. **Treating SMS like email** — sending daily promotional blasts. Opt-out rates spike, list dies. +3. **Discount on first abandoned cart message** — trains customers to always abandon. Reserve for second or third send. +4. **Generic "From: [shortcode]"** — recipients need brand name in the message itself. +5. **Forgetting quiet hours** — sending at 6 AM local time gets opt-outs and TCPA complaints. +6. **No STOP/HELP handling** — non-negotiable. Every platform handles this; verify yours does. +7. **Emojis everywhere** — pushes you into UCS-2 encoding, halves segment size, doubles cost. +8. **Mismatching A2P sample messages and actual sends** — carriers flag and block. +9. **Not tracking conversions** — you can't justify channel ROI without attribution. +10. **No throttling on bulk sends** — burst sends trigger carrier filtering. Use platform throttling. + +--- + +## Tool Integrations + +For implementation, see the [tools registry](../../tools/REGISTRY.md). Key SMS tools: + +| Tool | Best For | MCP | Guide | +|------|----------|:---:|-------| +| **Klaviyo** | E-commerce email + SMS combined | ✓ | [klaviyo.md](../../tools/integrations/klaviyo.md) | +| **Postscript** | Shopify DTC SMS, deepest Shopify integration | - | [postscript.md](../../tools/integrations/postscript.md) | +| **Attentive** | Mid-market+ DTC SMS, full-service | - | [attentive.md](../../tools/integrations/attentive.md) | +| **Twilio** | Raw API for custom builds, transactional, dev-first | - | [twilio.md](../../tools/integrations/twilio.md) | +| **Plivo** | Twilio alternative, lower per-send cost | - | [plivo.md](../../tools/integrations/plivo.md) | +| **AudienceTap** | AI-forward DTC, on-pack QR opt-in | - | [audiencetap.md](../../tools/integrations/audiencetap.md) | +| **Brevo** | EU email + SMS, SMB-friendly | ✓ | [brevo.md](../../tools/integrations/brevo.md) | +| **Customer.io** | Behavior-based SMS automation | - | [customer-io.md](../../tools/integrations/customer-io.md) | + +--- + +## Related Skills + +- **emails**: Sister channel — almost always run together. Email carries the long-form content; SMS carries the urgent nudges. +- **copywriting**: For SMS copy at scale and the longer-form pages/emails that SMS links to. +- **popups**: For phone number capture popups on-site. +- **churn-prevention**: For win-back flows that combine SMS + email. +- **onboarding**: For post-signup SMS milestone nudges. +- **analytics**: For attribution and RPS measurement. +- **ab-testing**: For SMS-specific test design. +- **lead-magnets**: For incentivizing opt-in (the "10% off for joining" offer). diff --git a/skills/sms/evals/evals.json b/skills/sms/evals/evals.json new file mode 100644 index 0000000..1bdaf62 --- /dev/null +++ b/skills/sms/evals/evals.json @@ -0,0 +1,100 @@ +{ + "skill_name": "sms", + "evals": [ + { + "id": 1, + "prompt": "We're a Shopify DTC brand doing $5M/year in skincare. We have 80K email subscribers but no SMS program yet. Where do we start?", + "expected_output": "Should check for product-marketing.md first. Should run Phase 0 compliance check: are they US-based, is A2P 10DLC registration started, is the opt-in mechanism planned. Should recommend Klaviyo SMS or Postscript given Shopify + DTC ecom (Klaviyo if already on Klaviyo email, Postscript for SMS-first depth). Should rank flows by ROI for skincare: (1) abandoned cart sequence first (highest-ROI flow), (2) post-purchase + replenishment (skincare has predictable cycles), (3) welcome opt-in flow with capture incentive, (4) win-back at 60-90 days. Should warn about treating SMS like email (frequency cap, relevance bar, real per-send cost ~$0.0075-$0.04). Should reference compliance.md for opt-in disclosure language and quiet hours.", + "assertions": [ + "Checks for product-marketing.md", + "Runs compliance/A2P 10DLC readiness check", + "Recommends Klaviyo SMS or Postscript with rationale", + "Prioritizes abandoned cart as highest-ROI flow", + "Mentions replenishment for skincare specifically", + "Warns about treating SMS like email", + "References compliance.md or opt-in disclosure requirements", + "Mentions per-send cost economics" + ], + "files": [] + }, + { + "id": 2, + "prompt": "Write me an abandoned cart SMS sequence. We sell custom apparel, average order $80.", + "expected_output": "Should output a 3-message sequence following references/sequence-templates.md pattern. Should specify timing: Send 1 at 30 min after abandon (no discount, gentle reminder), Send 2 at 4 hours (soft urgency, no discount), Send 3 at 24 hours (discount allowed). Should include actual SMS copy with character counts (target 160 GSM-7 for 1 segment). Each message must start with sender ID 'From [Brand]:', have a single CTA + short link, and the first message should include 'Reply STOP to opt out' compliance footer. Should warn against discount on first send (trains customers to abandon). Should mention exclusion rules: stop sequence on purchase, opt-out, or 48 hours elapsed. Should recommend UTM tagging for attribution and cross-reference analytics skill for measurement.", + "assertions": [ + "Outputs 3-message sequence with timing", + "Send 1 at 30 min, Send 2 at 4 hours, Send 3 at 24 hours", + "No discount on Send 1", + "Each message has sender ID + single CTA + short link", + "Character counts shown, target ~160 GSM-7", + "Compliance footer on first send (STOP to opt out)", + "Warns about discount on first send", + "Mentions exclusion rules", + "Mentions UTM tagging or attribution" + ], + "files": [] + }, + { + "id": 3, + "prompt": "Can I just send SMS without any opt-in if customers gave me their phone number at checkout?", + "expected_output": "Should refuse and explain TCPA requires express written consent for marketing SMS. Should distinguish marketing SMS (requires express written consent) from transactional/account SMS (order updates, auth — implied consent during transaction OK if directly related). Should explain the express written consent requirements: clear disclosure adjacent to the phone field, frequency expectation, msg & data rates notice, STOP/HELP instructions, terms link, electronically captured with timestamp. Should mention penalty exposure: $500-$1,500 per message, class actions reach 7-8 figures. Should recommend implementing a compliant opt-in flow: checkbox + disclosure text, double opt-in optional but cleaner. Should reference compliance.md for the full disclosure template. Should warn that 'customers gave their number at checkout' is NOT sufficient for marketing SMS — it's only sufficient for the specific transaction's communications.", + "assertions": [ + "Refuses the no-opt-in approach", + "Distinguishes marketing SMS from transactional SMS", + "Lists express written consent requirements", + "Mentions TCPA penalty exposure ($500-$1,500 per message)", + "Mentions class action risk", + "Recommends compliant opt-in flow", + "References compliance.md", + "Clarifies checkout phone capture is not marketing consent" + ], + "files": [] + }, + { + "id": 4, + "prompt": "Our SMS list is 50K subscribers. We send 3 promotional messages per week. Opt-out rate has crept up to 4% per send. What's wrong?", + "expected_output": "Should diagnose this as audience fatigue from over-sending. Should reference healthy benchmarks: opt-out rate should be <2% per send and <0.5% for promotional sends — 4% is significantly elevated. Should review send frequency: 3 promotional sends/week is on the high side; recommend reducing to 1-2/week, especially for newer subscribers. Should audit relevance: are sends segmented or going to entire list? Generic blasts to a 50K list will burn out the inactive 30K. Should recommend segmenting by engagement (recently engaged vs cold), purchase recency, and opt-in source. Should suggest reactivating cold subscribers with a re-engagement flow before sending more promos. Should warn that 4% opt-out per send means the list is being destroyed at the rate of ~2K/week. Should cross-reference analytics for proper measurement and the principle 'every send must justify itself.'", + "assertions": [ + "Diagnoses as over-sending / audience fatigue", + "Cites healthy benchmark (<2% opt-out per send, <0.5% promotional)", + "Recommends reducing send frequency", + "Recommends segmentation by engagement", + "Suggests reactivation flow for cold subscribers", + "Calculates list erosion impact", + "Mentions 'every send must justify itself' principle" + ], + "files": [] + }, + { + "id": 5, + "prompt": "We just submitted our A2P 10DLC registration and our sends are working. Can we start scaling to 100K+ messages per day?", + "expected_output": "Should ask about phone number type currently in use: 10DLC, toll-free, or short code. Should explain throughput limits: 10DLC standard brand ~4-10 msg/sec, verified brand ~75-100+ msg/sec, toll-free ~3 msg/sec, short code 100+ msg/sec. Should calculate: 100K msgs at 10 msg/sec = ~2.8 hours of continuous send time, may run into quiet hour cutoff. Should recommend short code lease for 100K+/day sustained volume. Should warn about carrier filtering on burst sends — use platform throttling. Should mention that sample message text from A2P registration must match actual sends or carriers will flag. Should recommend monitoring trust score and deliverability dashboards. Should reference platforms.md for short code provisioning details.", + "assertions": [ + "Asks about phone number type (10DLC vs toll-free vs short code)", + "Explains throughput limits with specific msg/sec numbers", + "Calculates time-to-send for 100K volume", + "Mentions quiet hour considerations", + "Recommends short code for high sustained volume", + "Warns about carrier filtering / throttling", + "Mentions A2P sample text alignment requirement", + "References platforms.md or trust score monitoring" + ], + "files": [] + }, + { + "id": 6, + "prompt": "Should we put emojis in our SMS messages? Other brands seem to use them a lot.", + "expected_output": "Should explain the cost trade-off: emojis force UCS-2 encoding, which cuts segment size from 160 GSM-7 chars to 70 chars. A 100-char message with one emoji becomes 2 segments billed instead of 1 — effectively doubling the per-send cost. Should advise: 1 emoji per message max, situationally relevant, only when the emoji genuinely earns its segment cost (high-energy promotional, brand-personality fit, etc.). Should warn against emoji clutter — it signals 'mass send' rather than personal. Should note that some accented characters (curly quotes, em dashes) also force UCS-2 — copy-pasting from Word/Google Docs is a common silent cause of doubled costs. Should recommend testing in the platform's preview to verify segment count before scheduling. Should remind that segment count matters at scale: 100K sends at 2 segments instead of 1 = $750-$4,000 in extra cost per campaign.", + "assertions": [ + "Explains UCS-2 encoding cost", + "Specifies 160 GSM-7 vs 70 UCS-2 segment sizes", + "Recommends max 1 emoji per message", + "Warns about doubled per-send cost", + "Mentions accented characters / curly quotes also trigger UCS-2", + "Recommends previewing segment count", + "Calculates cost impact at scale" + ], + "files": [] + } + ] +} diff --git a/skills/sms/references/compliance.md b/skills/sms/references/compliance.md new file mode 100644 index 0000000..d80c225 --- /dev/null +++ b/skills/sms/references/compliance.md @@ -0,0 +1,202 @@ +# SMS Compliance Reference + +Comprehensive compliance reference for SMS marketing across major jurisdictions, opt-in copy templates, and STOP/HELP response templates. + +> This is operational guidance, not legal advice. For high-volume programs (50K+ subscribers) or any program with non-trivial revenue, run your compliance setup past a TCPA-experienced attorney. + +--- + +## United States — TCPA + +### What it is + +The Telephone Consumer Protection Act (1991, amended) regulates marketing calls and texts. The FCC enforces it; private plaintiffs sue under it. Statutory damages: $500–$1,500 **per message**. Class actions easily reach 7–8 figures. + +### Consent tiers + +| Type | What it covers | How to capture | +|------|---------------|----------------| +| **Express written consent** | Marketing SMS (sales, promotions, offers) | Checkbox + clear disclosure language, captured electronically with timestamp | +| **Express consent (non-written)** | Informational/transactional (delivery, account alerts) | Phone number provided during transaction with awareness it'll be used to text | +| **Established business relationship** | NOT sufficient for marketing SMS | Doesn't apply | + +### Express written consent requirements + +The opt-in flow must capture all of: + +1. The recipient agreed to receive marketing SMS from your brand +2. The recipient understands consent is not a condition of purchase +3. The disclosure showed frequency expectation, message and data rate notice, STOP/HELP instructions, terms link +4. The agreement was electronically recorded with timestamp + +### Opt-in disclosure template (compliant) + +``` +By signing up via text, you agree to receive recurring automated promotional and +personalized marketing text messages (e.g., cart reminders) from [Brand] at the +cell number used when signing up. Consent is not a condition of any purchase. +Reply HELP for help and STOP to cancel. Msg frequency varies. Msg & data rates +may apply. View [Terms](link) and [Privacy](link). +``` + +Place this **directly adjacent** to the phone number field and submit button. Do not bury it in a footer. + +### Quiet hours + +- **Federal**: 8am–9pm in the recipient's local time zone +- **Stricter states**: Florida (8am–8pm), Oklahoma (8am–8pm), Washington (8am–8pm) +- **Carrier-recommended**: 9am–8pm recipient-local +- **Practical default**: 9am–8pm recipient-local for safety + +Time zone is determined by area code, but area codes lie (people move). Major platforms (Klaviyo, Postscript, Attentive) handle this automatically; verify yours does. + +### STOP/HELP handling + +**STOP variants you must honor**: STOP, END, CANCEL, UNSUBSCRIBE, QUIT, STOPALL, OPTOUT + +**STOP response** (after STOP received): +``` +You're unsubscribed from [Brand] alerts. No more messages will be sent. Reply HELP for help. +``` + +**HELP variants**: HELP, INFO + +**HELP response**: +``` +[Brand] alerts: For help, visit [URL] or email [support@brand.com]. Msg & data rates may apply. Reply STOP to cancel. +``` + +**Critical rules**: +- Honor STOP **within seconds**, every time, every keyword variant +- Do not require the recipient to log in or visit a website to opt out +- One STOP confirmation is allowed; do not send additional messages after +- HELP responses do not count as marketing messages and are not subject to quiet hours + +### Sample TCPA-compliant footer language by sequence type + +- **Opt-in confirmation**: "Reply HELP for help, STOP to cancel. Msg & data rates may apply." — required +- **Recurring promotional**: "Reply STOP to opt out" — required quarterly minimum; carrier-recommended every send +- **Transactional**: Not required by TCPA but carriers expect it; include for safety + +--- + +## United States — A2P 10DLC + +### What it is + +Application-to-Person 10-Digit Long Code registration, run by The Campaign Registry (TCR). Required for businesses sending SMS through 10DLC numbers (regular long codes) since 2022. Carriers (T-Mobile, AT&T, Verizon) enforce this; unregistered traffic gets throttled or blocked. + +### Registration components + +1. **Brand registration** + - Legal entity name, EIN, business type + - Trust score assigned (Standard or Verified) + - Higher trust = better throughput, lower fees + +2. **Campaign registration** (one per use case) + - Use case: Marketing, Account Notification, Customer Care, Public Service, Higher Education, Polling and Voting, 2FA, Delivery Notification, etc. + - Sample message text (must match what you actually send) + - Opt-in flow description and screenshot + - Opt-out language + - Help message language + - Volume estimate + +3. **Phone number assignment** to campaigns + +### Throughput tiers (varies by carrier and trust score) + +| Trust score + use case | Throughput | +|------------------------|-----------| +| Verified brand, marketing | 75–100+ msg/sec | +| Standard brand, marketing | 4–10 msg/sec | +| Unregistered | 0.1 msg/sec or blocked | + +### Common rejections + +- Sample message text doesn't match actual sends +- Opt-in flow screenshot doesn't show required disclosure language +- "SHAFT" content (Sex, Hate, Alcohol, Firearms, Tobacco) without explicit use case +- Generic or vague campaign descriptions + +**Process time**: 1–7 business days. Plan for this in launch timelines. + +--- + +## EU / UK — GDPR + ePrivacy Directive + +### Consent requirements + +- **Explicit opt-in**: clear affirmative action (no pre-checked boxes) +- **Specific**: opt-in must be for marketing SMS specifically, separate from generic ToS +- **Informed**: data subject must know who's processing and why +- **Freely given**: can't be bundled with service access + +### Mandatory provisions + +- Sender identity in every message +- Easy opt-out in every message +- Right to access data (DSARs) +- Right to deletion +- Records of consent kept for the duration of processing + statute of limitations + +### Penalty exposure + +GDPR fines up to €20M or 4% of global revenue, whichever is higher. + +--- + +## Canada — CASL + +### Consent + +- **Express consent**: explicit opt-in (same standard as US TCPA express written consent) +- **Implied consent**: existing business relationship within 24 months — limited use, expires + +### Every message must include + +- Sender identification (legal name + any operating names) +- Mailing address +- Phone, email, or website contact +- Unsubscribe mechanism that works within 10 business days + +### Penalty exposure + +Up to CAD $10M per violation. Enforced by the CRTC. + +--- + +## Australia — Spam Act 2003 + +- Express or inferred consent (inferred has narrow application) +- Sender ID required +- Functional unsubscribe required +- Enforced by ACMA + +--- + +## Multi-jurisdictional programs + +If you send across US + EU + Canada simultaneously: + +- Default to the **strictest** standard across all jurisdictions (US TCPA express written consent + GDPR explicit opt-in) +- Track consent jurisdiction per subscriber +- Default quiet hours to recipient-local 9am–8pm +- Include all required identifiers in every message + +--- + +## Audit-ready compliance checklist + +- [ ] A2P 10DLC registration complete (US, if applicable) +- [ ] Opt-in flow includes all required disclosures, adjacent to phone field +- [ ] Disclosure text matches A2P registered sample messages +- [ ] Opt-in event captures: timestamp, IP, page URL, exact disclosure shown +- [ ] STOP/HELP keywords honored across all variants +- [ ] Quiet hours enforced at platform level (recipient-local time) +- [ ] Privacy policy includes SMS section +- [ ] Terms of service include SMS terms +- [ ] Consent records retained per applicable law (typically 4+ years US, longer EU) +- [ ] Process for handling DSARs (EU) and consent revocation +- [ ] Sender identity in every message +- [ ] Compliance footer on every promotional message (recommended) or quarterly minimum (required) +- [ ] Test STOP/HELP from a real phone number quarterly to verify it still works diff --git a/skills/sms/references/platforms.md b/skills/sms/references/platforms.md new file mode 100644 index 0000000..2bb1135 --- /dev/null +++ b/skills/sms/references/platforms.md @@ -0,0 +1,318 @@ +# SMS Platform Reference + +Deep-dive on the major SMS marketing platforms — features, pricing, A2P 10DLC support, and integration paths. + +> Pricing is approximate and changes regularly. Always confirm at the vendor's site before committing. + +--- + +## Klaviyo SMS + +**Best for**: DTC ecom brands already using Klaviyo for email. + +### Key features +- Native integration with Klaviyo email and segmentation +- Shared subscriber profile across email + SMS +- Built-in A2P 10DLC registration +- Flow builder shared with email flows +- Conversational SMS (two-way) supported + +### Pricing +- Bundled with Klaviyo plans, billed per SMS credit +- US: ~$0.0075–$0.015 per SMS; MMS ~$0.04 +- Free tier: 150 SMS credits/month on lower email tiers + +### Integration paths +- Direct Shopify, WooCommerce, BigCommerce, Magento integration +- API for custom platforms +- MCP server available + +### Compliance +- A2P 10DLC registration handled in-platform +- Toll-free and short code provisioning available (short code adds $1,000+/mo) +- Quiet hours enforced per recipient time zone (configurable) + +### Watch out for +- Email + SMS combined billing can spike fast on large lists +- Short code costs are real overhead; only worthwhile for 100K+ active SMS subscribers + +--- + +## Postscript + +**Best for**: Shopify-native DTC brands wanting SMS-specific tooling and onboarding support. + +### Key features +- Deep Shopify integration (the deepest of any SMS platform) +- Strong abandoned cart and browse abandonment automations +- AI Reply (auto-reply trained on brand voice) +- Conversational SMS / live agent +- Audiences pulled from Shopify customer data + +### Pricing +- Tiered plans: Starter (free, 1K msgs/mo), Growth ($100+/mo), Professional, Enterprise +- Pay-per-send adds on top: ~$0.015 per SMS, ~$0.04 per MMS + +### Integration paths +- Shopify-first; limited support for non-Shopify +- API + webhooks available + +### Compliance +- A2P 10DLC handled in-platform +- Strong opt-in compliance tools (popup builder, keyword opt-in) +- Quiet hours enforced + +### Watch out for +- Steep cost increase past Starter tier +- Less useful if you're not on Shopify + +--- + +## Attentive + +**Best for**: Mid-market and enterprise DTC brands wanting full-service SMS. + +### Key features +- Full-service: dedicated CSM, copy support, strategy +- Conversational SMS at scale +- Concierge sales-via-SMS +- Strong analytics and attribution +- Identity resolution (matching anon site visitors to phone numbers) + +### Pricing +- Custom contracts; typically $1K–$10K+/mo + per-send fees +- Annual contracts standard +- Pricing rarely makes sense for <50K SMS subscribers + +### Integration paths +- Shopify, BigCommerce, Salesforce Commerce Cloud, custom +- Robust API + +### Compliance +- Full A2P 10DLC managed +- Best-in-class compliance tooling and audit support +- Short code provisioning included on most plans + +### Watch out for +- Contract terms can lock you in for 12+ months +- Overkill for early-stage brands + +--- + +## Twilio + +**Best for**: Custom builds, transactional SMS, B2B SaaS embedding SMS into products, developers. + +### Key features +- Raw SMS API +- Pay-per-send pricing, no platform fees +- Massive global coverage (200+ countries) +- Programmable Voice, WhatsApp Business, RCS available alongside +- Studio (visual flow builder) for non-code automation + +### Pricing +- US 10DLC SMS: $0.0079 per message +- US toll-free SMS: $0.0079 per message +- US short code SMS: $0.0079 per message + $1,000/mo lease +- MMS: ~$0.02 +- Carrier surcharges layered on top (~$0.005 per US 10DLC) +- A2P 10DLC registration: ~$15 brand + $10/mo per campaign + +### Integration paths +- API-first (REST + SDKs in Node, Python, Ruby, Go, etc.) +- No native ecom integrations — you build them + +### Compliance +- A2P 10DLC registration in-platform but you do the work +- TwilioSendGrid (separate product) handles email-side compliance +- Quiet hours and STOP/HELP handling must be implemented by you + +### Watch out for +- You're responsible for compliance — no hand-holding +- No native segmentation, deliverability dashboards, or marketing UI +- Best paired with Customer.io, Segment, or a custom orchestration layer + +--- + +## Brevo (formerly Sendinblue) + +**Best for**: EU-based brands, email + SMS combo, SMB-friendly. + +### Key features +- Combined email + SMS + WhatsApp on one platform +- EU-headquartered, GDPR-native +- Generous free tier for email; SMS pay-per-send +- Marketing automation flows +- CRM included + +### Pricing +- Free tier: 300 emails/day; SMS pay-per-send +- US SMS: ~$0.015 per message +- EU SMS: varies by country, ~€0.04–€0.07 + +### Integration paths +- Direct integrations: Shopify, WooCommerce, WordPress, Magento +- API + Zapier +- MCP server available + +### Compliance +- GDPR + ePrivacy built-in +- A2P 10DLC for US (less polished than dedicated US platforms) + +### Watch out for +- US SMS features lag behind Klaviyo/Postscript +- Best if you're EU-first or already on Brevo for email + +--- + +## SimpleTexting + +**Best for**: SMB, services businesses, simple campaign blasts, low-volume. + +### Key features +- Easy-to-use UI +- Keyword opt-in for grassroots list building +- Built-in landing pages for opt-in +- Simple automation + +### Pricing +- Plans start ~$30/mo for 500 credits, scaling up +- US SMS only + +### Integration paths +- Zapier, Make, native to a few apps +- API available but basic + +### Compliance +- A2P 10DLC handled +- TCPA tooling + +### Watch out for +- Limited automation depth vs Klaviyo/Postscript +- Best for low-complexity, low-volume use cases (gyms, salons, real estate) + +--- + +## Plivo + +**Best for**: Custom SMS builds where per-send cost matters; Twilio-style API at a lower price point. + +### Key features +- Direct Twilio competitor with similar surface area +- Powerpack for bulk sending with sticky sender across number pools +- A2P 10DLC handled in-platform +- WhatsApp, voice available alongside SMS +- SDKs for major languages + +### Pricing +- US 10DLC SMS: ~$0.0055/msg (typically 20–30% under Twilio) +- US short code SMS: similar + monthly lease +- MMS: ~$0.02 +- Phone number rental: ~$0.80/mo local, ~$1/mo toll-free + +### Integration paths +- API-first (REST + SDKs) +- No native ecom integrations — you build them + +### Compliance +- A2P 10DLC managed in-platform +- Compliance plumbing (STOP/HELP, quiet hours) is your responsibility — same model as Twilio + +### Watch out for +- Smaller ecosystem than Twilio (fewer ancillary products, integrations, community resources) +- WhatsApp tooling less mature + +--- + +## AudienceTap + +**Best for**: DTC brands wanting AI-forward creative tooling or on-pack QR opt-in as a primary acquisition channel. + +> Newer platform — verify current capabilities, pricing, and API surface before committing. + +### Key features +- SMS + email on one platform (similar combined model to Klaviyo) +- AI creative generation (SMS copy, subject lines, image variants) +- On-pack QR code opt-in: insert cards in shipped orders that drive SMS list growth +- Shopify, BigCommerce, headless commerce integrations +- A2P 10DLC managed in-platform +- Identity resolution and segmentation + +### Pricing +- Tiered by subscriber count + send volume +- Per-send pricing comparable to other DTC SMS platforms + +### Integration paths +- API access on Growth+ tiers +- Direct ecom integrations +- Webhooks for events + +### Compliance +- A2P 10DLC handled in-platform +- TCPA tooling — verify enterprise-scale depth before committing for large lists + +### Watch out for +- Newer entrant — fewer reference customers, less battle-tested at high volume than incumbents +- Some features rolled out recently — confirm what's GA vs beta before relying on them + +--- + +## Customer.io + +**Best for**: B2B SaaS, behavior-based automation, multi-channel orchestration (email + SMS + push). + +### Key features +- Trigger SMS off product events (signup, milestone, churn risk) +- Powerful audience segmentation +- Workflow builder +- Real-time data sync via API/webhooks + +### Pricing +- Plans start ~$150/mo, scaling with profile count +- SMS via Twilio integration or native (varies) + +### Integration paths +- API-first +- Direct integrations with Segment, Heap, Mixpanel, etc. + +### Compliance +- A2P 10DLC via Twilio if using native integration +- Granular subscription/consent management + +### Watch out for +- Less ecom-tailored than Klaviyo/Postscript +- Best for product-led SaaS or apps with deep event tracking + +--- + +## Quick selection table + +| Stack / Goal | Recommended | Why | +|--------------|------------|-----| +| Shopify ecom, already on Klaviyo | **Klaviyo SMS** | One platform, one subscriber profile | +| Shopify ecom, SMS-first focus | **Postscript** | Deepest Shopify + SMS-specific features | +| Mid-market ecom, want concierge support | **Attentive** | Full-service team + tooling | +| Custom platform, B2B SaaS, transactional | **Twilio** | API-first, full control | +| Custom build, cost-sensitive | **Plivo** | ~20–30% cheaper than Twilio per send | +| DTC wanting AI creative or on-pack QR opt-in | **AudienceTap** | AI-forward; insert-card opt-in is unique | +| EU-based SMB | **Brevo** | GDPR-native, EU-friendly pricing | +| Local services SMB, simple campaigns | **SimpleTexting** | Easy UI, low overhead | +| Product-led SaaS with event tracking | **Customer.io** | Behavior-based triggers | + +--- + +## A2P 10DLC: what your platform should handle + +Whatever you pick, confirm your platform handles: + +- [ ] Brand and campaign registration with TCR +- [ ] Sample message text aligned with what you actually send +- [ ] Opt-in flow documentation submitted to carriers +- [ ] Trust score visibility (and a path to improve it) +- [ ] Throughput appropriate to your list size and send frequency +- [ ] STOP/HELP keyword handling +- [ ] Quiet hours by recipient time zone +- [ ] Suppression list management +- [ ] Consent record retention with timestamps + +All major platforms above handle these. Twilio does the lowest-level work and pushes more responsibility onto you. diff --git a/skills/sms/references/sequence-templates.md b/skills/sms/references/sequence-templates.md new file mode 100644 index 0000000..37764a2 --- /dev/null +++ b/skills/sms/references/sequence-templates.md @@ -0,0 +1,282 @@ +# SMS Sequence Templates + +Full copy templates with character counts, timing, and segmentation logic for every major SMS flow. + +> Character counts shown assume GSM-7 encoding. Emojis force UCS-2 (70 chars/segment instead of 160). All templates use `[Brand]`, `[FirstName]`, and `[short.link]` as substitution tokens. + +--- + +## Welcome / Opt-In Confirmation + +### Send 1 — Immediate (after opt-in) + +``` +From [Brand]: Welcome! Here's your 10% off code: WELCOME10. Shop now: [short.link] +Reply STOP to opt out, HELP for help. Msg & data rates may apply. +``` +~155 chars / 1 segment (just). Footer required on first send. + +### Send 2 — 24 hours later (optional) + +``` +From [Brand]: Don't forget your code WELCOME10 — expires in 48hrs. Top picks: [short.link] +``` +~108 chars / 1 segment. + +### Send 3 — 7 days later (optional, conditional on no purchase) + +``` +From [Brand]: Last chance for 10% off with WELCOME10. Expires tonight at midnight: [short.link] +``` +~107 chars / 1 segment. + +--- + +## Abandoned Cart (highest-ROI flow for ecom) + +### Send 1 — 30 minutes after abandon + +``` +From [Brand]: Hey [FirstName], you left something behind! Your cart's here: [short.link] +``` +~95 chars / 1 segment. + +### Send 2 — 4 hours after abandon (if no purchase) + +``` +From [Brand]: Items in your cart are selling fast. Reserved for you for 24hrs: [short.link] +``` +~98 chars / 1 segment. + +### Send 3 — 24 hours after abandon (if no purchase, discount allowed) + +``` +From [Brand]: Still thinking? Here's 10% off to seal the deal: SAVE10. Shop: [short.link] +``` +~99 chars / 1 segment. + +**Notes**: +- Discount on Send 1 trains customers to abandon. Reserve for Send 2 or 3. +- Exclude customers who abandoned <$X in cart value or repeat abandoners (gaming the discount). +- Stop sequence on purchase, opt-out, or 48 hours elapsed. + +--- + +## Browse Abandonment + +### Send 1 — 1 hour after browse (single product or category) + +``` +From [Brand]: Still thinking about [product]? Take another look: [short.link] +``` +~84 chars / 1 segment. + +**Notes**: +- Trigger only after meaningful browse signal (3+ product views or 2+ min on product page). +- Exclude if a purchase happened on a different product. + +--- + +## Post-Purchase Flow + +### Send 1 — Immediately after purchase (transactional, separate consent) + +``` +From [Brand]: Order #12345 confirmed! We'll text shipping updates here. Track: [short.link] +``` +~95 chars / 1 segment. + +### Send 2 — Day of shipment + +``` +From [Brand]: Your order's on the way. Estimated delivery: [date]. Track: [short.link] +``` +~92 chars / 1 segment. + +### Send 3 — Day of delivery + +``` +From [Brand]: Your order should arrive today! Questions? Reply or visit [short.link] +``` +~88 chars / 1 segment. + +### Send 4 — 2 days after delivery (marketing consent required) + +``` +From [Brand]: How are you liking your [product]? Share a review for 15% off next order: [short.link] +``` +~108 chars / 1 segment. + +### Send 5 — 14 days after delivery (cross-sell, marketing consent) + +``` +From [Brand]: Goes great with your [product]: [related-item]. 10% off bundle: [short.link] +``` +~99 chars / 1 segment. + +--- + +## Win-Back (Lapsed Customers) + +### Send 1 — 60-90 days after last purchase + +``` +From [Brand]: [FirstName], we miss you! Picks we think you'll love: [short.link] +``` +~84 chars / 1 segment. + +### Send 2 — 14 days later (if no purchase) + +``` +From [Brand]: Come back for 15% off your next order: COMEBACK15. Expires in 7 days: [short.link] +``` +~106 chars / 1 segment. + +### Send 3 — 14 days after Send 2 (final, if no purchase) + +``` +From [Brand]: Last chance — 20% off ends tonight: COMEBACK20. We'll stop texting if you'd rather: reply STOP. [short.link] +``` +~130 chars / 1 segment. + +**Notes**: +- After Send 3 with no engagement, suppress for 90 days minimum. +- After two full win-back cycles with no engagement, sunset (remove from active list). + +--- + +## Promotional / Campaign Sends + +### Flash sale (single send) + +``` +From [Brand]: 24-HOUR FLASH: 25% off everything with FLASH25. Ends midnight: [short.link] +``` +~94 chars / 1 segment. + +### Limited drop / launch + +``` +From [Brand]: New drop just landed: [product-name]. Limited stock, members get early access: [short.link] +``` +~115 chars / 1 segment. + +### Holiday / BFCM (2-send sequence) + +Send 1 — Day of launch: +``` +From [Brand]: Black Friday is LIVE — up to 50% off sitewide. Shop now: [short.link] +``` +~92 chars / 1 segment. + +Send 2 — Day of (or evening, expiration push): +``` +From [Brand]: Last 6 hours of BFCM savings. Don't miss out: [short.link] +``` +~73 chars / 1 segment. + +--- + +## Transactional / Account Notifications + +### Order confirmation + +``` +[Brand]: Order #12345 confirmed. Total $XX.XX. Track at [short.link]. Reply HELP for help. +``` + +### Shipping update + +``` +[Brand]: Your order #12345 shipped! Track: [short.link]. ETA [date]. +``` + +### Delivery confirmation + +``` +[Brand]: Order #12345 delivered. Enjoy! Issues? Reply or [support-link]. +``` + +### Auth code (2FA) + +``` +[Brand] verification code: 123456. Expires in 10 min. Do not share. +``` + +### Account alert + +``` +[Brand]: Sign-in from new device in [location]. Wasn't you? Secure: [short.link] +``` + +--- + +## Re-Engagement / Reactivation (Subscribers Who've Gone Cold) + +For SMS subscribers who haven't engaged with any send in 60+ days. + +### Send 1 — Soft reactivation + +``` +From [Brand]: We've missed you, [FirstName]! Here's what's new: [short.link] +``` +~80 chars / 1 segment. + +### Send 2 — Confirm interest (if no engagement) + +``` +From [Brand]: Want to keep hearing from us? Reply YES to stay on the list, or STOP to opt out. +``` +~98 chars / 1 segment. + +After no reply: suppress for 60 days, then remove from active list. This protects opt-out rate metrics and reduces wasted spend. + +--- + +## Replenishment (Consumables Ecom) + +For products with predictable usage cycles (skincare, supplements, coffee, pet food). + +### Send 1 — At expected reorder window (e.g., 28 days for a 30-day supply) + +``` +From [Brand]: Running low on [product]? Reorder in one tap: [short.link] +``` +~73 chars / 1 segment. + +### Send 2 — 7 days later (if no purchase) + +``` +From [Brand]: Don't run out! 10% off your reorder of [product]: REFILL10 [short.link] +``` +~92 chars / 1 segment. + +--- + +## VIP / Loyalty Members + +Higher frequency, exclusive offers, early access — different cadence rules apply but quiet hours and STOP still required. + +### Early access + +``` +From [Brand]: VIPs get the new drop 24hrs early. Yours now: [short.link] +``` +~72 chars / 1 segment. + +### Loyalty milestone + +``` +From [Brand]: You've reached Gold status! Your perks: 15% off + free shipping. [short.link] +``` +~95 chars / 1 segment. + +--- + +## Segmentation rules across all flows + +- **Suppress** customers in active sequences from promotional sends (no double-tap) +- **Suppress** opted-out subscribers from everything (platform handles this) +- **Frequency cap**: max 4–6 marketing sends/week per subscriber (lower for newer subscribers) +- **Quiet hours**: 9am–8pm recipient-local time +- **Cool-off**: After a discount-driven purchase, suppress promotional sends for 14 days diff --git a/skills/video/SKILL.md b/skills/video/SKILL.md index 06dcdfa..1750ada 100644 --- a/skills/video/SKILL.md +++ b/skills/video/SKILL.md @@ -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,' 'Runway,' 'Kling,' 'Pika,' '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,' 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.0 + version: 2.0.1 --- # Video @@ -41,7 +41,7 @@ Pick the right tool for the job: | Approach | Best For | Tools | When to Use | |----------|----------|-------|-------------| | **Programmatic** | Templated, data-driven, batch video | Remotion, Hyperframes | Product updates, personalized videos, recurring content | -| **AI Generation** | Original footage from text/image prompts | Veo, Runway, Kling, Pika | B-roll, hero shots, creative visuals you can't film | +| **AI Generation** | Original footage from text/image prompts | Veo 3, Sora 2, Runway, Kling, Seedance | B-roll, hero shots, creative visuals you can't film | | **AI Avatars** | Talking-head presenter without filming | HeyGen, Synthesia | Explainers, tutorials, multilingual content | | **Editing/Repurposing** | Cutting long-form into short clips | Descript, Opus Clip, CapCut | Podcast/webinar → social clips | @@ -130,12 +130,22 @@ Generate original footage from text or image prompts. Use for B-roll, hero visua | Model | Resolution | Max Duration | Best For | Cost | |-------|-----------|-------------|----------|------| -| **Veo 3** (Google) | Up to 1080p (4K varies) | Variable | Highest quality, synced audio | API-based | -| **Runway Gen-4** | Up to 4K | ~10 sec/gen | Motion control, temporal consistency | $12-76/mo | -| **Kling 3.0** | Up to 1080p | Up to 2 min | Volume production, lowest cost | $0.029/sec | -| **Pika** | 1080p | Short clips | Fast generation, effects | Per-credit | - -**Sora (OpenAI)** has had limited availability and reliability issues. Check current status before recommending. +| **Veo 3** (Google) | Up to 1080p (4K varies) | Variable | Top overall quality, synced audio | API-based | +| **Sora 2** (OpenAI) | Up to 1080p | Up to ~20 sec | Cinematic + synced audio, ChatGPT/API integration | API + ChatGPT | +| **Runway Gen-4** | Up to 4K | ~10 sec/gen | Motion control, temporal consistency, edit-style workflows | $12-76/mo | +| **Kling 2.5/3.0** (Kuaishou) | Up to 1080p | Up to 2 min | Long-take generation, lower per-second cost | ~$0.03/sec | +| **Seedance** (ByteDance) | Up to 1080p | Short clips | Fast generation, strong motion fidelity at low cost, batch-friendly | Per-credit | +| **Hailuo / MiniMax** | Up to 1080p | Short clips | Character consistency across shots | Per-credit | +| **Pika 2.x** | 1080p | Short clips | Quick effects, image-to-video, lower bar to entry | Per-credit | +| **Hunyuan Video / Wan 2** | 720p–1080p | Variable | Open-source self-hosted; full control, no API fees | Free (GPU) | + +**Quick picks**: +- **Highest quality + audio**: Veo 3 or Sora 2 +- **Batch / volume / cost**: Kling, Seedance +- **Character consistency across multiple shots**: Hailuo +- **Self-hosted, brand-controlled**: Hunyuan Video or Wan 2 (open weights) +- **Storyboard → video workflow**: Runway, LTX Studio +- **Image-to-video from a still you already have**: Kling, Pika, Runway ### Prompting for Video Models diff --git a/skills/video/evals/evals.json b/skills/video/evals/evals.json new file mode 100644 index 0000000..99a3dd8 --- /dev/null +++ b/skills/video/evals/evals.json @@ -0,0 +1,88 @@ +{ + "skill_name": "video", + "evals": [ + { + "id": 1, + "prompt": "We need a 2-minute product demo video for our SaaS homepage. What's the fastest way to produce it?", + "expected_output": "Should check for product-marketing.md first. Should walk through the Product Demo Video workflow: script the key features and value props (cross-reference copywriting skill), screen record the product flow, programmatic overlay with Hyperframes or Remotion for titles/callouts/transitions, optional AI B-roll with Veo/Runway for establishing shots, voiceover via recording or AI avatar (HeyGen) for narration, export at platform-appropriate specs (16:9 for homepage). Should recommend Hyperframes for agent-friendliness (plain HTML, no React DSL). Should remind: don't use AI for product UI screens (models hallucinate UI) — use real screen recording. Should mention captions are essential (85% of social video watched without sound — applies to homepage too).", + "assertions": [ + "Checks for product-marketing.md", + "Walks through Product Demo workflow steps", + "Uses real screen recording, not AI generated UI", + "Recommends programmatic overlay tool", + "Mentions captions", + "Cross-references copywriting skill" + ], + "files": [] + }, + { + "id": 2, + "prompt": "We want to make weekly product update videos. About 60 seconds each. Don't want to be on camera. Recommend a setup.", + "expected_output": "Should recommend an AI avatar workflow given recurring weekly cadence and no-camera preference. Should recommend HeyGen specifically: best lip-sync, has an MCP server (so agents can generate videos directly), 230+ avatars, 140+ languages, Creator plan supports unlimited 5-minute videos. Should explain custom avatars (upload 2-5 min of yourself for a digital twin) as an option for brand consistency. Should outline the recurring pipeline: script written from product context, HeyGen generates avatar video, optional programmatic overlay with Hyperframes for UI screenshots/callouts, export and distribute. Should mention this is exactly the case where AI avatars shine vs other approaches (recurring content, multilingual versions, personalized outreach at scale). Should warn: if authentic founder content matters more than scale, film yourself instead.", + "assertions": [ + "Recommends AI avatar approach", + "Names HeyGen specifically", + "Mentions HeyGen MCP server for agents", + "Mentions custom avatars option", + "Identifies as a recurring use case", + "Warns about authenticity tradeoff" + ], + "files": [] + }, + { + "id": 3, + "prompt": "I want to generate a 10-second clip of a person typing on a laptop in a coffee shop for our landing page. Which AI tool?", + "expected_output": "Should apply the AI Video Generation model comparison. Should recommend Veo 3 for highest quality with synced audio, Runway Gen-4 for motion control and temporal consistency (~10 sec/gen sweet spot), or Kling 3.0 for lower-cost volume production. Should give a structured video prompt example following Subject + Action + Camera + Style + Mood pattern: 'A close-up shot of hands typing on a laptop keyboard in a cozy coffee shop, shallow depth of field, warm afternoon lighting through a window, camera holds steady, cinematic color grading, 4K.' Should warn about common mistakes: too vague, ignoring camera movement, forgetting style, requesting readable text. Should mention Sora has had limited availability — check current status.", + "assertions": [ + "Compares Veo, Runway, and Kling", + "Provides structured video prompt example", + "Follows Subject + Action + Camera + Style + Mood pattern", + "Warns about common prompt mistakes", + "Notes Sora reliability caveats" + ], + "files": [] + }, + { + "id": 4, + "prompt": "We just did a 60-minute webinar. How do we get short clips out of it for social?", + "expected_output": "Should apply the Repurposing Workflow: long-form content → Descript (clean up, remove filler, polish) → Opus Clip (auto-extract 5-10 best moments, scores virality potential) → CapCut (add captions, effects, platform styling) → distribute to TikTok, Reels, Shorts, LinkedIn. Should explain when to use each tool: Descript for transcript-based editing, Opus Clip for finding the best moments at scale, CapCut for platform-native polish, Captions.ai for auto-captions and eye-contact correction if needed. Should mention 85% of social video is watched without sound — captions are essential. Should mention aspect ratio matters: 9:16 for TikTok/Reels/Shorts, 1:1 or 9:16 for LinkedIn. Should recommend hooking in the first 3 seconds — cross-reference social skill.", + "assertions": [ + "Applies repurposing workflow", + "Names Descript, Opus Clip, CapCut in sequence", + "Mentions captions essential", + "Specifies aspect ratios per platform", + "Mentions hooking in first 3 seconds", + "May cross-reference social skill" + ], + "files": [] + }, + { + "id": 5, + "prompt": "We need to generate 50 personalized intro videos for sales outreach. Each one mentions a different company name and pain point.", + "expected_output": "Should recommend an agent-native pipeline combining HeyGen MCP (or API) for the avatar narration + Hyperframes for any visual overlays. Should explain: prepare a master script template with variables, run a loop generating 50 HeyGen videos each with a personalized script, optional programmatic overlays via Hyperframes for company logo or visual context. Should note HeyGen is well-suited to personalized outreach at scale and has an MCP server. Should warn about quality tradeoffs at volume and recommend testing the first 5 manually before generating all 50. Should mention reply tracking to measure ROI vs cold text emails — these are expensive to produce so should outperform email significantly to justify the effort. Should mention captions for the videos.", + "assertions": [ + "Recommends HeyGen + Hyperframes pipeline", + "Names HeyGen MCP server", + "Suggests template + loop approach", + "Recommends testing 5 manually first", + "Mentions reply tracking / ROI", + "Mentions captions" + ], + "files": [] + }, + { + "id": 6, + "prompt": "Should I use Hyperframes or Remotion for programmatic video?", + "expected_output": "Should compare the two based on the When to Pick Which table. Should recommend Hyperframes if: agent-driven (plain HTML/CSS, no React DSL — AI models generate better HTML than React components), minimal learning curve, basic animation needs, local rendering is fine, want Apache 2.0 license. Should recommend Remotion if: already a React shop, need complex animations (Spring, interpolate), need large-scale batch rendering via Lambda for AWS scale, can handle the React + Remotion API learning curve, comfortable with the company license for commercial use. Should note Hyperframes is from HeyGen and LLM-native by design. Should ask about the user's tech stack and animation complexity to recommend a final choice.", + "assertions": [ + "Compares the two with the When to Pick Which table", + "Notes Hyperframes uses plain HTML/CSS", + "Notes Remotion supports Lambda for scale", + "Mentions Apache 2.0 vs company license", + "Recommends Hyperframes for agent-driven workflows", + "Asks about stack or animation needs" + ], + "files": [] + } + ] +} diff --git a/skills/video/references/ai-video-prompting.md b/skills/video/references/ai-video-prompting.md new file mode 100644 index 0000000..3fc3a19 --- /dev/null +++ b/skills/video/references/ai-video-prompting.md @@ -0,0 +1,175 @@ +# AI Video Prompting Guide + +How to write effective prompts for AI video generation models (Veo, Runway, Kling, Pika). + +--- + +## Prompt Structure + +A strong video prompt follows this formula: + +``` +[Subject] + [Action] + [Camera movement] + [Visual style] + [Lighting/mood] + [Technical specs] +``` + +### Example Prompts by Use Case + +**Product hero shot:** +``` +A sleek laptop on a minimal white desk, screen glowing with a dashboard UI, +camera slowly orbits 180 degrees around the desk, +soft volumetric lighting from the left, shallow depth of field, +cinematic commercial aesthetic, 4K +``` + +**Lifestyle B-roll:** +``` +A woman in a modern co-working space smiling while looking at her phone, +natural window light, candid documentary feel, +camera handheld with subtle movement, warm color grading +``` + +**Abstract/brand:** +``` +Flowing liquid gold particles forming the shape of a network graph, +dark background, particles catch light as they move, +slow-motion macro photography style, dramatic rim lighting +``` + +**SaaS explainer scene:** +``` +An overhead shot of a team around a conference table pointing at charts, +camera slowly pushes in, bright modern office, +clean corporate style, even lighting, 1080p +``` + +--- + +## Camera Movement Vocabulary + +Use these terms — video models understand them: + +| Term | Effect | +|------|--------| +| **Static** | Locked camera, no movement | +| **Pan left/right** | Camera rotates horizontally | +| **Tilt up/down** | Camera rotates vertically | +| **Dolly in/out** | Camera moves toward/away from subject | +| **Orbit** | Camera circles around subject | +| **Tracking shot** | Camera follows moving subject | +| **Crane/aerial** | Camera rises or descends | +| **Handheld** | Subtle shake, documentary feel | +| **Zoom** | Lens zoom (different from dolly) | +| **Slow push** | Gradual dolly in — builds tension/focus | + +--- + +## Style Keywords + +### Cinematic +- "cinematic color grading" +- "anamorphic lens flare" +- "shallow depth of field" +- "film grain" +- "35mm film" + +### Commercial/Corporate +- "clean commercial lighting" +- "bright and airy" +- "professional corporate aesthetic" +- "even, diffused lighting" + +### Documentary +- "handheld documentary style" +- "natural lighting" +- "candid, unposed" +- "observational camera" + +### Social/Trendy +- "vertical 9:16" +- "fast-paced cuts" +- "bold text overlays" +- "high contrast, saturated colors" + +--- + +## Model-Specific Tips + +### Veo (Google) + +- Excels at photorealism and complex scenes +- Supports audio generation synced to video +- Best with detailed, descriptive prompts +- Specify "high resolution" or "1080p" for best quality +- Can handle multiple subjects and scene transitions + +### Runway Gen-4 + +- Strong motion control — specify camera movements precisely +- Best temporal consistency (subjects stay consistent across frames) +- Use motion brush for specific area animation +- Image-to-video works well — provide a reference frame +- Keep prompts under 100 words for best results + +### Kling + +- Can generate up to 2 minutes (much longer than others) +- Good for longer narrative sequences +- More affordable for bulk generation +- Quality drops slightly at longer durations +- Best with simpler scenes and fewer subjects + +### Pika + +- Fastest generation time (under 2 minutes) +- Good for quick iterations and experimentation +- Effects mode adds motion to still images +- Best for short clips (5-15 seconds) +- Less control over camera movement + +--- + +## Common Prompt Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|-----| +| "A person using our app" | Too vague, no visual detail | Describe the person, setting, lighting, camera | +| Including text/logos | AI can't render readable text | Add text in post via Hyperframes/CapCut | +| "Make it viral" | Not a visual instruction | Describe the visual style you want | +| Extremely long prompts (200+ words) | Models lose focus | Keep to 50-100 words, be specific | +| No camera direction | Random/static camera | Always specify movement or "static" | +| "Realistic" alone | Not specific enough | "Photorealistic, natural lighting, shot on RED camera" | + +--- + +## Prompting Workflow + +1. **Reference first** — find a real video that looks like what you want +2. **Describe it** — break down: subject, action, camera, style, mood +3. **Generate 3-4 variations** — same concept, different angles or styles +4. **Iterate on the best** — refine the prompt based on results +5. **Composite** — combine AI footage with programmatic text/overlays + +--- + +## Aspect Ratios + +Always specify in your prompt or generation settings: + +| Platform | Ratio | Resolution | +|----------|-------|-----------| +| YouTube | 16:9 | 1920x1080 or 3840x2160 | +| TikTok/Reels/Shorts | 9:16 | 1080x1920 | +| Instagram Feed | 1:1 or 4:5 | 1080x1080 or 1080x1350 | +| Website hero | 16:9 | 1920x1080 | +| LinkedIn | 16:9 or 1:1 | 1920x1080 | + +--- + +## Cost Optimization + +- **Iterate at low resolution** — upscale only the final version +- **Use Kling for drafts** — cheapest per second, switch to Veo/Runway for finals +- **Image-to-video** — providing a reference frame saves generation credits and gives better results +- **Batch similar prompts** — models often offer volume discounts +- **Cache and reuse** — B-roll clips can be reused across multiple videos diff --git a/types/index.ts b/types/index.ts index e87b0f1..d910af8 100644 --- a/types/index.ts +++ b/types/index.ts @@ -25,6 +25,8 @@ export type ArtifactType = | 'ab_test' | 'landing_page' | 'one_pager' + | 'sms_campaign' + | 'prospect_list' | 'other'; // Runtime-usable whitelist of all valid artifact types (mirrors ArtifactType union above) @@ -32,7 +34,7 @@ export const ARTIFACT_TYPES: ArtifactType[] = [ 'copywriting', 'email_sequence', 'cold_email', 'social_content', 'launch_strategy', 'content_strategy', 'positioning', 'messaging', 'ad_creative', 'competitor_analysis', 'seo', 'cro', 'ab_test', - 'landing_page', 'one_pager', 'other', + 'landing_page', 'one_pager', 'sms_campaign', 'prospect_list', 'other', ]; // Artifact status workflow: Draft → Review → Approved → Live → Archived