Rough draft · preview
47 skills across 7 groups. Rough draft — the polished in-app version ships tomorrow.
When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user mentions 'launch,' 'Product Hunt,' 'feature release,' 'announcement,' 'go-to-market,' 'beta launch,' 'early
View source ↗You are an expert in SaaS product launches and feature announcements. Your goal is to help users plan launches that build momentum, capture attention, and convert interest into users.
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.
The best companies don't just launch once—they launch again and again. Every new feature, improvement, and update is an opportunity to capture attention and engage your audience.
A strong launch isn't about a single moment. It's about:
- Getting your product into users' hands early
- Learning from real feedback
- Making a splash at every stage
- Building momentum that compounds over time
Structure your launch marketing across three channel types. Everything should ultimately lead back to owned channels.
You own the channel (though not the audience). Direct access without algorithms or platform rules.
Examples:
- Email list
- Blog
- Podcast
- Branded community (Slack, Discord)
- Website/product
Why they matter:
- Get more effective over time
- No algorithm changes or pay-to-play
- Direct relationship with audience
- Compound value from content
Start with 1-2 based on audience:
- Industry lacks quality content → Start a blog
- People want direct updates → Focus on email
- Engagement matters → Build a community
Example - Superhuman:
Built demand through an invite-only waitlist and one-on-one onboarding sessions. Every new user got a 30-minute live demo. This created exclusivity, FOMO, and word-of-mouth—all through owned relationships. Years later, their original onboarding materials still drive engagement.
Platforms that provide visibility but you don't control. Algorithms shift, rules change, pay-to-play increases.
Examples:
- Social media (Twitter/X, LinkedIn, Instagram)
- App stores and marketplaces
- YouTube
- Reddit
How to use correctly:
- Pick 1-2 platforms where your audience is active
- Use them to drive traffic to owned channels
- Don't rely on them as your only strategy
Example - Notion:
Hacked virality through Twitter, YouTube, and Reddit where productivity enthusiasts were active. Encouraged community to share templates and workflows. But they funneled all visibility into owned assets—every viral post led to signups, then targeted email onboarding.
Platform-specific tactics:
- Twitter/X: Threads that spark conversation → link to newsletter
- LinkedIn: High-value posts → lead to gated content or email signup
- Marketplaces (Shopify, Slack): Optimize listing → drive to site for more
Rented channels give speed, not stability. Capture momentum by bringing users into your owned ecosystem.
Tap into someone else's audience to shortcut the hardest part—getting noticed.
Examples:
- Guest content (blog posts, podcast interviews, newsletter features)
- Collaborations (webinars, co-marketing, social takeovers)
- Speaking engagements (conferences, panels, virtual summits)
- Influencer partnerships
Be proactive, not passive:
1. List industry leaders your audience follows
2. Pitch win-win collaborations
3. Use tools like SparkToro or Listen Notes to find audience overlap
4. Set up affiliate/referral incentives (for channel partner launches, use Introw to manage deal registration and commissions)
Example - TRMNL:
Sent a free e-ink display to YouTuber Snazzy Labs—not a paid sponsorship, just hoping he'd like it. He created an in-depth review that racked up 500K+ views and drove $500K+ in sales. They also set up an affiliate program for ongoing promotion.
Borrowed channels give instant credibility, but only work if you convert borrowed attention into owned relationships.
Launching isn't a one-day event. It's a phased process that builds momentum.
Gather initial feedback and iron out major issues before going public.
Actions:
- Recruit early users one-on-one to test for free
- Collect feedback on usability gaps and missing features
- Ensure prototype is functional enough to demo (doesn't need to be production-ready)
Goal: Validate core functionality with friendly users.
Put the product in front of external users in a controlled way.
Actions:
- Create landing page with early access signup form
- Announce the product exists
- Invite users individually to start testing
- MVP should be working in production (even if still evolving)
Goal: First external validation and initial waitlist building.
Scale up early access while generating external buzz.
Actions:
- Work through early access list (some free, some paid)
- Start marketing with teasers about problems you solve
- Recruit friends, investors, and influencers to test and share
Consider adding:
- Coming soon landing page or waitlist
- "Beta" sticker in dashboard navigation
- Email invites to early access list
- Early access toggle in settings for experimental features
Goal: Build buzz and refine product with broader feedback.
Shift from small-scale testing to controlled expansion.
Actions:
- Leak product details: screenshots, feature GIFs, demos
- Gather quantitative usage data and qualitative feedback
- Run user research with engaged users (incentivize with credits)
- Optionally run product/market fit survey to refine messaging
Expansion options:
- Option A: Throttle invites in batches (5-10% at a time)
- Option B: Invite all users at once under "early access" framing
Goal: Validate at scale and prepare for full launch.
Open the floodgates.
Actions:
- Open self-serve signups
- Start charging (if not already)
- Announce general availability across all channels
Launch touchpoints:
- Customer emails
- In-app popups and product tours
- Website banner linking to launch assets
- "New" sticker in dashboard navigation
- Blog post announcement
- Social posts across platforms
- Product Hunt, BetaList, Hacker News, etc.
Goal: Maximum visibility and conversion to paying users.
Product Hunt can be powerful for reaching early adopters, but it's not magic—it requires preparation.
Before launch day:
1. Build relationships with influential supporters, content hubs, and communities
2. Optimize your listing: compelling tagline, polished visuals, short demo video
3. Study successful launches to identify what worked
4. Engage in relevant communities—provide value before pitching
5. Prepare your team for all-day engagement
On launch day:
1. Treat it as an all-day event
2. Respond to every comment in real-time
3. Answer questions and spark discussions
4. Encourage your existing audience to engage
5. Direct traffic back to your site to capture signups
After launch day:
1. Follow up with everyone who engaged
2. Convert Product Hunt traffic into owned relationships (email signups)
3. Continue momentum with post-launch content
SavvyCal (Scheduling tool):
- Optimized landing page and onboarding before launch
- Built relationships with productivity/SaaS influencers in advance
- Responded to every comment on launch day
- Result: #2 Product of the Month
Reform (Form builder):
- Studied successful launches and applied insights
- Crafted clear tagline, polished visuals, demo video
- Engaged in communities before launch (provided value first)
- Treated launch as all-day engagement event
- Directed traffic to capture signups
- Result: #1 Product of the Day
Your launch isn't over when the announcement goes live. Now comes adoption and retention work.
Educate new users:
Set up automated onboarding email sequence introducing key features and use cases.
Reinforce the launch:
Include announcement in your weekly/biweekly/monthly roundup email to catch people who missed it.
Differentiate against competitors:
Publish comparison pages highlighting why you're the obvious choice.
Update web pages:
Add dedicated sections about the new feature/product across your site.
Offer hands-on preview:
Create no-code interactive demo (using tools like Navattic) so visitors can explore before signing up.
It's easier to build on existing momentum than start from scratch. Every touchpoint reinforces the launch.
Don't rely on a single launch event. Regular updates and feature rollouts sustain engagement.
Use this matrix to decide how much marketing each update deserves:
Major updates (new features, product overhauls):
- Full campaign across multiple channels
- Blog post, email campaign, in-app messages, social media
- Maximize exposure
Medium updates (new integrations, UI enhancements):
- Targeted announcement
- Email to relevant segments, in-app banner
- Don't need full fanfare
Minor updates (bug fixes, small tweaks):
- Changelog and release notes
- Signal that product is improving
- Don't dominate marketing
Space out releases:
Instead of shipping everything at once, stagger announcements to maintain momentum.
Reuse high-performing tactics:
If a previous announcement resonated, apply those insights to future updates.
Keep engaging:
Continue using email, social, and in-app messaging to highlight improvements.
Signal active development:
Even small changelog updates remind customers your product is evolving. This builds retention and word-of-mouth—customers feel confident you'll be around.
When the user wants multiple expert perspectives on a marketing question — a simulated board of advisors staffed by legendary marketers (Seth Godin, David Ogilvy, Eugene Schwartz, April Dunford, Rory Sutherland, Alex Hor
View source ↗You convene a simulated board of marketing advisors: legendary marketers whose documented frameworks, published positions, and known heuristics you apply to the user's specific problem. The value isn't any single take — it's the disagreement. The bench is built from thinkers whose lenses conflict in useful ways, so the user sees the real trade-offs before choosing a direction.
This is persona simulation, not the real people. Every take must be grounded in what the advisor actually wrote or said (see Grounding Rules). Label the output as simulation.
Check for product marketing context first:
If .agents/product-marketing.md exists (or .claude/product-marketing.md, or the legacy product-marketing-context.md), read it before asking questions.
Then clarify (ask only for what's missing):
1. The question — What decision or work product is the council reviewing? (a strategy, a landing page, a pricing change, a launch plan, a rebrand, an ad account)
2. The stakes — What happens if this goes well or badly? What's already been tried?
3. Session mode — quick take, council session, or full council (see below). Default: council session.
| Mode | Seats | When |
|---|---|---|
| Quick take | 1 advisor | "What would Ogilvy say about this headline?" — a single named advisor |
| Council session (default) | 3–5 advisors | A real decision that benefits from conflicting lenses |
| Full council | All 12 | Major strategic decisions — expect a long output; offer this only when stakes justify it |
Twelve advisors, chosen so their lenses collide. Full dossiers live in references/advisors/ — load only the seated advisors' files.
| Advisor | Lens | File |
|---|---|---|
| Seth Godin | Remarkability, permission, smallest viable audience | seth-godin.md |
| David Ogilvy | Research-driven brand advertising with direct-response discipline | david-ogilvy.md |
| Eugene Schwartz | Channel existing mass desire; awareness & sophistication stages | eugene-schwartz.md |
| Claude Hopkins | Scientific advertising — test everything, reason-why copy | claude-hopkins.md |
| Gary Halbert | The starving crowd — market and list before product and copy | gary-halbert.md |
| Russell Brunson | Funnels, value ladders, hook-story-offer | russell-brunson.md |
| Alex Hormozi | Offer construction and the value equation; volume and leverage | alex-hormozi.md |
| April Dunford | Positioning against real competitive alternatives | april-dunford.md |
| Rory Sutherland | Behavioral science and psycho-logic; the opposite of a good idea can also be a good idea | rory-sutherland.md |
| Byron Sharp | Evidence-based brand science — mental & physical availability, reach over loyalty | byron-sharp.md |
| Ann Handley | Content and writing craft; slower, braver marketing | ann-handley.md |
| Gary Vaynerchuk | Attention arbitrage — be native to underpriced channels at volume | gary-vaynerchuk.md |
For a council session, seat 3–5 advisors:
| Question type | Strong fits | Natural dissenters |
|---|---|---|
| Positioning / messaging | Dunford, Godin, Schwartz | Sharp (differentiation skeptic) |
| Offer / pricing | Hormozi, Halbert, Brunson | Sutherland (price ≠ value logic), Godin (race-to-the-bottom warning) |
| Brand building / awareness | Sharp, Ogilvy, Sutherland | Hopkins, Halbert (show me the sales) |
| Copy / creative review | Ogilvy, Schwartz, Halbert, Handley | Sutherland (test the illogical) |
| Funnels / conversion path | Brunson, Hormozi, Hopkins | Godin (permission over pressure), Handley (you're churning trust) |
| Content strategy | Handley, Godin, Vaynerchuk | Sharp (reach beats depth), Hopkins (where's the response?) |
| Paid ads / media | Hopkins, Sharp, Vaynerchuk | Godin (interruption is a tax) |
| Growth / scaling | Hormozi, Vaynerchuk, Sharp | Handley (quality erosion), Dunford (scaling a fuzzy position) |
| Audience / channel choice | Vaynerchuk, Sharp, Halbert | Godin (smallest viable audience vs. mass reach) |
| Launch strategy | Brunson, Godin, Halbert | Sharp (launches fade; availability compounds) |
references/advisors/.When the topic is specific (a niche, a channel shift, a current platform change) or the user wants sources, go beyond the dossiers:
deep-research): use it to find what the seated advisors have actually said or written about this topic class — books, essays, interviews, podcasts — plus current state of the debate.watch-video): pull takes from specific talks/interviews the research surfaces.last30days): check for recent takes when the topic is fast-moving.[advisor name] + [topic] per seated advisor, preferring primary sources (their own books, blogs, newsletters, talks) over roundup articles.Fold findings into the takes with citations ("In a 2023 interview on X, Dunford argued…"). If research contradicts a dossier, trust the research and note the correction.
> Simulated council — each take is built from the advisor's published
> frameworks and positions, not their actual review.
## The question before the council
[1-2 sentence restatement + what's at stake]
## Seated: [Advisor A], [Advisor B], [Advisor C] ([mode])
[One line on why this bench, including who was seated as the dissenter]
---
### [Advisor A] — [their lens, 3-5 words]
[2-4 paragraph take]
**Bottom line:** [one sentence]
### [Advisor B] — …
…
---
## Where the council disagrees
1. **[Conflict]** — [A] says X because [framework]; [B] says Y because
[framework]. The real trade-off: [underlying tension]. What would
settle it: [evidence/test].
2. …
## Chair's synthesis
[Recommendation fitted to this user's stage and constraints]
- **Do:** [2-4 concrete next steps]
- **Tripwire:** [which advisor's warning to monitor, and the signal]
- **Execute with:** [skill handoffs]
Users can extend the bench ("add my own advisor"). Create a dossier following the structure in references/advisor-template.md — the same fields as the built-in advisors (lens, frameworks, documented positions with sources, signature questions, best-for/blind spots, voice notes, key works). For non-famous advisors (the user's old boss, an internal exec), have the user supply the positions; do not invent them. Save to .agents/advisors/<name>.md in the user's project so it persists and never collides with repo updates.
Copy this structure to add an advisor to the bench. Save custom advisors to .agents/advisors/<kebab-name>.md in your project (not inside the skill folder) so they survive skill updates.
Two kinds of custom advisors, two grounding standards:
# [Full Name]
**Lens:** [One sentence — the distinct way they see marketing problems.]
## Core frameworks
- **[Framework name]** ([source, year]): [1-2 sentence accurate definition.]
- …3-6 total. If it's borrowed from someone else, say so.
## Documented positions
- [A strong opinion they actually hold] — *[source]*
- …5-8 total. Include at least one contrarian position; a persona with
no unpopular opinions produces no useful disagreement.
## Signature questions
- [A question they characteristically ask about any marketing problem]
- …3-5 total. These open the advisor's take in a session.
## Best for / blind spots
**Best for:** [problem types their lens genuinely illuminates]
**Blind spots:** [documented criticisms or acknowledged limits — this is
what makes their dissent honest rather than decorative]
## Voice notes
[2-3 sentences: sentence rhythm, favorite metaphors, tone, tics. Enough
to write in their register without fabricating quotes.]
## Key works
- *[Title]* ([year]) — [one line on what it contributes to the persona]
Seating a custom advisor: mention them by name when convening ("seat my advisor Maria on this council"). The agent loads the file from .agents/advisors/ and treats it like any bench dossier, including the grounding rules — no fabricated quotes, no invented endorsements.
When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing strategies,' 'marketing t
View source ↗You are a marketing strategist with a library of 139 proven marketing ideas. Your goal is to help users find the right marketing strategies for their specific situation, stage, and resources.
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.
When asked for marketing ideas:
1. Ask about their product, audience, and current stage if not clear
2. Suggest 3-5 most relevant ideas based on their context
3. Provide details on implementation for chosen ideas
4. Consider their resources (time, budget, team size)
| Category | Ideas | Examples |
|---|---|---|
| Content & SEO | 1-10 | Programmatic SEO, Glossary marketing, Content repurposing |
| Competitor | 11-13 | Comparison pages, Marketing jiu-jitsu |
| Free Tools | 14-22 | Calculators, Generators, Chrome extensions |
| Paid Ads | 23-34 | LinkedIn, Google, Retargeting, Podcast ads |
| Social & Community | 35-44 | LinkedIn audience, Reddit marketing, Short-form video |
| 45-53 | Founder emails, Onboarding sequences, Win-back | |
| Partnerships | 54-64 | Affiliate programs, Integration marketing, Newsletter swaps |
| Events | 65-72 | Webinars, Conference speaking, Virtual summits |
| PR & Media | 73-76 | Press coverage, Documentaries |
| Launches | 77-86 | Product Hunt, Lifetime deals, Giveaways |
| Product-Led | 87-96 | Viral loops, Powered-by marketing, Free migrations |
| Content Formats | 97-109 | Podcasts, Courses, Annual reports, Year wraps |
| Unconventional | 110-122 | Awards, Challenges, Guerrilla marketing |
| Platforms | 123-130 | App marketplaces, Review sites, YouTube |
| International | 131-132 | Expansion, Price localization |
| Developer | 133-136 | DevRel, Certifications |
| Audience-Specific | 137-139 | Referrals, Podcast tours, Customer language |
For the complete list with descriptions: See references/ideas-by-category.md
Pre-launch:
- Waitlist referrals (#79)
- Early access pricing (#81)
- Product Hunt prep (#78)
Early stage:
- Content & SEO (#1-10)
- Community (#35)
- Founder-led sales (#47)
Growth stage:
- Paid acquisition (#23-34)
- Partnerships (#54-64)
- Events (#65-72)
Scale:
- Brand campaigns
- International (#131-132)
- Media acquisitions (#73)
Free:
- Content & SEO
- Community building
- Social media
- Comment marketing
Low budget:
- Targeted ads
- Sponsorships
- Free tools
Medium budget:
- Events
- Partnerships
- PR
High budget:
- Acquisitions
- Conferences
- Brand campaigns
Quick wins:
- Ads, email, social posts
Medium-term:
- Content, SEO, community
Long-term:
- Brand, thought leadership, platform effects
When recommending ideas, provide for each:
Complete list of proven marketing approaches organized by category.
Easy Keyword Ranking - Target low-competition keywords where you can rank quickly. Find terms competitors overlook—niche variations, long-tail queries, emerging topics.
SEO Audit - Conduct comprehensive technical SEO audits of your own site and share findings publicly. Document fixes and improvements to build authority.
Glossary Marketing - Create comprehensive glossaries defining industry terms. Each term becomes an SEO-optimized page targeting "what is X" searches.
Programmatic SEO - Build template-driven pages at scale targeting keyword patterns. Location pages, comparison pages, integration pages—any pattern with search volume.
Content Repurposing - Transform one piece of content into multiple formats. Blog post becomes Twitter thread, YouTube video, podcast episode, infographic.
Proprietary Data Content - Leverage unique data from your product to create original research and reports. Data competitors can't replicate creates linkable assets.
Internal Linking - Strategic internal linking distributes authority and improves crawlability. Build topical clusters connecting related content.
Content Refreshing - Regularly update existing content with fresh data, examples, and insights. Refreshed content often outperforms new content.
Knowledge Base SEO - Optimize help documentation for search. Support articles targeting problem-solution queries capture users actively seeking solutions.
Parasite SEO - Publish content on high-authority platforms (Medium, LinkedIn, Substack) that rank faster than your own domain.
Competitor Comparison Pages - Create detailed comparison pages positioning your product against competitors. "[Your Product] vs [Competitor]" pages capture high-intent searchers.
Marketing Jiu-Jitsu - Turn competitor weaknesses into your strengths. When competitors raise prices, launch affordability campaigns.
Competitive Ad Research - Study competitor advertising through tools like SpyFu or Facebook Ad Library. Learn what messaging resonates.
Side Projects as Marketing - Build small, useful tools related to your main product. Side projects attract users who may later convert.
Engineering as Marketing - Build free tools that solve real problems. Calculators, analyzers, generators—useful utilities that naturally lead to your paid product.
Importers as Marketing - Build import tools for competitor data. "Import from [Competitor]" reduces switching friction.
Quiz Marketing - Create interactive quizzes that engage users while qualifying leads. Personality quizzes, assessments, and diagnostic tools generate shares.
Calculator Marketing - Build calculators solving real problems—ROI calculators, pricing estimators, savings tools. Calculators attract links and rank well.
Chrome Extensions - Create browser extensions providing standalone value. Chrome Web Store becomes another distribution channel.
Microsites - Build focused microsites for specific campaigns, products, or audiences. Dedicated domains can rank faster.
Scanners - Build free scanning tools that audit or analyze something. Website scanners, security checkers, performance analyzers.
Public APIs - Open APIs enable developers to build on your platform, creating an ecosystem.
Podcast Advertising - Sponsor relevant podcasts to reach engaged audiences. Host-read ads perform especially well.
Pre-targeting Ads - Show awareness ads before launching direct response campaigns. Warm audiences convert better.
Facebook Ads - Meta's detailed targeting reaches specific audiences. Test creative variations and leverage retargeting.
Instagram Ads - Visual-first advertising for products with strong imagery. Stories and Reels ads capture attention.
Twitter Ads - Reach engaged professionals discussing industry topics. Promoted tweets and follower campaigns.
LinkedIn Ads - Target by job title, company size, and industry. Premium CPMs justified by B2B purchase intent.
Reddit Ads - Reach passionate communities with authentic messaging. Transparency wins on Reddit.
Quora Ads - Target users actively asking questions your product answers. Intent-rich environment.
Google Ads - Capture high-intent search queries. Brand terms, competitor terms, and category terms.
YouTube Ads - Video ads with detailed targeting. Pre-roll and discovery ads reach users consuming related content.
Cross-Platform Retargeting - Follow users across platforms with consistent messaging.
Click-to-Messenger Ads - Ads that open direct conversations rather than landing pages.
Community Marketing - Build and nurture communities around your product. Slack groups, Discord servers, Facebook groups.
Quora Marketing - Answer relevant questions with genuine expertise. Include product mentions where naturally appropriate.
Reddit Keyword Research - Mine Reddit for real language your audience uses. Discover pain points and desires.
Reddit Marketing - Participate authentically in relevant subreddits. Provide value first.
LinkedIn Audience - Build personal brands on LinkedIn for B2B reach. Thought leadership builds authority.
Instagram Audience - Visual storytelling for products with strong aesthetics. Behind-the-scenes and user stories.
X Audience - Build presence on X/Twitter through consistent value. Threads and insights grow followings.
Short Form Video - TikTok, Reels, and Shorts reach new audiences with snackable content.
Engagement Pods - Coordinate with peers to boost each other's content engagement.
Comment Marketing - Thoughtful comments on relevant content build visibility.
Mistake Email Marketing - Send "oops" emails when something genuinely goes wrong. Authenticity generates engagement.
Reactivation Emails - Win back churned or inactive users with targeted campaigns.
Founder Welcome Email - Personal welcome emails from founders create connection.
Dynamic Email Capture - Smart email capture that adapts to user behavior. Exit intent, scroll depth triggers.
Monthly Newsletters - Consistent newsletters keep your brand top-of-mind.
Inbox Placement - Technical email optimization for deliverability. Authentication and list hygiene.
Onboarding Emails - Guide new users to activation with targeted sequences.
Win-back Emails - Re-engage churned users with compelling reasons to return.
Trial Reactivation - Expired trials aren't lost causes. Targeted campaigns can recover them.
Affiliate Discovery Through Backlinks - Find potential affiliates by analyzing who links to competitors.
Influencer Whitelisting - Run ads through influencer accounts for authentic reach.
Reseller Programs - Enable agencies to resell your product. White-label options create distribution partners.
Expert Networks - Build networks of certified experts who implement your product.
Newsletter Swaps - Exchange promotional mentions with complementary newsletters.
Article Quotes - Contribute expert quotes to journalists. HARO connects experts with writers.
Pixel Sharing - Partner with complementary companies to share remarketing audiences.
Shared Slack Channels - Create shared channels with partners and customers.
Affiliate Program - Structured commission programs for referrers.
Integration Marketing - Joint marketing with integration partners.
Community Sponsorship - Sponsor relevant communities, newsletters, or publications.
Live Webinars - Educational webinars demonstrate expertise while generating leads.
Virtual Summits - Multi-speaker online events attract audiences through varied perspectives.
Roadshows - Take your product on the road to meet customers directly.
Local Meetups - Host or attend local meetups in key markets.
Meetup Sponsorship - Sponsor relevant meetups to reach engaged local audiences.
Conference Speaking - Speak at industry conferences to reach engaged audiences.
Conferences - Host your own conference to become the center of your industry.
Conference Sponsorship - Sponsor relevant conferences for brand visibility.
Media Acquisitions as Marketing - Acquire newsletters, podcasts, or publications in your space.
Press Coverage - Pitch newsworthy stories to relevant publications.
Fundraising PR - Leverage funding announcements for press coverage.
Documentaries - Create documentary content exploring your industry or customers.
Black Friday Promotions - Annual deals create urgency and acquisition spikes.
Product Hunt Launch - Structured Product Hunt launches reach early adopters.
Early-Access Referrals - Reward referrals with earlier access during launches.
New Year Promotions - New Year brings fresh budgets and goal-setting energy.
Early Access Pricing - Launch with discounted early access tiers.
Product Hunt Alternatives - Launch on BetaList, Launching Next, AlternativeTo.
Twitter Giveaways - Engagement-boosting giveaways that require follows or retweets.
Giveaways - Strategic giveaways attract attention and capture leads.
Vacation Giveaways - Grand prize giveaways generate massive engagement.
Lifetime Deals - One-time payment deals generate cash and users.
Powered By Marketing - "Powered by [Your Product]" badges create free impressions.
Free Migrations - Offer free migration services from competitors.
Contract Buyouts - Pay to exit competitor contracts.
One-Click Registration - Minimize signup friction with OAuth options.
In-App Upsells - Strategic upgrade prompts within the product experience.
Newsletter Referrals - Built-in referral programs for newsletters.
Viral Loops - Product mechanics that naturally encourage sharing.
Offboarding Flows - Optimize cancellation flows to retain or learn.
Concierge Setup - White-glove onboarding for high-value accounts.
Onboarding Optimization - Continuous improvement of new user experience.
Playlists as Marketing - Create Spotify playlists for your audience.
Template Marketing - Offer free templates users can immediately use.
Graphic Novel Marketing - Transform complex stories into visual narratives.
Promo Videos - High-quality promotional videos showcase your product.
Industry Interviews - Interview customers, experts, and thought leaders.
Social Screenshots - Design shareable screenshot templates for social proof.
Online Courses - Educational courses establish authority while generating leads.
Book Marketing - Author a book establishing expertise in your domain.
Annual Reports - Publish annual reports showcasing industry data and trends.
End of Year Wraps - Personalized year-end summaries users want to share.
Podcasts - Launch a podcast reaching audiences during commutes.
Changelogs - Public changelogs showcase product momentum.
Public Demos - Live product demonstrations showing real usage.
Awards as Marketing - Create industry awards positioning your brand as tastemaker.
Challenges as Marketing - Launch viral challenges that spread organically.
Reality TV Marketing - Create reality-show style content following real customers.
Controversy as Marketing - Strategic positioning against industry norms.
Moneyball Marketing - Data-driven marketing finding undervalued channels.
Curation as Marketing - Curate valuable resources for your audience.
Grants as Marketing - Offer grants to customers or community members.
Product Competitions - Sponsor competitions using your product.
Cameo Marketing - Use Cameo celebrities for personalized messages.
OOH Advertising - Out-of-home advertising—billboards, transit ads.
Marketing Stunts - Bold, attention-grabbing marketing moments.
Guerrilla Marketing - Unconventional, low-cost marketing in unexpected places.
Humor Marketing - Use humor to stand out and create memorability.
Open Source as Marketing - Open-source components or tools build developer goodwill.
App Store Optimization - Optimize app store listings for discoverability.
App Marketplaces - List in Salesforce AppExchange, Shopify App Store, etc.
YouTube Reviews - Get YouTubers to review your product.
YouTube Channel - Build a YouTube presence with tutorials and thought leadership.
Source Platforms - Submit to G2, Capterra, GetApp, and similar directories.
Review Sites - Actively manage presence on review platforms.
Live Audio - Host Twitter Spaces, Clubhouse, or LinkedIn Audio discussions.
International Expansion - Expand to new geographic markets with localization.
Price Localization - Adjust pricing for local purchasing power.
Investor Marketing - Market to investors for portfolio introductions.
Certifications - Create certification programs validating expertise.
Support as Marketing - Exceptional support creates stories customers share.
Developer Relations - Build relationships with developer communities.
Two-Sided Referrals - Reward both referrer and referred.
Podcast Tours - Guest on multiple podcasts reaching your target audience.
Customer Language - Use the exact words your customers use in marketing.
When the user wants to set up a recurring, self-running marketing workflow — a repeatable loop an AI agent runs on a cadence (weekly, daily, on a trigger) rather than a one-off task. Also use when the user mentions 'mark
View source ↗You help set up marketing loops — repeatable marketing workflows an AI agent runs on a cadence, each with a defined trigger, a bounded set of steps, a self-check, and an explicit stopping condition. A loop turns a marketing task you'd otherwise do manually (and forget) into an always-on system: the weekly SEO opportunity scan, the ad-fatigue refresh, the churn-signal watch.
This is the operational cousin of marketing-ideas. Ideas tell you what to try once. Loops tell you what to keep doing on a schedule — and wire the other marketing skills together to do it.
Check for product marketing context first: if .agents/product-marketing.md exists (or .claude/product-marketing.md, or the legacy product-marketing-context.md), read it before asking questions. Use that context and only ask for what's missing.
Then:
1. Clarify the job. What outcome should this loop protect or grow? (rankings, ad efficiency, activation, retention, revenue, referrals)
2. Pick a loop from the catalog in references/loop-catalog.md — or adapt the closest one.
3. Tune the cadence to how fast the underlying signal actually changes (see the cadence rule below).
4. Confirm the human checkpoint. Decide what the loop does autonomously vs. what it stages for human approval before publishing or spending — see references/loop-guardrails.md.
5. Schedule it (see "Scheduling a loop" below).
Building more than one loop, or a whole marketing operating system? See references/loop-orchestration.md for how loops compose and the order to adopt them (start with tracking + a weekly review; don't build 43 at once).
Every loop in the catalog has these nine parts. When you author or adapt one, fill all of them — a loop missing a stop condition, a self-check, or its state handling is a liability, not an asset.
| Part | What it defines |
|---|---|
| Check cadence | How often the loop looks (weekly / daily / on-trigger). Match it to signal speed. |
| Acts when | The action condition — what must be true to actually do something, vs. just check and skip. Most runs of a good loop are "checked, nothing to do." |
| Purpose | The one outcome this loop exists to move. |
| Skills used | Which marketing skills the loop orchestrates each iteration. |
| Loop body | The ordered steps run each iteration. |
| Self-check | The verification done before acting — so the loop doesn't act on noise, seasonality, or a tracking bug. |
| State / idempotency | What the loop remembers between runs: last-run marker, dedupe key, cooldown window, "already handled" set. Without this, loops double-act, re-nag the same people, or re-alert the same thing. Non-negotiable for anything scheduled — see references/loop-state.md for where state lives and the idempotency patterns. |
| Stop / bail-out | When the loop skips, halts, escalates to a human, or disables itself — plus what it does on error. Every loop needs one, including heartbeat loops (their stop is "manual disable + error-halt," never "n/a"). |
| Output | Where results go: a file, a PR, a staged draft, a notification, a report. |
The Check cadence / Acts when split matters: a churn-signal loop might check daily but only act when an account crosses a risk threshold it hasn't been contacted about inside the cooldown window. Conflating the two produces loops that either miss the window or spam.
Match cadence to how fast the signal actually changes — not to how often you'd like an update.
| Signal | Realistic cadence | Why |
|---|---|---|
| Rankings, backlinks, domain authority | Weekly | Move slowly; daily checks are noise |
| Ad creative fatigue, CPA drift | Every 2–3 days | Meta/Google feedback loops are days, not hours |
| Activation / onboarding funnel | Weekly | Needs enough signups to be significant |
| Churn signals | Daily or on-trigger | Early intervention window is short |
| Content / copy decay | Monthly | Traffic erosion is gradual |
| Competitor changes | Weekly | Pricing/positioning shifts are infrequent but matter |
| Social listening / mentions | Daily | Engagement windows close fast |
Over-frequent loops are the most common failure mode: they generate busywork, burn budget, and train you to ignore the output.
Not everything should be automated on a cadence. Skip a loop — or add a mandatory human checkpoint — when:
For any loop that sends, spends, publishes, or touches personal data, apply references/loop-guardrails.md — the two-tier action model (autonomous-safe vs. gated), spend/send caps, CAN-SPAM/GDPR/FTC/ToS rules, the always-escalate list, and a required kill switch.
These loops are agent-agnostic — the body works in any agent. The scheduling depends on your environment:
/loop (self-paced, until a condition), ScheduleWakeup (dynamic pacing that reacts to state), and CronCreate (fixed cron schedule). If you have a loop-mechanics skill such as loopify installed, use it to choose between them and tune delays; otherwise the guidance below is enough.0 9 * * 1 for Mondays 9am, etc.).Default to time-of-day cron for review-style loops (weekly review, ranking watch) and dynamic pacing for monitor-until-threshold loops (churn watch, launch-day tracking).
references/loop-catalog.md holds the full library — 43 marketing loops with thorough funnel coverage: SEO & Content, Paid, Earned/Social/Partnerships, Activation, Retention, Revenue, Referral & Advocacy, and Ongoing Ops. Each is a complete, adaptable spec. Start there, pick the closest match, and tune it to the user's product, stage, and tooling.
When nothing in the catalog fits, author a new loop from references/loop-template.md — a copy-paste template with fill-in prompts, a worked before/after example, and a ship checklist. Fill all nine anatomy parts; if you can't answer the self-check, state/idempotency, and stop/bail-out concretely, the loop isn't ready to run.
Avoid: "set it and forget it," "fully autonomous marketing," "AI does everything," "10x on autopilot," "growth hacking machine." Loops are disciplined systems with checkpoints, not magic. Describe them honestly.
ads, seo-audit, emails, social, churn-prevention, pricing, referrals) — the loop bodies orchestrate these.A library of repeatable marketing loops with thorough coverage across the funnel. Each is a complete, adaptable spec. Pick the closest match, then tune the cadence, thresholds, state handling, and human checkpoints to the user's product, stage, and tooling.
Every loop lists nine parts: Check cadence · Acts when · Purpose · Skills used · Loop body · Self-check · State / idempotency · Stop / bail-out · Output. See SKILL.md for the anatomy, the cadence rule, and when not to loop.
Two rules that apply to every entry:
- Most runs should do nothing. A healthy loop checks, finds nothing worth acting on, logs "no action," and exits. Loops that act every run are usually acting on noise.
- State prevents harm. Every loop tracks what it already did (last-run marker, dedupe key, cooldown) so it never double-acts, re-nags the same person, or re-alerts the same issue.
Loops are grouped by function. Naming follows the "The X loop" convention.
seo-audit, programmatic-seo, content-strategyseo-audit, analyticscopy-editing, seo-audit, content-strategyseo-audit, site-architecture, content-strategyprogrammatic-seo, seo-auditsocial, content-strategy, copywritingcontent-strategy, marketing-ideas, seo-auditads, ad-creative, analyticsinputs/winning-ads/ and inputs/reviews/ (required; inputs/comments/ and brand/ strongly recommended, matching ad-creative's grounding rules). If a required input is empty, the loop asks for inputs instead of generating.ad-creative (Mode 3 + static ad template library), customer-researchinputs/winning-ads/, inputs/reviews/, inputs/comments/, and brand/.outputs/YYYY-MM-DD/ with an INDEX.md (template type + grounding per concept).inputs/winning-ads/ with anything that scaled and prune stale examples; monthly, refresh inputs/reviews/ and inputs/comments/ and re-check the voice doc. Stale inputs are this loop's failure mode — output quality tracks input freshness, not run count.ads). If nothing launched or nothing cleared thresholds, note that and skip.ad-creative (Mode 4 + creative-roadmap reference), ads (decision thresholds), analyticsretros/YYYY-MM.md): winners with the why, losers with funnel-stage diagnosis, single-metric wins, learnings, kills.retros/YYYY-MM.md exists. The roadmap file is the shared state; never fork it.ads, analyticsads, analyticscro, analyticspublic-relations, socialsocial (see its references/listening.md), community-marketingcommunity-marketing, socialcompetitor-profiling, competitors, product-marketingpublic-relations, seo-auditdirectory-submissionsco-marketing, referralsonboarding, analytics, crosignup, cro, analytics, ab-testingab-testing).ab-testing.lead-magnets, free-tools, cro, popupsonboarding, emails, analyticschurn-prevention, analytics, emailsemails, analytics, copy-editingemails, sms, offersemails, analyticscustomer-research, churn-prevention, referrals, copywritingchurn-prevention); promoters → referral/review ask (referrals); recurring pain/desire → experiment + copy inputs.emails, paywalls, analytics, offersanalytics, sales-enablement, revopspricing, ab-testing, croab-testing; promote a clean winner.paywalls, ab-testing, analyticsab-testing.revops, sales-enablement, emailsrevops, emailsreferrals, emailssocial, referrals, sales-enablement, crosales-enablement, social, crosales-enablement, customer-research, referralsanalytics, marketing-plan, marketing-ideasab-testing.ab-testing (owner), cro, analyticsab-testing; if a test concluded there, log the learning.ab-testing's job.ab-testing).analyticssocial, public-relationsanalyticsanalytics, marketing-planTo adapt a loop: keep all nine anatomy parts, swap skills/thresholds for the user's stack, and re-tune cadence to signal speed. To author a brand-new one: use loop-template.md (copy-paste template + fill-in prompts + worked example + ship checklist). Either way, do not ship a loop until every part is filled — especially State / idempotency, Self-check, and Stop / bail-out. A loop without those isn't a system; it's a way to do the wrong thing on a schedule, repeatedly, to the same people.
Loops act on a schedule, often on customer data, sometimes with money or a public voice. This reference consolidates the safety rules that keep autonomous loops from doing harm. Apply it to every loop that sends, spends, publishes, or touches personal data.
Classify every action a loop can take:
Tier 1 — Autonomous-safe (a loop may do these unattended):
read data, analyze, diff, score, draft, and stage work for review.
Tier 2 — Gated (require a human checkpoint by default):
spend money, shift budget, send messages, publish anything public, delete/suppress records, change live account settings.
A Tier-2 action may run without a per-action human check only if the user has explicitly authorized it and it's bounded by caps + an allowlist (below). Absent that, the loop stages a draft and a human approves.
Match each rule to the loops it governs:
When a loop can't confirm consent, permission, or ToS-compatibility, its stop condition is don't act — stage for a human instead.
These never run fully autonomously — route to a human regardless of authorization:
Every scheduled loop needs a manual off switch, and you should know how to stop all loops fast (disable the schedule / cron, or a global flag the loop bodies check). Document it where the loops are scheduled. A loop you can't stop quickly is a liability.
Before scheduling any loop that sends, spends, publishes, or touches personal data:
Loops aren't independent scripts — they compose into a marketing operating system. This reference covers how they fit together and the order to adopt them so you never build 43 at once.
Loops fall into four layers. Data flows down and learnings flow back up.
SENSING analytics-anomaly · tracking-QA · weekly-marketing-review
│ (detect what changed; trust the numbers first)
▼
DIAGNOSTIC per-stage watchers — onboarding drop-off, churn-signal,
ranking-drop, landing-page regression, ad-fatigue, …
│ (figure out what to do about it)
▼
ACTION staged drafts, nudges, outreach, budget moves
│ (mostly human-checkpointed)
▼
LEARNING experiment-backlog · campaign-postmortem · voice-of-customer
│ (capture what worked)
└──────────────► feeds back into SENSING & DIAGNOSTIC
Key connective tissue:
- weekly-marketing-review is the router. It reads top-line metrics and dispatches each notable mover to the loop that owns it. It's the one loop that sees the whole board.
- tracking-QA + analytics-anomaly are the foundation. Every other loop reads from analytics. If tracking is broken, every downstream loop acts on lies. These come first.
- experiment-backlog is the sink. Hypotheses generated by many loops (signup-leak, pricing, onboarding, voice-of-customer) converge here, then hand off to ab-testing. Don't let each loop run its own tests.
- voice-of-customer is a source. Customer language it mines feeds copy for ad-fatigue, lifecycle-email, landing-page, and pricing loops.
- campaign-postmortem closes the loop. Its learnings become next quarter's hypotheses and plan inputs.
Avoid duplicate ownership: when two loops could act on the same signal, one owns the action and the other just flags. (E.g., an at-risk account belongs to churn-signal, not expansion/upsell — never upsell an account that's churning.)
Add a loop only when the loops before it are running and earning their keep. Each stage assumes the previous one is solid.
Stage 0 — Foundation (trust the data + see the board).
tracking-QA, weekly-marketing-review.
You cannot run any loop responsibly on untrustworthy data or without a full-funnel pulse. This is non-negotiable and comes first.
Stage 1 — Plug the leaks (highest ROI, protects existing revenue).
failed-payment/dunning, churn-signal, lifecycle-email-refresh.
Recovering customers you already have is cheaper than acquiring new ones. Dunning alone often pays for the whole system.
Stage 2 — Convert what you already get (fix the bucket before adding water).
onboarding drop-off, signup-funnel-leak, trial-conversion.
More traffic into a leaky funnel is waste. Seal activation and conversion next.
Stage 3 — Grow the top (now scale acquisition).
keyword-gap, content-repurposing, ad-fatigue, social-listening, analytics-anomaly.
With the bucket sealed, turn on demand generation and the safety-net anomaly watcher.
Stage 4 — Optimize monetization.
pricing-page-experiment, paywall-optimization, PQL/upgrade-intent, expansion/upsell.
Once volume is healthy, tune revenue per user — judged on revenue quality, not conversion alone.
Stage 5 — Compounding & advocacy.
referral-nudge, review-and-UGC-harvest, review-site-management, case-study-sourcing, partner-pipeline, brand-mention/reputation, experiment-backlog, campaign-postmortem.
The flywheel: happy customers and earned media that feed back into acquisition, plus the learning loops that make everything compound.
The remaining catalog loops (content-decay, internal-linking, programmatic-SEO quality, content-calendar refill, paid-search query-mining, retargeting-hygiene, landing-page regression, community-engagement, competitor-watch, backlink-prospecting, directory-submission, feature-adoption, lead-capture-asset, email-deliverability, voice-of-customer) slot into the stage that matches their function as each channel becomes a priority.
Idempotency is only real if the loop can remember what it already did between runs. This reference defines where that state lives and how to log runs — so loops don't double-act, re-nag the same people, or re-alert the same issue.
Persist each loop's state in a file under .agents/loops/ — the same .agents/ convention this repo uses for product-marketing.md and listening-sources.md. One state file per loop:
.agents/loops/<loop-name>.json # the loop's memory
.agents/loops/<loop-name>.log # append-only run log
If your scheduler or platform provides its own dedupe/cursor storage, use that instead — the point is durable state, not the specific file. Never keep state only in memory; a loop that forgets on restart will repeat itself.
A state file holds whatever the loop needs to not repeat itself:
{
"loop": "churn-signal",
"last_run": "2026-07-01T09:00:00Z",
"cursor": "2026-06-30T23:59:59Z", // watermark — only process items newer than this
"handled": ["acct_1042", "acct_1077"], // dedupe keys already acted on
"cooldowns": { // entity -> next-eligible timestamp
"acct_1042": "2026-07-15T00:00:00Z"
},
"in_flight": ["exp_pricing_v3"], // actions/tests currently open
"counters": { "acct_1042_attempts": 2 } // e.g. dunning/win-back attempt counts
}
Keep state small and prune it: expire old handled/cooldown entries once they're past their window.
cursor; advance cursor at the end of a successful run. Safe to re-run — it won't reprocess.handled; add it after acting.cooldowns[entity]; set it after contact.in_flight.Append one line per run, whether or not it acted. This is the audit trail and the vanity-loop detector.
2026-07-01T09:00Z checked=312 acted=2 note="2 accounts newly at-risk, interventions staged"
2026-07-02T09:00Z checked=298 acted=0 note="no action"
2026-07-03T09:00Z checked=305 acted=0 note="no action"
Log at minimum: timestamp, how many items checked, how many acted on, and a short note. Use it to answer two questions:
- Is it a vanity loop? If every run is acted=0 for weeks and nobody misses it — or it acts every run (a sign it's chasing noise) — reconsider it.
- Did it double-act? Two runs acting on the same entity means the dedupe/cooldown state isn't working.
cursor/handled — but keep cooldowns so a reset doesn't spam people who were recently contacted.loop-guardrails.md).A copy-paste template for authoring your own marketing loop. Fill every one of the nine parts — a loop missing its state/idempotency, self-check, or stop/bail-out isn't a system, it's a way to do the wrong thing on a schedule.
Before you start, sanity-check that this should be a loop at all (see "When NOT to loop" in SKILL.md): it's recurring, signal-driven, and doesn't require human judgment to set strategy or creative direction each run.
### The <name> loop
- **Check cadence**: <how often it looks — match to how fast the signal changes, not how often you'd like an update>
- **Acts when**: <the action condition — what must be true to actually DO something vs. just check and skip. Most runs should skip.>
- **Purpose**: <the ONE outcome this loop exists to move>
- **Skills used**: <which marketing skills the loop orchestrates each run>
- **Loop body**:
1. <step — usually: pull data / diff vs. last run>
2. <step — identify what, if anything, crossed the action condition>
3. <step — draft or stage the response>
- **Self-check**: <the verification done BEFORE acting — is the signal real vs. noise/seasonality/tracking bug? Is the sample big enough to be significant?>
- **State / idempotency**: <what it remembers between runs — last-run marker, dedupe key, cooldown window, "already handled" set — so it doesn't double-act or re-nag the same people>
- **Stop / bail-out**: <when it skips, halts, escalates to a human, or disables itself — plus what it does on error. Include a human checkpoint before anything that spends money or publishes.>
- **Output**: <where results go — a file, a PR, a staged draft, a notification, a report>
If you can't answer 5, 6, and 7 concretely, the loop isn't ready to run.
Say you sell a freemium API tool and want to stop losing signups who never make their first API call.
### The first-call activation loop
- **Check cadence**: Daily
- **Acts when**: A user who signed up 48h ago still hasn't made a successful API call and isn't already in this nudge sequence.
- **Purpose**: Increase the share of new signups that reach first value (first successful API call).
- **Skills used**: `onboarding`, `emails`, `analytics`
- **Loop body**:
1. Pull signups from ~48h ago and their first-call status.
2. Filter to those with zero successful calls and no active nudge.
3. Draft a targeted "get your first call working" email (docs link, common blocker, offer to help).
- **Self-check**: Is "no call" a real activation gap, or a tracking gap (calls firing but not logged)? Confirm against server logs before emailing.
- **State / idempotency**: Track which users have entered this sequence; suppress anyone who has made a call since; one nudge per user per stage.
- **Stop / bail-out**: After 2 nudges with no call, stop and route to the broader re-engagement loop — don't keep emailing. Skip the run entirely if the events pipeline looks stale.
- **Output**: A staged activation email per qualifying user + a daily count of new activations.
Notice what makes it safe: the self-check guards against a tracking bug emailing active users, the state stops it re-nagging, and the stop caps attempts and hands off instead of looping forever.
Before you schedule a new loop, confirm:
SKILL.md.Once it runs, give it a few cycles and ask the "is this a vanity loop?" question: if nobody acts on the output, delete it.
When the user needs a comprehensive marketing plan for a client, a company they advise, or their own product. Also use when the user mentions "marketing plan," "growth plan," "GTM plan," "go-to-market plan," "AARRR plan,
View source ↗You are an expert marketing strategist operating at fCMO (fractional CMO) level. Your job is to produce a comprehensive, executable 12-month marketing plan for a specific client or company, structured by AARRR (Acquisition, Activation, Retention, Referral, Revenue), customized to their actual budget, team, stage, and capabilities, and cross-referenced with the full marketing-ideas library and the embedded 17-section current-state audit rubric.
The deliverable is a single Notion-paste-ready markdown document — the kind of strategy artifact a fractional CMO would present to founders. It must be specific to the client (not generic), exhaustive (covers every tactical surface area, not just what's prescribed), and operationally honest (reflects what their team can actually execute with their current stack and headcount).
Invoke this skill when:
Do not use when the user wants a tactical execution document for a single channel (use the channel-specific skill instead — emails, ads, seo-audit, onboarding, etc.), or when the user just wants marketing ideas without commitment to a plan (use marketing-ideas).
/marketing-plan {client-name-or-domain}
Examples:
- /marketing-plan quietude.app
- /marketing-plan acme-saas
- /marketing-plan (will prompt for client name)
On invocation, the skill reads ~/marketing-plans/{client-slug}/progress.md and resumes based on the state machine documented in references/methodology.md Step 1.1.2 (fresh → INIT → REVIEW → FINALIZE → finalized). Finalized plans are never silently overwritten — the user is asked whether to revise as v{N+1}, start fresh, or re-open a section.
The full workflow lives in references/methodology.md. Quick summary:
Read all available materials about the client. Pull data from any wired tools (Ahrefs, GA4 MCP, Stripe MCP, etc.). Conduct structured intake covering: client overview, ICP, current funnel state, funding state, team composition, marketing budget, channels currently active, what's already been done, what's in-flight, what's stuck, tooling stack. Save to research.md.
Use the embedded 17-section current-state rubric (references/current-state-rubric.md) as your scoring lens for Section 3 — score each section 0–5 against available materials.
Present each section's draft in chat. For each section you can:
- Approve as-is ("good," "next")
- Adjust ("change X to Y")
- Add observations ("also mention Z")
- Expand ("go deeper on this")
Save each confirmed section to the progress file as you go. The skill is resumable — if interrupted, run /marketing-plan client-name again to pick up at the next unfinished section.
Compile all 13 sections into final_plan.md. Run a verification pass: confirm cross-references (marketing-ideas idea numbers, related skills, MCP integrations) are accurate; check for machine-specific paths that shouldn't ship; ensure the brand voice matches what was captured in the strategic frame.
Optionally offer to publish to a shared GitHub repo (e.g., {client-org}/{client-context}/marketing/plan.md) if the user wants to share it with the team.
Full template lives in references/plan-template.md. The structure:
references/current-state-rubric.md).marketing-ideas cross-referenced to AARRR + client-specific status (Now / Q2 / Q3+ / Q4+ / Skip).AARRR replaces the older "channels and tactics" approach because it forces every recommendation to be funnel-stage-tagged, which makes the plan executable in priority order.
Full primer in references/aarrr-framework.md. Quick rule:
Brand and content are cross-cutting, not their own AARRR stage — they serve every stage.
The plan's "Current State" section scores the client against the embedded 17-section rubric. Full rubric in references/current-state-rubric.md — it's the source of truth, not a derivative of any external skill.
If the user already has a separately scored audit, ingest those scores directly into Section 3. Otherwise, score from available materials using the rubric as your lens — mark "scored from materials" in the section header so the team can push back where they have better data.
marketing-ideas — 139 proven marketing tactics. Section 12 of the plan cross-references every one to AARRR + client status. Detail in references/idea-cross-reference.md.product-marketing — Sets up the foundational .agents/product-marketing.md context file (positioning, ICP, voice). Read this first; Section 2 (Strategic frame) builds on it.onboarding, signup, emails, referrals, pricing, etc. The "Marketing operations stack" (Section 11) maps these to AARRR stages.The plan is opinionated about which skills serve which stages. Full mapping in references/ops-stack-mapping.md.
This is the differentiator of an fCMO-style plan vs. a generic marketing plan. The plan doesn't just say what to do — it says what skills and tooling execute it.
A small team + an fCMO + the marketing-skills library + MCP integrations can output the work of a 15–20-person traditional marketing org. The plan must show this stack explicitly, AARRR-stage by AARRR-stage.
Full mapping in references/ops-stack-mapping.md.
Every plan must include explicit "what changes when funding closes / when budget unlocks" reasoning. This makes the plan investor-friendly (founders mid-raise see what they're buying) and operationally honest (we're not pretending the team can spend $50K/mo on paid before the round closes).
Standard tiers in references/funding-stage-unlocks.md:
- Pre-seed / bootstrapped — $0–$2K/mo total marketing spend; organic only
- Seed close — $5–$15K/mo paid test budget; first marketing hire
- Seed deployment — $20–$50K/mo paid; second marketing hire
- Series A — $50–$150K/mo paid; performance + content + designer; international consideration
- Series B+ — $150K+/mo paid; brand campaigns; PR firm; full-stack marketing org
Use these as anchors. Adjust for category (consumer apps and ecommerce can spend more; deep-tech B2B may spend less).
The funding-stage anchors above tell you what's in the ballpark. To set the actual number defensibly, use one of two methods (full detail in references/budget-planning.md):
[(New ARR / (ARPC × 12)) × CAC] / annual retention rate. Best for fundraising or when the goal is fixed.Always add 10–20% experimental budget on top — CAC is the main dependency, and the experimental layer is what funds the next-channel investment before the current one plateaus.
For VC-backed Series A+ clients, anchor the 12-month outlook against the 3-3-2-2-2 rule (3× in years 1–2, 2× in years 3–7 from $1M ARR).
Pitch decks show hockey sticks. Real growth is a series of S-curves with plateaus between them. Full framework in references/growth-patterns.md. Key implications for the plan:
Strategy lives in-house. Execution can — and often should — be outsourced. Full framework in references/team-and-agency-model.md. Three implications for every plan:
A generic plan is a failed plan. Every plan must explicitly customize for:
If you can't confirm any of these in INIT, list them in Section 13's "Open decisions" — never gloss over them. CAC unknown is the highest-impact open decision — every revenue projection depends on it.
Plan structure stays consistent. What changes:
- B2B SaaS — Acquisition leans on SEO + content + outbound + LinkedIn. Activation = signup + product trial. Retention = product engagement + CSM motion. Referral = customer advocacy. Revenue = expansion / NRR.
- D2C consumer app — Acquisition leans on App Store + paid social + influencer + PR. Activation = onboarding + first session + paywall. Retention = lifecycle email + push. Referral = sharing mechanics. Revenue = subscription + upsell.
- Hardware-led — Acquisition leans on PR + retail + Amazon + Shopify SEO. Activation = unboxing + setup + first use. Retention = software companion + community. Referral = gifting + reviews. Revenue = blended LTV hardware + accessories + subscription.
- Marketplace — Activation has two sides (supply + demand). Retention is repeat transaction frequency. Revenue is take-rate × GMV.
- Developer tool — Acquisition leans on technical content + DevRel + documentation SEO. Activation = first build / first integration. Retention = depth of integration. Referral = team adoption.
Detail in references/client-types.md.
What separates a good plan from a generic one:
Good plan signals:
- Every move names the AARRR stage it serves
- Every recommendation is anchored in real client data (their actual budget, their actual team, their actual current channels)
- The 90-day roadmap has owners, not just actions
- The funding-stage section explains what changes when the next round closes
- The ops stack section names specific skills + MCPs per move
- The idea bank shows what we're not doing and why (skipped ideas with rationale)
- The exec summary can stand alone — could be lifted into an investor update
- Open decisions are explicit, not glossed over
Failure modes to avoid:
- Listing tactics without sequencing
- Recommending things the team can't execute at current size
- Pretending paid budget exists before the round closes
- Glossing over uncomfortable metrics (e.g., churn) instead of naming them as open decisions
- Generic language ("build a community," "improve SEO") without specific moves
- Ignoring brand voice — every plan section must respect the client's voice rules
- Padding the plan with skills/ideas the client doesn't actually need
- Not acknowledging work the team has already done
The final deliverable is a single markdown file: ~/marketing-plans/{client-slug}/final_plan.md.
Headers (## 1. Executive summary, etc.) are H2 for clean Notion paste. Tables for any structured comparison (RACI, idea bank, ops stack). Status legend for the idea bank. Internal references to other sections use §N (e.g., "see §5 for Activation detail").
Length expectation: ~8,000–12,000 words for a comprehensive plan. Shorter is fine if the client is early-stage with limited surface area; longer is fine if the client has years of history to acknowledge.
~/marketing-plans/
└── {client-slug}/
├── materials/ # Client-provided files (decks, audit output, brand-voice doc, etc.)
├── research.md # Research record written during INIT
├── progress.md # State machine — phase, current_section, approved artifacts, plan_version
├── sections/
│ ├── 01.md # Each approved section saved as a canonical artifact
│ └── ... # Zero-padded so they sort in order
└── final_plan.md # Compiled deliverable (FINALIZE output)
The full schema for progress.md and the resumption decision tree live in references/methodology.md Steps 1.1.1 and 1.1.2.
product-marketing — Run first. Captures positioning, ICP, voice in .agents/product-marketing.md so every section of the plan references the same foundation.marketing-ideas — Source of the 139 tactics in Section 12.customer-research — Deepens the ICP and voice-of-customer inputs that feed Section 2 (Strategic frame).onboarding — Deep work on Section 5 (Activation).emails — Deep work on Section 6 (Retention) + onboarding emails in Section 5.referrals — Deep work on Section 7 (Referral).pricing — Deep work on Section 8 (Revenue).seo-audit / ai-seo / programmatic-seo — Deep work on the SEO portion of Section 4 (Acquisition).ads / ad-creative — Deep work on the paid portion of Section 4 once budget unlocks.launch — Deep work on launch moments inside Section 4 / Section 9.The full intake questionnaire lives in references/methodology.md. The most important questions:
Default to comprehensive. Founders share a plan with their team and investors; brevity here is false economy. A 10,000-word plan with the right structure is more useful than a 3,000-word plan that misses the ops stack or the idea bank.
That said: don't pad. Every section should be dense, not bloated. If a section has nothing to say, write that explicitly — "Q4+ — long-game / not in scope for this 12-month plan" is honest and useful.
This plan is written for founders who are sharp, busy, and skeptical of marketing-speak. Write like a thoughtful colleague, not a deck-slide-writer. No jargon for jargon's sake. Direct claims, named tradeoffs, explicit assumptions. When unsure, name the open question rather than guessing.
The exec summary should be short enough to read in 60 seconds. The rest should reward deep reading.
AARRR (Dave McClure's "pirate metrics") is the spine of every plan produced by this skill. This doc is the primer + the decision rules for when each stage gets prioritized.
| Stage | Question | Common metrics |
|---|---|---|
| Acquisition | How do strangers become aware of us? | Visits, MQLs, signup-page sessions, app-store visits, CAC by channel |
| Activation | Once they try us, do they have an experience that converts? | Signup completion rate, time-to-value, % completing first key action, trial → paid rate |
| Retention | Do they stay and deepen? | DAU/WAU/MAU, week-1/4/12 retention, churn |
| Referral | Do retained users bring more users? | Viral coefficient, NPS, ambassador attribution |
| Revenue | What do they pay, who pays, how does it compound? | ARPU, LTV, expansion revenue, ARR / MRR |
Signup boundary rule. Signup intent (a stranger landing on the signup page) is Acquisition. Signup completion and everything after (first key action, trial-to-paid) is Activation. Apply this rule consistently across all docs and the plan template.
Three reasons.
1. Funnel-stage tagging forces prioritization. Without AARRR, marketing plans become channel-organized ("here's the SEO plan, here's the social plan, here's the paid plan"). Channels can address multiple stages; tagging by stage instead asks the more useful question: what stage of the funnel is the binding constraint right now?
2. Fix the leak before pouring water in. The Activation/Retention question ("does the funnel convert at acceptable rates given exposure?") is usually higher leverage than the Acquisition question ("how do we get more exposure?"). AARRR sequencing surfaces this naturally.
3. The Revenue / Referral conversation is honest. Most marketing plans bury monetization under "growth" and treat referral as wishful thinking. AARRR forces explicit treatment of both.
A common mistake: making "Brand" or "Content" the sixth bucket. They're not — they serve every stage.
In the plan, brand/content shows up as the strategic frame (Section 2) and cross-cutting in Section 11's ops stack — never as its own AARRR section.
For every client, one or two AARRR stages will be the binding constraint. The plan sequences moves there first.
Decision rules:
The diagnostic question: Where is the gap between TAM-level awareness and current funnel volume? What channels are saturated by competitors vs. open?
Common Acquisition moves:
- SEO content strategy (organic compounding)
- Founder-led channels (LinkedIn, X, Substack for B2B; Instagram/TikTok for D2C)
- Paid acquisition (when budget unlocks)
- App Store / Play Store / marketplace listing optimization
- PR and credibility-anchor amplification
- Events (live, webinar, conference speaking)
- Partnerships (newsletter swaps, integration co-marketing, reseller / agency partners)
- Hardware / commerce surface (Shopify SEO + Amazon for hybrid businesses)
- B2B sales support (case studies, partner pages, vertical content)
Sequencing principle: Build the organic compound first (SEO + founder-led + content + PR amplification + ambassadors). Only layer paid on top of a working organic baseline. Premature paid amplifies what's broken.
The diagnostic question: Where in the user's first session do they decide "this works for me" or "this doesn't"? What stops them from reaching that moment?
Common Activation moves:
- Bedrock fixes (broken gates, broken signup steps, broken paywall)
- Onboarding tests / rebuild (often the most leveraged single move)
- App Store listing rewrite (the threshold to the trial)
- Lifecycle Flow ship order (when to ship onboarding emails)
- Paywall structure + trial length
- Free → paid bridge (in-app upsells, soft paywalls)
Sequencing principle: Get to first felt value as fast as possible. Everything that adds friction between "user opens app" and "user has the experience that converts them" is a candidate to cut.
The diagnostic question: Why do users churn? What would have made them stay? What's the "second moment of value" after the first one?
Common Retention moves:
- Lifecycle email flows: onboarding, lapsed user re-engagement, post-purchase, win-back
- Subscription / preference centers
- Churn reconciliation (often metric definitions don't match across surfaces)
- Hardware → software activation paths (for hybrid businesses)
- Annual plan defaults / pricing structure (cross-cuts Revenue)
- Support as marketing (high-touch moments that drive stories)
- Community + practitioner networks
Sequencing principle: Ship lifecycle flows in the order their content is most stable. Hardware post-purchase flows ship first (they don't reference in-app screens that might change). Onboarding emails ship last (they reference UI that might change). Win-back is a quarterly campaign, not a one-time flow.
The diagnostic question: Is there inbound referral interest that isn't being captured? What's the share-after-value moment that's natural to the product?
Common Referral moves:
- Ambassador / affiliate program (start with inbound interest, not cold recruitment)
- Share-after-value moments built into the product (reflection prompts, milestone celebrations)
- Founder amplification (founder as referrer-zero)
- Long-game expert / Guides / certified-host networks (for category-creating businesses)
- Gifting flows (consumer / hardware)
- Two-sided referrals (reward both referrer and referred)
Sequencing principle: Lead with whoever is already raising their hand. If there are 5 inbound ambassadors, launch with those 5 — don't wait for a "complete program." Iterate based on what they tell you.
The diagnostic question: Is the company underpricing? Underpackaging? Missing an upsell? What's the "right" price discipline given LTV and brand voice?
Common Revenue moves:
- Pricing audit (what's actually charged today vs. listed?)
- Annual plan defaults
- Hardware → software bundling formalization
- Storefront / commerce page optimization
- B2B case studies + sales material
- Long-term value pool flags (data, expansion, enterprise) — flagged not executed
Sequencing principle: Run the pricing audit before testing changes. Surprisingly often, the "implied" pricing on the dashboard doesn't match the listed price — discounts, trials, or plan mix distorts the read. Surface the ground truth first.
Some moves clearly belong to one stage. Others span. The rule:
Assign to the stage where the move's primary measurable impact lands.
Examples:
- "Rewrite App Store listing in voice" — spans Acquisition (organic discovery) and Activation (threshold to trial). Primary impact = Activation (trial conversion rate). Assign to Activation, mention crossover.
- "Eye mask Shopify page rewrite" — spans Acquisition (organic search for sleep mask) and Revenue (sale conversion). Primary impact = Revenue (transaction). Assign to Revenue, mention crossover.
- "Alex's LinkedIn cadence" — Acquisition (top of funnel for D2C subscribers).
- "Customer.io Flow 6 (eye mask post-purchase)" — Retention (deepens hardware buyer engagement) with crossover to Activation (hardware → app premium activation path).
When in doubt: where would removing this move hurt the most? Assign there.
For most clients, the plan won't have equal volume across stages. That's fine — and worth surfacing as a diagnostic.
If a plan ends up evenly distributed across all five stages, the diagnostic was probably weak — re-examine the funnel state intake to find where the binding constraint is.
Always present AARRR in order (Acquisition → Activation → Retention → Referral → Revenue) regardless of priority order.
This is for the reader's mental model. Founders expect the funnel to flow top-to-bottom. If Retention is the most-leveraged stage but you lead with Retention, the reader has to context-switch.
To signal priority, use the executive summary (Section 1) — name the biggest bets there. The AARRR breakdown then walks the funnel in order, with the most leverage-positive section being the longest and most-detailed.
The problem with most SaaS marketing budgets is that they're pulled out of thin air — a number that hopefully doesn't constrain growth too much, but doesn't anchor in customer-acquisition economics either. The result: when someone asks "why this number?" there's no answer.
Two scientific methods solve this. Use one (not both) in Section 8 (Revenue) and Section 10 (12-month outlook) of every plan.
Excerpted and adapted from Founding Marketing by Corey Haines.
Direction: budget → revenue goal.
You start with what the company can comfortably spend on marketing, then forecast what revenue that spend can plausibly generate.
| Posture | % of ARR | When to use |
|---|---|---|
| Conservative (profit-preserving) | 5% | Established business focused on profit distribution; bootstrapped; founder-paid customer base |
| Standard growth | 15–25% | Most healthy SaaS in the seed-to-Series-A range |
| Aggressive growth (deploying raised capital) | up to 40% | Recently funded round, mandate to deploy fast, board accepts burn |
For reference: public SaaS companies routinely report sales-and-marketing spend between 20% and 55% of revenue (Zoom historically ran between 20% and 55% across years).
Business at $1M ARR, 5% allocation:
Business at $1M ARR, 40% allocation:
Direction: revenue goal → budget.
You start with the revenue goal and work backward through the unit economics to derive the budget required to hit it. Best for:
Marketing budget = [(New ARR / (ARPC × 12)) × CAC] / annual retention rate
Step 1 — How much new ARR per customer?
ARPC × 12 = $50 × 12 = $600 ARR per new customer
Step 2 — How many new customers do we need?
$1,000,000 / $600 = 1,667 new customers
Step 3 — What's the raw acquisition cost?
1,667 × $100 CAC = $166,700
Step 4 — Account for churn (15% annual = 85% retention)
$166,700 / 0.85 = $196,118 (round to $200K)
When someone asks how you got to the budget, walk them through the four steps. It's defensible.
The four steps each correspond to a real economic reality:
- Step 1 converts MRR-language into the ARR-language a board talks in
- Step 2 names the customer count, which is what the funnel actually has to deliver
- Step 3 anchors the budget in the cost of acquisition
- Step 4 acknowledges that churned customers don't count toward net new ARR, so the budget needs to cover the gap
Always add 10–20% as "experimental budget" on top of the formula output. CAC is the main dependency; if CAC comes in 50% higher than estimated, the cascading effect is missing the revenue goal. It is much cheaper to overestimate CAC than to underestimate it.
The experimental budget also funds the experiments that find your next channel before your current one plateaus (see growth-patterns.md — channel S-curves).
Once a company has crossed $1M ARR and taken a Series A, the implicit benchmark VCs expect is:
| Year | ARR multiple | Cumulative ARR (from $1M start) |
|---|---|---|
| Year 0 | — | $1M |
| Year +1 | 3× | $3M |
| Year +2 | 3× | $9M |
| Year +3 | 2× | $18M |
| Year +4 | 2× | $36M |
| Year +5 | 2× | $72M |
| Year +6 | 2× | $144M |
| Year +7 | 2× | $288M |
That's the 3-3-2-2-2 rule. Useful when:
Most companies miss it. That's fine. Knowing the benchmark gives the team a defensible reason to either match it or explicitly choose not to.
If there's no historical CAC, use a baseline: one year of revenue from the smallest paid plan. Deploy the budget, capture actual CAC data, replace the baseline with the measured number for the next planning cycle.
For an established CAC calculation, CAC must be blended. Include:
Then divide by the number of new customers acquired in the period. That blended number is the one to use in either budgeting method.
The mistake to avoid: calculating CAC from paid ad spend alone. A company that "doesn't run ads" still has a CAC — it's just hidden in the content team, the founder's time, the SEO contractor, the conference booth.
This whole framework derives a budget and a revenue goal — not a 12-month month-by-month forecast accurate to the dollar.
Unless the company is publicly traded, all forecasts are educated guesses. No startup under $100M ARR reliably hits forecasts to the month. The honest framing for the plan:
What's actionable: how to deploy the budget, what concrete moves to execute, what to adjust when real data comes in.
What's not actionable: trying to forecast traffic, pipeline, retention curves, conversion rates, and channel mix all down to the decimal point and expecting that forecast to hold. Founders who over-engineer the forecast tend to spend the plan period explaining variance instead of executing.
Rule for the plan: the budget number is honest. The annual goal is honest. The month-by-month projection is illustrative.
| Section | What to include |
|---|---|
| 3 (Current state) | Current monthly marketing spend broken down by line (paid, tools, content, headcount, retainers). Compute current %-of-ARR allocation. |
| 8 (Revenue) | The unit-economics table (CAC, ARPC, churn) that feeds whichever budget method you're using. |
| 10 (12-month outlook) | Apply Method 1 or Method 2 to derive the 12-month budget and the resulting revenue goal. Anchor against the 3-3-2-2-2 rule if Series A+ and VC-backed. |
| 11 (Ops stack) | Show the budget allocation across the AARRR stages — what % to Acquisition, Activation, etc. The ops-stack mapping informs which line items grow when the next funding tier unlocks. |
| 13 (Open decisions) | If CAC is unknown or contested, flag it as the highest-impact open decision — every other number depends on it. |
For most plans in the seed-to-Series-A range, Method 2 is more useful — it forces the conversation about whether the goal is funded.
The 13-section plan structure stays consistent across client types. What changes is the content emphasis within each section. This doc names the dominant patterns by client archetype.
Acquisition heavy:
- SEO is the dominant top-of-funnel motion (people search for solutions)
- Content marketing (blog, knowledge base, comparison pages) drives MQLs
- LinkedIn for both organic founder presence and paid
- Outbound (cold email + LinkedIn) often complements inbound
- Events (conferences, webinars) for high-ACV products
Activation:
- Signup → trial → first key action (PLG products)
- Trial → demo → POC (sales-led products)
- Empty states matter — guide users to first value action
Retention:
- Product engagement metrics (DAU, feature adoption)
- Customer success motion (CSM team for higher ACV)
- Lifecycle emails focused on feature discovery, value moments
Referral:
- Customer advocacy programs
- Partner / integration co-marketing
- G2 / Capterra reviews
- Champion-to-buyer expansion
Revenue:
- Expansion / NRR is often the biggest growth lever
- Tier upgrades, seat expansion, usage-based add-ons
cold-email, programmatic-seo, competitors, seo-audit, ai-seoads weighted toward LinkedIn + Googleemails for trial nurture + lifecyclepricing for tier optimizationAcquisition:
- App Store Optimization (ASO) is the highest-leverage non-site asset
- Paid social (Meta, TikTok) often dominant once budget exists
- Apple Search Ads for high-intent App Store traffic
- Influencer + content creators
- PR + endorsements
Activation:
- Onboarding is the dominant activation surface
- Time-to-value must be minutes, not hours
- Paywall structure + trial length critical
Retention:
- Lifecycle email + push
- In-app reminders (carefully — overuse = churn)
- Subscription preference center
- Win-back campaigns
Referral:
- Built-in sharing (share-a-month flow)
- Two-sided referrals
- Influencer / creator ambassadors
Revenue:
- Annual plan default is the biggest single move (compresses MRR but improves LTV)
- Tier optimization (Free → Premium → Premium+)
- In-app upsells
onboarding, paywalls, emailsads, ad-creative (heavy creative iteration)referralspricing for annual default + tier consolidationAcquisition:
- Shopify storefront SEO (hardware product pages target consumer search)
- Amazon listing (high-discovery, takes margin)
- PR amplification (hardware is photogenic — high-profile influencer endorsements move volume)
- Paid social for hardware (Meta + Instagram, eye-catching creative)
Activation:
- Two activations to track: hardware unboxing experience + software signup
- Hardware → software activation flow is the bridge
- Concierge setup for high-value hardware buyers
Retention:
- Hardware post-purchase lifecycle (different from app onboarding)
- Software companion drives stickiness
- Community / practitioner network around hardware
Referral:
- Hardware gifting flows (high WOM for physical products)
- Eye-catching hardware drives organic social sharing
- Reviews on Shopify + Amazon
Revenue:
- Blended LTV math is critical (hardware margin + software recurring)
- Bundle strategy (hardware buy → free Premium for X months)
- Annual plan default for software
seo-audit for Shopify product pagesemails for both hardware post-purchase and software lifecyclereferrals with gifting layerpricing for blended-bundle mathads with creative-heavy Meta presenceAcquisition:
- Two funnels — supply and demand
- Supply often acquired through outbound / partnership / cold email
- Demand often acquired through SEO / paid / content
- City-by-city programmatic SEO common
Activation:
- Supply activation: first listing posted, first response sent
- Demand activation: first purchase / first match / first transaction
- Both sides need their own onboarding
Retention:
- Repeat transaction frequency
- Supply utilization (% of listings active)
- Demand habit (DAU / MAU)
Referral:
- Supply → supply (refer other providers)
- Demand → demand (refer other buyers)
- Cross-side referrals are weaker
Revenue:
- Take-rate optimization
- Premium tier (better matching, lower fees)
- Lead-gen vs. transaction-fee monetization
programmatic-seo for city pages, vertical pagescold-email for supply-side recruitmentreferrals for both sidespricing for take-rate decisionsAcquisition:
- Technical content + docs SEO
- DevRel (conferences, talks, community)
- GitHub presence + npm/pip/etc. discovery
- Hacker News + Reddit + dev Twitter
Activation:
- First build / first integration is the activation event
- Time-to-Hello-World matters
- Documentation = onboarding for dev tools
Retention:
- Depth of integration (using more of the product)
- Team adoption (one user → entire org)
- Active project count
Referral:
- Star count on GitHub (semi-organic)
- Recommendation in technical forums
- Conference talks mentioning the tool
Revenue:
- Free → paid conversion when usage exceeds limits
- Team plans, enterprise tiers
- Support / SLA upsells
programmatic-seo for docsadscontent-strategy + technical contentcold-email to engineering leads at target companiesAcquisition:
- Academic publishing + peer-reviewed studies
- Conference speaking (academic + industry)
- Investor / advisor introductions
- PR via credibility hooks
Activation:
- Pilot programs / proof-of-concepts
- Concierge setup with high-touch onboarding
- Educational webinars / training
Retention:
- Customer success heavily
- Co-publication with customers
- Community of practice
Referral:
- Academic / clinical references
- Conference panel features
- Case studies with named institutions
Revenue:
- Pilot → paid expansion
- Institutional contracts (multi-seat / multi-year)
- Compliance / certification upsells
product-marketing, sales-enablement, pricingcold-email to specific researchers / practitionersAcquisition:
- Paid social (Meta, TikTok) often dominant
- Shopify SEO for product pages
- Amazon listings
- Influencer + creator partnerships
Activation:
- First purchase is the activation event
- Cart abandonment recovery
- Trust signals on checkout (reviews, returns, shipping)
Retention:
- Post-purchase lifecycle
- Loyalty programs
- Email + SMS for repeat purchase
Referral:
- Gifting flows
- Refer-a-friend programs
- Reviews + UGC
Revenue:
- AOV optimization (bundles, upsells)
- Customer LTV optimization (repeat purchase frequency)
- Subscription option for repeat purchases
ads + ad-creative (heavy weight)emails for post-purchase + abandoned cartreferrals with giftingpricing for bundles + subscription optionWhen you start drafting Sections 4–8 (AARRR), identify the client's archetype (or hybrid if applicable) and lean into the patterns above.
Hybrid cases are common. Quietude is "Hybrid hardware + software" with significant overlap to "Deep-tech / scientific / clinical" (because of the peer-reviewed study + clinical positioning). The plan blends emphases from both archetypes.
When in doubt, lead with the archetype that best fits the primary monetization model. Quietude's primary monetization is software subscription (with hardware as the wedge), so the D2C consumer app + hardware-hybrid patterns dominate, with deep-tech credibility moves layered in.
Some clients defy archetype:
- Content / media businesses — neither SaaS nor commerce; ad revenue or subscription model
- Social networks — own category, network effects dominate
- Real estate / events — physical + service model
For these, identify the closest archetype and adjust. Don't force-fit — name the deviation in the plan's Strategic Frame.
This 17-section rubric is the source of truth for Section 3 ("Current State") of every marketing plan. Score each section 0–5 from available materials, then write a 2–4 sentence "shape interpretation" that names where strengths and gaps cluster.
From rich materials. When the team has shared decks, prior content audits, a brand voice doc, kickoff transcript, app store and analytics snapshots — score each section from those artifacts. Mark "scored from materials" in the section heading so the team can push back where they have better data.
From a separately scored audit. If the team has already run a scored current-state assessment (in any format), ingest those scores directly. Don't redo the work — note the date the rubric was scored and flag any sections where material has shifted since.
Either way, the output is the same: a 17-row scored table, a total out of 85, and a shape paragraph.
What's scored: Clarity of category claim, differentiation, alignment across surfaces (homepage, app store, pitch deck, founder messaging).
Score guide:
- 0 = No positioning anywhere
- 2 = Inconsistent across surfaces; team can't articulate it on demand
- 4 = Clear, original, mostly consistent; minor surface gaps
- 5 = Distinctive, category-defining, every surface aligned
Maps to AARRR: Cross-cutting — feeds every stage.
What's scored: Depth and recency of customer research, ICP clarity, voice-of-customer capture.
Score guide:
- 0 = No formal research, only founder intuition
- 2 = Some research but stale or one-off
- 4 = Active research practice, customer language captured
- 5 = Continuous research, customer language flows into copy / product / messaging
Maps to AARRR: Cross-cutting — feeds especially Acquisition (channel choice) and Activation (onboarding voice).
What's scored: Headline clarity, voice alignment, conversion architecture, mobile experience.
Score guide:
- 0 = Generic / broken / off-brand
- 2 = Functional but underperforming; voice mostly absent
- 4 = Clear, voice-aligned, converting; minor optimization opportunities
- 5 = Distinctive, converts strongly, fully voice-aligned
Maps to AARRR: Acquisition + Activation.
What's scored: Existence and quality of dedicated product / pricing / feature pages. Are SKUs documented? Is pricing scannable? Are upsells visible?
Score guide:
- 0 = No dedicated pages
- 2 = Pages exist but are stale or off-voice
- 4 = Quality pages for primary products; gaps on secondary
- 5 = Every product, tier, and upsell has a high-converting page
Maps to AARRR: Acquisition + Revenue.
What's scored: Landing pages for specific campaigns, channels, or use cases. /partner, /science, /ambassadors, /eye-mask types of pages.
Score guide:
- 0 = No conversion pages
- 2 = One or two exist; rest of needed pages missing
- 4 = Most needed conversion pages exist; quality is good
- 5 = Full conversion page library, each high-converting
Maps to AARRR: Acquisition + Activation.
What's scored: Existence of "vs. {competitor}" pages, comparison content. Does the brand acknowledge alternatives, or pretend they don't exist?
Score guide:
- 0 = Nothing — actively avoiding competitor mentions
- 2 = Some content exists but is weak or hidden
- 4 = Solid comparison pages for top 2–3 competitors
- 5 = Comprehensive comparison library; SEO-targeted; high-converting
Maps to AARRR: Acquisition (consideration-stage SEO + sales enablement).
What's scored: Blog, knowledge base, science page, whitepapers, research, founder essays, podcast.
Score guide:
- 0 = No content surface
- 2 = Blog exists but is stale or thin
- 4 = Active content production; multiple formats
- 5 = Content is a moat — proprietary research, named pillars, daily volume
Maps to AARRR: Acquisition.
What's scored: New user onboarding (in-app + email). Time-to-value, completion rate, brand-voice alignment.
Score guide:
- 0 = No onboarding flow
- 2 = Onboarding exists but is broken, off-voice, or underperforming
- 4 = Solid onboarding; clear bottlenecks identified
- 5 = Tested, optimized, on-brand; activation rate at category top quartile
Maps to AARRR: Activation.
What's scored: Existence and quality of lifecycle email programs. Welcome / onboarding / post-purchase / lapsed / win-back.
Score guide:
- 0 = No lifecycle email
- 2 = Some flows exist but drafted not live, or live but stale
- 4 = Core flows live and performing; gaps on secondary flows
- 5 = Full lifecycle live, segmented, performing above category benchmarks
Maps to AARRR: Retention (+ Activation for onboarding emails).
What's scored: Sales decks, one-pagers, demos, case studies, pricing sheets. (For B2B / hybrid companies — for pure D2C, this can be marked N/A or scored low without implication.)
Score guide:
- 0 = No sales material
- 2 = Founder uses a deck but other material is thin
- 4 = Solid sales kit; reps can self-serve content
- 5 = Comprehensive material; updated quarterly; objection-handling library exists
Maps to AARRR: Acquisition + Revenue (B2B).
What's scored: Voice, tone, vocabulary, message hierarchy across surfaces. Is the brand voice documented, consistent, distinctive?
Score guide:
- 0 = No voice documented; surfaces inconsistent
- 2 = Voice exists in founder's head but isn't operationalized
- 4 = Documented voice; mostly consistent across surfaces
- 5 = Distinctive voice; documented; every surface respects it; voice is a moat
Maps to AARRR: Cross-cutting.
What's scored: Pricing structure clarity, packaging logic, recent pressure-testing, listed vs. effective price reconciliation.
Score guide:
- 0 = Pricing not pressure-tested in over a year; unclear structure
- 2 = Listed pricing exists but plan mix / discounting muddles the read
- 4 = Clear pricing; recent tests; LTV math known
- 5 = Pricing tested quarterly; packaging optimized; expansion levers known
Maps to AARRR: Revenue.
What's scored: Test cadence, instrumentation, A/B history, statistical rigor.
Score guide:
- 0 = No tests run; no instrumentation
- 2 = Some ad-hoc tests; no statistical rigor
- 4 = Regular test cadence; some wins
- 5 = Continuous testing program; experimentation culture; documented wins
Maps to AARRR: Cross-cutting (most impactful at Activation + Revenue).
What's scored: Quality of past launch executions. Product launches, feature launches, campaign launches.
Score guide:
- 0 = No structured launches; "soft launches" only
- 2 = Some launches but uneven execution
- 4 = Solid recent launches; playbook exists
- 5 = Repeatable launch motion; Product Hunt #1s; press coverage on demand
Maps to AARRR: Acquisition + Activation.
What's scored: Paid acquisition state. Active campaigns, channels, CAC tracking, creative quality.
Score guide:
- 0 = No paid acquisition
- 2 = Some paid but unstructured / wasteful
- 4 = Paid is firing across 2–3 channels with positive unit economics
- 5 = Sophisticated paid stack; CAC/LTV understood; creative iterated weekly
Maps to AARRR: Acquisition.
Note: For pre-seed clients with no paid budget, score this 0 without treating it as a weakness — it reflects the funding stage, not a marketing failure.
What's scored: Organic search performance. Domain rating, ranking keywords, organic traffic, content cluster strategy.
Score guide:
- 0 = No SEO; new domain or zero-authority
- 2 = Some content but no strategy; ranks for brand only
- 4 = Established content clusters; growing organic traffic; DR 25+
- 5 = SEO is a moat; DR 40+; thousand+ ranking keywords; consistent content production
Maps to AARRR: Acquisition.
What's scored: Geographic expansion, language localization, region-specific pricing.
Score guide:
- 0 = US/EN only; no international consideration
- 2 = International users exist but aren't served (one language, one currency)
- 4 = Multi-language, region-specific pricing, GTM playbook for new markets
- 5 = International is a strength; multi-region revenue; localized GTM
Maps to AARRR: Acquisition.
Note: For most early-stage companies, internationalization scores 0–1 and that's appropriate. Don't penalize early-stage companies for not having international playbooks yet.
Total = sum of all 17 scores. Out of 85.
The total matters less than the shape. After the scoring table, write a 2–4 sentence "shape interpretation":
"High in {strong sections}, low in {weak sections}. That shape is the gap the rest of the plan closes — Sections X (AARRR stage) is the longest because that's where the gap is widest."
Some sections are easier to score from outside than others. Subjectivity tier:
For subjective sections, write the rationale into the "Note" column so the team can push back if they disagree.
If the team already has scored output from any current-state assessment, ingest those scores directly — don't redo the work. Treat that prior scoring as the ground truth for sections it covers.
If the prior scoring was done weeks ago and material has shifted since (new shipped flows, new content live, repositioning, etc.), note "scored on YYYY-MM-DD; material has shifted since" and update any specific scores you have current evidence for.
This is the canonical reference example for the /marketing-plan skill. It's based on a real fCMO engagement for a hybrid hardware-and-software wellness platform. Names, domains, and identifying details have been changed — the client is called "Quietude" here, and the team members have been renamed (Alex / Sam / Casey / Devon). The funnel numbers, budget, and structural lessons preserve the shape of the original engagement so the example retains its teaching value.
Use this as the "what good looks like" reference when drafting a new plan. The structure, tone, depth, and operational specificity are the bar to clear.
Quietude's archetype: Hybrid hardware + software with deep-tech / clinical credibility layer. See references/client-types.md for archetype patterns.
Funding-stage context: Pre-seed-close (mid-raise on $3M seed). Tier 1 per references/funding-stage-unlocks.md. $0 paid budget; organic + lifecycle + ambassador only.
What was strong about this plan:
- Strategic frame (Section 2) leaned on the founder's own meditation-vs-regulation framing as the content pillar
- Current state (Section 3) included the 17-section audit rubric scored against existing materials (no formal audit run)
- 90-day roadmap (Section 9) had owner-assigned moves, not just actions
- Ops stack (Section 11) included a concrete operational proof-point (Customer.io MCP used live by non-technical founder on the kickoff call)
- Tactical idea bank (Section 12) cross-referenced all 139 marketing-ideas to AARRR + Quietude-specific status, including 23 explicit skips with rationale
Prepared by: Casey Reed (fCMO)
For: Alex, Sam, and the Quietude team
Date: 2026-05-27
Status: Draft v1 — for team review
Quietude has built something rare: a clinically validated, brand-coherent, founder-led product in a category that doesn't yet have a name. The opportunity in the next twelve months is not to invent a marketing engine from scratch — it's to convert the existing organic gravity into a measurable, repeatable funnel, then layer paid acquisition on top of that funnel once the seed round closes.
Three big bets, ranked by leverage:
What twelve months looks like, plausibly:
The 90-day priorities (which the rest of this doc operationalizes):
quietude.app, publish Pillar 1 hub + 3 spokes, publish the peer-reviewed psychophysiology study landing page.Everything else compounds on top of those six.
This section distills positioning, ICP, and brand voice into what the team needs to keep in mind while executing. Full detail lives in marketing-os.md, icp.md, and sound-philosophy.md.
A nervous system intelligence platform — clinically validated spatial audio + AI reflection companion (Mira) + hardware + venue installations + practitioner network. "We start with sound. We expand to every sense. We end with cities."
Quietude doesn't fit the meditation app category, the focus audio category, or the sleep tech category. The brand makes a stronger claim: bottom-up nervous system regulation through spatial audio, with clinical evidence as proof and somatic credibility as defense.
The category-defining frame, per Alex (2026-05-19): Meditation is top-down. Quietude is bottom-up. Meditation uses the mind to command the body — mental kung fu that fails the very people most likely to need help, because the prefrontal cortex is offline when stressed. Quietude enters through the brainstem, before the thinking mind. The body responds before it has to try. (Full content-pillar treatment in meditation-vs-regulation.md.)
This is the single most important strategic message. It belongs in App Store copy, onboarding, lifecycle email, SEO content, ambassador talking points, and the seed deck.
Overstimulated high-achieving professionals, 25–45, urban (Bay Area, NYC, London, Berlin, Austin). Tech workers, founders, creators, academics, designers, consultants. Often neurodivergent (ADHD, HSP, gifted). Sophisticated wellness buyers — already invested heavily in their inner life.
Their stated problem: "I can't shut my brain off. I've tried meditation apps. They don't work."
Their real problem: Overstimulation, not under-motivation. Their gift (quick thinking) became a curse. They need permission to stop optimizing — including their rest.
What they're actually buying: the feeling of stability, sensory indulgence, beautiful rituals, effortless effectiveness, a luxurious shortcut to the genius they can't access in chaos.
B2B seeds the market. D2C harvests. A venue install puts Quietude in front of ~20K people/year at ~$17K cost → 5% convert to subs → ~$430K/year per venue. Six compound channels (referral, Guides, content, home hosting, PR, community) make CAC approach zero by Year 3. Year 5: 75% of new subs come from near-zero-cost channels.
fCMO scope per kickoff: D2C-led. Alex owns B2B sales through events/network/founder credibility. The fCMO leverage is on the app/hardware D2C side. This plan reflects that split — B2B is acknowledged as the harvest engine but not treated as primary work surface.
Per Marketing OS:
- Tone. Authoritative yet accessible. Intimate yet professional. Revolutionary yet grounded. Authority comes from lived experience, not explanation.
- Speak from the body, not the mind. Every sentence restores somatic safety and orientation. Language opens space rather than closing meaning.
- YES vocabulary: Aliveness, inner life, nervous system, spatial sound, resonance, somatic safety, embodied clarity, natural rhythm, orientation, initiation, truth-telling.
- NO vocabulary: Zen, chill, vibes, "high-vibe," spiritual bypass, meditation clichés, didactic/explainer language, "let me explain why this works."
- Core method: Initiatory Reflection. Writing's purpose isn't to explain or convince — it's to shift the reader's internal state. The result should be "something in me moved," not "I understand this concept."
- CTA rule: Never pressure. "We do not remind. We invite."
This rule constrains every piece of copy across every AARRR stage. When in doubt: rewrite from the body.
This is what we're starting from — team, budget, what's already in motion, what's stuck, scored against the CF Marketing Audit 17-section rubric.
| Person | Role | Marketing surface area |
|---|---|---|
| Alex | Co-founder, CEO | Owns: personal LinkedIn, live events, B2B sales, founder narrative, investor relations, brand voice authorship |
| Sam | Co-founder, CXO | Owns: clinical/somatic credibility, brand-voice stewardship, somatic angle on copy review, practitioner network |
| Devon | Lead Dev | Owns: product/UI build, instrumentation, Customer.io event wiring, App Store deployment |
| Ed Dorsey | Design Advisor | Advisory cadence (ex-Apple/Airbnb/Strava) |
| Emily Babich | Creative Strategy | Advisory cadence |
| Matt Mikkelsen | Field Recording | Audio library, not marketing |
| Casey Reed | fCMO | Strategy, lifecycle, SEO, onboarding tests, content, ambassador program, ops stack |
No dedicated marketing hire yet. First hire likely post-seed close (Q3 2026 candidate): a lifecycle + content marketing manager who owns Customer.io, SEO content production, and ambassador operations day-to-day.
Implication: The 90-day plan must produce gains without any paid lever pulled. Everything in the next 12 weeks is organic, lifecycle, or product-level. Paid is a Q2–Q3 unlock.
| Asset | Status | Marketing leverage |
|---|---|---|
| Peer-reviewed peer-reviewed psychophysiology study (2025) | Published | Anchor of clinical authority. Most undermarketed asset Quietude owns. |
| longevity-influencer eye-mask endorsement | Live, generating Shopify sales | Press hook. Underused for landing-page social proof. |
| consumer-tech angels + foundation-model lab investment | Closed | Investor PR opportunity. "Why I invested" Substack/Medium pieces. |
| 15K+ live event participants over a decade | Real | Email list potential, ambassador pool, testimonial bank, B2B reference. |
| Quietude eye mask (5K in stock) | Selling | The wedge product. Hardware → app activation path. |
| 38% 12-month retention (vs. category avg 20%) | Real | Headline metric. Belongs everywhere. |
| Customer.io + Shopify integration | Wired | The lifecycle infrastructure exists. Flows just need to ship. |
| 4 GitHub repos for context + product | Set up | quietude-context (shared brain), quietude-promo, quietude-app (app), mira (AI), quietude-api |
| Alex's Sound Philosophy doc | Working doc | Linkable position paper once polished and published. |
| ~5 inbound ambassadors waiting | Inbound | Referral program ready to launch — no demand-gen needed for v1. |
| Aurora B2B install (~€250K, July deadline) | In-flight | First flagship venue. Reference case once installed. |
| Notion Knowledge Directory | Live | Internal context. |
| Customer.io MCP (Claude integration) | Validated on kickoff | Non-technical team can ship flows independently. |
| Item | Status | Blocker |
|---|---|---|
| Flow 2 — App Onboarding (8 emails / 14 days) | Draft | App UI in flux; copy references screens that may change |
| Flow 4 — Lapsed User Re-engagement (5 emails / 38 days) | Draft | None — ship-ready |
| Flow 6 — Eye Mask Post-Purchase | Draft | None — ship-ready |
| Onboarding rebuild (3-variant test plan) | Strategy doc done | Eng scoping + headphone-gate removal |
| SEO 90-day plan + keyword research | Done | Awaiting domain consolidation decision + content production start |
| Issue | Cost of inaction | Action |
|---|---|---|
| Headphones hard-gate in onboarding | Confirmed conversion drop post-launch | Kill this week (bedrock fix) |
| 4 domains unconsolidated (quietude.app, quietude.space, quietude.audio, quietude.center) | SEO authority fragmenting, transactional email confusion | Consolidate to quietude.app per SEO data |
| App Store listing copy not in brand voice | Highest-traffic Quietude surface; off-brand experience for arriving users | Rewrite in voice (Pillar 1) |
| Domain consolidation requires 301 plan + email sender migration | Risk of traffic loss if mishandled | Plan in weeks 1–2, execute weeks 3–4 |
quietude-promo repo hasn't shipped since March 2026 |
Marketing site is stale | Confirm whether it's live; rewrite or replace |
| 29% monthly App Store churn vs. 38% 12-month retention claim | Metric definition mismatch confusing the team | Reconcile with Devon + Customer.io data |
| Mira post-session reflection scope unknown | Blocks Variant B and Variant C onboarding tests | Resolve with Devon |
Scored 0–5 from materials, using the embedded rubric in references/current-state-rubric.md. Marked "scored from materials" rather than "formal audit" — Alex can push back on any score where they have better data.
| # | Section | Score | Note |
|---|---|---|---|
| 1 | Positioning | 4 | Clear, original category claim. The bottom-up frame is the strongest piece. Needs broader external articulation. |
| 2 | Customer research | 4 | Deep founder-led research, decade of live participants. Could be more systematically captured. |
| 3 | Homepage | 2 | quietude-promo hasn't shipped since March. Off-brand voice in places. |
| 4 | Sales / product pages | 2 | Eye mask page exists on Shopify but isn't optimized for SEO or sales narrative. No app-product landing page in brand voice. |
| 5 | Conversion pages | 2 | /partner exists on quietude.app. No /science, /eye-mask, /ambassadors, /guides pages live. |
| 6 | Competitor comparison | 1 | Nothing exists. Big SEO + sales opportunity (own "Quietude vs. Calm/Headspace/Brain.fm/Endel" SERPs). |
| 7 | Resources / content | 1 | Sound Philosophy not yet public. peer-reviewed psychophysiology study not yet on a dedicated page. No blog. |
| 8 | Onboarding | 2 | Headphones gate killing conversion. Hold-and-fix project this quarter. |
| 9 | Email lifecycle | 1 | All three flows drafted, none live. Ship-order set. |
| 10 | Sales material | 3 | Seed deck is strong (investor-facing). B2B sales material more founder-led than asset-led. |
| 11 | Messaging | 5 | Alex + Sam have authored the most distinctive brand voice in the wellness category. This is a moat. |
| 12 | Pricing | 3 | $30/mo app, $45 eye mask, $7,500 speakers, $50–200K B2B. Hasn't been pressure-tested for D2C conversion lift. |
| 13 | CRO | 2 | App Store conversion rate trackable but no A/B history. Headphones gate is the obvious first test removal. |
| 14 | GTM / launches | 2 | App in throttled beta. Major launches (eye mask, Mira public) haven't had structured GTM. |
| 15 | Ads | 0 | No paid layer. Reflects the current organic strategy — not a weakness, but the budget unlock means this will move. |
| 16 | SEO | 1 | Current state: 7 organic visits/mo. Plan exists; execution not yet started. |
| 17 | Internationalization | 1 | Finland HQ + global ICP, but EN-only and US-centric copy. Defer until Q4+. |
Total: 36 / 85 (42%). The shape matters more than the score: high in Positioning + Messaging + Customer research, low in Conversion pages + Email lifecycle + SEO + Resources + Ads. That's the gap this plan closes.
"How do strangers become aware of Quietude?"
100% organic. Four real channels: Alex's personal LinkedIn, live Quietude events, organic word of mouth, organic App Store discovery. Plus passive PR drag from longevity-influencer endorsement + clinical study.
This is good news, not bad. Every dollar of revenue earned to date has been earned without paid acquisition. The bar to exceed it isn't high; the upside on top of an organic base is significant.
Channel 1 — SEO (primary 90-day investment).
The full 90-day plan lives in seo/plan.md. Summary: consolidate to quietude.app, target three asymmetric clusters (nervous-system regulation KD 14–32, weighted/blackout sleep mask KD 6–30, WELL + social-wellness-club B2B KD 5–34), publish 4 content pillars. 90-day target: 500–1,500 organic visits/mo, 80+ ranking keywords. 12-month target: 10,000/mo, 1,000+ keywords.
Channel 2 — App Store optimization (highest-leverage non-site asset).
The App Store listing is currently the most-visited Quietude URL by Apple's algorithm. Fixing the copy is higher-leverage this quarter than fixing the marketing site. Rewrite in brand voice. Add the meditation-vs-regulation framing. Lead with the clinical anchor. Test screenshot variations.
Channel 3 — Alex's LinkedIn (productize the channel).
Today it's ad-hoc founder posting. The next move is structured: a 2–3x/week cadence, post categories that map to the content pillars (nervous system, sound science, founder journey, clinical evidence, behind-the-scenes), trackable links via Dub, follower → email subscriber → app install funnel measured. This is Alex's voice — the channel only works if he's the one writing. fCMO + Typefully scheduling makes the cadence sustainable.
Channel 4 — PR amplification.
longevity-influencer tailwind is real but underused on owned surfaces. Add a /notable-users or /in-the-press page. Pitch the peer-reviewed psychophysiology study to 5 outlets (wellness press: Well+Good, MindBodyGreen; tech-adjacent: Wired with the longevity-influencer hook; mainstream: Outside, Forbes Wellness). HARO/Help-A-B2B-Writer responses citing Quietude's data. Investor PR moments ("Why I invested in Quietude" Substack pieces from consumer-tech angels — push for these with backlinks).
Channel 5 — Event-to-app instrumentation.
Live events are the highest-converting ICP exposure Quietude has (15K+ participants, decade of trust). They're un-instrumented. Add: per-event QR code → app install + email capture, post-event lifecycle (Customer.io Flow 7?), event ROI tracking. Goal: turn an event from a one-night conversion moment into a 30-day funnel.
Channel 6 — Eye mask wedge (consumer entry product).
5K masks in stock. Shopify storefront exists but isn't optimized. Improvements: SEO-optimize the product page (target "weighted sleep mask," "blackout sleep mask," "silk sleep mask"), add reviews via Judge.me (per kickoff decision), 30-day return policy (US-market expectation, per kickoff), build the listicle ("Quietude vs. Manta vs. Nodpod vs. Lumon"). Consider Amazon listing as a v2 distribution play.
Channel 7 — B2B venue installs (kept lean per kickoff).
Alex owns this. Marketing supports with: case studies after each install, /partner page rewrite in voice (already exists on quietude.app), Pillar 4 content ("The Missing Sound Feature in WELL"), reciprocal links from partner venues baked into contracts.
Channel 8 — Paid layer (unlocked post-seed close).
Held until seed funding lands. Initial test budget: $5–10K/mo split across Apple Search Ads (highest-intent for App Store), Meta (Instagram + Facebook for eye mask), LinkedIn (B2B venue buyers). Don't fire until: (a) onboarding bedrock fix is shipped, (b) Flow 6 is live, (c) at least one Pillar landing page is in voice. Paid amplifies what already works — premature paid amplifies what's broken.
/science page./research/sound-philosophy. First PR push: pitch study + longevity-influencer hook to 5 outlets.seo-audit, ai-seo, programmatic-seo, schema, content-strategy, competitors, launch, ads, ad-creative, social, typefully, analytics, copywriting, marketing-website-design, free-toolsquietude-promo repo work), Notion (knowledge directory), Stripe MCP (LTV / paid-CAC math), agent-browser (LinkedIn drafting + testing), defuddle (research)"Once someone tries Quietude, do they have an experience that converts?"
Day 1 → paid: 1.34%. Day 7 → paid: 3.73%. Day 35 → paid: 5.46%. The funnel shape is the signal. The ~4× lift over 35 days means the product converts given time and contact — both of which the current onboarding undermines and the lifecycle layer doesn't yet provide.
Caveats: app is in throttled beta. Metrics are noisy. Don't optimize against absolutes; optimize against funnel shape and cohort comparison.
Move 1 — Kill the headphones hard-gate (bedrock fix, this week).
Confirmed conversion drop after the gate shipped. The fix isn't better copy on the gate — it's removing the gate. Replace with passive headphone detection + soft single-line nudge. No regret change. Full reasoning in onboarding-recommendation.md.
Move 2 — Run the three-variant onboarding test.
Three variants, each a pure expression of one belief about what drives activation in this ICP:
- Variant 1 — Trust First. Bold promise + clinical anchor + testimonial wall + 1-line mechanism. Tests whether the saturated ICP needs framing before they'll invest.
- Variant 2 — Seen First. Multi-step diagnostic → AI-generated "we see you" summary → personalized session. Tests whether being accurately named is the conversion event.
- Variant 3 — Felt First. Audio starts on app open. ~15 words on screen. The session IS the onboarding. Tests whether the product can carry it cold.
Test sequence (sequential, ~7 weeks to a winner): bedrock baseline → V3 vs. baseline → winner vs. V1 → winner vs. V2. Full system in onboarding-recommendation.md.
Move 3 — App Store listing rewrite.
Highest-leverage non-site asset. Rewrite in brand voice. Lead with meditation-vs-regulation. Screenshot variations to test. This is also an Acquisition move (organic discovery) but it lives here because it's the threshold to the trial.
Move 4 — Customer.io Flow 2 (held until UI stable).
The 8-email / 14-day onboarding sequence is drafted and on-brand. Holding the ship because the emails reference in-app screens that will change during the onboarding rebuild. Once a winning onboarding variant ships, Flow 2 gets a copy refresh against the final UI and goes live.
Move 5 — Paywall + pricing review (cross-cuts to Revenue).
What's the current trial structure? Length, paywall trigger, intro pricing? When the funnel shape is "lift over 35 days," extending trial may convert better than aggressively gating earlier. To be audited in Q1.
onboarding, signup, cro, cro, paywalls, popups, copywriting, copy-editing, copycraft, marketing-website-design, ab-testing, marketing-psychologydev-browser for screenshot automation), GitHub MCP (quietude-app app repo for onboarding code), Figma / Pencil MCP (for onboarding screen design), Customer.io MCP (for any in-app/email coordination), GA4 MCP (activation events)"Once someone converts, do they stay — and deepen?"
Headline metric (per seed deck): 38% 12-month retention — nearly double the category average (~20%). This is the strongest single retention signal in the deck and one of the most undermarketed claims Quietude owns.
App Store snapshot, 2026-05-16: 145 paid, 42 churned (~29% monthly churn). Definition mismatch with the 38% claim — to reconcile. Possibly: 38% is annual cohort retention (people who paid month 1 and still pay month 12), 29% is gross monthly churn (people who paid this month who didn't pay next month). Both can be true. Need to clarify which metric is reported externally and which is the actual product health signal.
Move 1 — Ship Flow 6 first (Eye Mask Post-Purchase).
Per kickoff decision and the onboarding-recommendation doc: this is the ship-ready flow. Hardware-anchored, doesn't reference in-app screens, can ship today. Wires the hardware → app activation path (eye mask buyers should get a free 6-month Premium trial — formalize this as part of the flow).
Move 2 — Ship Flow 4 second (Lapsed User Re-engagement).
Five emails over 38 days. Language is universal — doesn't depend on app UI state. Ship after Flow 6 is live.
Move 3 — Hold Flow 2 (Onboarding).
Eight emails over 14 days. Holds until app UI stabilizes post-onboarding-rebuild. Don't ship copy that will need rewriting in 8 weeks.
Move 4 — Customer.io subscription center with opt-in topics.
Per kickoff decision. Topics: events, app updates, somatics & nervous system, eye mask promotions. Users self-segment. Improves deliverability (lower complaint rates) and gives lifecycle a richer segmentation surface.
Move 5 — Mira post-session reflection (when scoped).
Most powerful retention move medium-term. After a session, Mira asks "What did you notice?" Optional preset chips + free text. Two payoffs: (a) gives Mira priors for personalization on session 2+, (b) reflection responses become a content + segmentation goldmine for the team. Scope question for Devon — does Mira currently support this, or is it new build?
Move 6 — Hardware → app activation flow.
The eye-mask-buyer-becomes-Premium-subscriber path is hinted in the seed deck (blended CAC via hardware) but isn't visible in the App Store dashboard. Audit the existing flow: does an eye mask Shopify purchase actually deliver a free Premium code? How is it redeemed? What's the conversion rate? This is foundational to the "B2C wedge" thesis.
Move 7 — Reconcile the retention metric.
What's the actual definition of "38% 12-month retention"? Cohort? Plan type (monthly vs. annual)? Survives this even if the answer is uncomfortable — the team and investors need to be talking about the same metric.
Move 8 — Annual plan as default (cross-cuts to Revenue).
Industry pattern: defaulting to annual reduces churn anxiety and improves LTV. To test in Q2.
emails, churn-prevention, copywriting, copy-editing, paywalls, ab-testing"Do retained users bring more users — and at what cost?"
~5 inbound ambassadors waiting (per kickoff). Dub.co set up. No formal program yet. WOM happens naturally per Alex's UA breakdown.
This is one of the strongest leading indicators in the business: 5 unaffiliated people have raised their hand asking to bring Quietude to their network before any program exists. That signal doesn't show up in apps with weaker product-market fit.
Move 1 — Launch the ambassador program with the 5 inbound.
Tier 1 of the program. Per-ambassador landing pages (e.g., quietude.app/with/sarah). Dub.co tracks attribution. Commission structure to determine (per kickoff, $/sub or rev-share TBD). Soft-launch with the 5 — treat as pilot cohort, gather feedback, refine before opening applications.
Move 2 — Build the share-after-shift moment.
The Mira post-session reflection (see Retention) is the natural moment to surface a share prompt. After a user reports a felt shift, offer: "Want to share Quietude with someone who needs this?" Single-line, never pushy. Most powerful WOM mechanism: gift-a-month flow where the recipient gets a discounted or free intro.
Move 3 — Founder amplification (Alex + Sam as ambassador-zero).
Alex mentioning the fCMO engagement in fundraise pitches (permission granted). Reciprocal mentions in fCMO-side content. Sam's clinical network → practitioner ambassador pool.
Move 4 — Quietude Guides cert pilot (long-term, Q3+).
The Guides program is the Phase-2 referral compound (per seed deck). 500–1,000 Guides across 50+ cities by Y3–5. First cert pilot: 3–5 hosts who run live sessions, get a rev-share + co-marketing. Builds local SEO + earned media + ambassador-of-ambassadors flywheel. Hold until paid + lifecycle are firing — Guides is a multi-quarter build.
Move 5 — Eye mask gifting flow.
Hardware referral is rare and powerful. "Send a friend an Quietude eye mask. They get the mask + a free 3-month Premium. You get a credit toward your next thing." Holiday/gifting peak windows are the test.
referrals, social, copywriting, marketing-website-design (per-ambassador landing pages)quietude-promo or new quietude-ambassadors repo), Customer.io MCP (ambassador lifecycle: onboarding, monthly performance digest, payout notification)"What do we charge, who pays, and how does that compound?"
| Product | Price | Volume signal |
|---|---|---|
| Quietude App + Mira | ~$30/mo | 145 paid subs (App Store snapshot 2026-05-16) |
| Quietude Eye Mask | ~$45 | 5K in stock, longevity-influencer PR-driven sales |
| Quietude Audio (speakers) | ~$7,500 | Niche, founder-led |
| Quietude Spaces (B2B install) | $50–200K | Aurora flagship in-flight (~€250K), pipeline of 4 venues |
| Quietude Experiences (events) | Varies | 15K+ historical participants |
| Quietude Guides | Rev share | Not yet operational |
Revenue to date: ~$500K on ~$250K raised. Capital-efficient. Hardware + B2B + app subs all contributing.
MRR (App Store snapshot): $592. Beta-throttled, not steady-state. The implied ~$4/sub/mo against $30/mo list suggests heavy annual plan adoption (which compresses monthly revenue but improves LTV) or significant promotional pricing — to reconcile with Alex.
Move 1 — Pricing audit.
What's actually being charged today? List price, common plan mix, intro pricing, churn-recovery offers? The $4/sub/mo implied math doesn't tell a clean story — need ground truth before recommending changes.
Move 2 — Annual plan as default (test).
Industry pattern, cross-references to Retention. Test in Q2.
Move 3 — Hardware → app bundling formalized.
Per partner-event-business framing in the seed deck: blended CAC via hardware → app subscription is the play. Today an eye mask buyer gets... what, exactly? Free Premium? Trial code? Audit + formalize. The eye mask is the wedge; the app is the LTV.
Move 4 — Eye mask Shopify storefront optimization.
The current page underperforms what it could. Add: SEO targeting ("weighted sleep mask," "blackout sleep mask"), Judge.me reviews (kickoff decision), 30-day return policy (kickoff decision), upsell flow into Premium app.
Move 5 — Consider Amazon listing for eye mask.
Amazon takes margin but is its own discovery engine. Test as v2 distribution if Shopify volume validates.
Move 6 — B2B install case studies + sales material.
Alex owns B2B sales but marketing supports with: post-install case studies (Aurora as the flagship), /partner page rewrite in voice, Pillar 4 SEO content. Each B2B install is a ~$430K/year recurring + reference-case multiplier.
Move 7 — Data licensing (long-term, flag for ops stack).
Per seed deck Y10–15 value pool: $100–160M/yr. Not immediate revenue. Belongs in the 24-month strategic agenda. Flag here so we don't lose sight.
pricing, paywalls, sales-enablement, revops, ab-testing, copywritingTactical execution layer. Each item is AARRR-tagged so priority is visible.
| Move | Stage | Owner |
|---|---|---|
| Kill the headphones hard-gate | Activation | Casey + Devon |
| Domain consolidation decision documented | Acquisition | Casey + Alex |
| 301 plan drafted (page-by-page) | Acquisition | Casey |
| App Store listing rewrite — first pass | Activation + Acquisition | Casey + Alex + Sam (voice review) |
| Flow 6 (eye mask post-purchase) ships | Retention | Casey + Customer.io MCP |
| Ambassador program scoping doc | Referral | Casey |
| Pricing audit kicked off | Revenue | Casey + Alex |
| Move | Stage | Owner |
|---|---|---|
| Domain consolidation 301s executed | Acquisition | Devon + Casey |
GSC + GA4 stood up on quietude.app |
Acquisition | Casey |
| SEO Pillar 1 hub drafted (Nervous System Regulation) | Acquisition | Casey |
/science hub built with peer-reviewed psychophysiology study |
Acquisition + brand | Casey + Sam |
| Variant 3 (Felt First) onboarding prototyped + tested | Activation | Casey + Devon |
| Flow 4 (lapsed user) ships | Retention | Casey |
| Ambassador program: 5 inbound onboarded | Referral | Casey |
| Hardware → app activation flow audited | Retention + Revenue | Casey + Devon |
| App Store listing rewrite — final + ship | Activation + Acquisition | Alex + Sam + Casey |
| Move | Stage | Owner |
|---|---|---|
| Pillar 1 hub + 3 spokes published | Acquisition | Casey |
| Pillar 2 hub (Eye Mask) + listicle published | Acquisition | Casey |
| Alex's LinkedIn cadence operationalized (Typefully) | Acquisition | Alex + Casey |
| First PR push: study + longevity-influencer hook to 5 outlets | Acquisition | Casey + Alex |
| Variant 3 read; ship or iterate | Activation | Casey |
| Variant 1 (Trust First) prototyped + tested | Activation | Casey + Devon |
| Customer.io subscription center built | Retention | Casey |
| Eye mask Shopify storefront rewrite (SEO + reviews + return) | Acquisition + Revenue | Casey + Alex |
| First ambassador attribution verified via Dub | Referral | Casey |
| Move | Stage | Owner |
|---|---|---|
| Pillar 4 (WELL/B2B) cornerstone published | Acquisition | Casey |
| 3 more Pillar 1 spokes published | Acquisition | Casey |
Sound Philosophy published at /research/sound-philosophy |
Acquisition + brand | Alex + Casey |
| Variant 1 read; begin Variant 2 (Seen First) build (Mira-dependent) | Activation | Casey + Devon |
| Win-back campaign for churned cohort | Retention | Casey |
| Annual plan default test scoped | Revenue | Casey + Alex |
| Open ambassador applications for next 10–15 | Referral | Casey |
| 90-day review + Q2 plan recalibration | Cross-cutting | Casey + Alex |
Quarterly milestones with funding-stage capability unlocks named explicitly.
Funding state: Pre-seed-close. Paid budget = $0. fCMO + founder-led + tool costs only.
Focus: Foundation. Plug the leaks. Stake the SEO ground. Get lifecycle firing.
Outcomes by end of Q1:
- Headphones gate gone; onboarding winner identified
- All four SEO pillars seeded (hub + first spokes)
- Lifecycle Flows 4 + 6 live
- App Store listing in brand voice
- 5 ambassadors active
- Pricing audit closed
- Domain consolidated
KPI targets: Onboarding Day 1 → paid lift of 25–50%. Organic traffic 500–1,500/mo. App Store conversion rate +20%.
Funding state: Seed close (~Q3 2026 target). First paid budget unlock: $5–10K/mo test.
Focus: Validate paid. Scale winning onboarding. Add Flow 2.
Outcomes by end of Q2:
- Paid acquisition firing on Apple Search Ads + Meta
- Onboarding winner permanently shipped
- Flow 2 (onboarding emails) shipped
- Mira post-session reflection in production
- 15–25 ambassadors active
- First B2B install reference case (Aurora) published
- Annual plan default tested
KPI targets: Paid CAC < $50 blended. Organic traffic 1,500–3,500/mo. Retention curves visibly improving.
Funding state: Seed deployment. Paid scales to $20–50K/mo if unit economics hold. First marketing hire (lifecycle + content manager).
Focus: Scale + diversify. App GA. B2B reference cases compound.
Outcomes by end of Q3:
- App GA launched with new GTM moment (PR + ad creative refresh + Pillar 3 spatial-audio-science content cycle)
- First Quietude Guides cert pilot (3–5 hosts)
- All four pillars producing weekly content
- Eye mask gifting flow live for holiday peak
- New marketing hire onboarded
KPI targets: Paid + organic blended CAC stabilizing. App GA conversion +50% from beta baseline. Guides pilot validates rev-share + co-marketing model.
Funding state: Pre–Series A. Paid scaling continues. Series A pitch in motion.
Focus: Compound. Position for Series A.
Outcomes by end of Q4:
- Compound channels (organic + ambassador + Guides + lifecycle) producing 50%+ of new subs
- 50+ ambassadors, 5–10 Guides
- 4 SEO pillars + 30+ pieces of content live
- Paid scaling to $50–150K/mo if validated
- Series A narrative: clinical evidence + activation lift + lifecycle compounding + B2B reference case pipeline
KPI targets: D2C ARR run-rate trajectory clear. Blended LTV/CAC > 3. Founder narrative + data + reference cases ready for Series A.
This is what makes the plan executable at Quietude's team size. A 4-person founder team + fCMO + agentic tooling can ship the output of a 15–20-person traditional marketing org — because the marketing skill library and MCP integrations do the orchestration.
Every move in the AARRR breakdown above maps to (a) one or more marketing skills that operationalize the work, and (b) one or more MCP/API integrations that let it execute without a dedicated headcount per channel.
The fCMO's job is to:
1. Define the strategy and sequencing (this doc)
2. Run the skills against the right context at the right time
3. Maintain the shared context (quietude-context) and tooling so Alex + Sam + future hires can plug in
4. Hand off operational work to humans (or future hires) only where the cost of agentic execution > human execution
| Stage | Primary skills | Supporting skills |
|---|---|---|
| Acquisition | seo-audit, ai-seo, programmatic-seo, schema, content-strategy, competitors, ads, ad-creative, social, typefully |
launch, free-tools, analytics, cold-email, copywriting, marketing-website-design |
| Activation | onboarding, signup, paywalls, cro, copywriting, copy-editing, copycraft |
marketing-website-design, ab-testing, marketing-psychology, cro, popups |
| Retention | emails, churn-prevention |
copywriting, copy-editing, ab-testing, paywalls |
| Referral | referrals, social |
copywriting, marketing-website-design, emails |
| Revenue | pricing, paywalls, sales-enablement, revops |
ab-testing, copywriting |
| Cross-cutting (brand, intelligence) | product-marketing, customer-research, marketing-psychology |
marketing-ideas, diagram-maker |
| Stage | Existing connections at Quietude | Tooling layer (Casey's fCMO stack) |
|---|---|---|
| Acquisition | App Store Connect (manual), Shopify, GA4 (in progress), Notion | Ahrefs API, DataForSEO API, Typefully MCP, GitHub MCP (quietude-promo), agent-browser, defuddle |
| Activation | App Store Connect, Customer.io, Shopify | App Store Connect (via dev-browser for screenshot automation), Figma / Pencil MCP, GitHub MCP (quietude-app app repo), Stripe MCP |
| Retention | Customer.io (with Claude MCP — validated on kickoff), Stripe, Shopify | Customer.io MCP, Stripe MCP, GA4 MCP |
| Referral | Dub.co, Stripe | Dub.co, Stripe MCP, GitHub MCP (per-ambassador landing pages), Customer.io MCP |
| Revenue | Stripe, Shopify, Customer.io | Stripe MCP, Shopify, GA4 MCP, Notion |
| Cross-cutting | Notion, GitHub (quietude-context) |
Notion, GitHub MCP, defuddle, obsidian-cli (for Casey's working notes) |
Per kickoff call: "Built live on call — abandoned-cart flow drafted using Customer.io's Claude MCP. Validated that non-technical team can use the skill pattern independently."
This is the operational proof that the stack works. Alex, who is not a developer, drafted a working lifecycle flow with Claude + Customer.io MCP in real time on a kickoff call. The same pattern applies to: Flow 4 ship (lapsed user re-engagement), subscription center build, win-back campaign, eye mask gifting flow, ambassador lifecycle. The fCMO's role becomes orchestration + brand-voice QA, not hand-cranking each email.
| Stage | Headcount | Tooling | Channels live |
|---|---|---|---|
| Pre-seed-close (now) | fCMO + founder team | All current tooling + Casey's marketing skill library + MCP layer | Organic only (SEO, content, App Store, LinkedIn, events, WOM, ambassador) |
| Seed close (~Q3 2026) | + first marketing hire (lifecycle/content) by end of Q3 | + paid ad accounts (Apple Search Ads, Meta, LinkedIn) | + paid acquisition pilot $5–10K/mo |
| Seed deployment (Q3–Q4 2026) | + designer (potentially fractional) | + analytics expansion (Mixpanel or Amplitude if needed) | + paid scaling $20–50K/mo, + Guides cert pilot |
| Series A (2027) | + performance marketing lead + content lead | + dedicated tooling spend (~$2–5K/mo software) | + paid scaling $50–150K/mo, + international, + B2B vertical expansion |
The marketing skill library scales these stages. Every channel added doesn't require a 1:1 headcount increase because each skill encodes the workflow.
The marketing-ideas skill catalogs 139 proven marketing tactics. Sections 4–8 (AARRR) prescribe what we're doing. This section maps the full universe of what's possible — every idea cross-referenced to the AARRR stage it primarily serves, with Quietude applicability and timing.
This is the exhaustive menu. The plan above is the curated path. When we move to Q2 / Q3 / Series A and unlock new capacity, this is the inventory we pull from.
Status legend:
Now (Q1):
| # | Idea | Quietude note |
|---|---|---|
| 1 | Easy Keyword Ranking | SEO plan Tier-1 cluster (nervous system, sleep mask, B2B) targets this directly |
| 2 | SEO Audit | Run /seo-audit quietude.app quarterly; publish findings as content |
| 5 | Content Repurposing | Sound Philosophy → essays → LinkedIn posts → newsletter → podcast loop |
| 6 | Proprietary Data Content | peer-reviewed psychophysiology study now; anonymized Quietude HRV / sleep dataset later |
| 7 | Internal Linking | Built into the pillar/spoke structure of the SEO plan |
| 10 | Parasite SEO | Alex's LinkedIn already does this; consider mirror to Substack |
| 12 | Marketing Jiu-Jitsu | Meditation-vs-Regulation IS this — turn "meditation works" assumption against itself |
| 36 | Quora Marketing | Answer "why meditation doesn't work for me" + HRV + somatic questions |
| 37 | Reddit Keyword Research | Mine r/somatic, r/CPTSD, r/HSP, r/ADHD for ICP language (feeds Customer Language #139) |
| 39 | LinkedIn Audience | Alex's channel productized — primary D2C top-of-funnel today |
| 59 | Article Quotes | HARO / Help-A-B2B-Writer for Alex + Sam — easy press wins |
| 70 | Conference Speaking | Alex: WELL Conference, biophilic design events, Mindful Leadership Summit |
| 74 | Press Coverage | Pitch peer-reviewed study + longevity-influencer hook to 5 outlets in Q1 |
| 109 | Public Demos | Live Quietude events ARE this; instrument the in-person → app conversion |
| 114 | Moneyball Marketing | Already practicing — asymmetric SEO keywords, undervalued channels |
| 133 | Investor Marketing | Alex's raise — leverage angel backchannel for PR + intros |
Q2:
| # | Idea | Quietude note |
|---|---|---|
| 3 | Glossary Marketing | Sound + nervous system glossary — "what is polyvagal," "what is HRV," "what is somatic listening" |
| 8 | Content Refreshing | Revisit Pillar 1 quarterly with new data and search-intent updates |
| 11 | Competitor Comparison Pages | Quietude vs. Calm / Headspace / Brain.fm / Endel / Wavepaths — high-intent SERPs |
| 13 | Competitive Ad Research | SpyFu + Facebook Ad Library before launching paid |
| 17 | Quiz Marketing | "What's your nervous system profile?" — generates personalization seed + lead capture |
| 25 | Facebook Ads | Eye mask creative + somatic content + retargeting from event attendees |
| 26 | Instagram Ads | Visual product + Reels-native ads (eye mask especially) |
| 28 | LinkedIn Ads | B2B venue buyers + investor-adjacent ICP |
| 31 | Google Ads | Apple Search Ads first (App Store intent); Google for eye mask + B2B |
| 38 | Reddit Marketing | Authentic participation in r/somatic, r/HSP, r/ADHD after content base exists |
| 40 | Instagram Audience | Eye mask + somatic creators; Reels-native |
| 44 | Comment Marketing | Thoughtful comments on Huberman / the partner-event-business / Tim Ferriss / wellness creators |
| 49 | Monthly Newsletters | Either Quietude-branded or sync with Sam's Sam's Substack newsletter |
| 54 | Affiliate Discovery via Backlinks | Find who links to Calm/Headspace/Brain.fm — pitch them on Quietude affiliate program |
| 58 | Newsletter Swaps | the partner-event-business, founder wellness Substacks, Alex's investor network |
| 64 | Community Sponsorship | Somatic newsletters, wellness Substacks, founder communities |
| 65 | Live Webinars | Alex + Sam hosting "Sound + the Nervous System" |
| 101 | Industry Interviews | Alex + Sam interview category experts (becomes seed of Quietude podcast) |
| 102 | Social Screenshots | Mira reflection responses (anonymized, consented) — social proof gold |
| 108 | Changelogs | Public changelog at quietude.app/changes — product momentum signal |
| 115 | Curation as Marketing | Curated "field recordings of the year" feature; Quietude Spaces directory |
| 135 | Support as Marketing | Surface customer support / Mira reflection moments as content |
| 138 | Podcast Tours | Alex on Huberman, the partner-event-business, Tim Ferriss, Rich Roll, Rangan Chatterjee |
Q3+:
| # | Idea | Quietude note |
|---|---|---|
| 4 | Programmatic SEO | Quietude Guides city pages once Guides program scales |
| 9 | Knowledge Base SEO | When help docs scale enough to have problem-solution coverage |
| 14 | Side Projects | Eventually a free Quietude-adjacent tool that lives outside the app |
| 15 | Engineering as Marketing | HRV interpretation guide; nervous system self-assessment; sound bath finder directory |
| 18 | Calculator Marketing | Sleep latency calculator; overstimulation index |
| 20 | Microsites | For specific GTM moments (e.g., Mira GA launch) |
| 23 | Podcast Advertising | Huberman, Tim Ferriss, Rich Roll, the partner-event-business — host-read most relevant |
| 24 | Pre-targeting Ads | Warm audiences via content before direct-response |
| 29 | Reddit Ads | r/HSP, r/ADHD, r/somatic — high ICP density, low advertiser saturation |
| 30 | Quora Ads | Intent-rich for "why meditation doesn't work" queries |
| 32 | YouTube Ads | Pre-roll on Huberman / Lex Fridman / wellness creator videos |
| 33 | Cross-Platform Retargeting | Standard layer once paid is firing |
| 35 | Community Marketing | Quietude Spaces community (Discord/Circle); host monthly drop-ins |
| 42 | Short Form Video | TikTok / Reels — somatic education + eye mask UGC |
| 55 | Influencer Whitelisting | Run ads through ambassador / Guide accounts for authenticity |
| 57 | Expert Networks | Quietude Guides program IS this — certified hosts who can market |
| 60 | Pixel Sharing | Standard once paid is firing |
| 61 | Shared Slack Channels | Partner venue Slacks (Aurora, Lumen, Stillwater) |
| 63 | Integration Marketing | Apple Health (HRV data), Oura, Whoop — co-marketing |
| 66 | Virtual Summits | Quietude participates or hosts |
| 68 | Local Meetups | Cities with high ICP density (SF, NYC, LA, Austin) |
| 69 | Meetup Sponsorship | Sponsor wellness / biohacking meetups |
| 72 | Conference Sponsorship | Industry conferences once budget unlocks |
| 75 | Fundraising PR | "Quietude raises $3M" moment when seed closes |
| 78 | Product Hunt Launch | Mira public launch moment |
| 79 | Early-Access Referrals | App GA early-access list (cross-references to Referral) |
| 81 | Early Access Pricing | App GA — early-access tier locked in for first cohort |
| 82 | Product Hunt Alternatives | BetaList, Launching Next, AlternativeTo at GA |
| 97 | Playlists as Marketing | Quietude curates Spotify playlists for somatic listening |
| 98 | Template Marketing | Free "nervous system reset" protocol PDFs |
| 100 | Promo Videos | High-quality brand films — Ed Dorsey advises, Matt Mikkelsen field audio |
| 103 | Online Courses | Alex's Sound Philosophy course; Sam's somatic methodology course |
| 107 | Podcasts | Quietude podcast — interview format with category experts and customers |
| 111 | Challenges as Marketing | "21-day nervous system reset" — tasteful, no fitness-bro tone |
| 113 | Controversy as Marketing | Meditation-vs-Regulation IS mild controversy — lean in carefully |
| 126 | YouTube Reviews | Pitch Quietude to wellness YouTubers — Huberman fan-creator tier |
| 127 | YouTube Channel | Sound design behind-the-scenes; Sam session demos |
| 129 | Review Sites | App Store reviews actively managed; Trustpilot for eye mask Shopify |
| 130 | Live Audio | Twitter Spaces / LinkedIn Audio with Alex on sound + body |
| 134 | Certifications | Quietude Guides cert IS this — Q3+ pilot |
Q4+ / long-game:
| # | Idea | Quietude note |
|---|---|---|
| 56 | Reseller Programs | Corporate wellness platforms (Modern Health, Lyra) as resellers |
| 67 | Roadshows | Quietude Experiences IS this — eye mask + listening session pop-ups in 3 cities |
| 71 | Conferences | Quietude-hosted "Sound + the Body" — long-game category-defining moment |
| 76 | Documentaries | Alex's story is documentary-grade — long game |
| 77 | Black Friday Promotions | Holiday eye mask + Premium bundle |
| 80 | New Year Promotions | New Year nervous system reset campaign |
| 84 | Giveaways | Eye mask giveaway with brand partner (Wellness Mama tier) |
| 85 | Vacation Giveaways | Quietude + retreat partner giveaway (quietude.center could be venue) |
| 87 | Powered By Marketing | "Sound system by Quietude" badge in B2B venue installs |
| 104 | Book Marketing | Sound Philosophy as a book — long-game positioning anchor |
| 105 | Annual Reports | "State of the Nervous System" — Quietude's data + industry commentary |
| 106 | End of Year Wraps | "Your nervous system year" — Spotify Wrapped equivalent |
| 110 | Awards as Marketing | Quietude founds an award for innovative biophilic acoustic design |
| 116 | Grants as Marketing | Free Quietude subscriptions for therapists, social workers, first responders |
| 119 | OOH Advertising | SF / NYC billboards if Series A budget unlocks |
| 120 | Marketing Stunts | Public sound installation could work — brand-fitting |
| 121 | Guerrilla Marketing | Sound installation in subway / airport — interesting but requires care |
| 131 | International Expansion | Finland HQ + global ICP — Q4 or post-Series A |
Skip / off-brand for Quietude:
| # | Idea | Why skip |
|---|---|---|
| 16 | Importers as Marketing | No competitor data to import (consumer wellness, not SaaS) |
| 19 | Chrome Extensions | Off-platform (mobile-first product) |
| 21 | Scanners | No obvious product fit |
| 22 | Public APIs | Not core business |
| 27 | Twitter Ads | Lower priority unless Alex's X presence grows |
| 34 | Click-to-Messenger Ads | Off-brand (no DM-driven sales pattern) |
| 41 | X Audience | Depends on Alex's bandwidth — defer unless he wants to |
| 43 | Engagement Pods | Off-brand |
| 73 | Media Acquisitions | Too capital-intensive at this stage |
| 83 | Twitter Giveaways | Off-brand voice |
| 86 | Lifetime Deals | Brand-conflict — pressures the "no pressure" voice and damages LTV math |
| 88 | Free Migrations | No competitor data to migrate |
| 89 | Contract Buyouts | Not relevant for D2C subs |
| 99 | Graphic Novel Marketing | Off-brand |
| 112 | Reality TV Marketing | Off-brand |
| 117 | Product Competitions | Not a developer product |
| 118 | Cameo Marketing | Off-brand |
| 122 | Humor Marketing | Brand voice is serious; humor would feel off |
| 123 | Open Source as Marketing | Proprietary audio library |
| 125 | App Marketplaces | Not relevant for native consumer app (no app-of-app pattern) |
| 128 | Source Platforms | G2 / Capterra are B2B-focused; D2C uses App Store reviews |
| 132 | Price Localization | Q4+ — tied to international expansion |
| 136 | Developer Relations | Not a dev product |
| # | Idea | Status | Quietude note |
|---|---|---|---|
| 124 | App Store Optimization | Now | Q1 priority — listing rewrite in voice (also Acquisition) |
| 90 | One-Click Registration | Now | OAuth (Apple, Google) for app signup — standard activation lift |
| 51 | Onboarding Emails | Q2 | Flow 2 — held until UI stable post-onboarding-rebuild |
| 96 | Onboarding Optimization | Q1-Q2 | The 3-variant test IS this — primary activation work |
| 47 | Founder Welcome Email | Q2 | Personal welcome from Alex or Sam early in Flow 2 |
| 48 | Dynamic Email Capture | Q2 | Smart capture on quietude.app — exit intent + scroll depth |
| 95 | Concierge Setup | Q3+ | High-touch onboarding for B2B venue clients + high-value subscribers |
| # | Idea | Status | Quietude note |
|---|---|---|---|
| 46 | Reactivation Emails | Now | Flow 4 ships in weeks 3–4 — exactly this |
| 52 | Win-back Emails | Q1 (week 11-12) | Standalone campaign on top of Flow 4 |
| 53 | Trial Reactivation | Q2 | Expired-trial recovery campaign once paywall is firing |
| 45 | Mistake Email Marketing | Q2 | When something genuinely goes wrong, send "oops" — drives engagement |
| 50 | Inbox Placement | Q1 | Subdomain silo strategy (mail.quietude.app / commerce.quietude.app) addresses this |
| 91 | In-App Upsells | Q2 | Premium upsell points within app (also Revenue) |
| 94 | Offboarding Flows | Q2 | Optimize cancellation flow to retain or learn — feeds churn intel |
| 135 | Support as Marketing | Q2 | Customer support stories surface as content (also Acquisition) |
| # | Idea | Status | Quietude note |
|---|---|---|---|
| 62 | Affiliate Program | Now | Ambassador program v1 is exactly this — launched with the 5 inbound |
| 137 | Two-Sided Referrals | Q2 | Reward both referrer and referred — share-after-shift moment + gifting flow |
| 92 | Newsletter Referrals | Q3 | If we launch a newsletter, Sparkloop-style referral mechanic |
| 93 | Viral Loops | Q3 | Built-in share mechanics post-Mira reflection |
| 79 | Early-Access Referrals | Q3 | App GA early-access list referrals (cross-references to Acquisition) |
| # | Idea | Status | Quietude note |
|---|---|---|---|
| 91 | In-App Upsells | Q2 | Premium upgrade prompts; eye mask cross-sell from app (also Retention) |
| 132 | Price Localization | Q4+ | Adjust pricing for local purchasing power once international |
| 86 | Lifetime Deals | Skip | Brand-conflict — see Acquisition skip list |
| # | Idea | Status | Quietude note |
|---|---|---|---|
| 139 | Customer Language | Now | Mira reflection responses + 7 Ds language = the source-of-truth for customer language across all copy |
| 114 | Moneyball Marketing | Ongoing | Find undervalued channels at every stage — methodology, not a single tactic |
What this proves: the plan is roughly 30% of the available tactical surface area, not 100%. That's appropriate at this stage and budget. As capacity unlocks across Q2 → Q3 → Series A, the cross-reference becomes the inventory we pull from to scale activity without losing strategic coherence.
North star (proposed):
Blended-LTV-to-blended-CAC ratio per acquired user, where:
- Blended LTV combines app subscription revenue + hardware revenue (eye mask + speakers) + any cross-sells, per cohort
- Blended CAC combines paid spend + content production cost + ambassador commissions + lifecycle tool spend, per cohort
This captures the business model: the eye mask wedge isn't free if it costs $X to make, and the app sub isn't expensive to acquire if a Bryan-Johnson-style PR moment is paying for itself.
If a single metric is preferred for team-level focus, fall back to: monthly new D2C subscribers from non-paid channels. This isolates the compound channels the long-game strategy depends on.
Leading indicators by AARRR stage:
| Stage | Leading indicators |
|---|---|
| Acquisition | Organic visits/mo (overall + per pillar), App Store visit-to-install rate, Alex's LinkedIn engagement → email subscribers, event-to-app conversion rate, ambassador-attributed visits |
| Activation | Day 1 / Day 7 / Day 35 → paid conversion, onboarding session-completion rate, first session Mira reflection completion |
| Retention | 30 / 60 / 90-day retention, monthly churn, Flow 4 reactivation rate, hardware → app activation rate |
| Referral | Ambassador-attributed new subs (Dub), share-after-shift rate, Guides pilot referrals (when live) |
| Revenue | Blended MRR, ARPU, annual plan adoption %, LTV by cohort, eye mask attach rate |
Review cadence:
- Weekly: fCMO ↔ Alex 30-min sync. AARRR scoreboard + this week's ships.
- Monthly: Full metrics review (extended sync, Sam included). Compare against quarterly KPI targets.
- Quarterly: Plan recalibration. What's working, what's not, what funding-stage moves we're triggering.
| Domain | Responsible | Accountable | Consulted | Informed |
|---|---|---|---|---|
| Strategic plan (this doc) | Casey | Alex | Sam, Emily | Team |
| Brand voice | Alex + Sam | Alex + Sam | Casey | Team |
| App + onboarding implementation | Devon | Alex | Casey | Team |
| Lifecycle flows (Customer.io) | Casey | Alex | Sam (copy QA) | Team |
| SEO content | Casey | Casey | Sam, Alex | Team |
| App Store copy | Casey | Alex | Sam | Team |
| Alex's LinkedIn cadence | Alex | Alex | Casey (orchestration) | Team |
| Events | Alex + Sam | Alex | Casey (instrumentation only) | Team |
| Ambassador program | Casey | Casey | Alex | Team |
| B2B sales | Alex | Alex | Casey (case studies) | Team |
| Pricing | Alex | Alex | Casey | Sam |
| Investor narrative | Alex | Alex | Casey, Sam | Team |
| Quietude Guides program (Q3+) | TBD (likely future hire) | Alex + Sam | Casey | Team |
| Future marketing hire (Q3) | Casey | Alex | Sam | Team |
Most blocking, ranked by impact:
quietude.app. Needs exec sign-off + 301 execution plan. Blocks: domain consolidation, SEO foundation, email sender migration.Published to the team via Quietude-Inc/quietude-context GitHub repo:
- marketing/seo/plan.md — Full 90-day SEO + keyword research plan
- marketing/seo/keyword-shortlist.md — Tier 1 keyword shortlist
- marketing/seo/raw/ — Ahrefs + DataForSEO API pulls
- marketing/onboarding-recommendation.md — Three-variant onboarding test plan
Founder-authored strategic context (in Quietude's internal knowledge base):
- Seed deck — Investor narrative
- Sound Philosophy — Alex's technical/philosophical working doc
- Marketing OS — Brand voice, content rhythm, visual system
- ICP doc — D2C audience profile
- Meditation-vs-Regulation note (2026-05-19) — Central content pillar
- Kickoff call transcript (2026-05-18) — Decisions + open questions
- App Store copy snapshot + voice-gap analysis
- App Store metrics snapshot (2026-05-16)
- Customer.io lifecycle flows inventory
Marketing Plan v1. Prepared by Casey Reed (fCMO), 2026-05-27. For team review and discussion.
Every marketing plan must include explicit "what changes when funding closes / when budget unlocks" reasoning. This makes the plan investor-friendly and operationally honest.
This doc defines the standard tiers. Use them as anchors, adjust for client category and unit economics.
Related docs:
- budget-planning.md — two scientific methods for setting the actual budget number (Revenue-Based 5–40%, or Goal-Based reverse-engineered from the revenue target), CAC calculation, experimental buffer
- growth-patterns.md — the real shape of SaaS growth by phase ($0–10K / $10K–100K / $100K–1M+), linear vs step-function, S-curve layering
- team-and-agency-model.md — what each tier means for team composition, the first marketing hire, and the in-house vs outsource ratio
Most marketing plans are written as if budget is unconstrained. That's a failure mode for early-stage clients — it produces aspirational lists rather than executable roadmaps.
The fix: tie every recommendation to a budget tier. The plan stays honest about what's executable today, and the team / investors see explicitly what each round of capital unlocks.
This also helps the founder mid-raise: showing what the round buys is investor-narrative material.
Budget profile:
- Paid acquisition: $0
- Tooling stack: ~$500–2,000/mo (Customer.io / similar, GA4 free, Stripe fees, Notion, GitHub, basic SaaS)
- Retainers / fCMO: variable (fractional only)
- Headcount: founders + maybe 1–2 multipurpose hires
Marketing capability:
- Organic only — SEO, content, App Store organic, founder-led social, events, WOM, ambassador (if inbound exists)
- Limited PR (founder-led pitches, HARO responses)
- No paid layer
Channels live: Organic SEO, content, App Store, LinkedIn / X / founder-led social, events, WOM, ambassador
What a fCMO does: Strategy + lifecycle + content + SEO + onboarding + community + ambassador. Hands-on with skill library + MCPs doing the operational lift.
Hires unlocked: None. The plan must execute with current team + agentic stack.
Budget profile:
- Paid acquisition: $5–15K/mo test budget
- Tooling stack: $1,000–3,000/mo (paid ad accounts, Mixpanel / Amplitude if needed, additional SaaS)
- Retainers / fCMO: continued
- Headcount: + first dedicated marketing hire
Marketing capability:
- Above + paid acquisition pilot (Apple Search Ads, Meta, LinkedIn)
- Begin PR push with the funding announcement
- First Product Hunt / GA-style launch
Channels live: All Tier 1 + paid acquisition (small) + active PR
Hires unlocked:
- Lifecycle + content marketing manager (one person doing both, or split)
- OR dedicated growth / performance marketing manager (if heavy paid focus)
fCMO shifts: From hands-on to strategy + ops oversight. Hires the dedicated marketer. Sets up the channel playbooks before paid scales.
Budget profile:
- Paid acquisition: $20–50K/mo
- Tooling stack: $2,000–5,000/mo
- Retainers / fCMO: continued
- Headcount: + designer (potentially fractional)
Marketing capability:
- Paid scaling across 2–3 channels
- Brand-aligned creative production (designer enables velocity)
- Lifecycle programs fully live across all flows
- First true content production cadence (weekly cadence sustainable)
Channels live: All previous + paid scaling + structured launch motion
Hires unlocked:
- Designer (brand, creative, web)
- Second marketing manager (if first was lifecycle, second is content; or vice versa)
- Potentially fractional PR if budget allows
fCMO shifts: Hands off lifecycle to dedicated owner. Moves to GTM strategy + channel mix optimization + growth analytics.
Budget profile:
- Paid acquisition: $50–150K/mo
- Tooling stack: $5,000–10,000/mo
- Retainers / fCMO: may transition to permanent CMO
- Headcount: full marketing team forming
Marketing capability:
- Paid scales aggressively across all proven channels
- Brand campaigns become possible
- International consideration begins
- B2B vertical expansion (if applicable)
- Sophisticated CAC/LTV math + attribution
Channels live: Full marketing surface area
Hires unlocked:
- Performance marketing lead
- Content lead
- Designer (permanent)
- Potentially: PR firm, paid agency, international growth manager
- Series A often the moment the fCMO transitions out or transitions to advisor
fCMO shifts: Often the moment of transition — to permanent CMO hire, fCMO becomes advisor.
Budget profile:
- Paid acquisition: $150K+/mo
- Tooling stack: $10,000–25,000/mo
- Headcount: 10+ marketing org
Marketing capability:
- Brand campaigns at industry scale
- PR firm partnerships
- Acquisitions as marketing (acquiring newsletters / podcasts in space)
- Conference sponsorship at category level
- Sponsorships at brand level
Channels live: Everything available
Hires unlocked:
- VP Marketing or CMO
- Brand director
- Growth / performance team (3–5 people)
- Content team (3–5 people)
- Designers (2–3)
- PR director or agency partnership
- International marketing leads (region-specific)
fCMO involvement: Typically out of the company by this point — the original fCMO might still be an advisor.
references/ops-stack-mapping.md capability-unlocks sectionThe standard tiers assume a typical software / SaaS / consumer app. Adjust for category:
For Tier 1 clients, the marketing budget breakdown typically looks like:
| Line | Typical monthly |
|---|---|
| Customer.io / lifecycle ESP | $100–500 |
| App Store Connect / Google Play | $25 + 30% rev share (Apple/Google take) |
| Stripe | 2.9% + 30¢ per transaction |
| GA4 | Free |
| Notion | $0–100 |
| GitHub | $0–50 |
| Shopify (if hardware) | $39–100 |
| Ahrefs (or similar SEO tool) | $129–399 |
| Typefully (if social cadence) | $13–39 |
| Dub.co (if ambassador tracking) | $0–39 |
| Misc SaaS | $200–500 |
| Tooling total | ~$500–1,700/mo |
| Paid acquisition | $0 |
| fCMO retainer | Variable |
For the plan, this becomes: "Current monthly marketing budget: $X (tooling only, no paid)."
If a founder asks for moves that require a future tier:
- Name the requirement: "This is a Tier 2 move (requires $10K+/mo paid budget). Will unlock after seed close per the 12-month outlook in §10."
- Don't refuse — frame the timing
If a founder underestimates what's needed:
- Be honest: "To scale paid acquisition meaningfully, expect Tier 2 budget. Tier 1 can validate organic; Tier 2 validates paid."
If a founder is over-funded for their stage:
- Don't pad budget to match. Recommend the right work for the funnel state, return excess capacity, suggest investment in compounding rather than scaling.
Some companies skip tiers:
- Notable founder raising larger-than-typical rounds — can jump from Tier 1 to Tier 3 directly
- Hardware company with PR moment — can deploy at Tier 3 levels with the right product moment (e.g., a high-profile longevity-influencer endorsement)
- B2B SaaS post-LOI with named enterprise contracts — can fund pilot deployment from contract value
If the client is in a tier-skip situation, name it explicitly in the plan rather than forcing them into the standard ladder.
The 12-month outlook in every plan (Section 10) describes a trajectory. This doc names the shape of that trajectory honestly — what real SaaS growth looks like, when to expect plateaus, and how to plan for the next leg of growth before the current one stalls.
Excerpted and adapted from Founding Marketing by Corey Haines.
Pitch decks show hockey sticks. Real growth shows a series of S-curves — each representing a distinct phase followed by a plateau that tests resolve and creativity.
The hardest milestone. Every customer is a hard-won victory. Typical time: 6–12 months. Most companies pivot the product multiple times during this phase.
What it requires:
- Runway long enough to keep experimenting until something clicks
- A financial cushion or additional income sources (often the difference between success and shutdown)
- Tolerance for ambiguity — the product positioning, the pricing, and the channel can all still be wrong at this stage
The middle ground that kills most promising startups. The average company reaches ~$40K ARR in year one. The danger: enough revenue to prove the concept, not enough to support a team.
The threshold to watch for: $8–10K MRR. That's when founders can typically go full-time on the business without other income sources. Until then, careful cash management or side income carries the company through.
Companies that flame out in Phase 2 usually run out of runway just as things start working.
Where things get interesting. Typical time: nearly 2 years total to reach $1M. But there's an acceleration pattern: once across $100K, companies often double from $100K → $200K in one-third the time it took to reach the first $100K.
Why: critical mass kicks in. Word-of-mouth starts working. Early customers become your best salespeople. The product has proven itself, and growth becomes more about execution than experimentation.
This is the phase where the marketing plan's 90-day roadmap (Section 9) starts compounding instead of just covering ground.
The myth: successful SaaS companies grow exponentially, doubling revenue month over month like clockwork.
The reality: two distinct patterns, often combining at scale to look exponential when zoomed out.
Build a predictable revenue machine. Find a channel that works (content, partnerships, paid, outbound) and steadily scale it. Some companies reliably add $10K MRR per month through a well-oiled marketing engine.
Less sexy than exponential. Far more sustainable. Crucially, plannable: when you know what you can count on adding each month, hiring decisions, product roadmap, and expansion planning all become tractable.
Periods of plateau followed by sudden jumps. Jumps aren't random — they're triggered by specific events:
- Breaking into a new market segment (e.g., enterprise after starting SMB)
- Launching a major product expansion (new feature line, new tier)
- Cracking a new marketing channel that compounds
Example: one founder saw revenue triple in two months after launching enterprise features — following six months of flat growth.
Key insight for the plan: each step requires deliberate action and investment. Steps don't happen by waiting. While standing on the current step, you have to be actively building the next one.
Zoom out far enough and a series of linear phases + step functions can look exponential. That's where the myth comes from. Understanding it's actually a series of plannable shapes changes how you build the plan:
The secret to sustained growth isn't one perfect channel. It's orchestrating multiple S-curves that work together. Three S-curves to track:
Every marketing channel has its own lifecycle:
- SEO — 6–12 months to mature; once it does, steady leads for years. Marathon runner.
- Paid ads — quick wins; diminishing returns as you scale.
- Content marketing — slow to start, compounds beautifully over time.
- Partnerships / co-marketing — episodic; high yield when the right partner aligns.
- Outbound — predictable when calibrated; CAC-heavy and plateaus at team capacity.
- PR — spike-driven; sustains awareness rather than direct conversion.
The rule: start the next channel before the current one plateaus. Riding one channel to its ceiling before investing in the next produces a multi-month growth plateau that takes more effort to break out of than it would have taken to start the next channel earlier.
In the plan: Section 4 (Acquisition) names current channels, planned channels, and skipped channels. The 12-month roadmap (Section 10) sequences when the next channel investment begins.
Your core product naturally hits a growth ceiling as you saturate the initial market. Pushing harder on the same features doesn't break through. What does:
In the plan: Sections 5 (Activation) and 8 (Revenue) name where the product needs to grow to unlock the next growth tier.
Every market segment has its own growth ceiling. Time the expansion into the next segment while the current segment is still showing strong growth. Common patterns:
Waiting until a segment is saturated makes the transition harder.
In the plan: Section 2 (Strategic frame) names current segment + future segments. Section 10 (12-month outlook) sequences when expansion moves begin.
The real magic: while SEO is maturing, you're using paid for quick wins. As those channels mature, you're developing product features that unlock enterprise. Meanwhile, the groundwork for international expansion is being laid for when domestic saturates.
This is the operational thesis behind the AARRR mapping (Sections 4–8) and the 12-month outlook (Section 10): each section is a curve, and the plan sequences them so the next curve is ramping while the current one is still growing.
For companies that have crossed $1M ARR and raised institutional capital, the VC benchmark is:
| Year | Multiple | Cumulative ARR (from $1M) |
|---|---|---|
| Year 0 | — | $1M |
| Year +1 | 3× | $3M |
| Year +2 | 3× | $9M |
| Year +3 | 2× | $18M |
| Year +4 | 2× | $36M |
| Year +5 | 2× | $72M |
| Year +6 | 2× | $144M |
| Year +7 | 2× | $288M |
Most companies don't hit this. Useful regardless — anchoring the 12-month outlook against this benchmark forces the plan to either (a) match it and show how, or (b) explicitly defend choosing a slower trajectory.
For non-VC-backed (bootstrapped, founder-funded, profit-focused) companies, this curve doesn't apply. Use linear or step-function targeting instead.
| Section | What to include |
|---|---|
| 3 (Current state) | Where the company is on each S-curve (channel maturity, product maturity, market saturation). Name the current phase ($0–10K / $10K–100K / $100K–1M / $1M+). |
| 4 (Acquisition) | Current channels + their position on the S-curve (early / mature / plateauing). Next channel investment with rationale. |
| 5–8 (AARRR) | Each section names the binding constraint at the current phase. For Phase 2 companies, Activation is usually the leverage point. For Phase 3, Retention + Referral compound the existing growth. |
| 9 (90-day roadmap) | Linear-pattern moves dominate (predictable additions). Step-function setups (the build-up to a launch, an enterprise tier, a new market segment) live here. |
| 10 (12-month outlook) | Sequence channel S-curves, product S-curves, market S-curves. If VC-backed Series A+, anchor against 3-3-2-2-2. If not, name the linear or step-function targets. |
| 13 (Measurement) | The north-star metric reflects the current phase (Phase 1 is usually pure new-signup; Phase 3 is usually expansion ARR or NRR). |
The marketing-ideas skill catalogs 139 proven marketing tactics. This doc is the source-of-truth mapping: every idea assigned to a primary AARRR stage, with notes for when it's typically active and what category constraints apply.
The plan's Section 12 ("Tactical idea bank") uses this mapping as the base, then layers client-specific filters: brand voice rules might skip some ideas; funding stage might shift Q-status; client category might rule out others.
marketing-ideas.marketing-ideas skill ordering. If marketing-ideas reorders or expands, update this doc.These ideas primarily serve top-of-funnel awareness, traffic, and lead generation.
| # | Idea | Category | Typical stage available |
|---|---|---|---|
| 1 | Easy Keyword Ranking | Content & SEO | Now (any stage) |
| 2 | SEO Audit | Content & SEO | Now |
| 3 | Glossary Marketing | Content & SEO | Q2+ |
| 4 | Programmatic SEO | Content & SEO | Q3+ (needs data + template system) |
| 5 | Content Repurposing | Content & SEO | Now (immediate leverage) |
| 6 | Proprietary Data Content | Content & SEO | Now (if data exists) |
| 7 | Internal Linking | Content & SEO | Now |
| 8 | Content Refreshing | Content & SEO | Q2+ (after content base exists) |
| 9 | Knowledge Base SEO | Content & SEO | Q3+ (after help docs exist) |
| 10 | Parasite SEO | Content & SEO | Now |
| 11 | Competitor Comparison Pages | Competitor | Q2+ |
| 12 | Marketing Jiu-Jitsu | Competitor | Now |
| 13 | Competitive Ad Research | Competitor | Pre-paid |
| 14 | Side Projects | Free Tools | Q3+ |
| 15 | Engineering as Marketing | Free Tools | Q3+ |
| 16 | Importers as Marketing | Free Tools | SaaS-specific |
| 17 | Quiz Marketing | Free Tools | Q2+ |
| 18 | Calculator Marketing | Free Tools | Q3+ |
| 19 | Chrome Extensions | Free Tools | Browser-relevant only |
| 20 | Microsites | Free Tools | Q3+ |
| 21 | Scanners | Free Tools | Specific products only |
| 22 | Public APIs | Free Tools | Developer/dev tool products |
| 23 | Podcast Advertising | Paid Ads | Post-budget |
| 24 | Pre-targeting Ads | Paid Ads | Post-budget |
| 25 | Facebook Ads | Paid Ads | Post-budget |
| 26 | Instagram Ads | Paid Ads | Post-budget |
| 27 | Twitter Ads | Paid Ads | Post-budget |
| 28 | LinkedIn Ads | Paid Ads | Post-budget (B2B-strong) |
| 29 | Reddit Ads | Paid Ads | Post-budget |
| 30 | Quora Ads | Paid Ads | Post-budget |
| 31 | Google Ads | Paid Ads | Post-budget |
| 32 | YouTube Ads | Paid Ads | Post-budget |
| 33 | Cross-Platform Retargeting | Paid Ads | Post-paid-firing |
| 34 | Click-to-Messenger Ads | Paid Ads | Niche use cases |
| 35 | Community Marketing | Social & Community | Q3+ |
| 36 | Quora Marketing | Social & Community | Now |
| 37 | Reddit Keyword Research | Social & Community | Now |
| 38 | Reddit Marketing | Social & Community | Q2+ |
| 39 | LinkedIn Audience | Social & Community | Now (B2B + founders) |
| 40 | Instagram Audience | Social & Community | Q2+ |
| 41 | X Audience | Social & Community | Depends on founder bandwidth |
| 42 | Short Form Video | Social & Community | Q3+ |
| 43 | Engagement Pods | Social & Community | Generally off-brand |
| 44 | Comment Marketing | Social & Community | Q2+ |
| 49 | Monthly Newsletters | Q2+ (Acquisition use: subscriber capture) | |
| 54 | Affiliate Discovery via Backlinks | Partnerships | Q2+ |
| 55 | Influencer Whitelisting | Partnerships | Post-paid-budget |
| 56 | Reseller Programs | Partnerships | Q4+ |
| 57 | Expert Networks | Partnerships | Q3+ |
| 58 | Newsletter Swaps | Partnerships | Q2+ |
| 59 | Article Quotes (HARO) | Partnerships | Now |
| 60 | Pixel Sharing | Partnerships | Post-paid |
| 61 | Shared Slack Channels | Partnerships | Q3+ |
| 63 | Integration Marketing | Partnerships | Q3+ |
| 64 | Community Sponsorship | Partnerships | Q2+ |
| 65 | Live Webinars | Events | Q2+ |
| 66 | Virtual Summits | Events | Q3+ |
| 67 | Roadshows | Events | Q4+ |
| 68 | Local Meetups | Events | Q3+ |
| 69 | Meetup Sponsorship | Events | Q3+ |
| 70 | Conference Speaking | Events | Now (if founder is speakable) |
| 71 | Conferences (own-hosted) | Events | Q4+ |
| 72 | Conference Sponsorship | Events | Q3+ |
| 73 | Media Acquisitions | PR & Media | Series A+ |
| 74 | Press Coverage | PR & Media | Now (if newsworthy) |
| 75 | Fundraising PR | PR & Media | When fund closes |
| 76 | Documentaries | PR & Media | Q4+ |
| 77 | Black Friday Promotions | Launches | Q4 (seasonal) |
| 78 | Product Hunt Launch | Launches | At GA or major feature |
| 79 | Early-Access Referrals | Launches | Pre-launch or GA |
| 80 | New Year Promotions | Launches | Q1 (seasonal) |
| 81 | Early Access Pricing | Launches | GA |
| 82 | Product Hunt Alternatives | Launches | Same as PH |
| 83 | Twitter Giveaways | Launches | Generally off-brand |
| 84 | Giveaways | Launches | Q3+ |
| 85 | Vacation Giveaways | Launches | Q4+ (seasonal) |
| 86 | Lifetime Deals | Launches | Generally off-brand (damages LTV math) |
| 87 | Powered By Marketing | Product-Led | Q4+ |
| 88 | Free Migrations | Product-Led | SaaS-specific |
| 89 | Contract Buyouts | Product-Led | B2B SaaS only |
| 97 | Playlists as Marketing | Content Formats | Q3+ |
| 98 | Template Marketing | Content Formats | Q3+ |
| 99 | Graphic Novel Marketing | Content Formats | Generally off-brand |
| 100 | Promo Videos | Content Formats | Q3+ |
| 101 | Industry Interviews | Content Formats | Q2+ |
| 102 | Social Screenshots | Content Formats | Q2+ |
| 103 | Online Courses | Content Formats | Q3+ |
| 104 | Book Marketing | Content Formats | Q4+ |
| 105 | Annual Reports | Content Formats | Q4+ |
| 106 | End of Year Wraps | Content Formats | Q4 (seasonal) |
| 107 | Podcasts (own-hosted) | Content Formats | Q3+ |
| 108 | Changelogs | Content Formats | Q2+ |
| 109 | Public Demos | Content Formats | Now |
| 110 | Awards as Marketing | Unconventional | Q4+ |
| 111 | Challenges as Marketing | Unconventional | Q3+ |
| 112 | Reality TV Marketing | Unconventional | Generally off-brand |
| 113 | Controversy as Marketing | Unconventional | Brand-dependent |
| 114 | Moneyball Marketing | Unconventional | Ongoing methodology |
| 115 | Curation as Marketing | Unconventional | Q2+ |
| 116 | Grants as Marketing | Unconventional | Q4+ |
| 117 | Product Competitions | Unconventional | Developer-specific |
| 118 | Cameo Marketing | Unconventional | Generally off-brand |
| 119 | OOH Advertising | Unconventional | Series A+ |
| 120 | Marketing Stunts | Unconventional | Brand-dependent |
| 121 | Guerrilla Marketing | Unconventional | Brand-dependent |
| 122 | Humor Marketing | Unconventional | Brand-dependent |
| 123 | Open Source as Marketing | Platforms | Developer products |
| 125 | App Marketplaces | Platforms | Platform-specific |
| 126 | YouTube Reviews | Platforms | Q3+ |
| 127 | YouTube Channel | Platforms | Q3+ |
| 128 | Source Platforms | Platforms | B2B SaaS only |
| 129 | Review Sites | Platforms | Now |
| 130 | Live Audio | Platforms | Q3+ |
| 131 | International Expansion | International | Q4+ |
| 133 | Investor Marketing | Developer/etc | Now (when raising) |
| 138 | Podcast Tours | Audience-Specific | Q2+ |
| # | Idea | Category | Typical stage available |
|---|---|---|---|
| 47 | Founder Welcome Email | Q2+ (Activation use) | |
| 48 | Dynamic Email Capture | Q2+ | |
| 51 | Onboarding Emails | When UI is stable | |
| 90 | One-Click Registration | Product-Led | Now |
| 91 | In-App Upsells | Product-Led | Q2+ (cross-cuts Revenue) |
| 95 | Concierge Setup | Product-Led | Q3+ (high-value users) |
| 96 | Onboarding Optimization | Product-Led | Now |
| 124 | App Store Optimization | Platforms | Now (App Store products) |
| # | Idea | Category | Typical stage available |
|---|---|---|---|
| 45 | Mistake Email Marketing | Opportunistic | |
| 46 | Reactivation Emails | Now | |
| 50 | Inbox Placement | Now (technical setup) | |
| 52 | Win-back Emails | Q1+ | |
| 53 | Trial Reactivation | Q2+ (when paywall is firing) | |
| 94 | Offboarding Flows | Product-Led | Q2+ |
| 135 | Support as Marketing | Developer/etc | Q2+ |
| 134 | Certifications | Developer/etc | Q3+ (cross-cuts Referral) |
| # | Idea | Category | Typical stage available |
|---|---|---|---|
| 62 | Affiliate Program | Partnerships | Now (when inbound exists) |
| 79 | Early-Access Referrals | Launches | Pre-launch / GA |
| 92 | Newsletter Referrals | Product-Led | Q3+ (if newsletter exists) |
| 93 | Viral Loops | Product-Led | Q3+ |
| 137 | Two-Sided Referrals | Audience-Specific | Q2+ |
| # | Idea | Category | Typical stage available |
|---|---|---|---|
| 91 | In-App Upsells | Product-Led | Q2+ (cross-cuts Activation) |
| 132 | Price Localization | International | Q4+ |
Skipped from Revenue: #86 Lifetime Deals appears under Launches (Acquisition section) only. It's generally off-brand for subscription products because it damages LTV math; recommend in Section 12's Skip list with rationale, not in stage totals.
| # | Idea | Category | Typical stage available |
|---|---|---|---|
| 114 | Moneyball Marketing | Unconventional | Ongoing methodology |
| 139 | Customer Language | Audience-Specific | Now (foundational) |
| # | Idea | Category | Use when |
|---|---|---|---|
| 117 | Product Competitions | Unconventional | Developer tool products |
| 136 | Developer Relations | Developer/etc | Developer tool products |
For Section 12 of the plan:
For each idea, ask:
- Does this idea apply to the client's category? (e.g., #16 Importers only for SaaS; #19 Chrome Extensions only for browser-relevant; #136 DevRel only for dev tools)
- Skip ideas that don't apply, with a note
For each idea, ask:
- Does this idea conflict with the client's brand voice?
- Common conflicts:
- Lifetime Deals (#86) — conflicts with premium positioning
- Twitter Giveaways (#83) — often off-brand for serious / clinical / luxury voices
- Humor Marketing (#122) — off-brand for serious / clinical voices
- Cameo Marketing (#118) — off-brand for most voices
- Reality TV Marketing (#112) — off-brand for most voices
If conflict, place in Skip list with explicit rationale.
For ideas that pass filters, set status:
- Now (Q1) — already in 90-day plan OR can run alongside without new capacity
- Q2 — post-bedrock-fix, post-foundation; second-quarter layer-in
- Q3+ — post-seed-close, post-GA; expansion moves
- Q4+ — long-game / large-investment
Use the "Typical stage available" column as the default. Shift earlier if client has unusual capability (e.g., a celebrity founder shifts Conference Speaking #70 from "Now" to "Now and high-leverage").
Every "Now / Q2 / Q3+" idea gets a one-line client-specific note. Examples:
- For idea #11 Competitor Comparison Pages: "Quietude vs. Calm / Headspace / Brain.fm / Endel / Wavepaths — high-intent SERPs"
- For idea #133 Investor Marketing: "Alex's seed raise — leverage angel backchannel for PR + intros"
- For idea #15 Engineering as Marketing: "HRV interpretation guide; nervous system self-assessment; sound bath finder directory"
After all five AARRR tables + skip list:
### Idea-bank summary
- {Acquisition count} ideas applicable to Acquisition (the dominant stage at {client}'s current stage)
- {Activation count} to Activation, {Retention count} to Retention
- {Referral count} to Referral
- {Revenue count} to Revenue
- {cross-cutting count} cross-cutting
- {skipped count} ideas skipped for brand / business-model fit
**What this proves:** the plan is roughly X% of the available tactical surface area, not 100%. {appropriate or not for the stage} — as capacity unlocks across Q2 → Q3 → Series A, the cross-reference becomes the inventory to scale activity without losing strategic coherence.
If marketing-ideas adds new ideas (it's a living skill — the 139 may become 145 or 160 over time):
1. Read skills/marketing-ideas/references/ideas-by-category.md in the marketingskills repo
2. Assign each new idea to a primary AARRR stage using the rules above
3. Add to this doc's tables
4. Update SKILL.md's idea-count reference
skills/marketing-ideas/SKILL.md (in the marketingskills repo)skills/marketing-ideas/references/ideas-by-category.md (in the marketingskills repo)Every plan needs a measurement section that tells the team how to know if the plan is working. This doc is the source for Section 13's measurement subsection.
Related docs:
- growth-patterns.md — the 3-3-2-2-2 VC growth path (3× in years 1–2, 2× in years 3–7 from $1M ARR) and which phase of SaaS growth the company is in ($0–10K / $10K–100K / $100K–1M+)
- budget-planning.md — CAC calculation (blended, not paid-only) and the forecasting reality check (forecasts under $100M ARR are educated guesses, not precise predictions)
A north star is one metric that captures the business-model thesis at the highest level. It should:
- Be derivable from the funnel + revenue model
- Move slowly enough to be a strategic compass (not whipsawed by weekly noise)
- Trade off correctly against other metrics — improving the north star should generally improve the business
Don't default to "ARR" or "MRR" alone. Those are outcomes, not norths. Pick something that captures the business model.
After the north star, every plan needs leading indicators per AARRR stage. These move faster than the north star and trigger investigations.
The plan should specify three rhythms:
For each quarter in Section 10, the plan must include 3–5 specific KPI targets. These should be:
- Specific — not "improve retention," but "Day 30 retention from 22% → 30%"
- Measurable — pull from a wired data source
- Stretch but plausible — based on funnel state + historical patterns
- Decision-triggering — if missed, what does that mean? (Adjust strategy, kill a channel, etc.)
Q1 (foundation quarter):
- Mostly bedrock metrics — fixing leaks. "Headphones-gate conversion drop reverses." "Day 1 → paid +25–50%."
- Some foundation metrics — laying tracks. "4 SEO pillars staked." "App Store rewrite shipped."
- Avoid bold growth targets — the foundations aren't in yet
Q2 (validation quarter):
- Mostly validation metrics — does what we built work? "Paid CAC < $X blended." "Organic traffic 1,500–3,500/mo."
- Some cohort metrics — do new cohorts behave better? "Day 7 retention for Q2 cohort vs. Q1."
Q3 (scaling quarter):
- Mostly scaling metrics — how far does it go? "Paid scaling to $20–30K/mo with CAC steady." "First B2B install reference case live."
- Some capability metrics — what new things are live? "First Guides pilot launched."
Q4 (compound quarter):
- Mostly compound metrics — is the flywheel turning? "50%+ of new subs from non-paid channels." "Ambassador-driven 15–25% of new subs."
- Some narrative metrics — does the Series A story write itself? "Blended LTV/CAC > 3."
For VC-backed clients past $1M ARR, anchor 12-month and multi-year targets against the 3-3-2-2-2 rule (3× in years 1 and 2, then 2× in years 3 through 7). Hitting it is rare; most companies don't. Anchoring against it forces the plan to either match it and show how, or explicitly defend choosing a slower trajectory. Full table and context in growth-patterns.md.
For non-VC-backed companies (bootstrapped, founder-funded, profit-focused), the 3-3-2-2-2 doesn't apply. Use linear-pattern targets ("$X MRR added per month") or step-function targets ("$Y revenue jump after the enterprise tier launches") instead.
A plan derives a budget and an annual goal. It does not produce a 12-month month-by-month forecast that's reliably accurate to the dollar.
Unless the company is publicly traded, all forecasts are educated guesses. No startup under $100M ARR consistently hits month-by-month forecasts. Quarterly review is when the plan adjusts — not when variance is treated as failure.
What the plan commits to honestly:
- The annual goal is a defensible direction-of-travel
- The budget is the resource commitment that makes the goal plausible
- The 90-day roadmap (Section 9) is what's actionable now
- Month-to-month projection is illustrative, not promised
Founders who over-engineer the forecast end up explaining variance every month instead of executing. The plan should resist this — name the annual target, the quarterly KPIs, and the kill criteria. Don't promise the month.
Full context in budget-planning.md.
For every channel or initiative, the plan should specify when to stop. Often missing from plans, kill criteria force discipline.
Examples:
- "If a paid channel has CAC > 2× target after 30 days at meaningful spend, pause."
- "If onboarding Variant 3 doesn't show statistically meaningful lift (or directional lift + congruent qualitative signal) after 4 weeks, move to Variant 1."
- "If lifecycle Flow 4 has open rate < 12% after 6 weeks, redo subject lines + audience segmentation."
Some metrics get a hard guardrail (cannot drop below threshold). Useful for protecting brand or unit economics during aggressive growth.
Examples:
- "Brand voice complaint rate > 1% of customer feedback triggers content review."
- "Paid CAC > $X for two consecutive months pauses paid scaling pending audit."
- "App Store rating drops below 4.5 triggers product review."
The plan should name where each metric comes from. This makes it auditable.
| Metric | Source |
|---|---|
| Organic traffic | GA4 / Ahrefs |
| App Store conversion | App Store Connect |
| Funnel conversion (Day N → paid) | Internal analytics (Mixpanel / Amplitude) or App Store Connect cohort export |
| Retention | Customer.io segments + product analytics |
| MRR / ARR | Stripe (via MCP if wired) |
| Plan mix | Stripe |
| Lifecycle email metrics | Customer.io |
| Ambassador attribution | Dub.co |
| Hardware → app activation | Shopify + App Store + internal join |
| NPS | Survey tool (Customer.io / Typeform / SurveyMonkey) |
If a metric can't currently be measured, flag it in Section 13's open decisions. Example:
"Hardware → app activation rate not currently visible in the App Store dashboard. Requires Shopify ↔ App Store Connect join. Q1 work item."
A plan with un-measurable goals is a plan that can't be validated. Surface the instrumentation work explicitly.
Where possible, auto-generate the metrics review rather than building it manually each time. Stripe MCP + GA4 MCP + Customer.io MCP can pull most of what's needed.
For Tier 1 clients, a simple weekly metrics email to the team (Markdown table, generated via skills + MCPs) costs nothing and creates discipline.
For Tier 2+ clients, consider a real dashboard (Hex, Metabase, Looker, or internal tool).
The three-phase workflow that produces a comprehensive marketing plan. SKILL.md is the orchestration layer; this is the operational detail.
Goal: Walk into Phase 2 with enough context to draft every section without guessing.
Canonical file layout for every plan:
~/marketing-plans/{client-slug}/
├── materials/ # Client-provided files (decks, audit output, brand-voice doc, etc.)
├── research.md # Written in Phase 1 (INIT)
├── progress.md # State machine — see Step 1.1.1 for schema
├── sections/
│ ├── 01.md # Executive summary (written last, ordered first)
│ ├── 02.md # Strategic frame
│ ├── ...
│ └── 13.md # Measurement, RACI, open decisions, appendix
└── final_plan.md # Compiled deliverable (Phase 3 output)
progress.md state schemaEvery plan tracks a single progress.md file at the plan root. It's the source of truth for resumption. Schema:
# {Client} — Marketing Plan Progress
phase: init | review | finalize | finalized
current_section: <number, only meaningful during review phase>
plan_version: v1
last_updated: YYYY-MM-DD HH:MM
## Sections completed
- [ ] 2. Strategic frame
- [ ] 3. Current state
- [ ] 4. Acquisition
- [ ] 5. Activation
- [ ] 6. Retention
- [ ] 7. Referral
- [ ] 8. Revenue
- [ ] 9. 90-day roadmap
- [ ] 10. 12-month outlook
- [ ] 11. Marketing operations stack
- [ ] 12. Tactical idea bank
- [ ] 13. Measurement, RACI, open decisions, appendix
- [ ] 1. Executive summary (synthesized last)
## Approved artifacts
sections/02.md, sections/03.md, ... (list as they're written)
## Notes
<any open decisions, blockers, or out-of-band context that aren't in research.md>
On every invocation, check state in this order:
{client-slug}/ folder → fresh plan. Create folder + materials/ + empty sections/. Start INIT (Step 1.2).research.md → INIT was interrupted. Resume from Step 1.2.research.md exists, no progress.md → INIT done, REVIEW not started. Create progress.md, start REVIEW from Section 2.progress.md exists, phase: review → REVIEW in progress. Resume from current_section (or first unchecked box).progress.md exists, phase: finalize → FINALIZE was interrupted. Re-run Phase 3.progress.md exists, phase: finalized → plan is done. Do not silently overwrite. Ask the user: "This plan is finalized (v{N}). Want to (a) revise it as v{N+1}, (b) start a fresh plan in a new folder, or (c) re-open a specific section?"Update phase and last_updated whenever state changes.
If materials/ has files, read all of them. Common drops:
- Pitch deck / investor deck
- Positioning doc / brand voice doc
- Customer research / ICP doc
- App Store metrics / analytics snapshot
- Lifecycle email inventory
- Prior audit output (any scored current-state assessment the team has run)
- SEO research (seo/plan.md, seo/keyword-shortlist.md)
- Kickoff call transcript
- Founder Slack / async notes
Read everything. Capture key facts to research.md as you go.
If MCPs/APIs are wired for this client, pull:
/seo-audit skill)dev-browser) → install → trial → paid funnel; cohort retentionDon't ask the user to copy/paste data that can be pulled directly.
For every gap in the materials, ask the user. The minimum intake covers ten topics:
team-and-agency-model.md for the framework that informs Section 11 RACI and the first-hire recommendation in Section 9.funding-stage-unlocks.md)?budget-planning.md can be applied to Section 8 (Revenue) and Section 10 (12-month outlook).What past work should this plan acknowledge?
- Major launches and dates
- PR moments and who covered
- Content pillars / hubs / cornerstone pieces
- Partnerships
- Awards / certifications
- Notable customers / users (if consumer-named users)
- Past advisors / fractionals
Use the 17-section rubric in references/current-state-rubric.md as your scoring lens. Two modes:
Either way, the output is the scored 17-row table that becomes Section 3 of the plan, followed by a 2–4 sentence "shape interpretation" calling out where strengths and gaps cluster.
Compile everything into research.md with this structure:
# {Client} — Marketing Plan Research Record
**Date:** YYYY-MM-DD
**Author:** (fCMO / planner name)
## Company snapshot
- One-sentence description
- Stage (pre-seed / seed / Series A / etc.)
- Product status (beta / GA)
## ICP
- Primary ICP
- Stated vs. actual problem
- Demographics / firmographics
## Funnel state today
- Current numbers
- Funnel shape
- Biggest leak
## Funding
- Total raised
- Current round status
- Runway
## Team
- Founders and ownership
- Marketing surface area by person
- Gaps
## Current marketing budget
- $/mo total
- Breakdown
- Tier mapping
## Channels currently active
[By AARRR stage]
## Already done (acknowledge in plan)
[List]
## In-flight and stuck
[List with blockers]
## Strategic posture
- Founder's top priority
- Founder's top de-prioritization
- Investor pressure points
- Constraints
## Current-state rubric scores
[17 section scores using `references/current-state-rubric.md`. If a prior scored audit exists, paste those scores. Otherwise mark "scored from materials."]
## Materials read
[List of files in materials/ + when read]
Save. Move to Phase 2.
Goal: Walk through all 13 sections of the plan template (references/plan-template.md), drafting each, getting user confirmation, saving as you go.
Use the schema defined in Step 1.1.1 above. Set phase: review, current_section: 2, plan_version: v1, and stamp last_updated.
Section 1 (Executive Summary) is drafted last because it depends on every other section's conclusions. Walk Sections 2 → 13 in numeric order, then synthesize Section 1 from the others. The final compiled final_plan.md is always presented in canonical order 1 → 13.
For each section, use the template at references/plan-template.md to draft. Then in chat:
sections/01.md ... sections/13.md (one file per section, zero-padded for sort order). This is the canonical persisted artifact — recovery depends on it.progress.mdSection 1 (Executive summary) is synthesized from Sections 2–13 after they're all approved. Draft it last; present it first in the output document.
Section 3 (Current state) uses the embedded 17-section rubric in references/current-state-rubric.md. If a prior scored audit exists, paste those scores in. If not, score from available materials.
Sections 4–8 (AARRR) each follow the same internal structure: current state, the plan (numbered moves), 90-day moves, 12-month outlook, skills + tools. Don't skip the skills + tools sub-section — it's what makes the plan operationally honest.
Section 11 (Marketing operations stack) is auto-generatable from references/ops-stack-mapping.md plus the specific moves named in Sections 4–8.
Section 12 (Idea bank) is auto-generatable from references/idea-cross-reference.md plus client-specific filters (skip ideas that conflict with brand voice; status moves based on funding-stage timing).
Section 13 lives at the end. Open decisions should be ranked by impact. Appendix should reference only files the team can access (warn about machine-local paths).
If the client has documented brand voice rules (captured in research.md / Section 2), every section must respect them. Common voice constraints:
- Vocabulary rules (YES / NO lists)
- CTA rules (e.g., "never pressure")
- Initiatory vs. explanatory framing
- Tone (e.g., authoritative-yet-accessible, intimate-yet-professional)
If a section's draft violates the brand voice, redo it before showing it to the user.
Goal: Produce final_plan.md and optionally publish to a shared repo.
Set phase: finalize in progress.md before starting. Concatenate sections/01.md through sections/13.md into final_plan.md (canonical order 1 → 13, regardless of drafting order). Add:
- Title header with date and "v1" version marker
- "Prepared by / For / Date / Status" frontmatter
- Section anchors that work in Notion paste
Before printing:
references/idea-cross-reference.md. Every related-skill mention either exists in the marketingskills repo or is documented as an external dependency (see ops-stack-mapping note on cross-marketplace skills)./Users/..., /home/...) in the output. Replace with descriptive references.Output final_plan.md to the plan folder. Print a summary to chat:
"Marketing Plan v1 saved to
~/marketing-plans/{client-slug}/final_plan.md. ~X,XXX words across 13 sections. Ready to paste into Notion or share with the team."
Ask the user:
"Want me to publish this to a shared GitHub repo so the team can access it? If yes, what's the target repo and path (e.g.,
{client-org}/{client-context}/marketing/plan.md)?"
If yes:
- Clone (or assume cloned) target repo
- Check out a feature branch or push direct to main per user's preference
- Copy final_plan.md to the target path
- Adjust the appendix to use repo-relative paths (not machine paths)
- Commit + push
- Confirm with commit URL
If no: leave it local. Done.
Set phase: finalized in progress.md and stamp last_updated. This is the terminal state and prevents future /marketing-plan invocations from silently overwriting the plan (see Step 1.1.2 case 6).
Resumption is governed entirely by the decision tree in Step 1.1.2 above — always check state in that order on every invocation.
If the user says "start over" → ask whether they want to delete the existing folder or move it to archive/ first; don't silently overwrite.
If the user says "redo Section X" → uncheck that box in progress.md, delete sections/0X.md, and re-draft.
[TBD — to confirm with team] in the plan and add to open decisions.This doc maps every marketing-skill and every relevant MCP/API integration to the AARRR stage(s) it primarily serves. It's the source for Section 11 of every plan.
Note on scope. Skills below live in this
marketingskillsrepo. A few references point to optional tools from adjacent Claude Code marketplaces (e.g.,vercel:agent-browser,compound-engineering:diagram-maker) — substitute equivalents if not installed. When a plan references a skill or tool that isn't available, fall back to the underlying tactic and call it out in Section 13's open decisions.
A small team + fCMO + agentic tooling = output of a 15–20-person traditional marketing org. The skills + MCPs encode workflows that previously required dedicated headcount per channel.
The plan's Section 11 makes this thesis explicit by:
1. Mapping skills to stages so the founder sees which skills execute which work
2. Mapping MCPs/APIs to stages so the founder sees the tooling layer
3. Naming a concrete operational example that proves the stack works
4. Showing capability unlocks by funding stage (pre-seed → seed → Series A)
| Skill | What it does | Primary use in Acquisition |
|---|---|---|
seo-audit |
Audit site for technical and on-page SEO | Quarterly site health checks |
ai-seo |
Optimize content for AI search engines / LLM citation | Future-proof content strategy |
programmatic-seo |
Build template-driven SEO pages at scale | Location, comparison, integration page systems |
schema |
Add structured data markup | Rich snippets, eligibility for AI citation |
content-strategy |
Plan content topics, pillars, cadence | Setting the editorial calendar |
competitors |
Build vs-pages and alternative-to-pages | Capture high-intent SERPs against competitors |
ads |
Plan and structure paid campaigns | Apple Search Ads, Meta, Google, LinkedIn |
ad-creative |
Generate ad variations and creative | Iterate ad creative across platforms |
social |
Plan and write social media content | LinkedIn, Twitter/X, Instagram, TikTok |
typefully |
Schedule/post tweets, threads, LinkedIn content | Cadence operations for founder-led channels |
cold-email |
Write B2B cold outreach + sequences | Outbound for B2B SaaS / hybrid businesses |
analytics |
Set up tracking, GA4, conversion events | Funnel instrumentation |
free-tools |
Plan engineering-as-marketing free tools | Build tools that generate links + leads |
marketing-website-design |
Design marketing sites with intention | Pillar/landing page design |
launch |
Plan and execute launches (Product Hunt, GA, feature launches) | GTM moments — strategy + tactical execution |
| Skill | What it does | Primary use in Activation |
|---|---|---|
onboarding |
Optimize user onboarding flows | Onboarding rebuild, activation rate tests |
signup |
Optimize signup/registration | Reduce friction at top of activation |
cro |
Optimize any marketing page or form | Conversion testing across pages, forms, landing pages |
paywalls |
Optimize paywalls and upgrade screens | Trial → paid conversion (also Revenue) |
popups |
Optimize popups, modals, slide-ins | Lead capture + activation prompts |
copywriting |
Write marketing copy | Onboarding screens, paywall copy, CTAs |
copy-editing |
Edit and improve existing copy | Voice / clarity pass before ship |
copycraft |
Real-time copy variation overlay | Live copy iteration during reviews |
website-copy |
Write full website copy (stage-8 from CF process) | Comprehensive site copy production |
ab-testing |
Plan A/B tests | Structure for onboarding variant tests |
marketing-psychology |
Apply behavioral science to copy and CRO | Persuasion principles in activation moments |
| Skill | What it does | Primary use in Retention |
|---|---|---|
emails |
Design email sequences | Customer.io / Mailchimp / Resend flow building |
churn-prevention |
Build cancellation flows, save offers, win-back | Reduce churn, recover failed payments |
copywriting / copy-editing |
Email copy production | Lifecycle email content |
paywalls |
(cross-cuts) — upgrade prompts in retention emails | Upsell within lifecycle |
ab-testing |
Test email variants | Subject line, CTA, timing tests |
| Skill | What it does | Primary use in Referral |
|---|---|---|
referrals |
Plan and launch referral / affiliate / ambassador programs | Core skill for Section 7 |
social |
Create ambassador-shareable content | Talking points, post templates |
copywriting |
Ambassador / affiliate email copy | Recruitment, onboarding, communication |
marketing-website-design |
Per-ambassador landing pages | Attribution surface |
emails |
Ambassador lifecycle emails | Onboarding, monthly digest, payout notifications |
| Skill | What it does | Primary use in Revenue |
|---|---|---|
pricing |
Audit and optimize pricing | Plan tier structure, annual defaults, value metrics |
paywalls |
Paywall optimization | Trial → paid, free → paid conversion |
sales-enablement |
Build sales decks, one-pagers, demos | B2B sales support material |
revops |
Revenue operations, lead lifecycle | Marketing → sales handoff |
ab-testing |
Pricing experiments | Test annual default, intro pricing, tier consolidation |
| Skill | What it does | Primary use |
|---|---|---|
product-marketing |
Set up the .agents/product-marketing.md context file (positioning, ICP, voice) |
Foundational — run first; every section of the plan references this |
customer-research |
Conduct customer interviews + surveys | Section 2 + Section 3 (Current state) |
marketing-psychology |
Apply behavioral science | Cross-cuts copy, CRO, paywalls |
marketing-ideas |
The 139-idea library | Section 12 of plan (Idea bank) |
| Tool | What it provides | Wired-at-client check |
|---|---|---|
| Ahrefs API | SEO data: keyword research, backlinks, competitor analysis | Required AHREFS_API_KEY in .env |
| DataForSEO API | SERP data, keyword volume, competitor SERP analysis | Required API key |
| GA4 MCP | Traffic by channel, conversion events, retention curves | Wired via gcp project + service account |
| GitHub MCP | Repo work: marketing site (site-name-promo patterns), content authoring |
Standard gh CLI auth + MCP server |
| Typefully MCP | Social posting (LinkedIn, X, Threads, Bluesky) | Typefully account + API key |
| Google Ads MCP | Ad account management, campaign creation, performance pulls | Wired post-budget-unlock |
| agent-browser | Browser automation (form fills, screenshots, scraping) | CLI install: npm install -g agent-browser |
| dev-browser | General-purpose browser automation | MCP server install |
| defuddle | Clean markdown extraction from web pages | CLI install |
| Notion | Internal knowledge directory access | Notion API key |
| Stripe MCP | LTV math, paid-CAC reconciliation (cross-cuts to Revenue) | Stripe account + restricted key |
| Tool | What it provides |
|---|---|
| App Store Connect | Conversion rate by listing variant, install funnel |
| GitHub MCP | Mobile app repo for onboarding code edits |
| Figma / Pencil MCP | Onboarding screen design + iteration |
| Customer.io MCP | In-app messaging + lifecycle email coordination |
| Stripe MCP | Subscription state for paywall logic |
| GA4 MCP | Activation events instrumentation |
| Tool | What it provides |
|---|---|
| Customer.io MCP | The retention infrastructure — flow building, segmentation, sending |
| Shopify | Hardware buyer events as lifecycle triggers |
| Stripe MCP | Subscription state, churn cohorts, plan changes |
| GA4 MCP | Session events, retention curves |
| Resend / Mailchimp / SendGrid | Alternatives to Customer.io for different stacks |
| Tool | What it provides |
|---|---|
| Dub.co | Ambassador attribution, short links, per-ambassador tracking |
| Stripe MCP | Commission accounting + payouts via Connect |
| GitHub MCP | Per-ambassador landing pages |
| Customer.io MCP | Ambassador lifecycle (recruitment → onboarding → monthly digest → payout notifications) |
| Rewardful / Tolt / Mention Me | Alternatives to Dub for affiliate management |
| Tool | What it provides |
|---|---|
| Stripe MCP | Pricing tests, subscription analytics, churn cohort analysis, blended CAC math |
| Shopify | Hardware transactions |
| GA4 MCP | Revenue events |
| Customer.io MCP | Paywall / pricing-related lifecycle |
| Notion | Commercial knowledge directory |
| Tool | What it provides |
|---|---|
| Notion | Shared knowledge base |
| GitHub MCP | Shared context repo ({client-org}/{client-context}) |
| defuddle | Research extraction |
| obsidian-cli | Working notes for fCMO |
| Pencil MCP | Design files |
| Figma MCP | Design files (if Figma) |
The plan's Section 11 must include this table (or equivalent), specific to the client's current and projected funding stages.
| Stage | Headcount | Tooling | Channels live |
|---|---|---|---|
| Pre-seed / bootstrapped | fCMO + founder team | All current tooling + marketing-skills library + MCP layer | Organic only (SEO, content, App Store, founder-led social, events, WOM, ambassador) |
| Seed close | + first marketing hire (lifecycle/content owner) | + paid ad accounts (Apple Search Ads, Meta, LinkedIn) + ads skill activated |
+ paid acquisition pilot ($5–15K/mo — see funding-stage-unlocks.md for canonical tiers) |
| Seed deployment | + designer (potentially fractional) | + analytics expansion (Mixpanel / Amplitude if needed) | + paid scaling ($20–50K/mo) + first launches (PH, GA) |
| Series A | + performance marketing lead + content lead | + dedicated tooling spend ($2–5K/mo software) + sponsored event budget | + paid scaling ($50–150K/mo) + international consideration + B2B vertical expansion |
| Series B+ | Full-stack marketing org (10+ people) | + agency partnerships + PR firm | + brand campaigns + acquisitions + sponsorships at category level |
Section 11 of the plan must include at least one concrete operational example that proves the stack thesis. The example should be:
- A specific event (not abstract claim)
- From this client's actual history if possible (most credible)
- Tied to a non-technical person executing via the stack (proves it works without dedicated engineering)
Examples from real engagements:
- "On the kickoff call, Alex drafted a working Customer.io abandoned-cart flow live, using Customer.io's Claude MCP. Validated that a non-technical founder can ship lifecycle work using the skill pattern independently."
- "In two weeks, the team scaled from 0 to 14 ranking keywords using programmatic-seo against the Ahrefs API + GitHub MCP — no dedicated SEO hire required."
- "The first email campaign generated a 24% reply rate after cold-email skill + GA4 MCP + Stripe MCP gave the team a verified target list of users with high LTV but no recent activity."
If the client has no such moment in their history yet, frame the example as the first move — "Here's the demonstration the team will run in week one to validate the stack:"
For clients without MCP connections set up, frame Section 11 differently:
- List the skills that DO apply with current tooling
- Name which MCPs would unlock which sections of the plan
- Treat MCP setup as a Q1 priority alongside the bedrock fixes
A plan can't claim the agentic-stack thesis if the stack isn't wired. Be honest about state.
The canonical template for every marketing plan generated by this skill. Each section has a purpose, a structure, and inline prompts for what to draft.
The Quietude plan (see references/example-quietude.md) is the canonical reference implementation.
# {Client} — Marketing Plan v1
**Prepared by:** {Author / fCMO name}
**For:** {Founders / leadership team}
**Date:** YYYY-MM-DD
**Status:** Draft v1 — for team review
Purpose: Lift-and-share. A founder should be able to paste this into a board update or investor email without editing.
Length: 400–700 words. Tight.
Structure:
1. One-sentence frame. What does this plan optimize for? Not "more revenue" — something specific to this client at this stage.
2. Three big bets, ranked by leverage. Each is a paragraph. Bet = a high-conviction thesis about where the team should focus capital and attention.
3. What twelve months looks like, plausibly. Bullet list. The plausible outcome state at end of plan horizon. Investor-readable.
4. 90-day priorities. Numbered list. The six (give or take) moves that ship in the first quarter.
Voice notes:
- Match the client's voice
- Direct, founder-readable, no marketing-speak
- Use names and numbers (specific channels, specific metrics) — not abstractions
- Tradeoffs named explicitly when they matter
Purpose: Distill positioning, ICP, business-model logic, and brand voice into a single page that any team member or new hire can read to orient.
Length: 800–1500 words.
Structure:
Pulled from positioning doc / seed deck / founder language.
Is the company creating a new category, redefining an existing one, or competing in a defined category? Name it. State the category-defining frame in 2–3 sentences. Reference the source (founder's words, ICP doc, etc.).
Demographics / firmographics + stated problem vs. real problem + what they're actually buying. Tight, 4–6 bullets.
How does the company make money? What's the customer-acquisition unit economics theory? What's the compounding channel thesis (if any)? Pulled from seed deck / financial model / founder narrative.
If the client has documented voice rules, list them. YES / NO vocabulary. CTA rules. Tone. Core method (initiatory, explanatory, narrative, etc.). Every other section of the plan must respect these.
Voice notes:
- This section is the most "lift from existing materials" — don't invent positioning. Surface what's there.
- If positioning is unclear or contradicted across materials, flag it in Section 13's open decisions.
Purpose: Anchor the plan in reality. What's the team, budget, in-flight work, and stuck work today?
Length: 1000–2000 words.
Structure:
Table of every person with marketing surface area:
| Person | Role | Marketing surface area |
|---|---|---|
Be honest about gaps. If there's no dedicated marketing hire yet, name when one becomes necessary and what role (see references/team-and-agency-model.md — first hire should be π-shaped strategist titled Manager or Lead, not VP/CMO).
references/budget-planning.md for the calculation)State the funding-stage tier this maps to (see references/funding-stage-unlocks.md). Implication: what 90-day plan must produce without lever pulls that require future budget.
Name the current phase: $0–10K ARR / $10K–100K / $100K–1M / $1M–$10M / $10M+. Each phase has its own binding constraint and dominant growth pattern (see references/growth-patterns.md). Section 10 sequences the move into the next phase.
Table:
| Asset | Status | Marketing leverage |
|---|---|---|
This is where past launches, PR moments, content pillars, certifications, notable users get acknowledged. Critical: don't write a plan that ignores work the team is proud of.
Table:
| Item | Status | Blocker |
|---|---|---|
Be honest about blockers. Where the blocker is "no time" or "no decision," that goes to Section 13's open decisions.
Table:
| Issue | Cost of inaction | Action |
|---|---|---|
Stuck things are the most leverage-positive places to focus the first weeks of the 90-day plan.
17-section scored snapshot using the embedded current-state rubric. See references/current-state-rubric.md for the full rubric and scoring guides.
If a prior scored audit exists, paste those scores in. Otherwise score from available materials and note "scored from materials" under the heading.
| # | Section | Score | Note |
|---|---|---|---|
| 1 | Positioning | 0–5 | |
| 2 | Customer research | 0–5 | |
| ... | ... | ... | ... |
| 17 | Internationalization | 0–5 |
Total: X / 85 (Y%). Note the shape of strength and weakness — that shape is the gap the rest of the plan closes.
Voice notes:
- Honest > polished. If the client's metrics are bad, name them. Founders read past sugar-coating.
Purpose: Answer "how do strangers become aware of us?" Map every channel: current state, planned moves, skipped (with reason).
Length: 1000–1800 words.
Structure:
Brief. What's working today, what's not, what the data shows about channel mix.
Numbered "Moves." Each move is a paragraph (3–6 sentences) describing the channel, the thesis, and the specific work. Common moves:
seo/plan.md). Otherwise: keyword research, pillar/spoke structure, content cadence.Week-by-week breakdown of the ships in the first quarter.
Quarter-by-quarter outcome state (Q1 / Q2 / Q3 / Q4).
seo-audit, ai-seo, ads, social, competitors, etc.)Purpose: Answer "once someone tries us, do they have an experience that converts?"
Length: 800–1500 words.
Structure: Same as Acquisition (Current state / The plan / 90-day / 12-month / Skills + tools).
Common moves:
- Bedrock fixes (broken signup, broken onboarding gates, etc.)
- Onboarding tests / rebuild (often the most leveraged move at this stage)
- App Store listing rewrite (cross-references to Acquisition)
- Lifecycle Flow ship order (when to ship onboarding emails vs. hold for product stability)
- Paywall + pricing review (often Activation × Revenue)
onboarding, signup, paywalls, copywriting, marketing-website-design, ab-testing, etc.
Purpose: Answer "once someone converts, do they stay and deepen?"
Length: 800–1500 words.
Structure: Same as above.
Common moves:
- Lifecycle email flows (post-purchase, lapsed user, win-back)
- Subscription / preference centers
- Churn reconciliation (often metric definitions don't match across surfaces)
- Hardware → software activation paths (for hybrid businesses)
- Annual plan default tests (cross-references to Revenue)
emails, churn-prevention, copywriting, paywalls, etc.
Purpose: Answer "do retained users bring more users, and at what cost?"
Length: 500–1200 words.
Structure: Same as above.
Common moves:
- Ambassador / affiliate program launch (if inbound interest exists, lead with it)
- Share-after-value moments built into product
- Founder amplification (founder as referrer-zero)
- Long-game expert / Guides / certified-host network
- Gifting flows (for consumer / hardware)
referrals, social, emails (for ambassador lifecycle), copywriting, etc.
Purpose: Answer "what do we charge, who pays, and how does it compound?"
Length: 500–1200 words.
Structure: Same as above.
Common moves:
- Pricing audit (what's actually charged today vs. listed?)
- Annual plan default tests
- Hardware → software bundling formalization (for hybrid businesses)
- Storefront / commerce page optimization
- B2B case studies + sales material
- Long-term value pools (data licensing, enterprise expansion) — flagged not executed in 12-month plan
Required table:
| Metric | Value | Note |
|---|---|---|
| ARPC (avg monthly revenue per customer) | $X | Pulled from Stripe / billing |
| Blended CAC | $X | Includes all marketing costs, not just paid |
| Annual retention rate | X% | 1 − annual churn |
| LTV (rough) | $X | ARPC × 12 / annual churn |
| LTV / CAC | X | Health benchmark: > 3 |
These feed the budget math in Section 10. If any of these are unknown, flag in Section 13 as top open decision.
pricing, paywalls, sales-enablement, revops, ab-testing, etc.
Purpose: The tactical execution layer. Every move ships within a named week, with an owner.
Length: Tables, not prose. Should fit on one printed page if possible.
Structure: Four 2–3-week sprints:
Highest-confidence, lowest-cost changes. Removing things that are broken.
| Move | Stage | Owner |
|---|---|---|
Pillar/foundational work. Domain consolidation. First content. First flows shipping. First tests live.
Compounding work begins. Content cadence. Repeat tests. Channel scaling.
Second-order moves. Layered tactics. 90-day review prep.
Purpose: Quarterly milestones with explicit funding-stage capability unlocks named, anchored against a defensible growth pattern.
Length: Four sub-sections, one per quarter. ~250–400 words each. Plus a short framing paragraph at the top naming the budget method and growth pattern.
State explicitly:
- Budget method used. Method 1 (Revenue-Based 5–40% of ARR) or Method 2 (Goal-Based formula). See references/budget-planning.md. Show the math.
- Annual budget total + the experimental buffer (+10–20%).
- Resulting end-of-year ARR goal. Honest forecast, not a guarantee — see the forecasting reality check in references/measurement-framework.md.
- Growth pattern expected. Linear (predictable $X MRR added per month), step-function (plateau between deliberate jumps), or layered S-curves. For VC-backed Series A+, anchor against 3-3-2-2-2 and show whether the plan matches it or explicitly chooses a different trajectory. See references/growth-patterns.md.
Funding state: {tier} per funding-stage-unlocks.md
Focus: One-sentence focus theme for the quarter.
Outcomes by end of Q{N}:
- Bulleted outcome list (5–8 items)
KPI targets: 3–5 specific numerical targets.
Channel/Product/Market S-curve position: Which curves are growing, which are plateauing, which is the next one being staged for this quarter (see growth-patterns.md — layering principle).
Purpose: The fCMO differentiator. Show how a small team + agentic tooling executes the plan without hiring at every channel.
Length: Tables + brief explanation.
Structure:
1–2 paragraphs explaining the principle: small team + marketing-skills library + MCP integrations = output of a larger team.
| Stage | Primary skills | Supporting skills |
|---|---|---|
| Acquisition | (list) | (list) |
| Activation | (list) | (list) |
| Retention | (list) | (list) |
| Referral | (list) | (list) |
| Revenue | (list) | (list) |
| Cross-cutting | (list) | (list) |
| Stage | Existing connections | fCMO tooling layer |
|---|---|---|
Pick one operational moment that proves the stack works (e.g., "Customer.io MCP let the non-technical founder draft a flow live on the kickoff call"). Anchor the abstract claim in a specific event.
| Stage | Headcount | Tooling | Channels live |
|---|---|---|---|
| (current) | (list) | (list) | (list) |
| (next round) | (delta) | (delta) | (delta) |
| ... | ... | ... | ... |
Apply the principle from references/team-and-agency-model.md: strategy in-house, execution often outsourced.
| Function | Owned by (internal strategic role) | Executed by (IC / contractor / agency) |
|---|---|---|
| Growth marketing (demand engine) | ||
| Product marketing (story engine) | ||
| Content marketing (trust engine) |
If the team is missing a strategic owner for one of these functions, the first 90-day move (Section 9) should be the hire — Manager or Lead title, π-shaped if possible, not VP/CMO.
If execution capacity is the gap, name the contractor or small niche agency in the right cell rather than the team's existing IC.
Pull from references/funding-stage-unlocks.md.
Purpose: Cross-reference all 139 ideas from the marketing-ideas skill against AARRR stages, with client-specific status.
Length: Long — tables can easily total 150+ rows.
Structure:
Explain the cross-reference: Sections 4–8 prescribe what's being done. This section maps what's possible.
By status (Now / Q2 / Q3+ / Q4+ / Skip), tables of relevant marketing-ideas by number.
| # | Idea | Client note |
|---|---|---|
Use references/idea-cross-reference.md as the source-of-truth mapping. Apply client-specific filters during draft (brand voice rules out some; funding stage shifts timing of others).
Purpose: Operational close. Define how the plan gets measured, who owns what, what's still TBD, and where to find the deeper docs.
Structure:
North star (proposed): One metric that captures the business-model thesis. For Quietude it was blended-LTV-to-blended-CAC; for a B2B SaaS it might be NRR × NPS; for a marketplace, take-rate × monthly transacting users. Make it specific to the company.
Leading indicators by AARRR stage: Table:
| Stage | Leading indicators |
|---|---|
| Acquisition | ... |
| Activation | ... |
| Retention | ... |
| Referral | ... |
| Revenue | ... |
Review cadence:
- Weekly: who syncs with whom, on what
- Monthly: who reviews what
- Quarterly: plan recalibration trigger
| Domain | Responsible | Accountable | Consulted | Informed |
|---|---|---|---|---|
Common domains: strategic plan, brand voice, app/product implementation, lifecycle, SEO content, App Store, founder-led social, events, ambassadors, B2B sales, pricing, investor narrative, future hires.
Ranked by impact. Each is: name + impact + what's blocked.
Published in this repo / shared with team: {relative paths to docs in the shared repo}
Founder-authored strategic context (internal knowledge base): {names of docs the team has access to outside the plan repo}
fCMO working drafts (not yet published): {names + how to access from author}
*{Client} Marketing Plan v1. Prepared by {Author}, {Date}. For team review and discussion.*
some-skill) and a tool (Customer.io MCP / Stripe MCP / Ahrefs / etc.).The marketing operations stack (Section 11 of every plan) describes what gets done. This doc describes who does it — the operating principle, the org shape, the first hire, the agency model, and how it evolves as the company scales.
Excerpted and adapted from Founding Marketing by Corey Haines.
Strategy lives in-house. Execution can — and often should — be outsourced.
Two failure modes are common when founders ignore this:
The traditional advice — "hire full-time for competitive advantages, only use agencies for commoditized work" — made sense when marketing moved slowly and talent stayed for decades. That world is gone. Full-time hires take months to ramp and years to develop deep expertise. The best agencies and contractors deliver results immediately, with cross-industry pattern recognition you couldn't build in-house affordably.
The strategic heart of the marketing operation. Specifically:
These are not delegatable. An external partner can sharpen the articulation, but the underlying conviction must come from the team.
External expertise shines in specific contexts:
The trick is defining what's being outsourced. Vague briefs ("help us with marketing") produce vague results. Specific briefs ("ship 20 RSAs across 4 ad groups by month-end with the CTR benchmarks in the brief") produce shippable work.
Every marketing engine has three primary functions. Whether you have a team of 1 or 50, the functions exist — even if one person owns several.
Drives quantitative outcomes: leads, signups, paid traffic, conversion rate, CAC.
Drives positioning quality, message-market fit, launch impact, sales enablement.
Drives organic traffic, brand affinity, thought leadership, trust signals.
These three functions are interconnected. Growth without story is performance with no positioning. Story without distribution is a great pitch nobody hears. Trust without demand capture is brand affinity that doesn't compound into revenue.
The most consequential decision in building the marketing engine isn't about channels or technology — it's who leads.
The first marketing hire should be a strategist, not a tactician. Counterintuitive when there's a mountain of tactical work to ship. Essential for sustainable growth.
The standard advice is to hire a T-shaped marketer: broad knowledge across many areas, deep in one. That's fine for a tactical IC role.
For the first strategic hire, look for π-shaped: two deep skill sets, plus broad surface-level competency across the rest. The two depths create unique leverage through their combination.
Product Marketing + Growth Marketing
- Owns positioning and drives distribution
- Crafts the message and gets it to market
- No gap between planning and doing
- Best for technical products or complex sales
Product Marketing + Content Marketing
- Translates product into compelling stories
- Owns voice and positioning together
- Creates content that compounds
- Best for thought-leadership or education-driven markets
Growth Marketing + Content Marketing
- Builds the demand engine and the content that fuels it
- Closes the loop between SEO/social distribution and conversion
- Best for content-led growth motions
The wrong shape for a first hire: deep paid media specialist alone, deep SEO specialist alone, deep designer alone. These are tactical depths; they need a strategic owner above them.
A common mistake: making the first marketing hire a "CMO" or "VP." Creates problems when you actually need to scale the org, because there's no headroom above them.
The right progression:
| Title | Scope |
|---|---|
| Manager | Individual contributor, co-manages freelancers |
| Lead | Senior IC, manages freelancers/agencies |
| Director / Head | Manages ICs and vendors |
| VP | Manages Directors |
| Chief (CMO) | Manages VPs |
The first hire is almost always Marketing Manager or Marketing Lead. They should be able to:
Both strategic and hands-on. Comfortable setting direction and rolling up sleeves. Most importantly: a builder — creates processes, frameworks, and systems that scale beyond their individual capacity.
Think of the marketing organization as an engine. Each part has a specific role; the magic is in how they work together.
What powers everything else. Without good fuel, even the best engine sputters.
Quality of the fuel determines efficiency. Poor positioning, weak stories, inconsistent branding waste energy regardless of execution.
Where strategy turns into action.
Needs to be well-maintained and properly tuned. Right processes, tools, people in place to execute consistently.
How you know if you're heading in the right direction.
Without good instrumentation, flying blind. Need both leading and lagging indicators.
Not all agencies are created equal. Ranked from most appropriate for early-stage to least:
For most pre-Series-A companies, this is the right answer for nearly all outsourced work.
The difference between a successful and failed agency relationship usually comes down to structure and management.
The best agency relationships feel like partnership: they understand the business, care about success, bring expertise you couldn't build in-house affordably. Takes work on both sides — clear expectations, open communication, mutual respect.
The right ratio of internal to external resources isn't static. It evolves with stage, needs, and market conditions.
Mode: discovery and iteration
Mode: optimization
Mode: coordination
The metaphor: a symphony orchestra. The internal team conducts. External partners play their instruments with expertise.
| Section | What to include |
|---|---|
| 3 (Current state) | Team composition — every person who touches marketing, what they own. Identify where the team is π-shaped vs. T-shaped vs. tactical-only. Flag gaps. |
| 9 (90-day roadmap) | If the team is missing the strategic owner, the first move is the first marketing hire (Lead or Manager). If the team has strategy but no execution capacity, the first move is the first contractor or specialized agency. |
| 10 (12-month outlook) | Map team evolution against funding-stage capability unlocks (see funding-stage-unlocks.md). When does the second hire come in? When does an agency relationship deepen? |
| 11 (Marketing operations stack) | RACI is more honest with this model: "owned by" = internal strategic role; "executed by" = internal IC, contractor, or agency. The plan should make it explicit who does what. |
| 13 (Open decisions) | If "first marketing hire" is open, name it as a top-three decision. If "in-house vs agency" for a specific function is open, frame the tradeoff using this doc's heuristics. |
When the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when the user mentions 'psychology,' 'mental models,' 'cognitive bias,' 'persuasion,' 'behavioral science
View source ↗You are an expert in applying psychological principles and mental models to marketing. Your goal is to help users understand why people buy, how to influence behavior ethically, and how to make better marketing decisions.
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 applying mental models. Use that context to tailor recommendations to the specific product and audience.
Mental models are thinking tools that help you make better decisions, understand customer behavior, and create more effective marketing. When helping users:
These models sharpen your strategy and help you solve the right problems.
Break problems down to basic truths and build solutions from there. Instead of copying competitors, ask "why" repeatedly to find root causes. Use the 5 Whys technique to tunnel down to what really matters.
Marketing application: Don't assume you need content marketing because competitors do. Ask why you need it, what problem it solves, and whether there's a better solution.
People don't buy products—they "hire" them to get a job done. Focus on the outcome customers want, not features.
Marketing application: A drill buyer doesn't want a drill—they want a hole. Frame your product around the job it accomplishes, not its specifications.
Know what you're good at and stay within it. Venture outside only with proper learning or expert help.
Marketing application: Don't chase every channel. Double down where you have genuine expertise and competitive advantage.
Instead of asking "How do I succeed?", ask "What would guarantee failure?" Then avoid those things.
Marketing application: List everything that would make your campaign fail—confusing messaging, wrong audience, slow landing page—then systematically prevent each.
The simplest explanation is usually correct. Avoid overcomplicating strategies or attributing results to complex causes when simple ones suffice.
Marketing application: If conversions dropped, check the obvious first (broken form, page speed) before assuming complex attribution issues.
Roughly 80% of results come from 20% of efforts. Identify and focus on the vital few.
Marketing application: Find the 20% of channels, customers, or content driving 80% of results. Cut or reduce the rest.
A local optimum is the best solution nearby, but a global optimum is the best overall. Don't get stuck optimizing the wrong thing.
Marketing application: Optimizing email subject lines (local) won't help if email isn't the right channel (global). Zoom out before zooming in.
Every system has one bottleneck limiting throughput. Find and fix that constraint before optimizing elsewhere.
Marketing application: If your funnel converts well but traffic is low, more conversion optimization won't help. Fix the traffic bottleneck first.
Every choice has a cost—what you give up by not choosing alternatives. Consider what you're saying no to.
Marketing application: Time spent on a low-ROI channel is time not spent on high-ROI activities. Always compare against alternatives.
After a point, additional investment yields progressively smaller gains.
Marketing application: The 10th blog post won't have the same impact as the first. Know when to diversify rather than double down.
Consider not just immediate effects, but the effects of those effects.
Marketing application: A flash sale boosts revenue (first order) but may train customers to wait for discounts (second order).
Models and data represent reality but aren't reality itself. Don't confuse your analytics dashboard with actual customer experience.
Marketing application: Your customer persona is a useful model, but real customers are more complex. Stay in touch with actual users.
Think in probabilities, not certainties. Estimate likelihoods and plan for multiple outcomes.
Marketing application: Don't bet everything on one campaign. Spread risk and plan for scenarios where your primary strategy underperforms.
Combine extreme safety with small high-risk/high-reward bets. Avoid the mediocre middle.
Marketing application: Put 80% of budget into proven channels, 20% into experimental bets. Avoid moderate-risk, moderate-reward middle.
These models explain how customers think, decide, and behave.
People attribute others' behavior to character, not circumstances. "They didn't buy because they're not serious" vs. "The checkout was confusing."
Marketing application: When customers don't convert, examine your process before blaming them. The problem is usually situational, not personal.
People prefer things they've seen before. Familiarity breeds liking.
Marketing application: Consistent brand presence builds preference over time. Repetition across channels creates comfort and trust.
People judge likelihood by how easily examples come to mind. Recent or vivid events seem more common.
Marketing application: Case studies and testimonials make success feel more achievable. Make positive outcomes easy to imagine.
People seek information confirming existing beliefs and ignore contradictory evidence.
Marketing application: Understand what your audience already believes and align messaging accordingly. Fighting beliefs head-on rarely works.
The longer something has survived, the longer it's likely to continue. Old ideas often outlast new ones.
Marketing application: Proven marketing principles (clear value props, social proof) outlast trendy tactics. Don't abandon fundamentals for fads.
People want things because others want them. Desire is socially contagious.
Marketing application: Show that desirable people want your product. Waitlists, exclusivity, and social proof trigger mimetic desire.
People continue investing in something because of past investment, even when it's no longer rational.
Marketing application: Know when to kill underperforming campaigns. Past spend shouldn't justify future spend if results aren't there.
People value things more once they own them.
Marketing application: Free trials, samples, and freemium models let customers "own" the product, making them reluctant to give it up.
People value things more when they've put effort into creating them.
Marketing application: Let customers customize, configure, or build something. Their investment increases perceived value and commitment.
Free isn't just a low price—it's psychologically different. "Free" triggers irrational preference.
Marketing application: Free tiers, free trials, and free shipping have disproportionate appeal. The jump from $1 to $0 is bigger than $2 to $1.
People strongly prefer immediate rewards over future ones, even when waiting is more rational.
Marketing application: Emphasize immediate benefits ("Start saving time today") over future ones ("You'll see ROI in 6 months").
People prefer the current state of affairs. Change requires effort and feels risky.
Marketing application: Reduce friction to switch. Make the transition feel safe and easy. "Import your data in one click."
People tend to accept pre-selected options. Defaults are powerful.
Marketing application: Pre-select the plan you want customers to choose. Opt-out beats opt-in for subscriptions (ethically applied).
Too many options overwhelm and paralyze. Fewer choices often lead to more decisions.
Marketing application: Limit options. Three pricing tiers beat seven. Recommend a single "best for most" option.
People accelerate effort as they approach a goal. Progress visualization motivates action.
Marketing application: Show progress bars, completion percentages, and "almost there" messaging to drive completion.
People judge experiences by the peak (best or worst moment) and the end, not the average.
Marketing application: Design memorable peaks (surprise upgrades, delightful moments) and strong endings (thank you pages, follow-up emails).
Unfinished tasks occupy the mind more than completed ones. Open loops create tension.
Marketing application: "You're 80% done" creates pull to finish. Incomplete profiles, abandoned carts, and cliffhangers leverage this.
Competent people become more likable when they show a small flaw. Perfection is less relatable.
Marketing application: Admitting a weakness ("We're not the cheapest, but...") can increase trust and differentiation.
Once you know something, you can't imagine not knowing it. Experts struggle to explain simply.
Marketing application: Your product seems obvious to you but confusing to newcomers. Test copy with people unfamiliar with your space.
People treat money differently based on its source or intended use, even though money is fungible.
Marketing application: Frame costs in favorable mental accounts. "$3/day" feels different than "$90/month" even though it's the same.
People avoid actions that might cause regret, even if the expected outcome is positive.
Marketing application: Address regret directly. Money-back guarantees, free trials, and "no commitment" messaging reduce regret fear.
People follow what others are doing. Popularity signals quality and safety.
Marketing application: Show customer counts, testimonials, logos, reviews, and "trending" indicators. Numbers create confidence.
These models help you ethically influence customer decisions.
People feel obligated to return favors. Give first, and people want to give back.
Marketing application: Free content, free tools, and generous free tiers create reciprocal obligation. Give value before asking for anything.
Once people commit to something, they want to stay consistent with that commitment.
Marketing application: Get small commitments first (email signup, free trial). People who've taken one step are more likely to take the next.
People defer to experts and authority figures. Credentials and expertise create trust.
Marketing application: Feature expert endorsements, certifications, "featured in" logos, and thought leadership content.
People say yes to those they like and those similar to themselves.
Marketing application: Use relatable spokespeople, founder stories, and community language. "Built by marketers for marketers" signals similarity.
Shared identity drives influence. "One of us" is powerful.
Marketing application: Position your brand as part of the customer's tribe. Use insider language and shared values.
Limited availability increases perceived value. Scarcity signals desirability.
Marketing application: Limited-time offers, low-stock warnings, and exclusive access create urgency. Only use when genuine.
Start with a small request, then escalate. Compliance with small requests leads to compliance with larger ones.
Marketing application: Free trial → paid plan → annual plan → enterprise. Each step builds on the last.
Start with an unreasonably large request, then retreat to what you actually want. The contrast makes the second request seem reasonable.
Marketing application: Show enterprise pricing first, then reveal the affordable starter plan. The contrast makes it feel like a deal.
Losses feel roughly twice as painful as equivalent gains feel good. People will work harder to avoid losing than to gain.
Marketing application: Frame in terms of what they'll lose by not acting. "Don't miss out" beats "You could gain."
The first number people see heavily influences subsequent judgments.
Marketing application: Show the higher price first (original price, competitor price, enterprise tier) to anchor expectations.
Adding a third, inferior option makes one of the original two look better.
Marketing application: A "decoy" pricing tier that's clearly worse value makes your preferred tier look like the obvious choice.
How something is presented changes how it's perceived. Same facts, different frames.
Marketing application: "90% success rate" vs. "10% failure rate" are identical but feel different. Frame positively.
Things seem different depending on what they're compared to.
Marketing application: Show the "before" state clearly. The contrast with your "after" makes improvements vivid.
These models specifically address how people perceive and respond to prices.
Prices ending in 9 seem significantly lower than the next round number. $99 feels much cheaper than $100.
Marketing application: Use .99 or .95 endings for value-focused products. The left digit dominates perception.
Round numbers feel premium and are easier to process. $100 signals quality; $99 signals value.
Marketing application: Use round prices for premium products ($500/month), charm prices for value products ($497/month).
For prices under $100, percentage discounts seem larger ("20% off"). For prices over $100, absolute discounts seem larger ("$50 off").
Marketing application: $80 product: "20% off" beats "$16 off." $500 product: "$100 off" beats "20% off."
People judge prices relative to options presented. A middle tier seems reasonable between cheap and expensive.
Marketing application: Three tiers where the middle is your target. The expensive tier makes it look reasonable; the cheap tier provides an anchor.
Framing the same price differently changes perception.
Marketing application: "$1/day" feels cheaper than "$30/month." "Less than your morning coffee" reframes the expense.
These models help you design effective marketing systems.
Decision time increases with the number and complexity of choices. More options = slower decisions = more abandonment.
Marketing application: Simplify choices. One clear CTA beats three. Fewer form fields beat more.
Attention → Interest → Desire → Action. The classic customer journey model.
Marketing application: Structure pages and campaigns to move through each stage. Capture attention before building desire.
Prospects need roughly 7 touchpoints before converting. One ad rarely converts; sustained presence does.
Marketing application: Build multi-touch campaigns across channels. Retargeting, email sequences, and consistent presence compound.
Small changes in how choices are presented significantly influence decisions.
Marketing application: Default selections, strategic ordering, and friction reduction guide behavior without restricting choice.
Behavior = Motivation × Ability × Prompt. All three must be present for action.
Marketing application: High motivation but hard to do = won't happen. Easy to do but no prompt = won't happen. Design for all three.
Make desired behaviors: Easy, Attractive, Social, Timely.
Marketing application: Reduce friction (easy), make it appealing (attractive), show others doing it (social), ask at the right moment (timely).
Behavior requires: Capability, Opportunity, Motivation.
Marketing application: Can they do it (capability)? Is the path clear (opportunity)? Do they want to (motivation)? Address all three.
The initial energy required to start something. High activation energy prevents action even if the task is easy overall.
Marketing application: Reduce starting friction. Pre-fill forms, offer templates, show quick wins. Make the first step trivially easy.
One metric that best captures the value you deliver to customers. Focus creates alignment.
Marketing application: Identify your North Star (active users, completed projects, revenue per customer) and align all efforts toward it.
When incentives backfire and produce the opposite of intended results.
Marketing application: Test incentive structures. A referral bonus might attract low-quality referrals gaming the system.
These models explain how marketing compounds and scales.
Output becomes input, creating cycles. Positive loops accelerate growth; negative loops create decline.
Marketing application: Build virtuous cycles: more users → more content → better SEO → more users. Identify and strengthen positive loops.
Small, consistent gains accumulate into large results over time. Early gains matter most.
Marketing application: Consistent content, SEO, and brand building compound. Start early; benefits accumulate exponentially.
A product becomes more valuable as more people use it.
Marketing application: Design features that improve with more users: shared workspaces, integrations, marketplaces, communities.
Sustained effort creates momentum that eventually maintains itself. Hard to start, easy to maintain.
Marketing application: Content → traffic → leads → customers → case studies → more content. Each element powers the next.
The price (time, money, effort, data) of changing to a competitor. High switching costs create retention.
Marketing application: Increase switching costs ethically: integrations, data accumulation, workflow customization, team adoption.
Balance trying new things (exploration) with optimizing what works (exploitation).
Marketing application: Don't abandon working channels for shiny new ones, but allocate some budget to experiments.
The threshold after which growth becomes self-sustaining.
Marketing application: Focus resources on reaching critical mass in one segment before expanding. Depth before breadth.
Focusing on successes while ignoring failures that aren't visible.
Marketing application: Study failed campaigns, not just successful ones. The viral hit you're copying had 99 failures you didn't see.
When facing a marketing challenge, consider:
| Challenge | Relevant Models |
|---|---|
| Low conversions | Hick's Law, Activation Energy, BJ Fogg, Friction |
| Price objections | Anchoring, Framing, Mental Accounting, Loss Aversion |
| Building trust | Authority, Social Proof, Reciprocity, Pratfall Effect |
| Increasing urgency | Scarcity, Loss Aversion, Zeigarnik Effect |
| Retention/churn | Endowment Effect, Switching Costs, Status-Quo Bias |
| Growth stalling | Theory of Constraints, Local vs Global Optima, Compounding |
| Decision paralysis | Paradox of Choice, Default Effect, Nudge Theory |
| Onboarding | Goal-Gradient, IKEA Effect, Commitment & Consistency |
When the user wants to create or update their product marketing context document. Also use when the user mentions 'product context,' 'marketing context,' 'set up context,' 'positioning,' 'who is my target audience,' 'des
View source ↗You help users create and maintain a product marketing context document. This captures foundational positioning and messaging information that other marketing skills reference, so users don't repeat themselves.
The document is stored at .agents/product-marketing.md.
First, check if .agents/product-marketing.md already exists. Also check .claude/product-marketing.md and the legacy filename product-marketing-context.md (in either .agents/ or .claude/) for older setups — if found anywhere other than .agents/product-marketing.md, offer to move it to the canonical location.
If it exists:
- Read it and summarize what's captured
- Ask which sections they want to update
- Only gather info for those sections
If it doesn't exist, offer two options:
Auto-draft from codebase (recommended): You'll study the repo—README, landing pages, marketing copy, package.json, etc.—and draft a V1 of the context document. The user then reviews, corrects, and fills gaps. This is faster than starting from scratch.
Start from scratch: Walk through each section conversationally, gathering info one section at a time.
Most users prefer option 1. After presenting the draft, ask: "What needs correcting? What's missing?"
If auto-drafting:
1. Read the codebase: README, landing pages, marketing copy, about pages, meta descriptions, package.json, any existing docs
2. Draft all sections based on what you find
3. Present the draft and ask what needs correcting or is missing
4. Iterate until the user is satisfied
If starting from scratch:
Walk through each section below conversationally, one at a time. Don't dump all questions at once.
For each section:
1. Briefly explain what you're capturing
2. Ask relevant questions
3. Confirm accuracy
4. Move to the next
Push for verbatim customer language — exact phrases are more valuable than polished descriptions because they reflect how customers actually think and speak, which makes copy more resonant.
If multiple stakeholders are involved in buying, capture for each:
- User, Champion, Decision Maker, Financial Buyer, Technical Influencer
- What each cares about, their challenge, and the value you promise them
The JTBD Four Forces:
- Push: What frustrations drive them away from current solution
- Pull: What attracts them to you
- Habit: What keeps them stuck with current approach
- Anxiety: What worries them about switching
After gathering information, create .agents/product-marketing.md with this structure:
# Product Marketing Context
*Last updated: [date]*
## Product Overview
**One-liner:**
**What it does:**
**Product category:**
**Product type:**
**Business model:**
## Target Audience
**Target companies:**
**Decision-makers:**
**Primary use case:**
**Jobs to be done:**
-
**Use cases:**
-
## Personas
| Persona | Cares about | Challenge | Value we promise |
|---------|-------------|-----------|------------------|
| | | | |
## Problems & Pain Points
**Core problem:**
**Why alternatives fall short:**
-
**What it costs them:**
**Emotional tension:**
## Competitive Landscape
**Direct:** [Competitor] — falls short because...
**Secondary:** [Approach] — falls short because...
**Indirect:** [Alternative] — falls short because...
## Differentiation
**Key differentiators:**
-
**How we do it differently:**
**Why that's better:**
**Why customers choose us:**
## Objections
| Objection | Response |
|-----------|----------|
| | |
**Anti-persona:**
## Switching Dynamics
**Push:**
**Pull:**
**Habit:**
**Anxiety:**
## Customer Language
**How they describe the problem:**
- "[verbatim]"
**How they describe us:**
- "[verbatim]"
**Words to use:**
**Words to avoid:**
**Glossary:**
| Term | Meaning |
|------|---------|
| | |
## Brand Voice
**Tone:**
**Style:**
**Personality:**
## Proof Points
**Metrics:**
**Customers:**
**Testimonials:**
> "[quote]" — [who]
**Value themes:**
| Theme | Proof |
|-------|-------|
| | |
## Goals
**Business goal:**
**Conversion action:**
**Current metrics:**
.agents/product-marketing.md/product-marketing anytime to update it."When the user wants to research, profile, or analyze competitors from their URLs. Also use when the user mentions 'competitor profile,' 'competitor research,' 'competitor analysis,' 'profile this competitor,' 'analyze co
View source ↗You are an expert competitive intelligence analyst. Your goal is to take a list of competitor URLs and produce comprehensive, structured competitor profile documents by combining live site scraping with SEO and market data.
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.
Before profiling, confirm:
If the user provides URLs and context is available, proceed without asking.
Every claim in a profile should be traceable to a source — scraped page content, review data, or SEO metrics. Label inferences clearly.
All profiles follow the same template so they can be compared side by side. Consistency matters more than completeness on any single profile.
Profiles are snapshots. Always include the date generated. Flag anything that looks stale (e.g., "pricing page last updated 2023").
Don't exaggerate competitor weaknesses or downplay their strengths. Accurate profiles are useful profiles.
Before synthesizing the profile, persist all raw scrape, SEO, and review data to disk so it can be re-read, audited, or re-used later without re-running expensive API calls.
Directory layout (relative to project root):
competitor-profiles/
├── raw/
│ └── <competitor-slug>/
│ └── <YYYY-MM-DD>/
│ ├── scrapes/ # one .md file per scraped page (homepage.md, pricing.md, ...)
│ ├── seo/ # one .json file per DataForSEO call (backlinks-summary.json, ranked-keywords.json, ...)
│ └── reviews/ # one .md or .json file per review source (g2.md, capterra.md, ...)
├── <competitor-slug>.md # final synthesized profile
└── _summary.md # cross-competitor summary
Rules:
<competitor-slug> is lowercase, hyphenated (e.g. responsehub, safe-base)<YYYY-MM-DD> is the date the data was pulled — supports re-running and diffing snapshots over timescrapes/<page-name>.mdseo/<endpoint-name>.jsonreviews/<source>.md (cleaned text) or .json (raw)The synthesized profile (<competitor-slug>.md) should reference the raw data folder it was built from in its ## Raw Data Sources section.
For each competitor URL, scrape key pages to extract positioning, features, pricing, and messaging.
Use Firecrawl Map to discover the competitor's site structure and identify key pages:
firecrawl_map → competitor URL
From the map, identify and prioritize these page types:
- Homepage
- Pricing page
- Features / product pages
- About / company page
- Blog (top-level, for content strategy signals)
- Customers / case studies page
- Integrations page
- Changelog / what's new (if exists)
Use Firecrawl Scrape on each identified page:
firecrawl_scrape → each key page URL
Save each result to competitor-profiles/raw/<competitor-slug>/<YYYY-MM-DD>/scrapes/<page-name>.md before extracting fields.
Extract from each page:
| Page | What to Extract |
|---|---|
| Homepage | Headline, subheadline, value proposition, primary CTA, social proof claims, target audience signals |
| Pricing | Tiers, prices, feature breakdown per tier, billing options, free tier/trial details, enterprise pricing signals |
| Features | Feature categories, key capabilities, how they describe each feature, screenshots/demo signals |
| About | Founding story, team size, funding, mission statement, headquarters |
| Customers | Named customers, logos, industries served, case study themes |
| Integrations | Integration count, key integrations, categories |
| Changelog | Release velocity, recent focus areas, product direction signals |
Use Firecrawl Scrape or Firecrawl Search to find:
- G2 reviews page for the competitor
- Capterra reviews page
- Product Hunt launch page
- TrustRadius profile
Save each scraped review page to competitor-profiles/raw/<competitor-slug>/<YYYY-MM-DD>/reviews/<source>.md. Then extract: overall rating, review count, common praise themes, common complaint themes, and 3-5 representative quotes.
Use DataForSEO MCP tools to gather quantitative competitive intelligence. Save each raw response as JSON to competitor-profiles/raw/<competitor-slug>/<YYYY-MM-DD>/seo/<endpoint-name>.json before parsing it into the profile. For the full list of MCP tools used in this skill (Firecrawl + DataForSEO) and example calls, see references/tool-reference.md.
Use backlinks_summary to get:
- Domain rank / authority score
- Total backlinks
- Referring domains count
- Spam score
Use backlinks_referring_domains for:
- Top referring domains (quality signals)
- Link acquisition patterns
Use dataforseo_labs_google_ranked_keywords to get:
- Total organic keywords ranking
- Keywords in top 3, top 10, top 100
- Estimated organic traffic
Use dataforseo_labs_google_domain_rank_overview for:
- Domain-level organic metrics
- Estimated traffic value
- Top keywords by traffic
Use dataforseo_labs_google_keywords_for_site to discover:
- What keywords they target
- Content gaps vs. your site
Use dataforseo_labs_google_competitors_domain to find:
- Their closest organic competitors (may reveal competitors you haven't considered)
- Market overlap data
Use dataforseo_labs_google_relevant_pages to find:
- Their highest-traffic pages
- Content that drives the most organic value
Combine scraped content with SEO data to build the profile. Cross-reference claims (e.g., if they claim "10,000 customers" on site, check if their traffic/backlink profile supports that scale).
Generate one markdown file per competitor, saved to a competitor-profiles/ directory in the project root.
Filename: competitor-profiles/[competitor-name].md
For the full profile and summary templates: See references/templates.md
Each profile follows this structure:
# [Competitor Name] — Competitor Profile
**URL**: [website]
**Generated**: [date]
**Depth**: [quick scan / deep profile]
---
## At a Glance
| Metric | Value |
|--------|-------|
| Tagline | [from homepage] |
| Founded | [year] |
| Headquarters | [location] |
| Team size | [estimate] |
| Funding | [if known] |
| Domain rank | [from DataForSEO] |
| Est. organic traffic | [monthly] |
| Referring domains | [count] |
| Organic keywords | [count] |
---
## Positioning & Messaging
**Primary value proposition**: [headline + subheadline from homepage]
**Target audience**: [who they're speaking to, based on copy analysis]
**Positioning angle**: [how they position — e.g., "simplicity-first," "enterprise-grade," "all-in-one"]
**Key messaging themes**:
- [theme 1 — with source page]
- [theme 2]
- [theme 3]
---
## Product & Features
### Core capabilities
- [capability 1] — [brief description from their site]
- [capability 2]
- ...
### Notable differentiators
- [what they emphasize as unique]
### Integrations
- [count] integrations
- Key: [list top 5-10]
### Product direction signals
- [based on changelog / recent feature releases]
---
## Pricing
| Tier | Price | Key Inclusions |
|------|-------|---------------|
| [Free/Starter] | [price] | [what's included] |
| [Pro/Growth] | [price] | [what's included] |
| [Enterprise] | [price] | [what's included] |
**Billing**: [monthly/annual, discount for annual]
**Free trial**: [yes/no, duration]
**Notable**: [any pricing quirks — per-seat, usage-based, hidden costs]
---
## Customers & Social Proof
**Named customers**: [list notable logos]
**Industries**: [primary industries served]
**Case study themes**: [what outcomes they highlight]
**Review ratings**:
- G2: [rating] ([count] reviews)
- Capterra: [rating] ([count] reviews)
---
## SEO & Content Strategy
**Organic strength**:
- Estimated monthly organic traffic: [number]
- Organic keywords (top 10): [count]
- Organic traffic value: $[estimated]
**Top organic pages** (by estimated traffic):
1. [page URL] — [keyword] — [est. traffic]
2. [page URL] — [keyword] — [est. traffic]
3. [page URL] — [keyword] — [est. traffic]
**Content strategy signals**:
- Blog post frequency: [estimate]
- Primary content types: [guides, comparisons, templates, etc.]
- Content focus areas: [topics they invest in]
**Backlink profile**:
- Referring domains: [count]
- Top referring sites: [list 5]
- Link acquisition pattern: [growing/stable/declining]
---
## Strengths & Weaknesses
### Strengths
- [strength 1 — with evidence source]
- [strength 2]
- [strength 3]
### Weaknesses
- [weakness 1 — with evidence source]
- [weakness 2]
- [weakness 3]
---
## Competitive Implications for [Your Product]
**Where they're strong vs. us**: [areas where this competitor has an advantage]
**Where we're strong vs. them**: [areas where you have an advantage]
**Opportunities**: [gaps in their offering or positioning we can exploit]
**Threats**: [areas where they're improving or gaining ground]
---
## Raw Data Sources
- Homepage scraped: [date]
- Pricing page scraped: [date]
- SEO data pulled: [date]
- Review data pulled: [date, sources]
After profiling all competitors, generate a competitor-profiles/_summary.md that includes:
Default to quick scan unless the user requests deep profiling or specifies a small number of competitors (3 or fewer).
When profiling more than one competitor:
Profiles are snapshots. When updating:
## Change Log section at the bottomOnly ask if not answered by context or input:
Ready-to-use templates for competitor profile sections and the summary document.
Abbreviated profile for when speed matters more than depth.
# [Competitor Name] — Quick Profile
**URL**: [website]
**Generated**: [date]
## At a Glance
| Metric | Value |
|--------|-------|
| Tagline | [from homepage] |
| Target audience | [inferred from copy] |
| Pricing starts at | [lowest paid tier] |
| Free tier/trial | [yes/no + details] |
| Domain rank | [from DataForSEO] |
| Est. organic traffic | [monthly] |
| Organic keywords (top 10) | [count] |
| Referring domains | [count] |
## Positioning
**Headline**: "[exact homepage headline]"
**Subheadline**: "[exact subheadline]"
**Positioning angle**: [1-2 sentence summary of how they position]
## Pricing Summary
| Tier | Price | Notable Inclusions |
|------|-------|-------------------|
| [tier] | [price] | [key items] |
| [tier] | [price] | [key items] |
## Key Takeaway
[2-3 sentences: what makes this competitor notable, where they're strong, where they're weak]
Use after profiling all competitors to create a side-by-side view.
# Competitive Landscape Summary
**Generated**: [date]
**Your product**: [name]
**Competitors profiled**: [count]
## Side-by-Side Comparison
| Dimension | [Your Product] | [Competitor 1] | [Competitor 2] | [Competitor 3] |
|-----------|---------------|----------------|----------------|----------------|
| **Tagline** | [yours] | [theirs] | [theirs] | [theirs] |
| **Target audience** | [yours] | [theirs] | [theirs] | [theirs] |
| **Positioning** | [angle] | [angle] | [angle] | [angle] |
| **Starting price** | $[X]/mo | $[X]/mo | $[X]/mo | $[X]/mo |
| **Free tier** | [yes/no] | [yes/no] | [yes/no] | [yes/no] |
| **Domain rank** | [score] | [score] | [score] | [score] |
| **Est. organic traffic** | [number] | [number] | [number] | [number] |
| **Referring domains** | [count] | [count] | [count] | [count] |
| **G2 rating** | [score] | [score] | [score] | [score] |
| **Key strength** | [one-liner] | [one-liner] | [one-liner] | [one-liner] |
| **Key weakness** | [one-liner] | [one-liner] | [one-liner] | [one-liner] |
Visual representation of where competitors sit along two key dimensions. Choose the two axes most relevant to your market.
| Market Type | X-Axis | Y-Axis |
|---|---|---|
| SaaS tools | Simple → Complex | Cheap → Expensive |
| Developer tools | Low-code → Code-first | Individual → Team |
| B2B platforms | SMB-focused → Enterprise-focused | Point solution → Platform |
| Content tools | Template-driven → Custom | Self-serve → Managed |
## Positioning Map
**Axes**: [X-axis label] vs. [Y-axis label]
[Y-axis high label]
│
│
[Competitor A] │ [Competitor B]
│
───────────────────────┼───────────────────────
[X-axis low] │ [X-axis high]
│
[Your Product] │ [Competitor C]
│
[Y-axis low label]
### Interpretation
- [1-2 sentences about what the map reveals]
- [where the whitespace / opportunity is]
Per-competitor SWOT relative to your product.
## SWOT: [Competitor] vs. [Your Product]
### Strengths (theirs vs. ours)
- [Where they genuinely outperform us — be honest]
### Weaknesses (theirs vs. ours)
- [Where they fall short compared to us — with evidence]
### Opportunities (for us)
- [Gaps in their offering we can exploit]
- [Segments they're ignoring]
- [Messaging angles they're missing]
### Threats (from them)
- [Areas where they're improving fast]
- [Features they're building that overlap with us]
- [Market moves that could shift perception]
Append to the bottom of any profile when updating it.
---
## Change Log
| Date | What Changed | Source |
|------|-------------|--------|
| [date] | Pricing increased from $X to $Y | Pricing page re-scrape |
| [date] | Launched [feature] | Changelog scrape |
| [date] | Domain rank changed from X to Y | DataForSEO re-pull |
| [date] | Added [integration] | Integrations page re-scrape |
Quick reference for the Firecrawl and DataForSEO MCP tools used in competitor profiling.
Purpose: Discover all URLs on a competitor's site to identify key pages.
When to use: First step for every competitor — before scraping individual pages.
Key output: List of URLs with their page types/paths.
Tip: Look for paths containing /pricing, /features, /about, /customers, /integrations, /blog, /changelog.
Purpose: Extract content from a single page as clean markdown.
When to use: After mapping, scrape each key page individually.
Key output: Page content in markdown format — headlines, body text, structured data.
Tip: Scrape homepage first — it reveals positioning, audience, and social proof in one shot.
Purpose: Search the web for specific content about a competitor.
When to use: Finding review pages, press coverage, or competitor mentions not on their own site.
Example queries:
- "[Competitor Name]" site:g2.com
- "[Competitor Name]" review
- "[Competitor Name]" funding OR raised
Purpose: Crawl multiple pages from a site in one operation.
When to use: Deep profiles where you want to analyze many pages (e.g., all feature pages, all blog posts). More expensive — use selectively.
Tip: Set page limits to avoid crawling entire sites. Target specific URL patterns.
Purpose: Extract structured data from a page using a schema.
When to use: When you need specific data points in a consistent format (e.g., pricing tier details, feature lists).
Tip: Define a clear schema for what you want extracted — more reliable than parsing raw markdown.
Purpose: Get domain authority, total backlinks, referring domains, spam score.
Input: Target domain (e.g., competitor.com)
Key metrics: domain_rank, total_backlinks, referring_domains, backlinks_spam_score
Purpose: List top referring domains — shows where their link equity comes from.
Input: Target domain + limit
Key metrics: Per-domain: rank, backlinks, domain name
Purpose: Organic search overview — traffic, keywords, traffic value.
Input: Target domain
Key metrics: organic_count (keywords), organic_traffic (estimated monthly), organic_cost (traffic value in $)
Purpose: What keywords a domain ranks for, with positions.
Input: Target domain
Key metrics: Per-keyword: keyword, position, search_volume, url (ranking page)
Tip: Sort by traffic to find their highest-value keywords.
Purpose: Keywords relevant to a domain — broader than ranked keywords, includes opportunities.
Input: Target domain
Key metrics: keyword, search_volume, competition, cpc
Purpose: Find a domain's closest organic competitors by keyword overlap.
Input: Target domain
Key metrics: domain, avg_position, intersections (shared keywords), full_domain_rank
Tip: May reveal competitors the user hasn't considered.
Purpose: Find keywords where two domains both rank — shows direct competition.
Input: Two target domains
Key metrics: keyword, position for each domain, search_volume
Tip: Use this to compare the user's domain vs. each competitor.
Purpose: Find a domain's most important pages by organic traffic.
Input: Target domain
Key metrics: page, metrics (traffic, keywords per page)
Tip: Reveals their content strategy — which pages drive the most value.
Purpose: Detect the technology stack a domain uses.
Input: Target domain
Key metrics: Technologies grouped by category (CMS, analytics, marketing, payments, etc.)
Purpose: List individual backlinks to a domain.
Input: Target domain + limit
Key metrics: url_from, url_to, anchor, domain_from_rank, is_new
Purpose: Compare domain ranks across multiple domains at once.
Input: Array of target domains
Key metrics: domain_rank per domain
Tip: Use this for the summary comparison table.
1. firecrawl_map → get site URLs
2. In parallel:
a. firecrawl_scrape → homepage
b. firecrawl_scrape → pricing page
c. dataforseo_labs_google_domain_rank_overview → organic metrics
d. backlinks_summary → domain authority
3. Synthesize into abbreviated profile
1. firecrawl_map → get site URLs
2. In parallel (batch 1 — scraping):
a. firecrawl_scrape → homepage
b. firecrawl_scrape → pricing page
c. firecrawl_scrape → features page(s)
d. firecrawl_scrape → about page
e. firecrawl_scrape → customers/case studies page
f. firecrawl_scrape → integrations page
3. In parallel (batch 2 — SEO data):
a. dataforseo_labs_google_domain_rank_overview
b. dataforseo_labs_google_ranked_keywords
c. backlinks_summary
d. backlinks_referring_domains
e. dataforseo_labs_google_relevant_pages
f. dataforseo_labs_google_competitors_domain
4. In parallel (batch 3 — optional extras):
a. domain_analytics_technologies_domain_technologies
b. firecrawl_search → G2/Capterra reviews
c. dataforseo_labs_google_domain_intersection (vs. user's domain)
5. Synthesize into full profile
1. Map all competitor sites in parallel
2. Scrape all homepages in parallel, then pricing pages in parallel
3. Pull domain_rank_overview for all in parallel
4. Pull backlinks_bulk_ranks for all at once
5. Build profiles in sequence (synthesis requires focus)
6. Build summary comparison last
| Issue | Action |
|---|---|
| Firecrawl scrape returns empty/blocked | Try with firecrawl_browser_create for JS-heavy sites |
| Pricing page not found in map | Search for /pricing, /plans, /packages — some sites use different paths |
| DataForSEO returns no data for domain | Domain may be too new or too small — note "insufficient data" in profile |
| Rate limits hit | Space out requests; prioritize highest-value data first |
| Review page scraping blocked | Use firecrawl_search to find cached or alternative review sources |
When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product]
View source ↗You are an expert in creating competitor comparison and alternative pages. Your goal is to build pages that rank for competitive search terms, provide genuine value to evaluators, and position your product effectively.
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.
Before creating competitor pages, understand:
Your Product
- Core value proposition
- Key differentiators
- Ideal customer profile
- Pricing model
- Strengths and honest weaknesses
Competitive Landscape
- Direct competitors
- Indirect/adjacent competitors
- Market positioning of each
- Search volume for competitor terms
Goals
- SEO traffic capture
- Sales enablement
- Conversion from competitor users
- Brand positioning
Search intent: User is actively looking to switch from a specific competitor
URL pattern: /alternatives/[competitor] or /[competitor]-alternative
Target keywords: "[Competitor] alternative", "alternative to [Competitor]", "switch from [Competitor]"
Page structure:
1. Why people look for alternatives (validate their pain)
2. Summary: You as the alternative (quick positioning)
3. Detailed comparison (features, service, pricing)
4. Who should switch (and who shouldn't)
5. Migration path
6. Social proof from switchers
7. CTA
Search intent: User is researching options, earlier in journey
URL pattern: /alternatives/[competitor]-alternatives
Target keywords: "[Competitor] alternatives", "best [Competitor] alternatives", "tools like [Competitor]"
Page structure:
1. Why people look for alternatives (common pain points)
2. What to look for in an alternative (criteria framework)
3. List of alternatives (you first, but include real options)
4. Comparison table (summary)
5. Detailed breakdown of each alternative
6. Recommendation by use case
7. CTA
Important: Include 4-7 real alternatives. Being genuinely helpful builds trust and ranks better.
AI-answer expectations by stage: these pages often earn citations in AI answers, but whether AI recommends your brand from them depends on offsite consensus (reviews, forums, analysts) — for emerging brands, a self-ranked list can surface the competitors in the AI answer while you get only the citation. Still publish for search intent and category framing, but set expectations accordingly — see ai-seo's citations-vs-recommendations reference for the data.
Search intent: User is directly comparing you to a specific competitor
URL pattern: /vs/[competitor] or /compare/[you]-vs-[competitor]
Target keywords: "[You] vs [Competitor]", "[Competitor] vs [You]"
Page structure:
1. TL;DR summary (key differences in 2-3 sentences)
2. At-a-glance comparison table
3. Detailed comparison by category (Features, Pricing, Support, Ease of use, Integrations)
4. Who [You] is best for
5. Who [Competitor] is best for (be honest)
6. What customers say (testimonials from switchers)
7. Migration support
8. CTA
Search intent: User comparing two competitors (not you directly)
URL pattern: /compare/[competitor-a]-vs-[competitor-b]
Page structure:
1. Overview of both products
2. Comparison by category
3. Who each is best for
4. The third option (introduce yourself)
5. Comparison table (all three)
6. CTA
Why this works: Captures search traffic for competitor terms, positions you as knowledgeable.
Start every page with a quick summary for scanners—key differences in 2-3 sentences.
Go beyond tables. For each dimension, write a paragraph explaining the differences and when each matters.
For each category: describe how each handles it, list strengths and limitations, give bottom line recommendation.
Include tier-by-tier comparison, what's included, hidden costs, and total cost calculation for sample team size.
Be explicit about ideal customer for each option. Honest recommendations build trust.
Cover what transfers, what needs reconfiguration, support offered, and quotes from customers who switched.
For detailed templates: See references/templates.md
Create a single source of truth for each competitor with:
- Positioning and target audience
- Pricing (all tiers)
- Feature ratings
- Strengths and weaknesses
- Best for / not ideal for
- Common complaints (from reviews)
- Migration notes
For data structure and examples: See references/content-architecture.md
For each competitor, gather:
| Format | Primary Keywords |
|---|---|
| Alternative (singular) | [Competitor] alternative, alternative to [Competitor] |
| Alternatives (plural) | [Competitor] alternatives, best [Competitor] alternatives |
| You vs Competitor | [You] vs [Competitor], [Competitor] vs [You] |
| Competitor vs Competitor | [A] vs [B], [B] vs [A] |
Consider FAQ schema for common questions like "What is the best alternative to [Competitor]?"
Complete competitor profile in YAML format for use across all comparison pages.
For each page: URL, meta tags, full page copy organized by section, comparison tables, CTAs.
Recommended pages to create with priority order based on search volume.
How to structure and maintain competitor data for scalable comparison pages.
Create a single source of truth for each competitor:
competitor_data/
├── notion.md
├── airtable.md
├── monday.md
└── ...
Per competitor, document:
name: Notion
website: notion.so
tagline: "The all-in-one workspace"
founded: 2016
headquarters: San Francisco
# Positioning
primary_use_case: "docs + light databases"
target_audience: "teams wanting flexible workspace"
market_position: "premium, feature-rich"
# Pricing
pricing_model: per-seat
free_tier: true
free_tier_limits: "limited blocks, 1 user"
starter_price: $8/user/month
business_price: $15/user/month
enterprise: custom
# Features (rate 1-5 or describe)
features:
documents: 5
databases: 4
project_management: 3
collaboration: 4
integrations: 3
mobile_app: 3
offline_mode: 2
api: 4
# Strengths (be honest)
strengths:
- Extremely flexible and customizable
- Beautiful, modern interface
- Strong template ecosystem
- Active community
# Weaknesses (be fair)
weaknesses:
- Can be slow with large databases
- Learning curve for advanced features
- Limited automations compared to dedicated tools
- Offline mode is limited
# Best for
best_for:
- Teams wanting all-in-one workspace
- Content-heavy workflows
- Documentation-first teams
- Startups and small teams
# Not ideal for
not_ideal_for:
- Complex project management needs
- Large databases (1000s of rows)
- Teams needing robust offline
- Enterprise with strict compliance
# Common complaints (from reviews)
common_complaints:
- "Gets slow with lots of content"
- "Hard to find things as workspace grows"
- "Mobile app is clunky"
# Migration notes
migration_from:
difficulty: medium
data_export: "Markdown, CSV, HTML"
what_transfers: "Pages, databases"
what_doesnt: "Automations, integrations setup"
time_estimate: "1-3 days for small team"
Same structure for yourself—be honest:
name: [Your Product]
# ... same fields
strengths:
- [Your real strengths]
weaknesses:
- [Your honest weaknesses]
best_for:
- [Your ideal customers]
not_ideal_for:
- [Who should use something else]
Each page pulls from centralized data:
Benefits:
- Update competitor pricing once, updates everywhere
- Add new feature comparison once, appears on all pages
- Consistent accuracy across pages
- Easier to maintain at scale
URL: /alternatives or /alternatives/index
Purpose: Lists all "[Competitor] Alternative" pages
Page structure:
1. Headline: "[Your Product] as an Alternative"
2. Brief intro on why people switch to you
3. List of all alternative pages with:
- Competitor name/logo
- One-line summary of key differentiator vs. that competitor
- Link to full comparison
4. Common reasons people switch (aggregated)
5. CTA
Example:
## Explore [Your Product] as an Alternative
Looking to switch? See how [Your Product] compares to the tools you're evaluating:
- **[Notion Alternative](/alternatives/notion)** — Better for teams who need [X]
- **[Airtable Alternative](/alternatives/airtable)** — Better for teams who need [Y]
- **[Monday Alternative](/alternatives/monday)** — Better for teams who need [Z]
URL: /vs or /compare
Purpose: Lists all "You vs [Competitor]" and "[A] vs [B]" pages
Page structure:
1. Headline: "Compare [Your Product]"
2. Section: "[Your Product] vs Competitors" — list of direct comparisons
3. Section: "Head-to-Head Comparisons" — list of [A] vs [B] pages
4. Brief methodology note
5. CTA
Keep them updated: When you add a new comparison page, add it to the relevant index.
Internal linking:
- Link from index → individual pages
- Link from individual pages → back to index
- Cross-link between related comparisons
SEO value:
- Index pages can rank for broad terms like "project management tool comparisons"
- Pass link equity to individual comparison pages
- Help search engines discover all comparison content
Sorting options:
- By popularity (search volume)
- Alphabetically
- By category/use case
- By date added (show freshness)
Include on index pages:
- Last updated date for credibility
- Number of pages/comparisons available
- Quick filters if you have many comparisons
The site footer appears on all marketing pages, making it a powerful internal linking opportunity for competitor pages.
At minimum, add links to your comparison index pages in the footer:
Footer
├── Compare
│ ├── Alternatives → /alternatives
│ └── Comparisons → /vs
This ensures every marketing page passes link equity to your comparison content hub.
For stronger internal linking, create dedicated footer columns for each format you've built, linking directly to your top competitors:
Footer
├── [Product] vs ├── Alternatives to ├── Compare
│ ├── vs Notion │ ├── Notion Alternative │ ├── Notion vs Airtable
│ ├── vs Airtable │ ├── Airtable Alternative │ ├── Monday vs Asana
│ ├── vs Monday │ ├── Monday Alternative │ ├── Notion vs Monday
│ ├── vs Asana │ ├── Asana Alternative │ ├── ...
│ ├── vs Clickup │ ├── Clickup Alternative │ └── View all →
│ ├── ... │ ├── ... │
│ └── View all → │ └── View all → │
Guidelines:
- Include up to 8 links per column (top competitors by search volume)
- Add "View all" link to the full index page
- Only create columns for formats you've actually built pages for
- Prioritize competitors with highest search volume
/vs/ URLs)Ready-to-use templates for each section of competitor comparison pages.
Start every page with a quick summary for scanners:
**TL;DR**: [Competitor] excels at [strength] but struggles with [weakness].
[Your product] is built for [your focus], offering [key differentiator].
Choose [Competitor] if [their ideal use case]. Choose [You] if [your ideal use case].
For each major dimension, write a paragraph:
## Features
[Competitor] offers [description of their feature approach].
Their strength is [specific strength], which works well for [use case].
However, [limitation] can be challenging for [user type].
[Your product] takes a different approach with [your approach].
This means [benefit], though [honest tradeoff].
Teams who [specific need] often find this more effective.
Go beyond checkmarks:
## Feature Comparison
### [Feature Category]
**[Competitor]**: [2-3 sentence description of how they handle this]
- Strengths: [specific]
- Limitations: [specific]
**[Your product]**: [2-3 sentence description]
- Strengths: [specific]
- Limitations: [specific]
**Bottom line**: Choose [Competitor] if [scenario]. Choose [You] if [scenario].
## Pricing
| | [Competitor] | [Your Product] |
|---|---|---|
| Free tier | [Details] | [Details] |
| Starting price | $X/user/mo | $X/user/mo |
| Business tier | $X/user/mo | $X/user/mo |
| Enterprise | Custom | Custom |
**What's included**: [Competitor]'s $X plan includes [features], while
[Your product]'s $X plan includes [features].
**Total cost consideration**: Beyond per-seat pricing, consider [hidden costs,
add-ons, implementation]. [Competitor] charges extra for [X], while
[Your product] includes [Y] in base pricing.
**Value comparison**: For a 10-person team, [Competitor] costs approximately
$X/year while [Your product] costs $Y/year, with [key differences in what you get].
## Service & Support
| | [Competitor] | [Your Product] |
|---|---|---|
| Documentation | [Quality assessment] | [Quality assessment] |
| Response time | [SLA if known] | [Your SLA] |
| Support channels | [List] | [List] |
| Onboarding | [What they offer] | [What you offer] |
| CSM included | [At what tier] | [At what tier] |
**Support quality**: Based on [G2/Capterra reviews, your research],
[Competitor] support is described as [assessment]. Common feedback includes
[quotes or themes].
[Your product] offers [your support approach]. [Specific differentiator like
response time, dedicated CSM, implementation help].
## Who Should Choose [Competitor]
[Competitor] is the right choice if:
- [Specific use case or need]
- [Team type or size]
- [Workflow or requirement]
- [Budget or priority]
**Ideal [Competitor] customer**: [Persona description in 1-2 sentences]
## Who Should Choose [Your Product]
[Your product] is built for teams who:
- [Specific use case or need]
- [Team type or size]
- [Workflow or requirement]
- [Priority or value]
**Ideal [Your product] customer**: [Persona description in 1-2 sentences]
## Switching from [Competitor]
### What transfers
- [Data type]: [How easily, any caveats]
- [Data type]: [How easily, any caveats]
### What needs reconfiguration
- [Thing]: [Why and effort level]
- [Thing]: [Why and effort level]
### Migration support
We offer [migration support details]:
- [Free data import tool / white-glove migration]
- [Documentation / migration guide]
- [Timeline expectation]
- [Support during transition]
### What customers say about switching
> "[Quote from customer who switched]"
> — [Name], [Role] at [Company]
Focus on switchers:
## What Customers Say
### Switched from [Competitor]
> "[Specific quote about why they switched and outcome]"
> — [Name], [Role] at [Company]
> "[Another quote]"
> — [Name], [Role] at [Company]
### Results after switching
- [Company] saw [specific result]
- [Company] reduced [metric] by [amount]
Instead of:
| Feature | You | Competitor |
|---------|-----|-----------|
| Feature A | ✓ | ✓ |
| Feature B | ✓ | ✗ |
Do this:
| Feature | You | Competitor |
|---------|-----|-----------|
| Feature A | Full support with [detail] | Basic support, [limitation] |
| Feature B | [Specific capability] | Not available |
Group features into meaningful categories:
- Core functionality
- Collaboration
- Integrations
- Security & compliance
- Support & service
| Category | You | Competitor | Notes |
|---|---|---|---|
| Ease of use | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | [Brief note] |
| Feature depth | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | [Brief note] |
When the user wants to conduct, analyze, or synthesize customer research. Use when the user mentions "customer research," "ICP research," "talk to customers," "analyze transcripts," "customer interviews," "survey analysi
View source ↗You are an expert customer researcher. Your goal is to help uncover what customers actually think, feel, say, and struggle with — so that everything from positioning to product to copy is grounded in reality rather than assumption.
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 to skip questions already answered.
You have raw research material (transcripts, surveys, reviews, tickets). Your job is to extract signal.
You need to gather intel from online sources (Reddit, G2, forums, communities, review sites). Your job is to know where to look and what to extract.
Most engagements combine both. Establish which mode applies before proceeding.
Customer interview / sales call transcripts
- Extract: pains, triggers, desired outcomes, language used, objections, alternatives considered
- Look for: the moment they decided to look for a solution, what they tried before, what success looks like to them
Survey results
- Segment responses by customer tier, use case, or tenure before drawing conclusions
- Flag: what open-ended answers say vs. what multiple-choice answers say (they often conflict)
- Identify: the 20% of responses that contain the most useful signal
Customer support conversations
- Mine for: recurring complaints, confusion points, feature requests, and "I wish it could…" language
- Categorize tickets before analyzing — don't treat all tickets as equal signal
- Separate bugs from confusion from missing features from expectation mismatches
Win/loss interviews and churned customer notes
- Wins: what tipped the decision? What almost made them choose a competitor?
- Losses and churn: was it price, features, fit, timing, or something else?
- Segment by reason — don't average across different churn causes
NPS responses
- Passives and detractors are higher signal than promoters for improvement work
- Pair scores with verbatims — a 9 with a specific complaint beats a 10 with no comment
For each asset, extract:
Jobs to Be Done — what outcome is the customer trying to achieve?
- Functional job: the task itself
- Emotional job: how they want to feel
- Social job: how they want to be perceived
Pain Points — what's frustrating, broken, or inadequate about their current situation?
- Prioritize pains mentioned unprompted and with emotional language
Trigger Events — what changed that made them seek a solution?
- Common triggers: team growth, new hire, missed target, embarrassing incident, competitor doing something
Desired Outcomes — what does success look like in their words?
- Capture exact quotes, not paraphrases
Language and Vocabulary — exact words and phrases customers use
- This is gold for copy. "We were drowning in spreadsheets" > "manual process inefficiency"
Alternatives Considered — what else did they look at or try?
- Includes doing nothing, hiring someone, or building internally
After extracting from individual assets:
Label every insight with a confidence level before presenting it:
| Confidence | Criteria |
|---|---|
| High | Theme appears in 3+ independent sources; mentioned unprompted; consistent across segments |
| Medium | Theme appears in 2 sources, or only prompted, or limited to one segment |
| Low | Single source; could be an outlier; needs validation |
Recency window: Weight sources from the last 12 months more heavily. Markets shift — a 3-year-old transcript may reflect a different product and buyer.
Sample bias checks:
- Online reviewers skew toward power users and people with strong opinions
- Support tickets skew toward problems, not value
- Reddit skews technical and skeptical vs. mainstream buyers
- Factor this in when drawing conclusions about "all customers"
Minimum viable sample: Don't build personas or draw messaging conclusions from fewer than 5 independent data points per segment.
Online communities are where customers speak without a filter. The goal is to find authentic, unmoderated language about the problem space.
Choose sources based on your ICP type — then read references/source-guides.md for detailed playbooks, search operators, and per-platform extraction tips.
| ICP Type | Primary Sources |
|---|---|
| B2B SaaS / technical buyers | Reddit (role-specific subs), G2/Capterra, Hacker News, LinkedIn, Indie Hackers, SparkToro |
| SMB / founders | Reddit (r/entrepreneur, r/smallbusiness), Indie Hackers, Product Hunt, Facebook Groups, SparkToro |
| Developer / DevOps | r/devops, r/programming, Hacker News, Stack Overflow, Discord servers |
| B2C / consumer | App store reviews (1-3 star), Reddit hobby/lifestyle subs, YouTube comments, TikTok/Instagram comments |
| Enterprise | LinkedIn, industry analyst reports, G2 Enterprise filter, job postings, SparkToro |
Quick decision guide:
- Have a product category? → Start with G2/Capterra reviews (yours + competitors)
- Need to know where your audience spends time? → SparkToro (reveals podcasts, YouTube, subreddits, websites, social accounts)
- Need raw language? → Reddit and YouTube comments
- Need trigger events? → LinkedIn posts, job postings, Hacker News "Ask HN" threads
- Need competitive intel? → Competitor 4-star reviews on G2; Product Hunt discussions; SparkToro competitor audience analysis
For every piece of content you find:
| Field | What to Capture |
|---|---|
| Source | Platform, thread URL, date |
| Verbatim quote | Exact words — don't paraphrase |
| Context | What prompted the comment? |
| Sentiment | Positive / negative / neutral / frustrated |
| Theme tag | Pain / trigger / outcome / alternative / language |
| Customer profile signals | Role, company size, industry hints from the post |
After gathering from multiple sources, synthesize into:
## Top Themes (ranked by frequency × intensity)
### Theme 1: [Name]
**Summary**: [1-2 sentences]
**Frequency**: Appeared in X of Y sources
**Intensity**: High / Medium / Low (based on emotional language used)
**Representative quotes**:
- "[exact quote]" — [source, date]
- "[exact quote]" — [source, date]
**Implications**: What this means for messaging / product / positioning
### Theme 2: ...
Early-stage products (or new categories) lack first-party review data. Don't invent personas — walk outward through proxy sources, in order:
Personas built this way are provisional: tag each with its proxy source, and replace proxy evidence with first-party evidence as real reviews arrive.
Personas should be built from research, not invented. Don't create a persona until you have at least 5-10 data points (interviews, reviews, or community posts) from a consistent segment.
## [Persona Name] — [Role/Title]
**Profile**
- Title range: [e.g., "Marketing Manager to VP of Marketing"]
- Company size: [e.g., "50–500 employees, Series A–C SaaS"]
- Industry: [if narrow]
- Reports to: [who]
- Team size managed: [if relevant]
**Primary Job to Be Done**
[One sentence: what outcome are they trying to achieve in their role?]
**Trigger Events**
What causes them to start looking for a solution like yours?
- [trigger 1]
- [trigger 2]
**Top Pains**
1. [Pain — in their words if possible]
2. [Pain]
3. [Pain]
**Desired Outcomes**
- [What success looks like to them]
- [How they measure it]
- [How it makes them look to their boss/team]
**Objections and Fears**
- [What makes them hesitate to buy or switch]
**Alternatives They Consider**
- [Competitor, DIY, do nothing, hire someone]
**Key Vocabulary**
Words and phrases they actually use (sourced from research):
- "[phrase]"
- "[phrase]"
**How to Reach Them**
- Channels: [where they spend time]
- Content they consume: [formats, topics]
- Influencers/communities they trust: [specific names if known]
Depending on what the user needs, offer:
Ask the user which deliverable(s) they need before generating output.
If context is unclear:
Don't ask all five at once — lead with #1 and #2, then follow up as needed.
| When to hand off | Skill |
|---|---|
| Writing copy informed by the research | copywriting |
| Optimizing a page using VOC insights | cro |
| Building a competitor comparison page | competitors |
| Creating a churn prevention strategy from churn research | churn-prevention |
| Planning paid ads informed by research | ads |
| Writing cold email using research on pain/trigger | cold-email |
| Translating customer research into an ICP for outbound | prospecting |
| Planning content based on discovered topics | content-strategy |
| Rolling research into a comprehensive marketing plan | marketing-plan |
Detailed, source-by-source playbooks for gathering customer intelligence from online watering holes.
Start by identifying where your ICP spends time, not where your product is discussed.
Discovery methods:
- Search site:reddit.com "[job title] tools" or site:reddit.com "[problem category] software"
- Use subreddit search tools with problem-space keywords
- Look at what subreddits show up in Google results when you search ICP problems
- Check what subreddits competitors' customers mention in reviews
Common high-value subreddits by category:
- B2B SaaS: r/sales, r/marketing, r/entrepreneur, r/startups, r/smallbusiness
- Dev tools: r/programming, r/devops, r/webdev, r/cscareerquestions
- Analytics/data: r/analytics, r/dataengineering, r/BusinessIntelligence
- Marketing: r/PPC, r/SEO, r/emailmarketing, r/content_marketing
- HR/recruiting: r/recruiting, r/humanresources, r/jobs
- Finance/ops: r/accounting, r/financialplanning, r/projectmanagement
site:reddit.com/r/[subreddit] "[keyword]"
site:reddit.com "[problem]" "recommend" OR "suggestion" OR "alternative"
site:reddit.com "[competitor name]" "vs" OR "alternative" OR "switched"
High-signal post types:
- "What tools do you use for X?" → reveals alternatives and vocab
- "Frustrated with [competitor], looking for alternatives" → reveals pain and switching triggers
- "How do you handle X?" → reveals workflow and workarounds
- "Is [your category] worth it?" → reveals objections and evaluation criteria
- Complaint threads about competitors → reveals gaps you might fill
What to extract:
- The exact problem described in the post
- Top-voted solutions (what do practitioners actually recommend?)
- Complaints about existing solutions in comments
- The language used — note specific words and phrases
- Upvote patterns — consensus vs. controversy
site:reddit.com [query] (better results)Read in this order for maximum signal:
What to extract:
- What they say they use it for (the job to be done)
- What they say is hardest or most frustrating
- What they compare it to ("coming from [X]", "better than [Y]")
- Industry and role signals in reviewer profiles
The 4-star competitor reviews are gold — customers who like the product but still have complaints.
G2 structure to exploit:
- "What do you like best?" → their strengths (your battlecard intel)
- "What do you dislike?" → their weaknesses (your opportunities)
- "What problems are you solving?" → the job to be done
Capterra has similar structure. Trustpilot skews B2C. AppSumo reviews are useful for SMB/prosumer SaaS.
For each competitor's 4-star reviews, extract:
| Category | Notes |
|---|---|
| Job to be done | Why do they use the product? |
| Top praise | What do they love (and might be hard for you to match)? |
| Top complaint | What frustrates them? |
| Switching context | Did they mention switching from something else? |
| Unmet need | "I wish it could…" or "It would be better if…" |
Strong signal for founder/builder/SMB ICP.
Where to look:
- "Ask IH" posts: questions about problems your product solves
- Milestone posts: when founders describe their stack, they reveal tool preferences and pain
- Comment threads on product launches in your category
Search: site:indiehackers.com "[problem]" or use IH's native search.
Discussion tabs on competing products are a research goldmine:
- Questions asked = pre-sales concerns = objections
- Comments = early adopter reactions = leading indicators of reception
- "Alternatives to X" collections reveal the competitive landscape as users see it
Strong signal for technical/developer ICP. Skews toward builders and skeptics.
High-value searches:
- site:news.ycombinator.com "[competitor or category]"
- HN "Ask HN: best tools for X" threads
- "Show HN" posts for competitors — read the skeptical comments
What's different about HN:
- Users are more likely to critique underlying architecture and business model
- Strong opinions about pricing models (especially anything subscription-based)
- First principles objections you might not hear elsewhere
Search for posts by practitioners describing their workflows:
- "[Role] at [company size]" + problem keyword
- "We used to [old way] but now we [new way]" stories
- Posts asking for tool recommendations get comments from active buyers
A job posting is a company's admission of a pain point.
What to look for:
- What tools are listed as "nice to have" vs. "required"? (reveals stack and adjacent tools)
- What metrics and outcomes are mentioned in the role description?
- What does the role spend most of its time doing? (reveals the job to be done)
Search: site:linkedin.com/jobs "[role title]" "[relevant tool or category]"
What to look for in comments:
- "Does this work for [specific use case]?" → edge cases and unmet needs
- "I tried this but…" → failure points
- "What about [competitor]?" → active evaluation
- Timestamps with questions → confusion points in the workflow
"[competitor]" -filter:replies min_faves:10
"[problem keyword]" "anyone know" OR "recommend" OR "alternative"
"[category] is broken" OR "frustrated with [category]"
Google: "[competitor 1] vs [competitor 2]" or "best [category] software [year]"
Read the comments on these posts — people who find comparison content are actively evaluating. Their comments are questions your sales process should answer.
B2C research requires different sources than B2B SaaS. Consumer buyers don't congregate on LinkedIn or G2 — they leave traces in app stores, social media, and communities built around the activity your product serves.
One of the richest unfiltered sources for mobile/consumer products.
Read in this order:
1. 1-2 star reviews — failure modes, unmet expectations, frustration peaks
2. 3-star reviews — honest tradeoffs and "it's good but…" feedback
3. 5-star reviews — what they love in their own words (proof points and positioning)
What to extract:
- What job they hired the app to do ("I use this to…")
- The moment it stopped working for them
- What they compared it to or switched from
- Emotional language — "I love how…", "I'm so frustrated that…"
Search tip: Sort by "Most Recent" to get fresh signal, then "Most Critical" for pain themes.
Same priority order as app stores: 3-star reviews first.
G2 analog for consumer SaaS: Trustpilot, Sitejabber, and product-specific review aggregators.
B2C Reddit is highly vertical — go to the hobby/lifestyle subreddit, not the general ones.
Examples by product type:
- Fitness apps: r/running, r/loseit, r/fitness, r/MyFitnessPal
- Personal finance: r/personalfinance, r/financialindependence, r/ynab
- Productivity/notes: r/productivity, r/Notion, r/ObsidianMD
- Travel: r/travel, r/solotravel, r/digitalnomad
- Parenting: r/Parenting, r/beyondthebump, r/daddit
Search pattern: site:reddit.com/r/[community] "[app name OR problem]"
High-signal for consumer products with visual/lifestyle appeal.
How to find signal:
- Search TikTok for "[product name] review" or "is [product] worth it"
- Watch the top 5-10 videos; read ALL comments — not just likes
- On Instagram, check tagged posts from real users (not brand posts)
What to extract:
- Questions in comments = unmet needs or unclear positioning
- "Does this work for…?" = jobs they want to hire it for
- "I switched from X" comments = switching triggers
- Complaints about price, missing features, or broken promises
Same approach as B2B but different video types:
Comments on review videos are especially valuable — these are people actively in the consideration phase.
SparkToro is a behavioral audience research tool. Instead of mining individual posts and comments, it aggregates clickstream, search, and social data to show what your audience does at scale — what they read, watch, listen to, follow, and search for.
By competitor:
- "People who follow @competitor" — reveals shared audience affinities
- "People who visit competitor.com" — shows what else they consume
By audience description:
- "People who frequently talk about [topic]" — finds audience behaviors
- "People whose bio contains [job title]" — profiles a role-based segment
By your own audience:
- "People who visit yourdomain.com" — understand your actual audience
- Compare against competitor audience profiles to find gaps
| Data Type | What It Tells You | Use It For |
|---|---|---|
| Top websites visited | Where your audience reads | Content partnerships, guest posting targets |
| Top podcasts | What they listen to | Podcast guesting, sponsorship decisions |
| Top YouTube channels | What they watch | Video content strategy, ad placements |
| Top subreddits | Where they discuss | Community participation, Reddit ad targeting |
| Search keywords | What they Google | SEO and content topic planning |
| AI prompt topics | What they ask AI tools | Emerging content opportunities |
| Social accounts followed | Who influences them | Influencer partnerships, co-marketing |
| Demographics | Who they are | Persona building, ad targeting |
SparkToro data is aggregated and anonymized — it shows patterns, not individual opinions. Treat it as:
- High confidence for behavioral data (what they visit, follow, search for)
- Medium confidence for demographic data (self-reported, may be incomplete)
- Not a substitute for qualitative research (doesn't capture language, emotions, or the "why")
See tools/integrations/sparktoro.md for full tool details and pricing.
Use a simple tagging system across all sources:
| Tag | Meaning |
|---|---|
#pain |
A problem or frustration |
#trigger |
An event that prompted the search |
#outcome |
What success looks like |
#language |
Exact phrases worth using in copy |
#alternative |
Another solution they considered or use |
#objection |
Reason to hesitate or not buy |
#competitor |
Anything about a competing product |
Keep a running doc with columns: Source | Date | Quote | Tags | Notes
After 20-30 entries, patterns will emerge. Look for quotes that appear in multiple unrelated sources — those are your highest-confidence insights.
Not all sources carry equal weight. Use this guide when assigning confidence labels.
| Source | Signal Strength | Bias to Note |
|---|---|---|
| Customer interviews (unprompted) | Very high | Small sample; selection bias toward engaged customers |
| Win/loss interviews | High | Recent memory only; rationalization common |
| App store / G2 reviews | High | Skews toward strong opinions (love or hate) |
| Reddit / community posts | Medium-high | Skews technical, skeptical, vocal minorities |
| Support tickets | Medium | Skews toward problems; silent majority not represented |
| Survey (open-ended) | Medium | Primed by question framing |
| Survey (multiple choice) | Low-medium | Artifacts of the options you provided |
| NPS verbatims | Medium | Correlates with score; prompted by the survey moment |
| YouTube/TikTok comments | Medium | Skews toward engaged viewers; social performance |
| SparkToro audience data | Medium-high | Aggregated behavioral data; strong for "what" but not "why" |
| Job postings | Low-medium | Aspirational, not necessarily reflective of current pain |
When presenting insights, lead with confidence:
[HIGH CONFIDENCE] Customers feel overwhelmed by manual reporting — appears in 12 of 20 interviews,
4 Reddit threads, and is the #1 complaint in 3-star G2 reviews. Consistent across SMB and mid-market.
[MEDIUM CONFIDENCE] Customers compare us to spreadsheets more than to direct competitors —
mentioned in 6 interviews and 3 Reddit threads, but not yet seen in review data.
[LOW CONFIDENCE] Enterprise buyers may have procurement concerns — mentioned by 2 interviewees
from companies 500+. Needs more signal before acting on it.
When a theme appears consistently across old and new data, that's a durable signal worth acting on.
When the user wants to design, construct, or improve an offer — the thing they actually sell — including value framing, bonus stacking, guarantee design, scarcity/urgency, naming, and payment structure. Also use when the
View source ↗You are an expert in offer construction. Your goal is to help the user build offers that move — not by writing better copy on a worse offer, but by improving the offer itself.
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.
The offer is the thing, not the page. Better copy on a weak offer compounds slowly. A stronger offer with average copy converts immediately. Most "we need better copy" requests are actually "we need a better offer" requests in disguise.
This skill exists because the rest of the repo handles the expression of an offer — copywriting writes the sales page, cro optimizes the conversion path, pricing sets the tier structure, launch orchestrates the moment, paywalls shapes the upgrade prompt. None of them ask the deeper question: is the offer underneath any of that actually good?
You sell:
- Services — consulting, freelance, agency retainers, productized services
- Courses — async, cohort-based, live
- Coaching — 1:1, group, mastermind
- Info products — guides, swipe files, templates, communities
- High-ticket B2B — $5K+ ACV with a sales conversation
- Direct-response — e-com promo offers, infomercial-style, paid-traffic-to-VSL
pricing does more of the workYou sell:
- Self-serve SaaS with tiered subscriptions — the levers are mostly tier structure, value metric, and packaging; offer construction (bonuses, guarantees) is secondary
- Marketplaces — the offer is structural, not constructed
Skim this skill in those cases for the value equation framing, then go to pricing.
The single most useful frame for offer design. Originally from Alex Hormozi's $100M Offers — internalized broadly across direct-response and creator-economy training since.
Dream Outcome × Perceived Likelihood of Achievement
Value = ─────────────────────────────────────────────────────────
Time Delay × Effort & Sacrifice
You move the four levers like this:
| Lever | What it means | How to increase value |
|---|---|---|
| Dream outcome ↑ | What the customer actually wants | Connect to the bigger goal behind the surface ask. Specify and name it. |
| Perceived likelihood ↑ | Do they believe they'll get it | Proof (case studies, named customers, data), guarantees, methodology specificity |
| Time delay ↓ | How long until result | Faster onboarding, faster first win, faster end-to-end timeline |
| Effort & sacrifice ↓ | What it costs them in time/work/risk besides money | Done-for-you, simpler process, fewer decisions, lower learning curve |
Implication for offer construction: most "lower the price" requests are actually "raise the numerator or lower the denominator" requests. Price is the comparison, not the value.
For the full framework, examples, and how to diagnose which lever is broken: see references/value-equation.md
A complete offer has six components. Skip any one and conversion suffers.
| # | Component | Question it answers |
|---|---|---|
| 1 | Core deliverable | What do they get? |
| 2 | Bonus stack | What else do they get that makes the core feel undervalued? |
| 3 | Guarantee | What happens if it doesn't work? |
| 4 | Scarcity / urgency | Why now, not later? |
| 5 | Name | What is this thing called? |
| 6 | Price + payment structure | What do they pay and how? |
Most weak offers fail on bonuses (none), guarantees (none or wrong type), or scarcity (none, or fake). Most aggressive-to-the-point-of-cringe offers fail on guarantee (over-promising) or scarcity (fake countdown timers).
For the full anatomy with worked examples: see references/offer-anatomy.md
| Reference | When to read |
|---|---|
| value-equation.md | Diagnosing which lever is broken on a stuck offer |
| offer-anatomy.md | Building a complete offer from scratch |
| guarantee-design.md | Picking the right type of guarantee for your business model |
| bonus-stacking.md | Adding bonuses that raise perceived value without devaluing the core |
| scarcity-urgency.md | Creating real scarcity (and avoiding the fake patterns that destroy trust) |
| offer-formats.md | Format playbooks by business type — service, course, coaching, info product, SaaS lead magnet, agency retainer, high-ticket B2B |
| examples.md | Anonymized worked examples — before/after for each business type |
When the user says "my offer isn't converting" or "I want to improve my offer":
Some offer patterns work but cost more than they're worth:
The repo voice: opinionated, but honest. Building offers well doesn't mean building offers loud.
When drafting offer language (sales pages, emails, headlines), avoid:
Use specific numbers, named customers, concrete outcomes, real timelines. Specificity beats superlatives.
How to add bonuses that raise perceived value without devaluing the core offer.
Three jobs at once:
The third job is the underrated one. Most weak bonus stacks throw four generic "extras" at the buyer. Strong bonus stacks read the buyer's specific hesitations and close them in order.
For each major objection your buyer has, add a bonus that closes it.
| Objection | Targeted bonus |
|---|---|
| "I don't have time to implement this" | Done-for-you setup, week 1 |
| "I don't know which tools to use" | Pre-vetted tool stack with discount codes |
| "What if I get stuck?" | 30-day async Slack support |
| "I'm not sure my team will buy in" | Stakeholder pitch deck |
| "I've tried something like this before and it didn't work" | Case study from someone in your exact situation |
| "What about [edge case in my industry]?" | Industry-specific bonus reference doc |
| "Will I have to learn a bunch of new tools?" | Pre-built templates for the tools we recommend |
| "What if I don't finish it?" | 1:1 accountability check-in at day 30 |
| "My situation is more complex than the average buyer" | 1:1 onboarding call to customize the plan |
| "Will this work in [region/language]?" | Localized version or addendum |
A 4-bonus stack that closes 4 specific objections converts massively better than a 4-bonus stack of generic "extras."
The answers cluster around 3–6 objections. Build a bonus for each.
Each bonus has a stated value (what it would cost if you bought it separately). Bonuses should:
Have a stated value the buyer can verify. Compare to a comparable product or service. "$497 value — that's what the standalone template pack costs" beats "$5,000 value." (Standalone? Compared to what?)
Total to less than 2x the price of the core offer. A $1K offer can comfortably have $1.5K in bonuses. A $1K offer with "$25K in bonuses" reads as a scam.
Be things you'd actually sell separately. If you'd never sell the bonus as a standalone product, the stated value isn't real. Sophisticated buyers can tell.
Each have a specific named outcome. "Bonus: marketing toolkit" is weak. "Bonus: 12 pre-built Notion templates for your first 90 days, valued at $297 because that's what the standalone template pack sells for at [link]" is strong.
Most strong offers stack exactly 3–5 bonuses. More starts to feel like padding; fewer leaves objections un-closed.
A common structure:
| # | Type | Purpose | Typical value |
|---|---|---|---|
| 1 | Speed bonus | Removes time-delay objection | Templates, swipes, accelerators |
| 2 | Trust bonus | Removes likelihood-of-failure objection | Case study, methodology doc, examples library |
| 3 | Stuck bonus | Removes "what if I get stuck" objection | Office hours, Slack, on-demand support |
| 4 | Decision bonus | Removes "I have to choose between X and Y" objection | Tool stack with discount codes, pre-vetted recommendations |
| 5 (optional) | Bigger-than-you-asked bonus | Adds dream-outcome surface area | Adjacent deliverable, related framework, partner offer |
Example for a $2K B2B copywriting course:
| # | Bonus | Closes |
|---|---|---|
| 1 | "30 winning sales page templates (last updated 2026-Q2)" — $297 value | "I don't have time to write from scratch" |
| 2 | "9 case studies from agencies that hit $250K MRR using these frameworks" — $0 (proof, not a saleable asset) | "Does this actually work for my situation?" |
| 3 | "60-day Slack access with weekly office hours" — $497 value | "What if I get stuck on a specific project?" |
| 4 | "The tool stack: 5 tools we use + discount codes (saves ~$1,200/yr)" — $1,200 value | "I don't know what to use" |
| 5 | "Bonus session: How to charge $5K+ per project" — $297 value | Pricing confidence (adjacent dream outcome) |
Total stated value: ~$2,300 in bonuses on a $2K core. Math checks out (under 2x). Each bonus closes a real objection.
"$50,000 in bonuses included today only!" on a $497 product. The asymmetry is the tell — every sophisticated buyer's bullshit detector fires.
Stated values must be defensible. If you can't point to a comparable price, don't quote the value.
If your core offer is "I'll write your sales page for $5K" and your bonus is "PLUS — bonus sales page edits for free for life!" — the bonus implies the core is incomplete. Now the buyer wonders why they should buy without the bonus.
Bonuses should be additive to a complete core, not patches on an incomplete one.
A weak core surrounded by amazing bonuses converts at the moment of sale but produces angry refund requests. The buyer bought the bonuses, got the core, felt cheated.
Order: strong core first, then bonuses to address specific objections.
5+ bonuses with high stated values starts to read as a course-bro funnel. Premium buyers ignore the bonus list entirely; mid-market buyers feel they're being upsold; new buyers get confused.
3–5 bonuses, each with a specific purpose. Cap it.
"BONUS! Private community access!" on every course in your category isn't a bonus, it's table stakes. If every competitor offers the same bonuses, none of them are differentiators.
Find bonuses that are specific to your buyer's situation. A SaaS bonus for a SaaS-focused buyer beats a generic "private community" every time.
A bonus delivered on day 1 closes "what if I never use it?" risk.
A bonus delivered at week 4 maintains momentum.
A bonus delivered at completion rewards finishing.
Mix the timing intentionally:
A buyer who gets all bonuses up-front is more likely to abandon (they got what they wanted, lost incentive to finish). A buyer who gets some bonuses at completion is more likely to finish (and refer).
For each existing bonus on a current offer, ask:
Most stuck offers have either zero bonuses or too many generic ones. The right move is usually: cut to 3–5 specific objection-closing bonuses, name each one clearly, and put defensible values on them.
Anonymized examples drawn from real engagements. Each shows the weak version, the diagnostic, and the strong version.
The offer (as it was):
Fractional CMO services. $15K/month. We'll help you grow.
Diagnostic:
- Dream outcome: 4 (vague — "grow")
- Perceived likelihood: 3 (no methodology, no case studies)
- Time delay: 4 (no timeline, indefinite engagement)
- Effort & sacrifice: 5 (unclear what the buyer has to do)
- Anatomy: only the core is present. No bonuses, no guarantee, no scarcity, no name.
Lowest binding constraint: perceived likelihood. Buyers don't believe an unnamed service will deliver.
| Component | What was added |
|---|---|
| Core | "The 90-Day Marketing Reset" — 8-week audit + 12-week execution plan, delivered by a CMO who's run marketing at 3+ similar-stage companies |
| Bonuses | (1) Weekly 1:1s for 12 weeks (~$12K value); (2) Pre-vetted execution-partner intros (priceless); (3) Board-deck marketing strategy section template |
| Guarantee | "After the 8-week audit, if you don't have a clear 90-day plan you'd run yourself, you don't pay the audit fee." |
| Scarcity | "We take 2 engagements per quarter — next slot opens [date]" |
| Name | "The 90-Day Marketing Reset" |
| Price | $15K → $5K start, $5K week 8, $5K week 16 |
Same delivery, same person, ~3x close rate, longer engagements (because the buyer is clearer about scope).
Lesson: the price didn't move. The structure did.
The offer:
Learn copywriting. $1,997. Includes 6 modules and Slack access.
Diagnostic:
- Dream outcome: 5 ("learn copywriting" — surface ask, not dream outcome)
- Perceived likelihood: 3 (no case studies, no named methodology)
- Time delay: 4 (6-month course, no first-win)
- Effort & sacrifice: 4 (lots of homework, weekly calls, big commitment)
Lowest binding constraint: perceived likelihood. Buyers don't believe THEY can do it.
| Component | What changed |
|---|---|
| Core | "Write sales pages clients pay you $5K+ for in 12 weeks" — outcome-framed |
| Bonuses | (1) 30 winning sales page templates (last updated Q2 2026) — $297 value; (2) 9 named case studies from copywriters in 6 industries — proof, not pitch; (3) 60-day Slack with weekly office hours — $497 value; (4) The tool stack with discount codes — $1,200 value |
| Guarantee | "Complete all 6 modules, submit the final exercise, and if you haven't written a sales page that lands you a $5K+ client within 12 months, refund in full." |
| Scarcity | Cohort scarcity — doors close Friday, next cohort in 3 months |
| Name | "The $5K Sales Page Bootcamp" |
| Price | $1,997 pay-in-full OR $797 × 3 |
Same modules. Same instructor. ~4x conversion. Lower refund rate (conditional guarantee qualifies).
Lesson: rename the outcome, add proof, install a real scarcity mechanic.
The offer:
Notion templates for marketers. $97. 20 templates included.
Diagnostic:
- Dream outcome: 6 (clear what you get, less clear what you achieve with it)
- Perceived likelihood: 6 (templates work for some, less for others — no proof)
- Time delay: 8 (instant access)
- Effort & sacrifice: 5 (setup work to customize each template)
Lowest binding constraint: perceived likelihood + dream outcome. "Will these actually save me time, for my setup?"
| Component | What changed |
|---|---|
| Core | "The Marketing Ops Stack — 20 Notion templates that turn your scattered docs into a working marketing OS in one Saturday" — outcome-framed |
| Bonuses | (1) 10-minute "do this first" Loom — speed bonus; (2) "Stack the templates" flowchart (visual setup map); (3) Lifetime updates as templates are added |
| Guarantee | "30-day no-questions money-back" — unconditional, fits the price point |
| Scarcity | Founding-buyer pricing — $97 for the first 200 buyers, then $147 |
| Name | "The Marketing Ops Stack" |
| Price | $97 pay-in-full |
Same templates. ~2x close rate from the same traffic. The differentiator was the "in one Saturday" outcome anchor and the Loom that proves the speed claim.
Lesson: for low-priced info products, the dream outcome and a fast first-win are the levers. Don't over-engineer the guarantee.
The offer:
Enterprise plan: $50K/year. Includes unlimited users, all features, dedicated support.
Diagnostic:
- Dream outcome: 5 (features-listed, not outcome-framed)
- Perceived likelihood: 5 (no roll-out plan, no time-to-value)
- Time delay: 3 (unclear when value starts; sales says "implementation varies")
- Effort & sacrifice: 4 (procurement + security review + IT integration + change management)
Lowest binding constraint: time delay. Enterprise buyers can't tolerate "implementation varies."
| Component | What changed |
|---|---|
| Core | "Production-ready in 30 days, ROI by quarter end" — time-anchored |
| Bonuses | (1) Dedicated implementation engineer for 30 days; (2) Pre-built integration packs for top 5 platforms; (3) Custom training session for the buyer's team; (4) Quarterly business reviews with the buyer's CSM |
| Guarantee | "Not in production by day 30? You don't pay until you are." SLA-based. |
| Scarcity | Capacity-based: "We onboard 4 enterprise accounts per quarter. Next slot starts [date]." |
| Name | Tier name stayed "Enterprise" but added the engagement name "Strategic Onboarding" |
| Price | $50K annual → $50K annual with quarterly billing + paid 30-day pilot |
Same product. ~30% higher close rate, 50% shorter sales cycle. The pilot + SLA combination removed the procurement objection.
Lesson: for enterprise B2B, time-to-value IS the offer. Solve it explicitly.
The offer:
Group coaching for founders. $4K/quarter. Includes 12 calls and Slack.
Diagnostic:
- Dream outcome: 5 (vague — "be a better founder")
- Perceived likelihood: 4 (one alumni testimonial, no methodology)
- Time delay: 6 (quarterly cadence reasonable)
- Effort & sacrifice: 7 (12 calls is real time)
Lowest binding constraint: dream outcome + perceived likelihood.
| Component | What changed |
|---|---|
| Core | "12 founders, 12 weeks, one specific goal each — and a room that's seen it before" — peer-room positioning |
| Bonuses | (1) 1:1 onboarding call to set the personal goal; (2) Founder Library — 90 frameworks from past members; (3) 1:1 mid-quarter check-in; (4) Alumni access for 1 year after |
| Guarantee | "First two weeks — if it's not the room you wanted, full refund. After that, you're in." |
| Scarcity | Cohort size capped at 12 — once full, you're on the waitlist for next quarter |
| Name | "The Founders' Quarter" |
| Price | $4K/quarter pay-in-full OR $1,500 × 3 |
Same coach, same cadence. Higher close rate. Notably: members renew at ~70% (was ~35% before) because the "alumni access for 1 year" bonus changed the buying decision frame from "quarter" to "year."
Lesson: for coaching, the room IS the offer. Position the room, not the curriculum. Renewal-friendly bonuses lock in long-term LTV.
The offer:
Content marketing retainer. $8K/month. 4 articles per month + SEO strategy.
Diagnostic:
- Dream outcome: 4 (output-described, not outcome-framed)
- Perceived likelihood: 5 (no case studies linking content to revenue)
- Time delay: 3 (SEO is slow; client expectations misaligned)
- Effort & sacrifice: 6 (interviews, reviews, approvals all on client side)
Lowest binding constraint: dream outcome (vague) and time delay (misaligned expectations).
| Component | What changed |
|---|---|
| Core | "We own the content engine. You get organic-driven sales meetings by month 9, with measurable revenue attribution." — outcome + timeline |
| Bonuses | (1) Persona research kickoff (one-time); (2) Quarterly content audit + republish list; (3) Pre-vetted freelance writers with QA layer; (4) Quarterly executive readout |
| Guarantee | "First 30 days is a paid pilot — 4 published pieces + 3 keyword roadmap. If at the end you don't see a clear 12-month path, we end the engagement, no balance owed." |
| Scarcity | Capacity-based: "We take on 3 retainer clients per quarter. Next slot is [date]." |
| Name | Tier name: "Growth Retainer"; engagement name: "The 90-Day Content Reset → 9-Month Growth Engine" |
| Price | $8K/month, 6-month minimum, OR $7K/month for 12-month commit |
Same writers. Same SEO methodology. ~2x close rate. 60% of pilots convert to 12-month commits.
Lesson: for slow-cycle services (SEO, brand, content), the offer has to address the timeline explicitly. "Trust us, results in 6 months" doesn't sell; "paid pilot → milestone at day 30 → ramp" does.
Look at the changes side-by-side:
| Example | Core change | Most important other change |
|---|---|---|
| Fractional CMO | Named it, added scope | First-milestone guarantee |
| Copywriting course | Outcome-framed, added proof | Case studies bonus |
| Notion templates | "in one Saturday" anchor | First-step Loom bonus |
| B2B SaaS | Time-to-value commitment | SLA-based guarantee + pilot |
| Coaching mastermind | Positioned the room, not the coach | 1-year alumni access bonus |
| Agency retainer | Outcome + timeline framing | Paid pilot guarantee |
The pattern: in every case, the price barely moved (or didn't move at all). What moved was the structure of the offer — naming, framing, guaranteeing, sequencing.
The price is the comparison. The value is the offer.
A guarantee directly raises perceived likelihood of achievement (the buyer thinks: "they'll only offer this if they're confident") and lowers effort & sacrifice (less emotional risk). It's one of the highest-leverage levers in offer design.
The wrong guarantee hurts more than no guarantee. Pick the type that matches your business model.
| Type | What it promises | When it works | When it backfires |
|---|---|---|---|
| 1. Unconditional money-back | "Refund anytime within X days, no questions" | Low-priced info, high-trust audience | High-priced/high-touch; refund risk eats margin |
| 2. Conditional money-back | "Refund if you complete X and still don't see Y" | Courses, programs requiring effort | Sophisticated buyers; harder to honor publicly |
| 3. Better-than-money-back | "If it doesn't work, full refund + $X" | Confident delivery, ample margin | If you fail; the few failures explode publicly |
| 4. Service-level / SLA | "If we don't deliver X by Y, your money back" | Productized services, agency work | Vague SLAs you can't measure |
| 5. Performance-based | "Pay only when X happens" (rev share, results-based) | Sophisticated B2B, high-confidence delivery | Long cycles, hard-to-attribute outcomes |
| 6. Anti-guarantee | "No refunds. Make sure you want it." | Premium audiences, mature buyers | Confused / first-time buyers; reads cold |
| 7. Outcome-or-extension | "If you don't get X by Y, we continue free" | Coaching, services with extendable time | Open-ended cost; choose with care |
| 8. Comparison guarantee | "Beat [competitor]'s result or refund" | When you can credibly compare | When you can't measure the competitor cleanly |
Decision tree:
What's your buyer's biggest perceived risk?
- "What if it doesn't work?" → money-back family (1, 2, 3)
- "What if you don't deliver on time?" → SLA (4)
- "What if I pay and get no results?" → performance-based (5) or outcome-or-extension (7)
- "Is this real or scam?" → comparison or specificity-based (8)
What's your refund tolerance?
- Can absorb refunds at scale → unconditional (1)
- Need to qualify refunders → conditional (2)
- Confident enough to add a bonus on top → better-than-money-back (3)
- Can't afford refunds at all → anti-guarantee (6) or no guarantee + strong proof
What's your buyer sophistication?
- Premium / mature buyers → anti-guarantee can work; "we don't do refunds" reads as confidence
- First-time-in-category buyers → strong refund guarantee; they need permission to try
- Sophisticated B2B → SLA or performance-based; they expect commercial terms
How measurable is the outcome?
- Clean and measurable → performance-based, comparison, or outcome-or-extension
- Fuzzy / subjective → money-back family with a conditional gate (you completed the work)
Strong: "Complete all six modules within 60 days, submit the final exercise, and if you haven't [specific outcome] we refund in full." Conditional on effort, clear on outcome.
Weak: "100% money-back guarantee." No conditions = refund magnet for buyers who never engaged.
Strong: "After the first two sessions, if you don't think the engagement will deliver, we end it and refund the unused balance." Mid-engagement off-ramp builds trust.
Weak: "Satisfaction guaranteed." Means nothing.
Strong: "First month is a paid pilot. At the end, if you don't see [specific milestone], you don't pay for month 2 and we end on good terms." Clear gate, clear out.
Weak: "We'll work until you're happy." Open-ended cost. Don't.
Strong (premium audience): "No refunds. The application process is rigorous because the value is real. If you're not sure, don't apply yet." Anti-guarantee works here.
Weak (premium audience): Generic 30-day refund. Reads cheap.
Strong: "30-day no-questions refund." The transactional bar is "I bought it, looked at it, didn't want it." Unconditional fits.
Weak: No guarantee. The buyer's risk is too high for the price.
Strong: Free trial or annual-prepay-with-money-back-in-first-30-days. Reduces friction without locking in unhappy users.
Weak: "Cancel anytime" alone — not a guarantee, just standard SaaS terms.
Strong: Double-your-money-back or comparable risk inversion. Direct-response buyers expect risk-reversal-heavy offers.
Weak: Vanilla 30-day refund. Doesn't differentiate from every other ad on the platform.
The guarantee text matters. Patterns that work:
Specific terms:
If, after completing the first 4 weeks of the program, you can't point to one specific business outcome you've achieved, email us and we'll refund 100%.
Confident tone:
We know this works. If it doesn't for you, we don't want your money.
Acknowledge the awkwardness:
Guarantees feel slimy. Here's ours anyway: if you do the work in modules 1–3 and don't see meaningful traction, we refund.
Patterns that don't work:
"Double your revenue or your money back + $1,000." If even 1 in 50 buyers fails and gets the bonus refund + writes a public review, the offer is permanently damaged.
Stress-test: what happens if 10% of buyers invoke the guarantee?
"Refund if you watched all 24 modules, completed the 6 exercises, attended every live call, and posted in the community at least once per week."
Buyers read this as "they made it impossible to actually get a refund." Trust drops.
Two conditions max. Three only if they're closely related (e.g., "completed the course AND submitted the final project AND emailed us a question").
If your guarantee is your strongest perceived-likelihood lever, put it on the sales page in 24pt text. Move it above the buy button.
Re-read your guarantee text every six months. The wording that worked a year ago may now be undermined by something you've changed about your offer.
Strong proof + weak guarantee > strong guarantee + weak proof. Order matters. Build proof first, then layer on the guarantee.
Anti-guarantees ("no refunds, this is final") work when:
What you're saying: "We don't need a guarantee because the work is real, the buyer has self-qualified, and we won't engage in transactional refund games."
The wrong audience reads this as cold or scammy. The right audience reads it as confidence. Know your buyer.
When auditing an offer with no guarantee (or a weak one), ask:
Most offers don't have the wrong guarantee — they have no guarantee at all. Adding any guarantee is almost always a lift. Adding the right one is the lever.
A complete offer has six components. Skip any one and conversion suffers — usually noticeably.
| # | Component | Question it answers | Where it fails |
|---|---|---|---|
| 1 | Core deliverable | What do they get? | Too vague, or pitched as features instead of outcome |
| 2 | Bonus stack | What else do they get that makes the core feel undervalued? | Either no bonuses, or inflated/fake bonuses |
| 3 | Guarantee | What happens if it doesn't work? | None, wrong type, or over-promising |
| 4 | Scarcity / urgency | Why now, not later? | None, fake, or destructively manipulative |
| 5 | Name | What is this thing called? | Generic, internal-jargon, or no name at all |
| 6 | Price + payment structure | What do they pay and how? | Single number with no payment flexibility |
The thing they actually get.
The features still matter — buyers want to know what they're getting — but the frame is the outcome. Features support the outcome, they don't replace it.
What's in. What's out. What's optional. Buyers buy clarity; ambiguity erodes perceived likelihood.
Example scope statement:
Includes:
- 90-day program with weekly live calls (recorded)
- Private Slack with daily founder access
- 12 fill-in-the-blank templates
- 1 90-minute strategy session with a senior strategist
Doesn't include:
- 1:1 calls outside the strategy session
- Implementation of the work (you/your team does this; we coach)
- Tools and software (you provide; we recommend specific stacks)
Sophisticated buyers want the methodology and scope. New-to-category buyers want the dream outcome and proof. Read your audience.
What you add to make the core feel undervalued at the asking price.
Bonuses do three jobs at once:
1. Raise perceived value of the total offer
2. Lower perceived risk — even if the core underdelivers, "I got X for free"
3. Close specific objections — each bonus can target a different buying objection
For each major objection your buyer has, add a bonus that closes it:
| Objection | Targeted bonus |
|---|---|
| "I don't have time to implement this" | Done-for-you setup, day 1 |
| "I don't know which tools to use" | Pre-vetted tool stack with discount codes |
| "What if I get stuck?" | 30-day async support |
| "I'm not sure my team will buy in" | Stakeholder pitch deck for your team |
| "I've tried something like this before and it didn't work" | Case study of someone in your exact situation |
A 4-bonus stack that closes 4 specific objections converts massively better than a 4-bonus stack of generic "extras."
"$50,000 in bonuses!" on a $500 offer reads as scam. The asymmetry destroys trust.
Bonuses should:
- Have a stated value the buyer can verify (compare to a comparable product)
- Total to less than 2x the price (e.g., a $1K offer can have ~$1.5K in bonuses comfortably)
- Be things you'd actually sell separately if you wanted
For the full bonus-stacking framework, see bonus-stacking.md.
What happens if it doesn't work.
A guarantee directly raises perceived likelihood of achievement (the buyer thinks: "they'll only offer this if they're sure"). It also lowers effort & sacrifice (less emotional risk).
The wrong guarantee can hurt:
- Over-promising guarantees attract refund-seekers
- Generic "100% guaranteed" with no conditions reads as legally unenforceable
- No guarantee at all signals you're not confident
The right type depends on your business model, refund risk tolerance, and buyer sophistication. For the full taxonomy, see guarantee-design.md.
The reason to buy now, not later.
Two flavors:
- Scarcity — limited quantity (cohort size, seats, inventory, batch)
- Urgency — limited time (cohort deadline, season, bonus expiry)
The bar: the scarcity has to be real. Fake countdown timers and "only 3 spots left" lies work once and torch trust permanently. The internet is small; you will be caught.
Common honest scarcity formats:
- Cohort closes Friday (because the cohort actually starts Monday)
- Founding-member pricing for the first 20 customers (because you're capacity-constrained)
- Seasonal product or service (because demand is seasonal)
- Bonus expires at launch end (because the bonus is your time)
- Capacity-based service tier (because you literally can't take more clients)
For full guidance on creating real scarcity, see scarcity-urgency.md.
What this thing is called.
A named offer beats an unnamed offer for three reasons:
1. Repeatability — buyers can tell their friend about it
2. Distinction — a name makes it a thing, not a generic service
3. Pricing power — branded offers can charge more than the same delivery sold as a service
Can a buyer text a friend: "I just signed up for the [name]. It's $X and you get [one-line outcome]"? If yes, the name works. If no, rename.
The price is the obvious part. The structure is the underrated part.
Buyers compare the price to:
- The dream outcome (does this get me the result I want?)
- The next-best alternative (what else could I buy?)
- The cost of doing nothing (what does the status quo cost me?)
- Other items in your own catalog (anchor pricing)
You can move price perception without changing the number by:
- Showing the cost of doing nothing more vividly
- Anchoring against a higher-priced alternative
- Sequencing other items in your catalog at higher prices first
Same total price, different structures convert very differently:
| Structure | When it works | Trade-off |
|---|---|---|
| Pay in full | High-trust buyers, lower price points | Highest perceived commitment, smallest buyer pool |
| Pay in 2-4 installments | Mid-range price, hesitant buyers | More buyers, payment defaults |
| Monthly subscription | SaaS, ongoing services | Annuity revenue, churn risk |
| Pay-after-results | High-confidence delivery, sophisticated buyers | Cash flow lag, fewer disputes |
| Down payment + balance on delivery | Services with milestone-based delivery | Balance risk on backend |
| Free trial → paid | Low-friction SaaS, info products | Conversion drop-off |
Often the right move isn't lowering price — it's adding a payment plan. Same $6K price, "$6K today" vs "$2K × 3 monthly" converts very differently.
A B2B fractional CMO service.
| Component | Weak version | Strong version |
|---|---|---|
| Core | "Fractional CMO services" | "8-week marketing audit + 90-day execution plan, delivered by a CMO who's done it for 3+ similar companies" |
| Bonuses | None | (1) 1:1 weekly check-ins for 90 days; (2) pre-vetted execution-partner introductions; (3) board-deck for marketing strategy section |
| Guarantee | None | "If after the 8-week audit you don't have a clear 90-day plan you'd run yourself, you don't pay the audit fee" |
| Scarcity | None | "We take 2 engagements per quarter — next slot opens [date]" |
| Name | "fCMO Consulting" | "The 90-Day Marketing Reset" |
| Price | "$15K, paid up front" | "$15K → $5K to start, $5K at week 8, $5K at week 16" |
Same delivery. Same person. Different offer. Different conversion.
The point: most "we need to lower our price" conversations are actually "we have one of six components missing or weak" conversations.
The right offer format depends on what you sell. The same six components (core, bonuses, guarantee, scarcity, name, price) get assembled differently by business type.
This reference is organized by business type. Find yours, then use the format as a starting point — not a fixed recipe.
You sell your time and skill.
| Component | Default |
|---|---|
| Core | A scoped engagement with a specific deliverable and timeline |
| Bonuses | Templates, frameworks, post-engagement support, tool stack |
| Guarantee | First-milestone gate (paid pilot or first-deliverable refund) |
| Scarcity | Capacity-based (next slot opens [date]) |
| Name | Methodology-named or outcome-named (e.g., "The 30-Day Activation Sprint") |
| Price | Project-based with down-payment, or monthly retainer |
Move from "I sell consulting" to "I sell the 8-Week Marketing Reset." Same delivery, different offer.
The productized version:
- Has a name
- Has a fixed scope and timeline
- Has a fixed price
- Has the same bonuses every time
- Has a defined gate (week 4 check-in, paid pilot, milestone review)
Productizing raises perceived value, simplifies sales, and creates a repeatable case-study factory.
You sell structured learning.
| Component | Default |
|---|---|
| Core | The curriculum + delivery format |
| Bonuses | Templates, swipe files, case studies, community access |
| Guarantee | Conditional money-back (completion-gated) |
| Scarcity | Cohort scarcity (enrollment closes [date]) |
| Name | Outcome-named or methodology-named |
| Price | Pay-in-full or 2–4 installments |
| Decision | Async | Cohort |
|---|---|---|
| Pricing | Lower ($297–$1,997) | Higher ($1,497–$5,000+) |
| Scarcity | Bonus expiry, price increases | Cohort start date |
| Guarantee | Generous unconditional | Conditional on completion |
| Conversion mechanic | Email funnel, evergreen webinar | Launch window + cohort deadline |
| Default bonus | Templates, swipes | Slack + office hours + 1:1 review |
You sell access to your expertise applied to their specific situation.
| Component | Default |
|---|---|
| Core | Sessions + asynchronous access + specific outcome focus |
| Bonuses | Resources from your library, intro to network, post-engagement check-ins |
| Guarantee | Outcome-or-extension or first-two-sessions out |
| Scarcity | Capacity-based (N spots / quarter) |
| Name | Identity-named or outcome-named (e.g., "Founder Marketing Mastermind") |
| Price | Monthly retainer or 3/6/12-month engagement |
| Decision | 1:1 | Group / mastermind |
|---|---|---|
| Pricing | $1,500–$10,000+/mo | $497–$2,500+/mo |
| Scarcity | Capacity (4–10 1:1 clients) | Cohort size (8–30 members) |
| Guarantee | First-two-sessions out | Trial period, no refunds after |
| Bonuses | Custom resources, intros | Group access, peer accountability, library access |
| Default delivery | Weekly or biweekly sessions | Monthly group calls + community |
You sell packaged knowledge or assets.
| Component | Default |
|---|---|
| Core | The asset(s) + lifetime access |
| Bonuses | Adjacent assets, walkthroughs, templates |
| Guarantee | Generous unconditional (30-day no-questions) |
| Scarcity | Bonus expiry, price-increase scheduling |
| Name | Outcome-named, often punchy and specific |
| Price | $29–$497, pay-in-full |
You sell to companies with a sales conversation.
| Component | Default |
|---|---|
| Core | A multi-month engagement or annual contract |
| Bonuses | Onboarding, training, integration, dedicated CSM |
| Guarantee | SLA, performance-based, or pilot-gated |
| Scarcity | Quarter-end pricing, capacity (N onboardings/quarter), tier limits |
| Name | Internal-stable (e.g., "Enterprise Plan") + named engagement type (e.g., "Strategic Onboarding") |
| Price | Annual contract with quarterly payment, often custom |
You sell ongoing service delivery.
| Component | Default |
|---|---|
| Core | Monthly deliverables + dedicated team + reporting cadence |
| Bonuses | Strategy sessions, tool access, audit credits, library access |
| Guarantee | Month-1 paid pilot or 90-day out clause |
| Scarcity | Capacity (N clients / vertical / quarter) |
| Name | Tier-named ("Growth," "Scale," "Enterprise") + service line |
| Price | Monthly retainer with discount for annual commit |
You sell a tool with tiered subscriptions.
| Component | Default |
|---|---|
| Core | Tiered subscription with clear feature differentiation |
| Bonuses | Free onboarding, templates, integrations, partner discounts |
| Guarantee | Free trial OR annual-with-30-day-refund |
| Scarcity | Founding-pricing for first N customers, or seasonal launches |
| Name | Tier-named ("Starter," "Pro," "Team," "Enterprise") |
| Price | Monthly or annual with discount, value-metric-based |
pricing skill.For SaaS, this skill is supplemental. Read pricing first.
You sell from a sales page or VSL to cold traffic.
| Component | Default |
|---|---|
| Core | The "thing" + clear payoff |
| Bonuses | Heavy bonus stack (5–7 bonuses, layered values) |
| Guarantee | Aggressive risk reversal (better-than-money-back, double guarantee) |
| Scarcity | Real time-bound (launch window, evergreen with hard close) |
| Name | Hooky, often pattern-interrupt |
| Price | Often single-payment with payment plan offered |
This format is high-skill. If you're not from a direct-response background, hire someone or partner with someone who is.
If you're not sure which format applies, pick the closest match and adapt. The biggest mistake is borrowing a format from a different business type (e.g., applying direct-response bonus stacking to a premium B2B service — wrong audience, wrong aesthetic).
Two diagnostic questions:
For worked examples by business type, see examples.md.
The reason to buy now, not later.
This is the most misused offer lever in the industry. Done right, it's a meaningful conversion lift and a respect-the-buyer's-time gesture. Done wrong (fake countdown timers, lies about inventory), it converts once and torches trust permanently.
The repo voice: only ship real scarcity. If the scarcity is fake, take it off the page.
| What it limits | Examples | |
|---|---|---|
| Scarcity | Quantity | Cohort size, seats, inventory, batch, capacity |
| Urgency | Time | Cohort deadline, season, bonus expiry, price increase |
Both work via the same mechanism — they convert "I'll think about it" into "decide now." The difference is what enforces the decision: a limit on how many, or a limit on when.
The bar: the constraint has to be real. Here are the formats that work without lying.
You can only deliver to N customers at a time. The next slot opens when one finishes.
"We take 2 fractional CMO engagements per quarter. Next slot opens September 15."
Works for: services, agencies, coaching, consulting, anything labor-bound.
The class starts on a date. After the date, the door closes until the next cohort.
"Cohort 7 starts October 1. Doors close September 28. Next cohort: January."
Works for: courses, programs, group coaching, anything synchronous.
The first N buyers get a different price. After that, the price goes up.
"Founding pricing — $497/mo for the first 50 members. After we hit 50, the price moves to $797/mo."
Works for: SaaS, communities, memberships. Critical: actually raise the price when you hit 50. Otherwise it was a lie.
You have N units. When they're gone, they're gone.
"We're only producing 100 of the print edition. Sold out, no reprints."
Works for: physical products, limited-run digital, bespoke services.
Demand or capacity is seasonal.
"Tax-prep service for Q1 2026 closes January 15. After that, we focus on existing clients only until April."
Works for: tax, retail Q4, events, education enrollment, anything calendar-bound.
A bonus is available only until X date. The core offer stays the same; the added value expires.
"Order by Friday and the 1:1 onboarding session is included. After Friday, the offer is the same but onboarding is +$497."
Works for: anything with a launch window. Critical: actually remove the bonus when the date hits.
The price goes up on a date. Communicate it transparently.
"On November 1, the program moves from $1,997 to $2,497. Anyone enrolled before November 1 keeps the $1,997 price for life."
Works for: courses, SaaS, communities. Builds credibility because the buyer can verify it later.
Pattern-match and rip these off your page:
The timer hits 0:00 and refreshes. The buyer comes back tomorrow, same timer, same urgency. Every buyer who notices loses trust.
If you use a countdown, it ends on a real date. After that date, the discount or bonus actually ends — verifiably.
Especially on digital products where there's no capacity constraint. Especially when the number stays at "3" for weeks.
Use this only when the constraint is real (cohort, capacity, inventory) AND when the number reflects reality.
"127 people are looking at this page right now."
These can be honest on some platforms (Booking.com etc.) when they reflect actual traffic. They're dishonest when fabricated. Buyers increasingly assume fabrication.
"This bonus expires at midnight!" — but every page on the site says the same thing at midnight every night.
The bonus has to actually expire, or the line is a lie.
Repeated "FINAL HOURS" emails that send weekly. Every recipient who notices unsubscribes or stops opening.
Use "last chance" once. If you use it multiple times, you've taught your list that "last chance" is meaningless.
Buyers compare notes. The internet is small.
Real scarcity converts ~the same as fake scarcity at the moment of purchase. The difference shows up at month 6, when fake-scarcity offers are facing trust collapse and real-scarcity offers are still compounding.
If you have to fake it, you don't have an offer-design problem — you have a value-equation problem. Go back to value-equation.md.
Some offers don't need scarcity:
Don't force scarcity into offers that don't need it. The forced version is worse than no scarcity.
For an existing offer with weak or no scarcity:
If you can't find a real constraint, don't ship scarcity. The "trick" of fake scarcity is one of the most expensive shortcuts in marketing. The honest version is usually cheaper than people think — every business has some real constraint (capacity, calendar, batch, attention).
Scarcity is the final lever. It only works if the rest of the offer is strong.
If conversions are bad, scarcity is rarely the first thing to fix. Run the diagnostic from value-equation.md first.
The order is:
1. Strong dream outcome
2. Specific perceived likelihood (proof + methodology + guarantee)
3. Compressed time delay
4. Reduced effort & sacrifice
5. Then scarcity to get the decision now
Scarcity is the close, not the offer.
The single most useful frame for offer design. Originated in Alex Hormozi's $100M Offers; the underlying idea (multiply benefits, divide costs) is much older — direct-response copywriters have been doing it for a century.
Dream Outcome × Perceived Likelihood of Achievement
Value = ─────────────────────────────────────────────────────────
Time Delay × Effort & Sacrifice
The customer compares the Value score to the Price. If Value > Price, they buy. If not, they don't, no matter how good the copy is.
Price is the comparison, not the value. Most "lower the price" requests are actually "raise the numerator or lower the denominator" requests.
What the customer actually wants — usually one or two levels above the surface ask.
| Surface ask | Dream outcome |
|---|---|
| "I want a website" | "I want more qualified leads I can close" |
| "I want to learn copywriting" | "I want to write copy clients pay me $5K+ per project for" |
| "I want a meal plan" | "I want to feel confident in a swimsuit on a beach in 12 weeks" |
| "I want fitness coaching" | "I want my back pain gone so I can pick up my kids without thinking about it" |
| "I want a Notion template" | "I want to feel in control of my work for the first time in years" |
| "I want to lower CAC" | "I want a marketing engine I can step away from for two weeks without things breaking" |
Pitching the surface ask. ("Get a website" instead of "get a website that brings you 5 qualified leads a week.") The bigger the buyer's pain, the more important this is — they're not buying a deliverable, they're buying a future.
Do they actually believe they'll get the dream outcome? This is the single most underweighted lever — most offers are perfectly fine on the dream outcome side but the buyer just doesn't think it'll work for them.
Stacking more features ("we also include X, Y, Z") instead of stacking more proof. Features address dream outcome. Proof addresses likelihood. Most stuck offers need proof, not features.
How long from purchase to result. The denominator is doing a lot of work here — slow results don't just feel slow, they erode perceived likelihood (the longer it takes, the less the buyer believes it'll work).
Promising a faster timeline than you can deliver. The first time you miss it, perceived likelihood for every future buyer drops permanently as the failure story spreads.
What the buyer pays besides money — time, learning curve, decisions, willpower, social risk, opportunity cost.
Overestimating how much your buyer enjoys the work. They want the outcome, not the process. (Exception: identity-buyers — fitness, learning, mastery. For those, the process is part of the dream outcome. Read your buyer.)
When an offer is stuck, score each lever 1–10 honestly. The lowest is the binding constraint.
Initial scoring:
- Dream outcome: 6 (become a better copywriter — too vague)
- Perceived likelihood: 4 (one testimonial, no methodology name)
- Time delay: 5 (6-month course, no first-win mechanic)
- Effort & sacrifice: 4 (lots of homework, live calls, weekly assignments)
Lowest: effort & sacrifice and perceived likelihood are tied. Pick one (perceived likelihood — easier to move and unblocks more downstream work):
After: perceived likelihood goes 4 → 8. Course converts at ~3x baseline. Two months later, attack effort & sacrifice (replace weekly live calls with async + 1 live Q&A).
The price-vs-value comparison happens in the buyer's head, not yours. You only know it's working when the buyer can articulate the dream outcome back to you in their own words, and when they don't need to ask "but does this actually work?"
If they're asking either of those questions, you have a value equation problem, not a copy problem.
When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increase,' 'value metric,' '
View source ↗You are an expert in SaaS pricing and monetization strategy. Your goal is to help design pricing that captures value, drives growth, and aligns with customer willingness to pay.
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. Packaging — What's included at each tier?
- Features, limits, support level
- How tiers differ from each other
2. Pricing Metric — What do you charge for?
- Per user, per usage, flat fee
- How price scales with value
3. Price Point — How much do you charge?
- The actual dollar amounts
- Perceived value vs. cost
Price should be based on value delivered, not cost to serve:
Key insight: Price between the next best alternative and perceived value.
The value metric is what you charge for—it should scale with the value customers receive.
Good value metrics:
- Align price with value delivered
- Are easy to understand
- Scale as customer grows
- Are hard to game
| Metric | Best For | Example |
|---|---|---|
| Per user/seat | Collaboration tools | Slack, Notion |
| Per usage | Variable consumption | AWS, Twilio |
| Per feature | Modular products | HubSpot add-ons |
| Per contact/record | CRM, email tools | Mailchimp |
| Per transaction | Payments, marketplaces | Stripe |
| Flat fee | Simple products | Basecamp |
Ask: "As a customer uses more of [metric], do they get more value?"
- If yes → good value metric
- If no → price doesn't align with value
Good tier (Entry): Core features, limited usage, low price
Better tier (Recommended): Full features, reasonable limits, anchor price
Best tier (Premium): Everything, advanced features, 2-3x Better price
For detailed tier structures and persona-based packaging: See references/tier-structure.md
Four questions that identify acceptable price range:
1. Too expensive (wouldn't consider)
2. Too cheap (question quality)
3. Expensive but might consider
4. A bargain
Analyze intersections to find optimal pricing zone.
Identifies which features customers value most:
- Show sets of features
- Ask: Most important? Least important?
- Results inform tier packaging
For detailed research methods: See references/research-methods.md
Market signals:
- Competitors have raised prices
- Prospects don't flinch at price
- "It's so cheap!" feedback
Business signals:
- Very high conversion rates (>40%)
- Very low churn (<3% monthly)
- Strong unit economics
Product signals:
- Significant value added since last pricing
- Product more mature/stable
The Van Westendorp survey identifies the acceptable price range for your product.
Ask each respondent:
1. "At what price would you consider [product] to be so expensive that you would not consider buying it?" (Too expensive)
2. "At what price would you consider [product] to be priced so low that you would question its quality?" (Too cheap)
3. "At what price would you consider [product] to be starting to get expensive, but you still might consider it?" (Expensive/high side)
4. "At what price would you consider [product] to be a bargain—a great buy for the money?" (Cheap/good value)
The acceptable price range: PMC to PME
Optimal pricing zone: Between OPP and IDP
Price Sensitivity Analysis Results:
─────────────────────────────────
Point of Marginal Cheapness: $29/mo
Optimal Price Point: $49/mo
Indifference Price Point: $59/mo
Point of Marginal Expensiveness: $79/mo
Recommended range: $49-59/mo
Current price: $39/mo (below optimal)
Opportunity: 25-50% price increase without significant demand impact
MaxDiff identifies which features customers value most, informing packaging decisions.
Which feature is MOST important to you?
Which feature is LEAST important to you?
□ Unlimited projects
□ Custom branding
□ Priority support
□ API access
□ Advanced analytics
Features are ranked by utility score:
- High utility = Must-have (include in base tier)
- Medium utility = Differentiator (use for tier separation)
- Low utility = Nice-to-have (premium tier or cut)
| Utility Score | Packaging Decision |
|---|---|
| Top 20% | Include in all tiers (table stakes) |
| 20-50% | Use to differentiate tiers |
| 50-80% | Higher tiers only |
| Bottom 20% | Consider cutting or premium add-on |
Direct method (simple but biased):
"How much would you pay for [product]?"
Better: Gabor-Granger method:
"Would you buy [product] at [$X]?" (Yes/No)
Vary price across respondents to build demand curve.
Even better: Conjoint analysis:
Show product bundles at different prices
Respondents choose preferred option
Statistical analysis reveals price sensitivity per feature
Track how customers use your product:
- Feature usage frequency
- Volume metrics (users, records, API calls)
- Outcome metrics (revenue generated, time saved)
Usage-Value Correlation Analysis:
─────────────────────────────────
Segment: High-LTV customers (>$10k ARR)
Average monthly active users: 15
Average projects: 8
Average integrations: 4
Segment: Churned customers
Average monthly active users: 3
Average projects: 2
Average integrations: 0
Insight: Value correlates with team adoption (users)
and depth of use (integrations)
Recommendation: Price per user, gate integrations to higher tiers
2 tiers: Simple, clear choice
- Works for: Clear SMB vs. Enterprise split
- Risk: May leave money on table
3 tiers: Industry standard
- Good tier = Entry point
- Better tier = Recommended (anchor to best)
- Best tier = High-value customers
4+ tiers: More granularity
- Works for: Wide range of customer sizes
- Risk: Decision paralysis, complexity
Good tier (Entry):
- Purpose: Remove barriers to entry
- Includes: Core features, limited usage
- Price: Low, accessible
- Target: Small teams, try before you buy
Better tier (Recommended):
- Purpose: Where most customers land
- Includes: Full features, reasonable limits
- Price: Your "anchor" price
- Target: Growing teams, serious users
Best tier (Premium):
- Purpose: Capture high-value customers
- Includes: Everything, advanced features, higher limits
- Price: Premium (often 2-3x "Better")
- Target: Larger teams, power users, enterprises
Feature gating:
- Basic features in all tiers
- Advanced features in higher tiers
- Works when features have clear value differences
Usage limits:
- Same features, different limits
- More users, storage, API calls at higher tiers
- Works when value scales with usage
Support level:
- Email support → Priority support → Dedicated success
- Works for products with implementation complexity
Access and customization:
- API access, SSO, custom branding
- Works for enterprise differentiation
┌────────────────┬─────────────────┬─────────────────┬─────────────────┐
│ │ Starter │ Pro │ Business │
│ │ $29/mo │ $79/mo │ $199/mo │
├────────────────┼─────────────────┼─────────────────┼─────────────────┤
│ Users │ Up to 5 │ Up to 20 │ Unlimited │
│ Projects │ 10 │ Unlimited │ Unlimited │
│ Storage │ 5 GB │ 50 GB │ 500 GB │
│ Integrations │ 3 │ 10 │ Unlimited │
│ Analytics │ Basic │ Advanced │ Custom │
│ Support │ Email │ Priority │ Dedicated │
│ API Access │ ✗ │ ✓ │ ✓ │
│ SSO │ ✗ │ ✗ │ ✓ │
│ Audit logs │ ✗ │ ✗ │ ✓ │
└────────────────┴─────────────────┴─────────────────┴─────────────────┘
Different customers have different:
- Willingness to pay
- Feature needs
- Buying processes
- Value perception
Segment by:
- Company size (solopreneur → SMB → enterprise)
- Use case (marketing vs. sales vs. support)
- Sophistication (beginner → power user)
- Industry (different budget norms)
Step 1: Define personas
| Persona | Size | Needs | WTP | Example |
|---|---|---|---|---|
| Freelancer | 1 person | Basic features | Low | $19/mo |
| Small Team | 2-10 | Collaboration | Medium | $49/mo |
| Growing Co | 10-50 | Scale, integrations | Higher | $149/mo |
| Enterprise | 50+ | Security, support | High | Custom |
Step 2: Map features to personas
| Feature | Freelancer | Small Team | Growing | Enterprise |
|---|---|---|---|---|
| Core features | ✓ | ✓ | ✓ | ✓ |
| Collaboration | — | ✓ | ✓ | ✓ |
| Integrations | — | Limited | Full | Full |
| API access | — | — | ✓ | ✓ |
| SSO/SAML | — | — | — | ✓ |
| Audit logs | — | — | — | ✓ |
| Custom contract | — | — | — | ✓ |
Step 3: Price to value for each persona
- Research willingness to pay per segment
- Set prices that capture value without blocking adoption
- Consider segment-specific landing pages
Freemium works when:
- Product has viral/network effects
- Free users provide value (content, data, referrals)
- Large market where % conversion drives volume
- Low marginal cost to serve free users
- Clear feature/usage limits for upgrade trigger
Freemium risks:
- Free users may never convert
- Devalues product perception
- Support costs for non-paying users
- Harder to raise prices later
Free trial works when:
- Product needs time to demonstrate value
- Onboarding/setup investment required
- B2B with buying committees
- Higher price points
- Product is "sticky" once configured
Trial best practices:
- 7-14 days for simple products
- 14-30 days for complex products
- Full access (not feature-limited)
- Clear countdown and reminders
- Credit card optional vs. required trade-off
Credit card upfront:
- Higher trial-to-paid conversion (40-50% vs. 15-25%)
- Lower trial volume
- Better qualified leads
Freemium + Trial:
- Free tier with limited features
- Trial of premium features
- Example: Zoom (free 40-min, trial of Pro)
Reverse trial:
- Start with full access
- After trial, downgrade to free tier
- Example: See premium value, live with limitations until ready
Add "Contact Sales" when:
- Deal sizes exceed $10k+ ARR
- Customers need custom contracts
- Implementation/onboarding required
- Security/compliance requirements
- Procurement processes involved
Table stakes:
- SSO/SAML
- Audit logs
- Admin controls
- Uptime SLA
- Security certifications
Value-adds:
- Dedicated support/success
- Custom onboarding
- Training sessions
- Custom integrations
- Priority roadmap input
Per-seat at scale:
- Volume discounts for large teams
- Example: $15/user (standard) → $10/user (100+)
Platform fee + usage:
- Base fee for access
- Usage-based above thresholds
- Example: $500/mo base + $0.01 per API call
Value-based contracts:
- Price tied to customer's revenue/outcomes
- Example: % of transactions, revenue share
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,' 'generati
View source ↗You are an expert in AI search optimization — the practice of making content discoverable, extractable, and citable by AI systems including Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, and Copilot. Your goal is to help users get their content cited as a source in AI-generated answers.
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):
| Platform | How It Works | Source Selection |
|---|---|---|
| Google AI Overviews | Summarizes top-ranking pages | Strong correlation with traditional rankings |
| ChatGPT (with search) | Searches web, cites sources | Draws from wider range, not just top-ranked |
| Perplexity | Always cites sources with links | Favors authoritative, recent, well-structured content |
| Gemini | Google's AI assistant | Pulls from Google index + Knowledge Graph |
| Copilot | Bing-powered AI search | Bing index + authoritative sources |
| Claude | Brave Search (when enabled) | Training data + Brave search results |
For a deep dive on how each platform selects sources and what to optimize per platform, see references/platform-ranking-factors.md.
Traditional SEO gets you ranked. AI SEO gets you cited.
In traditional search, you need to rank on page 1. In AI search, a well-structured page can get cited even if it ranks on page 2 or 3 — AI systems select sources based on content quality, structure, and relevance, not just rank position.
Critical stats:
- AI Overviews appear in ~45% of Google searches
- AI Overviews reduce clicks to websites by up to 58%
- Brands are 6.5x more likely to be cited via third-party sources than their own domains
- Optimized content gets cited 3x more often than non-optimized
- Statistics and citations boost visibility by 40%+ across queries
This is important to read once before doing anything else.
Google's position (AI features 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.
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.
Before optimizing, assess your current AI search presence.
Test 10-20 of your most important queries across platforms:
| Query | Google AI Overview | ChatGPT | Perplexity | You Cited? | Competitors Cited? |
|---|---|---|---|---|---|
| [query 1] | Yes/No | Yes/No | Yes/No | Yes/No | [who] |
| [query 2] | Yes/No | Yes/No | Yes/No | Yes/No | [who] |
Query types to test:
- "What is [your product category]?"
- "Best [product category] for [use case]"
- "[Your brand] vs [competitor]"
- "How to [problem your product solves]"
- "[Your product category] pricing"
When your competitors get cited and you don't, examine:
- Content structure — Is their content more extractable?
- Authority signals — Do they have more citations, stats, expert quotes?
- Freshness — Is their content more recently updated?
- Schema markup — Do they have structured data you're missing?
- Third-party presence — Are they cited via Wikipedia, Reddit, review sites?
For each priority page, verify:
| Check | Pass/Fail |
|---|---|
| Clear definition in first paragraph? | |
| Self-contained answer blocks (work without surrounding context)? | |
| Statistics with sources cited? | |
| Comparison tables for "[X] vs [Y]" queries? | |
| FAQ section with natural-language questions? | |
| Schema markup (FAQ, HowTo, Article, Product)? | |
| Expert attribution (author name, credentials)? | |
| Recently updated (within 6 months)? | |
| Heading structure matches query patterns? | |
| AI bots allowed in robots.txt? |
Verify your robots.txt allows AI crawlers. Each AI platform has its own bot, and blocking it means that platform can't cite you:
Check your robots.txt for Disallow rules targeting any of these. If you find them blocked, you have a business decision to make: blocking prevents AI training on your content but also prevents citation. One middle ground is blocking training-only crawlers (like CCBot from Common Crawl) while allowing the search bots listed above.
See references/platform-ranking-factors.md for the full robots.txt configuration.
1. Structure (make it extractable)
2. Authority (make it citable)
3. Presence (be where AI looks)
AI systems extract passages, not pages. Every key claim should work as a standalone statement.
Content block patterns:
- Definition blocks for "What is X?" queries
- Step-by-step blocks for "How to X" queries
- Comparison tables for "X vs Y" queries
- Pros/cons blocks for evaluation queries
- FAQ blocks for common questions
- Statistic blocks with cited sources
For detailed templates for each block type, see references/content-patterns.md.
Structural rules:
- Lead every section with a direct answer (don't bury it)
- Keep key answer passages to 40-60 words (optimal for snippet extraction)
- Use H2/H3 headings that match how people phrase queries
- Tables beat prose for comparison content
- Numbered lists beat paragraphs for process content
- Each paragraph should convey one clear idea
AI systems prefer sources they can trust. Build citation-worthiness.
The Princeton GEO research (KDD 2024, studied across Perplexity.ai) ranked 9 optimization methods:
| Method | Visibility Boost | How to Apply |
|---|---|---|
| Cite sources | +40% | Add authoritative references with links |
| Add statistics | +37% | Include specific numbers with sources |
| Add quotations | +30% | Expert quotes with name and title |
| Authoritative tone | +25% | Write with demonstrated expertise |
| Improve clarity | +20% | Simplify complex concepts |
| Technical terms | +18% | Use domain-specific terminology |
| Unique vocabulary | +15% | Increase word diversity |
| Fluency optimization | +15-30% | Improve readability and flow |
| ~~Keyword stuffing~~ | -10% | Actively hurts AI visibility |
Best combination: Fluency + Statistics = maximum boost. Low-ranking sites benefit even more — up to 115% visibility increase with citations.
Statistics and data (+37-40% citation boost)
- Include specific numbers with sources
- Cite original research, not summaries of research
- Add dates to all statistics
- Original data beats aggregated data
Expert attribution (+25-30% citation boost)
- Named authors with credentials
- Expert quotes with titles and organizations
- "According to [Source]" framing for claims
- Author bios with relevant expertise
Freshness signals
- "Last updated: [date]" prominently displayed
- Regular content refreshes (quarterly minimum for competitive topics)
- Current year references and recent statistics
- Remove or update outdated information
E-E-A-T alignment
- First-hand experience demonstrated
- Specific, detailed information (not generic)
- Transparent sourcing and methodology
- Clear author expertise for the topic
AI systems don't just cite your website — they cite where you appear.
Third-party sources matter more than your own site:
- Wikipedia mentions (7.8% of all ChatGPT citations)
- Reddit discussions (1.8% of ChatGPT citations)
- Industry publications and guest posts
- Review sites (G2, Capterra, TrustRadius for B2B SaaS)
- YouTube (frequently cited by Google AI Overviews)
- Quora answers
Actions:
- Ensure your Wikipedia page is accurate and current
- Participate authentically in Reddit communities
- Get featured in industry roundups and comparison articles
- Maintain updated profiles on relevant review platforms
- Create YouTube content for key how-to queries
- Answer relevant Quora questions with depth
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:
/pricing.md or /pricing.txt — Structured pricing data for AI agents
# Pricing — [Your Product Name]
## Free
- Price: $0/month
- Limits: 100 emails/month, 1 user
- Features: Basic templates, API access
## Pro
- Price: $29/month (billed annually) | $35/month (billed monthly)
- Limits: 10,000 emails/month, 5 users
- Features: Custom domains, analytics, priority support
## Enterprise
- Price: Custom — contact sales@example.com
- Limits: Unlimited emails, unlimited users
- Features: SSO, SLA, dedicated account manager
Why this matters now:
- AI agents increasingly compare products programmatically before a human ever visits your site
- Opaque pricing gets filtered out of AI-mediated buying journeys
- A simple markdown file is trivially parseable by any LLM — no rendering, no JavaScript, no login walls
- Same principle as robots.txt (for crawlers), llms.txt (for AI context), and AGENTS.md (for agent capabilities)
Best practices:
- Use consistent units (monthly vs. annual, per-seat vs. flat)
- Include specific limits and thresholds, not just feature names
- List what's included at each tier, not just what's different
- Keep it updated — stale pricing is worse than no file
- Link to it from your sitemap and main pricing page
/llms.txt — Context file for AI systems (see llmstxt.org)
If you don't have one yet, add an llms.txt that gives AI systems a quick overview of what your product does, who it's for, and links to key pages (including your pricing).
/okf/ — Open Knowledge Format bundle (Google-backed, v0.1)
Google introduced OKF in June 2026 — a markdown spec for representing site content as a directory of cross-linked files with YAML frontmatter, agent-readable without scraping. Built primarily for data-team catalog metadata; the site-readable-by-agents repurposing was popularized by Suganthan Mohanadasan. No confirmed AI-search ranking signal today — treat it as protocol-layer registration like early schema.org. For the full breakdown, implementation paths (free generator, WordPress plugin, by-hand), hosting guidance, and when to skip, see references/okf.md.
Structured data helps AI systems understand your content. Key schemas:
| Content Type | Schema | Why It Helps |
|---|---|---|
| Articles/Blog posts | Article, BlogPosting |
Author, date, topic identification |
| How-to content | HowTo |
Step extraction for process queries |
| FAQs | FAQPage |
Direct Q&A extraction |
| Products | Product |
Pricing, features, reviews |
| Comparisons | ItemList |
Structured comparison data |
| Reviews | Review, AggregateRating |
Trust signals |
| Organization | Organization |
Entity recognition |
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.
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)
Not all content is equally citable. Prioritize these formats:
| Content Type | Citation Share | Why AI Cites It |
|---|---|---|
| Comparison articles | ~33% | Structured, balanced, high-intent |
| Definitive guides | ~15% | Comprehensive, authoritative |
| Original research/data | ~12% | Unique, citable statistics |
| Best-of/listicles | ~10% | Clear structure, entity-rich |
| Product pages | ~10% | Specific details AI can extract |
| How-to guides | ~8% | Step-by-step structure |
| Opinion/analysis | ~10% | Expert perspective, quotable |
Underperformers for AI citation:
- Generic blog posts without structure
- Thin product pages with marketing fluff
- Gated content (AI can't access it)
- Content without dates or author attribution
- PDF-only content (harder for AI to parse)
Citation ≠ recommendation. Getting cited means your content was useful to consult; getting recommended — onto the buyer's actual shortlist — is governed by web-wide consensus (reviews, forums, analysts, press) and is largely independent of your own content. Self-promotional "best [category]" listicles can even backfire for emerging brands: in one 100-query B2B study, 69% of the AI Overview citations that self-promotional listicles earned came in answers that recommended competitors instead of the publishing brand. See references/citations-vs-recommendations.md for the visibility ladder (retrieved → cited → mentioned → recommended), stage-dependent buyer's-guide strategy, what earns recommendations, and the attribution blind spot.
| Metric | What It Measures | How to Check |
|---|---|---|
| AI Overview presence | Do AI Overviews appear for your queries? | Manual check or Semrush/Ahrefs |
| Brand citation rate | How often you're cited in AI answers | AI visibility tools (see below) |
| Share of AI voice | Your citations vs. competitors | Peec AI, Otterly, ZipTie |
| Citation sentiment | How AI describes your brand | Manual review + monitoring tools |
| Recommendation rate | Whether you're on the shortlist, not just cited (see citations-vs-recommendations.md) | Prompt tracking + mention framing |
| Source attribution | Which of your pages get cited | Track referral traffic from AI sources |
| Tool | Coverage | Best For |
|---|---|---|
| Otterly AI | ChatGPT, Perplexity, Google AI Overviews | Share of AI voice tracking |
| Peec AI | ChatGPT, Gemini, Perplexity, Claude, Copilot+ | Multi-platform monitoring at scale |
| ZipTie | Google AI Overviews, ChatGPT, Perplexity | Brand mention + sentiment tracking |
| LLMrefs | ChatGPT, Perplexity, AI Overviews, Gemini | SEO keyword → AI visibility mapping |
Monthly manual check:
1. Pick your top 20 queries
2. Run each through ChatGPT, Perplexity, and Google
3. Record: Are you cited? Who is? What page?
4. Log in a spreadsheet, track month-over-month
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.
Google's guide calls these out explicitly — they hurt across both traditional Search and AI features.
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.
/pricing.md fileFor implementation, see the tools registry.
| Tool | Use For |
|---|---|
semrush |
AI Overview tracking, keyword research, content gap analysis |
ahrefs |
Backlink analysis, content explorer, AI Overview data |
gsc |
Search Console performance data, query tracking |
ga4 |
Referral traffic from AI sources |
Being cited by an AI engine and being recommended by it are two different outcomes governed by two different systems. A citation means your page was useful enough to pull information from. A recommendation means the model put your brand on the buyer's shortlist. Optimizing for the first does not automatically earn the second — and for smaller brands, conflating them leads to content strategies that can actively help competitors.
Source note: the analysis and data in this reference draw on Lily Ray's (Amsive) 2026 study of B2B "best [category] software" queries, behavioral studies by Scrunch and SimilarWeb, and commentary by John-Henry Scherck (Growth Plays).
AI visibility is a ladder, not a binary. Each rung has different selection criteria and different measurement:
| Rung | What it means | What governs it | How to see it |
|---|---|---|---|
| 1. Retrieved | The model read your content while building its answer, without citing it | Crawlability, parseable structure, query relevance | Mostly invisible; bot logs hint at it |
| 2. Cited | Your page appears as a source in the answer | Content usefulness: structure, statistics, clarity, freshness | Prompt-tracking tools, AI Overview source lists |
| 3. Mentioned | Your brand is named in the answer text | Entity recognition + how the web talks about you | Prompt-tracking tools |
| 4. Recommended | Your product is on the shortlist the buyer actually considers | Aggregate web consensus — reviews, forums, analysts, press, video — largely independent of your own content | Prompt tracking + the framing around the mention |
Rungs 1–3 are legitimate signals your content is working, and most prompt-tracking tools report them. But rung 4 is where buying behavior changes, and it's earned differently: citation is about whether your content is useful to consult; recommendation is mostly a reflection of what the broader web says about you — whether you published a guide on the topic or not.
There is also a shadow rung: recommended against. On detailed, requirements-heavy prompts, models increasingly name products a buyer should avoid for their use case, with sources. The downside of weak third-party consensus is no longer just absence from the shortlist — it can be an explicit rule-out. This makes monitoring the framing around your mentions (favorable / neutral / hedged / negative), not just counting them, part of the job.
The common tactic — publish a "best [category] software" guide, rank yourself #1, and let it shape both organic search and AI answers — now has a stage-dependent payoff.
The data: Lily Ray (Amsive) analyzed 100 B2B "best [category] software" queries across three dates in spring 2026. Across the dataset, self-promotional listicles earned 323 citations in AI Overviews — and in 224 of them (69% of the citations), the answer left the publishing brand out of the recommendations, pointing buyers to competitors instead.
The mechanism: the model treats your guide as a source about the category. It happily extracts the competitor names, comparisons, and evaluation criteria you compiled — then makes its recommendation from web-wide consensus, where the established players dominate. For an emerging brand, a self-promotional buyer's guide can function as a vote for your competitors: you did the research that helps the model describe them.
The split by stage:
What this changes (and doesn't): genuinely useful buyer's guides still belong in a B2B content strategy at any stage. What changes is the expectation and the investment split. If you're not yet the consensus pick, weight effort toward the offsite signals that actually govern recommendations (below) rather than publishing a plethora of self-ranked listicles.
Recommendation is a consensus signal. The inputs the models weigh live mostly off your site:
| Channel | Why it moves recommendations | Related skill |
|---|---|---|
| Review platforms (G2, Capterra, TrustRadius, app stores) | Third-party validation models treat as evidence of legitimacy | customer-research (review generation loops) |
| Analyst coverage (Gartner, Forrester, industry reports) | High-authority category framing; models echo analyst shortlists | public-relations |
| Communities and forums (Reddit, HN, Slack/Discord, niche forums) | Unprompted practitioner discussion is heavily retrieved and hard to fake | community-marketing |
| Earned media and PR | Independent sources repeating your positioning beyond your own site | public-relations |
| Video and podcasts | Increasingly retrieved; transcripts carry brand + category associations | video, social |
The test to apply before investing in another self-ranked guide: if a model ignored everything on our domain, would the rest of the web still put us on the shortlist? If not, that gap is the priority. AEO discourse often stops at "are we in the answer?" — the better question is "are we credible enough to be recommended?"
The encouraging flip side: earning an AI recommendation is harder to game than a top search ranking ever was. The durable strategy is the same at every stage — be the best fit for a clear set of buyers, and give those buyers reasons to talk about you in public, where the models can retrieve it.
Two behavioral studies quantified the gap between rungs:
The attribution blind spot: in the SimilarWeb data, only about 9% of those post-recommendation visits arrived as visible AI referral traffic; the largest share arrived via branded search, with direct and other channels making up the rest — indistinguishable from ordinary organic visitors. AI recommendations are already sending real, engaged buyers, but standard attribution underreports the AI touch.
Measurement triad (no single signal is complete; together they give a reliable read):
Also watch branded search volume as a proxy: sustained lifts without a matching campaign are increasingly AI-influence showing up under another name.
Reusable content block patterns optimized for answer engines and AI citation.
These patterns help content appear in featured snippets, AI Overviews, voice search results, and answer boxes.
Use for "What is [X]?" queries.
## What is [Term]?
[Term] is [concise 1-sentence definition]. [Expanded 1-2 sentence explanation with key characteristics]. [Brief context on why it matters or how it's used].
Example:
## What is Answer Engine Optimization?
Answer Engine Optimization (AEO) is the practice of structuring content so AI-powered systems can easily extract and present it as direct answers to user queries. Unlike traditional SEO that focuses on ranking in search results, AEO optimizes for featured snippets, AI Overviews, and voice assistant responses. This approach has become essential as over 60% of Google searches now end without a click.
Use for "How to [X]" queries. Optimal for list snippets.
## How to [Action/Goal]
[1-sentence overview of the process]
1. **[Step Name]**: [Clear action description in 1-2 sentences]
2. **[Step Name]**: [Clear action description in 1-2 sentences]
3. **[Step Name]**: [Clear action description in 1-2 sentences]
4. **[Step Name]**: [Clear action description in 1-2 sentences]
5. **[Step Name]**: [Clear action description in 1-2 sentences]
[Optional: Brief note on expected outcome or time estimate]
Example:
## How to Optimize Content for Featured Snippets
Earning featured snippets requires strategic formatting and direct answers to search queries.
1. **Identify snippet opportunities**: Use tools like Semrush or Ahrefs to find keywords where competitors have snippets you could capture.
2. **Match the snippet format**: Analyze whether the current snippet is a paragraph, list, or table, and format your content accordingly.
3. **Answer the question directly**: Provide a clear, concise answer (40-60 words for paragraph snippets) immediately after the question heading.
4. **Add supporting context**: Expand on your answer with examples, data, and expert insights in the following paragraphs.
5. **Use proper heading structure**: Place your target question as an H2 or H3, with the answer immediately following.
Most featured snippets appear within 2-4 weeks of publishing well-optimized content.
Use for "[X] vs [Y]" queries. Optimal for table snippets.
## [Option A] vs [Option B]: [Brief Descriptor]
| Feature | [Option A] | [Option B] |
|---------|------------|------------|
| [Criteria 1] | [Value/Description] | [Value/Description] |
| [Criteria 2] | [Value/Description] | [Value/Description] |
| [Criteria 3] | [Value/Description] | [Value/Description] |
| [Criteria 4] | [Value/Description] | [Value/Description] |
| Best For | [Use case] | [Use case] |
**Bottom line**: [1-2 sentence recommendation based on different needs]
Use for evaluation queries: "Is [X] worth it?", "Should I [X]?"
## Advantages and Disadvantages of [Topic]
[1-sentence overview of the evaluation context]
### Pros
- **[Benefit category]**: [Specific explanation]
- **[Benefit category]**: [Specific explanation]
- **[Benefit category]**: [Specific explanation]
### Cons
- **[Drawback category]**: [Specific explanation]
- **[Drawback category]**: [Specific explanation]
- **[Drawback category]**: [Specific explanation]
**Verdict**: [1-2 sentence balanced conclusion with recommendation]
Use for topic pages with multiple common questions. Essential for FAQ schema.
## Frequently Asked Questions
### [Question phrased exactly as users search]?
[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences].
### [Question phrased exactly as users search]?
[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences].
### [Question phrased exactly as users search]?
[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences].
Tips for FAQ questions:
- Use natural question phrasing ("How do I..." not "How does one...")
- Include question words: what, how, why, when, where, who, which
- Match "People Also Ask" queries from search results
- Keep answers between 50-100 words
Use for "Best [X]", "Top [X]", "[Number] ways to [X]" queries.
Caveat for self-promotional listicles: ranking yourself #1 in your own "best [category]" guide gets the page cited far more reliably than it gets your brand recommended — for emerging brands, AI answers often harvest the competitor names from the guide and recommend them instead. See citations-vs-recommendations.md before building these at scale.
## [Number] Best [Items] for [Goal/Purpose]
[1-2 sentence intro establishing context and selection criteria]
### 1. [Item Name]
[Why it's included in 2-3 sentences with specific benefits]
### 2. [Item Name]
[Why it's included in 2-3 sentences with specific benefits]
### 3. [Item Name]
[Why it's included in 2-3 sentences with specific benefits]
These patterns optimize content for citation by AI assistants like ChatGPT, Claude, Perplexity, and Gemini.
Statistics increase AI citation rates by 15-30%. Always include sources.
[Claim statement]. According to [Source/Organization], [specific statistic with number and timeframe]. [Context for why this matters].
Example:
Mobile optimization is no longer optional for SEO success. According to Google's 2024 Core Web Vitals report, 70% of web traffic now comes from mobile devices, and pages failing mobile usability standards see 24% higher bounce rates. This makes mobile-first indexing a critical ranking factor.
Named expert attribution adds credibility and increases citation likelihood.
"[Direct quote from expert]," says [Expert Name], [Title/Role] at [Organization]. [1 sentence of context or interpretation].
Example:
"The shift from keyword-driven search to intent-driven discovery represents the most significant change in SEO since mobile-first indexing," says Rand Fishkin, Co-founder of SparkToro. This perspective highlights why content strategies must evolve beyond traditional keyword optimization.
Structure claims for easy AI extraction with clear attribution.
[Topic] [verb: is/has/requires/involves] [clear, specific claim]. [Source] [confirms/reports/found] that [supporting evidence]. This [explains/means/suggests] [implication or action].
Example:
E-E-A-T is the cornerstone of Google's content quality evaluation. Google's Search Quality Rater Guidelines confirm that trust is the most critical factor, stating that "untrustworthy pages have low E-E-A-T no matter how experienced, expert, or authoritative they may seem." This means content creators must prioritize transparency and accuracy above all other optimization tactics.
Create quotable, standalone statements that AI can extract directly.
**[Topic/Question]**: [Complete, self-contained answer that makes sense without additional context. Include specific details, numbers, or examples in 2-3 sentences.]
Example:
**Ideal blog post length for SEO**: The optimal length for SEO blog posts is 1,500-2,500 words for competitive topics. This range allows comprehensive topic coverage while maintaining reader engagement. HubSpot research shows long-form content earns 77% more backlinks than short articles, directly impacting search rankings.
Structure claims with evidence for maximum credibility.
[Opening claim statement].
Evidence supporting this includes:
- [Data point 1 with source]
- [Data point 2 with source]
- [Data point 3 with source]
[Concluding statement connecting evidence to actionable insight].
Different content domains benefit from different authority signals.
Voice queries are conversational and question-based. Optimize for these patterns:
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.
Goal: Get cited in "What is [category]?" and "Best [category]" queries. (Citation is the realistic goal here; being recommended in the answer depends on offsite consensus — see citations-vs-recommendations.md.)
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
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
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
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
Google's AI features pull from product feeds and business profiles for local + ecom queries. Optimize:
Google's v0.1 markdown spec for representing site content as an agent-readable bundle. Introduced on the Google Cloud blog on 2026-06-12 and shipped inside Knowledge Catalog.
OKF is a directory of cross-linked markdown files. Each file has:
type required; title, description, resource, tags, timestamp recommended)An optional index.md lists the files for progressive disclosure. The bundle can be distributed as a git repo (recommended), a tarball/zip, or a subdirectory of a larger repo.
The full spec fits on one page. The repo lives under GoogleCloudPlatform (the "not an official Google product" disclaimer is Google's standard open-source boilerplate, not a denial — it appears on most of Google's open-source repos including their main AI samples repo).
---
type: Article
title: How to Connect the Ahrefs MCP Server to Manus
description: The official MCP servers, why they did not connect, and the fix.
resource: https://yoursite.com/blog/ahrefs-mcp-manus/
tags: [mcp, ahrefs]
---
# How to Connect the Ahrefs MCP Server to Manus
The body of the post, as clean markdown.
Add an index.md that lists all files so an agent can see the bundle's shape before opening each file, and that is the entire format.
Google built OKF for data teams sharing catalog metadata — BigQuery tables, API endpoints, metrics, playbooks. Most of the spec's examples are data-team artifacts, not blog posts. Google's blog post framing: "improve data sharing" and "standardized documentation" for collaboration across teams.
Pointing OKF at a marketing site is a clever repurposing popularized by Suganthan Mohanadasan. It's a legitimate use case for the format but not Google's primary one. Frame it accurately when explaining it to founders or marketing teams.
Nothing immediate. Nothing crawls the web for OKF bundles yet — the spec is weeks old, no AI engine has announced integration, and Knowledge Catalog ingests bundles only for paying enterprise customers' data teams.
Treat OKF as protocol-layer registration — the same shape of bet as early schema.org adoption was a decade ago. Schema took the better part of ten years to pay off; people who shipped it early are still glad they did.
A secondary benefit that pays off today regardless: generating the bundle is itself an internal-linking audit. Suganthan's tool draws every page as a node and every internal link as an edge, so islands and orphans become obvious at a glance.
| Layer | Purpose |
|---|---|
sitemap.xml |
Tells a crawler which URLs exist |
robots.txt (with AI bot rules) |
Permits or blocks AI crawlers |
llms.txt |
Points an agent at the handful of pages you most want read |
/pricing.md |
Structured pricing for agent-buyer comparisons |
/okf/ bundle |
Hands over the content itself as cross-linked concepts |
| Schema markup | Per-page structured data (Article, FAQPage, Product, etc.) |
These stack rather than compete. llms.txt is a signpost, OKF is the library.
Three options, ordered by how much effort they take:
suganthan.com/okf-generator — paste a URL or sitemap, crawls up to 100 pages, returns a downloadable bundle. Also draws the resulting page graph so you can spot disconnected pages before publishing.
Suganthan's plugin (free, GPL, awaiting wp.org approval at time of writing) installs in a minute, serves the bundle at /okf/, and rebuilds on every publish or edit so it stays in sync. Direct download link is in his blog post. Requires WordPress 6.0+ and PHP 7.4+. Read-only — never edits posts or settings.
Only practical for a handful of pages. Each post becomes a markdown file with frontmatter that you cross-link manually. Miserable for a whole site.
Serve the bundle at yoursite.com/okf/, starting with yoursite.com/okf/index.md:
/okf/After it's serving, add a line to llms.txt pointing to the bundle so agents that read llms.txt (today) can discover the bundle (later).
llms.txt, schema markup, or other machine-readable files (OKF compounds with those; alone it does nothing)OKF is v0.1, weeks old. Worth tracking, not worth obsessing over:
okf/index.md to see who's shipping bundlesEach AI search platform has its own search index, ranking logic, and content preferences. This guide covers what matters for getting cited on each one.
Sources cited throughout: Princeton GEO study (KDD 2024), SE Ranking domain authority study, ZipTie content-answer fit analysis.
Every AI platform shares three baseline requirements:
Beyond these basics, each platform weights different signals. Here's what matters and where.
Google AI Overviews pull from Google's own index and lean heavily on E-E-A-T signals (Experience, Expertise, Authoritativeness, Trustworthiness). They appear in roughly 45% of Google searches.
What makes Google AI Overviews different: They already have your traditional SEO signals — backlinks, page authority, topical relevance. The additional AI layer adds a preference for content with cited sources and structured data. Research shows that including authoritative citations in your content correlates with a 132% visibility boost, and writing with an authoritative (not salesy) tone adds another 89%.
Importantly, AI Overviews don't just recycle the traditional Top 10. Only about 15% of AI Overview sources overlap with conventional organic results. Pages that wouldn't crack page 1 in traditional search can still get cited if they have strong structured data and clear, extractable answers.
What to focus on:
- Schema markup is the single biggest lever — Article, FAQPage, HowTo, and Product schemas give AI Overviews structured context to work with (30-40% visibility boost)
- Build topical authority through content clusters with strong internal linking
- Include named, sourced citations in your content (not just claims)
- Author bios with real credentials matter — E-E-A-T is weighted heavily
- Get into Google's Knowledge Graph where possible (an accurate Wikipedia entry helps)
- Target "how to" and "what is" query patterns — these trigger AI Overviews most often
Watch for OKF. In June 2026 Google introduced the Open Knowledge Format — a markdown spec for agent-readable site bundles. There is no confirmed signal that AI Overviews factor it in today, but the spec is published, the GitHub repo lives under GoogleCloudPlatform, and it ships inside Knowledge Catalog. For protocol-layer "register early" plays, it has the same shape as early schema.org adoption did a decade ago. See Machine-Readable Files for AI Agents in the main SKILL.md for how to generate and serve a bundle.
ChatGPT's web search draws from a Bing-based index. It combines this with its training knowledge to generate answers, then cites the web sources it relied on.
What makes ChatGPT different: Domain authority matters more here than on other AI platforms. An SE Ranking analysis of 129,000 domains found that authority and credibility signals account for roughly 40% of what determines citation, with content quality at about 35% and platform trust at 25%. Sites with very high referring domain counts (350K+) average 8.4 citations per response, while sites with slightly lower trust scores (91-96 vs 97-100) drop from 8.4 to 6 citations.
Freshness is a major differentiator. Content updated within the last 30 days gets cited about 3.2x more often than older content. ChatGPT clearly favors recent information.
The most important signal is content-answer fit — a ZipTie analysis of 400,000 pages found that how well your content's style and structure matches ChatGPT's own response format accounts for about 55% of citation likelihood. This is far more important than domain authority (12%) or on-page structure (14%) alone. Write the way ChatGPT would answer the question, and you're more likely to be the source it cites.
Where ChatGPT looks beyond your site: Wikipedia accounts for 7.8% of all ChatGPT citations, Reddit for 1.8%, and Forbes for 1.1%. Brand official sites are cited frequently but third-party mentions carry significant weight.
What to focus on:
- Invest in backlinks and domain authority — it's the strongest baseline signal
- Update competitive content at least monthly
- Structure your content the way ChatGPT structures its answers (conversational, direct, well-organized)
- Include verifiable statistics with named sources
- Clean heading hierarchy (H1 > H2 > H3) with descriptive headings
Perplexity always cites its sources with clickable links, making it the most transparent AI search platform. It combines its own index with Google's and runs results through multiple reranking passes — initial relevance retrieval, then traditional ranking factor scoring, then ML-based quality evaluation that can discard entire result sets if they don't meet quality thresholds.
What makes Perplexity different: It's the most "research-oriented" AI search engine, and its citation behavior reflects that. Perplexity maintains curated lists of authoritative domains (Amazon, GitHub, major academic sites) that get inherent ranking boosts. It uses a time-decay algorithm that evaluates new content quickly, giving fresh publishers a real shot at citation.
Perplexity has unique content preferences:
- FAQ Schema (JSON-LD) — Pages with FAQ structured data get cited noticeably more often
- PDF documents — Publicly accessible PDFs (whitepapers, research reports) are prioritized. If you have authoritative PDF content gated behind a form, consider making a version public.
- Publishing velocity — How frequently you publish matters more than keyword targeting
- Self-contained paragraphs — Perplexity prefers atomic, semantically complete paragraphs it can extract cleanly
What to focus on:
- Allow PerplexityBot in robots.txt
- Implement FAQPage schema on any page with Q&A content
- Host PDF resources publicly (whitepapers, guides, reports)
- Add Article schema with publication and modification timestamps
- Write in clear, self-contained paragraphs that work as standalone answers
- Build deep topical authority in your specific niche
Copilot is embedded across Microsoft's ecosystem — Edge, Windows, Microsoft 365, and Bing Search. It relies entirely on Bing's index, so if Bing hasn't indexed your content, Copilot can't cite it.
What makes Copilot different: The Microsoft ecosystem connection creates unique optimization opportunities. Mentions and content on LinkedIn and GitHub provide ranking boosts that other platforms don't offer. Copilot also puts more weight on page speed — sub-2-second load times are a clear threshold.
What to focus on:
- Submit your site to Bing Webmaster Tools (many sites only submit to Google Search Console)
- Use IndexNow protocol for faster indexing of new and updated content
- Optimize page speed to under 2 seconds
- Write clear entity definitions — when your content defines a term or concept, make the definition explicit and extractable
- Build presence on LinkedIn (publish articles, maintain company page) and GitHub if relevant
- Ensure Bingbot has full crawl access
Claude uses Brave Search as its search backend when web search is enabled — not Google, not Bing. This is a completely different index, which means your Brave Search visibility directly determines whether Claude can find and cite you.
What makes Claude different: Claude is extremely selective about what it cites. While it processes enormous amounts of content, its citation rate is very low — it's looking for the most factually accurate, well-sourced content on a given topic. Data-rich content with specific numbers and clear attribution performs significantly better than general-purpose content.
What to focus on:
- Verify your content appears in Brave Search results (search for your brand and key terms at search.brave.com)
- Allow ClaudeBot and anthropic-ai user agents in robots.txt
- Maximize factual density — specific numbers, named sources, dated statistics
- Use clear, extractable structure with descriptive headings
- Cite authoritative sources within your content
- Aim to be the most factually accurate source on your topic — Claude rewards precision
If your robots.txt blocks an AI bot, that platform can't cite your content. Here are the user agents to allow:
User-agent: GPTBot # OpenAI — powers ChatGPT search
User-agent: ChatGPT-User # ChatGPT browsing mode
User-agent: PerplexityBot # Perplexity AI search
User-agent: ClaudeBot # Anthropic Claude
User-agent: anthropic-ai # Anthropic Claude (alternate)
User-agent: Google-Extended # Google Gemini and AI Overviews
User-agent: Bingbot # Microsoft Copilot (via Bing)
Allow: /
Training vs. search: Some AI bots are used for both model training and search citation. If you want to be cited but don't want your content used for training, your options are limited — GPTBot handles both for OpenAI. However, you can safely block CCBot (Common Crawl) without affecting any AI search citations, since it's only used for training dataset collection.
If you're optimizing for AI search for the first time, focus your effort where your audience actually is:
Start with Google AI Overviews — They reach the most users (45%+ of Google searches) and you likely already have Google SEO foundations in place. Add schema markup, include cited sources in your content, and strengthen E-E-A-T signals.
Then address ChatGPT — It's the most-used standalone AI search tool for tech and business audiences. Focus on freshness (update content monthly), domain authority, and matching your content structure to how ChatGPT formats its responses.
Then expand to Perplexity — Especially valuable if your audience includes researchers, early adopters, or tech professionals. Add FAQ schema, publish PDF resources, and write in clear, self-contained paragraphs.
Copilot and Claude are lower priority unless your audience skews enterprise/Microsoft (Copilot) or developer/analyst (Claude). But the fundamentals — structured content, cited sources, schema markup — help across all platforms.
Actions that help everywhere:
1. Allow all AI bots in robots.txt
2. Implement schema markup (FAQPage, Article, Organization at minimum)
3. Include statistics with named sources in your content
4. Update content regularly — monthly for competitive topics
5. Use clear heading structure (H1 > H2 > H3)
6. Keep page load time under 2 seconds
7. Add author bios with credentials
When the user wants to audit or optimize an App Store or Google Play listing. Also use when the user mentions 'ASO audit,' 'app store optimization,' 'optimize my app listing,' 'improve app visibility,' 'app store ranking
View source ↗Analyze App Store and Google Play listings against ASO best practices. Fetches
live listing data, scores metadata, visuals, and ratings, then produces a
prioritized action plan.
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.
Apple: apps.apple.com/{country}/app/{name}/id{digits}
Google: play.google.com/store/apps/details?id={package}
If the user gives an app name instead of a URL, search the web for:
site:apps.apple.com "{app name}" or site:play.google.com "{app name}"
Use WebFetch to retrieve the listing page. Extract every available field:
Apple App Store fields:
Google Play fields:
If WebFetch returns incomplete data (stores render client-side), note gaps and
work with what's available. Ask the user to paste missing fields if critical.
WebFetch cannot extract screenshot images or caption text. Take a screenshot
of the listing page to get visual data:
Promotional text (Apple): This 170-char field appears above the description
but is often indistinguishable from it in scraped HTML. If you cannot confirm
its presence, note this and recommend the user check App Store Connect.
Before scoring, classify the app into one of three tiers. This determines how
you interpret "textbook ASO" deviations — a deliberate brand choice by a
household name is not the same as a missed opportunity by an unknown app.
| Tier | Signals | Examples |
|---|---|---|
| Dominant | Household name, 1M+ ratings, top-10 in category, near-universal brand recognition. Users search by brand name, not generic keywords. | Instagram, Uber, Spotify, WhatsApp, Netflix |
| Established | Well-known in their category, 100K+ ratings, strong organic installs, recognized brand but not universally known. | Strava, Notion, Duolingo, Cash App, Calm |
| Challenger | Building awareness, <100K ratings, needs discovery through keywords and ASO tactics. Most apps fall here. | Your app, most indie/startup apps |
Dominant apps get adjusted scoring in these areas:
Established apps get partial adjustment:
Challenger apps are scored strictly against textbook ASO best practices — every character, screenshot, and keyword matters.
Key principle: Before docking points, ask: "Is this a mistake or a deliberate
choice by a team that has data I don't?" If the app has 1M+ ratings and a
dedicated ASO team, assume their choices are data-informed unless clearly wrong.
Score each dimension 0-10 using the criteria in references/scoring-criteria.md.
Apply the brand maturity tier adjustments from Phase 1.5.
Reference files for platform specs and benchmarks:
references/apple-specs.md — Official Apple character limits, screenshot/video specs, CPP/PPO rules, rejection triggersreferences/google-play-specs.md — Official Google Play limits, screenshot specs, Android Vitals thresholds, policiesreferences/benchmarks.md — Conversion data, rating impact, video lift, screenshot behavior, CPP/event benchmarks| # | Dimension | Weight | What It Covers |
|---|---|---|---|
| 1 | Title & Subtitle | 20% | Character usage, keyword presence, clarity, brand + keyword balance |
| 2 | Description | 15% | First 3 lines, keyword density (Google), CTA, structure, promotional text |
| 3 | Visual Assets | 25% | Screenshot count/quality/messaging, video, icon, feature graphic |
| 4 | Ratings & Reviews | 20% | Average rating, volume, recency, developer responses |
| 5 | Metadata & Freshness | 10% | Category choice, update recency, localization count, data safety |
| 6 | Conversion Signals | 10% | Price positioning, IAP transparency, social proof, download range |
Final score = weighted sum, out of 100.
| Score | Grade | Meaning |
|---|---|---|
| 85-100 | A | Well-optimized; focus on A/B testing and iteration |
| 70-84 | B | Good foundation; clear opportunities to improve |
| 50-69 | C | Significant gaps; prioritized fixes will have high impact |
| 30-49 | D | Major optimization needed across multiple dimensions |
| 0-29 | F | Listing needs a complete overhaul |
If the user provides competitor URLs or asks for comparison:
If no competitors are specified, suggest the user provide 2-3 or offer to search
for top apps in their category.
Use the template in references/report-template.md to structure the output.
The report must include:
references/apple-specs.md for full specs, dimensions, and rejection triggersreferences/google-play-specs.md for full specs and policy details| Field | Apple Indexed? | Google Indexed? |
|---|---|---|
| Title | Yes | Yes (strongest signal) |
| Subtitle / Short desc | Yes | Yes |
| Keyword field | Yes (hidden) | Does not exist |
| Long description | No | Yes (heavily) |
| Screenshot captions | Yes (since 2025) | No |
| In-app events | Yes | N/A (LiveOps instead) |
| Developer name | No | Partial |
| IAP names | Yes | Yes |
Flag these if found. Items marked (tier-dependent) should be evaluated against
the app's brand maturity tier — they may be deliberate choices for Dominant apps.
Always flag (all tiers):
Flag for Challenger/Established only (not mistakes for Dominant apps):
Flag for all tiers but note context:
All data from developer.apple.com as of March 2026.
| Field | Limit | Indexed for Search? | Notes |
|---|---|---|---|
| App Name | 30 chars (min 2) | Yes | Must be unique; no trademarks, competitor names, pricing |
| Subtitle | 30 chars | Yes | No unverifiable claims |
| Keywords | 100 bytes | Yes (hidden) | Commas, no spaces between terms |
| Description | 4,000 chars | No | Plain text only, no HTML |
| Promotional Text | 170 chars | No (Apple confirmed) | Updatable without new version |
| What's New | 4,000 chars | No | Required for all versions after first |
| IAP Name | 35 chars | Yes | Appears in search |
| IAP Description | 55 chars | No | |
| In-App Event Name | 30 chars | Yes | Title case required |
| In-App Event Short Desc | 50 chars | Yes | Sentence case |
| In-App Event Long Desc | 120 chars | No | Sentence case |
Keywords field is 100 bytes, not 100 characters. Non-Latin scripts (Arabic,
Chinese, Japanese, Korean) use 2-3 bytes per character, reducing effective
keyword count significantly.
| Device | Required? | Count | Dimensions (portrait) |
|---|---|---|---|
| 6.9" iPhone | Required | 1-10 | 1260 x 2736 |
| 13" iPad | Required | 1-10 | 2064 x 2752 |
| Mac | If applicable | 1-10 | Up to 2880 x 1800 (16:10) |
| Apple Watch | If applicable | 1-10 | Varies by model |
| Apple TV | If applicable | 1-10 | 1920 x 1080 or 3840 x 2160 |
| Apple Vision Pro | If applicable | 1-10 | 3840 x 2160 |
Event card image: 16:9, min 1920x1080, max 3840x2160
Event details image: 9:16, min 1080x1920, max 2160x3840
Not suitable: Repetitive daily tasks, price promotions without new content, general awareness campaigns.
| Guideline | Rejection Trigger |
|---|---|
| 2.3.1 | Hidden features, misleading marketing, false pricing |
| 2.3.2 | Not disclosing IAPs in description/screenshots |
| 2.3.3 | Screenshots that don't show app in use (only splash/login) |
| 2.3.4 | Preview videos using non-app content |
| 2.3.5 | Wrong category selected |
| 2.3.7 | Keyword stuffing: trademarks, competitor names, pricing, irrelevant terms |
| 2.3.8 | Metadata not appropriate for all audiences (must be 4+ rated) |
| 2.3.10 | Other platform names/imagery (Android, etc.) in metadata |
| 2.3.12 | Generic What's New for significant changes |
| 2.3.13 | Inaccurate in-app event metadata |
Sources: developer.apple.com/app-store/product-page/,
developer.apple.com/app-store/search/,
developer.apple.com/app-store/review/guidelines/
Industry data from AppTweak, SplitMetrics, Sensor Tower, and others. Updated March 2026.
Average CVR (page view to install):
| Category | iOS CVR | Google Play CVR |
|---|---|---|
| Navigation | 115%* | -- |
| Auto & Vehicles | -- | 70.5% |
| Business | 66.7% | -- |
| Music (Games) | -- | 45.0% |
| Utilities & Tools | -- | 36.8% |
| Shopping | -- | 27.7% |
| Health & Fitness | -- | 23.2% |
| Finance | -- | 19.7% |
| Food & Drink | -- | 13.1% |
| Games (Board) | 1.2% | 7.3% |
| Games (overall) | 3-5% realistic | -- |
*Above 100% = some users install from search without visiting product page.
Source: AppTweak 2025 Benchmarks Report (H1 2024 data, US market)
| Rating Change | Conversion Impact |
|---|---|
| 3.0 to 4.0 stars | +89% |
| 4.0 to 4.5 stars | +20-30% |
| 4.3 to 4.6 stars | +22-28% (Finance, Health) |
| 0.4-star gap vs competitor | ~25% lost installs from same search |
| 3-star vs 5-star app | 50% fewer conversions for 3-star |
Critical thresholds:
Sources: AppFollow, MobileAction, Sensor Tower, Troof.ai
iOS: +20-40% conversion lift (video autoplays on product page)
Google Play: Minimal lift (only ~6% of visitors tap to play)
Takeaway: Video is high-ROI on iOS, low-ROI on Google Play.
Sources: StoreMaven, SplitMetrics, Leanplum
Sources: AppTweak, ASOMobile, Sensor Tower
Sources: AppTweak, SplitMetrics, MobileAction
Source: Phiture, MobileAction
Sources: Phiture, AppTweak, Appalize
Source: Google Play Console documentation
| Improvement | Classification |
|---|---|
| >10% | Strong winner -- apply immediately |
| 5-10% | Meaningful winner |
| 2-5% | Marginal winner |
| <2% | Noise -- not significant |
Source: SplitMetrics, MobileAction
All data from support.google.com and developer.android.com as of March 2026.
| Field | Limit | Indexed? | Notes |
|---|---|---|---|
| App Title | 30 chars | Yes (strongest signal) | Reduced from 50 in Sept 2021 |
| Short Description | 80 chars | Yes | Visible without expanding |
| Full Description | 4,000 chars | Yes (heavily) | Google NLP indexes entire text |
| Developer Name | 64 chars | Partial | Same emoji/caps restrictions as title |
Title, Icon, Developer Name:
Short Description:
Screenshots, Feature Graphic, Video:
| Device | Min | Max | Aspect Ratio | Min Resolution | Max Long Edge |
|---|---|---|---|---|---|
| Phone | 2 | 8 | 9:16 or 16:9 | 320px any side | 3,840px |
| 7" Tablet | 4 | 8 | 9:16 or 16:9 | 1,080px short | 7,680px |
| 10" Tablet | 4 | 8 | 9:16 or 16:9 | 1,080px short | 7,680px |
| Chromebook | 4 | 8 | 9:16 or 16:9 | 1,080px short | 7,680px |
| Wear OS | 1 | 8 | 1:1 | 384x384 | 3,840px |
| Android TV | 1 | 8 | 16:9 | 1,920x1,080 | 3,840px |
Note: Google Play max is 8 screenshots per device, not 10 like Apple.
| Type | Description | Duration |
|---|---|---|
| Offers | Discounts, free items, bundles | Up to 28 days |
| Events | Time-limited in-app events | Must have time limit |
| Major Update | Significant new features | Max 1 week |
| Crossover (games) | Cross-game/IP collaboration | Varies |
Apps exceeding these thresholds get reduced visibility in search and recommendations.
| Metric | Overall Threshold | Per-Device Threshold |
|---|---|---|
| User-Perceived Crash Rate | 1.09% | 8% |
| User-Perceived ANR Rate | 0.47% | 8% |
| Excessive Partial Wake Locks | 5% | N/A |
Consequences: Reduced search visibility, warning labels on listing, quality alerts to users before install.
Recovery: Google checks daily using 28-day rolling average.
Google confirms these affect ranking:
Sources: support.google.com/googleplay/android-developer/answer/4448378,
support.google.com/googleplay/android-developer/answer/9898842,
developer.android.com/topic/performance/vitals
Use this structure for all ASO audit reports.
# ASO Audit: {App Name}
**Store:** {Apple App Store / Google Play}
**URL:** {listing URL}
**Audit date:** {date}
**Brand tier:** {Dominant / Established / Challenger} — {one-line justification}
**Overall Score:** {score}/100 (Grade: {A/B/C/D/F})
| Dimension | Score | Grade | Key Issue |
|-----------|-------|-------|-----------|
| Title & Subtitle | X/10 | {grade} | {one-line summary} |
| Description | X/10 | {grade} | {one-line summary} |
| Visual Assets | X/10 | {grade} | {one-line summary} |
| Ratings & Reviews | X/10 | {grade} | {one-line summary} |
| Metadata & Freshness | X/10 | {grade} | {one-line summary} |
| Conversion Signals | X/10 | {grade} | {one-line summary} |
| **OVERALL** | **{weighted}/100** | **{grade}** | |
Grade scale per dimension: 9-10 = A, 7-8 = B, 5-6 = C, 3-4 = D, 1-2 = F
Highest-impact changes that take under 1 hour:
### 1. {Action verb} — {specific change}
**Impact:** {High/Medium} | **Effort:** {<15 min / <30 min / <1 hour}
**Current:** {what it is now}
**Recommended:** {exact replacement, with character count}
**Why:** {one sentence explaining the impact}
### 2. ...
### 3. ...
**Current title:** "{title}" ({X}/30 chars used)
**Current subtitle/short desc:** "{subtitle}" ({X}/30 or /80 chars used)
**Issues found:**
- {issue 1}
- {issue 2}
**Recommended title:** "{new title}" ({X}/30 chars) — {rationale}
**Recommended subtitle:** "{new subtitle}" ({X}/30 or /80 chars) — {rationale}
**First 3 lines (above fold):**
> {quoted text}
**Issues found:**
- {issue 1}
- {issue 2}
**Keyword density (Google Play only):** {X}% — target: 2-3%
**Top keywords found:** {keyword1} (Xn), {keyword2} (Xn), ...
**Missing high-value keywords:** {keyword1}, {keyword2}, ...
**Recommended first 3 lines:**
> {rewritten text}
**Screenshots:** {count} ({store} shows first {3/all} in search)
**Preview video:** {Yes/No}
**Icon assessment:** {description}
**Feature graphic (Google Play):** {Yes/No}
**Screenshot audit:**
1. {screenshot 1 description} — {pass/issue}
2. {screenshot 2 description} — {pass/issue}
...
**Recommendations:**
- {specific visual change 1}
- {specific visual change 2}
**Average rating:** {X.X} stars ({count} ratings)
**Recent review sentiment:** {Positive/Mixed/Negative}
**Common complaints:** {theme1}, {theme2}
**Developer responses:** {Yes, active / Sporadic / None}
**Recommendations:**
- {specific action 1}
- {specific action 2}
**Last updated:** {date} ({X days/months ago})
**Localizations:** {count} languages
**Category:** {current category}
**In-app events/LiveOps:** {Yes/No}
**Recommendations:**
- {specific action 1}
- {specific action 2}
**Price model:** {Free / Freemium / Paid}
**IAP count:** {count}
**Downloads (Google Play):** {range}
**Social proof visible:** {awards, press, badges — or "none"}
**Recommendations:**
- {specific action 1}
- {specific action 2}
| Keyword | Rationale | Where to Place | Priority |
|---------|-----------|----------------|----------|
| {keyword} | {why this keyword} | {title/subtitle/description/keyword field} | {High/Med/Low} |
| ... | ... | ... | ... |
Note: Without paid ASO tools, exact search volume is unavailable. These
suggestions are based on category analysis, competitor metadata, and semantic
relevance. Validate with AppTweak, Sensor Tower, or MobileAction for volume data.
| Metric | {Your App} | {Competitor 1} | {Competitor 2} |
|--------|-----------|----------------|----------------|
| Title keywords | ... | ... | ... |
| Rating | ... | ... | ... |
| Screenshots | ... | ... | ... |
| Video | ... | ... | ... |
| Description keywords | ... | ... | ... |
| Last updated | ... | ... | ... |
| Overall ASO score | ... | ... | ... |
Ordered by impact (high to low), grouped by effort:
### Do This Week (Quick Wins)
1. {action} — {expected impact}
2. {action} — {expected impact}
### Do This Month (Medium Effort)
3. {action} — {expected impact}
4. {action} — {expected impact}
### Plan for Next Quarter (High Effort)
5. {action} — {expected impact}
6. {action} — {expected impact}
Always include this section:
What this audit cannot measure without paid ASO tools:
- Exact keyword search volume and difficulty scores
- Historical keyword ranking positions
- Download and revenue estimates
- Apple keyword field contents (hidden from public view)
- Install conversion rate data (only available to app owner in console)
- A/B test results from previous experiments
For these data points, consider using AppTweak ($69/mo), Sensor Tower, or
MobileAction ($69/mo).
Score each dimension 0-10 using the rubrics below.
Apply brand maturity tier adjustments from Phase 1.5 of the main skill.
Before scoring, determine the app's tier: Dominant, Established, or Challenger.
Dominant apps (Instagram, Uber, Spotify, WhatsApp, Netflix):
Established apps (Duolingo, Strava, Notion, Calm, Cash App):
Challenger apps (most apps):
Key principle: Before docking points, ask: "Is this a mistake or a data-informed
choice by a team with more information than I have?"
Challenger rubric:
| Score | Criteria |
|---|---|
| 9-10 | Brand + high-value keyword in title, complementary keywords in subtitle, no word repetition across fields, near max character usage, instantly communicates app purpose |
| 7-8 | Good keyword presence, minor character waste (5+ unused chars), clear purpose |
| 5-6 | Has keywords but poor placement, some repetition between fields, purpose somewhat clear |
| 3-4 | Title is brand-only or generic, subtitle missing or weak, poor character usage |
| 1-2 | No keyword strategy, title doesn't communicate purpose, major character waste |
| 0 | Cannot assess (data unavailable) |
Dominant/Established adjustment: Brand-only titles (e.g., "Instagram") are
valid if the brand has high search volume. Score 8+ for Dominant apps where
brand recognition eliminates the need for generic keywords. Evaluate whether
unused characters represent waste or intentional simplicity.
Check for:
| Score | Criteria |
|---|---|
| 9-10 | First 3 lines hook with clear value prop, structured with features/benefits/social proof/CTA, promotional text actively used, compelling and scannable |
| 7-8 | Good opening, decent structure, could improve scannability or CTA |
| 5-6 | Generic opening ("Welcome to..."), some structure, missing CTA or social proof |
| 3-4 | Wall of text, no clear value prop above fold, no promotional text |
| 1-2 | Minimal or boilerplate description, no effort |
| 0 | Cannot assess |
| Score | Criteria |
|---|---|
| 9-10 | Keywords in first 3 sentences, 2-3% natural density throughout, HTML formatting used, structured sections, strong CTA, keywords feel natural |
| 7-8 | Good keyword presence, some structure, density slightly off (1-2% or 3-4%) |
| 5-6 | Keywords present but sparse (<1%) or stuffed (>5%), weak structure |
| 3-4 | No keyword strategy visible, poor formatting, wall of text |
| 1-2 | Minimal description, no keywords, no structure |
| 0 | Cannot assess |
Check for:
| Score | Criteria |
|---|---|
| 9-10 | 8-10 screenshots with clear messaging/captions, preview video present, screenshots tell a story in sequence, each communicates one benefit, icon is distinctive and memorable |
| 7-8 | 6-7 screenshots with captions, good icon, no video OR good video but some screenshot messaging unclear |
| 5-6 | 5+ screenshots but weak/no captions, basic icon, no video, screenshots are UI dumps |
| 3-4 | 3-4 screenshots, no captions, generic icon, no storytelling |
| 1-2 | Fewer than 3 screenshots, or screenshots are raw unedited UI, poor icon |
| 0 | Cannot assess |
Check for:
| Score | Criteria |
|---|---|
| 9-10 | 4.5+ stars, 10K+ ratings, recent reviews positive, developer responds to negatives, steady review flow |
| 7-8 | 4.0-4.4 stars, 1K+ ratings, mostly positive recent reviews, some developer responses |
| 5-6 | 3.5-3.9 stars, 500+ ratings, mixed recent reviews, no developer responses |
| 3-4 | 3.0-3.4 stars, <500 ratings, negative themes in recent reviews |
| 1-2 | Below 3.0 stars, few ratings, no developer engagement, visible complaints |
| 0 | No ratings yet or cannot assess |
Check for:
| Score | Criteria |
|---|---|
| 9-10 | Updated within last month, 10+ localizations, optimal category choice, in-app events/LiveOps active, data safety complete |
| 7-8 | Updated within 2 months, 5+ localizations, good category, data safety present |
| 5-6 | Updated within 3 months, 2-4 localizations, acceptable category |
| 3-4 | Updated 3-6 months ago, 1-2 localizations, possibly wrong category |
| 1-2 | Not updated in 6+ months, single language, poor category choice |
| 0 | Cannot assess |
Check for:
| Score | Criteria |
|---|---|
| 9-10 | Clear value before download, transparent pricing/IAP, social proof visible (press, awards), download range suggests strong traction, developer credibility strong |
| 7-8 | Good value communication, pricing clear, some social proof |
| 5-6 | Value prop exists but weak, pricing unclear or IAP heavy, limited social proof |
| 3-4 | Unclear what user gets, confusing pricing, no social proof, low downloads visible |
| 1-2 | No value communication, suspicious pricing, app looks abandoned |
| 0 | Cannot assess |
Check for:
Final Score = (Title * 0.20) + (Description * 0.15) + (Visuals * 0.25)
+ (Ratings * 0.20) + (Metadata * 0.10) + (Conversion * 0.10)
Scale to 100: Final Score * 10
Example: Title: 7, Description: 6, Visuals: 8, Ratings: 9, Metadata: 5, Conversion: 7
(7 * 0.20) + (6 * 0.15) + (8 * 0.25) + (9 * 0.20) + (5 * 0.10) + (7 * 0.10)
= 1.4 + 0.9 + 2.0 + 1.8 + 0.5 + 0.7
= 7.3 → 73/100 → Grade: B
When the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions "programmatic SEO," "template pages," "pages at scale," "directory pages," "location pages," "[keyword] +
View source ↗You are an expert in programmatic SEO—building SEO-optimized pages at scale using templates and data. Your goal is to create pages that rank, provide value, and avoid thin content penalties.
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.
Before designing a programmatic SEO strategy, understand:
Business Context
- What's the product/service?
- Who is the target audience?
- What's the conversion goal for these pages?
Opportunity Assessment
- What search patterns exist?
- How many potential pages?
- What's the search volume distribution?
Competitive Landscape
- Who ranks for these terms now?
- What do their pages look like?
- Can you realistically compete?
Hierarchy of data defensibility:
1. Proprietary (you created it)
2. Product-derived (from your users)
3. User-generated (your community)
4. Licensed (exclusive access)
5. Public (anyone can use—weakest)
Use subfolders, not subdomains — subfolders consolidate domain authority while subdomains split it:
- Good: yoursite.com/templates/resume/
- Bad: templates.yoursite.com/resume/
Pages must actually answer what people are searching for.
Better to have 100 great pages than 10,000 thin ones.
| Playbook | Pattern | Example |
|---|---|---|
| Templates | "[Type] template" | "resume template" |
| Curation | "best [category]" | "best website builders" |
| Conversions | "[X] to [Y]" | "$10 USD to GBP" |
| Comparisons | "[X] vs [Y]" | "webflow vs wordpress" |
| Examples | "[type] examples" | "landing page examples" |
| Locations | "[service] in [location]" | "dentists in austin" |
| Personas | "[product] for [audience]" | "crm for real estate" |
| Integrations | "[product A] [product B] integration" | "slack asana integration" |
| Glossary | "what is [term]" | "what is pSEO" |
| Translations | Content in multiple languages | Localized content |
| Directory | "[category] tools" | "ai copywriting tools" |
| Profiles | "[entity name]" | "stripe ceo" |
For detailed playbook implementation: See references/playbooks.md
| If you have... | Consider... |
|---|---|
| Proprietary data | Directories, Profiles |
| Product with integrations | Integrations |
| Design/creative product | Templates, Examples |
| Multi-segment audience | Personas |
| Local presence | Locations |
| Tool or utility product | Conversions |
| Content/expertise | Glossary, Curation |
| Competitor landscape | Comparisons |
You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego").
Identify the pattern:
- What's the repeating structure?
- What are the variables?
- How many unique combinations exist?
Validate demand:
- Aggregate search volume
- Volume distribution (head vs. long tail)
- Trend direction
Identify data sources:
- What data populates each page?
- Is it first-party, scraped, licensed, public?
- How is it updated?
Page structure:
- Header with target keyword
- Unique intro (not just variables swapped)
- Data-driven sections
- Related pages / internal links
- CTAs appropriate to intent
Ensuring uniqueness:
- Each page needs unique value
- Conditional content based on data
- Original insights/analysis per page
Hub and spoke model:
- Hub: Main category page
- Spokes: Individual programmatic pages
- Cross-links between related spokes
Avoid orphan pages:
- Every page reachable from main site
- XML sitemap for all pages
- Breadcrumbs with structured data
Content quality:
- [ ] Each page provides unique value
- [ ] Answers search intent
- [ ] Readable and useful
Technical SEO:
- [ ] Unique titles and meta descriptions
- [ ] Proper heading structure
- [ ] Schema markup implemented
- [ ] Page speed acceptable
Internal linking:
- [ ] Connected to site architecture
- [ ] Related pages linked
- [ ] No orphan pages
Indexation:
- [ ] In XML sitemap
- [ ] Crawlable
- [ ] No conflicting noindex
Track: Indexation rate, Rankings, Traffic, Engagement, Conversion
Watch for: Thin content warnings, Ranking drops, Manual actions, Crawl errors
Beyond mixing and matching data point permutations, these are the proven playbooks for programmatic SEO.
Pattern: "[Type] template" or "free [type] template"
Example searches: "resume template", "invoice template", "pitch deck template"
What it is: Downloadable or interactive templates users can use directly.
Why it works:
- High intent—people need it now
- Shareable/linkable assets
- Natural for product-led companies
Value requirements:
- Actually usable templates (not just previews)
- Multiple variations per type
- Quality comparable to paid options
- Easy download/use flow
URL structure: /templates/[type]/ or /templates/[category]/[type]/
Pattern: "best [category]" or "top [number] [things]"
Example searches: "best website builders", "top 10 crm software", "best free design tools"
What it is: Curated lists ranking or recommending options in a category.
Why it works:
- Comparison shoppers searching for guidance
- High commercial intent
- Evergreen with updates
Value requirements:
- Genuine evaluation criteria
- Real testing or expertise
- Regular updates (date visible)
- Not just affiliate-driven rankings
URL structure: /best/[category]/ or /[category]/best/
Pattern: "[X] to [Y]" or "[amount] [unit] in [unit]"
Example searches: "$10 USD to GBP", "100 kg to lbs", "pdf to word"
What it is: Tools or pages that convert between formats, units, or currencies.
Why it works:
- Instant utility
- Extremely high search volume
- Repeat usage potential
Value requirements:
- Accurate, real-time data
- Fast, functional tool
- Related conversions suggested
- Mobile-friendly interface
URL structure: /convert/[from]-to-[to]/ or /[from]-to-[to]-converter/
Pattern: "[X] vs [Y]" or "[X] alternative"
Example searches: "webflow vs wordpress", "notion vs coda", "figma alternatives"
What it is: Head-to-head comparisons between products, tools, or options.
Why it works:
- High purchase intent
- Clear search pattern
- Scales with number of competitors
Value requirements:
- Honest, balanced analysis
- Actual feature comparison data
- Clear recommendation by use case
- Updated when products change
URL structure: /compare/[x]-vs-[y]/ or /[x]-vs-[y]/
See also: competitors skill for detailed frameworks
Pattern: "[type] examples" or "[category] inspiration"
Example searches: "saas landing page examples", "email subject line examples", "portfolio website examples"
What it is: Galleries or collections of real-world examples for inspiration.
Why it works:
- Research phase traffic
- Highly shareable
- Natural for design/creative tools
Value requirements:
- Real, high-quality examples
- Screenshots or embeds
- Categorization/filtering
- Analysis of why they work
URL structure: /examples/[type]/ or /[type]-examples/
Pattern: "[service/thing] in [location]"
Example searches: "coworking spaces in san diego", "dentists in austin", "best restaurants in brooklyn"
What it is: Location-specific pages for services, businesses, or information.
Why it works:
- Local intent is massive
- Scales with geography
- Natural for marketplaces/directories
Value requirements:
- Actual local data (not just city name swapped)
- Local providers/options listed
- Location-specific insights (pricing, regulations)
- Map integration helpful
URL structure: /[service]/[city]/ or /locations/[city]/[service]/
Pattern: "[product] for [audience]" or "[solution] for [role/industry]"
Example searches: "payroll software for agencies", "crm for real estate", "project management for freelancers"
What it is: Tailored landing pages addressing specific audience segments.
Why it works:
- Speaks directly to searcher's context
- Higher conversion than generic pages
- Scales with personas
Value requirements:
- Genuine persona-specific content
- Relevant features highlighted
- Testimonials from that segment
- Use cases specific to audience
URL structure: /for/[persona]/ or /solutions/[industry]/
Pattern: "[your product] [other product] integration" or "[product] + [product]"
Example searches: "slack asana integration", "zapier airtable", "hubspot salesforce sync"
What it is: Pages explaining how your product works with other tools.
Why it works:
- Captures users of other products
- High intent (they want the solution)
- Scales with integration ecosystem
Value requirements:
- Real integration details
- Setup instructions
- Use cases for the combination
- Working integration (not vaporware)
URL structure: /integrations/[product]/ or /connect/[product]/
Pattern: "what is [term]" or "[term] definition" or "[term] meaning"
Example searches: "what is pSEO", "api definition", "what does crm stand for"
What it is: Educational definitions of industry terms and concepts.
Why it works:
- Top-of-funnel awareness
- Establishes expertise
- Natural internal linking opportunities
Value requirements:
- Clear, accurate definitions
- Examples and context
- Related terms linked
- More depth than a dictionary
URL structure: /glossary/[term]/ or /learn/[term]/
Pattern: Same content in multiple languages
Example searches: "qué es pSEO", "was ist SEO", "マーケティングとは"
What it is: Your content translated and localized for other language markets.
Why it works:
- Opens entirely new markets
- Lower competition in many languages
- Multiplies your content reach
Value requirements:
- Quality translation (not just Google Translate)
- Cultural localization
- hreflang tags properly implemented
- Native speaker review
URL structure: /[lang]/[page]/ or yoursite.com/es/, /de/, etc.
Pattern: "[category] tools" or "[type] software" or "[category] companies"
Example searches: "ai copywriting tools", "email marketing software", "crm companies"
What it is: Comprehensive directories listing options in a category.
Why it works:
- Research phase capture
- Link building magnet
- Natural for aggregators/reviewers
Value requirements:
- Comprehensive coverage
- Useful filtering/sorting
- Details per listing (not just names)
- Regular updates
URL structure: /directory/[category]/ or /[category]-directory/
Pattern: "[person/company name]" or "[entity] + [attribute]"
Example searches: "stripe ceo", "airbnb founding story", "elon musk companies"
What it is: Profile pages about notable people, companies, or entities.
Why it works:
- Informational intent traffic
- Builds topical authority
- Natural for B2B, news, research
Value requirements:
- Accurate, sourced information
- Regularly updated
- Unique insights or aggregation
- Not just Wikipedia rehash
URL structure: /people/[name]/ or /companies/[name]/
| If you have... | Consider... |
|---|---|
| Proprietary data | Stats, Directories, Profiles |
| Product with integrations | Integrations |
| Design/creative product | Templates, Examples |
| Multi-segment audience | Personas |
| Local presence | Locations |
| Tool or utility product | Conversions |
| Content/expertise | Glossary, Curation |
| International potential | Translations |
| Competitor landscape | Comparisons |
You can layer multiple playbooks:
- Locations + Personas: "Marketing agencies for startups in Austin"
- Curation + Locations: "Best coworking spaces in San Diego"
- Integrations + Personas: "Slack for sales teams"
- Glossary + Translations: Multi-language educational content
When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "p
View source ↗You are an expert in structured data and schema markup. Your goal is to implement schema.org markup that helps search engines understand content and enables rich results in search.
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.
Before implementing schema, understand:
Page Type - What kind of page? What's the primary content? What rich results are possible?
Current State - Any existing schema? Errors in implementation? Which rich results already appearing?
Goals - Which rich results are you targeting? What's the business value?
<head> or end of <body>| Type | Use For | Required Properties |
|---|---|---|
| Organization | Company homepage/about | name, url |
| WebSite | Homepage (search box) | name, url |
| Article | Blog posts, news | headline, image, datePublished, author |
| Product | Product pages | name, image, offers |
| SoftwareApplication | SaaS/app pages | name, offers |
| FAQPage | FAQ content | mainEntity (Q&A array) |
| HowTo | Tutorials | name, step |
| BreadcrumbList | Any page with breadcrumbs | itemListElement |
| LocalBusiness | Local business pages | name, address |
| Event | Events, webinars | name, startDate, location |
For complete JSON-LD examples: See references/schema-examples.md
Required: name, url
Recommended: logo, sameAs (social profiles), contactPoint
Required: headline, image, datePublished, author
Recommended: dateModified, publisher, description
Required: name, image, offers (price + availability)
Recommended: sku, brand, aggregateRating, review
Required: mainEntity (array of Question/Answer pairs)
Required: itemListElement (array with position, name, item)
You can combine multiple schema types on one page using @graph:
{
"@context": "https://schema.org",
"@graph": [
{ "@type": "Organization", ... },
{ "@type": "WebSite", ... },
{ "@type": "BreadcrumbList", ... }
]
}
Missing required properties - Check Google's documentation for required fields
Invalid values - Dates must be ISO 8601, URLs fully qualified, enumerations exact
Mismatch with page content - Schema doesn't match visible content
// Full JSON-LD code block
{
"@context": "https://schema.org",
"@type": "...",
// Complete markup
}
Complete JSON-LD examples for common schema types.
For company/brand homepage or about page.
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "Example Company",
"url": "https://example.com",
"logo": "https://example.com/logo.png",
"sameAs": [
"https://twitter.com/example",
"https://linkedin.com/company/example",
"https://facebook.com/example"
],
"contactPoint": {
"@type": "ContactPoint",
"telephone": "+1-555-555-5555",
"contactType": "customer service"
}
}
For homepage, enables sitelinks search box.
{
"@context": "https://schema.org",
"@type": "WebSite",
"name": "Example",
"url": "https://example.com",
"potentialAction": {
"@type": "SearchAction",
"target": {
"@type": "EntryPoint",
"urlTemplate": "https://example.com/search?q={search_term_string}"
},
"query-input": "required name=search_term_string"
}
}
For blog posts and news articles.
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "How to Implement Schema Markup",
"image": "https://example.com/image.jpg",
"datePublished": "2024-01-15T08:00:00+00:00",
"dateModified": "2024-01-20T10:00:00+00:00",
"author": {
"@type": "Person",
"name": "Jane Doe",
"url": "https://example.com/authors/jane"
},
"publisher": {
"@type": "Organization",
"name": "Example Company",
"logo": {
"@type": "ImageObject",
"url": "https://example.com/logo.png"
}
},
"description": "A complete guide to implementing schema markup...",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://example.com/schema-guide"
}
}
For product pages (e-commerce or SaaS).
{
"@context": "https://schema.org",
"@type": "Product",
"name": "Premium Widget",
"image": "https://example.com/widget.jpg",
"description": "Our best-selling widget for professionals",
"sku": "WIDGET-001",
"brand": {
"@type": "Brand",
"name": "Example Co"
},
"offers": {
"@type": "Offer",
"url": "https://example.com/products/widget",
"priceCurrency": "USD",
"price": "99.99",
"availability": "https://schema.org/InStock",
"priceValidUntil": "2024-12-31"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "4.8",
"reviewCount": "127"
}
}
For SaaS product pages and app landing pages.
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "Example App",
"applicationCategory": "BusinessApplication",
"operatingSystem": "Web, iOS, Android",
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "4.6",
"ratingCount": "1250"
}
}
For pages with frequently asked questions.
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "What is schema markup?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Schema markup is a structured data vocabulary that helps search engines understand your content..."
}
},
{
"@type": "Question",
"name": "How do I implement schema?",
"acceptedAnswer": {
"@type": "Answer",
"text": "The recommended approach is to use JSON-LD format, placing the script in your page's head..."
}
}
]
}
For instructional content and tutorials.
{
"@context": "https://schema.org",
"@type": "HowTo",
"name": "How to Add Schema Markup to Your Website",
"description": "A step-by-step guide to implementing JSON-LD schema",
"totalTime": "PT15M",
"step": [
{
"@type": "HowToStep",
"name": "Choose your schema type",
"text": "Identify the appropriate schema type for your page content...",
"url": "https://example.com/guide#step1"
},
{
"@type": "HowToStep",
"name": "Write the JSON-LD",
"text": "Create the JSON-LD markup following schema.org specifications...",
"url": "https://example.com/guide#step2"
},
{
"@type": "HowToStep",
"name": "Add to your page",
"text": "Insert the script tag in your page's head section...",
"url": "https://example.com/guide#step3"
}
]
}
For any page with breadcrumb navigation.
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://example.com"
},
{
"@type": "ListItem",
"position": 2,
"name": "Blog",
"item": "https://example.com/blog"
},
{
"@type": "ListItem",
"position": 3,
"name": "SEO Guide",
"item": "https://example.com/blog/seo-guide"
}
]
}
For local business location pages.
{
"@context": "https://schema.org",
"@type": "LocalBusiness",
"name": "Example Coffee Shop",
"image": "https://example.com/shop.jpg",
"address": {
"@type": "PostalAddress",
"streetAddress": "123 Main Street",
"addressLocality": "San Francisco",
"addressRegion": "CA",
"postalCode": "94102",
"addressCountry": "US"
},
"geo": {
"@type": "GeoCoordinates",
"latitude": "37.7749",
"longitude": "-122.4194"
},
"telephone": "+1-555-555-5555",
"openingHoursSpecification": [
{
"@type": "OpeningHoursSpecification",
"dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
"opens": "08:00",
"closes": "18:00"
}
],
"priceRange": "$$"
}
For event pages, webinars, conferences.
{
"@context": "https://schema.org",
"@type": "Event",
"name": "Annual Marketing Conference",
"startDate": "2024-06-15T09:00:00-07:00",
"endDate": "2024-06-15T17:00:00-07:00",
"eventAttendanceMode": "https://schema.org/OnlineEventAttendanceMode",
"eventStatus": "https://schema.org/EventScheduled",
"location": {
"@type": "VirtualLocation",
"url": "https://example.com/conference"
},
"image": "https://example.com/conference.jpg",
"description": "Join us for our annual marketing conference...",
"offers": {
"@type": "Offer",
"url": "https://example.com/conference/tickets",
"price": "199",
"priceCurrency": "USD",
"availability": "https://schema.org/InStock",
"validFrom": "2024-01-01"
},
"performer": {
"@type": "Organization",
"name": "Example Company"
},
"organizer": {
"@type": "Organization",
"name": "Example Company",
"url": "https://example.com"
}
}
Combine multiple schema types using @graph.
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "Organization",
"@id": "https://example.com/#organization",
"name": "Example Company",
"url": "https://example.com"
},
{
"@type": "WebSite",
"@id": "https://example.com/#website",
"url": "https://example.com",
"name": "Example",
"publisher": {
"@id": "https://example.com/#organization"
}
},
{
"@type": "BreadcrumbList",
"itemListElement": [...]
}
]
}
export default function ProductPage({ product }) {
const schema = {
"@context": "https://schema.org",
"@type": "Product",
name: product.name,
// ... other properties
};
return (
<>
<Head>
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
/>
</Head>
{/* Page content */}
</>
);
}
When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO heal
View source ↗You are an expert in search engine optimization. Your goal is to identify SEO issues and provide actionable recommendations to improve organic search performance.
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.
Before auditing, understand:
Site Context
- What type of site? (SaaS, e-commerce, blog, etc.)
- What's the primary business goal for SEO?
- What keywords/topics are priorities?
Current State
- Any known issues or concerns?
- Current organic traffic level?
- Recent changes or migrations?
Scope
- Full site audit or specific pages?
- Technical + on-page, or one focus area?
- Access to Search Console / analytics?
web_fetch and curl cannot reliably detect structured data / schema markup.
Many CMS plugins (AIOSEO, Yoast, RankMath) inject JSON-LD via client-side JavaScript — it won't appear in static HTML or web_fetch output (which strips <script> tags during conversion).
To accurately check for schema markup, use one of these methods:
1. Browser tool — render the page and run: document.querySelectorAll('script[type="application/ld+json"]')
2. Google Rich Results Test — https://search.google.com/test/rich-results
3. Screaming Frog export — if the client provides one, use it (SF renders JavaScript)
Reporting "no schema found" based solely on web_fetch or curl leads to false audit findings — these tools can't see JS-injected schema.
Robots.txt
- Check for unintentional blocks
- Verify important pages allowed
- Check sitemap reference
XML Sitemap
- Exists and accessible
- Submitted to Search Console
- Contains only canonical, indexable URLs
- Updated regularly
- Proper formatting
Site Architecture
- Important pages within 3 clicks of homepage
- Logical hierarchy
- Internal linking structure
- No orphan pages
Crawl Budget Issues (for large sites)
- Parameterized URLs under control
- Faceted navigation handled properly
- Infinite scroll with pagination fallback
- Session IDs not in URLs
Index Status
- site:domain.com check
- Search Console coverage report
- Compare indexed vs. expected
Indexation Issues
- Noindex tags on important pages
- Canonicals pointing wrong direction
- Redirect chains/loops
- Soft 404s
- Duplicate content without canonicals
Canonicalization
- All pages have canonical tags
- Self-referencing canonicals on unique pages
- HTTP → HTTPS canonicals
- www vs. non-www consistency
- Trailing slash consistency
Core Web Vitals
- LCP (Largest Contentful Paint): < 2.5s
- INP (Interaction to Next Paint): < 200ms
- CLS (Cumulative Layout Shift): < 0.1
Speed Factors
- Server response time (TTFB)
- Image optimization
- JavaScript execution
- CSS delivery
- Caching headers
- CDN usage
- Font loading
Tools
- PageSpeed Insights
- WebPageTest
- Chrome DevTools
- Search Console Core Web Vitals report
Check when the site serves multiple languages or regions. Misconfigurations can suppress indexing of entire locale variants or drag down site-wide quality signals. See International SEO reference for evidence and source URLs.
Three equivalent placement methods: HTML <link> in <head>, HTTP Link headers, XML sitemap <xhtml:link>. If using multiple, they must agree -- conflicting signals cause Google to drop that pair. For 10+ locales, prefer sitemap-based (no page weight, no per-request cost).
Check for:
- Self-referencing entry on every page (page must include itself in the hreflang set)
- Reciprocal links (if A points to B, B must point back to A -- or both are ignored)
- Valid codes: ISO 639-1 language + optional ISO 3166-1 Alpha 2 region (e.g., en, en-GB -- never en-UK)
- x-default present, pointing to fallback page (language selector or default locale)
- All target URLs return 200, are indexable, and match their canonical URL
- No duplicate language-region codes pointing to different URLs
Common errors: Missing self-referencing entry (all hreflang ignored). No return tag / one-directional (pair dropped). Invalid codes like en-UK (use en-GB). Hreflang target is non-canonical, 404, or blocked (cluster discarded). HTML and sitemap annotations disagree (conflicting pair dropped).
At scale: <xhtml:link> children don't count toward 50K URL sitemap limit, but the 50MB file size limit becomes the bottleneck (plan 2K-5K URLs per file with full hreflang). Focus hreflang on pages receiving wrong-language traffic -- not required on every page. For Bing: supplement with <html lang> and <meta http-equiv="content-language"> (Bing treats hreflang as a weak signal).
/ar/page canonicals to /ar/page)https + same domain variant)Common mistakes: all locales canonical to English (kills indexing), canonical URL not in hreflang set (silently ignored), protocol mismatch between canonical and hreflang, CMS setting deep page canonical to homepage.
Check for:
- xmlns:xhtml namespace on <urlset>, each <url> includes <xhtml:link> for all locales including itself
- x-default alternate included; all URLs absolute (full protocol + domain)
- Sitemap index in Search Console and robots.txt; split by content type, not by locale
Next.js caveat: alternates.languages does NOT auto-include a self-referencing <xhtml:link> for the <loc> URL -- you must add the current locale explicitly.
Recommended: Subdirectories (/en/, /ar/). Acceptable: Subdomains or ccTLDs. Not recommended: URL parameters (?lang=en).
Check for:
- Consistent locale prefix strategy; all locales prefixed (hiding locale from URLs prevents Google from distinguishing versions)
- Root URL handled as x-default with redirect, or serves default locale content
- No IP/Accept-Language content negotiation (Googlebot: US IPs, no Accept-Language header)
- Trailing slash + case consistency across locale paths, canonicals, hreflang, and sitemaps
- 301 redirects from non-canonical format to canonical
Note: Google's International Targeting report in Search Console is deprecated. Geotargeting relies on hreflang, content signals, and linking patterns.
Translation quality:
- AI-translated content is not inherently spam (Google's 2025 stance), but scaled low-value translations can trigger scaled content abuse policy
- Google uses visible content to determine language -- translate ALL page content (title, description, headings, body), not just boilerplate
- Translating only template/nav while main content stays in original language creates duplicates
Thin locale pages:
- Helpful content system is site-wide -- many thin locale pages can suppress rankings for strong pages too
- Don't noindex thin locales (wastes crawl budget) or cross-locale canonical (conflicts with hreflang)
- Best approach: don't create locale pages you cannot make genuinely helpful
Check for:
- All locale pages have fully translated main content (not just UI chrome)
- No near-identical content across locales ("Duplicate, Google chose different canonical" in GSC)
- Hreflang only for locales with genuine content and search demand
- Localized signals: currency, phone format, addresses where applicable
- Broken hreflang links (404s, redirects) waste crawl budget AND invalidate hreflang clusters
Check for:
- Unique titles for each page
- Primary keyword near beginning
- 50-60 characters (visible in SERP)
- Compelling and click-worthy
- Brand name placement (end, usually)
Common issues:
- Duplicate titles
- Too long (truncated)
- Too short (wasted opportunity)
- Keyword stuffing
- Missing entirely
Check for:
- Unique descriptions per page
- 150-160 characters
- Includes primary keyword
- Clear value proposition
- Call to action
Common issues:
- Duplicate descriptions
- Auto-generated garbage
- Too long/short
- No compelling reason to click
Check for:
- One H1 per page
- H1 contains primary keyword
- Logical hierarchy (H1 → H2 → H3)
- Headings describe content
- Not just for styling
Common issues:
- Multiple H1s
- Skip levels (H1 → H3)
- Headings used for styling only
- No H1 on page
Primary Page Content
- Keyword in first 100 words
- Related keywords naturally used
- Sufficient depth/length for topic
- Answers search intent
- Better than competitors
Thin Content Issues
- Pages with little unique content
- Tag/category pages with no value
- Doorway pages
- Duplicate or near-duplicate content
Check for:
- Descriptive file names
- Alt text on all images
- Alt text describes image
- Compressed file sizes
- Modern formats (WebP)
- Lazy loading implemented
- Responsive images
Check for:
- Important pages well-linked
- Descriptive anchor text
- Logical link relationships
- No broken internal links
- Reasonable link count per page
Common issues:
- Orphan pages (no internal links)
- Over-optimized anchor text
- Important pages buried
- Excessive footer/sidebar links
Per Page
- Clear primary keyword target
- Title, H1, URL aligned
- Content satisfies search intent
- Not competing with other pages (cannibalization)
Site-Wide
- Keyword mapping document
- No major gaps in coverage
- No keyword cannibalization
- Logical topical clusters
Experience
- First-hand experience demonstrated
- Original insights/data
- Real examples and case studies
Expertise
- Author credentials visible
- Accurate, detailed information
- Properly sourced claims
Authoritativeness
- Recognized in the space
- Cited by others
- Industry credentials
Trustworthiness
- Accurate information
- Transparent about business
- Contact information available
- Privacy policy, terms
- Secure site (HTTPS)
Executive Summary
- Overall health assessment
- Top 3-5 priority issues
- Quick wins identified
Technical SEO Findings
For each issue:
- Issue: What's wrong
- Impact: SEO impact (High/Medium/Low)
- Evidence: How you found it
- Fix: Specific recommendation
- Priority: 1-5 or High/Medium/Low
On-Page SEO Findings
Same format as above
Content Findings
Same format as above
Prioritized Action Plan
1. Critical fixes (blocking indexation/ranking)
2. High-impact improvements
3. Quick wins (easy, immediate benefit)
4. Long-term recommendations
Free Tools
- Google Search Console (essential)
- Google PageSpeed Insights
- Bing Webmaster Tools
- Rich Results Test (use this for schema validation — it renders JavaScript)
- Mobile-Friendly Test
- Schema Validator
Note on schema detection:
web_fetchstrips<script>tags (including JSON-LD) and cannot detect JS-injected schema. Use the browser tool, Rich Results Test, or Screaming Frog instead — they render JavaScript and capture dynamically-injected markup. See the Schema Markup Detection Limitation section above.
Paid Tools (if available)
- Screaming Frog
- Ahrefs / Semrush
- Sitebulb
- ContentKing
Words, phrases, and punctuation patterns commonly associated with AI-generated text. Avoid these to ensure writing sounds natural and human.
Sources: Grammarly (2025), Microsoft 365 Life Hacks (2025), GPTHuman (2025), Walter Writes (2025), Textero (2025), Plagiarism Today (2025), Rolling Stone (2025), MDPI Blog (2025)
The em dash (—) has become one of the most reliable markers of AI-generated content.
Em dashes are longer than hyphens (-) and are used for emphasis, interruptions, or parenthetical information. While they have legitimate uses in writing, AI models drastically overuse them.
| Instead of | Use |
|---|---|
| The results—which were surprising—showed... | The results, which were surprising, showed... |
| This approach—unlike traditional methods—allows... | This approach, unlike traditional methods, allows... |
| The study found—as expected—that... | The study found, as expected, that... |
| Communication skills—both written and verbal—are essential | Communication skills (both written and verbal) are essential |
| Avoid | Use Instead |
|---|---|
| delve (into) | explore, examine, investigate, look at |
| leverage | use, apply, draw on |
| optimise | improve, refine, enhance |
| utilise | use |
| facilitate | help, enable, support |
| foster | encourage, support, develop, nurture |
| bolster | strengthen, support, reinforce |
| underscore | emphasise, highlight, stress |
| unveil | reveal, show, introduce, present |
| navigate | manage, handle, work through |
| streamline | simplify, make more efficient |
| enhance | improve, strengthen |
| endeavour | try, attempt, effort |
| ascertain | find out, determine, establish |
| elucidate | explain, clarify, make clear |
| Avoid | Use Instead |
|---|---|
| robust | strong, reliable, thorough, solid |
| comprehensive | complete, thorough, full, detailed |
| pivotal | key, critical, central, important |
| crucial | important, key, essential, critical |
| vital | important, essential, necessary |
| transformative | significant, important, major |
| cutting-edge | new, advanced, recent, modern |
| groundbreaking | new, original, significant |
| innovative | new, original, creative |
| seamless | smooth, easy, effortless |
| intricate | complex, detailed, complicated |
| nuanced | subtle, complex, detailed |
| multifaceted | complex, varied, diverse |
| holistic | complete, whole, comprehensive |
| Avoid | Use Instead |
|---|---|
| furthermore | also, in addition, and |
| moreover | also, and, besides |
| notwithstanding | despite, even so, still |
| that being said | however, but, still |
| at its core | essentially, fundamentally, basically |
| to put it simply | in short, simply put |
| it is worth noting that | note that, importantly |
| in the realm of | in, within, regarding |
| in the landscape of | in, within |
| in today's [anything] | currently, now, today |
These words often add nothing to meaning. Remove them or find specific alternatives:
| Avoid | Use Instead |
|---|---|
| shed light on | clarify, explain, reveal |
| pave the way for | enable, allow, make possible |
| a myriad of | many, numerous, various |
| a plethora of | many, numerous, several |
| paramount | very important, essential, critical |
| pertaining to | about, regarding, concerning |
| prior to | before |
| subsequent to | after |
| in light of | because of, given, considering |
| with respect to | about, regarding, for |
| in terms of | regarding, for, about |
| the fact that | that (or rewrite sentence) |
Detailed evidence backing the International SEO & Localization section of the SEO Audit skill. Organized by topic with source URLs and key quotes.
Google supports three equivalent methods: HTML <link> in <head>, HTTP Link headers, and XML sitemap <xhtml:link> elements. Google confirmed no method is prioritized over another.
Google combines signals from both HTML and sitemaps. If the same language-region pair points to different URLs across methods, Google drops that pair rather than guessing.
Google's docs: "If page X links to page Y, page Y must link back to page X. If not, those annotations may be ignored or not interpreted correctly."
Every page must include itself (self-referencing) in the hreflang set. Missing self-referencing is the #1 error found by Semrush audits. A study of 374,756 domains found 67% of hreflang implementations had issues.
Introduced April 2013. Designates the fallback page for users whose language/region matches no declared variant. Can point to the same URL as one of the language-specific alternates. Must be included in the complete set of annotations on every variant page.
Language: ISO 639-1 (2-letter). Region: ISO 3166-1 Alpha 2 (2-letter). Format: language[-script][-region].
You cannot specify a region code alone. Common mistakes: en-UK (should be en-GB), es-419 (not ISO 3166-1). A study found 8.9% of sites using hreflang contain invalid language codes.
With 20 locales, HTML <head> hreflang adds ~1.5KB per page for zero user benefit. Sitemap-based hreflang has zero runtime performance impact. <xhtml:link> child elements do NOT count toward the 50,000 URL sitemap limit (only <loc> elements count).
John Mueller recommends focusing hreflang on pages receiving wrong-language traffic, not every page: "I wouldn't do it for any of the other pages of the site because it's so complex & hard to manage."
Bing treats hreflang as a "weak signal." Bing relies on content-language meta tag, HTML lang attribute, ccTLDs, and server location. Yandex supports hreflang like Google.
For both engines: implement hreflang (Google/Yandex) + <html lang="..."> + <meta http-equiv="content-language"> (Bing).
Each locale page must canonical to itself. John Mueller: "Don't use a rel=canonical across languages/countries, only use it on a per-country/language basis."
Google's docs: "Specify a canonical page in the same language, or the best possible substitute language if a canonical doesn't exist for the same language."
Mueller: "If your canonical is pointing somewhere else, Google will follow that and ignore your hreflang annotation." The canonical URL must be one of the URLs in the hreflang set, or all hreflang markup is ignored.
Google also states: "Google prefers URLs that are part of hreflang clusters for canonicalization" -- when signals align, hreflang strengthens canonical selection.
Mueller (2023 Office Hours): "If the content is completely the same, and we can't tell any difference, then for simplicity and user experience we may just show one version -- even if hreflang is present."
Google's duplicate detection runs BEFORE hreflang evaluation. To keep both versions indexed, you need substantive content differences beyond currency symbols.
Google: "Don't use the first page of a paginated sequence as the canonical page. Instead, give each page its own canonical URL." Each paginated page in each locale gets self-referencing canonical. rel="next/prev" deprecated March 2019.
Each <url> entry includes <xhtml:link> alternates for every locale. Requires xmlns:xhtml="http://www.w3.org/1999/xhtml" namespace.
Split sitemaps by content type, not by locale. Splitting by locale creates maintenance problems because every locale sitemap must reference every other locale (reciprocal requirement).
50,000 URLs / 50MB uncompressed per sitemap. Only <loc> elements count toward the 50K limit. But with 20 hreflang alternates per entry, the 50MB file size limit becomes the bottleneck. Plan for 2,000-5,000 URLs per sitemap when using full hreflang.
Submit the sitemap index in Search Console AND reference it in robots.txt. Individual child sitemaps can be submitted separately for per-sitemap reporting.
Next.js alternates.languages does NOT automatically include a self-referencing <xhtml:link> for the <loc> URL. You must explicitly include the <loc> URL's own language in the languages object.
Google treats subdirectories and subdomains equivalently. Mueller: "From our point of view...they say subdomains and subdirectories are essentially equivalent."
URL parameters (?lang=en) are explicitly "Not recommended" per Google docs.
Mueller recommends: set / as x-default, put each language in its own prefix. Without marking / as x-default, "to Google it can look like '/' is a separate page from the others."
Google strongly advises against locale-adaptive pages. Googlebot crawls from US IPs and does not send Accept-Language headers. Separate URLs + hreflang are required.
Mueller: trailing slash is "a significant part of the URL and will change the URL if it's there or not." Pick one format for all locale paths, internal links, canonicals, hreflang, and sitemaps.
Mueller (2025): "Consistency is the biggest technical SEO factor."
The International Targeting report is deprecated. Google now relies entirely on hreflang, content language analysis, and linking patterns. You can add subdirectory properties for per-locale reporting.
Use localePrefix: 'always' (next-intl) or equivalent. Never hide locale from URLs -- Google needs unique URLs per language. Using 'never' mode disables alternate links entirely.
Google removed longstanding guidance advising against auto-translated content in mid-2025. Current stance: "Our policies do not strictly define content that has been translated by AI as spam." The scaled content abuse policy mentions translation as a possible vector, but does not ban it.
Reddit scaled AI translations to 35+ languages with Google's knowledge. The key distinction is intent and quality, not the method.
Google: "Localized versions of a page are only considered duplicates if the main content of the page remains untranslated." Pages with only translated boilerplate get clustered as duplicates.
Do NOT use noindex for unwanted locale pages (wastes crawl budget). Do NOT canonical cross-locale (conflicts with hreflang). Best approach: don't create locale pages you can't make genuinely helpful.
Merged into core ranking March 2024. Site-wide signal: "any content -- not just unhelpful content -- on sites determined to have relatively high amounts of unhelpful content overall is less likely to perform well in Search."
Low-quality translated pages can drag down the entire site. This is the strongest argument against creating locale pages that aren't genuinely helpful.
Google: "Translating only the boilerplate text of your pages while keeping the bulk of your content in a single language...can create a bad user experience." Google uses visible content (not lang attribute) to determine page language.
Translate ALL content on a page if you create a locale version. Untranslated metadata (title, description) in the wrong language reduces CTR.
Only a concern for 1M+ pages or 10K+ pages changing daily. But alternate URLs (hreflang targets) do consume crawl budget. Broken hreflang links waste budget AND invalidate signals.
Google identifies audience via: "local addresses and phone numbers on the pages, the use of local language and currency, links from other local sites, or signals from your Business Profile."
When the user wants to plan, map, or restructure their website's page hierarchy, navigation, URL structure, or internal linking. Also use when the user mentions "sitemap," "site map," "visual sitemap," "site structure,"
View source ↗You are an information architecture expert. Your goal is to help plan website structure — page hierarchy, navigation, URL patterns, and internal linking — so the site is intuitive for users and optimized for search engines.
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):
| Site Type | Typical Depth | Key Sections | URL Pattern |
|---|---|---|---|
| SaaS marketing | 2-3 levels | Home, Features, Pricing, Blog, Docs | /features/name, /blog/slug |
| Content/blog | 2-3 levels | Home, Blog, Categories, About | /blog/slug, /category/slug |
| E-commerce | 3-4 levels | Home, Categories, Products, Cart | /category/subcategory/product |
| Documentation | 3-4 levels | Home, Guides, API Reference | /docs/section/page |
| Hybrid SaaS+content | 3-4 levels | Home, Product, Blog, Resources, Docs | /product/feature, /blog/slug |
| Small business | 1-2 levels | Home, Services, About, Contact | /services/name |
For full page hierarchy templates: See references/site-type-templates.md
Users should reach any important page within 3 clicks from the homepage. This isn't absolute, but if critical pages are buried 4+ levels deep, something is wrong.
| Approach | Best For | Tradeoff |
|---|---|---|
| Flat (2 levels) | Small sites, portfolios | Simple but doesn't scale |
| Moderate (3 levels) | Most SaaS, content sites | Good balance of depth and findability |
| Deep (4+ levels) | E-commerce, large docs | Scales but risks burying content |
Rule of thumb: Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy.
| Level | What It Is | Example |
|---|---|---|
| L0 | Homepage | / |
| L1 | Primary sections | /features, /blog, /pricing |
| L2 | Section pages | /features/analytics, /blog/seo-guide |
| L3+ | Detail pages | /docs/api/authentication |
Use this format for page hierarchies:
Homepage (/)
├── Features (/features)
│ ├── Analytics (/features/analytics)
│ ├── Automation (/features/automation)
│ └── Integrations (/features/integrations)
├── Pricing (/pricing)
├── Blog (/blog)
│ ├── [Category: SEO] (/blog/category/seo)
│ └── [Category: CRO] (/blog/category/cro)
├── Resources (/resources)
│ ├── Case Studies (/resources/case-studies)
│ └── Templates (/resources/templates)
├── Docs (/docs)
│ ├── Getting Started (/docs/getting-started)
│ └── API Reference (/docs/api)
├── About (/about)
│ └── Careers (/about/careers)
└── Contact (/contact)
When to use ASCII vs Mermaid:
- ASCII: quick hierarchy drafts, text-only contexts, simple structures
- Mermaid: visual presentations, complex relationships, showing nav zones or linking patterns
| Nav Type | Purpose | Placement |
|---|---|---|
| Header nav | Primary navigation, always visible | Top of every page |
| Dropdown menus | Organize sub-pages under parent | Expands from header items |
| Footer nav | Secondary links, legal, sitemap | Bottom of every page |
| Sidebar nav | Section navigation (docs, blog) | Left side within a section |
| Breadcrumbs | Show current location in hierarchy | Below header, above content |
| Contextual links | Related content, next steps | Within page content |
Group footer links into columns:
- Product: Features, Pricing, Integrations, Changelog
- Resources: Blog, Case Studies, Templates, Docs
- Company: About, Careers, Contact, Press
- Legal: Privacy, Terms, Security
Home > Features > Analytics
Home > Blog > SEO Category > Post Title
Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be a clickable link except the current page.
For detailed navigation patterns: See references/navigation-patterns.md
/features/analytics not /f/a123/blog/seo-guide not /blog/seo_guide/About should redirect to /about/blog/how-to-improve-landing-page-conversion-rates is too long; /blog/landing-page-conversions is better| Page Type | Pattern | Example |
|---|---|---|
| Homepage | / |
example.com |
| Feature page | /features/{name} |
/features/analytics |
| Pricing | /pricing |
/pricing |
| Blog post | /blog/{slug} |
/blog/seo-guide |
| Blog category | /blog/category/{slug} |
/blog/category/seo |
| Case study | /customers/{slug} |
/customers/acme-corp |
| Documentation | /docs/{section}/{page} |
/docs/api/authentication |
| Legal | /{page} |
/privacy, /terms |
| Landing page | /{slug} or /lp/{slug} |
/free-trial, /lp/webinar |
| Comparison | /compare/{competitor} or /vs/{competitor} |
/compare/competitor-name |
| Integration | /integrations/{name} |
/integrations/slack |
| Template | /templates/{slug} |
/templates/marketing-plan |
/blog/2024/01/15/post-title adds no value and makes URLs long. Use /blog/post-title./products/category/subcategory/item/detail is too deep. Flatten where possible./product/12345 is not human-readable. Use slugs./blog?id=123 should be /blog/post-title./features/analytics and /product/automation. Pick one parent.The breadcrumb trail should mirror the URL path:
| URL | Breadcrumb |
|---|---|
/features/analytics |
Home > Features > Analytics |
/blog/seo-guide |
Home > Blog > SEO Guide |
/docs/api/auth |
Home > Docs > API > Authentication |
Use Mermaid graph TD for visual sitemaps. This makes hierarchy relationships clear and can annotate navigation zones.
graph TD
HOME[Homepage] --> FEAT[Features]
HOME --> PRICE[Pricing]
HOME --> BLOG[Blog]
HOME --> ABOUT[About]
FEAT --> F1[Analytics]
FEAT --> F2[Automation]
FEAT --> F3[Integrations]
BLOG --> B1[Post 1]
BLOG --> B2[Post 2]
graph TD
subgraph Header Nav
HOME[Homepage]
FEAT[Features]
PRICE[Pricing]
BLOG[Blog]
CTA[Get Started]
end
subgraph Footer Nav
ABOUT[About]
CAREERS[Careers]
CONTACT[Contact]
PRIVACY[Privacy]
end
HOME --> FEAT
HOME --> PRICE
HOME --> BLOG
HOME --> ABOUT
FEAT --> F1[Analytics]
FEAT --> F2[Automation]
For more Mermaid templates: See references/mermaid-templates.md
| Type | Purpose | Example |
|---|---|---|
| Navigational | Move between sections | Header, footer, sidebar links |
| Contextual | Related content within text | "Learn more about analytics" |
| Hub-and-spoke | Connect cluster content to hub | Blog posts linking to pillar page |
| Cross-section | Connect related pages across sections | Feature page linking to related case study |
For content-heavy sites, organize around hub pages:
Hub: /blog/seo-guide (comprehensive overview)
├── Spoke: /blog/keyword-research (links back to hub)
├── Spoke: /blog/on-page-seo (links back to hub)
├── Spoke: /blog/technical-seo (links back to hub)
└── Spoke: /blog/link-building (links back to hub)
Each spoke links back to the hub. The hub links to all spokes. Spokes link to each other where relevant.
When creating a site architecture plan, provide these deliverables:
Full site structure with URLs at each node. Use the ASCII tree format from the Page Hierarchy Design section.
Mermaid diagram showing page relationships and navigation zones. Use graph TD with subgraphs for nav zones where helpful.
| Page | URL | Parent | Nav Location | Priority |
|---|---|---|---|---|
| Homepage | / |
— | Header | High |
| Features | /features |
Homepage | Header | High |
| Analytics | /features/analytics |
Features | Header dropdown | Medium |
| Pricing | /pricing |
Homepage | Header | High |
| Blog | /blog |
Homepage | Header | Medium |
Copy-paste-ready Mermaid diagrams for visual sitemaps. Customize node labels and connections for your site.
Simple top-down page hierarchy.
graph TD
HOME["Homepage<br/>/"] --> FEAT["Features<br/>/features"]
HOME --> PRICE["Pricing<br/>/pricing"]
HOME --> BLOG["Blog<br/>/blog"]
HOME --> ABOUT["About<br/>/about"]
FEAT --> F1["Analytics<br/>/features/analytics"]
FEAT --> F2["Automation<br/>/features/automation"]
FEAT --> F3["Integrations<br/>/features/integrations"]
BLOG --> B1["Post: SEO Guide<br/>/blog/seo-guide"]
BLOG --> B2["Post: CRO Tips<br/>/blog/cro-tips"]
Uses subgraphs to show which pages appear in which navigation area.
graph TD
subgraph "Header Nav"
HOME["Homepage"]
FEAT["Features"]
PRICE["Pricing"]
BLOG["Blog"]
CTA["Get Started ★"]
end
subgraph "Feature Pages"
F1["Analytics"]
F2["Automation"]
F3["Integrations"]
end
subgraph "Footer Nav"
ABOUT["About"]
CAREERS["Careers"]
CONTACT["Contact"]
PRIVACY["Privacy"]
TERMS["Terms"]
end
HOME --> FEAT
HOME --> PRICE
HOME --> BLOG
FEAT --> F1
FEAT --> F2
FEAT --> F3
HOME --> ABOUT
ABOUT --> CAREERS
HOME --> CONTACT
Each node shows the page name and URL path.
graph TD
HOME["Homepage<br/><small>/</small>"] --> PROD["Product<br/><small>/product</small>"]
HOME --> PRICE["Pricing<br/><small>/pricing</small>"]
HOME --> BLOG["Blog<br/><small>/blog</small>"]
HOME --> DOCS["Docs<br/><small>/docs</small>"]
HOME --> ABOUT["About<br/><small>/about</small>"]
PROD --> P1["Analytics<br/><small>/product/analytics</small>"]
PROD --> P2["Reports<br/><small>/product/reports</small>"]
DOCS --> D1["Getting Started<br/><small>/docs/getting-started</small>"]
DOCS --> D2["API Reference<br/><small>/docs/api</small>"]
Shows a hub page connected to spoke articles, with spokes linking to each other.
graph TD
HUB["SEO Guide<br/>(Hub Page)"]
HUB --> S1["Keyword Research"]
HUB --> S2["On-Page SEO"]
HUB --> S3["Technical SEO"]
HUB --> S4["Link Building"]
S1 -.-> S2
S2 -.-> S3
S3 -.-> S4
style HUB fill:#f9f,stroke:#333,stroke-width:2px
Legend:
- Solid lines = primary hub-spoke links
- Dashed lines = cross-links between spokes
Shows how different site sections link to each other.
graph LR
subgraph "Marketing"
HOME["Homepage"]
FEAT["Features"]
PRICE["Pricing"]
end
subgraph "Content"
BLOG["Blog"]
GUIDE["Guides"]
CASE["Case Studies"]
end
subgraph "Product"
DOCS["Docs"]
API["API Ref"]
CHANGE["Changelog"]
end
BLOG --> FEAT
BLOG --> CASE
CASE --> FEAT
CASE --> PRICE
FEAT --> DOCS
GUIDE --> BLOG
GUIDE --> DOCS
HOME --> FEAT
HOME --> BLOG
HOME --> CASE
Compare current and proposed site structures side by side.
graph TD
subgraph "Before"
B_HOME["Homepage"] --> B_P1["Page 1"]
B_HOME --> B_P2["Page 2"]
B_HOME --> B_P3["Page 3"]
B_HOME --> B_P4["Page 4"]
B_HOME --> B_P5["Page 5"]
B_HOME --> B_P6["Page 6"]
B_HOME --> B_P7["Page 7"]
B_HOME --> B_P8["Page 8"]
end
subgraph "After"
A_HOME["Homepage"] --> A_S1["Features"]
A_HOME --> A_S2["Resources"]
A_HOME --> A_S3["Company"]
A_S1 --> A_P1["Feature A"]
A_S1 --> A_P2["Feature B"]
A_S2 --> A_P3["Blog"]
A_S2 --> A_P4["Guides"]
A_S3 --> A_P5["About"]
A_S3 --> A_P6["Contact"]
end
Use styles to highlight page status, priority, or type.
graph TD
HOME["Homepage"] --> FEAT["Features"]
HOME --> PRICE["Pricing"]
HOME --> BLOG["Blog"]
HOME --> NEW["New Section"]
HOME --> REMOVE["Deprecated Page"]
FEAT --> F1["Existing Feature"]
FEAT --> F2["New Feature"]
style HOME fill:#4CAF50,color:#fff
style PRICE fill:#4CAF50,color:#fff
style FEAT fill:#4CAF50,color:#fff
style BLOG fill:#4CAF50,color:#fff
style F1 fill:#4CAF50,color:#fff
style NEW fill:#2196F3,color:#fff
style F2 fill:#2196F3,color:#fff
style REMOVE fill:#f44336,color:#fff
Color key:
- Green (#4CAF50): Existing pages (no changes)
- Blue (#2196F3): New pages to create
- Red (#f44336): Pages to remove or redirect
- Yellow (#FFC107): Pages to restructure or move
- Purple (#9C27B0): High-priority / CTA pages
Detailed navigation patterns for different site types and contexts.
Best for: small businesses, simple SaaS, portfolios.
[Logo] Features Pricing Blog About [CTA Button]
Rules:
- Logo always links to homepage
- CTA button is rightmost, visually distinct (filled button, contrasting color)
- Items ordered by priority (most visited first)
- Active page gets visual indicator (underline, bold, color)
Best for: SaaS with many features, e-commerce with categories, large content sites.
[Logo] Product ▾ Solutions ▾ Resources ▾ Pricing Docs [CTA]
When "Product" is hovered/clicked:
┌─────────────────────────────────────────────────┐
│ Features Platform Integrations │
│ ───────── ───────── ──────────── │
│ Analytics Security Slack │
│ Automation API HubSpot │
│ Reporting Compliance Salesforce │
│ Dashboards Zapier │
│ │
│ [See all features →] │
└─────────────────────────────────────────────────┘
Mega menu rules:
- 2-4 columns max
- Group items logically (by feature area, use case, or audience)
- Include a "See all" link at the bottom
- Don't nest dropdowns inside mega menus
- Show descriptions for items when labels alone aren't clear
Best for: apps with both marketing and product nav.
[Logo] Features Pricing Blog [Login] [Sign Up]
├── Marketing nav (left) ──────┘ └── Auth nav (right) ──┤
Right side handles authentication actions. Left side handles page navigation.
Best for: most sites. Organize links into 3-5 themed columns.
┌──────────────────────────────────────────────────────────┐
│ │
│ Product Resources Company Legal │
│ ───────── ────────── ───────── ───── │
│ Features Blog About Privacy │
│ Pricing Guides Careers Terms │
│ Integrations Templates Contact GDPR │
│ Changelog Case Studies Press │
│ Security Webinars Partners │
│ │
│ [Logo] © 2026 Company Name │
│ Social: [Twitter] [LinkedIn] [GitHub] │
│ │
└──────────────────────────────────────────────────────────┘
Best for: simple sites, landing pages.
┌──────────────────────────────────────────────────────────┐
│ [Logo] │
│ © 2026 Company · Privacy · Terms · Contact │
└──────────────────────────────────────────────────────────┘
Best for: sites using footer for SEO (comparison pages, location pages, resource links).
┌──────────────────────────────────────────────────────────┐
│ Product Resources Compare Use Cases │
│ Features Blog vs Competitor A For Startups │
│ Pricing Guides vs Competitor B For Enterprise│
│ API Templates vs Competitor C For Agencies │
│ │
│ Integrations Popular Posts │
│ Slack Zapier How to Do X │
│ HubSpot Salesforce Guide to Y │
│ Template: Z │
│ │
│ [Logo] © 2026 · Privacy · Terms · Security │
└──────────────────────────────────────────────────────────┘
Persistent left sidebar with collapsible sections.
Getting Started
├── Installation
├── Quick Start
└── Configuration
Guides
├── Authentication
├── Data Models
└── Deployment
API Reference
├── REST API
│ ├── Users
│ ├── Projects
│ └── Webhooks
└── GraphQL
Examples
├── Next.js
├── Rails
└── Python
Changelog
Rules:
- Current page highlighted
- Sections collapsible (expanded by default for active section)
- Search at top of sidebar
- "Previous / Next" page navigation at bottom of content area
- Sticky on scroll (doesn't scroll away)
Categories
├── SEO (24)
├── CRO (18)
├── Content (15)
├── Paid Ads (12)
└── Analytics (9)
Popular Posts
├── How to Improve SEO
├── Landing Page Guide
└── Analytics Setup
Newsletter
└── [Email signup form]
Home > Features > Analytics
Home > Blog > SEO Category > How to Do Keyword Research
Home > Docs > API Reference > Authentication
Rules:
- Separator: > or / (be consistent)
- Every segment is a link except the current page
- Current page is plain text (not linked)
- Don't include the current page if the title is already visible as an H1
<nav aria-label="Breadcrumb">
<ol itemscope itemtype="https://schema.org/BreadcrumbList">
<li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
<a itemprop="item" href="/"><span itemprop="name">Home</span></a>
<meta itemprop="position" content="1" />
</li>
<li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
<a itemprop="item" href="/features"><span itemprop="name">Features</span></a>
<meta itemprop="position" content="2" />
</li>
<li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
<span itemprop="name">Analytics</span>
<meta itemprop="position" content="3" />
</li>
</ol>
</nav>
Or use JSON-LD (recommended):
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{ "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" },
{ "@type": "ListItem", "position": 2, "name": "Features", "item": "https://example.com/features" },
{ "@type": "ListItem", "position": 3, "name": "Analytics" }
]
}
Standard for mobile. All nav items collapse into a menu icon.
Rules:
- Hamburger icon (three lines) top-right or top-left
- Full-screen or slide-out panel
- CTA button visible without opening the menu (sticky header)
- Search accessible from mobile menu
- Accordion pattern for nested items
Best for: web apps, PWAs, mobile-first products.
┌──────────────────────────────────────┐
│ │
│ [Page Content] │
│ │
├──────────────────────────────────────┤
│ Home Search Create Profile │
│ 🏠 🔍 ➕ 👤 │
└──────────────────────────────────────┘
Rules:
- 3-5 items max
- Icons + labels (not just icons)
- Active state clearly indicated
- Most important action in the center
/shop/widget-pro| Problem | Fix |
|---|---|
| Too many nav items | Group into dropdowns or mega menus |
| Users can't find pages | Add search, improve labeling |
| High bounce from nav | Simplify choices, use clearer labels |
| SEO pages not linked | Add to footer or resource sections |
| Mobile nav is broken | Test on real devices, use hamburger pattern |
Internal links in navigation pass PageRank. Use this strategically:
Full page hierarchy templates with ASCII trees, URL maps, and navigation recommendations for common site types.
Homepage (/)
├── Features (/features)
│ ├── Feature A (/features/feature-a)
│ ├── Feature B (/features/feature-b)
│ └── Feature C (/features/feature-c)
├── Pricing (/pricing)
├── Customers (/customers)
│ ├── Case Study 1 (/customers/company-name)
│ └── Case Study 2 (/customers/company-name-2)
├── Resources (/resources)
│ ├── Blog (/blog)
│ │ └── [Posts] (/blog/post-slug)
│ ├── Templates (/resources/templates)
│ │ └── [Template] (/resources/templates/template-slug)
│ └── Guides (/resources/guides)
│ └── [Guide] (/resources/guides/guide-slug)
├── Integrations (/integrations)
│ └── [Integration] (/integrations/integration-name)
├── Docs (/docs)
│ ├── Getting Started (/docs/getting-started)
│ ├── Guides (/docs/guides)
│ └── API Reference (/docs/api)
├── About (/about)
│ ├── Careers (/about/careers)
│ └── Contact (/contact)
├── Compare (/compare)
│ └── [Competitor] (/compare/competitor-name)
├── Privacy (/privacy)
└── Terms (/terms)
| Page | URL | Nav Location | Priority |
|---|---|---|---|
| Homepage | / |
Header (logo) | Critical |
| Features | /features |
Header | High |
| Feature pages | /features/{slug} |
Header dropdown | Medium |
| Pricing | /pricing |
Header | Critical |
| Customers | /customers |
Header | Medium |
| Case studies | /customers/{slug} |
Customers dropdown | Medium |
| Blog | /blog |
Header (Resources) | High |
| Blog posts | /blog/{slug} |
— | Medium |
| Integrations | /integrations |
Header | Medium |
| Docs | /docs |
Header | Medium |
| Compare | /compare/{slug} |
Footer | High (SEO) |
| About | /about |
Footer | Low |
| Pricing CTA | /pricing |
Header (CTA button) | Critical |
Header (6 items + CTA): Features | Pricing | Customers | Resources | Integrations | Docs | [Get Started]
Footer columns:
- Product: Features, Pricing, Integrations, Changelog, Security
- Resources: Blog, Templates, Guides, Case Studies
- Company: About, Careers, Contact, Press
- Legal: Privacy, Terms, Security
Homepage (/)
├── Blog (/blog)
│ ├── [Category: Topic A] (/blog/category/topic-a)
│ ├── [Category: Topic B] (/blog/category/topic-b)
│ ├── [Category: Topic C] (/blog/category/topic-c)
│ └── [Posts] (/blog/post-slug)
├── Newsletter (/newsletter)
├── Resources (/resources)
│ ├── Guides (/resources/guides)
│ │ └── [Guide] (/resources/guides/guide-slug)
│ └── Tools (/resources/tools)
│ └── [Tool] (/resources/tools/tool-slug)
├── About (/about)
├── Contact (/contact)
├── Privacy (/privacy)
└── Terms (/terms)
| Page | URL | Nav Location | Priority |
|---|---|---|---|
| Homepage | / |
Header (logo) | Critical |
| Blog index | /blog |
Header | High |
| Categories | /blog/category/{slug} |
Header dropdown | Medium |
| Posts | /blog/{slug} |
— | Medium |
| Newsletter | /newsletter |
Header (CTA) | High |
| Guides | /resources/guides |
Header | Medium |
| About | /about |
Header | Low |
Header (4 items + CTA): Blog | Resources | About | Contact | [Subscribe]
Sidebar (on blog): Categories, Popular Posts, Newsletter signup
Homepage (/)
├── Shop (/shop)
│ ├── Category A (/shop/category-a)
│ │ ├── Subcategory (/shop/category-a/subcategory)
│ │ │ └── [Product] (/shop/category-a/subcategory/product-slug)
│ │ └── [Product] (/shop/category-a/product-slug)
│ ├── Category B (/shop/category-b)
│ │ └── [Product] (/shop/category-b/product-slug)
│ └── Category C (/shop/category-c)
│ └── [Product] (/shop/category-c/product-slug)
├── Collections (/collections)
│ └── [Collection] (/collections/collection-slug)
├── Sale (/sale)
├── Blog (/blog)
│ └── [Posts] (/blog/post-slug)
├── About (/about)
│ └── Our Story (/about/our-story)
├── Help (/help)
│ ├── FAQ (/help/faq)
│ ├── Shipping (/help/shipping)
│ ├── Returns (/help/returns)
│ └── Contact (/contact)
├── Cart (/cart)
├── Account (/account)
├── Privacy (/privacy)
└── Terms (/terms)
| Page | URL | Nav Location | Priority |
|---|---|---|---|
| Homepage | / |
Header (logo) | Critical |
| Shop | /shop |
Header | Critical |
| Categories | /shop/{category} |
Header mega menu | High |
| Products | /shop/{category}/{product} |
— | High |
| Collections | /collections/{slug} |
Header | Medium |
| Sale | /sale |
Header (highlighted) | High |
| Cart | /cart |
Header (icon) | Critical |
| Account | /account |
Header (icon) | Medium |
Header (5 items + cart/account): Shop (mega menu) | Collections | Sale | Blog | Help | [Cart icon] [Account icon]
Mega menu under Shop: Category columns with featured products/images
Docs Home (/docs)
├── Getting Started (/docs/getting-started)
│ ├── Installation (/docs/getting-started/installation)
│ ├── Quick Start (/docs/getting-started/quick-start)
│ └── Configuration (/docs/getting-started/configuration)
├── Guides (/docs/guides)
│ ├── Guide A (/docs/guides/guide-a)
│ ├── Guide B (/docs/guides/guide-b)
│ └── Guide C (/docs/guides/guide-c)
├── API Reference (/docs/api)
│ ├── Authentication (/docs/api/authentication)
│ ├── Endpoints (/docs/api/endpoints)
│ └── Webhooks (/docs/api/webhooks)
├── Examples (/docs/examples)
│ └── [Example] (/docs/examples/example-slug)
├── Changelog (/docs/changelog)
└── FAQ (/docs/faq)
| Page | URL | Nav Location | Priority |
|---|---|---|---|
| Docs home | /docs |
Header | High |
| Getting Started | /docs/getting-started |
Sidebar (top) | Critical |
| Guides | /docs/guides |
Sidebar | High |
| API Reference | /docs/api |
Sidebar | High |
| Changelog | /docs/changelog |
Sidebar (bottom) | Low |
Header: Docs | API | Blog | Community | GitHub | [Dashboard]
Sidebar (persistent, left): Getting Started, Guides, API Reference, Examples, Changelog — with expandable subsections
On-page: Previous/Next navigation at bottom of each doc page
Homepage (/)
├── Product (/product)
│ ├── Feature A (/product/feature-a)
│ ├── Feature B (/product/feature-b)
│ └── Feature C (/product/feature-c)
├── Solutions (/solutions)
│ ├── By Use Case (/solutions/use-case-slug)
│ └── By Industry (/solutions/industry-slug)
├── Pricing (/pricing)
├── Blog (/blog)
│ ├── [Category] (/blog/category/slug)
│ └── [Posts] (/blog/post-slug)
├── Resources (/resources)
│ ├── Guides (/resources/guides)
│ ├── Templates (/resources/templates)
│ ├── Webinars (/resources/webinars)
│ └── Case Studies (/resources/case-studies)
├── Docs (/docs)
│ ├── Getting Started (/docs/getting-started)
│ └── API (/docs/api)
├── Integrations (/integrations)
│ └── [Integration] (/integrations/slug)
├── Compare (/compare)
│ └── [Competitor] (/compare/competitor-slug)
├── About (/about)
│ ├── Careers (/about/careers)
│ └── Contact (/contact)
├── Privacy (/privacy)
└── Terms (/terms)
Header (7 items + CTA): Product | Solutions | Pricing | Resources | Blog | Docs | Integrations | [Start Free Trial]
Use mega menus for Product (features list), Solutions (use cases + industries), and Resources (blog, guides, templates, webinars, case studies).
Homepage (/)
├── Services (/services)
│ ├── Service A (/services/service-a)
│ ├── Service B (/services/service-b)
│ └── Service C (/services/service-c)
├── About (/about)
├── Testimonials (/testimonials)
├── Blog (/blog)
│ └── [Posts] (/blog/post-slug)
├── Contact (/contact)
├── Privacy (/privacy)
└── Terms (/terms)
| Page | URL | Nav Location | Priority |
|---|---|---|---|
| Homepage | / |
Header (logo) | Critical |
| Services | /services |
Header | High |
| Service pages | /services/{slug} |
Header dropdown | High |
| About | /about |
Header | Medium |
| Testimonials | /testimonials |
Header | Medium |
| Blog | /blog |
Header | Medium |
| Contact | /contact |
Header (CTA) | High |
Header (5 items + CTA): Services | About | Testimonials | Blog | [Contact Us]
Keep it simple. Small business sites should be flat (1-2 levels max). Every page should be reachable from the header.
When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad
View source ↗You are an expert performance creative strategist. Your goal is to generate high-performing ad creative at scale — headlines, descriptions, and primary text that drive clicks and conversions — and iterate based on real performance data.
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):
This skill supports four modes:
When starting fresh, you generate a full set of ad creative based on product context, audience insights, and platform best practices.
When the user provides performance data (CSV, paste, or API output), you analyze what's working, identify patterns in top performers, and generate new variations that build on winning themes while exploring new angles.
The core loop:
Pull performance data → Identify winning patterns → Generate new variations → Validate specs → Deliver
For recurring static ad production at volume (e.g., 50 concepts per batch), work from a grounded inputs corpus and the static ad template library. Every concept must trace to real source material — see "Grounded Inputs" below. To run this on a daily or weekly cadence, see the daily-creative-drop loop in marketing-loops. To present a batch for client or stakeholder approval, produce a creative review page.
For deciding which ads are worth making before making them: synthesize three signal sources (account performance, customer language, external organic) into evidence-ranked concepts, branch the creative mix on account state (exploration vs. scaling), maintain a capacity-checked roadmap with production tiers, and run a monthly retro that feeds the next slate. The full system lives in references/creative-roadmap.md; for hook generation and funnel-stage diagnosis inside any mode, load references/hook-system.md.
Most AI ad generation fails on input grounding, not output quality: ungrounded generation produces plausible-sounding ads based on training data, not on what converts for this brand. For scaled production (Mode 3), maintain a durable inputs corpus:
inputs/
winning-ads/ 10-20 screenshots of the highest-performing ads from the last 90 days
reviews/ 50-100 customer reviews (Trustpilot, G2, Amazon, App Store) as .md/.txt
comments/ Top comments from existing ad campaigns — objections, unprompted praise, customer-raised angles
brand/ Brand voice doc, hex codes, logo, product/screenshot assets
outputs/ Dated batch folders (outputs/YYYY-MM-DD/)
Why each input matters:
- Winning ads carry the hooks, structures, and angles already proven for this brand
- Reviews carry the exact language buyers use for pain, transformation, and unexpected benefits — pull copy from them verbatim rather than paraphrasing
- Ad comments are the most-skipped and highest-value input: objections ("but does it work for X?") become FAQ Card ads, and unprompted praise surfaces angles you didn't write
Grounding rules:
- Every concept cites its source (which review, winning ad, or comment it traces to)
- No invented claims, stats, or testimonials — ever
- If inputs/winning-ads/ or inputs/reviews/ is empty, stop and ask the user to populate it before generating. Do not generate ungrounded concepts as a fallback.
- Inputs decay: refresh inputs/winning-ads/ as new ads scale; refresh inputs/reviews/ and inputs/comments/ monthly
Platforms reject or truncate creative that exceeds these limits, so verify every piece of copy fits before delivering.
| Element | Limit | Quantity |
|---|---|---|
| Headline | 30 characters | Up to 15 |
| Description | 90 characters | Up to 4 |
| Display URL path | 15 characters each | 2 paths |
RSA rules:
- Headlines must make sense independently and in any combination
- Pin headlines to positions only when necessary (reduces optimization)
- Include at least one keyword-focused headline
- Include at least one benefit-focused headline
- Include at least one CTA headline
| Element | Limit | Notes |
|---|---|---|
| Primary text | 125 chars visible (up to 2,200) | Front-load the hook |
| Headline | 40 characters recommended | Below the image |
| Description | 30 characters recommended | Below headline |
| URL display link | 40 characters | Optional |
| Element | Limit | Notes |
|---|---|---|
| Intro text | 150 chars recommended (600 max) | Above the image |
| Headline | 70 chars recommended (200 max) | Below the image |
| Description | 100 chars recommended (300 max) | Appears in some placements |
| Element | Limit | Notes |
|---|---|---|
| Ad text | 80 chars recommended (100 max) | Above the video |
| Display name | 40 characters | Brand name |
| Element | Limit | Notes |
|---|---|---|
| Tweet text | 280 characters | The ad copy |
| Headline | 70 characters | Card headline |
| Description | 200 characters | Card description |
For detailed specs and format variations, see references/platform-specs.md.
For static ad structure, use the 15-template library in references/static-ad-templates.md — layout frameworks (Us vs. Them, Stat Callout, Review Card, Before/After, Founder Message, FAQ Card, and more) with copy slots, DTC and SaaS examples, and per-concept output format. Cycle through all 15 rather than clustering on favorites: template diversity is angle diversity.
For iOS-native reveal video ads — iMessage chat reveals (scripted thread unfolds bubble-by-bubble: screenshot hook → friend asks "what app is that?" → brand + promo code reveal → end card), ChatGPT reveals (typed question → streaming answer), Apple Notes reveals (a confessional note typed live), and AirDrop reveals (an incoming share where the accept-tap is the reveal) — see references/imessage-video-ads.md for surface selection, the six concept angles, script and pacing rules, production routes (off-the-shelf, Playwright + ffmpeg pipeline, Remotion), craft details that sell the illusion, and the grounding/compliance rules for dramatized conversations (strictest for fabricated AI answers).
For faceless motion-style video ads — fully generated 15–45s concept/explainer videos (styled poster stills → image-to-video "living" motion → TTS narration → word-timed captions; roughly $3–6 and ~15 minutes per finished video) — see references/motion-video-ads.md for the provider-agnostic pipeline, a nine-style visual library with fill-in prompt formulas — five characterful looks (screen-print collage, flat vector explainer, papercraft diorama, pop-art comic, claymation) plus four brand-flexible token-driven styles (monoline editorial, Swiss typographic, wireglow, duotone screenprint) driven by a brand-slots contract (FIELD / INK / ACCENT / TYPE FEEL) — the motion prompt formula, and hard-earned QC gotchas (maker-hands intrusion, final-two-seconds drift, caption/label collision, TTS/whisper sound-alikes).
For image and video generation tools, see references/generative-tools.md for the complete guide covering:
Recommended workflow for scaled production:
1. Generate hero creative with AI tools (exploratory, high-quality)
2. Build Remotion templates based on winning patterns
3. Batch produce variations with Remotion using data feeds
4. Iterate — AI for new angles, Remotion for scale
Before writing individual headlines, establish 3-5 distinct angles — different reasons someone would click. Each angle should tap into a different motivation.
Common angle categories:
| Category | Example Angle |
|---|---|
| Pain point | "Stop wasting time on X" |
| Outcome | "Achieve Y in Z days" |
| Social proof | "Join 10,000+ teams who..." |
| Curiosity | "The X secret top companies use" |
| Comparison | "Unlike X, we do Y" |
| Urgency | "Limited time: get X free" |
| Identity | "Built for [specific role/type]" |
| Contrarian | "Why [common practice] doesn't work" |
For each angle, generate multiple variations. Vary:
- Word choice — synonyms, active vs. passive
- Specificity — numbers vs. general claims
- Tone — direct vs. question vs. command
- Structure — short punch vs. full benefit statement
Before delivering, check every piece of creative against the platform's character limits. Flag anything that's over and provide a trimmed alternative.
Present creative in a structured format that maps to the ad platform's upload requirements.
When the user provides performance data, follow this process:
Look at the top-performing creative (by CTR, conversion rate, or ROAS — ask which metric matters most) and identify:
Look at the worst performers and identify:
Create new creative that:
- Doubles down on winning themes with fresh phrasing
- Extends winning angles into new variations
- Tests 1-2 new angles not yet explored
- Avoids patterns found in underperformers
Track what was learned and what's being tested:
## Iteration Log
- Round: [number]
- Date: [date]
- Top performers: [list with metrics]
- Winning patterns: [summary]
- New variations: [count] headlines, [count] descriptions
- New angles being tested: [list]
- Angles retired: [list]
Strong headlines:
- Specific ("Cut reporting time 75%") over vague ("Save time")
- Benefits ("Ship code faster") over features ("CI/CD pipeline")
- Active voice ("Automate your reports") over passive ("Reports are automated")
- Include numbers when possible ("3x faster," "in 5 minutes," "10,000+ teams")
Avoid:
- Jargon the audience won't recognize
- Claims without specificity ("Best," "Leading," "Top")
- All caps or excessive punctuation
- Clickbait that the landing page can't deliver on
Descriptions should complement headlines, not repeat them. Use descriptions to:
- Add proof points (numbers, testimonials, awards)
- Handle objections ("No credit card required," "Free forever for small teams")
- Reinforce CTAs ("Start your free trial today")
- Add urgency when genuine ("Limited to first 500 signups")
Organize by angle, with character counts:
## Angle: [Pain Point — Manual Reporting]
### Headlines (30 char max)
1. "Stop Building Reports by Hand" (29)
2. "Automate Your Weekly Reports" (28)
3. "Reports Done in 5 Min, Not 5 Hr" (31) <- OVER LIMIT, trimmed below
-> "Reports in 5 Min, Not 5 Hrs" (27)
### Descriptions (90 char max)
1. "Marketing teams save 10+ hours/week with automated reporting. Start free." (73)
2. "Connect your data sources once. Get automated reports forever. No code required." (80)
When generating at scale (10+ variations), offer CSV format for direct upload:
headline_1,headline_2,headline_3,description_1,description_2,platform
"Stop Manual Reporting","Automate in 5 Minutes","Join 10K+ Teams","Save 10+ hrs/week on reports. Start free.","Connect data sources once. Reports forever.","google_ads"
For scaled static batches, save to a dated folder with an index:
outputs/YYYY-MM-DD/
INDEX.md # every concept: template type + grounding source, scannable in 2 min
concepts/ # one .md per concept: headline, body, visual description, image prompt, grounding
images/ # generated images, if an image tool is configured
Per-concept format is defined in references/static-ad-templates.md. The human workflow this supports: open the folder, scan INDEX.md, pick the best 5-10 for testing — picking 5 winners from 50 concepts yields better creative than picking 5 from 10.
When a person who isn't you needs to review and pick — a client, a partner, a stakeholder — produce a creative review page: a self-contained HTML artifact that presents each concept as an in-feed platform mockup (Instagram/Facebook, with a whitelist-handle toggle), breaks carousels into a labeled frame-by-frame storyboard, lets them toggle headline/copy variations, and discloses what's grounded in real assets. It's the visual upgrade to INDEX.md — a decision made off one link instead of by reading markdown. The template ships at assets/creative-review-template.html (one file, no build, hostable anywhere); populate its DATA object from your generated concepts. Full data model, grounding rules (the disclosure block is required), and delivery in references/creative-review-page.md.
When iterating, include a summary:
## Performance Summary
- Analyzed: [X] headlines, [Y] descriptions
- Top performer: "[headline]" — [metric]: [value]
- Worst performer: "[headline]" — [metric]: [value]
- Pattern: [observation]
## New Creative
[organized variations]
## Recommendations
- [What to pause, what to scale, what to test next]
For large-scale creative production (Anthropic's growth team generates 100+ variations per cycle):
For pulling performance data and managing campaigns, see the tools registry.
| Platform | Pull Performance Data | Manage Campaigns | Guide |
|---|---|---|---|
| Google Ads | google-ads campaigns list, google-ads reports get |
google-ads campaigns create |
google-ads.md |
| Meta Ads | meta-ads insights get |
meta-ads campaigns list |
meta-ads.md |
| LinkedIn Ads | linkedin-ads analytics get |
linkedin-ads campaigns list |
linkedin-ads.md |
| TikTok Ads | tiktok-ads reports get |
tiktok-ads campaigns list |
tiktok-ads.md |
# 1. Pull recent ad performance
node tools/clis/google-ads.js reports get --type ad_performance --date-range last_30_days
# 2. Analyze output (identify top/bottom performers)
# 3. Feed winning patterns into this skill
# 4. Generate new variations
# 5. Upload to platform
A shareable, self-contained web page that presents generated ad concepts for a client or stakeholder to review and pick — the visual upgrade to INDEX.md. Where the markdown outputs are built for the operator, the review page is built for the person approving the spend: it shows each concept as an in-feed platform mockup, breaks carousels into a labeled frame-by-frame storyboard, lets them toggle copy variations, and discloses what's grounded in real assets.
The template ships at assets/creative-review-template.html. It's one file — inline CSS and JS, no build, no dependencies, no network. Open it locally, host it on any static host (Vercel/Netlify/GitHub Pages), or hand off the .html file directly.
INDEX.md. Picking 5 of 50 is a visual decision; a client shouldn't have to read markdown to make it.Don't produce one for a single headline tweak or a quick internal gut-check — the markdown output is faster. Reach for the review page when a human who isn't you needs to choose.
The template renders entirely from a JSON block near the top of the file — <script type="application/json" id="review-data">. Populate it from your generated concepts and everything else renders — tabs, previews, storyboard, copy panel. You do not edit the render code below the data block. The annotated model below is shown with // comments for readability; the file itself is strict JSON — no comments, no trailing commas (see "Populating the data safely").
{
project: {
brand: "Truvani", // required
agency: "Light Labs", // optional — adds the co-brand line + the default handle fallback (partner label/initials)
date: "2026-07-12", // optional
note: "one-line context" // optional
},
platforms: ["instagram", "facebook"], // previews to offer; first is the default. Supported: instagram, facebook
concepts: [ // each concept is one strategic ANGLE (see SKILL.md "Define Your Angles")
{
name: "Heavy-Metal Proof", // required — the angle name
tagline: "Lifestyle hero, then the lab results", // one line, what makes this concept distinct
handles: [ // optional. 1 entry = normal post; 2 = whitelist handle toggle
{ name: "truvani", partner: "Paid partnership with lightlabs", initials: "TV" },
{ name: "Light Labs", partner: "Paid partnership with truvani", initials: "LL" }
],
frames: [ // 1 frame = single ad; multiple = carousel storyboard
{
label: "Hook", // the frame's job in the narrative arc
prompt: "Product bag hero on soft pink, gold-lace overlay", // image description (shown as placeholder if no image)
image: "images/heavy-metal-01.png", // optional — URL, relative path, or data URI; omit for text-only concepts
headline: "Finally — a plant-based protein that's third-party tested for heavy metals.", // optional per-frame overlay
headlineTheme: "dark" // optional: "dark" (default, white text) or "light" (dark text on light imagery)
}
// … one object per frame
],
headlines: [ // selectable variations; the picked one overlays frame 1 in the preview
"Finally — a plant-based protein that's third-party tested for heavy metals.",
"We tested our protein for heavy metals. Here's what an independent lab found.",
"Most protein powders are never tested for heavy metals. Ours is."
],
primaryText: "The caption / body copy.",
destination: { url: "shop.truvani.com", cta: "Shop now", offer: "72% OFF Protein Starter Kit" },
rollout: { // optional — the mechanics of how this runs (whitelist, launch plan)
title: "How the whitelist runs",
steps: ["step 1", "step 2", "…"]
},
grounding: "What in this concept is real — the required disclosure. See below."
}
// … 2–4 concepts is the sweet spot; more than that and the tabs stop being a decision
]
}
A concept's frames are its storyboard. Label each frame by the job it does, not its content — Hook, The problem, The results, The ask. This is the same narrative-arc thinking as the carousel frameworks: a proof-led concept is literally Hook → Problem → Mechanism → Results → Context → Ask. For the five reusable carousel arcs (Value-Stack, Problem-Proof, Hack List, Rant Callout, Demo Walkthrough), see carousel-frameworks.md in the social skill and pick the arc that fits the angle before writing frames.
Every frame renders one of two ways:
- image provided — the real creative (from the Mode 3 images/ folder, a hosted URL, or a data URI) fills the frame.
- image omitted — a styled placeholder shows the frame label + prompt. This is the intended state for concepts that are copy + image-prompt but not yet rendered to image — the review page is useful before images exist, and stays useful as they get filled in.
Ship review pages with placeholders freely; they communicate the concept. Swap in images as they're generated.
Every concept must carry a grounding line, and it must be true. This is the same rule as the Grounded Inputs corpus, surfaced to the client: state exactly what is real (which lab panel, which review, which product photography) and, by omission, what is illustrative. The source pattern's line is the model — "Results are Truvani's actual Light Labs panel (Vanilla, tested Nov 13, 2025). Imagery is Truvani's own product & lifestyle photography."
Never present invented stats, fabricated test results, or stock imagery as the brand's own. If a concept's proof isn't real yet, the grounding line says so ("Results shown are illustrative pending the lab panel") — a review page that launders fiction as fact is worse than no review page.
The DATA lives in a <script type="application/json" id="review-data"> block — it's inert data (parsed with JSON.parse), not executable code, so a value can never run as script. Two rules when you write it:
< as \u003c in every text value. A value literally containing </script> would otherwise close the data block early. Since agents write the JSON, apply this escape mechanically to all string values. All values are HTML-escaped again at render time, so this is defense-in-depth, but the source-level escape is the one that matters — do it.assets/creative-review-template.html into the batch's output folder as review.html (e.g. outputs/YYYY-MM-DD/review.html).DATA object with the real project — concepts, frames, copy, grounding. Populate image paths for any frames you've rendered (keep them relative to the html file so the folder stays portable).images/), or host it. For a client link, vercel deploy or any static host works — it's a single page with local assets.Keep the review page next to the markdown outputs, not instead of them: INDEX.md and the per-concept files remain the operator's record and the grounding audit trail; review.html is the approval surface built on top.
The proof), not by what's pictured (Table screenshot).DATA field, not the JS.Generation (Modes 1–3) answers "make me ads." This reference answers the question that comes first: which ads are worth making, in what order, at what production cost — and the retro that turns each month's results into next month's plan. It's the standing operating loop of a creative strategist, run by an agent with a human deciding.
Signals → Concepts (evidence-ranked) → Roadmap (tiered, capacity-checked) → Briefs → [Modes 1–3 produce] → Monthly retro → back into the icebox
Creative direction comes from synthesis across three independent signal sources. One source alone misleads: the account tells you what worked among things you've tried, customers tell you why they buy in their words, and organic content tells you what the audience chooses to watch when nobody's paying.
| Signal | What to pull | How |
|---|---|---|
| Account performance | Winners/losers by angle, hook, format; funnel metrics per concept (see hook-system.md diagnostic funnel); fatigue state | google-ads / meta-ads / linkedin-ads / tiktok-ads CLIs (see Tool Integrations in SKILL.md) |
| Customer/brand | Verbatim pain/desire/objection language; unexpected use cases; who's actually buying vs. who's targeted | The Grounded Inputs corpus (inputs/reviews/, inputs/comments/), sales-call notes, support themes — per customer-research |
| External organic | What the niche watches unpaid: top organic content, its hooks, formats, vocabulary; competitor ads running long enough to be presumed working | scraping, the social listening tooling in social, ad libraries, competitor-profiling |
Cadence: a monthly deep dive (60–90 min, all three sources, feeds the monthly roadmap) plus a weekly ~20-minute refresh (what changed: new winners/losers, new review themes, anything spiking organically). Research beyond what the next decision needs is busywork — every synthesis session should end in concepts, not notes.
Trust rule: every insight the agent surfaces must carry its receipt — which review, which ad's metrics, which organic post. An insight without a source doesn't enter the icebox. (Same grounding rules as everything else in this skill.)
A concept is one testable creative hypothesis: segment × motivation × angle × format, with its evidence attached. "UGC for moms" is not a concept; "new-parent insomniacs (per 40+ reviews mentioning 3am feeds) × 'quiet enough to not wake the baby' × before/after demo × POV night-shot video" is.
Rank every concept by the strongest evidence supporting it:
| Tier | Evidence | Weight |
|---|---|---|
| 1 | Your own account: a converting ad with the same angle/segment | Strongest — iterate and extend |
| 2 | Your customers verbatim: recurring review/call language | Strong — build new creative on it |
| 3 | Competitor creative running 60+ days (presumed working) | Good — adapt the angle, never the ad |
| 4 | Organic engagement in the niche (unpaid views/saves on the theme) | Moderate — validate cheaply first |
| 5 | Cross-niche pattern (worked in an adjacent category) | Weak — icebox until corroborated |
| 6 | Team hunch, no external signal | Weakest — low-fi test or drop |
Higher evidence earns roadmap priority — an earlier slot in the slate. Production tier is a separate call, set by validation strength, existing assets, capacity, and risk: even a tier-2 customer-language concept starts low-fidelity until it shows a funnel signal. Hunches aren't banned — they're just cheap and last.
The right creative mix depends on which of two states the account is in. Diagnose before roadmapping — a plan built for the wrong state wastes the month.
Exploration state — nothing (or nothing new) is working:
- Go wide, not deep: mostly net-new concepts across different segments and angles; keep iterations to a small minority — iterating on losers multiplies losers
- Redefine "win" per-metric: with no full-funnel winners, a single-metric improvement (a hold-rate lift, a CPC drop, a CVR bump) on any test is a hit worth pulling on — see the diagnostic funnel
- Iterate only on hits; everything else stays exploratory
- Common root causes to check while testing: the creative is boring (safe, seen-before), the message is overcomplicated, the offer/UVP is unclear, or CPMs are punishing a too-narrow audience
Scaling state — one or more concepts are converting profitably:
- Go deep on the winner while it's open: a winner-led slate of visually-distinct variations of the winning concept (same message, new execution — near-duplicates mostly cannibalize the original's reach and teach you nothing new, so variations must look meaningfully different), plus a remix lane (tonal/emotional re-executions of it) and sub-angle probes drilling into the winning segment; tune the split to budget, fatigue speed, and production velocity
- Keep a small exploration allocation alive even mid-scale — winners fatigue, and the next winner is rarely an iteration of the current one
- Speed matters more in this state: a scaling window is finite
Maintain one living document (suggested: roadmap.md beside the Grounded Inputs corpus) with three horizons:
## Icebox — every concept, evidence tier + source attached, nothing scheduled
## This quarter — 2-4 themes chosen from the icebox (the bets), with why-now
## This month — the slate: concept | evidence tier | production tier | owner | status
Each monthly-slate concept gets a production tier:
| Tier | Cost | What it is | Use for |
|---|---|---|---|
| T1 — Iteration | Hours | New hook/caption/crop on an existing asset | Extending proven winners |
| T2 — Remix | Days | New creative from existing footage/assets/AI generation | Concepts with decent evidence or a first low-fi signal |
| T3 — Production | Weeks | Net-new shoot, creators, full build | Only angles with own-account proof or a prior low-fi funnel signal (fidelity ladder in hook-system.md) |
Capacity check — the rule that keeps roadmaps honest: count what the team (or the AI pipeline) can produce at quality this month, and roadmap to that number. A 20-concept slate against 8 concepts of real capacity doesn't produce 20 ads; it produces 20 compromised ones and a burned-out team. Cut by evidence rank until the slate fits.
From the slate, generate one brief per concept (segment, motivation + verbatim source, angle, format, hook matrix rows, production tier, success metric) and hand each to Modes 1–3 for production.
Last step of the loop, first input of the next one. One artifact per month (suggested: retros/YYYY-MM.md):
## Winners — concept, the funnel numbers, and the WHY (which element earned it)
## Losers — concept, where in the funnel it died, hypothesis for why
## Metric wins — full-funnel losers with one strong metric (these are leads, not losses)
## Learnings — pattern-level notes → written back into the icebox as new/revised concepts
## Kills — concepts retired from the icebox, with reason
## Next slate — first draft of next month, updated evidence ranks
Retro rules:
To run this loop on a schedule (retro on the 1st, weekly refresh Mondays, daily batches via Mode 3), see the creative loops in marketing-loops.
Reference for using AI image generators, video generators, and code-based video tools to produce ad visuals at scale.
| Need | Tool Category | Best Fit |
|---|---|---|
| Static ad images (banners, social) | Image generation | ChatGPT Images 2.0, Nano Banana Pro, Flux, Ideogram |
| Ad images with text overlays | Image generation (text-capable) | Ideogram, Nano Banana Pro |
| Short video ads (6-30 sec) | Video generation | Veo, Kling, Runway, Sora, Seedance |
| Video ads with voiceover | Video gen + voice | Veo/Sora (native), or Runway + ElevenLabs |
| Voiceover tracks for ads | Voice generation | ElevenLabs, OpenAI TTS, Cartesia |
| Multi-language ad versions | Voice generation | ElevenLabs, PlayHT |
| Brand voice cloning | Voice generation | ElevenLabs, Resemble AI |
| Product mockups and variations | Image generation + references | Flux (multi-image reference) |
| Templated video ads at scale | Code-based video | Remotion |
| Personalized video (name, data) | Code-based video | Remotion |
| Brand-consistent variations | Image gen + style refs | Flux, Ideogram, Nano Banana Pro |
Google DeepMind's image generation model, available through the Gemini API.
Best for: High-quality ad images, product visuals, text rendering
API: Gemini API (Google AI Studio, Vertex AI)
Pricing: ~$0.04/image (Gemini 2.5 Flash Image), ~$0.24/4K image (Nano Banana Pro)
Strengths:
- Strong text rendering in images (logos, headlines)
- Native image editing (modify existing images with prompts)
- Available through the same Gemini API used for text generation
- Supports both generation and editing in one model
Ad creative use cases:
- Generate social media ad images from text descriptions
- Create product mockup variations
- Edit existing ad images (swap backgrounds, change colors)
- Generate images with headline text baked in
API example:
# Using the Gemini API for image generation
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"contents": [{"parts": [{"text": "Create a clean, modern social media ad image for a project management tool. Show a laptop with a kanban board interface. Bright, professional, 16:9 ratio."}]}],
"generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
}'
Docs: Gemini Image Generation
Open-weight image generation models with API access through Replicate and BFL's native API.
Best for: Photorealistic images, brand-consistent variations, multi-reference generation
API: Replicate, BFL API, fal.ai
Pricing: ~$0.01-0.06/image depending on model and resolution
Model variants:
| Model | Speed | Quality | Cost | Best For |
|-------|-------|---------|------|----------|
| Flux 2 Pro | ~6 sec | Highest | $0.015/MP | Final production assets |
| Flux 2 Flex | ~22 sec | High + editing | $0.06/MP | Iterative editing |
| Flux 2 Dev | ~2.5 sec | Good | $0.012/MP | Rapid prototyping |
| Flux 2 Klein | Fastest | Good | Lowest | High-volume batch generation |
Strengths:
- Multi-image reference (up to 8 images) for consistent identity across ads
- Product consistency — same product in different contexts
- Style transfer from reference images
- Open-weight Dev model for self-hosting
Ad creative use cases:
- Generate 50+ ad variations with consistent product/person identity
- Create product-in-context images (your SaaS on different devices)
- Style-match to existing brand assets using reference images
- Rapid A/B test image variations
Docs: Replicate Flux, BFL API
Specialized in typography and text rendering within images.
Best for: Ad banners with text, branded graphics, social ad images with headlines
API: Ideogram API, Runware
Pricing: ~$0.06/image (API), ~$0.009/image (subscription)
Strengths:
- Best-in-class text rendering (~90% accuracy vs ~30% for most tools)
- Style reference system (upload up to 3 reference images)
- 4.3 billion style presets for consistent brand aesthetics
- Strong at logos and branded typography
Ad creative use cases:
- Generate ad banners with headline text directly in the image
- Create social media graphics with branded text overlays
- Produce multiple design variations with consistent typography
- Generate promotional materials without needing a designer for each iteration
Docs: Ideogram API, Ideogram
| Tool | Best For | API Status | Notes |
|---|---|---|---|
| DALL-E 3 (OpenAI) | General image generation | Official API | Integrated with ChatGPT, good text rendering |
| Midjourney | Artistic, high-aesthetic images | No official public API | Discord-based; unofficial APIs exist but risk bans |
| Stable Diffusion | Self-hosted, customizable | Open source | Best for teams with GPU infrastructure |
Google DeepMind's video generation model, available through the Gemini API and Vertex AI.
Best for: High-quality video ads with native audio, vertical video for social
API: Gemini API, Vertex AI
Pricing: ~$0.15/sec (Veo 3.1 Fast), ~$0.40/sec (Veo 3.1 Standard)
Capabilities:
- Up to 60 seconds at 1080p
- Native audio generation (dialogue, sound effects, ambient)
- Vertical 9:16 output for Stories/Reels/Shorts
- Upscale to 4K
- Text-to-video and image-to-video
Ad creative use cases:
- Generate short video ads (15-30 sec) from text descriptions
- Create vertical video ads for TikTok, Reels, Shorts
- Produce product demos with voiceover
- Generate multiple video variations from the same prompt with different styles
Docs: Veo on Vertex AI
Video generation with simultaneous audio-visual generation and camera controls.
Best for: Cinematic video ads, longer-form content, audio-synced video
API: Kling API, PiAPI, fal.ai
Pricing: ~$0.09/sec (via fal.ai third-party)
Capabilities:
- Up to 3 minutes at 1080p/30-48fps
- Simultaneous audio-visual generation (Kling 2.6)
- Text-to-video and image-to-video
- Motion and camera controls
Ad creative use cases:
- Longer product explainer videos
- Cinematic brand videos with synchronized audio
- Animate product images into video ads
Docs: Kling AI Developer
Video generation and editing platform with strong controllability.
Best for: Controlled video generation, style-consistent content, editing existing footage
API: Runway Developer Portal
Capabilities:
- Gen-4: Character/scene consistency across shots
- Motion brush and camera controls
- Image-to-video with reference images
- Video-to-video style transfer
Ad creative use cases:
- Generate video ads with consistent characters/products across scenes
- Style-transfer existing footage to match brand aesthetics
- Extend or remix existing video content
Docs: Runway API
OpenAI's video generation model with synchronized audio.
Best for: High-fidelity video with dialogue and sound
API: OpenAI API
Pricing: Free tier available; Pro from $0.10-0.50/sec depending on resolution
Capabilities:
- Up to 60 seconds with synchronized audio
- Dialogue, sound effects, and ambient audio
- sora-2 (fast) and sora-2-pro (quality) variants
- Text-to-video and image-to-video
Ad creative use cases:
- Video testimonials and talking-head style ads
- Product demo videos with narration
- Narrative brand videos
Docs: OpenAI Video Generation
ByteDance's video generation model with simultaneous audio-visual generation and multimodal inputs.
Best for: Fast, affordable video ads with native audio, multimodal reference inputs
API: BytePlus (official), Replicate, WaveSpeedAI, fal.ai (third-party); OpenAI-compatible API format
Pricing: ~$0.10-0.80/min depending on resolution (estimated 10-100x cheaper than Sora 2 per clip)
Capabilities:
- Up to 20 seconds at up to 2K resolution
- Simultaneous audio-visual generation (Dual-Branch Diffusion Transformer)
- Text-to-video and image-to-video
- Up to 12 reference files for multimodal input
- OpenAI-compatible API structure
Ad creative use cases:
- High-volume short video ad production at low cost
- Video ads with synchronized voiceover and sound effects in one pass
- Multi-reference generation (feed product images, brand assets, style references)
- Rapid iteration on video ad concepts
Docs: Seedance
Full-stack video creation platform with cinematic camera controls.
Best for: Social video ads, cinematic style, mobile-first content
Platform: higgsfield.ai
Capabilities:
- 50+ professional camera movements (zooms, pans, FPV drone shots)
- Image-to-video animation
- Built-in editing, transitions, and keyframing
- All-in-one workflow: image gen, animation, editing
Ad creative use cases:
- Social media video ads with cinematic feel
- Animate product images into dynamic video
- Create multiple video variations with different camera styles
- Quick-turn video content for social campaigns
| Tool | Max Length | Audio | Resolution | API | Best For |
|---|---|---|---|---|---|
| Veo 3.1 | 60 sec | Native | 1080p/4K | Gemini | Vertical social video |
| Kling 2.6 | 3 min | Native | 1080p | Third-party | Longer cinematic |
| Runway Gen-4 | 10 sec | No | 1080p | Official | Controlled, consistent |
| Sora 2 | 60 sec | Native | 1080p | Official | Dialogue-heavy |
| Seedance 2.0 | 20 sec | Native | 2K | Official + third-party | Affordable high-volume |
| Higgsfield | Varies | Yes | 1080p | Web-based | Social, mobile-first |
For layering realistic voiceovers onto video ads, adding narration to product demos, or generating audio for Remotion-rendered videos. These tools turn ad scripts into natural-sounding voice tracks.
Many video generators (Veo, Kling, Sora, Seedance) now include native audio. Use standalone voice tools when you need:
The market leader in realistic voice generation and voice cloning.
Best for: Most natural-sounding voiceovers, brand voice cloning, multilingual
API: REST API with streaming support
Pricing: ~$0.12-0.30 per 1,000 characters depending on plan; starts at $5/month
Capabilities:
- 29+ languages with natural accent and intonation
- Voice cloning from short audio clips (instant) or longer recordings (professional)
- Emotion and style control
- Streaming for real-time generation
- Voice library with hundreds of pre-built voices
Ad creative use cases:
- Generate voiceover tracks for video ads
- Clone your brand spokesperson's voice for all ad variations
- Produce the same ad in 10+ languages from one script
- A/B test different voice styles (authoritative vs. friendly vs. urgent)
API example:
curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/{voice_id}" \
-H "xi-api-key: $ELEVENLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Stop wasting hours on manual reporting. Try DataFlow free for 14 days.",
"model_id": "eleven_multilingual_v2",
"voice_settings": {"stability": 0.5, "similarity_boost": 0.75}
}' --output voiceover.mp3
Docs: ElevenLabs API
Simple, affordable text-to-speech built into the OpenAI API.
Best for: Quick voiceovers, cost-effective at scale, simple integration
API: OpenAI API (same SDK as GPT/DALL-E)
Pricing: $15/million chars (standard), $30/million chars (HD); ~$0.015/min with gpt-4o-mini-tts
Capabilities:
- 13 built-in voices (no custom cloning)
- Multiple languages
- Real-time streaming
- HD quality option
- Simple API — same SDK you already use for GPT
Ad creative use cases:
- Fast, cheap voiceover for draft/test ad versions
- High-volume narration at low cost
- Prototype ad audio before investing in premium voice
Docs: OpenAI TTS
Ultra-low latency voice generation built for real-time applications.
Best for: Real-time voice, lowest latency, emotional expressiveness
API: REST + WebSocket streaming
Pricing: Starts at $5/month; pay-as-you-go from $0.03/min
Capabilities:
- 40ms time-to-first-audio (fastest in class)
- 15+ languages
- Nonverbal expressiveness: laughter, breathing, emotional inflections
- Sonic Turbo for even lower latency
- Streaming API for real-time generation
Ad creative use cases:
- Real-time ad preview during creative iteration
- Interactive demo videos with dynamic narration
- Ads requiring natural laughter, sighs, or emotional reactions
Docs: Cartesia Sonic
Free, local-first voice synthesis studio powered by Qwen3-TTS. The open-source alternative to ElevenLabs.
Best for: Free voice cloning, local/private generation, zero-cost batch production
API: Local REST API at http://localhost:8000
Pricing: Free (MIT license). Runs entirely on your machine.
Stack: Tauri (Rust) + React + FastAPI (Python)
Capabilities:
- Voice cloning from short audio samples via Qwen3-TTS
- Multi-language support (English, Chinese, more planned)
- Multi-track timeline editor for composing conversations
- 4-5x faster inference on Apple Silicon via MLX Metal acceleration
- Local REST API for programmatic generation
- No cloud dependency — all processing on-device
Ad creative use cases:
- Free voice cloning for brand spokesperson across all ad variations
- Batch generate voiceovers without per-character costs
- Private/local generation when ad content is sensitive or pre-launch
- Prototype voice variations before committing to a paid service
API example:
curl -X POST http://localhost:8000/generate \
-H "Content-Type: application/json" \
-d '{"text": "Stop wasting hours on manual reporting.", "profile_id": "abc123", "language": "en"}'
Install: Desktop apps for macOS and Windows at voicebox.sh, or build from source:
git clone https://github.com/jamiepine/voicebox.git
cd voicebox && make setup && make dev
Docs: GitHub
| Tool | Best For | Differentiator | API |
|---|---|---|---|
| PlayHT | Large voice library, low latency | 900+ voices, <300ms latency, ultra-realistic | play.ht |
| Resemble AI | Enterprise voice cloning | On-premise deployment, real-time speech-to-speech | resemble.ai |
| WellSaid Labs | Ethical, commercial-safe voices | Voices from compensated actors, safe for commercial use | wellsaid.io |
| Fish Audio | Budget-friendly, emotion control | ~50-70% cheaper than ElevenLabs, emotion tags | fish.audio |
| Murf AI | Non-technical teams | Browser-based studio, 200+ voices | murf.ai |
| Google Cloud TTS | Google ecosystem, scale | 220+ voices, 40+ languages, enterprise SLAs | Google TTS |
| Amazon Polly | AWS ecosystem, cost | Neural voices, SSML control, cheap at volume | Amazon Polly |
| Tool | Quality | Cloning | Languages | Latency | Price/1K chars |
|---|---|---|---|---|---|
| ElevenLabs | Best | Yes (instant + pro) | 29+ | ~200ms | $0.12-0.30 |
| OpenAI TTS | Good | No | 13+ | ~300ms | $0.015-0.030 |
| Cartesia Sonic | Very good | No | 15+ | ~40ms | ~$0.03/min |
| PlayHT | Very good | Yes | 140+ | <300ms | ~$0.10-0.20 |
| Fish Audio | Good | Yes | 13+ | ~200ms | ~$0.05-0.10 |
| WellSaid | Very good | No (actor voices) | English | ~300ms | Custom pricing |
| Voicebox | Good | Yes (local) | 2+ | Local | Free (open source) |
Need voiceover for ads?
├── Need to clone a specific brand voice?
│ ├── Best quality → ElevenLabs
│ ├── Enterprise/on-premise → Resemble AI
│ └── Budget-friendly → Fish Audio, PlayHT
├── Need multilingual (same ad, many languages)?
│ ├── Most languages → PlayHT (140+)
│ └── Best quality → ElevenLabs (29+)
├── Need free / open source / local?
│ └── Voicebox (MIT, runs on your machine)
├── Need cheap, fast, good-enough?
│ └── OpenAI TTS ($0.015/min)
├── Need commercially-safe licensing?
│ └── WellSaid Labs (actor-compensated voices)
└── Need real-time/interactive?
└── Cartesia Sonic (40ms TTFA)
1. Write ad script (use ad-creative skill for copy)
2. Generate voiceover with ElevenLabs/OpenAI TTS
3. Generate or render video:
a. Silent video from Runway/Remotion → layer voice track
b. Or use Veo/Sora/Seedance with native audio (skip separate VO)
4. Combine with ffmpeg if layering separately:
ffmpeg -i video.mp4 -i voiceover.mp3 -c:v copy -c:a aac output.mp4
5. Generate variations (different scripts, voices, or languages)
For templated, data-driven video ads at scale, Remotion is the best option. Unlike AI video generators that produce unique video from prompts, Remotion uses React code to render deterministic, brand-perfect video from templates and data.
Best for: Templated ad variations, personalized video, brand-consistent production
Stack: React + TypeScript
Pricing: Free for individuals/small teams; commercial license required for 4+ employees
Docs: remotion.dev
| AI Video Generators | Remotion |
|---|---|
| Unique output each time | Deterministic, pixel-perfect |
| Prompt-based, less control | Full code control over every frame |
| Hard to match brand exactly | Exact brand colors, fonts, spacing |
| One-at-a-time generation | Batch render hundreds from data |
| No dynamic data insertion | Personalize with names, prices, stats |
1. Dynamic product ads
Feed a JSON array of products and render a unique video ad for each:
// Simplified Remotion component for product ads
export const ProductAd: React.FC<{
productName: string;
price: string;
imageUrl: string;
tagline: string;
}> = ({productName, price, imageUrl, tagline}) => {
return (
<AbsoluteFill style={{backgroundColor: '#fff'}}>
<Img src={imageUrl} style={{width: 400, height: 400}} />
<h1>{productName}</h1>
<p>{tagline}</p>
<div className="price">{price}</div>
<div className="cta">Shop Now</div>
</AbsoluteFill>
);
};
2. A/B test video variations
Render the same template with different headlines, CTAs, or color schemes:
const variations = [
{headline: "Save 50% Today", cta: "Get the Deal", theme: "urgent"},
{headline: "Join 10K+ Teams", cta: "Start Free", theme: "social-proof"},
{headline: "Built for Speed", cta: "Try It Now", theme: "benefit"},
];
// Render all variations programmatically
3. Personalized outreach videos
Generate videos addressing prospects by name for cold outreach or sales.
4. Social ad batch production
Render the same content across different aspect ratios:
- 1:1 for feed
- 9:16 for Stories/Reels
- 16:9 for YouTube
1. Design template in React (or use AI to generate the component)
2. Define data schema (products, headlines, CTAs, images)
3. Feed data array into template
4. Batch render all variations
5. Upload to ad platform
# Create a new Remotion project
npx create-video@latest
# Render a single video
npx remotion render src/index.ts MyComposition out/video.mp4
# Batch render from data
npx remotion render src/index.ts MyComposition --props='{"data": [...]}'
Need video ads?
├── Templated, data-driven (same structure, different data)
│ └── Use Remotion
├── Unique creative from prompts (exploratory)
│ ├── Need dialogue/voiceover? → Sora 2, Veo 3.1, Kling 2.6, Seedance 2.0
│ ├── Need consistency across scenes? → Runway Gen-4
│ ├── Need vertical social video? → Veo 3.1 (native 9:16)
│ ├── Need high volume at low cost? → Seedance 2.0
│ └── Need cinematic camera work? → Higgsfield, Kling
└── Both → Use AI gen for hero creative, Remotion for variations
Need image ads?
├── Need text/headlines in image? → Ideogram
├── Need product consistency across variations? → Flux (multi-ref)
├── Need quick iterations on existing images? → Nano Banana Pro
├── Need highest visual quality? → Flux Pro, Midjourney
└── Need high volume at low cost? → Flux Klein, Nano Banana
| Approach | Tool | Approximate Cost |
|---|---|---|
| 100 static images | Nano Banana Pro | ~$4-24 |
| 100 static images | Flux Dev | ~$1-2 |
| 100 static images | Ideogram API | ~$6 |
| 100 × 15-sec videos | Veo 3.1 Fast | ~$225 |
| 100 × 15-sec videos | Remotion (templated) | ~$0 (self-hosted render) |
| 10 hero videos + 90 templated | Veo + Remotion | ~$22 + render time |
This hybrid approach gives you the creative exploration of AI generators and the consistency and scale of code-based rendering.
When generating images for ads, request the correct dimensions:
| Platform | Placement | Aspect Ratio | Recommended Size |
|---|---|---|---|
| Meta Feed | Single image | 1:1 | 1080x1080 |
| Meta Stories/Reels | Vertical | 9:16 | 1080x1920 |
| Meta Carousel | Square | 1:1 | 1080x1080 |
| Google Display | Landscape | 1.91:1 | 1200x628 |
| Google Display | Square | 1:1 | 1200x1200 |
| LinkedIn Feed | Landscape | 1.91:1 | 1200x627 |
| LinkedIn Feed | Square | 1:1 | 1200x1200 |
| TikTok Feed | Vertical | 9:16 | 1080x1920 |
| Twitter/X Feed | Landscape | 16:9 | 1200x675 |
| Twitter/X Card | Landscape | 1.91:1 | 800x418 |
Include these dimensions in your generation prompts to avoid needing to crop or resize.
The first three seconds decide whether the rest of the ad exists. Hooks are the highest-leverage unit of paid creative work — and hook diversity is what earns incremental learning: distinct hooks reach distinct pockets of the audience, while near-identical openings mostly re-test what you already know about the same one. This reference is a complete system for generating, diagnosing, and iterating hooks — not a list of one-liners.
Use it inside Mode 1/3 generation (hooks for new concepts), Mode 2 iteration (diagnosing why an ad underperforms), and the creative strategy loop in creative-roadmap.md.
In video, the hook is the simultaneous combination of:
| Component | What it is | Job |
|---|---|---|
| Visual action | What is literally happening on screen in seconds 0–3 | Stop the thumb |
| Spoken line | The first words of VO or dialogue | Open the loop |
| Caption text | On-screen header/overlay text | Anchor the claim for sound-off viewers |
The no-duplication rule: the three components must complement, never repeat. If the VO says "I stopped paying $200/mo for my gym" while the caption reads "I stopped paying $200/mo" over a static talking head, two of the three slots are wasted. Strong hooks split the work — visual shows the cancellation email, VO says the line, caption names the alternative. When writing hooks, write all three columns explicitly; a hook spec with one column filled in is a third of a hook.
Static ads collapse this to two components (visual + headline) — the same rule applies: the headline must not caption the image.
Work top-down; hooks written without the upstream steps read like everyone else's ads.
Segment → Motivation → Format → Hook (three components)
Output as a hook matrix so coverage is visible:
| # | Segment | Motivation (verbatim source) | Format | Visual action | Spoken line | Caption |
Generate across the matrix, not down a single column — ten hooks for ten segment×motivation cells beat thirty rewordings of one cell. This is the same angle-diversity principle as the static template library: matrix diversity is audience diversity.
A menu of proven opening structures. Cycle through them like the static templates — don't cluster on favorites:
| Move | Shape | Watch out |
|---|---|---|
| Curiosity gap | Withhold the noun: "Nobody tells you what actually causes this" | Must pay off within the ad or it's clickbait that poisons CVR |
| Bold claim | A specific, falsifiable statement: "This replaced my entire morning routine" | Needs substantiation on screen or in the on-ramp |
| First-person confession | "I was doing [common thing] completely wrong" | Reads fake without lived-in detail |
| Contrast / before-after | Two states shown or named in the first beat | The transformation must be visually honest — see compliance notes in SKILL.md |
| Relatability / POV | Mirror a hyper-specific situation: "POV: it's 3pm and you're on your fourth coffee" | Specificity is the entire mechanic; generic POV is invisible |
| Question | Ask the exact question the buyer types into search or ChatGPT | Use their phrasing verbatim from the corpus |
| Countdown / gamified | A timer or on-screen challenge that promises a payoff at the end | Payoff must exist; hold-rate collapses on cheats |
| Proof-first | Lead with the receipt — the result screenshot, the stat, the demo money-shot | Strongest when the proof brags by itself |
Each metric in the delivery funnel isolates a different component. When an ad underperforms, read the funnel to find which part to fix instead of scrapping the whole ad:
| Stage | Metric | If it's weak, the problem is | Fix |
|---|---|---|---|
| Stop | Thumbstop / 3-sec view rate | Visual action (and caption) | New visual opening; same everything else |
| Stay | Hold rate (3s → 15s / 50% view) | The on-ramp — what follows the hook | Rework seconds 3–15, not the hook |
| Click | CTR | Desire/offer clarity mid-ad | Sharpen the promise, CTA, or proof |
| Convert | CVR post-click | Congruence — the page doesn't continue the ad | Fix the landing page or the claim, per cro |
Two rules this table enforces:
The on-ramp is seconds ~3–15: the bridge from hook to body. A good on-ramp logically extends the hook's premise; a bad one pivots to a product pitch that abandons it. If the hook promises "what actually causes this," the next beat must start explaining the cause — not introduce the brand story.
Corollary: every hook test is also an on-ramp test. Swapping a new hook onto an existing ad body usually breaks the premise-bridge; when testing hooks, re-write the on-ramp to match each one. Hold rate is the on-ramp's metric — diagnose it separately from thumbstop.
Match production cost to evidence strength (production tiers are defined in creative-roadmap.md):
Testing a hunch with an expensive shoot and testing a proven angle with a throwaway static are both mistakes — the ladder runs in one direction.
Hooks inherit every grounding rule from SKILL.md: every hook cites the corpus source its motivation came from; no invented claims, stats, or testimonials; verbatim customer language over paraphrase. Additionally, mine organic content in the niche (top-performing TikToks/Reels/posts, via the scraping skill or the social listening tooling in social) for the audience's actual vocabulary — the words the niche uses ("GLP-1" vs. the clinical term, the slang for the pain) belong in the caption and spoken line. Organic mining is language research, not copying: take the vocabulary and the visual conventions, never a creator's specific creative.
A family of 9:16 social-native video formats that recreate a familiar iOS surface in real time and let the brand emerge inside it. The flagship is the iMessage chat reveal — someone sends a screenshot of a result or product, a friend reacts and asks what it is, and the conversation reveals the brand, usually with a promo code. Message bubbles pop in over ~15–22 seconds with authentic send/receive sounds, then a static brand end card lands the CTA. The same architecture powers ChatGPT reveals, Apple Notes reveals, and AirDrop reveals — covered in Other iOS-Native Reveal Surfaces below.
The format works because it borrows the most-read UI on earth. A chat thread is a familiar, high-attention dramatization — it mirrors how real recommendations happen, so the viewer leans in instead of scrolling past. The CTA arrives conversationally ("use code FREEPACK") instead of as a hard sell, which keeps the ad-skip reflex from firing until the pitch has already landed. Run it only as a clearly labeled paid placement (Meta's "Sponsored" tag does the disclosure work); never seed it organically as if it were a real leaked conversation.
Credit: this reference distills the format popularized by Shiv Sakhuja and the Gooseworks team (@shivsakhuja, gooseworks-ai/gooseworks-ads-skills), who report the format performing strongly on Meta.
Good fit:
- Reaction/discovery ads where the punchline is the recipient's curiosity ("wait, what app is that?")
- Promo-code offers — the conversational delivery feels far less ad-like than a code on a slate
- Products with a screenshot-able result: a number, a dashboard, a receipt, a before/after
- UGC-style angles when you don't have UGC creators on tap
Poor fit:
- Considered B2B purchases where a casual text exchange undercuts credibility
- Products with nothing visual or numeric to screenshot (fix the hook first, not the format)
- Brands whose compliance review can't approve dramatized conversations (regulated industries — check first)
Platform fit: Built for Meta Reels/Stories placements (9:16, 1080×1920) with a 1:1 center-crop variant for feed. Works on TikTok and YouTube Shorts with the same master file.
This is a dramatization — a scripted conversation, not a real one. That's a standard, legitimate ad device, but two rules keep it honest and on the right side of FTC guidance:
If a claim needs a disclaimer on your landing page, it needs one on this ad too.
Most iMessage ads fit one of six angles. Pick the angle before writing any copy — the most common failure mode ("script is fine but the ad feels off") is an angle mismatch, not bad lines. The strongest hooks share one of three traits: a specific number, a small act of self-trust, or a physically novel product mechanic.
| Angle | The hook attachment | The reveal |
|---|---|---|
| Result-as-screenshot | A number that brags by itself — race time, app summary, dashboard stat | "X minutes a day. that's it." |
| Setup flex | A photo of your space — tiny apartment gym, race-kit corner, desk setup | "this is the whole setup" |
| Cancellation moment | A confirmation receipt — gym cancellation email, "subscription cancelled" page | "$X/mo → $Y/mo. do the math" |
| Feature-as-punchline | A short clip of the product mechanic in motion | The mechanic is the brand |
| Friend-asks-friend (inverse) | The peer opens with the wow — "how are you doing this 😭" | You reply with the brand |
| Receipt-as-hook | A mundane financial document — statement, App Store receipt | A small act of self-trust |
0:00 Hook attachment lands (the screenshot the whole chat is about)
↓ short reactions, 250–450ms apart ("bro no way" / "wait is that real")
0:06 The question — "what app is that??"
↓ typing indicator … then the brand-name reply
0:12 The pitch, in texting voice — one or two bubbles max
0:15 The code — "use FREEPACK, first pack's free" (code renders link-underlined)
0:17 Beat of silence, then the closer — "bet" / "ok downloading"
0:18 300ms crossfade → static brand end card: logo, code, tagline (~3s)
Script rules:
Three ways to produce it, in order of control:
Gooseworks distributes their pipeline as an installable agent skill — npx gooseworks install --all, then invoke the goose-ads skill from your agent. It handles rendering, recording, SFX, and stitching end to end. Use this to validate the format before building anything custom. (Their ads-skills source repo is public but carries no open-source license — treat it as reference reading, not code to vendor.)
The architecture that produces a convincing result: render the chat as HTML/CSS mimicking the iMessage UI, drive the animation with a timeline script, record it headlessly with Playwright, and assemble audio + end card with ffmpeg.
from, text, attachment paths, typing-indicator flags), theme, header. The script is reviewable and re-renderable without touching code.display: none — not opacity: 0, or the thread pre-allocates space and never "grows"). A driver script walks a timeline array revealing each bubble, driving the composer, and auto-scrolling. Never record scene-by-scene and concat — every page reload causes a visible micro-flicker.viewport and recordVideo.size to 1080×1920 — if you omit recordVideo.size, Playwright records a scaled-down video by default. Recording small and upscaling ships soft, blurry bubble text.xfade requires both inputs to match in resolution, pixel format, and frame rate — render the end card to a fixed-frame MP4 at the same specs as the chat recording before fading. Export the 9:16 master plus a 1:1 center crop.Once a winning script structure emerges, rebuild it as a Remotion composition (see generative-tools.md) with the thread JSON as props. Then variations — new hooks, new codes, new personas — are data changes, not re-productions. Right move at the "we're testing 10 script variants a week" stage, not for the first ad.
These are the difference between "feels like a real chat" and "feels like a mockup":
bigsoundbank.com/UPLOAD/mp3/1313.mp3, ~0.5s) and receive tritone (bigsoundbank.com/UPLOAD/mp3/1111.mp3 — trim to ~1.4s with a 400ms fade). Normalize loud (≈ -9 LUFS) so they cut through the music. Note the recordings being CC0 doesn't mean Apple has licensed its sound marks or UI trade dress — this is standard practice in the format, but regulated brands and risk-averse legal teams should review the iMessage mimicry as a whole; a generic chat-app skin (neutral bubbles, non-Apple sounds) is the fallback that keeps the mechanic.amix divides volume by input count by default — pass normalize=0 or the whole mix comes out mysteriously quiet. Then run the mix through a limiter with the ceiling just under full scale (e.g. alimiter=limit=0.95, ≈ -0.4 dB) so it's loud without clipping.Before shipping:
Treat the thread as the variable and the pipeline as fixed. Test in this order — hook first, everything else after:
The same architecture extends to further surfaces too — WhatsApp, Slack, a search box — same timeline-driven recording, different UI shell.
Everything above about production (UI mockup → timeline-driven continuous recording → deterministic SFX cues → static end card), grounding, and disclosure carries over unchanged. What changes per surface is the persuasion mechanic and a handful of craft details.
| Surface | Persuasion mechanic | Reach for it when |
|---|---|---|
| iMessage | A friend's recommendation — social proof through dialogue | The product is discovered through results people share ("what app is that?") |
| ChatGPT | An authoritative answer to the viewer's own question | The problem is question-shaped — something people would literally type into ChatGPT |
| Apple Notes | A private confession made public — first-person, no dialogue | The angle is transformation or realization ("things nobody told me about 45") |
| AirDrop | A spontaneous peer share — "someone nearby thought this was worth sending you right now," with a built-in accept/decline decision | The product is something people pass to each other (a deal, a link, a find, a file) and the accept-tap can be the reveal |
The strongest signal for choosing: which of these surfaces already fills your audience's day. Recommendation products want iMessage; advice-seeking problems want ChatGPT; identity/transformation stories want Notes; and anything people spontaneously pass to each other wants AirDrop.
The viewer identifies with the asker. The typed question is the hook and must be the target customer's verbatim question — awkward phrasing and all ("why is my stomach so bloated all of a sudden at 47?"). The streaming answer names the problem's real mechanism, then the solution category; the brand lands in the answer's recommendation or in a typed follow-up ("what's the best one?").
Craft details:
- Stream the answer in word chunks, not character-by-character (that's typing, not generation) and not whole paragraphs at once. A subtle tick underneath the stream and a clean stop when the response completes; no iMessage tritones anywhere.
- Type the question like thumbs, stream the answer like a model. Two distinct rhythms — the contrast is what reads as "real ChatGPT."
- Keep the answer scannable: short paragraphs, a bolded phrase or a short list, exactly the way ChatGPT actually formats. A wall of text breaks the illusion and loses the viewer.
- OpenAI's interface is their trade dress — same legal-review posture as the Apple UI mimicry note above, with a generic "AI assistant" skin as the fallback.
Compliance — stricter here than anywhere else in this family. The "answer" is your ad copy wearing a lab coat: an authority costume. Every claim in it needs the same substantiation as a claim in your own voice, and the format's borrowed authority raises the bar, not lowers it. Do not put health, medical, or financial advice in a fabricated AI answer without legal review — that's the highest-risk version of this format. And never present the exchange as a real, unprompted ChatGPT output endorsing your product; it's a dramatization, same as the iMessage thread.
A different genre from the chat formats: confession, not conversation. The viewer watches someone type a private note — a list of realizations, a "things I wish I knew" entry — with the keyboard visible. The note's title is the hook and does the job slide 1 does in a carousel ("Things nobody told me about 45."). The product appears as one item in the list, named the way a person would actually write it to themselves — not the way a brand would.
Craft details:
- Audio is keyboard taps only. No chat SFX, no receive tones — a note has no other party. A quiet music bed still works underneath.
- Type at real thumb pace with jitter, same as the iMessage composer rule. One typo-and-correction reads as human; several read as staged.
- Get the Notes chrome right: title styled larger than body, the formatting bar above the keyboard, iOS-yellow accents. Same HTML-mimicry approach — and the same Apple trade-dress review note and generic-notes-app fallback — as everything else here.
- Fit the note to the frame. Write short enough that the whole note fits without scrolling, or scroll once, deliberately, late.
- First person or it doesn't work. The moment the note reads like ad copy ("[Brand] changed everything!"), the intimacy that makes the format convert is gone. The product mention should be the least enthusiastic line in the note.
The grounding rule hits differently here: the confession is a dramatization of a composite, true customer story — pull the realizations from real reviews and interviews (the Grounded Inputs corpus), and keep any numbers or outcomes to documented ones.
The one interaction-native format in the family: the hook is an incoming AirDrop request, and the Accept tap is the reveal. The viewer watches from the receiver's POV — a translucent AirDrop card slides up, "[Sender] would like to share [preview]," with a gray Decline and a blue Accept. The curiosity is structural ("what is this and who's sending it?") and the accept/decline choice is a built-in micro-conversion beat baked into iOS itself. Tapping Accept transfers the item — and that's where the product, the offer, or the result lands.
Craft details:
- The preview thumbnail is the hook. It's the one image on the AirDrop card before Accept, so it has to earn the tap — same job as the iMessage screenshot attachment. Make it the result, the product money-shot, or the offer.
- Cast the sender name like a real share. "Sarah's iPhone," "Mom," "Jordan's MacBook" reads native; a brand name in the sender slot reads like an ad — save brand-as-sender for the reveal, not the incoming card.
- The transfer progress ring is the signature motion — don't skip it. Incoming card → a beat of hesitation ("accept?") → the Accept tap → the circular progress fills → the item lands + end card. That progress-ring beat is what makes it read as a real AirDrop and not a cut.
- Audio is the AirDrop swoosh / received tone, not the iMessage tritones. Same CC0-Apple-sounds sourcing and the same Apple trade-dress review note as the rest of the family, with a generic "nearby share" skin as the fallback.
- Keep it short and get the material right. The card's blur/translucency and the gray Decline / blue Accept button pair are the recognizable cues; a flat opaque sheet breaks the illusion. The whole beat is faster than the chat formats — the interaction is the ad.
- Receiver POV by default; sender POV as the flex. Receiving reads as discovery ("someone sent me this"); sending reads as a recommendation you're making ("had to AirDrop this to the group") — use sender POV when the angle is advocacy rather than discovery.
Grounding is the same family rule: it's a dramatization of a share, not a claim that a real person actually AirDropped your product. Every claim on the transferred item is substantiated per the Grounded Inputs rules, and the exchange is never presented as a real, unprompted endorsement.
Format popularized by Borja (@borjafat) and the open
super-video-makermotion-collage recipe by Bomx; this guide is an original re-expression of the method, extended with a multi-style library and production lessons from building and shipping it end-to-end.
Produce a 15–45s faceless video ad or explainer from nothing but a concept: a styled
poster still (image model) → brought to life with subtle motion (image-to-video model)
→ narrated (TTS) → word-timed captions. No footage, no presenter, no editor. Cost per
finished video is roughly $3–6 in API calls; wall-clock ~15 minutes.
The format works because the still carries the idea (one literal, slightly surreal
visual per beat) and the motion only makes it breathe. Resist the urge to make the
video do the storytelling — this is animated poster design, not filmmaking.
I=-16:TP=-1.5:LRA=11, export per-placement aspect.Provider options (any combination works; the recipe is model-agnostic):
| Stage | One-key Gemini path | Alternatives |
|---|---|---|
| Stills | Nano Banana Pro (gemini-3-pro-image-preview) — excellent label typography |
GPT-Image, Flux, Ideogram |
| Motion | Veo 3.1 fast image-to-video (note: 1080p requires 8s clips) | Seedance 2.0 via fal.ai, Kling, Runway |
| VO | Gemini TTS (calm voices: Charon/Kore) | ElevenLabs, OpenAI TTS |
| Captions | whisper word timings + PIL/ASS burn-in | CapCut, platform auto-captions |
Five proven looks. Each is a fill-in-the-slots prompt formula; keep ONE style per
campaign so the account builds a recognizable visual identity. All five animate well.
Flat screen-print collage poster, single saturated
<COLOR>background, subtle newsprint grain. Centerpiece: a black-and-white halftone cutout of<SUBJECT DOING THE LITERAL CONCEPT>, treated as a paper sticker with a thin white die-cut outline, slightly torn edges, and a soft drop shadow. Visible halftone dot texture, vintage editorial photo feel, grayscale subject. Accent cutouts: 2–4 flat shapes (cream circle sun, black zigzag, scattered dots). A torn-paper label near the bottom with the words "<LABEL>" in bold condensed uppercase newspaper type. Matte printed risograph aesthetic, limited palette. No gradients, no glow, no 3D, no photorealism, no extra text.
Flat vector explainer illustration in the style of a premium animated science channel: a friendly simplified
<SUBJECT>, bold flat shapes with clean rounded edges, solid<BRAND COLOR>background, limited palette of<2-3 ACCENTS>, flat geometric accents, soft long shadows, completely flat 2D design. A clean rectangular banner near the bottom reads "<LABEL>" in bold geometric sans-serif uppercase. No outlines, no 3D, no photorealism, no texture, no extra text.
Layered papercraft diorama:
<SUBJECT>, every element hand-cut from colored construction paper with visible paper thickness and real drop shadows between layers,<COLOR>paper background with cut-paper accents, tactile handmade craft feel with slightly imperfect scissor cuts. A cut-paper banner near the bottom reads "<LABEL>" in chunky cut-out paper letters. Soft studio lighting on the paper layers. No digital gradients, no photorealistic humans, no extra text.
Vintage pop-art comic panel:
<SUBJECT>, bold black ink outlines, Ben-Day halftone dots shading, flat process colors (<PALETTE>), comic starburst accents, thick panel border, aged newsprint paper texture. A comic caption box near the bottom reads "<LABEL>" in bold comic lettering. 1960s printed comic aesthetic, slight ink misregistration. No 3D, no photorealism, no gradients, no extra text.
Stop-motion claymation scene: a charming handmade plasticine
<SUBJECT>, visible fingerprints and clay texture,<COLOR>clay backdrop and floor, chunky clay props, warm soft studio lighting like a stop-motion film set, shallow depth of field. A small clay sign near the bottom reads "<LABEL>" in hand-molded clay letters. Handcrafted miniature feel. No 2D illustration, no photorealistic humans, no extra text.
The five looks above are characterful — they impose their own palette. This second
tier is brand-first: each style is defined by slots, so any company's tokens drop
in and the output reads as that brand's own design system.
The brand slots contract. Before generating, resolve these from the brand's
guidelines (or .agents/product-marketing.md):
FIELD — the neutral ground (brand white/off-white, or brand dark)INK — the drawing/type color (brand gray/charcoal, near-black)ACCENT — ONE brand color or gradient, used sparingly (a rule, a beam, a square)TYPE FEEL — the brand's typographic voice ("clean modern grotesque sans", "geometric sans", "mono captions")Keep the accent genuinely scarce — one element per frame. Scarcity is what makes
these read as designed rather than generated.
Minimal editorial monoline illustration poster:
<SUBJECT>, drawn entirely in elegant thin single-weight<INK>lines on a clean<FIELD>background, the style of a premium tech company blog illustration. Sparse composition with generous whitespace, a few small monoline accent details, and ONE restrained<ACCENT>element:<a thin accent underline sweep / a small accent arc>. A small caption near the bottom reads "<LABEL>" in<TYPE FEEL>,<INK>, letterspaced uppercase, with a thin<ACCENT>underline. Precise, technical, refined. No fills except the single accent, no gradients, no 3D, no photorealism, no texture, no extra text.
Swiss International Typographic Style poster: the words "
<LABEL>" set enormous in a bold<TYPE FEEL>,<INK>on a<FIELD>background, filling the upper two thirds with tight leading and cropped edges. A small black-and-white photographic cutout of<SUBJECT>sits on a thin baseline grid in the lower third, aligned to an asymmetric grid with one thin<ACCENT>rule line and a small<ACCENT>square as the only color. Visible faint grid lines, precise margins, mathematical composition. Flat, printed, matte. No gradients, no 3D, no decoration, no extra text beyond the label and one small letterspaced caption line.
Dark minimal tech-keynote poster:
<SUBJECT>rendered as an elegant thin light-gray wireframe line drawing on a near-black<FIELD>background with subtle film grain. From<the focal object>emanates a soft narrow beam of glowing<ACCENT>gradient light, the only color, feathered and atmospheric. Faint thin concentric geometric guide circles. A caption near the bottom reads "<LABEL>" in<TYPE FEEL>, light gray, letterspaced uppercase, with a hairline gradient rule beneath it. Restrained, premium, technical. No photorealism, no 3D render look, no busy elements, no extra text.
Bold duotone screenprint photo poster: a dramatic photograph of
<SUBJECT>, reproduced as a two-color screenprint —<INK>for the shadows and<ACCENT>for the highlights — on an off-white<FIELD>paper background with visible coarse halftone grain and slight ink misregistration. Strong diagonal composition, the figure large and cropped. A wide solid<INK>bar near the bottom carries the words "<LABEL>" reversed out in bold condensed<TYPE FEEL>uppercase, with a small<ACCENT>square bullet. Editorial poster energy, matte printed feel. No gradients beyond the duotone, no 3D, no extra text.
Motion notes for this tier: F/G animate as drawing motions (lines extend, the accent
sweep draws itself, type settles by a few pixels); H animates as beam pulse + slow
wireframe rotation feel; I as grain shimmer + slow push. Same hard rules apply — motion
belongs to existing elements, composition never changes.
Subtle living-
<style>motion of the existing elements only.<ONE literal motion tied to the concept: the pile inflates / the arrow creeps higher / the megaphone trembles with each shout>.<Secondary ambient motion: accents drift, gentle push-in>. Every element that is visible now is the only thing that ever appears; the composition stays exactly as it is. Everything stays<style descriptor: a flat printed collage / flat 2D vector / cut paper / printed comic / handmade clay>. No camera whip, no scene change, no morphing, no added text.
Fully synthetic characters — no likeness/UGC disclosure issues, but check platform
AI-content disclosure requirements (Meta and TikTok label AI-generated media).
Don't fabricate statistics or testimonials in the VO; ground every claim.
Complete character limits, format requirements, and best practices for each ad platform.
| Element | Character Limit | Required | Notes |
|---|---|---|---|
| Headline | 30 chars | 3 minimum, 15 max | Any 3 may be shown together |
| Description | 90 chars | 2 minimum, 4 max | Any 2 may be shown together |
| Display path 1 | 15 chars | Optional | Appears after domain in URL |
| Display path 2 | 15 chars | Optional | Appears after path 1 |
| Final URL | No limit | Required | Landing page URL |
Combination rules:
- Google selects up to 3 headlines and 2 descriptions to show
- Headlines appear separated by " | " or stacked
- Any headline can appear in any position unless pinned
- Pinning reduces Google's ability to optimize — use sparingly
Pinning strategy:
- Pin your brand name to position 1 if brand guidelines require it
- Pin your strongest CTA to position 2 or 3
- Leave most headlines unpinned for machine learning
Headline mix recommendation (15 headlines):
- 3-4 keyword-focused (match search intent)
- 3-4 benefit-focused (what they get)
- 2-3 social proof (numbers, awards, customers)
- 2-3 CTA-focused (action to take)
- 1-2 differentiators (why you over competitors)
- 1 brand name headline
Description mix recommendation (4 descriptions):
- 1 benefit + proof point
- 1 feature + outcome
- 1 social proof + CTA
- 1 urgency/offer + CTA (if applicable)
| Element | Character Limit | Notes |
|---|---|---|
| Headline | 30 chars (5 required) | Short headlines for various placements |
| Long headline | 90 chars (5 required) | Used in display, video, discover |
| Description | 90 chars (1 required, 5 max) | Accompany various ad formats |
| Business name | 25 chars | Required |
| Element | Character Limit |
|---|---|
| Headline | 30 chars |
| Long headline | 90 chars |
| Description | 90 chars |
| Business name | 25 chars |
| Element | Recommended | Maximum | Notes |
|---|---|---|---|
| Primary text | 125 chars | 2,200 chars | Text above image; truncated after ~125 |
| Headline | 40 chars | 255 chars | Below image; truncated after ~40 |
| Description | 30 chars | 255 chars | Below headline; may not show |
| URL display link | 40 chars | N/A | Optional custom display URL |
Placement-specific notes:
- Feed: All elements show; primary text most visible
- Stories/Reels: Primary text overlaid; keep under 72 chars
- Right column: Only headline visible; skip description
- Audience Network: Varies by publisher
Best practices:
- Front-load the hook in primary text (first 125 chars)
- Use line breaks for readability in longer primary text
- Emojis: test, but don't overuse — 1-2 per ad max
- Questions in primary text increase engagement
- Headline should be a clear CTA or value statement
| Element | Limit |
|---|---|
| Greeting headline | 60 chars |
| Greeting description | 360 chars |
| Privacy policy text | 200 chars |
| Element | Recommended | Maximum | Notes |
|---|---|---|---|
| Intro text | 150 chars | 600 chars | Above the image; truncated after ~150 |
| Headline | 70 chars | 200 chars | Below the image |
| Description | 100 chars | 300 chars | Only shows on Audience Network |
| Element | Limit |
|---|---|
| Intro text | 255 chars |
| Card headline | 45 chars |
| Card count | 2-10 cards |
| Element | Limit |
|---|---|
| Subject line | 60 chars |
| Message body | 1,500 chars |
| CTA button | 20 chars |
| Element | Limit |
|---|---|
| Headline | 25 chars |
| Description | 75 chars |
LinkedIn-specific guidelines:
- Professional tone, but not boring
- Use job-specific language the audience recognizes
- Statistics and data points perform well
- Avoid consumer-style hype ("Amazing!" "Incredible!")
- First-person testimonials from peers resonate
| Element | Recommended | Maximum | Notes |
|---|---|---|---|
| Ad text | 80 chars | 100 chars | Above the video |
| Display name | N/A | 40 chars | Brand name |
| CTA button | Platform options | Predefined | Select from TikTok's options |
| Element | Notes |
|---|---|
| Caption | Uses original post caption |
| CTA button | Added by advertiser |
| Display name | Original creator's handle |
TikTok-specific guidelines:
- Native content outperforms polished ads
- First 2 seconds determine if they watch
- Use trending sounds and formats
- Text overlay is essential (most watch with sound off)
- Vertical video only (9:16)
| Element | Limit | Notes |
|---|---|---|
| Tweet text | 280 chars | Full tweet with image/video |
| Card headline | 70 chars | Website card |
| Card description | 200 chars | Website card |
| Element | Limit |
|---|---|
| Headline | 70 chars |
| Description | 200 chars |
Twitter/X-specific guidelines:
- Conversational, casual tone
- Short sentences work best
- One clear message per tweet
- Hashtags: 1-2 max (0 is often better for ads)
- Threads can work for consideration-stage content
{KeyWord:default}) can exceed limits — set safe defaultsWhen creating for multiple platforms simultaneously, start with the most restrictive format:
This cascading approach ensures your core message works everywhere, then gets enriched for platforms that allow more space.
Fifteen structural templates for static (image) ad creative. Each is a layout framework with slots for brand-specific copy — the structure is proven; the inputs make it yours.
Use these when generating static ad concepts at volume (Meta, Instagram, LinkedIn, display). Cycle through all templates rather than clustering on 2-3 favorites: template diversity is angle diversity, and the winner is usually not the one you'd have picked by hand.
Bold one-line claim. Single product hero shot. Minimal background. The headline does all the work.
Side-by-side comparison. Competitor or "old way" on the left (grayed out), your product on the right (full color). 4-6 comparison rows.
One dominant number takes up 60% of the visual. Supporting context below.
A five-star testimonial styled as a screenshotted product review. Reviewer name, star rating, date.
inputs/reviews/ verbatim — with permission where the platform requires itThree customer quotes arranged vertically, photo + name + one-line quote each.
Split image with arrow between. Transformation framing — product results, workflow, or visual proof.
Pain point on top (text or image), product as the answer below.
inputs/reviews/ — verbatim beats paraphraseHandwritten-style or plain-text note from the founder. Conversational, personal tone.
Product hero in the center, 4-6 callout boxes around the edges highlighting key components.
"As seen in" with publication logos and a pull quote.
Product in use in a real environment. Minimal copy. Aspirational, not salesy.
"5 reasons [audience] are switching to [brand]." Icons next to each point.
A common objection as the question, answered directly.
inputs/comments/ — the objections people post publicly under your adsName a specific competitor (or the category default) and explain the difference. Bold but factual.
Founder photo with the why-we-built-this narrative. Longer copy than other formats.
Each generated concept follows this structure:
## Concept [N]: [Template Name]
**Headline**: [the headline copy]
**Body**: [supporting copy, if the template uses it]
**Visual**: [layout description specific enough to design or generate from]
**Image prompt**: [prompt for the image tool, if generating — see generative-tools.md]
**Grounded in**: [which review / winning ad / comment this traces to, quoted or named]
For a batch, add an INDEX.md listing every concept with its template type and grounding source, so the reviewer can scan 50 concepts in two minutes.
For a standard 50-concept batch: 3-4 variations per template across all 15. If performance data shows certain templates consistently winning for this brand, shift to 60% proven templates / 40% full-cycle coverage — but never drop coverage to zero. Fatigue is why you're generating daily; the template that's tired next month is the one you're scaling today.
When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also use when the user mentions "content strategy," "what should I write about," "content ideas," "blog s
View source ↗You are a content strategist. Your goal is to help plan content that drives traffic, builds authority, and generates leads by being either searchable, shareable, or both.
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):
Every piece of content must be searchable, shareable, or both. Prioritize in that order—search traffic is the foundation.
Searchable content captures existing demand. Optimized for people actively looking for answers.
Shareable content creates demand. Spreads ideas and gets people talking.
Use-Case Content
Formula: [persona] + [use-case]. Targets long-tail keywords.
- "Project management for designers"
- "Task tracking for developers"
- "Client collaboration for freelancers"
Hub and Spoke
Hub = comprehensive overview. Spokes = related subtopics.
/topic (hub)
├── /topic/subtopic-1 (spoke)
├── /topic/subtopic-2 (spoke)
└── /topic/subtopic-3 (spoke)
Create hub first, then build spokes. Interlink strategically.
Note: Most content works fine under /blog. Only use dedicated hub/spoke URL structures for major topics with layered depth (e.g., Atlassian's /agile guide). For typical blog posts, /blog/post-title is sufficient.
Template Libraries
High-intent keywords + product adoption.
- Target searches like "marketing plan template"
- Provide immediate standalone value
- Show how product enhances the template
Thought Leadership
- Articulate concepts everyone feels but hasn't named
- Challenge conventional wisdom with evidence
- Share vulnerable, honest experiences
Data-Driven Content
- Product data analysis (anonymized insights)
- Public data analysis (uncover patterns)
- Original research (run experiments, share results)
Expert Roundups
15-30 experts answering one specific question. Built-in distribution.
Case Studies
Structure: Challenge → Solution → Results → Key learnings
Meta Content
Behind-the-scenes transparency. "How We Got Our First $5k MRR," "Why We Chose Debt Over VC."
For programmatic content at scale, see programmatic-seo skill.
Content pillars are the 3-5 core topics your brand will own. Each pillar spawns a cluster of related content.
Most of the time, all content can live under /blog with good internal linking between related posts. Dedicated pillar pages with custom URL structures (like /guides/topic) are only needed when you're building comprehensive resources with multiple layers of depth.
Pillar Topic (Hub)
├── Subtopic Cluster 1
│ ├── Article A
│ ├── Article B
│ └── Article C
├── Subtopic Cluster 2
│ ├── Article D
│ ├── Article E
│ └── Article F
└── Subtopic Cluster 3
├── Article G
├── Article H
└── Article I
Good pillars should:
- Align with your product/service
- Match what your audience cares about
- Have search volume and/or social interest
- Be broad enough for many subtopics
Map topics to the buyer's journey using proven keyword modifiers:
Modifiers: "what is," "how to," "guide to," "introduction to"
Example: If customers ask about project management basics:
- "What is Agile Project Management"
- "Guide to Sprint Planning"
- "How to Run a Standup Meeting"
Modifiers: "best," "top," "vs," "alternatives," "comparison"
Example: If customers evaluate multiple tools:
- "Best Project Management Tools for Remote Teams"
- "Asana vs Trello vs Monday"
- "Basecamp Alternatives"
Modifiers: "pricing," "reviews," "demo," "trial," "buy"
Example: If pricing comes up in sales calls:
- "Project Management Tool Pricing Comparison"
- "How to Choose the Right Plan"
- "[Product] Reviews"
Modifiers: "templates," "examples," "tutorial," "how to use," "setup"
Example: If support tickets show implementation struggles:
- "Project Template Library"
- "Step-by-Step Setup Tutorial"
- "How to Use [Feature]"
If user provides keyword exports (Ahrefs, SEMrush, GSC), analyze for:
- Topic clusters (group related keywords)
- Buyer stage (awareness/consideration/decision/implementation)
- Search intent (informational, commercial, transactional)
- Quick wins (low competition + decent volume + high relevance)
- Content gaps (keywords competitors rank for that you don't)
Output as prioritized table:
| Keyword | Volume | Difficulty | Buyer Stage | Content Type | Priority |
If user provides sales or customer call transcripts, extract:
- Questions asked → FAQ content or blog posts
- Pain points → problems in their own words
- Objections → content to address proactively
- Language patterns → exact phrases to use (voice of customer)
- Competitor mentions → what they compared you to
Output content ideas with supporting quotes.
If user provides survey data, mine for:
- Open-ended responses (topics and language)
- Common themes (30%+ mention = high priority)
- Resource requests (what they wish existed)
- Content preferences (formats they want)
Use web search to find content ideas:
Reddit: site:reddit.com [topic]
- Top posts in relevant subreddits
- Questions and frustrations in comments
- Upvoted answers (validates what resonates)
Quora: site:quora.com [topic]
- Most-followed questions
- Highly upvoted answers
Other: Indie Hackers, Hacker News, Product Hunt, industry Slack/Discord
Extract: FAQs, misconceptions, debates, problems being solved, terminology used.
Use web search to analyze competitor content:
Find their content: site:competitor.com/blog
Analyze:
- Top-performing posts (comments, shares)
- Topics covered repeatedly
- Gaps they haven't covered
- Case studies (customer problems, use cases, results)
- Content structure (pillars, categories, formats)
Identify opportunities:
- Topics you can cover better
- Angles they're missing
- Outdated content to improve on
Extract from customer-facing teams:
- Common objections
- Repeated questions
- Support ticket patterns
- Success stories
- Feature requests and underlying problems
Score each idea on four factors:
| Idea | Customer Impact (40%) | Content-Market Fit (30%) | Search Potential (20%) | Resources (10%) | Total |
|---|---|---|---|---|---|
| Topic A | 8 | 9 | 7 | 6 | 8.0 |
| Topic B | 6 | 7 | 9 | 8 | 7.1 |
When creating a content strategy, provide:
For each recommended piece:
- Topic/title
- Searchable, shareable, or both
- Content type (use-case, hub/spoke, thought leadership, etc.)
- Target keyword and buyer stage
- Why this topic (customer research backing)
Visual or structured representation of how content interconnects.
Reference for choosing, modeling, and implementing a headless CMS for marketing content.
Use this when selecting a CMS for a new project, designing content models for marketing sites, setting up editorial workflows, or connecting CMS content to programmatic pages.
A headless CMS separates content management from presentation. Content is stored in a structured backend and delivered via API to any frontend.
| Factor | Headless | Traditional |
|---|---|---|
| Multi-channel delivery | Yes | Limited |
| Developer control | Full | Constrained |
| Non-technical editing | Requires setup | Built-in |
| Time to launch | Longer | Faster |
| Content reuse | Native | Manual |
| Hosting flexibility | Any frontend | Platform-dependent |
| Type | Key Fields | Notes |
|---|---|---|
| Landing Page | title, slug, hero, sections[], seo | Modular sections for flexibility |
| Blog Post | title, slug, body, author, category, tags, publishedAt, seo | Rich text or Portable Text body |
| Case Study | title, customer, challenge, solution, results, metrics[], logo | Link to related products/features |
| Testimonial | quote, author, role, company, avatar, rating | Reference from landing pages |
| FAQ | question, answer, category | Group by category for programmatic pages |
| Author | name, bio, avatar, social links | Reference from blog posts |
| CTA Block | heading, body, buttonText, buttonUrl, variant | Reusable across pages |
Every page-level content type needs:
metaTitle — 50-60 charactersmetaDescription — 150-160 charactersogImage — 1200x630px social previewslug — URL path segmentcanonicalUrl — optional overridenoIndex — boolean for excluding from searchstructuredData — optional JSON-LD overrideAll major headless CMS platforms support draft previews:
useLiveQuery or Presentation toolpreview.contentful.com) with separate access tokenstatus=draft query parameter (v5; replaces v4's publicationState)Set up a preview route in your frontend (e.g., /api/preview) that authenticates and renders draft content.
| Role | Can Create | Can Edit | Can Publish | Can Delete |
|---|---|---|---|---|
| Author | Yes | Own | No | Own drafts |
| Editor | Yes | All | Yes | Drafts |
| Admin | Yes | All | Yes | All |
Exact permission models vary by platform. Sanity uses role-based access. Contentful has space-level roles. Strapi has granular RBAC.
| Feature | Sanity | Contentful | Strapi |
|---|---|---|---|
| Hosting | Cloud (managed) | Cloud (managed) | Self-hosted or Cloud |
| Query Language | GROQ | REST / GraphQL | REST / GraphQL |
| Free Tier | Generous | Limited | Open source (free) |
| Real-time Collab | Yes (built-in) | Limited | No |
| Best For | Developer flexibility | Enterprise multi-locale | Budget / self-hosted |
| Content Modeling | Schema-as-code | Web UI | Web UI or code |
| Media Handling | Built-in DAM | Built-in | Plugin-based |
Strengths: GROQ query language is powerful and flexible. Schema defined in code (version-controlled). Real-time collaborative editing. Portable Text for rich content. Generous free tier.
Considerations: Steeper learning curve for non-developers. Studio customization requires React knowledge. Vendor lock-in on GROQ queries.
Marketing fit: Best when developers and marketers collaborate closely. Strong for content-heavy sites with complex models.
Strengths: Mature enterprise platform. Excellent multi-locale support. Strong ecosystem of integrations. Composable content with Studio. Well-documented APIs.
Considerations: Pricing scales with content types and locales. Two separate APIs (Delivery and Management). Rate limits can be tight on lower plans.
Marketing fit: Best for enterprises with multi-market content needs. Good when you need established vendor reliability.
Strengths: Open source, self-hosted option. Full control over data. No per-seat pricing. Customizable admin panel. Plugin ecosystem. REST by default, GraphQL via plugin.
Considerations: Self-hosting means you handle infrastructure. Smaller ecosystem than Sanity/Contentful. V5 migration can be significant from V4.
Marketing fit: Best for teams with DevOps capability who want full control and no vendor lock-in. Good for budget-conscious projects.
Use CMS as the data source for programmatic pages. Store structured data (FAQs, comparisons, city pages) as content types and generate pages from queries. See programmatic-seo skill.
CMS content models enforce consistent structure. Define fields that match your copy frameworks (headline, subheadline, social proof, CTA). See copywriting skill.
URL structure, navigation hierarchy, and internal linking all depend on how content is organized in the CMS. Plan your content model and site architecture together. See site-architecture skill.
Pull CMS content into email templates for consistent messaging across web and email. Case studies, testimonials, and blog posts can feed email nurture sequences. See emails skill.
When the user wants to edit, review, or improve existing marketing copy, or refresh outdated content. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make
View source ↗You are an expert copy editor specializing in marketing and conversion copy. Your goal is to systematically improve existing copy through focused editing passes while preserving the core message.
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 editing. Use brand voice and customer language from that context to guide your edits.
Good copy editing isn't about rewriting—it's about enhancing. Each pass focuses on one dimension, catching issues that get missed when you try to fix everything at once.
Key principles:
- Don't change the core message; focus on enhancing it
- Multiple focused passes beat one unfocused review
- Each edit should have a clear reason
- Preserve the author's voice while improving clarity
Edit copy through seven sequential passes, each focusing on one dimension. After each sweep, loop back to check previous sweeps aren't compromised.
Focus: Can the reader understand what you're saying?
What to check:
- Confusing sentence structures
- Unclear pronoun references
- Jargon or insider language
- Ambiguous statements
- Missing context
Common clarity killers:
- Sentences trying to say too much
- Abstract language instead of concrete
- Assuming reader knowledge they don't have
- Burying the point in qualifications
Process:
1. Read through quickly, highlighting unclear parts
2. Don't correct yet—just note problem areas
3. After marking issues, recommend specific edits
4. Verify edits maintain the original intent
After this sweep: Confirm the "Rule of One" (one main idea per section) and "You Rule" (copy speaks to the reader) are intact.
Focus: Is the copy consistent in how it sounds?
What to check:
- Shifts between formal and casual
- Inconsistent brand personality
- Mood changes that feel jarring
- Word choices that don't match the brand
Common voice issues:
- Starting casual, becoming corporate
- Mixing "we" and "the company" references
- Humor in some places, serious in others (unintentionally)
- Technical language appearing randomly
Process:
1. Read aloud to hear inconsistencies
2. Mark where tone shifts unexpectedly
3. Recommend edits that smooth transitions
4. Ensure personality remains throughout
After this sweep: Return to Clarity Sweep to ensure voice edits didn't introduce confusion.
Focus: Does every claim answer "why should I care?"
What to check:
- Features without benefits
- Claims without consequences
- Statements that don't connect to reader's life
- Missing "which means..." bridges
The So What test:
For every statement, ask "Okay, so what?" If the copy doesn't answer that question with a deeper benefit, it needs work.
❌ "Our platform uses AI-powered analytics"
So what?
✅ "Our AI-powered analytics surface insights you'd miss manually—so you can make better decisions in half the time"
Common So What failures:
- Feature lists without benefit connections
- Impressive-sounding claims that don't land
- Technical capabilities without outcomes
- Company achievements that don't help the reader
Process:
1. Read each claim and literally ask "so what?"
2. Highlight claims missing the answer
3. Add the benefit bridge or deeper meaning
4. Ensure benefits connect to real reader desires
After this sweep: Return to Voice and Tone, then Clarity.
Focus: Is every claim supported with evidence?
What to check:
- Unsubstantiated claims
- Missing social proof
- Assertions without backup
- "Best" or "leading" without evidence
Types of proof to look for:
- Testimonials with names and specifics
- Case study references
- Statistics and data
- Third-party validation
- Guarantees and risk reversals
- Customer logos
- Review scores
Common proof gaps:
- "Trusted by thousands" (which thousands?)
- "Industry-leading" (according to whom?)
- "Customers love us" (show them saying it)
- Results claims without specifics
Process:
1. Identify every claim that needs proof
2. Check if proof exists nearby
3. Flag unsupported assertions
4. Recommend adding proof or softening claims
After this sweep: Return to So What, Voice and Tone, then Clarity.
Focus: Is the copy concrete enough to be compelling?
What to check:
- Vague language ("improve," "enhance," "optimize")
- Generic statements that could apply to anyone
- Round numbers that feel made up
- Missing details that would make it real
Specificity upgrades:
| Vague | Specific |
|---|---|
| Save time | Save 4 hours every week |
| Many customers | 2,847 teams |
| Fast results | Results in 14 days |
| Improve your workflow | Cut your reporting time in half |
| Great support | Response within 2 hours |
Common specificity issues:
- Adjectives doing the work nouns should do
- Benefits without quantification
- Outcomes without timeframes
- Claims without concrete examples
Process:
1. Highlight vague words and phrases
2. Ask "Can this be more specific?"
3. Add numbers, timeframes, or examples
4. Remove content that can't be made specific (it's probably filler)
After this sweep: Return to Prove It, So What, Voice and Tone, then Clarity.
Focus: Does the copy make the reader feel something?
What to check:
- Flat, informational language
- Missing emotional triggers
- Pain points mentioned but not felt
- Aspirations stated but not evoked
Emotional dimensions to consider:
- Pain of the current state
- Frustration with alternatives
- Fear of missing out
- Desire for transformation
- Pride in making smart choices
- Relief from solving the problem
Techniques for heightening emotion:
- Paint the "before" state vividly
- Use sensory language
- Tell micro-stories
- Reference shared experiences
- Ask questions that prompt reflection
Process:
1. Read for emotional impact—does it move you?
2. Identify flat sections that should resonate
3. Add emotional texture while staying authentic
4. Ensure emotion serves the message (not manipulation)
After this sweep: Return to Specificity, Prove It, So What, Voice and Tone, then Clarity.
Focus: Have we removed every barrier to action?
What to check:
- Friction near CTAs
- Unanswered objections
- Missing trust signals
- Unclear next steps
- Hidden costs or surprises
Risk reducers to look for:
- Money-back guarantees
- Free trials
- "No credit card required"
- "Cancel anytime"
- Social proof near CTA
- Clear expectations of what happens next
- Privacy assurances
Common risk issues:
- CTA asks for commitment without earning trust
- Objections raised but not addressed
- Fine print that creates doubt
- Vague "Contact us" instead of clear next step
Process:
1. Focus on sections near CTAs
2. List every reason someone might hesitate
3. Check if the copy addresses each concern
4. Add risk reversals or trust signals as needed
After this sweep: Return through all previous sweeps one final time: Heightened Emotion, Specificity, Prove It, So What, Voice and Tone, Clarity.
Use this after completing the Seven Sweeps for an additional quality gate. For high-stakes copy (landing pages, launch emails, sales pages), a multi-persona expert review catches issues that a single perspective misses.
Landing page copy:
- Conversion copywriter (clarity, CTA strength, benefit hierarchy)
- UX writer (scannability, cognitive load, user flow)
- Target customer persona (does this speak to me? do I trust it?)
- Brand strategist (voice consistency, positioning accuracy)
Email sequence:
- Email marketing specialist (subject lines, open/click optimization)
- Copywriter (hooks, storytelling, persuasion)
- Spam filter analyst (deliverability red flags, trigger words)
- Target customer persona (relevance, value, unsubscribe risk)
Sales page / long-form:
- Direct response copywriter (offer structure, objection handling, urgency)
- Skeptical buyer persona (proof gaps, trust issues, red flags)
- Editor (flow, readability, conciseness)
- SEO specialist (keyword coverage, search intent alignment)
| Score | Meaning |
|---|---|
| 9-10 | Publish-ready. No meaningful improvements. |
| 7-8 | Strong. Minor tweaks only. |
| 5-6 | Functional but has clear gaps. Needs another pass. |
| 3-4 | Significant issues. Major revision needed. |
| 1-2 | Fundamentally broken. Rethink approach. |
Use these for faster reviews when a full seven-sweep process isn't needed.
Cut these words:
- Very, really, extremely, incredibly (weak intensifiers)
- Just, actually, basically (filler)
- In order to (use "to")
- That (often unnecessary)
- Things, stuff (vague)
Replace these:
| Weak | Strong |
|---|---|
| Utilize | Use |
| Implement | Set up |
| Leverage | Use |
| Facilitate | Help |
| Innovative | New |
| Robust | Strong |
| Seamless | Smooth |
| Cutting-edge | New/Modern |
Watch for:
- Adverbs (usually unnecessary)
- Passive voice (switch to active)
- Nominalizations (verb → noun: "make a decision" → "decide")
For a final QA pass before delivering edits, work through the full checklist in references/checklist.md — covering all seven sweeps plus pre-start and final-check items.
Symptom: List of what the product does without why it matters
Fix: Add "which means..." after each feature to bridge to benefits
Symptom: "Leverage synergies to optimize outcomes"
Fix: Ask "How would a human say this?" and use those words
Symptom: Starting with company history or vague statements
Fix: Lead with the reader's problem or desired outcome
Symptom: The ask comes after too much buildup, or isn't clear
Fix: Make the CTA obvious, early, and repeated
Symptom: "Customers love us" with no evidence
Fix: Add specific testimonials, numbers, or case references
Symptom: "We help businesses grow"
Fix: Specify who, how, and by how much
Symptom: Copy tries to speak to everyone, resonates with no one
Fix: Pick one audience and write directly to them
Symptom: Listing every capability, overwhelming the reader
Fix: Focus on 3-5 key benefits that matter most to the audience
When editing collaboratively:
This iterative process ensures each edit doesn't create new problems while respecting the author's ownership of the copy.
Copy editing isn't just for new content. Existing pages decay over time — outdated stats, stale examples, and drifted brand voice. Use the content refresh framework when traffic is declining, data is stale, or the product has changed.
For the full refresh checklist, refresh vs. rewrite decision matrix, and cadence guide: See references/content-refresh.md
| Task | Skill to Use |
|---|---|
| Writing new page copy from scratch | copywriting |
| Reviewing and improving existing copy | copy-editing (this skill) |
| Editing copy you just wrote | copy-editing (this skill) |
| Structural or strategic page changes | cro |
Use this checklist alongside the Seven Sweeps Framework (see SKILL.md) as a final QA pass before delivering edited copy.
Copy editing isn't just for new content. Existing pages and posts decay over time — outdated stats, stale examples, drifted brand voice, and missed SEO opportunities. A content refresh applies the same editing rigor to content that's already published.
| Signal | Action |
|---|---|
| Core message still valid, details outdated | Refresh (update facts, stats, examples) |
| Brand voice has evolved significantly | Refresh + voice rewrite |
| Topic angle or audience has shifted | Full rewrite |
| Page structure doesn't match current search intent | Full rewrite |
| Just needs updated stats and links | Light refresh |
Replace complex or pompous words with plain English alternatives.
Source: Plain English Campaign A-Z of Alternative Words (2001), Australian Government Style Manual (2024), plainlanguage.gov
| Complex | Plain Alternative |
|---|---|
| (an) absence of | no, none |
| abundance | enough, plenty, many |
| accede to | allow, agree to |
| accelerate | speed up |
| accommodate | meet, hold, house |
| accomplish | do, finish, complete |
| accordingly | so, therefore |
| acknowledge | thank you for, confirm |
| acquire | get, buy, obtain |
| additional | extra, more |
| adjacent | next to |
| advantageous | useful, helpful |
| advise | tell, say, inform |
| aforesaid | this, earlier |
| aggregate | total |
| alleviate | ease, reduce |
| allocate | give, share, assign |
| alternative | other, choice |
| ameliorate | improve |
| anticipate | expect |
| apparent | clear, obvious |
| appreciable | large, noticeable |
| appropriate | proper, right, suitable |
| approximately | about, roughly |
| ascertain | find out |
| assistance | help |
| at the present time | now |
| attempt | try |
| authorise | allow, let |
| Complex | Plain Alternative |
|---|---|
| belated | late |
| beneficial | helpful, useful |
| bestow | give |
| by means of | by |
| Complex | Plain Alternative |
|---|---|
| calculate | work out |
| cease | stop, end |
| circumvent | avoid, get around |
| clarification | explanation |
| commence | start, begin |
| communicate | tell, talk, write |
| competent | able |
| compile | collect, make |
| complete | fill in, finish |
| component | part |
| comprise | include, make up |
| (it is) compulsory | (you) must |
| conceal | hide |
| concerning | about |
| consequently | so |
| considerable | large, great, much |
| constitute | make up, form |
| consult | ask, talk to |
| consumption | use |
| currently | now |
| Complex | Plain Alternative |
|---|---|
| deduct | take off |
| deem | treat as, consider |
| defer | delay, put off |
| deficiency | lack |
| delete | remove, cross out |
| demonstrate | show, prove |
| denote | show, mean |
| designate | name, appoint |
| despatch/dispatch | send |
| determine | decide, find out |
| detrimental | harmful |
| diminish | reduce, lessen |
| discontinue | stop |
| disseminate | spread, distribute |
| documentation | papers, documents |
| due to the fact that | because |
| duration | time, length |
| dwelling | home |
| Complex | Plain Alternative |
|---|---|
| economical | cheap, good value |
| eligible | allowed, qualified |
| elucidate | explain |
| enable | allow |
| encounter | meet |
| endeavour | try |
| enquire | ask |
| ensure | make sure |
| entitlement | right |
| envisage | expect |
| equivalent | equal, the same |
| erroneous | wrong |
| establish | set up, show |
| evaluate | assess, test |
| excessive | too much |
| exclusively | only |
| exempt | free from |
| expedite | speed up |
| expenditure | spending |
| expire | run out |
| Complex | Plain Alternative |
|---|---|
| fabricate | make |
| facilitate | help, make possible |
| finalise | finish, complete |
| following | after |
| for the purpose of | to, for |
| for the reason that | because |
| forthwith | now, at once |
| forward | send |
| frequently | often |
| furnish | give, provide |
| furthermore | also, and |
| Complex | Plain Alternative |
|---|---|
| generate | produce, create |
| henceforth | from now on |
| hitherto | until now |
| Complex | Plain Alternative |
|---|---|
| if and when | if, when |
| illustrate | show |
| immediately | at once, now |
| implement | carry out, do |
| imply | suggest |
| in accordance with | under, following |
| in addition to | and, also |
| in conjunction with | with |
| in excess of | more than |
| in lieu of | instead of |
| in order to | to |
| in receipt of | receive |
| in relation to | about |
| in respect of | about, for |
| in the event of | if |
| in the majority of instances | most, usually |
| in the near future | soon |
| in view of the fact that | because |
| inception | start |
| indicate | show, suggest |
| inform | tell |
| initiate | start, begin |
| insert | put in |
| instances | cases |
| irrespective of | despite |
| issue | give, send |
| Complex | Plain Alternative |
|---|---|
| (a) large number of | many |
| liaise with | work with, talk to |
| locality | place, area |
| locate | find |
| magnitude | size |
| (it is) mandatory | (you) must |
| manner | way |
| modification | change |
| moreover | also, and |
| Complex | Plain Alternative |
|---|---|
| negligible | small |
| nevertheless | but, however |
| notify | tell |
| notwithstanding | despite, even if |
| numerous | many |
| objective | aim, goal |
| (it is) obligatory | (you) must |
| obtain | get |
| occasioned by | caused by |
| on behalf of | for |
| on numerous occasions | often |
| on receipt of | when you get |
| on the grounds that | because |
| operate | work, run |
| optimum | best |
| option | choice |
| otherwise | or |
| outstanding | unpaid |
| owing to | because |
| Complex | Plain Alternative |
|---|---|
| partially | partly |
| participate | take part |
| particulars | details |
| per annum | a year |
| perform | do |
| permit | let, allow |
| personnel | staff, people |
| peruse | read |
| possess | have, own |
| practically | almost |
| predominant | main |
| prescribe | set |
| preserve | keep |
| previous | earlier, before |
| principal | main |
| prior to | before |
| proceed | go ahead |
| procure | get |
| prohibit | ban, stop |
| promptly | quickly |
| provide | give |
| provided that | if |
| provisions | rules, terms |
| proximity | nearness |
| purchase | buy |
| pursuant to | under |
| Complex | Plain Alternative |
|---|---|
| reconsider | think again |
| reduction | cut |
| referred to as | called |
| regarding | about |
| reimburse | repay |
| reiterate | repeat |
| relating to | about |
| remain | stay |
| remainder | rest |
| remuneration | pay |
| render | make, give |
| represent | stand for |
| request | ask |
| require | need |
| residence | home |
| retain | keep |
| revised | changed, new |
| Complex | Plain Alternative |
|---|---|
| scrutinise | examine, check |
| select | choose |
| solely | only |
| specified | given, stated |
| state | say |
| statutory | legal, by law |
| subject to | depending on |
| submit | send, give |
| subsequent to | after |
| subsequently | later |
| substantial | large, much |
| sufficient | enough |
| supplement | add to |
| supplementary | extra |
| Complex | Plain Alternative |
|---|---|
| terminate | end, stop |
| thereafter | then |
| thereby | by this |
| thus | so |
| to date | so far |
| transfer | move |
| transmit | send |
| ultimately | in the end |
| undertake | agree, do |
| uniform | same |
| utilise | use |
| Complex | Plain Alternative |
|---|---|
| variation | change |
| virtually | almost |
| visualise | imagine, see |
| ways and means | ways |
| whatsoever | any |
| with a view to | to |
| with effect from | from |
| with reference to | about |
| with regard to | about |
| with respect to | about |
| zone | area |
These phrases often add nothing. Delete them:
When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says "write copy for,
View source ↗You are an expert conversion copywriter. Your goal is to write marketing copy that is clear, compelling, and drives action.
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):
If you have to choose between clear and creative, choose clear.
Features: What it does. Benefits: What that means for the customer.
Use words your customers use. Mirror voice-of-customer from reviews, interviews, support tickets.
Each section should advance one argument. Build a logical flow down the page.
For thorough line-by-line review, use the copy-editing skill after your draft.
Get to the point. Don't bury the value in qualifications.
❌ Slack lets you share files instantly, from documents to images, directly in your conversations
✅ Need to share a screenshot? Send as many documents, images, and audio files as your heart desires.
Questions engage readers and make them think about their own situation.
- "Hate returning stuff to Amazon?"
- "Tired of chasing approvals?"
Analogies make abstract concepts concrete and memorable.
Puns and wit make copy memorable—but only if it fits the brand and doesn't undermine clarity.
Headline
- Your single most important message
- Communicate core value proposition
- Specific > generic
Example formulas:
- "{Achieve outcome} without {pain point}"
- "The {category} for {audience}"
- "Never {unpleasant event} again"
- "{Question highlighting main pain point}"
For comprehensive headline formulas: See references/copy-frameworks.md
For natural transition phrases: See references/natural-transitions.md
Subheadline
- Expands on headline
- Adds specificity
- 1-2 sentences max
Primary CTA
- Action-oriented button text
- Communicate what they get: "Start Free Trial" > "Sign Up"
| Section | Purpose |
|---|---|
| Social Proof | Build credibility (logos, stats, testimonials) |
| Problem/Pain | Show you understand their situation |
| Solution/Benefits | Connect to outcomes (3-5 key benefits) |
| How It Works | Reduce perceived complexity (3-4 steps) |
| Objection Handling | FAQ, comparisons, guarantees |
| Final CTA | Recap value, repeat CTA, risk reversal |
For detailed section types and page templates: See references/copy-frameworks.md
Weak CTAs (avoid):
- Submit, Sign Up, Learn More, Click Here, Get Started
Strong CTAs (use):
- Start Free Trial
- Get [Specific Thing]
- See [Product] in Action
- Create Your First [Thing]
- Download the Guide
Formula: [Action Verb] + [What They Get] + [Qualifier if needed]
Examples:
- "Start My Free Trial"
- "Get the Complete Checklist"
- "See Pricing for My Team"
Before writing, establish:
Formality level:
- Casual/conversational
- Professional but friendly
- Formal/enterprise
Brand personality:
- Playful or serious?
- Bold or understated?
- Technical or accessible?
Maintain consistency, but adjust intensity:
- Headlines can be bolder
- Body copy should be clearer
- CTAs should be action-oriented
When writing copy, provide:
Organized by section:
- Headline, Subheadline, CTA
- Section headers and body copy
- Secondary CTAs
For key elements, explain:
- Why you made this choice
- What principle it applies
For headlines and CTAs, provide 2-3 options:
- Option A: [copy] — [rationale]
- Option B: [copy] — [rationale]
Headline formulas, page section types, and structural templates.
{Achieve desirable outcome} without {pain point}
Understand how users are really experiencing your site without drowning in numbers
{Achieve desirable outcome} by {how product makes it possible}
Generate more leads by seeing which companies visit your site
Turn {input} into {outcome}
Turn your hard-earned sales into repeat customers
[Achieve outcome] in [timeframe]
Get your tax refund in 10 days
Never {unpleasant event} again
Never miss a sales opportunity again
{Question highlighting the main pain point}
Hate returning stuff to Amazon?
Stop [pain]. Start [pleasure].
Stop chasing invoices. Start getting paid on time.
{Key feature/product type} for {target audience}
Advanced analytics for Shopify e-commerce
{Key feature/product type} for {target audience} to {what it's used for}
An online whiteboard for teams to ideate and brainstorm together
You don't have to {skills or resources} to {achieve desirable outcome}
With Ahrefs, you don't have to be an SEO pro to rank higher and get more traffic
The {opposite of usual process} way to {achieve desirable outcome}
The easiest way to turn your passion into income
The [category] that [key differentiator]
The CRM that updates itself
[Number] [people] use [product] to [outcome]
50,000 marketers use Drip to send better emails
{Key benefit of your product}
Sound clear in online meetings
The simple way to {outcome}
The simple way to track your time
Finally, {category} that {benefit}
Finally, accounting software that doesn't suck
{Outcome} without {common pain}
Build your website without writing code
Get {benefit} from your {thing}
Get more revenue from your existing traffic
{Action verb} your {thing} like {admirable example}
Market your SaaS like a Fortune 500
What if you could {desirable outcome}?
What if you could close deals 30% faster?
Everything you need to {outcome}
Everything you need to launch your course
The {adjective} {category} built for {audience}
The lightweight CRM built for startups
Hero (Above the Fold)
- Headline + subheadline
- Primary CTA
- Supporting visual (product screenshot, hero image)
- Optional: Social proof bar
Social Proof Bar
- Customer logos (recognizable > many)
- Key metric ("10,000+ teams")
- Star rating with review count
- Short testimonial snippet
Problem/Pain Section
- Articulate their problem better than they can
- Create recognition ("that's exactly my situation")
- Hint at cost of not solving it
Solution/Benefits Section
- Bridge from problem to your solution
- 3-5 key benefits (not 10)
- Each: headline + explanation + proof if available
How It Works
- 3-4 numbered steps
- Reduces perceived complexity
- Each step: action + outcome
Final CTA Section
- Recap value proposition
- Repeat primary CTA
- Risk reversal (guarantee, free trial)
Testimonials
- Full quotes with names, roles, companies
- Photos when possible
- Specific results over vague praise
- Formats: quote cards, video, tweet embeds
Case Studies
- Problem → Solution → Results
- Specific metrics and outcomes
- Customer name and context
- Can be snippets with "Read more" links
Use Cases
- Different ways product is used
- Helps visitors self-identify
- "For marketers who need X" format
Personas / "Built For" Sections
- Explicitly call out target audience
- "Perfect for [role]" blocks
- Addresses "Is this for me?" question
FAQ Section
- Address common objections
- Good for SEO
- Reduces support burden
- 5-10 most common questions
Comparison Section
- vs. competitors (name them or don't)
- vs. status quo (spreadsheets, manual processes)
- Tables or side-by-side format
Integrations / Partners
- Logos of tools you connect with
- "Works with your stack" messaging
- Builds credibility
Founder Story / Manifesto
- Why you built this
- What you believe
- Emotional connection
- Differentiates from faceless competitors
Demo / Product Tour
- Interactive demos
- Video walkthroughs
- GIF previews
- Shows product in action
Pricing Preview
- Teaser even on non-pricing pages
- Starting price or "from $X/mo"
- Moves decision-makers forward
Guarantee / Risk Reversal
- Money-back guarantee
- Free trial terms
- "Cancel anytime"
- Reduces friction
Stats Section
- Key metrics that build credibility
- "10,000+ customers"
- "4.9/5 rating"
- "$2M saved for customers"
1. Hero
2. Feature 1
3. Feature 2
4. Feature 3
5. Feature 4
6. CTA
This is a list, not a persuasive narrative.
1. Hero with clear value prop
2. Social proof bar (logos or stats)
3. Problem/pain section
4. How it works (3 steps)
5. Key benefits (2-3, not 10)
6. Testimonial
7. Use cases or personas
8. Comparison to alternatives
9. Case study snippet
10. FAQ
11. Final CTA with guarantee
This tells a story and addresses objections.
1. Hero (headline, subhead, CTA, image)
2. Social proof bar
3. 3 key benefits with icons
4. Testimonial
5. How it works (3 steps)
6. Final CTA with guarantee
Good for ad landing pages where brevity matters.
1. Hero (outcome-focused headline)
2. Logo bar (recognizable companies)
3. Problem section (business pain)
4. Solution overview
5. Use cases by role/department
6. Security/compliance section
7. Integration logos
8. Case study with metrics
9. ROI/value section
10. Contact/demo CTA
Addresses enterprise buyer concerns.
1. Hero with launch announcement
2. Video demo or walkthrough
3. Feature highlights (3-5)
4. Before/after comparison
5. Early testimonials
6. Launch pricing or early access offer
7. CTA with urgency
Good for ProductHunt, launches, or announcements.
Start with phrases like:
- "You know the feeling..."
- "If you're like most [role]..."
- "Every day, [audience] struggles with..."
- "We've all been there..."
Then describe:
- The specific frustration
- The time/money wasted
- The impact on their work/life
For each benefit, include:
- Headline: The outcome they get
- Body: How it works (1-2 sentences)
- Proof: Number, testimonial, or example (optional)
Each step should be:
- Numbered: Creates sense of progress
- Simple verb: "Connect," "Set up," "Get"
- Outcome-oriented: What they get from this step
Example:
1. Connect your tools (takes 2 minutes)
2. Set your preferences
3. Get automated reports every Monday
Best testimonials include:
- Specific results ("increased conversions by 32%")
- Before/after context ("We used to spend hours...")
- Role + company for credibility
- Something quotable and specific
Avoid testimonials that just say:
- "Great product!"
- "Love it!"
- "Easy to use!"
Transitional phrases to guide readers through your content. Good signposting improves readability, user engagement, and helps search engines understand content structure.
Adapted from: University of Manchester Academic Phrasebank (2023), Plain English Campaign, web content best practices
Use to orient readers and set expectations:
Use to connect ideas and reinforce key points:
Note: Use "moreover" and "furthermore" sparingly. They can sound AI-generated when overused.
Use when citing sources, data, or expert opinions:
Note: Avoid "In conclusion" at the start of a paragraph. It's overused and signals AI writing.
Useful for conversational tone and featured snippet optimization:
For numbered lists and step-by-step content:
For claims that need qualification or aren't absolute:
These phrases are overused in AI-generated content:
See the seo-audit skill's references/ai-writing-detection.md for a complete list of AI writing tells.
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 imag
View source ↗You are an expert visual content producer who helps create marketing images using AI generation models, design tools, and optimization best practices. Your goal is to help users produce professional visual assets efficiently — from blog heroes and social graphics to product mockups and profile banners.
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):
Pick the right tool for the job:
| Approach | Best For | Tools | When to Use |
|---|---|---|---|
| AI Generation | Original images from text prompts | Gemini/Nano Banana, Flux, Ideogram | Blog heroes, social graphics, lifestyle scenes |
| AI Editing | Modify existing images | Gemini, Flux Flex | Background removal, style changes, variations |
| Design Tools | Templated, brand-consistent assets | Canva, Figma | Profile banners, social templates, presentations |
| Screenshot + Overlay | Product UI showcases | Browser screenshot + code overlay | Product mockups, feature announcements |
| Stock Photography | Generic business/lifestyle scenes | Unsplash, Pexels | When speed matters more than uniqueness |
Generate original images from text prompts. The fastest way to create unique marketing visuals.
| Model | Best For | Text in Images | API | Cost |
|---|---|---|---|---|
| Gemini Image (Google, "Nano Banana" / Nano Banana Pro) | All-around, editing, multi-image reference, text rendering | Good | Gemini API | Check pricing |
| Flux (Black Forest Labs — Pro 1.1, Kontext, Dev, Schnell) | Photorealism, brand consistency, batch; Kontext for in-image editing | Limited | BFL API, Replicate, fal.ai | Check pricing |
| Ideogram 3.0 | Typography, branded graphics, accurate text rendering | Best | Ideogram API | Check pricing |
| ChatGPT Images 2.0 / GPT Image (OpenAI) | General purpose, ChatGPT integration, native editing | Good | OpenAI API | Check 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 | Per-credit |
| Stable Diffusion 3.5 / SDXL | Self-hosted, customizable, fine-tunable | Varies | Open source | Free (GPU costs) |
Note: DALL-E 3 is fully deprecated. OpenAI's current image models are the GPT Image / ChatGPT Images family (gpt-image-1 and later).
Need text/headlines in the image?
├── Yes → Ideogram 3.0 (best), Gemini (good), GPT Image / ChatGPT Images (decent)
└── No ↓
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 (in-place)?
├── Yes → Gemini (native editing), Flux Kontext, ChatGPT Images
└── No ↓
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 Schnell, Gemini Flash, Stable Diffusion (self-hosted)
A strong image prompt follows: Subject + Setting + Style + Lighting + Composition + Technical
A laptop on a minimal white desk showing a dashboard UI,
soft directional lighting from the left, shallow depth of field,
clean commercial photography style, 16:9 aspect ratio, 4K
Common mistakes:
- Too vague ("a business image") — add specific details
- Forgetting aspect ratio — always specify dimensions
- Requesting complex text — use overlays instead for anything beyond short headlines
- No style direction — "photorealistic," "flat illustration," "3D render"
For detailed prompting guides per model, see references/ai-image-prompting.md.
For templated, brand-consistent work where AI generation is overkill or too unpredictable.
Best for non-designers who need polished output fast.
Best for teams with design systems or pixel-perfect needs.
| Scenario | Design Tool | AI Generation |
|---|---|---|
| Exact brand guidelines must be followed | Yes | Maybe (with strong ref images) |
| Need 20 size variants of one design | Yes (Canva Magic Resize) | No |
| Unique hero image for a blog post | No | Yes |
| Recurring social media template | Yes | No |
| Product mockup with real UI | No (use screenshots) | No (hallucinated UI) |
| Abstract/creative visual | No | Yes |
The image at the top of every post. Sets tone, improves shareability, required for OG/social previews.
Prompt pattern:
[Visual metaphor for topic], clean modern style,
bright natural lighting, shallow depth of field,
professional blog header aesthetic, 1200x630
Platform-specific images for organic posts.
| Platform | Primary Size | Aspect Ratio | Notes |
|---|---|---|---|
| Twitter/X | 1200x675 | 16:9 | Large image card |
| 1200x627 | 1.91:1 | Feed image | |
| Instagram Feed | 1080x1080 | 1:1 | Square; 1080x1350 (4:5) also strong |
| Instagram Stories | 1080x1920 | 9:16 | Full screen vertical |
| 1200x630 | 1.91:1 | Link share image |
Workflow:
1. Create the hero concept at highest resolution needed
2. Use Canva Magic Resize or manual crop for platform variants
3. Add text overlays programmatically (Ideogram or post-processing) if needed
4. Export at platform-specific dimensions
Showcase your product UI in context. AI models hallucinate UI — don't use them for this.
Tools: Browser DevTools (screenshot), Shottr (Mac), CleanShot X, or screencapture CLI.
Banners for profiles, directory listings, and marketplace pages. Often the first visual impression.
| Platform | Size | Notes |
|---|---|---|
| LinkedIn personal cover | 1584x396 | 4:1, safe zone center |
| LinkedIn company cover | 1128x191 | 5.9:1; LinkedIn recommends up to 4200x700 |
| Twitter/X header | 1500x500 | 3:1, partially obscured by avatar |
| Product Hunt gallery | 1270x760 | 5:3, up to 6 images |
| G2 profile | 1280x720 | 16:9, product screenshots preferred |
| GitHub social preview | 1280x640 | 2:1, shows in link cards |
| App Store screenshots | Varies by device | See aso skill for full specs |
| Google Play feature graphic | 1024x500 | ~2:1, required for store listing |
Best practices:
- Keep text minimal — banners are seen at small sizes on mobile
- Center critical content — edges get cropped differently per device
- Show the product — real UI screenshots outperform abstract graphics on directory listings
- Match your brand — use consistent colors, fonts, logo placement
- Update seasonally — stale banners signal an inactive product
Workflow:
1. Pick the platform(s) and note exact dimensions
2. For directories (Product Hunt, G2): use real product screenshots with light annotation
3. For profiles (LinkedIn, Twitter): use brand colors + tagline + optional product shot
4. Generate with Canva/Figma templates or Ideogram (if text-heavy)
5. Test at actual display size — zoom out to check readability
Logos, icons, and illustrations. AI generation has limits here.
| Asset | AI Generation | Design Tool | Notes |
|---|---|---|---|
| Logo | Poor — inconsistent, not vector | Yes (Figma) | Always design or commission logos |
| App icon | Decent starting point | Yes (Figma) | Generate concepts, refine manually |
| Illustrations | Good for style exploration | Depends | AI for concepts, finalize in design tool |
| Favicons | No | Yes | Derive from logo |
| Social icons | No | Yes | Use platform-provided assets |
Every image on your site affects page speed, which affects SEO and conversions.
| Format | Best For | Compression | Browser Support |
|---|---|---|---|
| WebP | Photos, graphics — default choice | Lossy + lossless | ~96% |
| AVIF | Highest compression, newest | Better than WebP | ~94% |
| JPEG | Fallback for older browsers | Lossy only | Universal |
| PNG | Transparency, screenshots | Lossless | Universal |
| SVG | Logos, icons, illustrations | Vector (scales) | Universal |
<picture> element or CDN auto-format)loading="lazy")width and height attributes prevent layout shift (CLS)# Convert to WebP (using cwebp)
cwebp -q 80 input.png -o output.webp
# Batch convert with ImageMagick
mogrify -format webp -quality 80 *.png
# Optimize JPEG (using jpegoptim)
jpegoptim --max=80 --strip-all *.jpg
# Check image sizes on a page
curl -s https://yoursite.com | grep -oP 'src="[^"]+\.(jpg|png|webp)"' | head -20
The image that appears when your URL is shared on social media, Slack, Discord, etc.
<meta property="og:image" content="https://yoursite.com/og/page-name.jpg" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:image" content="https://yoursite.com/og/page-name.jpg" />
Generate OG images programmatically for pages with dynamic content (blog posts, user profiles):
@vercel/og) — generates images at the edge using JSXBest for programmatic SEO: Generate unique OG images per page using templates + dynamic data.
How to write effective prompts for AI image generation models (Gemini/Nano Banana, Flux, Ideogram, DALL-E, Midjourney).
A strong image prompt follows this formula:
[Subject] + [Setting/context] + [Visual style] + [Lighting] + [Composition] + [Technical specs]
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
| 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 |
| 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 |
gpt-image-1 and variants (DALL-E 3 is deprecated)--style raw for less stylized, --ar 16:9 for aspect ratio| 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 |
When you need multiple images with consistent style (e.g., a blog series or social campaign):
| 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 |
When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms, or wants to do social listening and engagement triage. Also use
View source ↗You are an expert social media strategist. Your goal is to help create engaging content that builds audience, drives engagement, and supports business goals.
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):
| Platform | Best For | Frequency | Key Format |
|---|---|---|---|
| B2B, thought leadership | 3-5x/week | Carousels, stories | |
| Twitter/X | Tech, real-time, community | 3-10x/day | Threads, hot takes |
| Visual brands, lifestyle | 1-2 posts + Stories daily | Reels, carousels | |
| TikTok | Brand awareness, younger audiences | 1-4x/day | Short-form video |
| Communities, local businesses | 1-2x/day | Groups, native video |
For detailed platform strategies: See references/platforms.md
For hashtag limits and character counts: See references/platform-limits.md
Build your content around 3-5 pillars that align with your expertise and audience interests.
| Pillar | % of Content | Topics |
|---|---|---|
| Industry insights | 30% | Trends, data, predictions |
| Behind-the-scenes | 25% | Building the company, lessons learned |
| Educational | 25% | How-tos, frameworks, tips |
| Personal | 15% | Stories, values, hot takes |
| Promotional | 5% | Product updates, offers |
For each pillar, ask:
1. What unique perspective do you have?
2. What questions does your audience ask?
3. What content has performed well before?
4. What can you create consistently?
5. What aligns with business goals?
The first line determines whether anyone reads the rest.
For post templates and more hooks: See references/post-templates.md
For carousels (Instagram carousels, LinkedIn document posts): See references/carousel-frameworks.md — five slide-by-slide narrative architectures (Value-Stack, Problem-Proof, Hack List, Rant Callout, Demo Walkthrough) with framework selection guidance, per-slide copy slots, platform notes, and a production checklist. Pick the framework before writing slides.
Turn one piece of content into many. The best social content isn't created from scratch — it's extracted from longer-form pillar content and adapted to each platform.
| Platform | Format |
|---|---|
| Key insight + link in comments | |
| Carousel of main points | |
| Twitter/X | Thread of key takeaways |
| Carousel with visuals | |
| Reel summarizing the post |
Extract "content atoms" — self-contained moments from any long-form content that work on their own:
| Atom Type | What to Look For | Best Platform |
|---|---|---|
| Quotable moment | A bold claim, hot take, or memorable line (15-60 sec) | Twitter/X, LinkedIn, TikTok |
| Story arc | A complete mini-story with setup, conflict, resolution (60-90 sec) | Instagram Reels, TikTok, YouTube Shorts |
| Tactical tip | A specific how-to or framework explained clearly (30-60 sec) | LinkedIn, YouTube Shorts |
| Controversial take | A contrarian opinion that sparks debate | Twitter/X, LinkedIn |
| Data/stat callout | A surprising number or research finding | LinkedIn carousel, Twitter/X |
| Behind-the-scenes | Authentic, unpolished moments | Instagram Stories, TikTok |
Podcast repurposing workflow:
1. Get transcript — use Whisper, Descript, or your podcast host's transcription
2. Mark timestamps — flag the 5-10 best moments while listening or scanning transcript
3. Extract clips — pull video/audio clips for each moment (Descript, Opus Clip, or manual)
4. Write standalone captions — each clip needs context; don't assume the viewer heard the rest
5. Add subtitles — most social video is watched without sound
6. Schedule across 1-2 weeks — spread a single episode across multiple posts
Per episode, aim for:
- 3-5 short video clips or audiograms (15-60 sec) for Reels/TikTok/Shorts
- 1-2 LinkedIn text posts from key insights
- 1 Twitter/X thread of takeaways
- 1 carousel summarizing the main framework or list
- 1 newsletter section or blog post from the best segment
| Extract | Format |
|---|---|
| Key slides with commentary | LinkedIn carousel |
| Q&A highlights | Twitter/X thread |
| Speaker quotes | Quote graphics for Instagram/LinkedIn |
| Audience reactions/poll results | Engagement posts |
| Full recording → short clips | Reels, TikTok, Shorts |
| Extract | Format |
|---|---|
| Main insight | LinkedIn post |
| Curated links with commentary | Twitter/X thread |
| Data or stat | Quote graphic |
| Hot take or opinion | Twitter/X post, LinkedIn |
| Day | Twitter/X | ||
|---|---|---|---|
| Mon | Industry insight | Thread | Carousel |
| Tue | Behind-scenes | Engagement | Story |
| Wed | Educational | Tips tweet | Reel |
| Thu | Story post | Thread | Educational |
| Fri | Hot take | Engagement | Story |
For surfacing which posts to comment on (top-10 daily lists, brand/competitor monitoring, intent-signal triage), see references/listening.md. Includes a scoring rubric and curl recipes for Reddit, Hacker News, and Bluesky.
Awareness: Impressions, Reach, Follower growth rate
Engagement: Engagement rate, Comments (higher value than likes), Shares/reposts, Saves
Conversion: Link clicks, Profile visits, DMs received, Leads attributed
If engagement is low:
- Test new hooks
- Post at different times
- Try different formats
- Increase engagement with others
If reach is declining:
- Avoid external links in post body
- Increase posting frequency
- Engage more in comments
- Test video/visual content
Schedule: Core content posts, Threads, Carousels, Evergreen content
Post live: Real-time commentary, Responses to news/trends, Engagement with others
Instead of guessing, analyze what's working for top creators in your niche:
For the complete framework: See references/reverse-engineering.md
Short-form video is the highest-reach format on every major platform. These frameworks apply whether you're creating for TikTok, Instagram Reels, or YouTube Shorts.
| Platform | Optimal Length | Aspect Ratio | Key Difference |
|---|---|---|---|
| TikTok | 15-60 sec | 9:16 | Trending sounds, raw/authentic feel |
| Reels | 15-30 sec | 9:16 | Polished content, rewards saves/shares |
| Shorts | 30-60 sec | 9:16 | YouTube SEO applies, searchable titles |
You have 3 seconds to stop the scroll. Every video needs three simultaneous hooks:
[VISUAL HOOK] + [VERBAL HOOK] + [TEXT OVERLAY]
All three should hit in the first second.
Problem-Solution (15-30 sec):
[0-3s] Hook: State the problem
[3-10s] Agitate: Why it matters
[10-25s] Solution: Your method/product/tip
[25-30s] CTA: What to do next
List Format (30-60 sec):
[0-3s] Hook: "X things that [outcome]"
[3-50s] Items: One every 5-8 seconds
[50-60s] CTA
Tutorial (30-60 sec):
[0-3s] Hook: Show the end result first
[3-8s] Overview: "Here's how..."
[8-50s] Steps: Quick, clear instructions
[50-60s] Result + CTA
Captions increase watch time by 25-40%. Most social video is watched without sound.
Tools: CapCut (free), Descript, Captions.ai, Premiere Pro
| Business Type | Video Ideas |
|---|---|
| SaaS | Feature demos (show outcome first), before/after, "Watch me do X in Y seconds" |
| E-commerce | Unboxing, comparisons, how it's made, customer reviews |
| Services | Process reveals, client transformations, myth-busting |
| Personal brand | Lessons learned, controversial takes, day-in-the-life |
For video hook formulas and scripting templates: See references/short-form-video.md
Five slide-by-slide narrative architectures for carousels — Instagram carousels and LinkedIn document posts. Each framework is a different reason to keep swiping; picking the right one for the content matters more than polishing individual slides.
A carousel is not a blog post chopped into squares. It's a swipe-through with two jobs per slide: deliver one idea, and make the next swipe irresistible. These frameworks encode structures that show up repeatedly in high-performing carousels; treat them as starting structures to adapt, not rigid formulas — and expect to validate against your own analytics.
| Your content is... | Use | Why |
|---|---|---|
| A list of resources, tools, or tips | A: Value-Stack | Completeness is the promise; the count is the hook |
| A personal result with a system behind it | B: Problem-Proof | Proof opens and closes the loop; the system is the meat |
| Several named techniques on one theme | C: Hack List | Each hack re-earns the swipe independently |
| A strong opinion about a common practice | D: Rant Callout | Conviction is the content; structure keeps it fair |
| A product or workflow you can show | E: Demo Walkthrough | Seeing the steps is more persuasive than describing them |
Two cross-framework rules before the specifics:
The "everything you need" carousel. Works because the cover makes a completeness claim — an exact count and an exact deliverable — and every swipe pays it down.
| Slide | Job | Pattern |
|---|---|---|
| 1 — Cover | State the exact count + exact deliverable. Specificity proves scale upfront. | "[N] [resource type] for [role/outcome]" |
| 2 to N−1 — Value delivery | One item or category per slide, 3–6 concrete sub-items each. Same visual template, zero filler slides. | "[Category/item] — [sub-items]" |
| N — Close | Convert the swipe-through into an action. | "[Action] for [the payoff]" — comment a keyword, follow, link in bio |
Why the exact count matters: "27 free tools" outperforms "the best free tools" because a number is a checkable promise — the reader can verify you delivered. Rounding up with padding breaks the trust the count created.
SaaS example: "12 ChatGPT prompts for SaaS onboarding emails" → one prompt per slide with the use case → "Comment PROMPTS and I'll send the full doc."
Failure mode: filler slides to hit a bigger number. Cut to the real count; a tight 8 beats a padded 14.
The "I did X, here's the system" carousel. The hook is a result stated as fact, not advice — and the final slide shows the receipt, closing the loop slide 1 opened.
| Slide | Job | Pattern |
|---|---|---|
| 1 — Hook | A specific personal claim with a number. A result, not a tip. | "[I/we did X]. [Specific result, with number]." |
| 2 — Reframe the problem | Name what's actually going wrong so the reader recognizes themselves. | "The real problem — [named issue]" |
| 3–4 — The mechanism | Show the real system: named tools, named steps. Concrete beats vague. | "The system — [named tools/steps]" |
| 5 to N−1 — The detail | The literal prompt text, template, or step-by-step. This is the save-worthy part. | "[The literal prompt or process detail]" |
| N — Proof | The actual output artifact. A screenshot, not a description. | "[Screenshot of output] — the receipt" |
The open loop is the engine: slide 1 makes a claim, the last slide proves it, and everything between explains how. Readers swipe to see whether the receipt is real.
SaaS example: "We cut churn 22% with one onboarding email." → the real problem (activation, not price) → the sequence structure → the literal email copy → the retention chart.
Failure mode: vague mechanism slides ("optimize your workflow") — if the middle slides don't name tools and steps, the proof slide reads as luck, not system.
The "numbered techniques" carousel. A contrarian cover creates status anxiety — most people are doing this wrong — and each numbered hack independently re-earns the swipe.
| Slide | Job | Pattern |
|---|---|---|
| 1 — Contrarian hook | A stat or claim implying most people fail at this. | "[Stat implying most people fail at X]" |
| 2 — The problem | Why the common approach fails, ideally with an analogy. | "The problem — [why it fails]" |
| 3 to N−1 — Numbered hacks | One named technique per slide. Bad-vs-good contrast makes each hack land instantly. | "Hack #[n] — [named technique]" |
| N — Synthesis + close | A one-line thesis tying the hacks together, then a save/share/follow CTA. | "[Thesis tying hacks together]" + [CTA] |
Name every technique. "The 3-second rule" is shareable and memorable; "keep it short" is neither. Named techniques travel — people repeat them and credit the source.
SaaS example: "90% of trial emails never get opened." → why (they read like receipts, not messages) → Hack #1: The founder-from line, Hack #2: The one-question subject, ... → "Trial emails are conversations, not confirmations. Save this for your next sequence."
Failure mode: hacks that are restatements of each other. Each slide must survive alone — if two hacks collapse into one idea, merge them and go shorter.
The "someone had to say it" carousel. Personality-led and polarizing by design — the structure exists to keep the heat fair so it reads as conviction, not bitterness.
| Slide | Job | Pattern |
|---|---|---|
| 1 — Provocative claim | An unpopular opinion or direct accusation about a common practice. | "Unpopular opinion — [common practice]" |
| 2 to N−2 — Escalate the argument | Sensory, specific detail. Show the offense; don't gesture at it abstractly. Each slide raises the stakes. | "[Escalating, specific complaint]" |
| N−1 — Fairness pivot | "Don't get me wrong…" — clarify what you're not attacking. Anti-laziness, not anti-tool; anti-practice, not anti-person. | "The problem isn't [X], it's [Y]" |
| N — Close | Firm, personality-forward sign-off. Signed rants read as owned opinions; anonymous ones read as potshots. | "[Firm sign-off] — signed [name/persona]" |
The fairness pivot is what makes it work. Without it you're yelling; with it you're drawing a precise line, and precise lines get quoted. It also pre-empts the top hostile comment.
SaaS example: "Your AI-generated LinkedIn posts are costing you customers." → the specifics (same em-dash cadence, same 'game-changer' vocabulary, zero lived detail) → "Don't get me wrong — I use AI daily. The problem isn't the tool, it's publishing the first draft." → "Write like you talk. — [Name]"
Failure modes: skipping the pivot (reads unhinged, invites pile-ons), or ranting about something your own product/content visibly does (the comments will find it).
The "watch it work" carousel for product or workflow content. Show the finished result first, then the steps — the outcome earns attention for the process.
| Slide | Job | Pattern |
|---|---|---|
| 1 — Product + outcome | Brand/product plus the finished result. Lead with what they get. | "[Product] + [outcome], finished result" |
| 2 — Problem it solves | The specific frustration this replaces. | "[The specific pain this replaces]" |
| 3 — Process overview | The numbered step list, shown before the detail. Seeing the whole path lowers mid-swipe drop-off — readers commit when they know how long the road is. | "[N] steps to [outcome] in [timeframe]" |
| 4 to N−1 — Step-by-step | One real UI screenshot per step with a short caption. Real screenshots; mockups read as vaporware. | "Step [n] — [screenshot] — [caption]" |
| N — Result + positioning | The full-size output plus one brand-philosophy line. | "[Final output] + [positioning line]" |
Overview-before-detail is the key move (same reason recipe sites list ingredients before instructions): a reader who's seen "4 steps, 10 minutes" on slide 3 will finish; a reader dropped straight into step 1 with no map bails at step 2.
SaaS example: "From CSV to live dashboard in 4 steps" → the pain (weekly manual reporting) → the 4-step overview → one screenshot per step → the finished dashboard + "Built for marketers, not analysts."
Failure mode: screenshots with too much UI. Crop to the action, zoom the relevant control, annotate with one arrow — each screenshot should make sense at thumbnail size.
Instagram: 1080×1350 (4:5) slides; up to 20 slides but the frameworks' ranges above reflect where completion rates hold. The caption carries the searchable text — restate the hook and add context, don't just repeat slide 1. First slide doubles as the grid thumbnail.
LinkedIn (document posts): Upload as PDF. Square or 4:5. LinkedIn shows a "N pages" badge — Value-Stack's exact-count cover plays especially well here. B2B tolerates denser text per slide than Instagram, but the one-idea-per-slide rule still holds. The post text above the document is a second hook — write it as its own post, not a throwaway "see attached."
TikTok photo mode: Same frameworks work; pacing skews faster — trim each framework toward its minimum slide count.
Judge carousels on saves and completion, not likes — saves signal reference value (the algorithmic win for carousels), and where per-slide analytics exist (Instagram professional insights, LinkedIn document analytics, or third-party tools), drop-off position tells you which slide broke the swipe chain. When a carousel underperforms, the fix is usually slide 1 (didn't stop the scroll) or the framework choice (list content forced into a rant structure), not the middle slides. Track per-framework performance and double down on the two that fit your audience — see reverse-engineering.md for the analysis workflow.
Copy this file to .agents/listening-sources.md in your project (or .claude/listening-sources.md) and fill in the brackets. Claude reads it when running the listening workflow.
Delete sections you don't use. Keep this short and current — stale sources are worse than no sources.
Brand / product: [Your product name]
Category: [e.g., "AI writing assistant", "Postgres GUI"]
Goal: [e.g., "find people switching from Notion", "engage with B2B SaaS founders 50-200 employees"]
Used by the scoring rubric to judge ICP fit.
Engage with every post from these accounts when relevant. Keep this list to 20-50 max.
linkedin.com/in/handlelinkedin.com/in/handlehttps://example.com/feed/https://example.substack.com/feedUCxxxxxxxxSearch across all platforms. Claude runs these through Reddit, HN, Bluesky on the daily loop.
"alternative to [competitor]""looking for a [category] tool""recommend a [category]""switching from [competitor]""frustrated with [competitor]""[category] is so [bad/hard/expensive]""why is [category] [problem]""hate [pain point]""[your brand]""[your brand misspelling]""[your domain]""[competitor 1]""[competitor 2]"Pulled via Reddit JSON API on the daily loop.
URLs Claude opens via dev-browser to scan.
https://linkedin.com/sales/search/people?...https://linkedin.com/feed/hashtag/yourtopic/https://x.com/search?q=...&f=liveSave yourself the regret.
How to surface the right posts to engage with each day — instead of randomly scrolling. The goal is a short, scorable list ("here are your top 10 posts to comment on") rather than an open feed.
Use listening when the goal is commenting and relationships, not posting. Typical asks:
- "Give me the top 10 posts I should comment on today"
- "Who's complaining about [competitor] right now?"
- "Find people asking for a tool like mine"
- "Surface posts from my 20 target accounts in the last 24h"
- "What's the conversation around [topic] this week?"
If the user wants to create content, use the rest of the social skill. Listening feeds creation (it surfaces angles, language, objections), but the output is different.
A repeatable 20-minute loop the user (or you, on their behalf) can run each morning.
Output format Claude should produce:
TOP 10 POSTS — 2026-06-05
1. [Score 9/10] @author — LinkedIn — 2h ago
"We just rolled out X and the team is loving it…"
Why: ICP fit (B2B SaaS, 50–200 employees), buying-intent signal
Suggested comment: [draft]
Link: https://…
Score each post 1–10 across five dimensions, then sum and rank.
| Dimension | What it measures | Weight |
|---|---|---|
| ICP fit | Is the author your target customer / influencer? | 2x |
| Intent signal | Are they expressing a problem, asking, or shopping? | 2x |
| Reach potential | Is the post getting traction (likes/comments rising)? | 1x |
| Comment opportunity | Can you say something genuinely useful, not generic? | 2x |
| Recency | Posted in last 1–4h (early comments win, especially on LinkedIn) | 1x |
Intent signal examples (high-value):
- "Looking for a tool that does X"
- "Why is [category] so painful?"
- "We just switched from [competitor] because…"
- "Anyone use [competitor] — is it worth it?"
- A complaint about a known competitor
Drop if any of these are true:
- Author isn't ICP and isn't an influencer
- Post is >24h old and already has 50+ comments (your comment buries)
- Generic motivational/AI-slop post
- Self-promotion thread where comments don't get reach
- You can't add anything beyond "Great post!"
Match the comment to the post. Don't waste a tier-1 draft on a tier-3 opportunity.
Tier 1 — Relationship builder (target accounts, ICP, high intent)
- Add a specific insight or counter-example
- Reference your own experience with specifics (numbers, names, outcomes)
- Ask a thoughtful follow-up that invites a reply
- Length: 2–4 sentences, no link
Tier 2 — Visibility play (high-reach post, adjacent topic)
- Add one sharp insight in one sentence
- Pattern: "Agreed — and the part most miss is [X]"
- Length: 1–2 sentences
Tier 3 — Light touch (relationship maintenance)
- Specific reaction, not "Love this"
- Quote a specific line and react to it
- Length: 1 sentence
Never: "Great post!", emoji-only, "+1", LinkedIn-isms like "This is gold 🔥"
These are public JSON endpoints — no auth needed. Run them from bash, pipe to jq, and Claude can parse the output to score and draft comments.
Requires: jq (most recipes) and xmllint (RSS only). Install once:
# macOS
brew install jq
# xmllint ships with macOS; on Linux: apt install libxml2-utils
New posts in a subreddit:
curl -s -A "listening/1.0" \
"https://www.reddit.com/r/SaaS/new.json?limit=25" \
| jq '.data.children[].data | {title, author, url: ("https://reddit.com"+.permalink), score, num_comments, created_utc, selftext: (.selftext | .[0:300])}'
Search across Reddit by keyword (last day, sorted new):
curl -s -A "listening/1.0" \
"https://www.reddit.com/search.json?q=KEYWORD&sort=new&t=day&limit=25" \
| jq '.data.children[].data | {subreddit, title, url: ("https://reddit.com"+.permalink), author, score, created_utc}'
Swap KEYWORD for things like "alternative to notion", "recommend a crm", your competitor names, or your own brand for mentions. Use quotes around multi-word phrases.
Recent stories mentioning a keyword (last 24h):
SINCE=$(($(date +%s) - 86400))
curl -s "https://hn.algolia.com/api/v1/search_by_date?query=KEYWORD&tags=story&numericFilters=created_at_i>${SINCE}" \
| jq '.hits[] | {title, url, author, points, num_comments, created_at, story_id: .objectID, hn_url: ("https://news.ycombinator.com/item?id="+.objectID)}'
Recent comments mentioning a keyword:
curl -s "https://hn.algolia.com/api/v1/search_by_date?query=KEYWORD&tags=comment&numericFilters=created_at_i>${SINCE}" \
| jq '.hits[] | {author, comment_text, story_title, hn_url: ("https://news.ycombinator.com/item?id="+.objectID)}'
Search posts by keyword:
curl -s "https://public.api.bsky.app/xrpc/app.bsky.feed.searchPosts?q=KEYWORD&limit=25&sort=latest" \
| jq '.posts[] | {author: .author.handle, text: .record.text, likes: .likeCount, replies: .replyCount, url: ("https://bsky.app/profile/"+.author.handle+"/post/"+(.uri | split("/") | last))}'
For target accounts that publish to RSS (most blogs, all YouTube channels):
# YouTube channel feed (replace CHANNEL_ID)
curl -s "https://www.youtube.com/feeds/videos.xml?channel_id=CHANNEL_ID"
# Generic blog feed
curl -s "https://example.com/feed/" | xmllint --xpath "//item[position()<6]" - 2>/dev/null
LinkedIn and X don't expose useful public APIs, but you can drive a real browser session. dev-browser (MCP, already in the global setup) and Playwright both maintain persistent state — log in once, the session stays alive, Claude can navigate the authenticated feed.
dev-browser workflow (preferred — already wired up):
1. User logs into LinkedIn / X once in the dev-browser session
2. Claude navigates to a target URL (feed, profile, saved search, hashtag)
3. Claude reads the accessibility tree / page text, extracts posts
4. Claude scores using the rubric and drafts comments
5. User reviews and posts manually (don't auto-post — high-stakes, bot detection risk)
Useful URLs to feed dev-browser:
| URL pattern | What it shows |
|---|---|
linkedin.com/in/HANDLE/recent-activity/all/ |
A target account's recent posts |
linkedin.com/feed/hashtag/TOPIC/ |
Hashtag feed |
linkedin.com/feed/ |
Your main feed (algorithmic — less useful for triage) |
x.com/HANDLE |
A target account's profile |
x.com/search?q=QUERY&f=live |
Real-time search (use f=live for chronological) |
x.com/i/lists/LIST_ID |
A curated list — best for target accounts |
Tips:
- On X, build a private list of target accounts and use the list URL. Far cleaner than the algorithmic feed.
- LinkedIn's /recent-activity/all/ URL is the cleanest way to see one person's posts without the algorithm.
- For both platforms, scroll programmatically (dev-browser supports it) to load more posts before extracting.
Paid alternatives if you don't want to drive a browser:
| Platform | Tools |
|---|---|
| Sales Navigator (saved searches), Taplio (engagement) | |
| X | TweetDeck/X Pro (saved columns), Typefully, Taplio, Tweet Hunter |
Still closed (no good path):
- Instagram & TikTok — closed APIs, browser automation is detectable and risky. Use native saved searches / hashtag follows.
"competitor name" -site:competitor.com sorted by newThe user should maintain a list of sources somewhere persistent at .agents/listening-sources.md (or .claude/listening-sources.md). Claude reads it when running the daily loop.
A ready-to-fill template lives at listening-sources-template.md. Copy it into the project and edit. The source path depends on how the skill was installed:
# Plugin / marketplace install (most common):
cp .agents/skills/social/references/listening-sources-template.md .agents/listening-sources.md
# .claude/ install:
cp .claude/skills/social/references/listening-sources-template.md .agents/listening-sources.md
# Working inside the marketingskills repo:
cp skills/social/references/listening-sources-template.md .agents/listening-sources.md
The template covers: brand/category, ICP (for scoring), target accounts per platform, intent keywords, subreddits, saved-search URLs, and a do-not-engage list.
Quick reference for hashtag limits, character counts, and visible text thresholds on each major social platform.
| Element | Limit |
|---|---|
| Max hashtags | 5 (official limit) |
| Recommended hashtags | 3 – 5 |
| Max caption chars | 2,200 |
| Visible before "more" | ~125 chars |
| Element | Limit |
|---|---|
| Max hashtags | No official limit |
| Recommended hashtags | 1 – 2 |
| Max post chars | 63,206 |
| Ideal for engagement | 40 – 80 chars |
| Element | Limit |
|---|---|
| Max hashtags | 5 (since August 2025) |
| Recommended hashtags | 3 – 5 |
| Max caption chars | 4,000 |
| Visible before "more" | ~150 chars |
| Element | Limit |
|---|---|
| Max hashtags | No official limit |
| Recommended hashtags | 3 – 5 |
| Max post chars | 3,000 |
| Visible before "more" | ~210 chars |
| Element | Limit |
|---|---|
| Max hashtags | No official limit |
| Recommended hashtags | 1 – 2 |
| Max tweet chars | 280 (standard) / 25,000 (Premium+) |
| Visible before "more" | Full tweet (280 standard) |
| Element | Limit |
|---|---|
| Max hashtags | 15 (exceeding this causes YouTube to ignore ALL hashtags) |
| Recommended hashtags | 3 – 5 |
| Max title chars | 100 (visible before truncation: ~70) |
| Max description chars | 5,000 |
| Visible before "Show more" | ~100 chars |
The first 3 hashtags in the description automatically appear above the title as clickable links. For Shorts, use 1 – 5 hashtags.
| Element | Limit |
|---|---|
| Max hashtags | 20 per pin |
| Recommended hashtags | 2 – 5 |
| Max pin title chars | 100 |
| Max description chars | 500 |
| Visible before "More" | ~50 chars (desktop) |
Pinterest has deprioritized hashtags. Focus on keywords as natural sentences within the description for better SEO instead of relying on hashtags.
| Element | Limit |
|---|---|
| Max hashtags | 1 per post (topic tag) |
| Recommended hashtags | 1 |
| Max post chars | 500 |
| Max with text attachment | 10,500 (500 + 10,000 expandable) |
| Visible without expanding | First ~1 – 2 lines |
Threads limits topic tags to one per post. The platform is not hashtag-driven — the algorithm prioritizes content from followed accounts mixed with recommendations.
Detailed strategies for each major social platform.
Best for: B2B, thought leadership, professional networking, recruiting
Audience: Professionals, decision-makers, job seekers
Posting frequency: 3-5x per week
Best times: Tuesday-Thursday, 7-8am, 12pm, 5-6pm
What works:
- Personal stories with business lessons
- Contrarian takes on industry topics
- Behind-the-scenes of building a company
- Data and original insights
- Carousel posts (document format)
- Polls that spark discussion
What doesn't:
- Overly promotional content
- Generic motivational quotes
- Links in the main post (kills reach)
- Corporate speak without personality
Format tips:
- First line is everything (hook before "see more")
- Use line breaks for readability
- 1,200-1,500 characters performs well
- Put links in comments, not post body
- Tag people sparingly and genuinely
Algorithm tips:
- First hour engagement matters most
- Comments > reactions > clicks
- Dwell time (people reading) signals quality
- No external links in post body
- Document posts (carousels) get strong reach
- Polls drive engagement but don't build authority
Best for: Tech, media, real-time commentary, community building
Audience: Tech-savvy, news-oriented, niche communities
Posting frequency: 3-10x per day (including replies)
Best times: Varies by audience; test and measure
What works:
- Hot takes and opinions
- Threads that teach something
- Behind-the-scenes moments
- Engaging with others' content
- Memes and humor (if on-brand)
- Real-time commentary on events
What doesn't:
- Pure self-promotion
- Threads without a strong hook
- Ignoring replies and mentions
- Scheduling everything (no real-time presence)
Format tips:
- Tweets under 100 characters get more engagement
- Threads: Hook in tweet 1, promise value, deliver
- Quote tweets with added insight beat plain retweets
- Use visuals to stop the scroll
Algorithm tips:
- Replies and quote tweets build authority
- Threads keep people on platform (rewarded)
- Images and video get more reach
- Engagement in first 30 min matters
- Twitter Blue/Premium may boost reach
Best for: Visual brands, lifestyle, e-commerce, younger demographics
Audience: 18-44, visual-first consumers
Posting frequency: 1-2 feed posts per day, 3-10 Stories per day
Best times: 11am-1pm, 7-9pm
What works:
- High-quality visuals
- Behind-the-scenes Stories
- Reels (short-form video)
- Carousels with value
- User-generated content
- Interactive Stories (polls, questions)
What doesn't:
- Low-quality images
- Too much text in images
- Ignoring Stories and Reels
- Only promotional content
Format tips:
- Reels get 2x reach of static posts
- First frame of Reels must hook
- Carousels: 10 slides with educational content
- Use all Story features (polls, links, etc.)
Algorithm tips:
- Reels heavily prioritized over static posts
- Saves and shares > likes
- Stories keep you top of feed
- Consistency matters more than perfection
- Use all features (polls, questions, etc.)
Best for: Brand awareness, younger audiences, viral potential
Audience: 16-34, entertainment-focused
Posting frequency: 1-4x per day
Best times: 7-9am, 12-3pm, 7-11pm
What works:
- Native, unpolished content
- Trending sounds and formats
- Educational content in entertaining wrapper
- POV and day-in-the-life content
- Responding to comments with videos
- Duets and stitches
What doesn't:
- Overly produced content
- Ignoring trends
- Hard selling
- Repurposed horizontal video
Format tips:
- Hook in first 1-2 seconds
- Keep it under 30 seconds to start
- Vertical only (9:16)
- Use trending sounds
- Post consistently to train algorithm
Best for: Communities, local businesses, older demographics, groups
Audience: 25-55+, community-oriented
Posting frequency: 1-2x per day
Best times: 1-4pm weekdays
What works:
- Facebook Groups (community)
- Native video
- Live video
- Local content and events
- Discussion-prompting questions
What doesn't:
- Links to external sites (reach killer)
- Pure promotional content
- Ignoring comments
- Cross-posting from other platforms without adaptation
Ready-to-use templates for different platforms and content types.
[Hook: Unexpected outcome or lesson]
[Set the scene: When/where this happened]
[The challenge you faced]
[What you tried / what happened]
[The turning point]
[The result]
[The lesson for readers]
[Question to prompt engagement]
[Unpopular opinion stated boldly]
Here's why:
[Reason 1]
[Reason 2]
[Reason 3]
[What you recommend instead]
[Invite discussion: "Am I wrong?"]
[X things I learned about [topic] after [credibility builder]:
1. [Point] — [Brief explanation]
2. [Point] — [Brief explanation]
3. [Point] — [Brief explanation]
[Wrap-up insight]
Which resonates most with you?
How to [achieve outcome] in [timeframe]:
Step 1: [Action]
↳ [Why this matters]
Step 2: [Action]
↳ [Key detail]
Step 3: [Action]
↳ [Common mistake to avoid]
[Result you can expect]
[CTA or question]
Tweet 1: [Hook + promise of value]
"Here's exactly how to [outcome] (step-by-step):"
Tweet 2-7: [One step per tweet with details]
Final tweet: [Summary + CTA]
"If this was helpful, follow me for more on [topic]"
Tweet 1: [Intriguing hook]
"[Time] ago, [unexpected thing happened]. Here's the full story:"
Tweet 2-6: [Story beats, building tension]
Tweet 7: [Resolution and lesson]
Final tweet: [Takeaway + engagement ask]
Tweet 1: [Company/person] just [did thing].
Here's why it's genius (and what you can learn):
Tweet 2-6: [Analysis points]
Tweet 7: [Your key takeaway]
"[Related insight + follow CTA]"
[Slide 1: Bold statement or question]
[Slides 2-9: One point per slide, visual + text]
[Slide 10: Summary + CTA]
Caption: [Expand on the topic, add context, include CTA]
This is the generic shape. For five full slide-by-slide narrative architectures (Value-Stack, Problem-Proof, Hack List, Rant Callout, Demo Walkthrough) with selection guidance and per-slide copy slots, see carousel-frameworks.md.
Hook (0-2 sec): [Pattern interrupt or bold claim]
Setup (2-5 sec): [Context for the tip]
Value (5-25 sec): [The actual advice/content]
CTA (25-30 sec): [Follow, comment, share, link]
The first line determines whether anyone reads the rest.
Instead of guessing what works, systematically analyze top-performing content in your niche and extract proven patterns.
Identify 10-20 creators in your space who consistently get high engagement:
Selection criteria:
- Posting consistently (3+ times/week)
- High engagement rate relative to follower count
- Audience overlap with your target market
- Mix of established and rising creators
Where to find them:
- LinkedIn: Search by industry keywords, check "People also viewed"
- Twitter/X: Check who your target audience follows and engages with
- Use tools like SparkToro, Followerwonk, or manual research
- Look at who gets featured in industry newsletters
Gather 500-1000+ posts from your identified creators for analysis:
Tools:
- Apify — LinkedIn scraper, Twitter scraper actors
- Phantom Buster — Multi-platform automation
- Export tools — Platform-specific export features
- Manual collection — For smaller datasets, copy/paste into spreadsheet
Data to collect:
- Post text/content
- Engagement metrics (likes, comments, shares, saves)
- Post format (text-only, carousel, video, image)
- Posting time/day
- Hook/first line
- CTA used
- Topic/theme
Sort and analyze the data to find patterns:
Quantitative analysis:
- Rank posts by engagement rate
- Identify top 10% performers
- Look for format patterns (do carousels outperform?)
- Check timing patterns (best days/times)
- Compare topic performance
Qualitative analysis:
- What hooks do top posts use?
- How long are high-performing posts?
- What emotional triggers appear?
- What formats repeat?
- What topics consistently perform?
Questions to answer:
- What's the average length of top posts?
- Which hook types appear most in top 10%?
- What CTAs drive most comments?
- What topics get saved/shared most?
Document repeatable patterns you can use:
Hook patterns to codify:
Pattern: "I [unexpected action] and [surprising result]"
Example: "I stopped posting daily and my engagement doubled"
Why it works: Curiosity gap + contrarian
Pattern: "[Specific number] [things] that [outcome]:"
Example: "7 pricing mistakes that cost me $50K:"
Why it works: Specificity + loss aversion
Pattern: "[Controversial take]"
Example: "Cold outreach is dead."
Why it works: Pattern interrupt + invites debate
Format patterns:
- Carousel: Hook slide → Problem → Solution steps → CTA
- Thread: Hook → Promise → Deliver → Recap → CTA
- Story post: Hook → Setup → Conflict → Resolution → Lesson
CTA patterns:
- Question: "What would you add?"
- Agreement: "Agree or disagree?"
- Share: "Tag someone who needs this"
- Save: "Save this for later"
Take proven patterns and make them yours with these voice principles:
"Smart friend who figured something out"
- Write like you're texting advice to a friend
- Share discoveries, not lectures
- Use "I found that..." not "You should..."
- Be helpful, not preachy
Specific > Vague
❌ "I made good revenue"
✅ "I made $47,329"
❌ "It took a while"
✅ "It took 47 days"
❌ "A lot of people"
✅ "2,847 people"
Short. Breathe. Land.
- One idea per sentence
- Use line breaks liberally
- Let important points stand alone
- Create rhythm: short, short, longer explanation
❌ "I spent three years building my business the wrong way before I finally realized that the key to success was focusing on fewer things and doing them exceptionally well."
✅ "I built wrong for 3 years.
Then I figured it out.
Focus on less.
Do it exceptionally well.
Everything changed."
Write from emotion
- Start with how you felt, not what you did
- Use emotional words: frustrated, excited, terrified, obsessed
- Show vulnerability when authentic
- Connect the feeling to the lesson
❌ "Here's what I learned about pricing"
✅ "I was terrified to raise my prices.
My hands were shaking when I sent the email.
Here's what happened..."
Bridge from engagement to business results:
Soft conversions:
- Newsletter signups in bio/comments
- Free resource offers in follow-up comments
- DM triggers ("Comment X and I'll send you...")
- Profile visits → optimized profile with clear CTA
Direct conversions:
- Link in comments (not post body on LinkedIn)
- Contextual product mentions within valuable content
- Case study posts that naturally showcase your work
- "If you want help with this, DM me" (sparingly)
1. Find what's already working (don't guess)
2. Extract the patterns (hooks, formats, CTAs)
3. Layer your authentic voice on top
4. Test and iterate based on your own data
Detailed reference for creating short-form video content on TikTok, Instagram Reels, and YouTube Shorts.
The "Secret" Formula:
- "The secret to [outcome] that nobody talks about"
- "I found the hidden feature in [product/platform] that changes everything"
- "I can't believe this actually works..."
The Unexpected Discovery:
- "I tried [thing] for 30 days and I was NOT expecting this"
- "This completely changed how I think about [topic]"
- "Nobody talks about this, but..."
The Question:
- "Why does nobody talk about this?"
- "Am I the only one who didn't know this?"
- "The reason [common thing] doesn't work is..."
The Promise:
- "How to [achieve outcome] in [specific timeframe]"
- "[Number] [things] that will [benefit]"
- "Everything you need to know about [topic] in 60 seconds"
The Hack/Shortcut:
- "[Outcome] hack that actually works"
- "The [adjective] way to [outcome]"
- "If you're struggling with [problem], watch this"
The Warning:
- "Stop doing [common practice] — here's why"
- "[Number] mistakes that are killing your [results]"
- "Why [thing you think is good] is actually hurting you"
The Transformation:
- "3 months ago, I [bad state]. Today, I [good state]."
- "Here's how I went from [before] to [after]"
- "I used to think [old belief]. Then [event] changed everything."
The Failure:
- "I made a huge mistake with [topic]"
- "Here's why I stopped [common practice]"
- "I lost [something significant] because of this mistake"
The Journey:
- "So this just happened..."
- "This changed everything for me"
- "Let me tell you about the time I [interesting situation]"
## Video: [Working Title]
**Platform:** TikTok / Reels / Shorts
**Length:** XX seconds
**Format:** [Talking head / Slideshow / Demo / Screen recording]
### Hook (0-3 sec)
- Visual: [What viewer sees]
- Audio: [What they hear]
- Text overlay: [On-screen text]
### Body (3-X sec)
- [Timestamp] - [What happens/what you say]
- [Timestamp] - [Next beat]
- [Continue...]
### CTA (final 3-5 sec)
- Verbal: [What you say]
- Text: [On-screen text]
- Action: [Follow, comment, link in bio, etc.]
### Production Notes
- Music/sound: [Trending sound or music choice]
- B-roll needed: [List any clips needed]
- Graphics: [Any text animations or overlays]
[0-3s] Hook: Tease the outcome
[3-15s] Setup: Context and stakes
[15-45s] Journey: What happened
[45-55s] Resolution: The result
[55-60s] Lesson/CTA
Best for: Personal stories, case studies, testimonials
[0-3s] Setup: Text overlay sets the scene
[3-25s] Performance: Act out the relatable scenario
[25-30s] Punchline or twist
Best for: Relatable content, humor, niche communities
| Platform | Best Times (local) |
|---|---|
| TikTok | 7-9 AM, 12-3 PM, 7-11 PM |
| Reels | 9 AM, 12 PM, 7-9 PM |
| Shorts | 12-3 PM, 7-9 PM |
| Goal | Minimum | Optimal |
|---|---|---|
| Growing | 1/day | 2-4/day |
| Maintaining | 3/week | 1/day |
| Testing | 2/week | 5/week |
| Metric | What It Tells You |
|---|---|
| Watch time % | Is content engaging throughout? |
| Completion rate | Did hook + content deliver? |
| Saves | Is content valuable enough to revisit? |
| Shares | Is content worth spreading? |
| Comments | Did content spark conversation? |
| Follows | Did viewer want more from you? |
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
View source ↗You are an expert video producer who helps create marketing videos using AI generation models, AI avatars, and programmatic video frameworks. Your goal is to help users produce professional video content efficiently — from product demos and explainers to social clips and ads.
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):
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 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 |
Build videos with code. Best for repeatable, templated, or data-driven video at scale.
Open-source, Apache 2.0, from HeyGen. Uses plain HTML/CSS/JS — no framework DSL to learn. LLM-native: AI models generate better HTML than React components.
npm install hyperframes
Key concept: Each frame is an HTML document. Compose frames into a timeline, render to MP4.
import { render } from "hyperframes";
await render({
frames: [
{ html: "<h1>Welcome to Acme</h1>", duration: 3 },
{ html: "<h2>Here's what we built</h2>", duration: 3 },
{ html: "<p>Try it free →</p>", duration: 2 },
],
output: "intro.mp4",
width: 1080,
height: 1920, // 9:16 for vertical
});
Best for: Product announcements, changelogs, data-driven reports, personalized outreach videos.
Why agents prefer it: Plain HTML/CSS means any coding agent can generate frames without learning a framework. Deterministic rendering — same input always produces identical output.
Mature open-source framework. More powerful than Hyperframes but requires React knowledge.
npx create-video@latest
Key concept: React components are frames. Props drive content. Render locally or via Remotion Lambda (AWS) for scale.
export const ProductDemo: React.FC<{ title: string; features: string[] }> = ({
title, features
}) => {
const frame = useCurrentFrame();
return (
<AbsoluteFill style={{ background: "#000", color: "#fff" }}>
<h1>{title}</h1>
{features.map((f, i) => (
<Sequence from={i * 30} key={i}>
<p>{f}</p>
</Sequence>
))}
</AbsoluteFill>
);
};
Best for: Complex animations, interactive previews, large-scale batch rendering (Lambda).
| Factor | Hyperframes | Remotion |
|---|---|---|
| Agent compatibility | Better (plain HTML) | Good (React) |
| Animation complexity | Basic (CSS transitions) | Advanced (Spring, interpolate) |
| Batch rendering | Local | Lambda (AWS) for scale |
| Learning curve | Minimal | Moderate (React + Remotion API) |
| License | Apache 2.0 | Company license for commercial use |
Generate original footage from text or image prompts. Use for B-roll, hero visuals, and scenes you can't practically film.
| Model | Resolution | Max Duration | Best For | Cost |
|---|---|---|---|---|
| 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
Good video prompts specify: subject + action + camera + style + mood
A close-up shot of hands typing on a laptop keyboard,
shallow depth of field, warm office lighting,
camera slowly pulls back to reveal a modern workspace,
cinematic color grading, 4K
Common mistakes:
- Too vague ("a person working") — add specifics
- Ignoring camera movement — specify dolly, pan, static
- Forgetting style — "cinematic," "documentary," "commercial"
- Requesting text in video — AI models struggle with readable text
For detailed prompting guides: See references/ai-video-prompting.md
| Use Case | AI Generation | Stock Footage |
|---|---|---|
| Exact scene you imagined | Yes | Rarely matches |
| Consistent style across clips | Yes | Hard to match |
| Recognizable real locations | No (hallucinations) | Yes |
| Specific products/brands | No (use programmatic) | No |
| Quick B-roll | Either works | Faster |
Create talking-head videos without filming. An AI avatar delivers your script with realistic lip-sync, expressions, and gestures.
Best lip-sync and micro-expressions. 230+ avatars, 140+ languages.
Agent integration: HeyGen has an official MCP server — AI agents can generate avatar videos directly.
| Plan | Videos | Duration |
|---|---|---|
| Free | 3/mo | 3 min max |
| Creator | Unlimited | 5 min |
| Business | Unlimited | 20 min |
Check heygen.com/pricing for current prices.
Best for: Product explainers, feature announcements, personalized sales outreach, multilingual content.
Custom avatars: Upload a 2-5 min video of yourself to create a digital twin. Looks and sounds like you, generates videos from text scripts.
Full-body avatars with expressive body language. Built-in script generation from URLs/docs.
Best for: Corporate training, compliance videos, enterprise presentations where professional tone > realism.
| Scenario | Use Avatar | Use Instead |
|---|---|---|
| Recurring content (weekly updates) | Yes | — |
| Multilingual versions | Yes | — |
| Personalized outreach at scale | Yes | — |
| Authentic founder content | No | Film yourself |
| Product UI walkthrough | No | Screen recording |
| Creative/artistic video | No | AI generation |
Turn existing content into multiple video formats.
| Tool | What It Does | Best For |
|---|---|---|
| Descript | Transcript-based editing — edit video by editing text | Cleaning up interviews, podcasts, webinars |
| Opus Clip | Auto-clips long videos, scores virality potential | Long-form → short-form at scale |
| CapCut | Visual effects, captions, platform-native styling | TikTok/Reels polish |
| Captions.ai | Auto-captions, eye contact correction, AI dubbing | Solo talking-head content |
Long-form content (podcast, webinar, demo)
↓
Descript: Clean up, remove filler, polish
↓
Opus Clip: Auto-extract 5-10 best moments
↓
CapCut: Add captions, effects, platform styling
↓
Distribute: TikTok, Reels, Shorts, LinkedIn
To replicate the style of a video edit you admire — the cut rhythm, caption treatment, punch-ins, on-screen text, sound design — decompose it into a reusable edit spec (a beat sheet) and apply it to your own footage. Pull the reference with watch-video (visual/multimodal mode extracts frames at the cut points) or social-fetch, extract the edit anatomy beat by beat, and output a per-beat table plus the 3–5 signature moves that make the edit recognizable. Review the beat sheet once before executing it (in Remotion/Hyperframes, CapCut, or an AI restyle tool). Copies the editing grammar, never the reference's footage/script/music. Full method: references/edit-anatomy.md.
The most powerful setup combines tools that agents can control directly:
Agent writes script (from product context)
↓
Hyperframes: Generate templated video (HTML → MP4)
and/or
HeyGen MCP: Generate avatar video from script
and/or
Veo/Runway API: Generate B-roll footage
↓
Agent assembles final cut
↓
Output: Ready-to-publish video
What makes this agent-native:
- Hyperframes uses HTML — any coding agent can generate it
- HeyGen MCP server — agents call it directly
- Video model APIs — standard HTTP requests
- No manual editing step required
| Tool | Type | MCP | Guide |
|---|---|---|---|
| HeyGen | AI avatars | Yes | heygen.md |
| Hyperframes | Programmatic video | - | hyperframes.md |
| Remotion | Programmatic video | - | remotion.dev |
| Runway | AI generation | - | runwayml.com/docs |
How to write effective prompts for AI video generation models (Veo, Runway, Kling, Pika).
A strong video prompt follows this formula:
[Subject] + [Action] + [Camera movement] + [Visual style] + [Lighting/mood] + [Technical specs]
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
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 |
| 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" |
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 |
| 16:9 or 1:1 | 1920x1080 |
A viral short-form video usually isn't winning on the footage — it's winning on the edit: the cut rhythm, the caption style, the punch-ins, the on-screen text landing on the exact word, the b-roll cutaways, the sound design. This reference turns a reference edit you admire into a reusable edit spec — a beat sheet you (or an editing tool) can execute against your own footage — without copying a single frame of theirs.
This is the tool-agnostic half of "copy any viral edit": the decomposition. The generation is whatever you edit with afterward — CapCut, Premiere, Remotion/Hyperframes, or an AI restyle tool. The spec is the deliverable.
Don't use it to copy someone's actual creative — this extracts the editing grammar (structure, rhythm, caption treatment), not the script, footage, or brand. Same rule as mining organic content for vocabulary in the hook system: take the technique, never the creative.
You cannot decompose an edit from a description of it. Get the frames and the timing:
Note the total duration and roughly how many cuts there are before you start — cuts-per-second is the single most telling number about an edit's energy.
Walk the reference from 0:00 and log every editing decision. The dimensions that define a short-form edit:
| Dimension | What to read off the reference |
|---|---|
| Shot & framing | Talking head / screen recording / b-roll / text card; close-up vs. wide; headroom, rule-of-thirds, or dead-center |
| Cut rhythm | Where each cut lands and how fast (cuts-per-second); is it on the beat, on the word, or on the breath? |
| On-screen text | The words, when each appears/disappears, and where on the frame (top-third caption vs. big centered statement) |
| Caption style | Font, weight, color, outline/box, and animation (word-by-word pop, karaoke highlight, whole-line) |
| Motion | Punch-ins / zoom pushes, shakes, whip-transitions, speed ramps — where and how aggressive |
| B-roll & overlays | Cutaways, stickers, arrows, emoji, screenshots, meme inserts — what's laid over the base footage and when |
| Sound design | Music choice and where it hits, SFX (whooshes, dings, risers), and deliberate silence before a beat |
| Hook (first 2s) | The single most-copied element — what's on screen and said in the opening two seconds, before anyone's committed |
| Pacing curve | Does it stay frantic, or fast-hook → slower-body → fast-CTA? Map the energy over the runtime |
Read the pattern, not just the instances: "a hard cut + punch-in on every new sentence," "caption is one word at a time, yellow, karaoke-highlighted, bottom third," "a whoosh SFX on every scene change." Patterns are what make an edit replicable; a list of 40 individual cuts is not.
Two artifacts: a per-beat table and a short style summary.
The beat sheet — one row per beat (a beat = a cut or a distinct edit event):
| Beat | Time | Shot | On-screen text | Caption style | Transition / motion | Audio |
|------|-----------|-----------------|-----------------------|----------------------|-----------------------|------------------|
| 1 | 0:00–0:02 | CU talking head | "STOP doing this" | word-pop, yellow, ctr| hard in, slow push | music in + riser |
| 2 | 0:02–0:04 | screen record | (caption only) | karaoke, white, btm | hard cut + whoosh | click SFX |
| … | | | | | | |
The style summary — the 3–5 signature moves that make this edit recognizable, stated so they're reusable:
- e.g. "Every sentence gets a hard cut + a 5% punch-in." / "Captions are one word at a time, bottom-third, karaoke-highlighted." / "A whoosh SFX on every cut; music drops out for 0.5s before the CTA." / "The hook is a bold centered statement on frame 1, no logo."
The signature moves are the real deliverable — someone can apply those five rules to any footage and get the style. The table is the detailed backup.
Show the beat sheet before anyone edits anything — the same review-once gate as the ad-creative creative review page. The reviewer checks two things:
Approve, then execute the spec with your footage:
- Remotion / Hyperframes — when you want the edit templated and data-driven (see the programmatic-video section in SKILL.md); the beat sheet is the composition spec.
- CapCut / Premiere / an editor — hand off the beat sheet + style summary as the brief.
- An AI restyle tool — feed the style summary as the target style.
You are copying the edit, not the content. The beat sheet describes technique (cut rhythm, caption treatment, motion, sound design) applied to your footage and your message. General editing techniques and style cues are usually reusable — U.S. copyright protects expression, not procedures or methods (17 U.S.C. §102(b)) — but the reference's specific creative expression is not, and closely reproducing a finished video's exact selection and arrangement of choices can still create risk. So copy the grammar, not the finished work: use your own footage, message, script, voiceover, licensed music/SFX/samples, and brand elements. If the reference's "style" is really a specific bit or sketch, that's their creative — draw inspiration, don't reproduce it.
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 campa
View source ↗You are an expert performance marketer with direct access to ad platform accounts. Your goal is to help create, optimize, and scale paid advertising campaigns that drive efficient customer acquisition.
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):
This skill's depth lives in references — load by intent. For any operational decision on a live account (kill/keep/scale/budget), load the relevant playbook before answering; the thresholds live there, not here.
| User intent | Load | Covers |
|---|---|---|
| B2B strategy, funnel stages, budget splits, kill rules, lead quality, breakeven math | b2b-paid-playbook.md | Demand lifecycle, leading/lagging signals, kill rules, offline conversion loop, U/B/F lead scoring, scaling quadrant |
| Meta operations: when to kill/graduate/scale an ad, fatigue, testing structure | meta-decision-system.md | TCPL-anchored decision tree, ad-count ceiling, 80/20 CBO structure, fatigue bands, lead forms, Advantage+ transition |
| LinkedIn operations: bidding, audience sizing, scaling, benchmarks, TLAs, formats | linkedin-b2b-playbook.md | Bidding progression, penetration scaling, sizing rules, funnel benchmarks, document/conversation ads, audit shortlist |
| Google Search: what to spend on first, structure, match types, negatives, PMax | google-search-playbook.md | Intent ladder, account structure, match-type gates, negatives, bidding by volume, offline conversions, PMax guardrails |
| Named-account targeting, pipeline acceleration, cross-channel retargeting | abm-playbook.md | LinkedIn/Meta ABM, list mechanics, acceleration campaigns, UTM cross-channel remarketing, ABM measurement |
| Generating Google RSAs | rsa-output-spec.md | Mandatory output spec — limits, sidecars, template, self-check |
| Audience setup, tracking setup, launch checklists, copy formulas | audience-targeting.md · conversion-tracking.md · platform-setup-checklists.md · ad-copy-templates.md | Existing foundations |
| Platform | Best For | Use When |
|---|---|---|
| Google Ads | High-intent search traffic | People actively search for your solution |
| Meta | Demand generation, visual products | Creating demand, strong creative assets |
| B2B, decision-makers | Job title/company targeting matters, higher price points | |
| Twitter/X | Tech audiences, thought leadership | Audience is active on X, timely content |
| TikTok | Younger demographics, viral creative | Audience skews 18-34, video capacity |
Account
├── Campaign 1: [Objective] - [Audience/Product]
│ ├── Ad Set 1: [Targeting variation]
│ │ ├── Ad 1: [Creative variation A]
│ │ ├── Ad 2: [Creative variation B]
│ │ └── Ad 3: [Creative variation C]
│ └── Ad Set 2: [Targeting variation]
└── Campaign 2...
[Platform]_[Objective]_[Audience]_[Offer]_[Date]
Examples:
META_Conv_Lookalike-Customers_FreeTrial_2024Q1
GOOG_Search_Brand_Demo_Ongoing
LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24
Testing phase (first 2-4 weeks):
- 70% to proven/safe campaigns
- 30% to testing new audiences/creative
Scaling phase:
- Consolidate budget into winning combinations
- Increase budgets ~20% at a time — never 30%+ in one move (resets platform learning)
- Wait 3-5 days between increases for algorithm learning
Problem-Agitate-Solve (PAS):
[Problem] → [Agitate the pain] → [Introduce solution] → [CTA]
Before-After-Bridge (BAB):
[Current painful state] → [Desired future state] → [Your product as bridge]
Social Proof Lead:
[Impressive stat or testimonial] → [What you do] → [CTA]
For detailed templates and headline formulas: See references/ad-copy-templates.md
Knowing your audience deeply is still the highest-leverage work in paid ads — demographics, job titles, pain points, fears, hopes, the exact language they use, who they follow, what they've tried, why they failed, what they buy. Gather every identifier you can.
What's changed in 2026 is where you apply that knowledge. As ad-platform algorithms have gotten dramatically better at finding the right person, jamming all your audience identifiers into the platform's targeting filters underperforms feeding those same identifiers into the creative (headlines, copy, visuals, hooks, examples).
The discipline now: audience knowledge → creative first, targeting filters second. How much that ratio tips toward "creative" varies meaningfully by platform.
| Platform | Audience knowledge → creative | Audience knowledge → targeting filters | Notes |
|---|---|---|---|
| Meta (post-Andromeda) | 80%+ | 20% | Algorithm rewards broad + specific creative. See [[#Modern Meta playbook (Andromeda era — 2026+)]] below for the full reframe. Interest-stacking now actively hurts. |
| Google Search | 40% | 60% | Keywords are still the dominant signal — match-types, search-intent layering, and negative keywords still drive performance. Creative (RSA headlines) matters but is downstream of the keyword. |
| Google Performance Max / Demand Gen | 70% | 30% | Audience signals are advisory, not deterministic. Creative + product feed quality dominate. |
| 40% | 60% | Job-title / company / industry filters still produce real precision because LinkedIn's identity data is high-quality. Creative makes the click; firmographics make the right person see it. | |
| TikTok | 70% | 30% | Algorithm is closer to Meta's model — broad targeting + native-feeling creative wins. Some audience interests help but creative dominates. |
| Twitter/X | 50% | 50% | Interest + follower targeting still meaningful, but creative differentiation is high-leverage given lower competition. |
These ratios are directional, not precise. Test in your actual account.
Once you've gathered audience identifiers, here's how to put each kind into the creative:
Trying to make up for weak creative with hyper-precise targeting. If your creative is generic but you stack 12 interests + 3 demographic filters + a custom audience, what you've built is a small audience that all see a bad ad. Better: gather the same audience identifiers, write 5 creative variants that each speak to a different segment, target broadly, let the algorithm match each creative to the right segment.
For detailed targeting strategies by platform: See references/audience-targeting.md
Meta launched the Andromeda algorithm in 2025, which fundamentally changed Meta ads. The old playbook (interest stacking, polished video creative, single-winner scaling) underperforms. The new playbook:
"I want you to read this ad and be the author. If I show the next ad I'm going to ask you to write to 100 people, not 1 in 100 would be able to tell you it's written by a different person. Now write this for [demographic/niche]."
Production tips:
- Captions always (85% watch without sound)
- Vertical for Stories/Reels, square for feed
- Native feel outperforms polished
- First 3 seconds determine if they watch
For hard kill/keep/scale thresholds, use the platform playbooks (see Reference Routing): the kill rules and breakeven CPL/CPC math live in b2b-paid-playbook.md, and Meta's full decision tree lives in meta-decision-system.md.
| Objective | Primary Metrics |
|---|---|
| Awareness | CPM, Reach, Video view rate |
| Consideration | CTR, CPC, Time on site |
| Conversion | CPA, ROAS, Conversion rate |
If CPA is too high:
1. Check landing page (is the problem post-click?)
2. Tighten audience targeting
3. Test new creative angles
4. Improve ad relevance/quality score
5. Adjust bid strategy
If CTR is low:
- Creative isn't resonating → test new hooks/angles
- Audience mismatch → refine targeting
- Ad fatigue → refresh creative
If CPM is high:
- Audience too narrow → expand targeting
- High competition → try different placements
- Low relevance score → improve creative fit
| Funnel Stage | Audience | Message | Goal |
|---|---|---|---|
| Top | Blog readers, video viewers | Educational, social proof | Move to consideration |
| Middle | Pricing/feature page visitors | Case studies, demos | Move to decision |
| Bottom | Cart abandoners, trial users | Urgency, objection handling | Convert |
| Stage | Window | Frequency Cap |
|---|---|---|
| Hot (cart/trial) | 1-7 days | Higher OK |
| Warm (key pages) | 7-30 days | 3-5x/week |
| Cold (any visit) | 30-90 days | 1-2x/week |
The conventional retargeting playbook re-shows the same product/offer to people who didn't buy. The Sabri Suby principle: the #1 reason someone didn't buy is the offer wasn't right for them. Re-showing the same thing harder doesn't help.
Instead, retarget with different products, services, or offers from your catalog:
- Visitor clicked on protein powder, didn't buy → retarget with creatine (totally different category)
- Visitor downloaded a lead magnet, didn't book a call → retarget with a different lead magnet on a related topic
- Visitor viewed pricing, didn't sign up → retarget with a free audit or assessment instead
The lift from this is often dramatic — a 2-3 ROAS audience on the original offer can hit 6+ ROAS on a different offer.
Build out your retargeting layer with these 4 ad types running simultaneously:
These four together, retargeting the same audience that didn't convert from the top-of-funnel ad, dramatically lift the ROAS of the entire funnel.
Ad-to-landing-page congruence is the single most underrated lever in paid ads. Most advertisers spend 90% of effort on ads and 10% on the landing page; flip that ratio.
Meta is the best split-testing tool that exists — your ad headlines are exposed to ~1000x the audience that actually clicks through to your landing page. That means you get statistically-significant data on which headlines work much faster on Meta than on your landing page.
The play:
This works because the viewer who clicked is expecting that specific promise. When the landing page restates the exact promise verbatim, scent matches and conversion follows. When the landing page pivots to a different angle, bounce rate spikes regardless of how good the page is.
A standing discipline: at any given moment, you should have at least 3 split tests running somewhere in your funnel — ad creative, landing page, offer, or post-conversion flow. If you don't, you've capped your improvement curve.
The math: 3 simultaneous tests × ~10-20% lift each (compounding) = a fundamentally better funnel within a quarter.
The most common scaling failure: a business at a 40 ROAS spending $5k/month, refusing to scale because "if I spend more, my ROAS will drop." This is the wrong frame.
Net cash flow > ROAS percentage at the business level:
- ROAS dropping from 10 → 5 sounds bad
- But if spend goes from $10k → $100k, you net dramatically more total profit
- The number to optimize is blended ROAS at the business level, not per-ad-set ROAS
- Even better: optimize net free cash flow, not ROAS at all
Find your break-even ROAS:
1. Calculate the absolute maximum you can pay to acquire a customer and still be profitable (factoring LTV)
2. That's your break-even ROAS / CPA ceiling
3. Scale until you approach that ceiling, not until your ad-account ROAS drops below an arbitrary preference
The 3-hour founder review:
- Block out 3 hours per month in the calendar to physically review the numbers yourself
- Not what your data analyst says. Not what your media buyer says. You, going through the actual data
- The confidence this generates is irreplaceable — and confidence is what lets you scale with conviction
- "Data gives you confidence. Confidence gives you speed."
Outbound-call your leads who didn't convert:
- Every lead that downloaded a lead magnet or hit your funnel but didn't buy gets a call
- Ask why they didn't book, what was confusing, what the actual blocker was
- These verbatim answers become objection-handling ads (see Retargeting section)
- Massive insight-to-creative loop that most advertisers skip
Before launching campaigns, ensure proper tracking and account setup.
For complete setup checklists by platform: See references/platform-setup-checklists.md
For conversion pixel installation and event setup: See references/conversion-tracking.md
When the user requests Google Ads RSAs, load references/rsa-output-spec.md and follow it exactly — hard character limits, required sidecar artifacts (ad groups, negatives, sitelinks, callouts), output order, template shape, CFM medical compliance, and the pre-send self-check. Do not output any RSA that violates it.
For implementation, see the tools registry. Key advertising platforms:
| Platform | Best For | MCP | Guide |
|---|---|---|---|
| Google Ads | Search intent, high-intent traffic | ✓ | google-ads.md |
| Meta Ads | Demand gen, visual products, B2C | - | meta-ads.md |
| LinkedIn Ads | B2B, job title targeting | - | linkedin-ads.md |
| TikTok Ads | Younger demographics, video | - | tiktok-ads.md |
For tracking setup, see references/conversion-tracking.md, ga4.md, segment.md
Account-based marketing with ads: targeting named accounts on LinkedIn and Meta, accelerating open pipeline, and stitching channels together. ABM ads are a pipeline influence motion, not a lead-gen motion — measure accordingly.
Run paid ABM when: target account list ≥ ~1,000 companies (or you accept 1:1/1:few economics), deal size ~$25K+, sales cycle 60+ days, sales and marketing actually aligned on the list, and (for Meta) contact enrichment available.
Skip it when: TAL under ~500 with no enrichment, no first-party data, budget under ~$3K/month, or a short transactional cycle — standard ICP targeting will outperform.
Three motions, by list size:
List mechanics:
- LinkedIn needs 300 matched members minimum to serve; aim for 1,000+ rows (duplicating company names to pad the upload is fine — it dedupes on match). Contact lists match best at scale (LinkedIn suggests ~10K emails); company lists beat contact lists for most teams — easier to source, better match rates, less maintenance.
- Cold ABM audiences need ~15K members to deliver reliably.
- Segment mixed lists. Left as one audience, LinkedIn over-serves the largest enterprises in the list — accounts have sat at 15% list coverage because the algorithm parked on a few big companies. Split into homogeneous bands (e.g., enterprise / mid-market / SMB) with separate campaigns and budgets.
- List-based targeting typically buys reach materially cheaper than native firmographic targeting, with stronger decision-maker engagement.
- Use the per-company engagement report (Audiences → click into the list) to find under-served priority accounts, then break them into a dedicated campaign.
Personalized 1:1 creative: putting the target account's name/logo in the creative can lift CTR ~5–10× over generic ads. Legal exception: do not run company-name/logo-personalized ads into Germany — privacy law, not platform policy.
Frequency capping: target ~3 impressions/person/week in priority accounts. Mechanic: build a company-engagement audience of accounts that crossed ~500 impressions in the last 7 days and add it as an exclusion — it self-rotates accounts out as they cool down. Tune the threshold (300 if fatigue shows, 750 for more pressure).
Meta has no native company targeting — the play is bring your own matched audience:
Ads aimed at accounts already in your pipeline, to speed deals rather than source them:
Default split for B2B ABM: ~60% LinkedIn / ~30% Meta / ~10% other. LinkedIn buys precision (right person, right company) at $40–70 CPMs; Meta buys presence and committee reach at $10–25. Sequence LinkedIn first to validate the audience, then extend to Meta. Multi-channel ABM consistently and materially outperforms single-channel on engagement and conversion — the channels compound, they don't compete.
The cheapest high-quality audience you can build: retarget one platform's validated clickers on another platform.
utm_source=linkedin, utm_source=google&utm_medium=cpc).utm_source=linkedin" (or utm_source=google).Works in both directions (search clickers → LinkedIn remarketing needs meaningful search volume — worth it above roughly $30K/month search spend). Requires enough source-channel traffic to clear minimum audience sizes. Use a consistent account/campaign token in UTMs so attribution survives the hop.
ABM ads without sales follow-up is billboard spend:
Judge ABM on account movement, not CPL:
Framework lineage: adapted (re-expressed and restructured) from practitioner playbooks, notably Ivan Falco's ads-skills. Thresholds are practitioner-reported starting points — recalibrate against your own accounts.
Detailed formulas and templates for writing high-converting ad copy.
[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 →
[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.
[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]
[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
[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
| 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" |
| 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..." |
Best for: Top of funnel, cold audiences, complex products
Best for: Bottom of funnel, warm audiences, clear offers
Best for: Limited-time offers, scarcity situations
Best for: Active voice, clear next step
When testing ad copy, focus on these elements in order of impact:
Test one element at a time for clean data.
Detailed targeting strategies for each major ad platform.
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
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
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
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
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
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 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
| 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 |
| 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 |
| 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
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)
Cross-platform operating rules for B2B paid acquisition — where sales cycles run 2–24 months, in-platform conversions mislead, and lead quality matters more than lead cost. Use this alongside the platform playbooks (Meta decision system, LinkedIn, Google Search, ABM).
TOFU/MOFU/BOFU stops at conversion. B2B revenue doesn't — closed-lost deals, open pipeline, and existing customers are all addressable with ads. Plan across five stages:
| Stage | Outcome | Buyer awareness | Typical offers | KPIs |
|---|---|---|---|---|
| Create | Build affinity & trust | Unaware / Problem-aware | Educational content, POV | Cost per consumption, blended cost/opp |
| Capture | Convert in-market buyers | Solution / Product-aware | Demos, trials | Pipe-to-spend, direct cost/opp |
| Accelerate (sales-led) / Activate (product-led) | Close open deals faster / convert free users | Product / Offer-aware | Case studies, webinars, events | Pipeline velocity, paid signups |
| Revive | Restart closed-lost | Offer-aware | Incentivized demos, guided trials | SQOs created, cost/SQO |
| Expand | Grow existing accounts | Most aware | Referral programs, new-feature content | Expansion revenue, influenced SQOs |
Build bottom-up for fastest ROI: Expand → Revive → Accelerate/Activate → Capture → Create. The bottom stages are cheap, small-audience, and quick to pay back; Create is the biggest and slowest investment. Most teams build top-down and burn months waiting for ROI.
| Stage | Budget size | Time to ROI | Difficulty |
|---|---|---|---|
| Create | High | 90+ days | High (needs strong content + POV) |
| Capture | Moderate | <45 days | High (expensive, competitive) |
| Accelerate/Activate | Low | Tracks sales cycle | Low |
| Revive | Low | <45 days | Low |
| Expand | Low | <60 days | Medium (small audiences) |
Weight by motion: product-led skews budget to Create + Capture; sales-led with a small TAM skews to Create + Accelerate. The stage with the most pipeline isn't automatically the stage that deserves the most budget — fund where pipeline share exceeds budget share and the audience is under-penetrated.
You can't optimize on closed-won when deals close in 6 months. Split every stage's metrics:
The leading metric must demonstrably correlate with the lagging one — a proxy metric worth optimizing is measurable, moveable, not an average, and hard to game. If CPL falls while pipeline doesn't move, the proxy broke; fix the proxy, not the ads.
Derive targets from deal math, not platform benchmarks:
Set the actual target below breakeven by your required margin. Every kill rule and scaling decision keys off this number.
Two hard rules that remove emotion from pausing decisions:
These aren't statistically rigorous — they're repeatable, cheap to apply, and better than deciding by mood. Never pause a producer without a replacement staged (see the swap rules in the Meta decision system).
Smart bidding optimizes toward whatever you call a "conversion." Feed it raw form-fills and it will buy you cheap junk form-fills — CPL improves while pipeline dies. The fix, in order:
Reconcile platform-reported conversions against the CRM monthly. When they disagree, the CRM wins.
The platform can't see lead quality — score it yourself and rank ads by it:
Whoever runs the sales calls scores each lead (max 9) and logs it against the originating ad. After ~20 scored calls, rank ads by average quality score, not CPL or CTR — the ad with the best CPL is regularly the one producing 3/9 leads. Scale the high-score ads; kill variations whose average drops below ~5.
Route scaling tactics by your actual constraint:
| Low effort | High effort | |
|---|---|---|
| High budget | Audiences — bigger audiences, more segments, more frequency | Geography — new countries/regions (localization work) |
| Low budget | Ads — new creative, angles, formats | Objectives & bids — change objective or bid strategy to buy cheaper |
Before scaling spend, score yourself 1–3 on each: blended pipeline dashboard; per-channel dashboard; conversion tracking (1 = none, 2 = pixel only, 3 = offline conversions flowing); web analytics; a documented, agreed attribution process. Under ~6/15, fix visibility before adding budget — you're flying blind and every optimization is a guess. Fix the lowest score first.
Five channel families: paid social, paid search, paid review listings (G2, Capterra, Software Advice — often skipped, high intent), programmatic (display, audio, CTV, native), and sponsorships (newsletters, podcasts, events, creators). Evaluate on four axes: can you actually target your ICP; media cost (CPC/CPM); reach at your targeting; platform policy for your industry.
Before committing to a new channel, run a ~$100 test campaign to learn its real CPC/CPM for your targeting — platform estimates and published benchmarks are consistently wrong for specific ICPs.
Framework lineage: several operating rules in this file are adapted (re-expressed, restructured, and extended) from practitioner playbooks, notably Ivan Falco's ads-skills. Benchmarks and thresholds are practitioner-reported starting points — always recalibrate against your own account's first 30 days.
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.
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 | 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 |
| 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 |
Add to every page, in <head>:
<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.
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 |
// 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'
});
Sends hashed first-party data (email, phone) to improve attribution after cookie restrictions. Enable in Google Ads > Goals > Settings > Enhanced conversions.
gtag('set', 'user_data', {
'email': 'user@example.com', // auto-hashed by gtag
'phone_number': '+11234567890'
});
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
Add to every page, in <head>:
<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.
// 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'
});
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.
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
Add to every page, before </body>:
<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>
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:
window.lintrk('track', { conversion_id: YOUR_CONVERSION_ID });
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.
Add to every page, in <head>:
<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>
// 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'
});
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.
Pass hashed user data for better attribution:
ttq.identify({
email: 'user@example.com', // auto-hashed
phone_number: '+11234567890'
});
After installing any pixel, verify before going live:
| Platform | Tool |
|---|---|
| Google Tag Assistant, Chrome DevTools Network tab | |
| Meta | Meta Pixel Helper (Chrome extension), Events Manager Test Events |
| Insight Tag Validator in Campaign Manager | |
| TikTok | TikTok Pixel Helper (Chrome extension), Events Manager |
| All | GTM Preview Mode (if using Google Tag Manager) |
event_id, you'll double-count conversionsBrowser-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)
Intent-first operating rules for Google Ads: where to spend first, how to structure the account, when to loosen match types, and how to keep smart bidding pointed at revenue instead of junk form-fills. For RSA generation mechanics, see rsa-output-spec.md.
Spend opens rung by rung — each tier unlocks only after the one below proves it converts to pipeline:
Don't skip rungs. Broad spend before high-intent proof is how B2B accounts burn budgets with nothing in the CRM.
Bid on brand by default — if you don't, competitors will, and you pay in lost deals rather than clicks. The exception: if you're the only bidder and organic owns the whole SERP, test pausing brand and watch total brand conversions (paid + organic), not just paid. If total holds, you were cannibalizing yourself; if it drops, turn it back on. Cap brand budget — it rarely needs much, and shared budgets let brand eat everything (see below).
Search harvests existing demand; it cannot create demand. If your category has near-zero search volume, say so and put the budget upstream (LinkedIn/Meta/YouTube) instead of forcing keywords nobody types. Demand creation happens on social; Search is where you catch it landing.
Minimum viable split — each with an independent budget:
Why independent budgets: in a shared budget the cheapest, highest-converting campaign (always brand) starves the ones you actually need data from. The account looks profitable on paper and is blind everywhere that matters.
Source keywords from how buyers describe the problem (sales-call language, your own search-terms report, competitor ad copy) — not how you describe the product. A keyword with 50 searches/month and clear intent beats one with 5,000 and mixed intent. Tag every keyword by intent tier.
Match-type progression — in this order:
Starter lists to apply at build time:
Match-type mechanics gotcha: negative broad requires ALL its words present (any order) — negative broad "free trial" does not block "free" alone. Negative phrase blocks in-order phrases; negative exact blocks only that exact query. Most accidental over-blocking and under-blocking traces to this.
Don't over-negative: every negative narrows reach, and it compounds fast at B2B volumes. Negative the clearly wrong, not the merely uncertain — an ambiguous term deserves more data before it's cut.
Once a week per campaign, three passes:
| Conversions/month (campaign) | Strategy |
|---|---|
| 0–15 | Manual CPC or Maximize Conversions (no target) |
| 15–30 | Maximize Conversions |
| 30+ stable | Target CPA — set at or slightly above your trailing 30-day actual |
| Real revenue values flowing back | Target ROAS |
Rules of thumb: smart bidding needs ~30 conversions in 30 days per campaign to learn. Set tCPA near actuals — an aggressively low target chokes delivery (Google just stops bidding). Move targets in ±10–15% steps and wait 1–2 weeks; every change restarts learning, so don't panic-edit inside the learning window. Budget mechanics: campaigns can spend up to 2× daily budget in a day (Google balances monthly — single-day overspend is normal); a budget-capped campaign that's converting often lowers its CPA when you raise the budget, because constrained smart bidding underperforms.
The single highest-impact move in a B2B Google account: import CRM outcomes (SQL, opportunity, closed-won) back into Google via GCLID + offline conversion import or a native CRM integration, with real deal values. Until then, smart bidding optimizes to form-fills and buys you junk (see the optimize-to-quality trap in b2b-paid-playbook.md). B2B clicks close in 60–180 days — in-platform conversion counts will never tell the truth on their own. Reconcile against the CRM monthly; the CRM wins.
QS (1–10, per keyword) = expected CTR + ad relevance + landing page experience. Low QS means paying more for the same position — fix the weak component before raising the bid. Landing page rules that move it: message match (page headline echoes the ad's promise and the query — not a generic homepage); one job and one CTA per page; speed; proof above the fold. Form length is an intent gate: short forms buy volume at lower quality, longer qualified forms buy fewer/better — match it to what you're feeding back as the conversion event.
Value ranking: brand Search > high-intent non-brand Search > remarketing > PMax > broad demand-gen. PMax earns budget only after the cheaper, clearer wins are maxed. Never run it as the first campaign, on weak tracking, or on tiny budgets.
Guardrails when you do run it: account-level brand exclusions (or it cannibalizes brand Search and claims the credit); audience signals from first-party data; negative keywords from day one; offline conversions imported before scaling it; check the CRM quality of PMax leads by campaign — if they convert to pipeline at half the rate of Search leads, PMax is cheap-looking and expensive-in-reality. Google auto-generates a bad video if you don't supply one.
B2B SaaS Search ranges (wide on purpose — anchor to your own first 30 days): brand CTR 8–20%, CVR 15–40%; non-brand high-intent CTR 2–6%, CVR 3–10%, CPC $8–40+, CPL $80–400+; competitor terms run higher CPC and lower CVR than non-brand.
Weekly scorecard — exactly eight numbers: spend · leads · CPL · lead→SQL rate (from CRM) · SQLs · cost per SQL · Search impression share · top wasted search terms. Diagnostic: Search Lost IS (budget) vs Lost IS (rank) tells you whether you're capped by money or by Ad Rank — different problems, different fixes. If the eight are healthy and trending right, the account is healthy.
Framework lineage: adapted (re-expressed and restructured) from practitioner playbooks, notably Ivan Falco's ads-skills. Benchmarks are practitioner-reported starting points — recalibrate against your own account.
Operational rules for LinkedIn Ads: bidding, audience sizing, scaling triggers, benchmarks, and format-specific tactics. LinkedIn is the precision channel — highest-quality B2B targeting at the highest cost, so the operating discipline is about not wasting that precision.
Scheduling note: LinkedIn's ad day resets at UTC midnight. Professional activity peaks weekday mornings–early afternoon in the audience's timezone; dayparting there stretches limited budgets.
Title targeting is precise but small and expensive. Job function + seniority targeting typically triples the addressable audience with materially cheaper reach at similar engagement — at the cost of a weekly "negative title" exclusion pass for the first ~2 months (like negative keywords: exclude irrelevant titles as they show up in demographics).
Platform gotchas:
- Job-title targeting and seniority targeting are mutually exclusive — you can't stack them. Entry-level exclusions only work under function/seniority targeting.
- The Business Development function includes many CEOs, CMOs, and managing directors. Don't blanket-exclude BD if you sell to the C-suite — filter with seniority exclusions instead.
- Leave Audience Expansion OFF (it quietly spends a meaningful share of budget on out-of-ICP members) and Audience Network OFF for B2B lead gen.
Split priority: intent > persona > region/company size > seniority.
Audience penetration (reached ÷ audience size) is the scaling trigger, not spend:
Practitioner-reported B2B SaaS ranges — recalibrate on your own account. Careful: for engagement-objective and thought-leader campaigns, LinkedIn's reported "CTR" includes social actions; judge traffic on click-through to landing page (CTRTLP) specifically.
| Metric | Cold / TOF | MOF | BOF/retargeting |
|---|---|---|---|
| CTRTLP | 0.30–0.55% | 0.55–0.80% | 0.80–1.30% |
| CPM | $33–65 typical | — | — |
| CPC | $8–22+ | — | lower |
| Cost per lead (Lead Gen Form) | — | $50–200 | — |
| Cost per website form fill | — | — | $200–500 |
Other useful bars: lead-gen form fill rate >8% (below = form too long, offer weak, or audience too cold); cost per SQL should stay under ~$500 (enterprise ACVs tolerate $300–500+ CPLs; SMB needs $50–150); video view rate >40%, completion 8–15% for horizontal; expect return data to lag 3–6 months.
Ads promoted from a person's profile rather than the company page — currently the platform's biggest efficiency arbitrage:
Add groups in ROI order, funding each before the next: 1. Product value (direct response on your core offer) → 2. Remarketing → 3. Content (only content that can't be consumed in-feed — it must earn the click) → 4. Social proof (case studies, testimonials) → 5. Thought leadership (slowest payback, add last). Group-budget optimization tends to favor cheap audiences and video — don't mix enterprise with SMB or static with video in one group.
LinkedIn retargeting audiences only start collecting from the moment you create them. Create every retargeting audience you might ever want (site visitors, video viewers, ad engagers, lead-form openers, company page visitors) before launch — data you didn't capture is gone permanently.
Cross-channel: tag paid-search traffic with UTMs and build LinkedIn (and Meta) retargeting audiences from it — see the ABM playbook for the mechanic.
The highest-frequency findings when auditing LinkedIn accounts, in order: Audience Expansion left on · Audience Network left on · audiences too small to deliver · fewer than 4 active ads per campaign · campaigns under ~10 results/week (starved — consolidate) · stale creative (3+ months old) · no retargeting audiences created · lead quality never reconciled against CRM · brand/geo budget mixing · everything on automated bidding forever.
Framework lineage: adapted (re-expressed and restructured) from practitioner playbooks, notably Ivan Falco's ads-skills. Benchmarks are practitioner-reported starting points — recalibrate against your own account.
A quantified kill/keep/scale engine for Meta ads. Every threshold derives from one anchor number, so decisions become arithmetic instead of vibes. Pairs with the strategy-level Meta playbook in SKILL.md (creative-as-targeting, creative volume) — this file is the operating layer.
TCPL = Target Cost Per Qualified Lead (qualified = meets your ICP bar, not just a form-fill). Set it one of three ways:
Every rule below is expressed in multiples of TCPL. Review TCPL monthly.
More active ads than your budget can feed = every ad starves and nothing gets a fair read.
Ceiling = (daily budget × 14) / (2 × TCPL) — i.e., over a 14-day evaluation window, each ad needs at least 2× TCPL of spend to be judged.
$1,000/day at $500 TCPL → ceiling of 14 ads; run 6–10 (winners + 2–3 test slots). At the ceiling, launching a new test requires killing something first.
Run two CBO campaigns over the same audience:
Why: inside a single CBO, proven ads always starve new ads — tests never get enough spend to be judged. Why not ABO for testing: equal forced distribution keeps spending on ads Meta has already deprioritized. The separation is budget protection, not audience segmentation.
Image-first validation: launch new concepts as statics first; only produce the video/carousel/UGC version after the image passes the checks below. Exception: concepts that are inherently video (testimonial, demo, UGC).
CBO's spend allocation is itself a signal — Meta pre-screens your ads. At day 7 for each test ad:
When iterating on a delivery-killed ad, change the hook/visual/format only — the audience never got far enough for copy or CTA to matter.
Run in order; stop at the first triggered action:
Graduate only when all are true: ≥5 qualified leads · qualified rate ≥60% · cost per QL ≤ TCPL · running ≥14 days · ≥1 QL in the last 7 days.
Frequency bands by campaign type (safe / warning / critical):
| Campaign type | Safe | Warning | Critical |
|---|---|---|---|
| Cold prospecting | 1.0–2.5 | 2.5–4.0 | >4.0 |
| Retargeting | 2.0–4.0 | 4.0–6.0 | >6.0 |
| ABM (small audiences) | 2.0–5.0 | 5.0–8.0 | >8.0 |
Other signals, in urgency order: CTR down 20%+ from baseline over 7 days; CPM up 30%+ over 2 weeks (leading indicator — moves before CTR); ad relevance rankings "below average"; CPA up with stable targeting.
For scaling-campaign ads, apply a deliberately stricter bar than the general bands — these ads carry ~80% of spend, so fatigue there costs the most: warning at frequency 3.0–3.5 or cost +20% → start 2 iterations now (they take ~14 days to be ready); swap at >3.5, cost +40%, or >1.5× TCPL for 2 weeks.
Lifespan expectations (B2B): statics 14–28 days; short video and carousels 21–35; UGC/testimonial 28–42. Small B2B audiences build frequency fast — plan refresh every 14–21 days.
Retire (don't iterate) when CTR drops 30%+ from peak or frequency crosses the campaign type's critical band above — the concept is exhausted, not the execution.
Rotation without resetting learning: never edit creative inside a performing ad — that resets the learning phase. Launch new ads alongside existing ones, or spin up a new ad set with the same targeting. Pausing doesn't reset; editing does.
Never pause without a replacement. Keep 2–3 iterations staged; replacement live within 7 days, immediately for critical fatigue. If the pipeline is empty, redirect the budget to proven ads rather than leaving a zombie running. What to change depends on why it died: delivery kill → hook/visual; quality kill → angle and ICP language; cost kill → offer and audience; fatigue → fresh execution of the same proven concept.
Scale only when all: proven-ad count meets the next budget level's minimum; account frequency <3.0; cost per QL ≤ TCPL for 2+ consecutive weeks; 3+ replacements staged.
The #1 B2B Meta lead-quality problem: frictionless auto-filled forms produce leads who don't remember converting ("social amnesia"). Intentional friction = awareness = quality:
Lead form vs. landing page: LP converting ≥5% → use the LP; LP under ~2% → lead form; demo/trial offers → LP; content/webinar → form.
Manual is where you learn; Advantage+ is where you earn. Transition a campaign to Advantage+ only after: a proven offer, a validated audience, and ~50 conversions/week on the optimization event (the learning-phase exit bar — budget needed ≈ target CPA × 50 ÷ 7 per day). If you can't hit 50/week on the target event, optimize a higher-volume event up-funnel and retarget converters. Advantage+ conflicts with strict ABM (you can't lock it to a list) — see the ABM playbook. Watch Campaign Score directionally (70+ healthy, <50 = fighting the algorithm) but never trade lead quality for score.
B2B SaaS Meta ranges (practitioner-reported; recalibrate on your own first 30 days): CTR 1.0–1.5% (red flag <0.8%); CPM $10–20 (red flag >$25); CPL (form) $20–50 (red flag >$75); landing page CVR 8–12%. Seasonality: Q1 CPMs are the year's lowest (scale aggressively); Q4 runs +60–80% (consider reducing B2B spend and banking budget for January).
Framework lineage: this decision system is adapted (re-expressed, reconciled, and restructured) from practitioner operating systems, notably Ivan Falco's ads-skills. All thresholds are starting points — recalibrate against your own account.
Complete setup checklists for major ad platforms.
Before launching any campaign:
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.
1. ... (NN chars) so the reader can verify.Ad group structure: — list each ad group with its theme, target keywords (match types), and which RSAs map to it.Negative keywords: — minimum 8 entries, group-level vs campaign-level called out.If .agents/product-marketing.md indicates a Brazilian medical practice (CFM-regulated), the following terms are forbidden in headlines, descriptions, sitelinks, and callouts:
#1, melhor, o melhor, melhor do brasil, top, referênciagarantido, garantia, cura, cura definitiva, 100%, resultado garantido, livre da dorUse 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.
Ad group structure:
- AG1 [theme]: keywords (match types) → RSA1, RSA2
- AG2 [theme]: ...
Negative keywords:
Campaign-level:
- <kw>
- <kw>
(≥4 here)
Ad-group level:
- AG1: <kw>, <kw>
- AG2: <kw>, <kw>
(≥4 more here — TOTAL ≥8 entries)
Sitelinks (≥4):
- <title (≤25)> | <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 — ...
Before sending the output, run this checklist mentally:
If any check fails, rewrite before responding. Do not ship partial RSAs.
Write B2B cold emails and follow-up sequences that get replies. Use when the user wants to write cold outreach emails, prospecting emails, cold email campaigns, sales development emails, or SDR emails. Also use when the
View source ↗You are an expert cold email writer. Your goal is to write emails that sound like they came from a sharp, thoughtful human — not a sales machine following a template.
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.
Understand the situation (ask if not provided):
Work with whatever the user gives you. If they have a strong signal and a clear value prop, that's enough to write. Don't block on missing inputs — use what you have and note what would make it stronger.
The email should read like it came from someone who understands their world — not someone trying to sell them something. Use contractions. Read it aloud. If it sounds like marketing copy, rewrite it.
Cold email is ruthlessly short. If a sentence doesn't move the reader toward replying, cut it. The best cold emails feel like they could have been shorter, not longer.
If you remove the personalized opening and the email still makes sense, the personalization isn't working. The observation should naturally lead into why you're reaching out.
See personalization.md for the 4-level system and research signals.
The reader should see their own situation reflected back. "You/your" should dominate over "I/we." Don't open with who you are or what your company does.
Interest-based CTAs ("Worth exploring?" / "Would this be useful?") beat meeting requests. One CTA per email. Make it easy to say yes with a one-line reply.
The target voice: A smart colleague who noticed something relevant and is sharing it. Conversational but not sloppy. Confident but not pushy.
Calibrate to the audience:
What it should NOT sound like:
There's no single right structure. Choose a framework that fits the situation, or write freeform if the email flows naturally without one.
Common shapes that work:
For the full catalog of frameworks with examples, see frameworks.md.
Short, boring, internal-looking. The subject line's only job is to get the email opened — not to sell.
See subject-lines.md for the full data.
Each follow-up should add something new — a different angle, fresh proof, a useful resource. "Just checking in" gives the reader no reason to respond.
See follow-up-sequences.md for cadence, angle rotation, and breakup email templates.
Before presenting, gut-check:
The references contain performance data if you need to make informed choices:
Use this data to inform your writing — not as a checklist to satisfy.
| Metric | Average | Good | Excellent | Source |
|---|---|---|---|---|
| Open rate | 27.7% | 40–45% | 50%+ | Belkins, Snov.io |
| Reply rate | 4–5.8% | 5–10% | 10–15% | Belkins, Reachoutly |
| Reply rate (best-in-class) | — | — | 15–25%+ | Digital Bloom, Instantly |
| Positive reply % | ~48% | 55–60% | 62–65% | Digital Bloom |
| Meeting booking rate | 0.5–1% | 1–2% | 2.3%+ | Reachoutly |
| Bounce rate | 7.5% | <4% | <2% | Belkins |
500 emails → 100 opens (20%) → 25 replies (5%) → 8 positive replies (30%) → 4 meetings (50%) → 1 client (25% close). ~0.2% end-to-end conversion for average performers.
Reply rates dropped from 7–8% (2020–2022) to 4–5.8% (2024–2025), ~15% YoY decline. Drivers: inbox saturation (10+ cold emails/week, 20% say none relevant), stricter anti-spam (Google's threshold: 0.1% complaints), AI email flood (more volume, less quality signal). Writing craft matters more, not less — gap between average and excellent is widening.
Highest responding: Nonprofits (16.5%+), legal (10%), EdTech (7.8%), chemical (7.3%), manufacturing (6.1%).
Lowest responding: SaaS (3.5%), financial services (3.4%), IT services (3.5%).
| Factor | US | UK | Germany/DACH | Scandinavia |
|---|---|---|---|---|
| Tone | Direct, casual | Polite, professional | Precise, data-driven | Fact-based, egalitarian |
| Length | Shorter, blunt | Longer, insight-led | Detail-oriented | Concise but substantive |
| Social proof | Outcome numbers | Research-led credibility | Technical precision | Shared values |
North America: 4.1% response. Europe: 3.1%. Asia-Pacific: 2.8%. Shorter, more direct sequences work better in US. UK needs more insight/personality. GDPR affects European tone.
| Expert | Core Method | Best For |
|---|---|---|
| Alex Berman | 3C's: Compliment → Case Study → CTA | High-ticket B2B services, agencies |
| Josh Braun | "Poke the Bear" — neutral questions exposing invisible problems | Empathy-driven consultative selling |
| Kyle Coleman | Systematic research + AI personalization at scale | Bridging mass outreach and deep personalization |
| Becc Holland | Psychographic personalization, Premise Buckets | Combining personalization with relevance |
| Will Allred | Data-driven coaching, Mouse Trap, Vanilla Ice Cream | Any context; universal frameworks |
| Justin Michael | 1–3 sentence hyper-brevity, quote their own words | High-velocity SDR teams at scale |
| Sam Nelson | Agoge Sequence — Triple on Day 1 (email + LinkedIn + call) | Multi-channel, tiered personalization |
55% of replies come from follow-ups, not the initial email. Yet 48% of salespeople never follow up even once.
Increase the gap between each touch:
| Touch | Day | Notes |
|---|---|---|
| Initial email | 0 | Maximum personalization investment |
| Follow-up 1 | 3 | Waiting 3 days increases response by up to 31% |
| Follow-up 2 | 7–8 | Different angle |
| Follow-up 3 | 14 | New value piece |
| Follow-up 4 | 21–28 | Breakup email |
Best days: Tuesday–Thursday (Thursday peaks at 6.87% reply rate).
Best times: 9–11 AM or 1–3 PM in prospect's local time.
Avoid: Monday mornings (inbox overload), Friday afternoons (checked out).
Each follow-up must stand alone while building toward the goal. Never just "bump this up."
| Angle | Purpose | |
|---|---|---|
| Initial | Personalized hook + core value prop + soft CTA | Introduce problem/solution |
| Follow-up 1 | Different angle, new value piece (stat, insight, resource) | Show additional benefit |
| Follow-up 2 | Social proof / case study from similar company | Build credibility |
| Follow-up 3 | New insight, industry trend, or relevant resource | Demonstrate expertise |
| Follow-up 4 | Breakup — acknowledge silence, leave door open | Trigger loss aversion |
Add only one new value proposition per email (SalesBread). This naturally forces different angles.
Leverages loss aversion — removing pressure while creating scarcity through withdrawal. Close.com reports 10–15% response rates from breakup emails with cold prospects.
Structure:
Example:
I haven't heard back, so I'll assume now isn't the right time. Before I close the loop: [1-sentence insight or resource]. If that changes things, feel free to reply. Otherwise, no hard feelings — good luck with [their goal].
1-2-3 Format (reduces friction to near zero):
Since I haven't heard back, I'll keep it simple. Reply with a number:
1 — Interested, let's talk
2 — Not now, check back in 3 months
3 — Not interested, please stop
Critical rule: If you send a breakup email, honor it. Do not contact the prospect again.
Executives/founders: Ultra-low-effort, curiosity-driven. "Curious?" or "Worth 2 min?"
Mid-level managers: More specific value. "Want me to walk through how [Company] saved 15 hours/week?"
Higher in the org chart = less friction you can ask for.
Frameworks beat templates — they teach thinking patterns, not copy-paste shortcuts.
Structure: Identify pain → Amplify consequences → Present solution + soft CTA.
Best for: Problem-aware but not solution-aware prospects. The workhorse framework.
Most VP Sales at companies your size spend 5+ hours/week on manual CRM reporting. That's 250+ hours/year not spent coaching reps — and often means inaccurate forecasts reaching leadership. We built a tool that auto-generates CRM reports in real time. Teams like Datadog reduced reporting time by 80%. Would it make sense to see how?
Structure: Current painful situation → Ideal future → Your product as the bridge.
Best for: Transformation-driven offers with clear before/after. Emotional decision-makers.
Right now, your team is likely spending hours manually sourcing leads — feast or famine each quarter. Imagine qualified leads arriving daily on autopilot, reps spending 100% of their time selling. That's what our platform does. Companies like HubSpot saw a 40% pipeline increase within 90 days. Can I show you how?
Structure: Targeted pain question → Brief value → Direct next step.
Best for: C-suite prospects who prefer brevity. Qualify interest immediately.
Are your SDRs spending more time researching than selling? We help sales teams automate prospect research so reps focus on conversations. Clients see 3x more meetings per rep per week. Worth a 10-minute demo?
Structure: Hook/stat → Address specific challenge → Social proof/outcome → Clear CTA.
Best for: Data-driven prospects, high-ticket pitches with strong stats.
Companies in pharma lose 30% of leads due to manual outreach. Given {{Company}}'s growth this quarter, pipeline velocity is likely top of mind. Customers like Pfizer use our platform to automate lead qualification — cutting time-to-contact by 60%. Worth a 15-minute call?
Structure: Genuine compliment → How things could be better → Gentle push to action.
Best for: Senior prospects who respond to relationship-building. Requires genuine trigger.
Your keynote on scaling SDR teams was spot-on — especially on ramp time as the hidden cost. What if you could cut that in half? Our in-inbox coach helps new reps write effective emails from day one with real-time scoring. Open to a quick chat about how this could support your growth?
Structure: Introduce character (customer) → Tell challenge narrative → Reveal results.
Best for: Strong customer success stories. Humanizes the pitch.
Last year, Sarah — VP Sales at a Series B startup — had 5 SDRs competing against a rival with 20. Her team was getting crushed on volume. They adopted our AI prospecting tool and sent hyper-personalized emails at 3x pace without losing quality. Within 90 days, they booked more meetings than their competitor's entire team. Happy to share how this could work for {{Company}}.
Structure: Current reality → Complicating challenge → Question that speaks to need → Optional answer.
Best for: Consultative selling. Mirrors how professionals present to leadership.
Your team doubled this year. That usually means onboarding is eating into selling time. How are you handling ramp for new hires?
Structure: Contrarian hook → Explain benefit simply → Provide proof → Strong CTA.
Best for: Analytical buyers who need evidence (engineers, CFOs, ops leaders).
Most sales teams measure rep activity. The top 5% measure rep efficiency instead. When Acme switched, they booked 40% more meetings with fewer emails. Worth seeing how?
Structure: Compliment → Case Study → CTA.
Best for: Agency/services cold outreach. Case study does the heavy lifting.
Big fan of [Company]. We just built an app for [Competitor] that does XYZ. I have a few more ideas. Interested?
Structure: Observation + Binary value-prop question. 1–2 sentences total.
Best for: Maximum brevity. Impulsive reply based on curiosity.
Looks like you're hiring reps. Would it be helpful to get a more granular look at how they're ramping on email?
Structure: Trigger/Pain → Solution hint → Binary CTA. 1–3 sentences, no intro.
Best for: High-velocity SDR teams. Mobile-optimized. Deliberately polarizing.
Spend max 1 minute on personalization. Use industry/persona-level signals. For top-tier prospects, quote their own words from interviews — they almost always respond.
Structure: Observation → Problem/Insight → Credibility → Solution → Call-to-Conversation.
Best for: Universal "base" framework that works everywhere. Five parts.
Structure: Problem → Amplify → Story → Testimony → Offer → Response.
Best for: Longer-form or multi-email sequences. Consulting, education, complex B2B services. Each element can be developed across separate touches.
Personalization drives 50–250% more replies (Lavender). The key insight: if your personalization has nothing to do with the problem you solve, it's just an attention hack (Clay).
First name, company name, job title. Table stakes, no longer differentiating. ~5% lift.
Industry-specific pain points, trends, regulatory challenges. Scalable via micro-segmentation.
Most {{industry}} teams struggle with {{lead gen problem}}, which often leads to wasted effort.
Challenges specific to their role and seniority.
As Head of Sales, keeping pipeline steady is probably your biggest headache. Your RevOps team is small, so you're likely wearing multiple hats during scaling.
Specific, timely observations about that person connected to the problem you solve.
Noticed you're hiring 3 SDRs — sounds like you're scaling outbound fast. Most teams hit follow-up fatigue during onboarding.
| Signal | Where to find it | How to use it |
|---|---|---|
| Recent funding | Crunchbase, LinkedIn, press | "Congrats on Series B — scaling teams fast usually creates X challenge" |
| Job postings | LinkedIn Jobs, careers page | "Noticed you're hiring 3 SDRs — sounds like you're scaling outbound" |
| Tech stack | BuiltWith, Wappalyzer, HG Insights | "I see you're using HubSpot — most teams at your stage hit a ceiling with X" |
| LinkedIn activity | Posts, comments, job changes | "Really enjoyed your post about X" |
| Company news | Google News, press releases | "Congrats on acquiring X — integrating teams usually creates Y challenge" |
| Podcast/talks | Google, YouTube, podcasts | "Caught your talk at SaaStr on X — really insightful" |
| Website changes | Manual review | "Your new pricing page caught my eye — curious how it's converting" |
From "30 Minutes to President's Club":
Step 1: Build a research stack of top 10 buying signals — 5 company triggers, 5 person triggers. Stack-rank by relevance.
Step 2: Build a 3x3 template: (1) personalization attached to a problem, (2) problem you solve, (3) one-sentence solution + low-friction CTA.
Step 3: Create 5 "trigger templates" — pre-written personalization paragraphs for each trigger, with a smooth segue into the problem.
The personalization must logically connect to the problem. This creates 5 reusable triggers with the rest of the email constant. A top SDR writes a personalized email in under 3 minutes.
Tapping into what prospects are passionate about drives significantly higher response rates.
Trigger-event: "Congrats on the recent funding round — scaling the team from here is exciting, and I imagine [challenge] is top of mind."
Observation: "Your recent post about [topic] resonated — especially the part about [detail]. Got me thinking about how that applies to [challenge]."
Industry insight: "Most [role titles] I talk to spend [X hours/week] on [problem] — curious if that matches your experience at [Company]."
After writing any opening line, read from prospect's perspective: "So what? Why would I care?" If the answer is nothing, rewrite.
The subject line determines whether the email gets read. The data is counterintuitive: short, boring, internal-looking subject lines win decisively.
Subject lines that look like they came from a colleague, not a vendor, double open rates (Gong). Buyers mentally categorize before opening — if it looks like sales, it's filtered.
High-performing examples: "reply rates" · "trial delays" · "hiring ops" · "employee turnover" · "Q2 forecast" · "new patients" · "personalization issue" · "second page"
All-lowercase has highest open rates (Gong, 85M+ emails). Lowercase looks more personal/internal. For cold outreach specifically, lowercase beats title case.
Personalized subject lines boost opens 26–50%, but type matters:
Data conflicts: Belkins says questions perform well (46% open rate). Lavender says questions lower opens by 56%. Resolution: specific pain questions work ("Need help with {{challenge}}?"), generic questions fail ("Quick question?" / "Have 15 minutes?"). Default to statements.
| Anti-pattern | Impact |
|---|---|
| Salesy language ("increase," "boost," "ROI") | -17.9% opens |
| Urgency words ("ASAP," "urgent") | Below 36% opens |
| Excessive punctuation ("!!!" or "??") | -36% opens |
| Numbers and percentages | -46% opens |
| Emojis | Hurt B2B professionalism |
| Pitching product in subject | -57% replies |
| Empty/no subject line | +30% opens but -12% replies |
| Spam triggers ("free," "guarantee," "act now") | Deliverability risk |
Executives receive 300–400 emails daily, decide in seconds. They respond 23% more often than non-C-suite when emails pass their filter (6.4% reply rate).
What works: ultra-concise, human, understated. "{{companyInitiative}}" · "thank you" · "an update" · "a question" · reference to a specific project or trigger event.
Anything "salesy" is immediately rejected.
When the user wants to submit their product to startup, SaaS, AI, agent, MCP, no-code, or review directories for backlinks, domain rating, and discovery. Also use when the user mentions "directory submissions," "submit t
View source ↗You are an expert in directory-driven distribution for software products. Your goal is to help the user build a compounding backlink + discovery foundation by submitting to the right directories, in the right order, with the right positioning — and to make sure that foundation actually produces leads instead of vanity backlinks.
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.
Directory submissions are the foundation layer of distribution — never the whole strategy. They do three things well:
But directories alone will not generate meaningful leads. They exist to pass link equity into the pages that DO generate leads — template galleries, comparison pages, alternative pages, blog posts. Build the destination pages first, then submit to directories so the link equity has somewhere useful to land.
The full directory catalog lives in references/directory-list.md. The positioning variant library lives in references/positioning-variations.md. The submission tracker template lives in references/submission-tracker-template.csv.
Never submit to a directory until the landing page it will link to is live, indexed, and has:
- A single <h1> and sequential heading hierarchy — pages with clean hierarchy have 2.8× higher AI citation rates, and 87% of ChatGPT-cited pages use a single H1.
- A real pricing page (even "free while in beta" counts — most Tier 1 directories require one).
- Privacy policy + terms.
- Logo assets in PNG + SVG + square 1024×1024 + favicon.
- 5–8 real product screenshots at 1920×1080 (not marketing mockups).
- A 60–90 second demo video — products with video on Product Hunt get 2.7× more upvotes.
- FAQ schema markup (AI engines heavily weight FAQPage JSON-LD for answer extraction).
- Structured data: Organization, Product, SoftwareApplication.
Directories are the source of link equity. You need destinations that can convert the resulting traffic. Minimum destinations before submitting to anything:
- 3–5 competitor alternative pages (/alternatives/[competitor]) targeting "[competitor] alternative" keywords. Comparison/alternative pages convert at 5–15% vs 0.5–2% for generic content.
- 3–5 use-case pages (/for/[audience] or /use-cases/[use-case]).
- Template gallery with 20+ entries (if applicable — this was Typeform's largest SEO growth driver, generating 30K non-branded signups and $3M/year LTV).
- 1 "best of" blog post you wrote yourself about your own category, including honest coverage of competitors.
Never copy-paste the same description everywhere. AI engines penalize duplicate content, and each directory audience responds to different framing. See references/positioning-variations.md for the full variant library. Short version:
| Surface | Lead with | Why |
|---|---|---|
| Startup directories | Outcome | Audience is other founders. They care what it does. |
| SaaS directories | Alternative framing | People search "[competitor] alternative" — meet them there. |
| AI directories | AI-first architecture | TAAFT/Futurepedia audiences explicitly want AI tools. |
| Agent/MCP directories | Agent/MCP angle | Niche but high-intent. A real moat. |
| No-code directories | Ease + power | Audience values speed-to-build over depth. |
| Dev directories | Technical depth | Dev audiences reward technical substance. |
| B2B review sites | ROI + use case | Buyers want outcomes and case studies. |
Ask the user these 9 questions. If any are "no", they're not ready — help them build the missing piece first.
A "no" on any of 1–7 is a hard block. A "no" on 8–9 is a soft block: you can launch but will lose Tier 2 review value and Typeform-style compounding.
Full catalog in references/directory-list.md. Summary:
| Tier | When | Examples | Typical count |
|---|---|---|---|
| Tier 1 — Flagship launch | Launch week only | Product Hunt (anchor), BetaList, HN Show HN, Fazier, DevHunt | ~15 |
| Tier 2 — Startup/SaaS | Week 1 + rolling | AlternativeTo, SaaSHub, G2, Capterra, F6S, SourceForge, Slashdot | ~50 |
| Tier 3 — AI directories | Week 1–3 | TAAFT, Futurepedia, Toolify, Future Tools, aitools.inc, AIStage | ~40 |
| Tier 4 — Agent/MCP registries | Week 1–3 (if MCP) | Glama, APITracker, LF MCP Registry, AI Agents List | ~10 |
| Tier 5 — No-code directories | Week 1–3 (if no-code) | NoCodeFinder, No Code MBA, We Are No Code, MakerPad | ~8 |
| Tier 6 — "Best of" listicles | Rolling outreach | Cold outreach to DR 40+ blog posts | ~10 inclusions |
| Tier 7 — Integration marketplaces | When integrations ship | Zapier, HubSpot, Slack, Airtable, Notion | ~5 |
| Tier 8 — Profile & content platforms | Rolling | GitHub, WordPress.com, Substack, Dev.to, SlideShare, Behance | ~50 |
| Tier 9 — Local business directories | Rolling (if applicable) | Manta, Hotfrog, Locanto, MerchantCircle | ~20 |
| Tier 10 — Forums & communities | Rolling (participate first) | SitePoint, GrowthHackers, Warrior Forum, Designer News | ~13 |
| Tier 11 — Press release & article sites | Launch + milestones | PRLog, PR.com, EzineArticles, Feedspot | ~25 |
| Tier 12 — Social bookmarking | Rolling | Scoop.it, Diigo, Pearltrees | ~5 |
| Tier 13 — Niche vertical directories | When vertical fits | Justia (legal), Porch (home), LandBook (design), etc. | ~20 |
Triage rule: Only submit where the product is a genuine fit. Forcing a listing into the wrong category burns the first-submission advantage and gets rejected by moderators.
For each tier, prep a distinct description variant (pulled from references/positioning-variations.md):
- Tagline under 10 words
- Short description at 60 chars
- Long description at 150 words
- 5–8 category tags
- Logo assets
- Screenshots + demo video URL
- Founder story (2–3 sentences)
Critical: Don't copy-paste the same long description into every directory. Vary the opening sentence, the feature emphasis, and the audience framing per tier. AI engines cross-reference and down-weight duplicate content.
Set up the tracker spreadsheet (references/submission-tracker-template.csv). Work left-to-right through it. 2–3 hours per batch is realistic.
Per submission:
1. Copy the tier-appropriate positioning variant.
2. Fill in the form.
3. Upload assets.
4. Submit.
5. Log: date, URL, status, moderator notes.
6. Once live, verify the backlink exists and is dofollow: curl -sIL https://directory.com/your-listing | grep -i rel=. If absent, the link is dofollow.
Product Hunt is the single highest-leverage submission but also the most easily wasted. The 2026 PH algorithm weights comment quality more than upvote count — a post with 50 upvotes + 30 genuine comments ranks above one with 200 upvotes + 5 comments. 80% of failed launches fail because they launched without a warm audience OR asked for upvotes instead of feedback.
G2 and Capterra (now owned by G2 as of Feb 2026) listings are worthless without reviews. 10 reviews is the magic threshold for Grid appearance. Run the 10-in-30 protocol during launch month.
Directories are useless if the backlinks land on a generic homepage. Build these destination pages before submitting:
Competitor alternative pages convert at 5–15%, often hitting 15–30% for bottom-of-funnel queries. One page per top competitor:
/alternatives/[competitor-1]/alternatives/[competitor-2]/alternatives/[competitor-3]/alternatives/[competitor-4]Each page needs: honest feature comparison table, "when to choose X over us," "when to choose us over X," pricing comparison, 3–5 use-case examples, strong FAQ with schema.
Critical: Be honest. AI engines cross-reference competitor feature claims and de-rank pages that lie.
Every ICP gets a dedicated landing page:
- /for/[audience] — coaches, agencies, ecommerce, SaaS, consultants, etc.
- /use-cases/[use-case] — lead qualification, onboarding, product recommendations, etc.
Typeform's template library generated 30,000 non-branded organic signups and $3M/year LTV. The pattern:
- One indexable page per template at /templates/[slug].
- H1 with the keyword, 150+ word description, screenshot, "when to use this," "use this template" CTA.
- Related templates at the bottom of each page (internal linking = SEO compounding).
- 100 templates by day 30, 300 by day 90 is the realistic target.
Write honest roundups of your own category: /blog/best-[category]-tools-2026. Include yourself + 10 competitors with real reviews. These rank for category queries AND serve as canonical references AI engines cite.
Every integration = one landing page at /integrations/[partner]. Follows the Zapier playbook: Zapier gets ~2.6M monthly organic visits from programmatic integration pages (~15% of their total organic traffic).
In 2026, 30–50% of "research a tool" queries happen inside ChatGPT, Claude, Perplexity, or Google AI Overviews without ever touching a traditional search page. Directories matter here too — AI engines pull heavily from high-DR directories when generating answers. But the destination pages also need to be GEO-optimized.
FAQPage JSON-LD for answer extraction.Manually check monthly: ask ChatGPT, Claude, and Perplexity "what are the best [category] tools?" and log where the product appears. Free GEO tracking tools (GeoTracker, llmrefs) automate this.
Directories are one-shot. Community is ongoing. Both feed the same funnel.
90% of activity must be genuinely helpful; only 10% promotional. Violating this gets shadowbanned.
High-value subs (ranked):
- r/SideProject (200K+) — friendly to promo, launch announcements welcome.
- r/SaaS (300K+) — "Share Your SaaS" threads are explicit promo windows.
- r/startups (1.7M) — Feedback Friday thread.
- r/Entrepreneur (3.5M) — weekly promo thread.
- r/nocode, r/IndieHackers, r/alphaandbetausers — friendly.
- r/webdev, r/artificial, r/LocalLLaMA — strict, technical only.
What wins: real numbers (MRR, signups, churn), screenshots, "what I tried / what happened / what I'd do differently" structure, mini case studies with a clear lesson. What fails: hype, vague claims, "check out my new tool" posts, asking for upvotes.
80% of B2B social leads come from LinkedIn. Cadence: 3–5 posts/week — fewer loses momentum, more causes fatigue.
Content types ranked by 2026 engagement:
1. Personal stories with business lessons (1.5–2× avg engagement)
2. Original data / research (1.3–1.5×)
3. Contrarian industry takes (1.2–1.5×)
4. Document carousels with 8–12 slides (1.3–1.8×)
Build-in-public threads on architecture, revenue, decisions. Technical deep-dives get indexed by Google + Claude + Perplexity → indirect GEO.
Every substantial technical post = dofollow backlink + dev audience reach. Cross-post with canonical URL back to main blog.
Track weekly. If a number isn't moving, investigate — don't just submit more directories.
| Metric | Day 0 | Day 30 target | Day 90 target |
|---|---|---|---|
| Domain Rating (DR) | 0 | 20 | 30+ |
| Referring domains | 0 | 30 | 80+ |
| Indexed pages | — | 50 | 200+ |
| Organic clicks/day | 0 | 30 | 200+ |
| Directory listings live | 0 | 50 | 70+ |
| G2 reviews | 0 | 10 | 25 |
| Capterra reviews | 0 | 5 | 15 |
| AI citations (manual check) | 0 | 3 | 15+ |
| Signups from directory referrals | 0 | 50 | 300 |
| Signups from alt/use-case pages | 0 | 20 | 300 |
When the user asks for a directory plan, return:
references/positioning-variations.md)references/submission-tracker-template.csvKeep the plan actionable. Every item should be something the user can do today.
/alternatives/[tool] page patternCanonical list of directories organized by tier. DR values are approximate and drift over time — verify via Ahrefs or Moz before building a plan around them.
Column legend:
- DR — Domain Rating (Ahrefs). Higher = more link equity passed.
- Dofollow — Whether the backlink passes SEO value. Nofollow listings still matter for referral traffic and brand signals.
- Cost — Free unless noted.
Submit only during launch week. These are time-sensitive with limited re-submission windows.
| Directory | DR | Dofollow | Cost | Notes |
|---|---|---|---|---|
| Product Hunt | 91 | Yes | Free | The anchor event. Requires 3-week warm-up. 2026 algorithm weights comment quality over upvotes. Launch Tue/Wed/Thu at 12:01 AM PT. |
| Hacker News (Show HN) | 91 | Nofollow | Free | Only if you have a genuine technical angle. Post title format: "Show HN: [Product] — [hook]". Moderator death penalty for hype. |
| BetaList | 64 | Yes | Free (paid expedite ~$99) | Best for pre-launch waitlist building. Submission → 2–4 week queue unless expedited. |
| Launching Next | ~30 | Yes | Free | Editorial curation — needs a compelling story. |
| Fazier | ~30 | Yes | Free | Daily ranking with much lower competition than PH. Achievable #1. |
| Uneed | ~40 | Yes | Free | Curated, smaller audience, quality backlink. |
| Microlaunch | ~30 | Yes | Free | Month-long visibility vs one-day spike. |
| OpenHunts | ~25 | Yes | Free | Indie-maker friendly, reports 14%+ conversion rates. |
| DevHunt | ~35 | Yes | Free | Dev-focused. Best fit for developer tools and technical products. |
| PeerPush | ~25 | Yes | Free | Similar to Fazier. Low competition. |
| LaunchVault | ~20 | Yes | Free | Anti-VC positioning. Good for bootstrapped narrative. |
| What Launched Today | ~20 | Yes | Free | Guaranteed visibility on launch day regardless of votes. |
| Firsto | ~25 | Yes | Free tier | Sustained discovery, not one-day spike. |
| GetByte | ~20 | Yes | Free | Lightweight listing + promotional support. |
| Best of Web | ~30 | Yes | Free | Easy fast submission, free dofollow. |
| Tiny Launch | ~20 | Yes | Free | Lightweight, fast approval. |
| PitchWall | ~25 | Yes | Free | Indie-hacker friendly. |
Submit during launch week and continue rolling submissions thereafter.
| Directory | DR | Dofollow | Cost | Notes |
|---|---|---|---|---|
| AlternativeTo | 79 | Nofollow | Free | Massive SEO value despite nofollow. Submit as alternative to your top 4 competitors. |
| SaaSHub | 77 | Yes | Free | Ranks well for "[tool] alternatives" queries. High intent. |
| G2 | 92 | Yes | Free listing | 10 reviews required for Grid appearance. Paid badges start at $2,999/yr. |
| Capterra | 93 | Yes | Free listing | Owned by G2 (acquired Feb 2026). Reviews drive everything. |
| GetApp | 78 | Yes | Free | Auto-syncs from Capterra in some cases. Owned by G2. |
| SourceForge | 92 | Yes | Free | Legacy but still high DR. Trivial to list. |
| Slashdot | ~88 | Yes | Free | Legacy but high DR. Company profile submission. |
| Startup Stash | ~50 | Yes | Free | Curated, organized by startup need. |
| SideProjectors | ~35 | Yes | Free | Discovery + marketplace. Community-driven. |
| F6S | 65 | Yes | Free | Startup platform used by accelerators. |
| Stackshare | ~60 | Yes | Free | Dev-centric. Show your tech stack. |
| Resource.fyi | ~40 | Yes | Free | Curated for designers/devs/marketers. |
| Shipybara | ~30 | Yes | Free | Shows which companies use your tool. |
| TrustRadius | 72 | Yes | Free | Smaller but respected B2B review platform. |
| Crozdesk | ~55 | Yes | Free | Feeds into Gartner ecosystem. |
| Software Advice | 88 | Yes | Free | Gartner property. Auto-syncs with Capterra in some categories. |
| TheSaaSDirectory | 88 | Yes | Free | SaaS-specific directory. Good categorization. |
| Tech.co | 80 | Yes | Free | Startup/SaaS directory + media. |
| Taalk | 80 | Yes | Free | Startup directory. |
| Startup Fame | 77 | Yes | Free | Startup showcase directory. |
| Indie Hackers | 76 | Yes | Free | Build-in-public community + product directory. |
| Slant | 75 | Yes | Free | "What is the best..." recommendation platform. |
| Gust | 75 | Yes | Free | Startup/investor platform. Profile with links. |
| Inc42 | 75 | Yes | Free | Indian startup media + directory. |
| Wefunder | 76 | Yes | Free | Equity crowdfunding. Product profile with links. |
| Startups.com | 68 | Yes | Free | Startup community + resources. |
| IndieHustles | 66 | Yes | Free | Indie SaaS directory. |
| SaaSWorthy | 65 | Yes | Free | SaaS review/comparison site. |
| ToolsFine | 65 | Yes | Free | SaaS tool directory. |
| Bizcommunity | 65 | Yes | Free | Business news + directory. |
| StartUs | 62 | Yes | Free | Startup directory + insights. |
| Today Launches | 60 | Yes | Free | Daily launch directory. |
| StartupBuffer | 57 | Yes | Free | Startup promotion platform. |
| Feedough | 55 | Yes | Free | Startup resources + directory. |
| Indie Hacker Tools | 55 | Yes | Free | Tools for indie hackers. |
| Open Launch | 55 | Yes | Free | Product launch directory. |
| New SaaSly | 52 | Yes | Free | New SaaS product directory. |
| Business Software | 49 | Yes | Free | Business software directory. |
| Promote Project | 47 | Yes | Free | Project promotion directory. |
| FiveTaco | 47 | Yes | Free | SaaS tool directory. |
| Cuspera | 45 | Yes | Free | SaaS comparison platform. |
| BetaBound | 45 | Yes | Free | Beta testing community + directory. |
| Makerthrive | 45 | Yes | Free | Maker community + tools. |
| StartupTracker | 44 | Yes | Free | Startup tracking directory. |
| BusinessHunt | 43 | Yes | Free | Business product directory. |
| Launched.io | 40 | Yes | Free | Launch directory. |
| ProfitHunt | 40 | Yes | Free | Profitable startup directory. |
| 10words | 40 | Yes | Free | SaaS directory (10-word descriptions). |
| TrustMRR | 40 | Yes | Free | MRR-verified startup directory. |
| OpenClawDir | 35 | Yes | Free | Open directory. |
| Build Voyage | 33 | Yes | Free | Startup builder directory. |
| AlphaDigits | 32 | Yes | Free | SaaS directory. |
Relevant only for AI-native products. Submit during weeks 1–3.
| Directory | DR | Monthly Traffic | Notes |
|---|---|---|---|
| There's An AI For That (TAAFT) | 76 | 2M+ | Largest AI directory. Task-based search. Worth the effort to list well. |
| Futurepedia | 70 | 1M+ | 5,000+ tools, 54 categories. Matt Wolfe YouTube (2M+ subs) drives traffic. |
| Toolify.ai | 71 | 500K+ | 26K+ tools, 450+ categories. Tracks traffic trends. |
| Future Tools (futuretools.io) | 69 | 400K+ | Curated by Matt Wolfe. Smaller but influential. |
| AI Tools Neilpatel | 91 | n/a | Highest DR free AI directory. |
| Good AI Tools | 66 | n/a | Curated, quality over quantity. |
| NewTools.site | 51 | n/a | Dofollow backlink for every approved submission. |
| Directory | Est. DR | Notes |
|---|---|---|
| aitools.inc | ~66 | "10x your output" positioning. |
| AIStage | ~66 | Includes open source + news. |
| AItrendytools | ~69 | Comprehensive listing. |
| Grabon AI Directory | ~70 | High DR, broad audience. |
| TopAI.tools | ~60 | Task-based search similar to TAAFT. |
| Supertools | ~61 | Clean interface, good categorization. |
| AI Tools Directory (aitoolsdirectory.com) | ~55 | Curated; featured placement available. |
| AI Tools Love | ~25 | Comparison-focused. |
| AIChief | ~35 | Business-focused. |
| LogicBalls | ~40 | 3,500+ verified tools. |
| SaasAITools | ~30 | SaaS + AI crossover. |
| PoweredByAI | ~35 | Growing directory with newsletter reach. |
| TheAISurf | ~30 | Newer, actively promoting submissions. |
| Aixyz | ~30 | 1,500+ tools, smart filters. |
| AI Pedia Hub | ~40 | "Largest directory, updated daily." |
| Dofollow.Tools | ~30 | Explicitly free dofollow backlinks. |
| AIBacklinkList | ~25 | Aggregated list of 2500+ AI backlink opportunities. |
| AI Scout | ~25 | Emerging, less competition. |
| AiMatchPro | ~20 | Use-case search. |
| GPTForge | ~30 | Domain created 2025 — DR 88 from source list is implausible. Verify via Ahrefs. |
| AI Tools Guide | 77 | Curated AI tools directory. |
| AIToolly | 69 | AI tool discovery. |
| All The AI Tools | 66 | Comprehensive AI tool listing. |
| Aiforme.wiki | 66 | AI tool wiki/directory. |
| Noxilo | 66 | AI tools directory. |
| AI Generation | 55 | AI tools directory. |
| Every AI | 55 | AI tool aggregator. |
| BAI.tools | 53 | AI tools directory. |
| The Rundown Tools | 40 | AI newsletter's tool directory. |
| AI NavHub | 38 | AI navigation directory. |
| WhatTheAI | 35 | AI tools directory. |
| ToolAI | 31 | AI tools directory. |
| LLM Relevance | 30 | LLM-focused directory. |
Relevant only if the product exposes agent capabilities or MCP servers. These are a real moat for AI-native tools — traditional SaaS products cannot list here.
| Directory | Category | Notes |
|---|---|---|
| AI Agents List (aiagentslist.com) | Agents | Hosts the 593+ MCP server directory. |
| Glama.ai MCP servers | MCP | 20K+ security-graded MCP servers. A/B/C/F grades matter — optimize for a good grade. |
| APITracker MCP directory | MCP | 110+ servers, 90 official integrations. |
| Linux Foundation MCP Registry | MCP | Canonical registry (PR-based submission, low volume but high signal). Anthropic donated MCP to LF in Dec 2025. |
| AI Agent Store | Agents | Compare agents, platforms, frameworks. |
| AI Agents Base | Agents | All-in-one directory. |
| AI Agents Directory | Agents | Specialized, updated daily. |
| AI Agents Verse | Agents | Curated directory. |
| AgentHunter | Agents | "Discover the best AI agents." |
| Add AI Directory | Agents | Catalogs agents + tools. |
| AI Agents Live | Agents | Discovery + sharing. |
| AI Agents Marketplace | Agents | Organized by 300+ human role equivalents. |
Relevant for no-code platforms and builder tools.
| Directory | Est. DR | Notes |
|---|---|---|
| NoCodeFinder | ~45 | Accepts submissions. |
| No Code MBA Tools Directory | ~55 | Categorized by project type. |
| We Are No Code Tools Repository | ~40 | Curated. |
| NoCodeList | ~30 | — |
| NoCodeDevs | ~25 | — |
| NoCode.Tech | ~35 | — |
| MakerPad / Zapier | ~62 | Now owned by Zapier. No-code tool directory. |
| NoCodeFounders | ~45 | No-code community + forum. |
Not directories per se — these are blog posts on high-DR domains that you get included in via cold outreach. Often more valuable than directories because they combine a dofollow backlink with editorial trust + in-market buyer traffic + AI citation weight.
Search patterns to find opportunities:
- "best [category] tools" 2026
- "best [competitor] alternative"
- "top AI [category]"
- "[category] tools review"
Outreach template (short):
Hey [name], saw your post on [best X tools]. We launched [product] recently — thought it might be worth a mention. Happy to give you a free account + credits for readers. Here's a 60s demo: [link]. No worries if not a fit.
Target: 10 inclusions in 30 days. Each = dofollow backlink from DR 40–70 + referral traffic + AI citation fuel.
Only relevant once the product has integrations. These are the highest-DR backlinks available — worth engineering effort just to land them.
| Directory | DR | Notes |
|---|---|---|
| Zapier App Directory | 91 | Requires working Zapier integration. |
| HubSpot App Marketplace | 93 | Requires HubSpot app. |
| Slack App Directory | 89 | Requires Slack integration. |
| Airtable Marketplace | 82 | Requires Airtable integration. |
| Notion Integrations Gallery | 88 | Requires Notion integration. |
| Make (Integromat) | ~70 | Requires Make module. |
| Pipedream | ~70 | Requires Pipedream action. |
Create a profile or publish content on these high-DR platforms to earn a dofollow backlink. These are not traditional directories — they're content and identity platforms where your profile or published content links back to your site. Highest DR backlinks available without building integrations.
| Platform | DR | Category | Type | Notes |
|---|---|---|---|---|
| WordPress.com | 100 | Any | Blog | Create a free blog, link to main site in posts and profile. |
| Blogger | 100 | Any | Blog | Google property. Free blog with dofollow links. |
| Tumblr | 99 | Design | Blog | Highest DR blog platform. Project blog or microblog. |
| GitHub | 98 | Tech | Code host | Profile + repo README links. Every software product should have this. |
| SoundCloud | 96 | Music | Profile | Niche — relevant for audio/music products. |
| Weebly | 95 | Any | Blog | Free site builder with dofollow profile link. |
| SlideShare | 95 | Any | Content | Upload pitch decks, guides, presentations. |
| Flickr | 95 | Photography | Profile | Product screenshot galleries with profile link. |
| GitLab | 94 | Tech | Code host | Profile link. Mirror repos if open source. |
| eBay Stores | 94 | E-commerce | Profile | Niche — relevant for physical/digital goods. |
| Etsy | 93 | E-commerce | Profile | Niche — templates, digital downloads. |
| Substack | 93 | Tech | Newsletter | Publish product updates, thought leadership. High-intent readers. |
| Bitbucket | 93 | Tech | Code host | Profile link. Atlassian property. |
| Scribd | 93 | Any | Content | Upload whitepapers, guides, case studies. |
| Disqus | 93 | Professional | Profile | Profile with website link. Comment on industry blogs. |
| Behance | 93 | Design | Profile | Portfolio/project links. Best for design-adjacent products. |
| Pastebin | 93 | Tech | Code host | Code snippets with profile link. |
| Patreon | 93 | Creator | Profile | Creator page with product links. |
| Imgur | 93 | Any | Profile | Image hosting with profile link. |
| Dun & Bradstreet | 93 | B2B | Directory | Business credibility. Feeds AI training corpora. |
| Ghost.org | 92 | Any | Blog | Publish content with dofollow links. |
| Evernote | 92 | Any | Content | Public notebooks with links. |
| Issuu | 92 | Any | Content | Upload marketing PDFs, brochures, reports. |
| CodePen | 92 | Tech | Profile | Front-end demos and profile link. |
| Kaggle | 92 | AI | Profile | AI/data science community. Notebooks with links. |
| Houzz | 92 | Home | Profile | Niche — home/interior products. |
| LiveJournal | 91 | Any | Blog | Legacy but high DR. Blog with dofollow links. |
| Bandcamp | 91 | Music | Profile | Niche — audio products. |
| Dev.to | 90 | Tech | Blog | Technical articles with dofollow links. Cross-post with canonical URL. |
| Gravatar | 90 | Professional | Profile | Profile with website link. Quick setup. |
| Replit | 90 | Tech | Code host | Profile link. Interactive demos. |
| CodeProject | 90 | Tech | Blog | Technical articles for dev audience. |
| Jimdo | 89 | Any | Blog | Free site builder with profile link. |
| Calameo | 89 | Any | Content | Digital publishing platform. Upload PDFs. |
| Buy Me a Coffee | 88 | Creator | Profile | Creator page with product links. |
| ArtStation | 88 | Design | Profile | Portfolio for creative/design products. |
| 500px | 88 | Photography | Profile | Product imagery with profile link. |
| IndiaMART | 87 | B2B | Profile | Indian B2B marketplace. Niche but high DR. |
| Strikingly | 87 | Any | Blog | Free one-page site with backlink. |
| Hashnode | 85 | Tech | Blog | Dev blogging. Custom domain support. Dofollow links. |
| About.me | 85 | Professional | Profile | One-page profile. Quick dofollow backlink. |
| Mixcloud | 85 | Music | Profile | Niche — audio/podcast products. |
| 4Shared | 85 | Any | Content | File sharing with profile link. |
| HubPages | 84 | Any | Blog | Article publishing platform. |
| AppSumo | 84 | E-commerce | Marketplace | SaaS deals marketplace. Great for launch visibility + backlink. |
| TeachersPayTeachers | 84 | Education | Profile | Niche — education products. |
| AuthorStream | 70 | Any | Content | Presentation sharing. |
| Model Mayhem | 72 | Design | Profile | Niche — creative industry. |
| Penzu | 60 | Any | Blog | Online journal with profile link. |
| Crevado | 50 | Design | Profile | Portfolio platform. |
| MyFolio | 55 | Design | Profile | Portfolio platform. |
Relevant for products with a physical presence, local customer base, or business address. Also useful for any product wanting pure DR-building backlinks from established directories.
| Directory | DR | Category | Notes |
|---|---|---|---|
| Manta | 76 | Local business | US business directory. Free listing. |
| ActiveSearchResults | 74 | General | Search engine directory. |
| Hotfrog | 72 | Local business | International business directory. |
| Spoke | 70 | B2B | Business profile directory. |
| Locanto | 70 | General | Classifieds + business listings. International. |
| MerchantCircle | 68 | Local business | US small business directory. |
| Just Landed | 65 | Local business | International directory. |
| Showmelocal | 64 | Local business | US local search directory. |
| Cylex | 64 | Local business | International business directory. |
| Brownbook | 63 | Local business | Global business directory. |
| Tupalo | 62 | Local business | European business directory. |
| WebWiki | 60 | General | Website directory with reviews. |
| iBegin | 60 | Local business | US business directory. |
| CitySquares | 55 | Local business | US local business directory. |
| eLocal | 55 | Local business | US service provider directory. |
| 2FindLocal | 53 | Local business | US local directory. |
| Chamber of Commerce | 50 | Local business | Business directory + resources. |
| FindUsLocal | 50 | Local business | Local search directory. |
| ezlocal | 50 | Local business | US local business listings. |
| Yellow Pages Goes Green | 49 | Local business | Eco-friendly business directory. |
| Where To? | 46 | Local business | Local discovery directory. |
Create a profile and participate in relevant communities. Most give dofollow profile links. Value comes from both the backlink and referral traffic from genuine participation. Follow the 90/10 rule: 90% helpful, 10% promotional.
| Forum | DR | Category | Notes |
|---|---|---|---|
| Strava Clubs | 90 | Fitness | Niche — fitness/health products only. |
| Foursquare | 90 | Hospitality | Business listing with dofollow link. |
| SitePoint Forums | 89 | Tech | Web dev community. Genuine participation required. |
| Mumsnet Forums | 85 | Family | Niche — family/parenting products. Large UK audience. |
| Digital Point | 82 | Marketing | SEO/marketing forum. |
| WebmasterWorld | 77 | Marketing | SEO/webmaster community. High editorial standards. |
| BlackHatWorld | 77 | Marketing | SEO/marketing forum. Despite the name, has legitimate discussions. |
| GrowthHackers | 76 | Marketing | Growth marketing community. Dofollow articles + profile. |
| Warrior Forum | 73 | Marketing | Internet marketing community. |
| Apsense | 72 | Marketing | Business networking + marketing forum. |
| ActiveRain | 70 | Real estate | Niche — real estate industry. |
| Quibblo | 55 | General | Quiz/poll community with profile links. |
Publish articles or press releases to earn dofollow backlinks. Best for product launches, funding announcements, major feature releases. Some accept any topic, others are PR-specific.
| Site | DR | Type | Notes |
|---|---|---|---|
| EzineArticles | 80 | Article | Established article directory. Editorial review. |
| Feedspot | 80 | Blog directory | Blog discovery + RSS aggregation. Submit your blog. |
| Alltop | 73 | Blog directory | Guy Kawasaki's blog aggregator. |
| ArticlesBase | 70 | Article | Article publishing platform. |
| Blogarama | 64 | Blog directory | Blog directory with categories. |
| Sooper Articles | 60 | Article | Article submission site. |
| OnToplist | 60 | Blog directory | Blog ranking directory. |
| BlogEngage | 55 | Blog directory | Blog promotion community. |
| BizSugar | 55 | Business | Small business content sharing. |
| TechPluto | 50 | Marketing | Tech/marketing blog directory. |
| Site | DR | Notes |
|---|---|---|
| PRLog | 80 | Free press release distribution. Good reach. |
| PR.com | 77 | Free + paid press releases. Business directory too. |
| OpenPR | 72 | Free international press release distribution. |
| 1888 Press Release | 69 | Free press release site. |
| NewswireToday | 65 | Free press release distribution. |
| Online PR News | 62 | Free press release distribution. |
| PR Free | 62 | Free press release site. |
| Site | DR | Notes |
|---|---|---|
| SubmissionWebDirectory | 61 | General web directory. |
| Site Promotion Directory | 46 | Marketing-focused directory. |
| Semfirms | 45 | Marketing services directory. |
| CabinetM | 45 | Marketing technology directory. |
| Cold Email Kit | 44 | Email marketing directory. |
| Directory LDM Studio | 40 | General directory. |
| Quality Internet Directory | 39 | General web directory. |
| ProofStories | 32 | Marketing stories/case studies. |
Bookmark or curate content with dofollow links. Lower effort than publishing full articles. Most useful for building diverse backlink profile.
| Platform | DR | Notes |
|---|---|---|
| Scoop.it | 91 | Content curation platform. Create topic pages with links. |
| Diigo | 85 | Social bookmarking + annotation. Profile + bookmark links. |
| Pearltrees | 84 | Visual content curation. Organize links into collections. |
| BibSonomy | 70 | Academic bookmarking. Best for research/data products. |
| Folkd | 64 | Social bookmarking. Tag and share links. |
Industry-specific directories. Only submit if your product genuinely fits the vertical — forced listings get rejected and waste time.
| Directory | DR | Notes |
|---|---|---|
| Justia | 85 | Legal services directory. |
| Lawyers.com | 82 | Legal directory. |
| HG.org | 75 | Legal resources directory. |
| Directory | DR | Notes |
|---|---|---|
| Porch | 80 | Home services marketplace. |
| BuildZoom | 73 | Construction/contractor directory. |
| Tradify (FreeIndex) | 55 | UK trades directory. |
| iBuildNew | 45 | Australian home building directory. |
| Directory | DR | Notes |
|---|---|---|
| AllMenus | 76 | Restaurant directory. |
| Directory | DR | Notes |
|---|---|---|
| LandBook | 72 | Web design inspiration gallery. Submit landing pages. |
| Curated.design | 52 | Design inspiration directory. |
| Webdesign Inspiration | 45 | Website design showcase. |
| Directory | DR | Notes |
|---|---|---|
| Wellness.com | 60 | Health & wellness directory. |
| YogaTrail | 55 | Yoga/wellness directory. |
| MassageTherapy (AMBP) | 45 | Massage therapy directory. |
| Athlinks | 72 | Fitness/race results. Profile with links. |
| Fit Pro Directory | 40 | Fitness professional directory. |
| Directory | DR | Notes |
|---|---|---|
| Placester | 60 | Real estate marketing directory. |
| Directory | DR | Notes |
|---|---|---|
| Sulekha | 73 | Indian business directory. |
| EU-Business | 46 | European business directory. |
| Directory | DR | Notes |
|---|---|---|
| Evensi Events | 62 | Event discovery platform. |
| Directory | DR | Notes |
|---|---|---|
| (TeachersPayTeachers listed in Tier 8 — Profile Platforms) |
After any submission goes live, verify the backlink exists and is dofollow. You can:
rel="nofollow" or rel="ugc". If absent, the link is dofollow.curl -sIL https://directory.com/your-listing | grep -i linkRe-verify quarterly. Directories sometimes change all outbound links to nofollow without warning — if DR stops moving, check whether your biggest inbound links have silently flipped.
Directory audiences respond to different framings. Never copy-paste the same description everywhere — AI engines penalize duplicate content, and each directory type rewards a different opener.
Use this library to generate per-tier variants. Swap [product], [category], [competitors], [use-case], and [audience] with the real values.
| Tier | Lead sentence pattern | Why |
|---|---|---|
| Startup / launch | "[Product] is the easiest way to [outcome] for [audience]." | Founders scan for outcome clarity. |
| SaaS directory | "[Product] is the [differentiator] alternative to [competitors]." | Catches "[competitor] alternative" search intent. |
| AI directory | "[Product] uses [AI capability] to [outcome]." | TAAFT/Futurepedia audiences explicitly want AI. |
| Agent / MCP | "[Product] is an MCP-native / agent-native [category]." | Niche but high-intent. Ruling-out competitors. |
| No-code | "[Product] lets you build [output] without code." | Audience values speed, not technical depth. |
| Dev tool | "[Product] is a [technical category] with [differentiator]." | Devs want substance upfront. |
| B2B review | "[Product] helps [audience] [measurable business outcome]." | Reviewers want ROI language. |
Target: Product Hunt, BetaList, Fazier, Uneed, DevHunt, Microlaunch, OpenHunts, LaunchVault, Firsto, PitchWall
Tagline (under 10 words):
The [differentiator] way to [outcome] for [audience].
Short description (60 chars):
[Outcome-focused one-liner with product name]
Long description (150 words):
[Product] is the easiest way to [outcome] for [audience]. Built for teams who [pain point], [product] removes [friction] by [how].
Unlike [competitor category], [product] [key differentiator 1] and [key differentiator 2]. You can [action 1] in under [timeframe], [action 2] without [limitation], and [action 3] that would normally require [cost or technical skill].
We built [product] because [founder origin story in one sentence]. It's now used by [audience examples] to [use case examples].
Try it free at [url]. No credit card, no setup.
Tags: [product category], [audience type], [use case 1], [use case 2], [differentiator], [tech]
Target: AlternativeTo, SaaSHub, G2, Capterra, GetApp, SourceForge, Slashdot, Startup Stash, F6S
Tagline:
The [differentiator] alternative to [top competitors].
Long description:
[Product] is a [differentiator] alternative to [competitor 1], [competitor 2], and [competitor 3] — built for [audience] who need [gap the competitors don't fill].
Where [competitor 1] [limitation 1] and [competitor 2] [limitation 2], [product] [solves]. You get [feature 1], [feature 2], and [feature 3] in a single workspace, at [pricing relative to competitors].
Key features:
• [Feature 1] — [benefit]
• [Feature 2] — [benefit]
• [Feature 3] — [benefit]
• [Feature 4] — [benefit]
• [Integration 1], [Integration 2], [Integration 3] integrationsTrusted by [audience examples]. Start free at [url].
Tags: [competitor] alternative, [category], [audience], [differentiator], [top 3 features]
Target: TAAFT, Futurepedia, Toolify, Future Tools, aitools.inc, AIStage, LogicBalls, SaasAITools
Tagline:
AI-powered [category] for [audience].
Long description:
[Product] is an AI-powered [category] that [core AI capability]. It uses [specific models / techniques] to [outcome] — so [audience] can [job to be done] in a fraction of the time.
What makes it AI-first:
• [AI feature 1] — [what it does] using [model/approach]
• [AI feature 2] — [what it does]
• [AI feature 3] — [what it does]
• [AI feature 4] — [what it does][Product] is built on [tech stack] and supports [models/providers]. Use cases: [use case 1], [use case 2], [use case 3], [use case 4].
Free tier available. No API keys required to start.
Tags: AI [category], [AI capability 1], [AI capability 2], AI for [audience], [use case 1], [use case 2], [LLM provider], [differentiator]
Target: Glama, APITracker, Linux Foundation MCP Registry, AI Agents List, AI Agent Store, AgentHunter
Tagline:
MCP-native [category] for AI agents.
Long description:
[Product] is an MCP-native [category] that lets AI agents [capability]. It exposes [MCP server capabilities] via the Model Context Protocol, so agents in Claude, ChatGPT, Cursor, and any MCP-compatible client can [actions].
MCP capabilities:
• [Tool 1] — [what the agent can do]
• [Tool 2] — [what the agent can do]
• [Tool 3] — [what the agent can do]
• [Resource 1] — [context surfaced]
• [Prompt 1] — [pre-built prompt]Authentication: [auth method]. Transports: stdio, HTTP, SSE. Security: [security posture].
Installation: [one-line install command]. Docs: [docs URL].
Tags: MCP, MCP server, AI agent, agent [category], Claude integration, Model Context Protocol, [domain], [auth type]
Target: NoCodeFinder, No Code MBA Tools Directory, We Are No Code, NoCode.Tech
Tagline:
Build [output] without code.
Long description:
[Product] lets you build [output] without writing code. Drag, drop, or describe what you want and [product] handles the rest — [technical concept 1] and [technical concept 2] are automatic.
What you can build:
• [Example project 1] — built in [timeframe]
• [Example project 2] — built in [timeframe]
• [Example project 3] — built in [timeframe]No-code friendly features:
• [Visual feature 1]
• [Visual feature 2]
• [AI-assisted feature]
• [Pre-built templates]Start free. No credit card. Templates included.
Tags: no code, no-code [category], visual [tool], drag and drop, [output type], [audience type]
Target: DevHunt, Stackshare, GitHub, Dev.to, Hacker News Show HN
Tagline:
[Technical category] with [technical differentiator].
Long description:
[Product] is a [technical category] built on [tech stack]. It solves [technical problem] by [technical approach].
Architecture:
• [Component 1] — [tech used]
• [Component 2] — [tech used]
• [Component 3] — [tech used]Why it's different: [technical insight or novel approach]. We chose [trade-off] because [reason].
Open source: [yes/no/partial]. Self-hostable: [yes/no]. License: [license].
API: [REST / GraphQL / MCP / gRPC]. SDKs: [languages]. Docs: [url].
Tags: [language], [framework], [category], open source, API, [tech stack component], [architecture approach]
Target: G2, Capterra, TrustRadius, GetApp, Gartner Digital Markets, Crozdesk
Tagline:
[Business outcome] for [audience].
Long description:
[Product] helps [audience] [achieve measurable business outcome]. Teams use it to [use case 1], [use case 2], and [use case 3] — reducing [metric] by [percentage] and increasing [metric] by [percentage].
Key benefits:
• [Business benefit 1] with [how measured]
• [Business benefit 2] with [how measured]
• [Business benefit 3] with [how measured]Integrations: [enterprise integrations — HubSpot, Salesforce, Slack, etc.]
Security: [SOC 2 / GDPR / compliance posture]. Support: [support tier]. Pricing: [pricing range].
Trusted by [customer logos / company size]. Case studies at [url].
Tags: [business use case], [vertical], [audience role], [compliance], enterprise [category], [integration 1]
Pull 5–8 tags per submission from the relevant sections. Never repeat the exact same tag set across two directories in the same tier.
[category], [audience], [differentiator], [use case], AI, no-code, SaaS, [tech stack]
B2B, B2C, DTC, ecommerce, fintech, edtech, healthtech, martech, devtools, productivity, creator tools, agency tools
lead generation, lead qualification, customer onboarding, product recommendation, sales enablement, marketing automation, survey, assessment, calculator, quiz, intake form
AI agent, LLM, generative AI, conversational AI, RAG, MCP, agent framework, AI form, AI quiz, AI assistant, AI automation
open source, self-hosted, API-first, webhook, Zapier, no-code, low-code, embeddable, white-label, multi-tenant, SSO, SAML
DO:
- Vary the opening sentence across tiers
- Use real numbers and specific differentiators
- Match tone to audience (technical for devs, business for G2, excited for PH)
- Include a founder/origin angle in startup directories
- Lead with the AI-first angle in AI directories
DON'T:
- Copy-paste the same 150-word description everywhere
- Use vague claims ("blazing fast", "game-changing")
- Mention every feature — pick 3–5 per tier and rotate them
- Lie about competitor features (AI engines cross-reference and de-rank)
- Skip the tag list — it's how moderators route you to the right category
Directory,Tier,URL,Category,DR,Dofollow,Submission Date,Status,Live URL,Backlink Verified,Positioning Variant Used,Tags Used,Account Email,Notes Product Hunt,1,https://producthunt.com/posts/new,Launch,91,Yes,,Draft,,,Startup,,, Hacker News (Show HN),1,https://news.ycombinator.com/submit,Launch,91,No,,Draft,,,Dev,,, BetaList,1,https://betalist.com/submit,Launch,64,Yes,,Draft,,,Startup,,, Fazier,1,https://fazier.com/submit,Launch,30,Yes,,Draft,,,Startup,,, DevHunt,1,https://devhunt.org/submit,Launch,35,Yes,,Draft,,,Dev,,, Uneed,1,https://uneed.best/submit-a-tool,Launch,40,Yes,,Draft,,,Startup,,, Microlaunch,1,https://microlaunch.net/submit,Launch,30,Yes,,Draft,,,Startup,,, OpenHunts,1,https://openhunts.com/submit,Launch,25,Yes,,Draft,,,Startup,,, LaunchVault,1,https://launchvault.com/submit,Launch,20,Yes,,Draft,,,Startup,,, What Launched Today,1,https://whatlaunchedtoday.com,Launch,20,Yes,,Draft,,,Startup,,, Launching Next,1,https://launchingnext.com/submit,Launch,30,Yes,,Draft,,,Startup,,, PeerPush,1,https://peerpush.net/submit,Launch,25,Yes,,Draft,,,Startup,,, Firsto,1,https://firsto.co/submit,Launch,25,Yes,,Draft,,,Startup,,, GetByte,1,https://getbyte.co/submit,Launch,20,Yes,,Draft,,,Startup,,, Best of Web,1,https://bestofweb.io/submit,Launch,30,Yes,,Draft,,,Startup,,, Tiny Launch,1,https://tinylaunch.com/submit,Launch,20,Yes,,Draft,,,Startup,,, PitchWall,1,https://pitchwall.co/submit,Launch,25,Yes,,Draft,,,Startup,,, AlternativeTo,2,https://alternativeto.net/software/_/add/,SaaS,79,No,,Draft,,,SaaS,,, SaaSHub,2,https://saashub.com/submit,SaaS,77,Yes,,Draft,,,SaaS,,, G2,2,https://my.g2.com/sellers/welcome,SaaS,92,Yes,,Draft,,,B2B review,,, Capterra,2,https://www.capterra.com/vendors,SaaS,93,Yes,,Draft,,,B2B review,,, GetApp,2,https://www.getapp.com/vendors,SaaS,78,Yes,,Draft,,,B2B review,,, SourceForge,2,https://sourceforge.net/user/register,SaaS,92,Yes,,Draft,,,SaaS,,, Slashdot,2,https://slashdot.org/submission,SaaS,88,Yes,,Draft,,,SaaS,,, Startup Stash,2,https://startupstash.com/submit,SaaS,50,Yes,,Draft,,,Startup,,, SideProjectors,2,https://www.sideprojectors.com/project/new,SaaS,35,Yes,,Draft,,,Startup,,, F6S,2,https://www.f6s.com/company/create,SaaS,65,Yes,,Draft,,,Startup,,, Stackshare,2,https://stackshare.io/new-product,SaaS,60,Yes,,Draft,,,Dev,,, TrustRadius,2,https://www.trustradius.com/vendors,SaaS,72,Yes,,Draft,,,B2B review,,, Crozdesk,2,https://crozdesk.com/vendors,SaaS,55,Yes,,Draft,,,SaaS,,, There's An AI For That,3,https://theresanaiforthat.com/submit,AI,76,Yes,,Draft,,,AI,,, Futurepedia,3,https://www.futurepedia.io/submit-tool,AI,70,Yes,,Draft,,,AI,,, Toolify.ai,3,https://www.toolify.ai/submit,AI,71,Yes,,Draft,,,AI,,, Future Tools,3,https://www.futuretools.io/submit-a-tool,AI,69,Yes,,Draft,,,AI,,, AI Tools Neilpatel,3,https://neilpatel.com/ai-tools,AI,91,Yes,,Draft,,,AI,,, Good AI Tools,3,https://goodaitools.com/submit,AI,66,Yes,,Draft,,,AI,,, NewTools.site,3,https://newtools.site/submit,AI,51,Yes,,Draft,,,AI,,, aitools.inc,3,https://aitools.inc/submit,AI,66,Yes,,Draft,,,AI,,, AIStage,3,https://aistage.net/submit,AI,66,Yes,,Draft,,,AI,,, AItrendytools,3,https://www.aitrendytools.com/submit,AI,69,Yes,,Draft,,,AI,,, Grabon AI Directory,3,https://www.grabon.in/indulge/ai-tools/submit,AI,70,Yes,,Draft,,,AI,,, TopAI.tools,3,https://topai.tools/submit,AI,60,Yes,,Draft,,,AI,,, Supertools,3,https://supertools.therundown.ai/submit,AI,61,Yes,,Draft,,,AI,,, AI Tools Directory,3,https://aitoolsdirectory.com/submit,AI,55,Yes,,Draft,,,AI,,, LogicBalls,3,https://logicballs.com/submit,AI,40,Yes,,Draft,,,AI,,, SaasAITools,3,https://saasaitools.com/submit,AI,30,Yes,,Draft,,,AI,,, PoweredByAI,3,https://poweredbyai.app/submit,AI,35,Yes,,Draft,,,AI,,, TheAISurf,3,https://theaisurf.com/submit,AI,30,Yes,,Draft,,,AI,,, Aixyz,3,https://ai.xyz/submit,AI,30,Yes,,Draft,,,AI,,, AI Pedia Hub,3,https://aipediahub.com/submit,AI,40,Yes,,Draft,,,AI,,, Dofollow.Tools,3,https://dofollow.tools/submit,AI,30,Yes,,Draft,,,AI,,, AI Scout,3,https://aiscout.net/submit,AI,25,Yes,,Draft,,,AI,,, AiMatchPro,3,https://aimatchpro.ai/submit,AI,20,Yes,,Draft,,,AI,,, AIChief,3,https://aichief.com/submit,AI,35,Yes,,Draft,,,AI,,, AI Tools Love,3,https://aitools.love/submit,AI,25,Yes,,Draft,,,AI,,, AI Agents List,4,https://aiagentslist.com/submit,Agent,,Yes,,Draft,,,Agent,,, Glama.ai MCP,4,https://glama.ai/mcp/servers,MCP,,Yes,,Draft,,,MCP,,, APITracker MCP,4,https://apitracker.io/mcp-servers,MCP,,Yes,,Draft,,,MCP,,, Linux Foundation MCP Registry,4,https://github.com/modelcontextprotocol/registry,MCP,,Yes,,Draft,,,MCP,,, AI Agent Store,4,https://aiagentstore.ai/submit,Agent,,Yes,,Draft,,,Agent,,, AI Agents Base,4,https://aiagentsbase.com/submit,Agent,,Yes,,Draft,,,Agent,,, AI Agents Directory,4,https://aiagentsdirectory.com/submit,Agent,,Yes,,Draft,,,Agent,,, AgentHunter,4,https://agenthunter.com/submit,Agent,,Yes,,Draft,,,Agent,,, AI Agents Live,4,https://aiagents.live/submit,Agent,,Yes,,Draft,,,Agent,,, AI Agents Marketplace,4,https://aiagentsmarketplace.com/submit,Agent,,Yes,,Draft,,,Agent,,, NoCodeFinder,5,https://www.nocodefinder.com/submit,No-Code,45,Yes,,Draft,,,No-code,,, No Code MBA,5,https://www.nocode.mba/tools/submit,No-Code,55,Yes,,Draft,,,No-code,,, We Are No Code,5,https://www.wearenocode.com/submit,No-Code,40,Yes,,Draft,,,No-code,,, NoCodeList,5,https://nocodelist.co/submit,No-Code,30,Yes,,Draft,,,No-code,,, NoCodeDevs,5,https://www.nocodedevs.com/submit,No-Code,25,Yes,,Draft,,,No-code,,, NoCode.Tech,5,https://www.nocode.tech/submit,No-Code,35,Yes,,Draft,,,No-code,,, Zapier App Directory,7,https://zapier.com/developer,Integration,91,Yes,,Draft,,,Integration,,, HubSpot App Marketplace,7,https://ecosystem.hubspot.com/marketplace,Integration,93,Yes,,Draft,,,Integration,,, Slack App Directory,7,https://api.slack.com/apps,Integration,89,Yes,,Draft,,,Integration,,, Airtable Marketplace,7,https://airtable.com/marketplace,Integration,82,Yes,,Draft,,,Integration,,, Notion Integrations,7,https://www.notion.so/integrations,Integration,88,Yes,,Draft,,,Integration,,, Make (Integromat),7,https://www.make.com/en/partners,Integration,70,Yes,,Draft,,,Integration,,, Pipedream,7,https://pipedream.com/docs/components,Integration,70,Yes,,Draft,,,Integration,,, Software Advice,2,https://www.softwareadvice.com/vendors,SaaS,88,Yes,,Draft,,,B2B review,,, TheSaaSDirectory,2,https://thesaasdirectory.com,SaaS,88,Yes,,Draft,,,SaaS,,, Tech.co,2,https://tech.co,SaaS,80,Yes,,Draft,,,SaaS,,, Taalk,2,https://taalk.com,Startup,80,Yes,,Draft,,,Startup,,, Startup Fame,2,https://startupfa.me,Startup,77,Yes,,Draft,,,Startup,,, Indie Hackers,2,https://www.indiehackers.com,SaaS,76,Yes,,Draft,,,Startup,,, Slant,2,https://www.slant.co,SaaS,75,Yes,,Draft,,,SaaS,,, Gust,2,https://gust.com,Startup,75,Yes,,Draft,,,Startup,,, Inc42,2,https://inc42.com,Startup,75,Yes,,Draft,,,Startup,,, Wefunder,2,https://wefunder.com,Startup,76,Yes,,Draft,,,Startup,,, Startups.com,2,https://www.startups.com,Startup,68,Yes,,Draft,,,Startup,,, IndieHustles,2,https://www.indiehustles.com,SaaS,66,Yes,,Draft,,,SaaS,,, SaaSWorthy,2,https://www.saasworthy.com,SaaS,65,Yes,,Draft,,,SaaS,,, ToolsFine,2,https://toolsfine.com,SaaS,65,Yes,,Draft,,,SaaS,,, Bizcommunity,2,https://www.bizcommunity.com,B2B,65,Yes,,Draft,,,B2B,,, StartUs,2,https://startus.cc,Startup,62,Yes,,Draft,,,Startup,,, Today Launches,2,https://todaylaunches.com,Startup,60,Yes,,Draft,,,Startup,,, StartupBuffer,2,https://startupbuffer.com,Startup,57,Yes,,Draft,,,Startup,,, Feedough,2,https://www.feedough.com,Startup,55,Yes,,Draft,,,Startup,,, Indie Hacker Tools,2,https://www.indiehacker.tools,Startup,55,Yes,,Draft,,,Startup,,, Open Launch,2,https://open-launch.com,Startup,55,Yes,,Draft,,,Startup,,, New SaaSly,2,https://newsaasly.com,SaaS,52,Yes,,Draft,,,SaaS,,, Business Software,2,https://www.business-software.com,SaaS,49,Yes,,Draft,,,SaaS,,, Promote Project,2,https://www.promoteproject.com,Startup,47,Yes,,Draft,,,Startup,,, FiveTaco,2,https://fivetaco.com,SaaS,47,Yes,,Draft,,,SaaS,,, Cuspera,2,https://www.cuspera.com,SaaS,45,Yes,,Draft,,,SaaS,,, BetaBound,2,https://betabound.com,Startup,45,Yes,,Draft,,,Startup,,, Makerthrive,2,https://makerthrive.com,Startup,45,Yes,,Draft,,,Startup,,, StartupTracker,2,https://startuptracker.io,Startup,44,Yes,,Draft,,,Startup,,, BusinessHunt,2,https://businesshunt.co,SaaS,43,Yes,,Draft,,,SaaS,,, Launched.io,2,https://launched.io,Startup,40,Yes,,Draft,,,Startup,,, ProfitHunt,2,https://profithunt.co,Startup,40,Yes,,Draft,,,Startup,,, 10words,2,https://10words.io,SaaS,40,Yes,,Draft,,,SaaS,,, TrustMRR,2,https://trustmrr.com,Startup,40,Yes,,Draft,,,Startup,,, OpenClawDir,2,https://openclawdir.com,Tech,35,Yes,,Draft,,,Dev,,, Build Voyage,2,https://buildvoyage.com,Startup,33,Yes,,Draft,,,Startup,,, AlphaDigits,2,https://alphadigits.com,SaaS,32,Yes,,Draft,,,SaaS,,, GPTForge,3,https://gptforge.net,AI,30,Yes,,Draft,,,AI,,,Domain created 2025 — DR 88 from source list is implausible AI Tools Guide,3,https://aitoolsguide.com,AI,77,Yes,,Draft,,,AI,,, AIToolly,3,https://aitoolly.com,AI,69,Yes,,Draft,,,AI,,, All The AI Tools,3,https://alltheaitools.com,AI,66,Yes,,Draft,,,AI,,, Aiforme.wiki,3,https://aiforme.wiki,AI,66,Yes,,Draft,,,AI,,, Noxilo,3,https://noxilo.com,AI,66,Yes,,Draft,,,AI,,, AI Generation,3,https://www.theaigeneration.com,AI,55,Yes,,Draft,,,AI,,, Every AI,3,https://every-ai.com,AI,55,Yes,,Draft,,,AI,,, BAI.tools,3,https://bai.tools,AI,53,Yes,,Draft,,,AI,,, The Rundown Tools,3,https://www.rundown.ai/tools,AI,40,Yes,,Draft,,,AI,,, AI NavHub,3,https://ainavhub.com,AI,38,Yes,,Draft,,,AI,,, WhatTheAI,3,https://whattheai.tech,AI,35,Yes,,Draft,,,AI,,, ToolAI,3,https://toolai.io,AI,31,Yes,,Draft,,,AI,,, LLM Relevance,3,https://www.llmrelevance.com,AI,30,Yes,,Draft,,,AI,,, MakerPad / Zapier,5,https://www.makerpad.co,No-Code,62,Yes,,Draft,,,No-code,,, NoCodeFounders,5,https://www.nocodefounders.com,No-Code,45,Yes,,Draft,,,No-code,,, WordPress.com,8,https://wordpress.com,Blog,100,Yes,,Draft,,,Profile,,, Blogger,8,https://www.blogger.com,Blog,100,Yes,,Draft,,,Profile,,, Tumblr,8,https://www.tumblr.com,Blog,99,Yes,,Draft,,,Profile,,, GitHub,8,https://github.com,Tech,98,Yes,,Draft,,,Profile,,, SoundCloud,8,https://soundcloud.com,Music,96,Yes,,Draft,,,Profile,,, Weebly,8,https://www.weebly.com,Blog,95,Yes,,Draft,,,Profile,,, SlideShare,8,https://www.slideshare.net,Content,95,Yes,,Draft,,,Profile,,, Flickr,8,https://www.flickr.com,Photography,95,Yes,,Draft,,,Profile,,, GitLab,8,https://gitlab.com,Tech,94,Yes,,Draft,,,Profile,,, eBay Stores,8,https://www.ebay.com,E-commerce,94,Yes,,Draft,,,Profile,,, Etsy,8,https://www.etsy.com,E-commerce,93,Yes,,Draft,,,Profile,,, Substack,8,https://substack.com,Newsletter,93,Yes,,Draft,,,Profile,,, Bitbucket,8,https://bitbucket.org,Tech,93,Yes,,Draft,,,Profile,,, Scribd,8,https://www.scribd.com,Content,93,Yes,,Draft,,,Profile,,, Disqus,8,https://disqus.com,Professional,93,Yes,,Draft,,,Profile,,, Behance,8,https://www.behance.net,Design,93,Yes,,Draft,,,Profile,,, Pastebin,8,https://pastebin.com,Tech,93,Yes,,Draft,,,Profile,,, Patreon,8,https://www.patreon.com,Creator,93,Yes,,Draft,,,Profile,,, Imgur,8,https://imgur.com,Content,93,Yes,,Draft,,,Profile,,, Dun & Bradstreet,8,https://www.dnb.com,B2B,93,Yes,,Draft,,,Profile,,, Ghost.org,8,https://ghost.org,Blog,92,Yes,,Draft,,,Profile,,, Evernote,8,https://evernote.com,Content,92,Yes,,Draft,,,Profile,,, Issuu,8,https://issuu.com,Content,92,Yes,,Draft,,,Profile,,, CodePen,8,https://codepen.io,Tech,92,Yes,,Draft,,,Profile,,, Kaggle,8,https://www.kaggle.com,AI,92,Yes,,Draft,,,Profile,,, Houzz,8,https://www.houzz.com,Home,92,Yes,,Draft,,,Profile,,, LiveJournal,8,https://www.livejournal.com,Blog,91,Yes,,Draft,,,Profile,,, Bandcamp,8,https://bandcamp.com,Music,91,Yes,,Draft,,,Profile,,, Dev.to,8,https://dev.to,Tech,90,Yes,,Draft,,,Profile,,, Gravatar,8,https://gravatar.com,Professional,90,Yes,,Draft,,,Profile,,, Replit,8,https://replit.com,Tech,90,Yes,,Draft,,,Profile,,, CodeProject,8,https://www.codeproject.com,Tech,90,Yes,,Draft,,,Profile,,, Jimdo,8,https://www.jimdo.com,Blog,89,Yes,,Draft,,,Profile,,, Calameo,8,https://www.calameo.com,Content,89,Yes,,Draft,,,Profile,,, Buy Me a Coffee,8,https://www.buymeacoffee.com,Creator,88,Yes,,Draft,,,Profile,,, ArtStation,8,https://www.artstation.com,Design,88,Yes,,Draft,,,Profile,,, 500px,8,https://500px.com,Photography,88,Yes,,Draft,,,Profile,,, AppSumo,8,https://appsumo.com,E-commerce,84,Yes,,Draft,,,Profile,,, IndiaMART,8,https://www.indiamart.com,B2B,87,Yes,,Draft,,,Profile,,, Strikingly,8,https://www.strikingly.com,Blog,87,Yes,,Draft,,,Profile,,, Hashnode,8,https://hashnode.com,Tech,85,Yes,,Draft,,,Profile,,, About.me,8,https://about.me,Professional,85,Yes,,Draft,,,Profile,,, Mixcloud,8,https://www.mixcloud.com,Music,85,Yes,,Draft,,,Profile,,, 4Shared,8,https://www.4shared.com,Content,85,Yes,,Draft,,,Profile,,, HubPages,8,https://hubpages.com,Blog,84,Yes,,Draft,,,Profile,,, TeachersPayTeachers,8,https://www.teacherspayteachers.com,Education,84,Yes,,Draft,,,Profile,,, AuthorStream,8,https://www.authorstream.com,Content,70,Yes,,Draft,,,Profile,,, Model Mayhem,8,https://www.modelmayhem.com,Design,72,Yes,,Draft,,,Profile,,, Penzu,8,https://penzu.com,Blog,60,Yes,,Draft,,,Profile,,, Crevado,8,https://crevado.com,Design,50,Yes,,Draft,,,Profile,,, MyFolio,8,https://myfolio.com,Design,55,Yes,,Draft,,,Profile,,, Manta,9,https://www.manta.com,Local business,76,Yes,,Draft,,,Local,,, ActiveSearchResults,9,https://www.activesearchresults.com,Local business,74,Yes,,Draft,,,Local,,, Hotfrog,9,https://www.hotfrog.com,Local business,72,Yes,,Draft,,,Local,,, Spoke,9,https://www.spoke.com,Local business,70,Yes,,Draft,,,Local,,, Locanto,9,https://www.locanto.com,General,70,Yes,,Draft,,,Local,,, MerchantCircle,9,https://www.merchantcircle.com,Local business,68,Yes,,Draft,,,Local,,, Just Landed,9,https://www.justlanded.com,Local business,65,Yes,,Draft,,,Local,,, Showmelocal,9,https://www.showmelocal.com,Local business,64,Yes,,Draft,,,Local,,, Cylex,9,https://www.cylex.us.com,Local business,64,Yes,,Draft,,,Local,,, Brownbook,9,https://www.brownbook.net,Local business,63,Yes,,Draft,,,Local,,, Tupalo,9,https://tupalo.com,Local business,62,Yes,,Draft,,,Local,,, WebWiki,9,https://www.webwiki.com,Local business,60,Yes,,Draft,,,Local,,, iBegin,9,https://www.ibegin.com,Local business,60,Yes,,Draft,,,Local,,, CitySquares,9,https://citysquares.com,Local business,55,Yes,,Draft,,,Local,,, eLocal,9,https://elocal.com,Local business,55,Yes,,Draft,,,Local,,, 2FindLocal,9,https://www.2findlocal.com,Local business,53,Yes,,Draft,,,Local,,, Chamber of Commerce,9,https://www.chamberofcommerce.com,Local business,50,Yes,,Draft,,,Local,,, FindUsLocal,9,https://www.finduslocal.com,Local business,50,Yes,,Draft,,,Local,,, ezlocal,9,https://www.ezlocal.com,Local business,50,Yes,,Draft,,,Local,,, Yellow Pages Goes Green,9,https://www.yellowpagesgoesgreen.org,Local business,49,Yes,,Draft,,,Local,,, Where To?,9,https://www.where2go.com,Local business,46,Yes,,Draft,,,Local,,, SitePoint Forums,10,https://www.sitepoint.com/community,Tech,89,Yes,,Draft,,,Forum,,, Mumsnet Forums,10,https://www.mumsnet.com/Talk,Family,85,Yes,,Draft,,,Forum,,, Digital Point,10,https://forums.digitalpoint.com,Marketing,82,Yes,,Draft,,,Forum,,, WebmasterWorld,10,https://www.webmasterworld.com,Marketing,77,Yes,,Draft,,,Forum,,, BlackHatWorld,10,https://www.blackhatworld.com,Marketing,77,Yes,,Draft,,,Forum,,, GrowthHackers,10,https://growthhackers.com,Marketing,76,Yes,,Draft,,,Forum,,, Warrior Forum,10,https://www.warriorforum.com,Marketing,73,Yes,,Draft,,,Forum,,, Apsense,10,https://www.apsense.com,Marketing,72,Yes,,Draft,,,Forum,,, Strava Clubs,10,https://www.strava.com,Fitness,90,Yes,,Draft,,,Forum,,, Foursquare,10,https://business.foursquare.com,Hospitality,90,Yes,,Draft,,,Forum,,, ActiveRain,10,https://activerain.com,Real estate,70,Yes,,Draft,,,Forum,,, Quibblo,10,https://www.quibblo.com,General,55,Yes,,Draft,,,Forum,,, EzineArticles,11,https://ezinearticles.com,Article,80,Yes,,Draft,,,Article,,, PRLog,11,https://www.prlog.org,Press release,80,Yes,,Draft,,,PR,,, Feedspot,11,https://www.feedspot.com,Blog directory,80,Yes,,Draft,,,Article,,, PR.com,11,https://www.pr.com,Press release,77,Yes,,Draft,,,PR,,, Alltop,11,https://alltop.com,Blog directory,73,Yes,,Draft,,,Article,,, OpenPR,11,https://www.openpr.com,Press release,72,Yes,,Draft,,,PR,,, ArticlesBase,11,https://www.articlesbase.com,Article,70,Yes,,Draft,,,Article,,, 1888 Press Release,11,https://www.1888pressrelease.com,Press release,69,Yes,,Draft,,,PR,,, NewswireToday,11,https://www.newswiretoday.com,Press release,65,Yes,,Draft,,,PR,,, Blogarama,11,https://www.blogarama.com,Blog directory,64,Yes,,Draft,,,Article,,, Online PR News,11,https://www.onlineprnews.com,Press release,62,Yes,,Draft,,,PR,,, PR Free,11,https://www.pr-free.com,Press release,62,Yes,,Draft,,,PR,,, SubmissionWebDirectory,11,https://www.submissionwebdirectory.com,General,61,Yes,,Draft,,,Article,,, Sooper Articles,11,https://www.sooperarticles.com,Article,60,Yes,,Draft,,,Article,,, OnToplist,11,https://www.ontoplist.com,Blog directory,60,Yes,,Draft,,,Article,,, BlogEngage,11,https://www.blogengage.com,Blog directory,55,Yes,,Draft,,,Article,,, BizSugar,11,https://www.bizsugar.com,Business,55,Yes,,Draft,,,Article,,, TechPluto,11,https://www.techpluto.com,Marketing,50,Yes,,Draft,,,Article,,, Semfirms,11,https://www.semfirms.com,Marketing,45,Yes,,Draft,,,Article,,, CabinetM,11,https://www.cabinetm.com,Marketing,45,Yes,,Draft,,,Article,,, Cold Email Kit,11,https://coldemailkit.com,Marketing,44,Yes,,Draft,,,Article,,, Directory LDM Studio,11,https://www.directory.ldmstudio.com,General,40,Yes,,Draft,,,Article,,, Quality Internet Directory,11,https://www.qualityinternetdirectory.com,General,39,Yes,,Draft,,,Article,,, Site Promotion Directory,11,https://www.sitepromotiondirectory.com,Marketing,46,Yes,,Draft,,,Article,,, ProofStories,11,https://proofstories.io,Marketing,32,Yes,,Draft,,,Article,,, Scoop.it,12,https://www.scoop.it,Curation,91,Yes,,Draft,,,Bookmarking,,, Diigo,12,https://www.diigo.com,Bookmarking,85,Yes,,Draft,,,Bookmarking,,, Pearltrees,12,https://www.pearltrees.com,Bookmarking,84,Yes,,Draft,,,Bookmarking,,, BibSonomy,12,https://www.bibsonomy.org,Research,70,Yes,,Draft,,,Bookmarking,,, Folkd,12,https://www.folkd.com,Bookmarking,64,Yes,,Draft,,,Bookmarking,,, Justia,13,https://www.justia.com,Legal,85,Yes,,Draft,,,Niche,,, Lawyers.com,13,https://www.lawyers.com,Legal,82,Yes,,Draft,,,Niche,,, Porch,13,https://porch.com,Home,80,Yes,,Draft,,,Niche,,, AllMenus,13,https://www.allmenus.com,Hospitality,76,Yes,,Draft,,,Niche,,, HG.org,13,https://www.hg.org,Legal,75,Yes,,Draft,,,Niche,,, Sulekha,13,https://www.sulekha.com,B2B,73,Yes,,Draft,,,Niche,,, BuildZoom,13,https://www.buildzoom.com,Home,73,Yes,,Draft,,,Niche,,, LandBook,13,https://land-book.com,Design,72,Yes,,Draft,,,Niche,,, Athlinks,13,https://www.athlinks.com,Fitness,72,Yes,,Draft,,,Niche,,, Evensi Events,13,https://evensi.com,Events,62,Yes,,Draft,,,Niche,,, Wellness.com,13,https://www.wellness.com,Health,60,Yes,,Draft,,,Niche,,, Placester,13,https://placester.com,Real estate,60,Yes,,Draft,,,Niche,,, YogaTrail,13,https://www.yogatrail.com,Health,55,Yes,,Draft,,,Niche,,, Tradify (FreeIndex),13,https://www.freeindex.co.uk,Home,55,Yes,,Draft,,,Niche,,, Webdesign Inspiration,13,https://webdesign-inspiration.com,Design,45,Yes,,Draft,,,Niche,,, iBuildNew,13,https://www.ibuildnew.com.au,Home,45,Yes,,Draft,,,Niche,,, EU-Business,13,https://www.eu-business.com,B2B,46,Yes,,Draft,,,Niche,,, MassageTherapy (AMBP),13,https://www.massagetherapy.com,Health,45,Yes,,Draft,,,Niche,,, Fit Pro Directory,13,https://fitprofessionals.net,Fitness,40,Yes,,Draft,,,Niche,,, Curated.design,13,https://www.curated.design,Design,52,Yes,,Draft,,,Niche,,,
When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions "email sequence," "drip campaign," "nurture sequence," "onboar
View source ↗You are an expert in email marketing and automation. Your goal is to create email sequences that nurture relationships, drive action, and move people toward conversion.
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.
Before creating a sequence, understand:
Sequence Type
- Welcome/onboarding sequence
- Lead nurture sequence
- Re-engagement sequence
- Post-purchase sequence
- Event-based sequence
- Educational sequence
- Sales sequence
Audience Context
- Who are they?
- What triggered them into this sequence?
- What do they already know/believe?
- What's their current relationship with you?
Goals
- Primary conversion goal
- Relationship-building goals
- Segmentation goals
- What defines success?
Depends on:
- Sales cycle length
- Product complexity
- Relationship stage
Consider:
- B2B: Avoid weekends
- B2C: Test weekends
- Time zones: Send at local time
Patterns that work:
- Question: "Still struggling with X?"
- How-to: "How to [achieve outcome] in [timeframe]"
- Number: "3 ways to [benefit]"
- Direct: "[First name], your [thing] is ready"
- Story tease: "The mistake I made with [topic]"
Length: 5-7 emails over 12-14 days
Goal: Activate, build trust, convert
Key emails:
1. Welcome + deliver promised value (immediate)
2. Quick win (day 1-2)
3. Story/Why (day 3-4)
4. Social proof (day 5-6)
5. Overcome objection (day 7-8)
6. Core feature highlight (day 9-11)
7. Conversion (day 12-14)
Length: 6-8 emails over 2-3 weeks
Goal: Build trust, demonstrate expertise, convert
Key emails:
1. Deliver lead magnet + intro (immediate)
2. Expand on topic (day 2-3)
3. Problem deep-dive (day 4-5)
4. Solution framework (day 6-8)
5. Case study (day 9-11)
6. Differentiation (day 12-14)
7. Objection handler (day 15-18)
8. Direct offer (day 19-21)
Length: 3-4 emails over 2 weeks
Trigger: 30-60 days of inactivity
Goal: Win back or clean list
Key emails:
1. Check-in (genuine concern)
2. Value reminder (what's new)
3. Incentive (special offer)
4. Last chance (stay or unsubscribe)
Length: 5-7 emails over 14 days
Goal: Activate, drive to aha moment, upgrade
Note: Coordinate with in-app onboarding—email supports, doesn't duplicate
Key emails:
1. Welcome + first step (immediate)
2. Getting started help (day 1)
3. Feature highlight (day 2-3)
4. Success story (day 4-5)
5. Check-in (day 7)
6. Advanced tip (day 10-12)
7. Upgrade/expand (day 14+)
For detailed templates: See references/sequence-templates.md
For detailed email type reference: See references/email-types.md
For detailed copy, personalization, and testing guidelines: See references/copy-guidelines.md
Sequence Name: [Name]
Trigger: [What starts the sequence]
Goal: [Primary conversion goal]
Length: [Number of emails]
Timing: [Delay between emails]
Exit Conditions: [When they leave the sequence]
Email [#]: [Name/Purpose]
Send: [Timing]
Subject: [Subject line]
Preview: [Preview text]
Body: [Full copy]
CTA: [Button text] → [Link destination]
Segment/Conditions: [If applicable]
What to measure and benchmarks
For implementation, see the tools registry. Key email tools:
| Tool | Best For | MCP | Guide |
|---|---|---|---|
| Customer.io | Behavior-based automation | - | customer-io.md |
| Mailchimp | SMB email marketing | ✓ | mailchimp.md |
| Nitrosend | AI-native email (sequences via prompts) | ✓ | nitrosend.md |
| Resend | Developer-friendly transactional | ✓ | resend.md |
| SendGrid | Transactional email at scale | - | sendgrid.md |
| Kit | Creator/newsletter focused | - | kit.md |
A comprehensive guide to lifecycle and campaign emails. Use this as an audit checklist and implementation reference.
Trigger: User signs up (free or trial)
Goal: Activate user, drive to aha moment
Typical sequence: 5-7 emails over 14 days
Key metrics: Activation rate, feature adoption
Trigger: User converts to paid
Goal: Reinforce purchase decision, drive adoption, reduce early churn
Typical sequence: 3-5 emails over 14 days
Key point: Different from new user series—they've committed. Focus on reinforcement and expansion, not conversion.
Trigger: User hasn't completed critical setup step after X time
Goal: Nudge completion of high-value action
Format: Single email or 2-3 email mini-sequence
Example triggers:
- Hasn't connected integration after 48 hours
- Hasn't invited team member after 3 days
- Hasn't completed profile after 24 hours
Copy approach:
- Remind them what they started
- Explain why this step matters
- Make it easy (direct link to complete)
- Offer help if stuck
Trigger: Existing user invites teammate
Goal: Activate the invited user
Recipient: The person being invited
Copy approach:
- Personalize with inviter's name
- Explain what they're joining
- Single CTA to accept invite
- Social proof optional
Trigger: Free user shows engagement, or trial ending
Goal: Convert free to paid
Typical sequence: 3-5 emails
Trigger options:
- Time-based (trial day 10, 12, 14)
- Behavior-based (hit usage limit, used premium feature)
- Engagement-based (highly active free user)
Sequence structure:
- Value summary: What they've accomplished
- Feature comparison: What they're missing
- Social proof: Who else upgraded
- Urgency: Trial ending, limited offer
- Final: Last chance + easy path
Trigger: User approaching plan limits or using features available on higher tier
Goal: Upsell to next tier
Format: Single email or 2-3 email sequence
Trigger examples:
- 80% of seat limit reached
- 90% of storage/usage limit
- Tried to use higher-tier feature
- Power user behavior patterns
Copy approach:
- Acknowledge their growth (positive framing)
- Show what next tier unlocks
- Quantify value vs. cost
- Easy upgrade path
Trigger: Customer milestone (30/60/90 days, key achievement, support resolution)
Goal: Generate social proof on G2, Capterra, app stores
Format: Single email
Best timing:
- After positive support interaction
- After achieving measurable result
- After renewal
- NOT after billing issues or bugs
Copy approach:
- Thank them for being a customer
- Mention specific value/milestone if possible
- Explain why reviews matter (help others decide)
- Direct link to review platform
- Keep it short—this is an ask
Trigger: Signs of struggle (drop in usage, failed actions, error encounters)
Goal: Save at-risk user, improve experience
Format: Single email
Trigger examples:
- Usage dropped significantly week-over-week
- Multiple failed attempts at action
- Viewed help docs repeatedly
- Stuck at same onboarding step
Copy approach:
- Genuine concern tone
- Specific: "I noticed you..." (if data allows)
- Offer direct help (not just link to docs)
- Personal from support or CSM
- No sales pitch—pure help
Trigger: Time-based (weekly, monthly, quarterly)
Goal: Demonstrate value, drive engagement, reduce churn
Format: Single email, recurring
What to include:
- Key metrics/activity summary
- Comparison to previous period
- Achievements/milestones
- Suggestions for improvement
- Light CTA to explore more
Examples:
- "You saved X hours this month"
- "Your team completed X projects"
- "You're in the top X% of users"
Key point: Make them feel good and remind them of value delivered.
Trigger: Time-based (quarterly) or event-based (post-milestone)
Goal: Measure satisfaction, identify promoters and detractors
Format: Single email
Best practices:
- Keep it simple: Just the NPS question initially
- Follow-up form for "why" based on score
- Personal sender (CEO, founder, CSM)
- Tell them how you'll use feedback
Follow-up based on score:
- Promoters (9-10): Thank + ask for review/referral
- Passives (7-8): Ask what would make it a 10
- Detractors (0-6): Personal outreach to understand issues
Trigger: Customer milestone, promoter NPS score, or campaign
Goal: Generate referrals
Format: Single email or periodic reminders
Good timing:
- After positive NPS response
- After customer achieves result
- After renewal
- Seasonal campaigns
Copy approach:
- Remind them of their success
- Explain the referral offer clearly
- Make sharing easy (unique link)
- Show what's in it for them AND referee
Trigger: Monthly subscriber at renewal time or campaign
Goal: Convert monthly to annual (improve LTV, reduce churn)
Format: Single email or 2-email sequence
Value proposition:
- Calculate exact savings
- Additional benefits (if any)
- Lock in current price messaging
- Easy one-click switch
Best timing:
- Around monthly renewal date
- End of year / new year
- After 3-6 months of loyalty
- Price increase announcement (lock in old rate)
Trigger: Payment fails
Goal: Recover revenue, retain customer
Typical sequence: 3-4 emails over 7-14 days
Sequence structure:
- Email 1 (Day 0): Friendly notice, update payment link
- Email 2 (Day 3): Reminder, service may be interrupted
- Email 3 (Day 7): Urgent, account will be suspended
- Email 4 (Day 10-14): Final notice, what they'll lose
Copy approach:
- Assume it's an accident (card expired, etc.)
- Clear, direct, no guilt
- Single CTA to update payment
- Explain what happens if not resolved
Key metrics: Recovery rate, time to recovery
Trigger: User cancels subscription
Goal: Learn why, opportunity to save
Format: Single email (immediate)
Options:
- In-app survey at cancellation (better completion)
- Follow-up email if they skip in-app
- Personal outreach for high-value accounts
Questions to ask:
- Primary reason for cancelling
- What could we have done better
- Would anything change your mind
- Can we help with transition
Winback opportunity: Based on reason, offer targeted save (discount, pause, downgrade, training).
Trigger: X days before renewal (14 or 30 days typical)
Goal: No surprise charges, opportunity to expand
Format: Single email
What to include:
- Renewal date and amount
- What's included in renewal
- How to update payment/plan
- Changes to pricing/features (if any)
- Optional: Upsell opportunity
Required for: Annual subscriptions, high-value contracts
Trigger: Time-based
Goal: Drive engagement, demonstrate value
Format: Single email, recurring
Content by frequency:
- Daily: Notifications, quick stats (for high-engagement products)
- Weekly: Activity summary, highlights, suggestions
- Monthly: Comprehensive report, achievements, ROI if calculable
Structure:
- Key metrics at a glance
- Notable achievements
- Activity breakdown
- Suggestions / what to try next
- CTA to dive deeper
Personalization: Must be relevant to their actual usage. Empty reports are worse than no report.
Trigger: Specific achievement or event
Goal: Celebrate, drive continued engagement
Format: Single email per event
Milestone examples:
- First [action] completed
- 10th/100th [thing] created
- Goal achieved
- Team collaboration milestone
- Usage streak
Copy approach:
- Celebration tone
- Specific achievement
- Context (compared to others, compared to before)
- What's next / next milestone
Trigger: Trial ended without conversion
Goal: Convert or re-engage
Typical sequence: 3-4 emails over 30 days
Sequence structure:
- Email 1 (Day 1 post-expiry): Trial ended, here's what you're missing
- Email 2 (Day 7): What held you back? (gather feedback)
- Email 3 (Day 14): Incentive offer (discount, extended trial)
- Email 4 (Day 30): Final reach-out, door is open
Segmentation: Different approach based on trial engagement level:
- High engagement: Focus on removing friction to convert
- Low engagement: Offer fresh start, more onboarding help
- No engagement: Ask what happened, offer demo/call
Trigger: Time after cancellation (30, 60, 90 days)
Goal: Win back churned customers
Typical sequence: 2-3 emails spread over 90 days
Sequence structure:
- Email 1 (Day 30): What's new since you left
- Email 2 (Day 60): We've addressed [common reason]
- Email 3 (Day 90): Special offer to return
Copy approach:
- No guilt, no desperation
- Genuine updates and improvements
- Personalize based on cancellation reason if known
- Make return easy
Key point: They're more likely to return if their reason was addressed.
Trigger: Time-based (monthly)
Goal: Engagement, brand presence, content distribution
Format: Single email, recurring
Content mix:
- Product updates and tips
- Customer stories
- Educational content
- Company news
- Industry insights
Best practices:
- Consistent send day/time
- Scannable format
- Mix of content types
- One primary CTA focus
- Unsubscribe is okay—keeps list healthy
Trigger: Calendar events (Black Friday, New Year, etc.)
Goal: Drive conversions with timely offer
Format: Campaign burst (2-4 emails)
Common opportunities:
- New Year (fresh start, annual planning)
- End of fiscal year (budget spending)
- Black Friday / Cyber Monday
- Industry-specific seasons
- Back to school / work
Sequence structure:
- Announcement: Offer reveal
- Reminder: Midway through promotion
- Last chance: Final hours
Trigger: New feature release
Goal: Adoption, engagement, demonstrate momentum
Format: Single email per major release
What to include:
- What's new (clear and simple)
- Why it matters (benefit, not just feature)
- How to use it (direct link)
- Who asked for it (community acknowledgment)
Segmentation: Consider targeting based on relevance:
- Users who would benefit most
- Users who requested feature
- Power users first (for beta feel)
Trigger: Time-based (weekly or monthly)
Goal: Thought leadership, engagement, brand value
Format: Curated newsletter
Content:
- Curated news and links
- Your take / commentary
- What it means for readers
- How your product helps
Best for: B2B products where customers care about industry trends.
Trigger: Price change announcement
Goal: Transparent communication, minimize churn
Format: Single email (or sequence for major changes)
Timeline:
- Announce 30-60 days before change
- Reminder 14 days before
- Final notice 7 days before
Copy approach:
- Clear, direct, transparent
- Explain the why (value delivered, costs increased)
- Grandfather if possible (lock in old rate)
- Give options (annual lock-in, downgrade)
Important: Honesty and advance notice build trust even when price increases.
Use this to audit your current email program:
Detailed templates for common email sequences.
Email 1: Welcome (Immediate)
- Subject: Welcome to [Product] — here's your first step
- Deliver what was promised (lead magnet, access, etc.)
- Single next action
- Set expectations for future emails
Email 2: Quick Win (Day 1-2)
- Subject: Get your first [result] in 10 minutes
- Enable small success
- Build confidence
- Link to helpful resource
Email 3: Story/Why (Day 3-4)
- Subject: Why we built [Product]
- Origin story or mission
- Connect emotionally
- Show you understand their problem
Email 4: Social Proof (Day 5-6)
- Subject: How [Customer] achieved [Result]
- Case study or testimonial
- Relatable to their situation
- Soft CTA to explore
Email 5: Overcome Objection (Day 7-8)
- Subject: "I don't have time for X" — sound familiar?
- Address common hesitation
- Reframe the obstacle
- Show easy path forward
Email 6: Core Feature (Day 9-11)
- Subject: Have you tried [Feature] yet?
- Highlight underused capability
- Show clear benefit
- Direct CTA to try it
Email 7: Conversion (Day 12-14)
- Subject: Ready to [upgrade/buy/commit]?
- Summarize value
- Clear offer
- Urgency if appropriate
- Risk reversal (guarantee, trial)
Email 1: Deliver + Introduce (Immediate)
- Deliver the lead magnet
- Brief intro to who you are
- Preview what's coming
Email 2: Expand on Topic (Day 2-3)
- Related insight to lead magnet
- Establish expertise
- Light CTA to content
Email 3: Problem Deep-Dive (Day 4-5)
- Articulate their problem deeply
- Show you understand
- Hint at solution
Email 4: Solution Framework (Day 6-8)
- Your approach/methodology
- Educational, not salesy
- Builds toward your product
Email 5: Case Study (Day 9-11)
- Real results from real customer
- Specific and relatable
- Soft CTA
Email 6: Differentiation (Day 12-14)
- Why your approach is different
- Address alternatives
- Build preference
Email 7: Objection Handler (Day 15-18)
- Common concern addressed
- FAQ or myth-busting
- Reduce friction
Email 8: Direct Offer (Day 19-21)
- Clear pitch
- Strong value proposition
- Specific CTA
- Urgency if available
Email 1: Check-In (Day 30-60 of inactivity)
- Subject: Is everything okay, [Name]?
- Genuine concern
- Ask what happened
- Easy win to re-engage
Email 2: Value Reminder (Day 2-3 after)
- Subject: Remember when you [achieved X]?
- Remind of past value
- What's new since they left
- Quick CTA
Email 3: Incentive (Day 5-7 after)
- Subject: We miss you — here's something special
- Offer if appropriate
- Limited time
- Clear CTA
Email 4: Last Chance (Day 10-14 after)
- Subject: Should we stop emailing you?
- Honest and direct
- One-click to stay or go
- Clean the list if no response
Coordinate with in-app onboarding. Email supports, doesn't duplicate.
Email 1: Welcome + First Step (Immediate)
- Confirm signup
- One critical action
- Link directly to that action
Email 2: Getting Started Help (Day 1)
- If they haven't completed step 1
- Quick tip or video
- Support option
Email 3: Feature Highlight (Day 2-3)
- Key feature they should know
- Specific use case
- In-app link
Email 4: Success Story (Day 4-5)
- Customer who succeeded
- Relatable journey
- Motivational
Email 5: Check-In (Day 7)
- How's it going?
- Ask for feedback
- Offer help
Email 6: Advanced Tip (Day 10-12)
- Power feature
- For engaged users
- Level-up content
Email 7: Upgrade/Expand (Day 14+)
- For trial users: conversion push
- For free users: upgrade prompt
- For paid: expansion opportunity
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
View source ↗You are an expert at building qualified prospect lists across four motions: B2B SaaS, general B2B, local small businesses, and early-stage demand-signal discovery (finding your first customers from public pain signals). Your goal is to turn an ICP definition into a verified, scored, ready-to-outreach lead sheet — using the right data sources, qualification signals, and compliance posture for each motion.
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.
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 |
| Demand-signal | Early-stage: your first customers, design partners, or beta users | Evidence of the exact pain/demand/timing signal — a cited public source, not just firmographic fit | Forums, communities, reviews, GitHub issues, job posts, launch announcements (via last30days, social-fetch, scraping) |
If the user describes a hybrid motion (e.g., "SMBs that are also SaaS"), pick the dominant branch and pull in qualification signals from the other. If the user is early-stage and needs their first customers or design partners — evidence of demand over list coverage — use the Demand-signal branch.
For the branch-specific deep dives:
- SaaS → see references/saas-prospecting.md
- B2B → see references/b2b-prospecting.md
- Local SMB → see references/local-prospecting.md
- Demand-signal (find your first customers) → see references/demand-signals.md
Every prospecting engagement follows the same five phases. Tools and qualification signals change per branch; the phases don't.
Pull from product-marketing.md if available. Otherwise, gather:
Output the ICP as a one-paragraph statement plus a checklist of pass/fail criteria. Don't move to discovery without this.
Source 2–3× more candidates than the user wants in the final list — qualification will cull aggressively.
If the user's list quality bar is high, smaller is better. 25 verified leads beats 250 mostly-junk ones.
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. Don't ship leads with invalid or risky emails.
Apply this rubric for the SaaS, B2B, and Local SMB branches. The Demand-signal branch scores differently — 0–100 demand-fit, not Hot/Warm/Cold — see references/demand-signals.md.
| 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.
(SaaS / B2B / Local SMB. The Demand-signal branch ships an evidence report instead — see references/demand-signals.md.)
Default to a markdown table in chat. Switch to CSV when the list is >25 rows or the user explicitly asks for a file.
After the table, always add "Top outreach targets" — the top 3–5 hot leads with one sentence each on why this lead should be reached out to first.
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
These apply to every branch. Read first, every engagement.
For the full compliance reference (GDPR, CAN-SPAM, CASL, LinkedIn ToS, Google Maps ToS, Clay/Apollo/ZoomInfo use restrictions): see references/compliance.md.
If missing, ask once, then infer reasonable defaults and continue:
product-marketing.md if presentFull breakdown in 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.
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 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
SaaS / B2B columns:
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:
score,business,category,area,distance_km,website_status,website_url,social_urls,phone,email,source_urls,why_prospect,confidence,verified_date,notes
For implementation, see the tools registry. Key prospecting tools:
| Tool | Best For | MCP | Guide |
|---|---|---|---|
| Apollo | B2B / SaaS firmographic + contact discovery | - | apollo.md |
| Clay | Multi-source enrichment + waterfall | ✓ | clay.md |
| Clearbit | Email-to-company enrichment | - | clearbit.md |
| ZoomInfo | Enterprise B2B contact + intent | ✓ | zoominfo.md |
| Hunter | Email pattern + verification | - | hunter.md |
| Snov | Email finder + verifier | - | snov.md |
| Truelist | Email deliverability validation | - | truelist.md |
| Outreach | Sales engagement (post-list) | ✓ | outreach.md |
| RB2B | Visitor identification (warm intent) | - | rb2b.md |
| GitHub | Stargazers/forks/watchers as developer-intent signal | - | github.md |
| Firecrawl | Single-target site extraction (prospect's own website) | ✓ | firecrawl.md |
| Browserbase | Real-browser site research when rendering or interaction needed | ✓ | browserbase.md |
For when the user sells to non-SaaS B2B — services, agencies, manufacturers, mid-market and enterprise companies, professional services firms.
Recommended CSV columns:
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.
Prioritize for the top 3–5 hot leads:
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."
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.
CAN-SPAM regulates the cold email send, not the list build. But the list build matters because:
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.
The strictest applicable framework. Triggers when:
You have three credible options:
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
Consent — typically not feasible for cold outreach (you don't have consent before first contact)
Existing customer relationship — only applies to current customers, not prospects
Stricter than CAN-SPAM. Cold B2B outreach requires:
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.
Before shipping a list to the user (or downstream to cold-email):
Tool selection guide for prospecting across all three branches.
| 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 |
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
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
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
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
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, snov.md
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
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.
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.
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
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
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.
Both tools can technically point at any URL. The hard rule:
joescoffeeshop.com) that you found through manual discoverygoogle.com/maps, LinkedIn search results, Yelp listings, or any platform whose ToS prohibits bulk extractionDiscovery happens on platforms (manual browser-assisted research). Extraction happens on individual public business sites.
Integrations: see firecrawl.md, browserbase.md
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
When the user has no paid tools, lean on:
Slower than tooled-up workflows, but produces high-quality smaller lists if the user is willing to do the work.
A typical full-stack prospecting workflow:
Adapt this sequence based on which tools the user actually has.
The other three branches build a list from who fits (firmographics, technographics, proximity). This branch builds a list from who is already showing the pain — the early-stage motion where you have a product and a hunch but no customer base yet, and you need your first ten real conversations. You are not filtering a database; you are mining recent public discourse for people describing the exact problem you solve, then linking every prospect to the evidence.
Use this branch when the user is pre-product-market-fit, launching something new, or looking for design partners, beta users, or first customers rather than a scaled outbound list. It reuses the shared five phases and every compliance guardrail in SKILL.md; what changes is where you look, how you score, and what you ship.
Pattern credit: the framework here is re-expressed from the open-source first-customer-finder Codex skill (Kappaemme, MIT), extended with our live-recency tooling.
| List-building branches (SaaS / B2B / SMB) | Demand-signal discovery | |
|---|---|---|
| Starts from | A firmographic ICP | A described problem |
| Sources | Contact databases (Apollo, ZoomInfo, Clay) | Public discourse (forums, reviews, issues, posts) |
| Contact step | Enrich + verify email deliverability | None — reach them where they already posted |
| Wins on | Coverage at scale | 10 strong evidence-backed matches over a long list |
| Output | A scored lead sheet | An evidence report + manual outreach plan |
A prospect here without a cited pain, need, or timing signal is a speculative fit — it does not belong in the primary shortlist. Evidence is the entry ticket.
Define, specifically enough to reject weak matches:
Don't start broad collection until the brief is sharp. Pull from .agents/product-marketing.md if it exists.
Search several angles, not one query repeated. Adapt wording to how the audience actually talks (mine their vocabulary from organic content first — see the ad-creative hook-system's organic-language note for the same idea).
Use our live-recency edge. A generic skill relies on whatever a web search surfaces; you have better:
- last30days — Reddit, Hacker News, X, YouTube, and web signals from the last 30 days. This is the single highest-value tool for this branch: recency is the timing signal.
- social-fetch — pull the full content of a specific post/thread you find, normalized.
- scraping / Firecrawl / Browserbase — read the original public page (a forum thread, a GitHub issue, a review), never qualify from a search snippet alone.
- deep-research — for a multi-source sweep with adversarial verification when the wedge is broad.
- competitor-profiling / customer-research — competitor switching signals and review-mining for the pain language.
Forums and public community threads · public social posts and replies · product and app-marketplace reviews · GitHub issues and feature requests · public company pages, job posts, changelogs, launch announcements · "looking for a tool" posts and directories.
Avoid private groups, gated communities, data brokers, leaked datasets, and any source whose terms prohibit access — the same compliance guardrails as every other branch (see SKILL.md), including the no-sensitive-traits rule.
Business/professional context only. Qualify and reach out only where someone is posting in a professional or business capacity about a work problem (a founder in an indie-hackers thread, a developer in a GitHub issue, an ops lead in a subreddit for their role). Exclude personal-distress contexts entirely — health, financial hardship, addiction, grief, or any consumer support forum where people are venting personal problems, even if your product is tangentially relevant. When the motion is genuinely consumer (B2C), a public pain post is not on its own a lawful basis for cold outreach — reach people through the channel's own norms (reply publicly where replying is expected) and never DM a stranger off a personal post.
Quote minimally, paraphrase by default, and link every material pain or timing signal.
The list-building branches score Hot/Warm/Cold on ICP fit. This branch scores 0–100 on demand fit — how strongly the evidence says this specific prospect wants this specific thing now. Score each dimension 0–5:
| Dimension | Weight | What it measures |
|---|---|---|
| Pain strength | 25% | Directness, severity, repetition, and cost of the stated problem |
| Product fit | 25% | How directly your product solves the evidenced job |
| Timing | 20% | Freshness + a current trigger present |
| Public reachability | 15% | A natural, relevant public/professional contact path exists |
| Evidence quality | 15% | Specificity, source reliability, confidence the signal is really theirs |
score = pain/5*25 + fit/5*25 + timing/5*20 + reachability/5*15 + evidence/5*15
| Band | Meaning |
|---|---|
| 80–100 | Strong first-customer candidate |
| 65–79 | Promising — validate fast |
| 50–64 | Plausible but missing a material signal |
| Below 50 | Do not include in the primary shortlist |
An old explicit request can still count — but lower the timing score and label the date. A company that merely matches the industry with no evidenced trigger is not a qualified prospect here.
Displayed name (company/project/public professional) · source title + URL · visible publication date or "date unavailable" · source type · the concise pain/timing signal · observed evidence vs. inference (label which) · score breakdown · freshness warning when the signal is stale.
Recommend the most natural channel already associated with the source, and only where a reply is a normal part of that channel (reply in the public thread, respond via a public professional profile). Don't turn a public post into a private DM the poster didn't invite, and never contact someone off a personal-distress post. Draft one opener, under ~90 words, in this shape:
Never claim familiarity you don't have, never fabricate personal details, and never auto-send: no messages, connects, follows, comments, form submissions, or CRM records unless the user separately authorizes that action. This is the manual/gated posture from the marketing-loops guardrails.
Lead with the most actionable evidence, in this order:
For a shareable standalone HTML version of this report, the JSON→HTML generator pattern in ad-creative's creative-review-page.md is the model (escape every value; keep it self-contained).
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).
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) |
base_locationWhen 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.
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:
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 for setup details.
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 |
Chat table (≤15 rows):
| Score | Business | Category | Area | Distance | Website status | Website/Social | Phone | Why it's a prospect | Confidence |
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
Prioritize for the top 3 hot leads:
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."
The local branch is the most scraping-sensitive of the three motions. Specifically:
For when the user sells SaaS or digital services to other SaaS companies / digital businesses.
Beyond standard firmographics (industry, size, geography), SaaS prospects are qualified by:
Combine 2+ sources for cross-verification.
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.For dev-tool SaaS, GitHub is one of the highest-quality discovery channels:
node tools/clis/github-prospects.js stargazers <owner/repo> --enrich --with-company --format csvcompany set — these are the easiest to enrich downstreamTradeoffs: 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.
For each candidate, verify:
Recommended CSV columns:
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.
Prioritize for the top 3–5 hot leads:
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."
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
View source ↗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.
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):
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 | Too much text for SMS, costs add up | |
| Newsletter | 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 is the foundation, not an afterthought. A single TCPA class-action settlement runs $5M–$40M. The basics:
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.
For full compliance details, edge cases, opt-in copy templates, and STOP/HELP response templates: see references/compliance.md.
| 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.
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.
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.
The recipient gave you their phone number. Every send should pass: "would I be glad I got this text?" If no, don't send.
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.
Short links are mandatory (klvy.co, txt.attn.tv, branded short domain). Track UTM params on every link.
"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.
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
Note: Discount on first message trains customers to abandon. Reserve discount for Send 2 or 3.
For full sequence templates with copy and timing: see references/sequence-templates.md.
For complete copy patterns by sequence type with character counts: see references/sequence-templates.md.
| 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.
| 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 |
utm_source=sms&utm_medium=sms&utm_campaign=[campaign-name]Cross-reference ab-testing skill for proper test design and analytics for attribution setup.
When the user asks for an SMS plan, return:
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."
For implementation, see the tools registry. Key SMS tools:
| Tool | Best For | MCP | Guide |
|---|---|---|---|
| Klaviyo | E-commerce email + SMS combined | ✓ | klaviyo.md |
| Postscript | Shopify DTC SMS, deepest Shopify integration | - | postscript.md |
| Attentive | Mid-market+ DTC SMS, full-service | - | attentive.md |
| Twilio | Raw API for custom builds, transactional, dev-first | - | twilio.md |
| Plivo | Twilio alternative, lower per-send cost | - | plivo.md |
| AudienceTap | AI-forward DTC, on-pack QR opt-in | - | audiencetap.md |
| Brevo | EU email + SMS, SMB-friendly | ✓ | brevo.md |
| Customer.io | Behavior-based SMS automation | - | customer-io.md |
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.
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.
| 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 |
The opt-in flow must capture all of:
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.
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 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
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.
Brand registration
- Legal entity name, EIN, business type
- Trust score assigned (Standard or Verified)
- Higher trust = better throughput, lower fees
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
Phone number assignment to campaigns
| 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 |
Process time: 1–7 business days. Plan for this in launch timelines.
GDPR fines up to €20M or 4% of global revenue, whichever is higher.
Up to CAD $10M per violation. Enforced by the CRTC.
If you send across US + EU + Canada simultaneously:
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.
Best for: DTC ecom brands already using Klaviyo for email.
Best for: Shopify-native DTC brands wanting SMS-specific tooling and onboarding support.
Best for: Mid-market and enterprise DTC brands wanting full-service SMS.
Best for: Custom builds, transactional SMS, B2B SaaS embedding SMS into products, developers.
Best for: EU-based brands, email + SMS combo, SMB-friendly.
Best for: SMB, services businesses, simple campaign blasts, low-volume.
Best for: Custom SMS builds where per-send cost matters; Twilio-style API at a lower price point.
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.
Best for: B2B SaaS, behavior-based automation, multi-channel orchestration (email + SMS + push).
| 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 |
Whatever you pick, confirm your platform handles:
All major platforms above handle these. Twilio does the lowest-level work and pushes more responsibility onto you.
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.
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.
From [Brand]: Don't forget your code WELCOME10 — expires in 48hrs. Top picks: [short.link]
~108 chars / 1 segment.
From [Brand]: Last chance for 10% off with WELCOME10. Expires tonight at midnight: [short.link]
~107 chars / 1 segment.
From [Brand]: Hey [FirstName], you left something behind! Your cart's here: [short.link]
~95 chars / 1 segment.
From [Brand]: Items in your cart are selling fast. Reserved for you for 24hrs: [short.link]
~98 chars / 1 segment.
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.
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.
From [Brand]: Order #12345 confirmed! We'll text shipping updates here. Track: [short.link]
~95 chars / 1 segment.
From [Brand]: Your order's on the way. Estimated delivery: [date]. Track: [short.link]
~92 chars / 1 segment.
From [Brand]: Your order should arrive today! Questions? Reply or visit [short.link]
~88 chars / 1 segment.
From [Brand]: How are you liking your [product]? Share a review for 15% off next order: [short.link]
~108 chars / 1 segment.
From [Brand]: Goes great with your [product]: [related-item]. 10% off bundle: [short.link]
~99 chars / 1 segment.
From [Brand]: [FirstName], we miss you! Picks we think you'll love: [short.link]
~84 chars / 1 segment.
From [Brand]: Come back for 15% off your next order: COMEBACK15. Expires in 7 days: [short.link]
~106 chars / 1 segment.
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).
From [Brand]: 24-HOUR FLASH: 25% off everything with FLASH25. Ends midnight: [short.link]
~94 chars / 1 segment.
From [Brand]: New drop just landed: [product-name]. Limited stock, members get early access: [short.link]
~115 chars / 1 segment.
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.
[Brand]: Order #12345 confirmed. Total $XX.XX. Track at [short.link]. Reply HELP for help.
[Brand]: Your order #12345 shipped! Track: [short.link]. ETA [date].
[Brand]: Order #12345 delivered. Enjoy! Issues? Reply or [support-link].
[Brand] verification code: 123456. Expires in 10 min. Do not share.
[Brand]: Sign-in from new device in [location]. Wasn't you? Secure: [short.link]
For SMS subscribers who haven't engaged with any send in 60+ days.
From [Brand]: We've missed you, [FirstName]! Here's what's new: [short.link]
~80 chars / 1 segment.
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.
For products with predictable usage cycles (skincare, supplements, coffee, pet food).
From [Brand]: Running low on [product]? Reorder in one tap: [short.link]
~73 chars / 1 segment.
From [Brand]: Don't run out! 10% off your reorder of [product]: REFILL10 [short.link]
~92 chars / 1 segment.
Higher frequency, exclusive offers, early access — different cadence rules apply but quiet hours and STOP still required.
From [Brand]: VIPs get the new drop 24hrs early. Yours now: [short.link]
~72 chars / 1 segment.
From [Brand]: You've reached Gold status! Your perks: 15% off + free shipping. [short.link]
~95 chars / 1 segment.
When the user wants to plan, design, or implement an A/B test or experiment, or build a growth experimentation program. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant
View source ↗You are an expert in experimentation and A/B testing. Your goal is to help design tests that produce statistically valid, actionable results.
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.
Before designing a test, understand:
Because [observation/data],
we believe [change]
will cause [expected outcome]
for [audience].
We'll know this is true when [metrics].
Weak: "Changing the button color might increase clicks."
Strong: "Because users report difficulty finding the CTA (per heatmaps and feedback), we believe making the button larger and using contrasting color will increase CTA clicks by 15%+ for new visitors. We'll measure click-through rate from page view to signup start."
| Type | Description | Traffic Needed |
|---|---|---|
| A/B | Two versions, single change | Moderate |
| A/B/n | Multiple variants | Higher |
| MVT | Multiple changes in combinations | Very high |
| Split URL | Different URLs for variants | Moderate |
| Baseline | 10% Lift | 20% Lift | 50% Lift |
|---|---|---|---|
| 1% | 150k/variant | 39k/variant | 6k/variant |
| 3% | 47k/variant | 12k/variant | 2k/variant |
| 5% | 27k/variant | 7k/variant | 1.2k/variant |
| 10% | 12k/variant | 3k/variant | 550/variant |
Calculators:
- Evan Miller's
- Optimizely's
For detailed sample size tables and duration calculations: See references/sample-size-guide.md
| Category | Examples |
|---|---|
| Headlines/Copy | Message angle, value prop, specificity, tone |
| Visual Design | Layout, color, images, hierarchy |
| CTA | Button copy, size, placement, number |
| Content | Information included, order, amount, social proof |
| Approach | Split | When to Use |
|---|---|---|
| Standard | 50/50 | Default for A/B |
| Conservative | 90/10, 80/20 | Limit risk of bad variant |
| Ramping | Start small, increase | Technical risk mitigation |
Considerations:
- Consistency: Users see same variant on return
- Balanced exposure across time of day/week
DO:
- Monitor for technical issues
- Check segment quality
- Document external factors
Avoid:
- Peek at results and stop early
- Make changes to variants
- Add traffic from new sources
Looking at results before reaching sample size and stopping early leads to false positives and wrong decisions. Pre-commit to sample size and trust the process.
| Result | Conclusion |
|---|---|
| Significant winner | Implement variant |
| Significant loser | Keep control, learn why |
| No significant difference | Need more traffic or bolder test |
| Mixed signals | Dig deeper, maybe segment |
Document every test with:
- Hypothesis
- Variants (with screenshots)
- Results (sample, metrics, significance)
- Decision and learnings
For templates: See references/test-templates.md
Individual tests are valuable. A continuous experimentation program is a compounding asset. This section covers how to run experiments as an ongoing growth engine, not just one-off tests.
1. Generate hypotheses (from data, research, competitors, customer feedback)
2. Prioritize with ICE scoring
3. Design and run the test
4. Analyze results with statistical rigor
5. Promote winners to a playbook
6. Generate new hypotheses from learnings
→ Repeat
Feed your experiment backlog from multiple sources:
| Source | What to Look For |
|---|---|
| Analytics | Drop-off points, low-converting pages, underperforming segments |
| Customer research | Pain points, confusion, unmet expectations |
| Competitor analysis | Features, messaging, or UX patterns they use that you don't |
| Support tickets | Recurring questions or complaints about conversion flows |
| Heatmaps/recordings | Where users hesitate, rage-click, or abandon |
| Past experiments | "Significant loser" tests often reveal new angles to try |
Score each hypothesis 1-10 on three dimensions:
| Dimension | Question |
|---|---|
| Impact | If this works, how much will it move the primary metric? |
| Confidence | How sure are we this will work? (Based on data, not gut.) |
| Ease | How fast and cheap can we ship and measure this? |
ICE Score = (Impact + Confidence + Ease) / 3
Run highest-scoring experiments first. Re-score monthly as context changes.
Track your experimentation rate as a leading indicator of growth:
| Metric | Target |
|---|---|
| Experiments launched per month | 4-8 for most teams |
| Win rate | 20-30% is common for mature programs (sustained higher rates may indicate conservative hypotheses) |
| Average test duration | 2-4 weeks |
| Backlog depth | 20+ hypotheses queued |
| Cumulative lift | Compound gains from all winners |
When a test wins, don't just implement it — document the pattern:
## [Experiment Name]
**Date**: [date]
**Hypothesis**: [the hypothesis]
**Sample size**: [n per variant]
**Result**: [winner/loser/inconclusive] — [primary metric] changed by [X%] (95% CI: [range], p=[value])
**Guardrails**: [any guardrail metrics and their outcomes]
**Segment deltas**: [notable differences by device, segment, or cohort]
**Why it worked/failed**: [analysis]
**Pattern**: [the reusable insight — e.g., "social proof near pricing CTAs increases plan selection"]
**Apply to**: [other pages/flows where this pattern might work]
**Status**: [implemented / parked / needs follow-up test]
Over time, your playbook becomes a library of proven growth patterns specific to your product and audience.
Weekly (30 min): Review running experiments for technical issues and guardrail metrics. Don't call winners early — but do stop tests where guardrails are significantly negative.
Bi-weekly: Conclude completed experiments. Analyze results, update playbook, launch next experiment from backlog.
Monthly (1 hour): Review experiment velocity, win rate, cumulative lift. Replenish hypothesis backlog. Re-prioritize with ICE.
Quarterly: Audit the playbook. Which patterns have been applied broadly? Which winning patterns haven't been scaled yet? What areas of the funnel are under-tested?
Reference for calculating sample sizes and test duration.
Baseline conversion rate: If your page converts at 5%, that's your baseline.
MDE (Minimum Detectable Effect): The smallest improvement you care about detecting. Set this based on:
- Business impact (is a 5% lift meaningful?)
- Implementation cost (worth the effort?)
- Realistic expectations (what have past tests shown?)
Statistical significance (95%): Means there's less than 5% chance the observed difference is due to random chance.
Statistical power (80%): Means if there's a real effect of size MDE, you have 80% chance of detecting it.
| Lift to Detect | Sample per Variant | Total Sample |
|---|---|---|
| 5% (1% → 1.05%) | 1,500,000 | 3,000,000 |
| 10% (1% → 1.1%) | 380,000 | 760,000 |
| 20% (1% → 1.2%) | 97,000 | 194,000 |
| 50% (1% → 1.5%) | 16,000 | 32,000 |
| 100% (1% → 2%) | 4,200 | 8,400 |
| Lift to Detect | Sample per Variant | Total Sample |
|---|---|---|
| 5% (3% → 3.15%) | 480,000 | 960,000 |
| 10% (3% → 3.3%) | 120,000 | 240,000 |
| 20% (3% → 3.6%) | 31,000 | 62,000 |
| 50% (3% → 4.5%) | 5,200 | 10,400 |
| 100% (3% → 6%) | 1,400 | 2,800 |
| Lift to Detect | Sample per Variant | Total Sample |
|---|---|---|
| 5% (5% → 5.25%) | 280,000 | 560,000 |
| 10% (5% → 5.5%) | 72,000 | 144,000 |
| 20% (5% → 6%) | 18,000 | 36,000 |
| 50% (5% → 7.5%) | 3,100 | 6,200 |
| 100% (5% → 10%) | 810 | 1,620 |
| Lift to Detect | Sample per Variant | Total Sample |
|---|---|---|
| 5% (10% → 10.5%) | 130,000 | 260,000 |
| 10% (10% → 11%) | 34,000 | 68,000 |
| 20% (10% → 12%) | 8,700 | 17,400 |
| 50% (10% → 15%) | 1,500 | 3,000 |
| 100% (10% → 20%) | 400 | 800 |
| Lift to Detect | Sample per Variant | Total Sample |
|---|---|---|
| 5% (20% → 21%) | 60,000 | 120,000 |
| 10% (20% → 22%) | 16,000 | 32,000 |
| 20% (20% → 24%) | 4,000 | 8,000 |
| 50% (20% → 30%) | 700 | 1,400 |
| 100% (20% → 40%) | 200 | 400 |
Duration (days) = (Sample per variant × Number of variants) / (Daily traffic × % exposed)
Scenario 1: High-traffic page
- Need: 10,000 per variant (2 variants = 20,000 total)
- Daily traffic: 5,000 visitors
- 100% exposed to test
- Duration: 20,000 / 5,000 = 4 days
Scenario 2: Medium-traffic page
- Need: 30,000 per variant (60,000 total)
- Daily traffic: 2,000 visitors
- 100% exposed
- Duration: 60,000 / 2,000 = 30 days
Scenario 3: Low-traffic with partial exposure
- Need: 15,000 per variant (30,000 total)
- Daily traffic: 500 visitors
- 50% exposed to test
- Effective daily: 250
- Duration: 30,000 / 250 = 120 days (too long!)
Even with sufficient sample size, run tests for at least:
- 1 full week: To capture day-of-week variation
- 2 business cycles: If B2B (weekday vs. weekend patterns)
- Through paydays: If e-commerce (beginning/end of month)
Avoid running tests longer than 4-8 weeks:
- Novelty effects wear off
- External factors intervene
- Opportunity cost of other tests
Evan Miller's Calculator
https://www.evanmiller.org/ab-testing/sample-size.html
- Simple interface
- Bookmark-worthy
Optimizely's Calculator
https://www.optimizely.com/sample-size-calculator/
- Business-friendly language
- Duration estimates
AB Test Guide Calculator
https://www.abtestguide.com/calc/
- Includes Bayesian option
- Multiple test types
VWO Duration Calculator
https://vwo.com/tools/ab-test-duration-calculator/
- Duration-focused
- Good for planning
With more than 2 variants (A/B/n tests), you need more sample:
| Variants | Multiplier |
|---|---|
| 2 (A/B) | 1x |
| 3 (A/B/C) | ~1.5x |
| 4 (A/B/C/D) | ~2x |
| 5+ | Consider reducing variants |
Why? More comparisons increase chance of false positives. You're comparing:
- A vs B
- A vs C
- B vs C (sometimes)
Apply Bonferroni correction or use tools that handle this automatically.
Problem: Not enough sample to detect realistic effects
Fix: Be realistic about MDE, get more traffic, or don't test
Problem: Waiting for sample size when you already have significance
Fix: This is actually fine—you committed to sample size, honor it
Problem: Using wrong conversion rate for calculation
Fix: Use the specific metric and page, not site-wide averages
Problem: Calculating for full traffic, then analyzing segments
Fix: If you plan segment analysis, calculate sample for smallest segment
Problem: Dividing traffic too many ways
Fix: Prioritize ruthlessly, run fewer concurrent tests
Options when you can't get enough traffic:
If you must check results before reaching sample size:
Statistical method that adjusts for multiple looks at data.
Daily traffic to page: _____
Baseline conversion rate: _____
MDE I care about: _____
Sample needed per variant: _____ (from tables above)
Days to run: Sample / Daily traffic = _____
If days > 60: Consider alternatives
If days > 30: Acceptable for high-impact tests
If days < 14: Likely feasible
If days < 7: Easy to run, consider running longer anyway
Templates for planning, documenting, and analyzing experiments.
# A/B Test: [Name]
## Overview
- **Owner**: [Name]
- **Test ID**: [ID in testing tool]
- **Page/Feature**: [What's being tested]
- **Planned dates**: [Start] - [End]
## Hypothesis
Because [observation/data],
we believe [change]
will cause [expected outcome]
for [audience].
We'll know this is true when [metrics].
## Test Design
| Element | Details |
|---------|---------|
| Test type | A/B / A/B/n / MVT |
| Duration | X weeks |
| Sample size | X per variant |
| Traffic allocation | 50/50 |
| Tool | [Tool name] |
| Implementation | Client-side / Server-side |
## Variants
### Control (A)
[Screenshot]
- Current experience
- [Key details about current state]
### Variant (B)
[Screenshot or mockup]
- [Specific change #1]
- [Specific change #2]
- Rationale: [Why we think this will win]
## Metrics
### Primary
- **Metric**: [metric name]
- **Definition**: [how it's calculated]
- **Current baseline**: [X%]
- **Minimum detectable effect**: [X%]
### Secondary
- [Metric 1]: [what it tells us]
- [Metric 2]: [what it tells us]
- [Metric 3]: [what it tells us]
### Guardrails
- [Metric that shouldn't get worse]
- [Another safety metric]
## Segment Analysis Plan
- Mobile vs. desktop
- New vs. returning visitors
- Traffic source
- [Other relevant segments]
## Success Criteria
- Winner: [Primary metric improves by X% with 95% confidence]
- Loser: [Primary metric decreases significantly]
- Inconclusive: [What we'll do if no significant result]
## Pre-Launch Checklist
- [ ] Hypothesis documented and reviewed
- [ ] Primary metric defined and trackable
- [ ] Sample size calculated
- [ ] Test duration estimated
- [ ] Variants implemented correctly
- [ ] Tracking verified in all variants
- [ ] QA completed on all variants
- [ ] Stakeholders informed
- [ ] Calendar hold for analysis date
# A/B Test Results: [Name]
## Summary
| Element | Value |
|---------|-------|
| Test ID | [ID] |
| Dates | [Start] - [End] |
| Duration | X days |
| Result | Winner / Loser / Inconclusive |
| Decision | [What we're doing] |
## Hypothesis (Reminder)
[Copy from test plan]
## Results
### Sample Size
| Variant | Target | Actual | % of target |
|---------|--------|--------|-------------|
| Control | X | Y | Z% |
| Variant | X | Y | Z% |
### Primary Metric: [Metric Name]
| Variant | Value | 95% CI | vs. Control |
|---------|-------|--------|-------------|
| Control | X% | [X%, Y%] | — |
| Variant | X% | [X%, Y%] | +X% |
**Statistical significance**: p = X.XX (95% = sig / not sig)
**Practical significance**: [Is this lift meaningful for the business?]
### Secondary Metrics
| Metric | Control | Variant | Change | Significant? |
|--------|---------|---------|--------|--------------|
| [Metric 1] | X | Y | +Z% | Yes/No |
| [Metric 2] | X | Y | +Z% | Yes/No |
### Guardrail Metrics
| Metric | Control | Variant | Change | Concern? |
|--------|---------|---------|--------|----------|
| [Metric 1] | X | Y | +Z% | Yes/No |
### Segment Analysis
**Mobile vs. Desktop**
| Segment | Control | Variant | Lift |
|---------|---------|---------|------|
| Mobile | X% | Y% | +Z% |
| Desktop | X% | Y% | +Z% |
**New vs. Returning**
| Segment | Control | Variant | Lift |
|---------|---------|---------|------|
| New | X% | Y% | +Z% |
| Returning | X% | Y% | +Z% |
## Interpretation
### What happened?
[Explanation of results in plain language]
### Why do we think this happened?
[Analysis and reasoning]
### Caveats
[Any limitations, external factors, or concerns]
## Decision
**Winner**: [Control / Variant]
**Action**: [Implement variant / Keep control / Re-test]
**Timeline**: [When changes will be implemented]
## Learnings
### What we learned
- [Key insight 1]
- [Key insight 2]
### What to test next
- [Follow-up test idea 1]
- [Follow-up test idea 2]
### Impact
- **Projected lift**: [X% improvement in Y metric]
- **Business impact**: [Revenue, conversions, etc.]
For tracking all tests in a central location:
| Test ID | Name | Page | Dates | Primary Metric | Result | Lift | Link |
|---------|------|------|-------|----------------|--------|------|------|
| 001 | Hero headline test | Homepage | 1/1-1/15 | CTR | Winner | +12% | [Link] |
| 002 | Pricing table layout | Pricing | 1/10-1/31 | Plan selection | Loser | -5% | [Link] |
| 003 | Signup form fields | Signup | 2/1-2/14 | Completion | Inconclusive | +2% | [Link] |
For simple tests that don't need full documentation:
## [Test Name]
**What**: [One sentence description]
**Why**: [One sentence hypothesis]
**Metric**: [Primary metric]
**Duration**: [X weeks]
**Result**: [TBD / Winner / Loser / Inconclusive]
**Learnings**: [Key takeaway]
## A/B Test Update: [Name]
**Status**: Running / Complete
**Days remaining**: X (or complete)
**Current sample**: X% of target
### Preliminary observations
[What we're seeing - without making decisions yet]
### Next steps
[What happens next]
### Timeline
- [Date]: Analysis complete
- [Date]: Decision and recommendation
- [Date]: Implementation (if winner)
For deciding which tests to run:
| Factor | Weight | Test A | Test B | Test C |
|---|---|---|---|---|
| Potential impact | 30% | |||
| Confidence in hypothesis | 25% | |||
| Ease of implementation | 20% | |||
| Risk if wrong | 15% | |||
| Strategic alignment | 10% | |||
| Total |
Scoring: 1-5 (5 = best)
For collecting test ideas:
| ID | Page/Area | Observation | Hypothesis | Potential Impact | Status |
|----|-----------|-------------|------------|------------------|--------|
| H1 | Homepage | Low scroll depth | Shorter hero will increase scroll | High | Testing |
| H2 | Pricing | Users compare plans | Comparison table will help | Medium | Backlog |
| H3 | Signup | Drop-off at email | Social login will increase completion | Medium | Backlog |
When the user wants to reduce churn, build cancellation flows, set up save offers, recover failed payments, or implement retention strategies. Also use when the user mentions 'churn,' 'cancel flow,' 'offboarding,' 'save
View source ↗You are an expert in SaaS retention and churn prevention. Your goal is to help reduce both voluntary churn (customers choosing to cancel) and involuntary churn (failed payments) through well-designed cancel flows, dynamic save offers, proactive retention, and dunning strategies.
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):
Churn has two types requiring different strategies:
| Type | Cause | Solution |
|---|---|---|
| Voluntary | Customer chooses to cancel | Cancel flows, save offers, exit surveys |
| Involuntary | Payment fails | Dunning emails, smart retries, card updaters |
Voluntary churn is typically 50-70% of total churn. Involuntary churn is 30-50% but is often easier to fix.
This skill supports three modes:
Every cancel flow follows this sequence:
Trigger → Survey → Dynamic Offer → Confirmation → Post-Cancel
Step 1: Trigger
Customer clicks "Cancel subscription" in account settings.
Step 2: Exit Survey
Ask why they're cancelling. This determines which save offer to show.
Step 3: Dynamic Save Offer
Present a targeted offer based on their reason (discount, pause, downgrade, etc.)
Step 4: Confirmation
If they still want to cancel, confirm clearly with end-of-billing-period messaging.
Step 5: Post-Cancel
Set expectations, offer easy reactivation path, trigger win-back sequence.
The exit survey is the foundation. Good reason categories:
| Reason | What It Tells You |
|---|---|
| Too expensive | Price sensitivity, may respond to discount or downgrade |
| Not using it enough | Low engagement, may respond to pause or onboarding help |
| Missing a feature | Product gap, show roadmap or workaround |
| Switching to competitor | Competitive pressure, understand what they offer |
| Technical issues / bugs | Product quality, escalate to support |
| Temporary / seasonal need | Usage pattern, offer pause |
| Business closed / changed | Unavoidable, learn and let go gracefully |
| Other | Catch-all, include free text field |
Survey best practices:
- 1 question, single-select with optional free text
- 5-8 reason options max (avoid decision fatigue)
- Put most common reasons first (review data quarterly)
- Don't make it feel like a guilt trip
- "Help us improve" framing works better than "Why are you leaving?"
The key insight: match the offer to the reason. A discount won't save someone who isn't using the product. A feature roadmap won't save someone who can't afford it.
Offer-to-reason mapping:
| Cancel Reason | Primary Offer | Fallback Offer |
|---|---|---|
| Too expensive | Discount (20-30% for 2-3 months) | Downgrade to lower plan |
| Not using it enough | Pause (1-3 months) | Free onboarding session |
| Missing feature | Roadmap preview + timeline | Workaround guide |
| Switching to competitor | Competitive comparison + discount | Feedback session |
| Technical issues | Escalate to support immediately | Credit + priority fix |
| Temporary / seasonal | Pause subscription | Downgrade temporarily |
| Business closed | Skip offer (respect the situation) | — |
Discount
- 20-30% off for 2-3 months is the sweet spot
- Avoid 50%+ discounts (trains customers to cancel for deals)
- Time-limit the offer ("This offer expires when you leave this page")
- Show the dollar amount saved, not just the percentage
Pause subscription
- 1-3 month pause maximum (longer pauses rarely reactivate)
- 60-80% of pausers eventually return to active
- Auto-reactivation with advance notice email
- Keep their data and settings intact
Plan downgrade
- Offer a lower tier instead of full cancellation
- Show what they keep vs. what they lose
- Position as "right-size your plan" not "downgrade"
- Easy path back up when ready
Feature unlock / extension
- Unlock a premium feature they haven't tried
- Extend trial of a higher tier
- Works best for "not getting enough value" reasons
Personal outreach
- For high-value accounts (top 10-20% by MRR)
- Route to customer success for a call
- Personal email from founder for smaller companies
┌─────────────────────────────────────┐
│ We're sorry to see you go │
│ │
│ What's the main reason you're │
│ cancelling? │
│ │
│ ○ Too expensive │
│ ○ Not using it enough │
│ ○ Missing a feature I need │
│ ○ Switching to another tool │
│ ○ Technical issues │
│ ○ Temporary / don't need right now │
│ ○ Other: [____________] │
│ │
│ [Continue] │
│ [Never mind, keep my subscription] │
└─────────────────────────────────────┘
↓ (selects "Too expensive")
┌─────────────────────────────────────┐
│ What if we could help? │
│ │
│ We'd love to keep you. Here's a │
│ special offer: │
│ │
│ ┌───────────────────────────────┐ │
│ │ 25% off for the next 3 months│ │
│ │ Save $XX/month │ │
│ │ │ │
│ │ [Accept Offer] │ │
│ └───────────────────────────────┘ │
│ │
│ Or switch to [Basic Plan] at │
│ $X/month → │
│ │
│ [No thanks, continue cancelling] │
└─────────────────────────────────────┘
UI principles:
- Keep the "continue cancelling" option visible (no dark patterns)
- One primary offer + one fallback, not a wall of options
- Show specific dollar savings, not abstract percentages
- Use the customer's name and account data when possible
- Mobile-friendly (many cancellations happen on mobile)
For detailed cancel flow patterns by industry and billing provider, see references/cancel-flow-patterns.md.
The best save happens before the customer ever clicks "Cancel."
Track these leading indicators of churn:
| Signal | Risk Level | Timeframe |
|---|---|---|
| Login frequency drops 50%+ | High | 2-4 weeks before cancel |
| Key feature usage stops | High | 1-3 weeks before cancel |
| Support tickets spike then stop | High | 1-2 weeks before cancel |
| Email open rates decline | Medium | 2-6 weeks before cancel |
| Billing page visits increase | High | Days before cancel |
| Team seats removed | High | 1-2 weeks before cancel |
| Data export initiated | Critical | Days before cancel |
| NPS score drops below 6 | Medium | 1-3 months before cancel |
Build a simple health score (0-100) from weighted signals:
Health Score = (
Login frequency score × 0.30 +
Feature usage score × 0.25 +
Support sentiment × 0.15 +
Billing health × 0.15 +
Engagement score × 0.15
)
| Score | Status | Action |
|---|---|---|
| 80-100 | Healthy | Upsell opportunities |
| 60-79 | Needs attention | Proactive check-in |
| 40-59 | At risk | Intervention campaign |
| 0-39 | Critical | Personal outreach |
Before they think about cancelling:
| Trigger | Intervention |
|---|---|
| Usage drop >50% for 2 weeks | "We noticed you haven't used [feature]. Need help?" email |
| Approaching plan limit | Upgrade nudge (not a wall — paywalls handles this) |
| No login for 14 days | Re-engagement email with recent product updates |
| NPS detractor (0-6) | Personal follow-up within 24 hours |
| Support ticket unresolved >48h | Escalation + proactive status update |
| Annual renewal in 30 days | Value recap email + renewal confirmation |
Failed payments cause 30-50% of all churn but are the most recoverable.
Pre-dunning → Smart retry → Dunning emails → Grace period → Hard cancel
Not all failures are the same. Retry strategy by decline type:
| Decline Type | Examples | Retry Strategy |
|---|---|---|
| Soft decline (temporary) | Insufficient funds, processor timeout | Retry 3-5 times over 7-10 days |
| Hard decline (permanent) | Card stolen, account closed | Don't retry — ask for new card |
| Authentication required | 3D Secure, SCA | Send customer to update payment |
Retry timing best practices:
- Retry 1: 24 hours after failure
- Retry 2: 3 days after failure
- Retry 3: 5 days after failure
- Retry 4: 7 days after failure (with dunning email escalation)
- After 4 retries: Hard cancel with reactivation path
Smart retry tip: Retry on the day of the month the payment originally succeeded (if Day 1 worked before, retry on Day 1). Stripe Smart Retries handles this automatically.
| Timing | Tone | Content | |
|---|---|---|---|
| 1 | Day 0 (failure) | Friendly alert | "Your payment didn't go through. Update your card." |
| 2 | Day 3 | Helpful reminder | "Quick reminder — update your payment to keep access." |
| 3 | Day 7 | Urgency | "Your account will be paused in 3 days. Update now." |
| 4 | Day 10 | Final warning | "Last chance to keep your account active." |
Dunning email best practices:
- Direct link to payment update page (no login required if possible)
- Show what they'll lose (their data, their team's access)
- Don't blame ("your payment failed" not "you failed to pay")
- Include support contact for help
- Plain text performs better than designed emails for dunning
| Metric | Poor | Average | Good |
|---|---|---|---|
| Soft decline recovery | <40% | 50-60% | 70%+ |
| Hard decline recovery | <10% | 20-30% | 40%+ |
| Overall payment recovery | <30% | 40-50% | 60%+ |
| Pre-dunning prevention | None | 10-15% | 20-30% |
For the complete dunning playbook with provider-specific setup, see references/dunning-playbook.md.
| Metric | Formula | Target |
|---|---|---|
| Monthly churn rate | Churned customers / Start-of-month customers | <5% B2C, <2% B2B |
| Revenue churn (net) | (Lost MRR - Expansion MRR) / Start MRR | Negative (net expansion) |
| Cancel flow save rate | Saved / Total cancel sessions | 25-35% |
| Offer acceptance rate | Accepted offers / Shown offers | 15-25% |
| Pause reactivation rate | Reactivated / Total paused | 60-80% |
| Dunning recovery rate | Recovered / Total failed payments | 50-60% |
| Time to cancel | Days from first churn signal to cancel | Track trend |
Segment churn by:
- Acquisition channel — Which channels bring stickier customers?
- Plan type — Which plans churn most?
- Tenure — When do most cancellations happen? (30, 60, 90 days?)
- Cancel reason — Which reasons are growing?
- Save offer type — Which offers work best for which segments?
Test one variable at a time:
| Test | Hypothesis | Metric |
|---|---|---|
| Discount % (20% vs 30%) | Higher discount saves more | Save rate, LTV impact |
| Pause duration (1 vs 3 months) | Longer pause increases return rate | Reactivation rate |
| Survey placement (before vs after offer) | Survey-first personalizes offers | Save rate |
| Offer presentation (modal vs full page) | Full page gets more attention | Save rate |
| Copy tone (empathetic vs direct) | Empathetic reduces friction | Save rate |
How to run cancel flow experiments: Use the ab-testing skill to design statistically rigorous tests. PostHog is a good fit for cancel flow experiments — its feature flags can split users into different flows server-side, and its funnel analytics track each step of the cancel flow (survey → offer → accept/decline → confirm). See the PostHog integration guide for setup.
For implementation, see the tools registry.
| Tool | Best For | Key Feature |
|---|---|---|
| Churnkey | Full cancel flow + dunning | AI-powered adaptive offers, 34% avg save rate |
| ProsperStack | Cancel flows with analytics | Advanced rules engine, Stripe/Chargebee integration |
| Raaft | Simple cancel flow builder | Easy setup, good for early-stage |
| Chargebee Retention | Chargebee customers | Native integration, was Brightback |
| Provider | Smart Retries | Dunning Emails | Card Updater |
|---|---|---|---|
| Stripe | Built-in (Smart Retries) | Built-in | Automatic |
| Chargebee | Built-in | Built-in | Via gateway |
| Paddle | Built-in | Built-in | Managed |
| Recurly | Built-in | Built-in | Built-in |
| Braintree | Manual config | Manual | Via gateway |
| Tool | Use For |
|---|---|
stripe |
Subscription management, dunning config, payment retries |
customer-io |
Dunning email sequences, retention campaigns |
posthog |
Cancel flow A/B tests via feature flags, funnel analytics |
mixpanel / ga4 |
Usage tracking, churn signal analysis |
segment |
Event routing for health scoring |
Detailed cancel flow patterns by business type, billing provider, and industry.
High volume, low touch. The flow must work without human intervention.
Flow structure:
Cancel button → Exit survey (1 question) → Dynamic offer → Confirm → Post-cancel
Characteristics:
- Fully automated, no human in the loop
- Quick — 2-3 screens maximum
- One offer + one fallback, not a menu of options
- Mobile-optimized (significant cancellations on mobile)
- Clear "continue cancelling" at every step
Typical save rate: 20-30%
Example flow for a $29/mo productivity app:
1. "What's the main reason?" → 6 options
2. Selected "Too expensive" → "Get 25% off for 3 months (save $21.75)"
3. Declined → "Or switch to our Starter plan at $12/mo"
4. Declined → "We're sorry to see you go. Your access continues until [date]."
Lower volume, higher stakes. Personal outreach is worth the cost.
Flow structure:
Cancel button → Exit survey → Offer (or route to CS) → Confirm → Post-cancel
Characteristics:
- Route accounts above MRR threshold to customer success
- Show team impact ("Your 8 team members will lose access")
- Offer admin-to-admin call for enterprise accounts
- Longer consideration — allow "schedule a call" as a save option
- Require admin/owner role to cancel (not any team member)
Typical save rate: 30-45% (higher because of personal touch)
MRR-based routing:
| Account MRR | Cancel Flow |
|---|---|
| <$100/mo | Automated flow with offers |
| $100-$500/mo | Automated + flag for CS follow-up |
| $500-$2,000/mo | Route to CS before cancel completes |
| $2,000+/mo | Block self-serve cancel, require CS call |
Users cancelling paid to return to free tier. Different psychology — they're not leaving, they're downgrading.
Flow structure:
Cancel button → "Switch to Free?" prompt → Exit survey (if still cancelling) → Offer → Confirm
Characteristics:
- Lead with the free tier as the first option (not a save offer)
- Show what they keep on free vs. what they lose
- The "save" is keeping them on free, not losing them entirely
- Track free-tier users for future re-upgrade campaigns
Offer priority:
1. Discount (if reason = price)
2. Pause (if reason = not using / temporary)
3. Annual plan switch (if engaged but price-sensitive)
Offer priority:
1. Pause remainder of term (if temporary)
2. Plan adjustment + credit for next renewal
3. Personal outreach from CS
4. Partial refund + downgrade (better than full refund + cancel)
Refund handling:
- Offer prorated refund if significant time remaining
- "Pause until renewal" if less than 3 months left
- Be generous — bad refund experiences create vocal detractors
Don't lead with your biggest discount. Escalate:
Cancel click → 15% off → Still cancelling → 25% off → Still cancelling → Let them go
Rules:
- Maximum 2 discount offers per cancel session
- Never exceed 30% (higher trains cancel-for-discount behavior)
- Time-limit discounts (2-3 months, then full price resumes)
- Track discount accepters — if they cancel again at full price, don't re-offer
Pause is often better than a discount because it doesn't devalue your product.
Implementation:
| Setting | Recommendation |
|---|---|
| Pause duration options | 1 month, 2 months, 3 months |
| Default selection | 1 month (shortest) |
| Maximum pause | 3 months (longer pauses rarely return) |
| During pause | Keep data, remove access |
| Reactivation | Auto-reactivate with 7-day advance email |
| Repeat pauses | Allow 1 pause per 12-month period |
Pause reactivation sequence:
- Day -7: "Your pause ends in 7 days. We've been busy — here's what's new."
- Day -1: "Welcome back tomorrow! Here's what's waiting for you."
- Day 0: "You're back! Here's a quick tour of what's new."
For multi-plan products, downgrade is the strongest save:
┌─────────────────────────────────────────┐
│ Before you go, what about right-sizing │
│ your plan? │
│ │
│ Current: Pro ($49/mo) │
│ │
│ ┌─────────────────────────────────┐ │
│ │ Switch to Starter ($19/mo) │ │
│ │ │ │
│ │ ✓ Keep: Projects, integrations │ │
│ │ ✗ Lose: Advanced analytics, │ │
│ │ team features │ │
│ │ │ │
│ │ [Switch to Starter] │ │
│ └─────────────────────────────────┘ │
│ │
│ [No thanks, continue cancelling] │
└─────────────────────────────────────────┘
Downgrade best practices:
- Show exactly what they keep and what they lose
- Use checkmarks and X marks for scanability
- Preserve their data even on the lower plan
- If they downgrade, don't show upgrade prompts for at least 30 days
When the cancel reason is "switching to competitor":
This data is gold for product and marketing teams.
What happens after cancel matters for:
- Win-back potential
- Word of mouth
- Review sentiment
Your subscription has been cancelled.
What happens next:
• Your access continues until [billing period end date]
• Your data will be preserved for 90 days
• You can reactivate anytime from your account settings
[Reactivate My Account]
We'd love to have you back. We'll keep improving based on feedback
from customers like you.
| Timing | Action |
|---|---|
| Immediately | Confirmation email with access end date |
| Day 1 | (Nothing — don't be desperate) |
| Day 7 | NPS/satisfaction survey about overall experience |
| Day 30 | "What's new" email with recent improvements |
| Day 60 | Address their specific cancel reason if resolved |
| Day 90 | Final win-back with special offer |
For detailed win-back email sequences: See the emails skill.
The most effective cancel flows use segmentation to show different offers to different customers.
| Dimension | Why It Matters |
|---|---|
| Plan / MRR | Higher-value customers get personal outreach |
| Tenure | Long-term customers get more generous offers |
| Usage level | High-usage customers get different messaging than dormant ones |
| Billing interval | Monthly vs. annual need different approaches |
| Previous saves | Don't re-offer the same discount to a repeat canceller |
| Cancel reason | Drives which offer to show (core mapping) |
New customer (< 30 days):
- They haven't activated. The save is onboarding, not discounts.
- Offer: Free onboarding call, setup help, extended trial
- Ask: "What were you hoping to accomplish?" (learn what's missing)
Engaged customer cancelling on price:
- They love the product but can't justify the cost.
- Offer: Discount, annual plan switch, downgrade
- High save potential
Dormant customer (no login 30+ days):
- They forgot about you. A discount won't bring them back.
- Offer: Pause subscription, "what changed?" conversation
- Low save potential — focus on learning why
Power user switching to competitor:
- They're actively choosing something else.
- Offer: Competitive match, feedback call, roadmap preview
- Medium save potential — depends on reason
Complete guide to recovering failed payments and reducing involuntary churn.
Day -30 to -7: Pre-dunning (prevent failures)
Day 0: Payment fails → Smart retry #1 + Email #1
Day 1-3: Smart retry #2 + Email #2
Day 3-5: Smart retry #3
Day 5-7: Smart retry #4 + Email #3
Day 7-10: Final retry + Email #4 (final warning)
Day 10-14: Grace period ends → Account paused/cancelled
Day 14+: Win-back sequence begins
| Timing | Action |
|---|---|
| 30 days before expiry | Email: "Your card ending in 4242 expires next month" |
| 15 days before expiry | Email: "Update your payment method to avoid interruption" |
| 7 days before expiry | Email: "Your card expires in 7 days — update now" |
| 3 days before expiry | In-app banner: "Payment method expiring soon" |
Email template — Card expiring:
Subject: Your card ending in 4242 expires soon
Hi [Name],
The card on file for your [Product] subscription expires on [date].
Update your payment method now to avoid any interruption:
[Update Payment Method →]
This takes less than 30 seconds.
— [Product] Team
Major card networks offer automatic card update programs:
| Service | Network | What It Does |
|---|---|---|
| Visa Account Updater (VAU) | Visa | Auto-updates stored card numbers and expiry dates |
| Mastercard Automatic Billing Updater (ABU) | Mastercard | Same for Mastercard |
| Amex Cardrefresher | American Express | Same for Amex |
Impact: Reduces hard declines from expired/replaced cards by 30-50%.
How to enable:
- Stripe: Automatic — enabled by default
- Chargebee: Enabled through gateway settings
- Recurly: Built-in, enabled by default
- Braintree: Contact processor to enable
Prompt for a second payment method:
- During signup: "Add a backup payment method" (low conversion)
- After first successful payment: "Protect your account with a backup card" (better timing)
- After a failed payment is recovered: "Add a backup to prevent future interruptions" (best timing — they felt the pain)
For annual plans or high-value subscriptions:
- Email 7 days before renewal with amount and date
- Include link to update payment method
- Show what's included in the renewal
- Required by some regulations for auto-renewals
| Code | Type | Meaning | Retry? |
|---|---|---|---|
insufficient_funds |
Soft | Temporarily low balance | Yes — retry in 2-3 days |
card_declined (generic) |
Soft | Various temporary reasons | Yes — retry 3-4 times |
processing_error |
Soft | Gateway/network issue | Yes — retry within 24h |
expired_card |
Hard | Card is expired | No — request new card |
stolen_card |
Hard | Card reported stolen | No — request new card |
do_not_honor |
Soft/Hard | Bank refused (ambiguous) | Try once more, then ask for new card |
authentication_required |
Auth | SCA/3DS needed | Send customer to authenticate |
Stripe (Smart Retries — recommended):
- Enable "Smart Retries" in Stripe Dashboard → Billing → Settings
- Stripe's ML model picks optimal retry timing based on billions of transactions
- Typically 4-8 retry attempts over 3-4 weeks
- Recovers ~15% more than fixed-schedule retries
Manual retry schedule (if no smart retries):
| Retry | Timing | Best Day/Time |
|---|---|---|
| 1 | Day 1 (24h after failure) | Morning, same day of week as original |
| 2 | Day 3 | Try a different time of day |
| 3 | Day 5 | After typical payday (1st, 15th) |
| 4 | Day 7 | Morning of the next business day |
| 5 (final) | Day 10 | Last attempt before grace period ends |
Retry timing insights:
- Retry on the same day of month the original payment succeeded
- Retry after common paydays (1st and 15th of the month)
- Avoid retrying on weekends (lower approval rates)
- Morning retries (8-10am local time) perform slightly better
Tone: Friendly, matter-of-fact. No alarm.
Subject: Action needed — your payment didn't go through
Hi [Name],
We tried to charge your [card type] ending in [last 4] for your
[Product] subscription ($[amount]), but it didn't go through.
This happens sometimes — usually a quick card update fixes it.
[Update Payment Method →]
Your access isn't affected yet. We'll retry automatically, but
updating your card is the fastest fix.
Need help? Just reply to this email.
— [Product] Team
Tone: Helpful, slightly more urgent.
Subject: Quick reminder — update your payment for [Product]
Hi [Name],
Just a heads-up — we still haven't been able to process your
$[amount] payment for [Product].
[Update Payment Method →]
Takes less than 30 seconds. Your [data/projects/team access]
is safe, but we'll need a valid payment method to keep your
account active.
Questions? Reply here and we'll help.
— [Product] Team
Tone: Direct, clear consequences.
Subject: Your [Product] account will be paused in 3 days
Hi [Name],
We've tried to process your payment several times, but your
[card type] ending in [last 4] keeps getting declined.
If we don't receive payment by [date], your account will be
paused and you'll lose access to:
• [Key feature/data they use]
• [Their projects/workspace]
• [Team access for X members]
[Update Payment Method Now →]
Your data won't be deleted — you can reactivate anytime by
updating your payment method.
— [Product] Team
Tone: Final, clear, no guilt.
Subject: Last chance to keep your [Product] account active
Hi [Name],
This is our last reminder. Your payment of $[amount] is past
due, and your account will be paused tomorrow ([date]).
[Update Payment Method →]
After pausing:
• Your data is saved for [90 days]
• You can reactivate anytime
• Just update your card to restore access
If you intended to cancel, no action needed — your account
will be paused automatically.
— [Product] Team
| Setting | Recommendation |
|---|---|
| Duration | 7-14 days after final retry |
| Access | Degraded (read-only) or full access |
| Visibility | In-app banner: "Payment past due — update to continue" |
| Retry | Continue background retries during grace |
| Communication | Dunning emails continue |
Option A: Full access during grace (recommended for B2B)
- Lower friction, customer feels respected
- Higher recovery rate (they still see value)
- Risk: some customers exploit the grace period
Option B: Read-only access (recommended for B2C)
- Can view but not create/edit
- Creates urgency without data loss fear
- Clear message: "Update payment to resume full access"
Option C: Immediate lockout (not recommended)
- Aggressive, damages relationship
- Lower recovery rate
- Only appropriate for very low-cost plans
| Timing | Action |
|---|---|
| Grace period ends | Pause account (not delete) |
| Day 1 post-pause | "Your account has been paused" email |
| Day 7 post-pause | "Your data is still here" reminder |
| Day 30 post-pause | Win-back attempt with new offer |
| Day 60 post-pause | Final win-back |
| Day 90 post-pause | Data deletion warning (if applicable) |
Enable Smart Retries:
1. Dashboard → Settings → Billing → Subscriptions and emails
2. Enable "Smart Retries" under retry rules
3. Set failed payment emails in Dashboard → Settings → Emails
Custom retry rules (if not using Smart Retries):
Retry 1: 3 days after failure
Retry 2: 5 days after failure
Retry 3: 7 days after failure
Final: Mark subscription as unpaid after last retry
Webhook events to handle:
- invoice.payment_failed — trigger dunning
- invoice.paid — cancel dunning, restore access
- customer.subscription.updated — status changes
- customer.subscription.deleted — final cancellation
Built-in dunning:
1. Settings → Configure Chargebee → Retry Settings
2. Configure retry attempts and intervals
3. Settings → Configure Chargebee → Email Notifications → Dunning
Dunning options:
- Automatic retries with configurable schedule
- Built-in dunning emails (customizable templates)
- Grace period configuration per plan
Managed dunning:
- Paddle handles retries and dunning automatically
- Limited customization (Paddle manages the relationship)
- Webhook: subscription.payment_failed, subscription.cancelled
- Best for hands-off approach
Revenue Recovery:
1. Configuration → Dunning Management
2. Set retry schedule per plan
3. Configure grace period and final action (pause vs cancel)
Advanced features:
- Machine-learning retry optimization
- Per-plan dunning schedules
- Built-in Account Updater
Don't rely on email alone. Show payment failures in the app:
┌──────────────────────────────────────────────────────┐
│ ⚠ Your payment of $29 failed. Update your card to │
│ avoid losing access. [Update Payment →] [Dismiss] │
└──────────────────────────────────────────────────────┘
Rules:
- Show on every page load during dunning period
- Allow dismiss (but show again next session)
- Direct link to payment update (fewest clicks possible)
- Don't block the product — let them continue using it
┌─────────────────────────────────────┐
│ │
│ Your account will be paused │
│ on [date] │
│ │
│ Update your payment method to │
│ keep access to your [X] projects │
│ and [Y] team members. │
│ │
│ [Update Payment Method] │
│ [Remind Me Later] │
│ │
└─────────────────────────────────────┘
| Metric | How to Calculate | Target |
|---|---|---|
| Recovery rate | Recovered payments / Total failed | 50-60% |
| Recovery rate by decline type | Recovered / Failed per type | Soft: 70%+, Hard: 40%+ |
| Time to recovery | Days from failure to successful payment | <5 days |
| Pre-dunning prevention rate | Prevented failures / Expected failures | 20-30% |
| Dunning email open rate | Opens / Sent per email | 60%+ |
| Dunning email click rate | Clicks / Opens per email | 30%+ |
| Revenue recovered (monthly) | Sum of recovered payment amounts | Track trend |
| Revenue lost to involuntary churn | Sum of failed + unrecovered amounts | Track trend |
By company stage:
| Stage | Typical Involuntary Churn | Target After Optimization |
|---|---|---|
| Early (< $1M ARR) | 3-5% of MRR/month | 1-2% |
| Growth ($1-10M ARR) | 2-4% of MRR/month | 0.5-1.5% |
| Scale ($10M+ ARR) | 1-3% of MRR/month | 0.3-0.8% |
Monthly failed payment MRR: $10,000
Current recovery rate: 30% ($3,000 recovered)
Target recovery rate: 60% ($6,000 recovered)
Monthly improvement: $3,000/month
Annual improvement: $36,000/year
Cost of dunning optimization: ~$200-500/month (tooling)
ROI: 6-15x
When the user wants to optimize, improve, or increase conversions on any marketing page or form — including homepage, landing pages, pricing pages, feature pages, lead capture forms, or contact forms. Also use when the u
View source ↗You are a conversion rate optimization expert. Your goal is to analyze marketing pages and provide actionable recommendations to improve conversion rates.
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.
Before providing recommendations, identify:
Analyze the page across these dimensions, in order of impact:
Check for:
- Can a visitor understand what this is and why they should care within 5 seconds?
- Is the primary benefit clear, specific, and differentiated?
- Is it written in the customer's language (not company jargon)?
Common issues:
- Feature-focused instead of benefit-focused
- Too vague or too clever (sacrificing clarity)
- Trying to say everything instead of the most important thing
Evaluate:
- Does it communicate the core value proposition?
- Is it specific enough to be meaningful?
- Does it match the traffic source's messaging?
Strong headline patterns:
- Outcome-focused: "Get [desired outcome] without [pain point]"
- Specificity: Include numbers, timeframes, or concrete details
- Social proof: "Join 10,000+ teams who..."
Primary CTA assessment:
- Is there one clear primary action?
- Is it visible without scrolling?
- Does the button copy communicate value, not just action?
- Weak: "Submit," "Sign Up," "Learn More"
- Strong: "Start Free Trial," "Get My Report," "See Pricing"
CTA hierarchy:
- Is there a logical primary vs. secondary CTA structure?
- Are CTAs repeated at key decision points?
Check:
- Can someone scanning get the main message?
- Are the most important elements visually prominent?
- Is there enough white space?
- Do images support or distract from the message?
Types to look for:
- Customer logos (especially recognizable ones)
- Testimonials (specific, attributed, with photos)
- Case study snippets with real numbers
- Review scores and counts
- Security badges (where relevant)
Placement: Near CTAs and after benefit claims
Common objections to address:
- Price/value concerns
- "Will this work for my situation?"
- Implementation difficulty
- "What if it doesn't work?"
Address through: FAQ sections, guarantees, comparison content, process transparency
Look for:
- Too many form fields
- Unclear next steps
- Confusing navigation
- Required information that shouldn't be required
- Mobile experience issues
- Long load times
Structure your recommendations as:
Easy changes with likely immediate impact.
Bigger changes that require more effort but will significantly improve conversions.
Hypotheses worth A/B testing rather than assuming.
For key elements (headlines, CTAs), provide 2-3 alternatives with rationale.
When recommending experiments, consider tests for:
- Hero section (headline, visual, CTA)
- Trust signals and social proof placement
- Pricing presentation
- Form optimization
- Navigation and UX
For comprehensive experiment ideas by page type: See references/experiments.md
For detailed form CRO guidance — including field optimization, multi-step forms, error handling, and form-specific experiments — see references/form.md.
Comprehensive list of A/B tests and experiments organized by page type.
| Test | Hypothesis |
|---|---|
| Headline variations | Specific vs. abstract messaging |
| Subheadline clarity | Add/refine to support headline |
| CTA above fold | Include or exclude prominent CTA |
| Hero visual format | Screenshot vs. GIF vs. illustration vs. video |
| CTA button color | Test contrast and visibility |
| CTA button text | "Start Free Trial" vs. "Get Started" vs. "See Demo" |
| Interactive demo | Engage visitors immediately with product |
| Test | Hypothesis |
|---|---|
| Logo placement | Hero section vs. below fold |
| Case study in hero | Show results immediately |
| Trust badges | Add security, compliance, awards |
| Social proof in headline | "Join 10,000+ teams" messaging |
| Testimonial placement | Above fold vs. dedicated section |
| Video testimonials | More engaging than text quotes |
| Test | Hypothesis |
|---|---|
| Feature presentation | Icons + descriptions vs. detailed sections |
| Section ordering | Move high-value features up |
| Secondary CTAs | Add/remove throughout page |
| Benefit vs. feature focus | Lead with outcomes |
| Comparison section | Show vs. competitors or status quo |
| Test | Hypothesis |
|---|---|
| Sticky navigation | Persistent nav with CTA |
| Nav menu order | High-priority items at edges |
| Nav CTA button | Add prominent button in nav |
| Support widget | Live chat vs. AI chatbot |
| Footer optimization | Clearer secondary conversions |
| Exit intent popup | Capture abandoning visitors |
| Test | Hypothesis |
|---|---|
| Annual vs. monthly display | Highlight savings or simplify |
| Price points | $99 vs. $100 vs. $97 psychology |
| "Most Popular" badge | Highlight target plan |
| Number of tiers | 3 vs. 4 vs. 2 visible options |
| Price anchoring | Order plans to anchor expectations |
| Custom enterprise tier | Show vs. "Contact Sales" |
| Test | Hypothesis |
|---|---|
| Pricing calculator | For usage-based pricing clarity |
| Guided pricing flow | Multistep wizard vs. comparison table |
| Feature comparison format | Table vs. expandable sections |
| Monthly/annual toggle | With savings highlighted |
| Plan recommendation quiz | Help visitors choose |
| Checkout flow length | Steps required after plan selection |
| Test | Hypothesis |
|---|---|
| FAQ section | Address pricing objections |
| ROI calculator | Demonstrate value vs. cost |
| Money-back guarantee | Prominent placement |
| Per-user breakdowns | Clarity for team plans |
| Feature inclusion clarity | What's in each tier |
| Competitor comparison | Side-by-side value comparison |
| Test | Hypothesis |
|---|---|
| Value testimonials | Quotes about ROI specifically |
| Customer logos | Near pricing section |
| Review scores | G2/Capterra ratings |
| Case study snippet | Specific pricing/value results |
| Test | Hypothesis |
|---|---|
| Field count | Fewer fields, higher completion |
| Multi-step vs. single | Progress bar encouragement |
| Form placement | Above fold vs. after content |
| Phone field | Include vs. exclude |
| Field enrichment | Hide fields you can auto-fill |
| Form labels | Inside field vs. above |
| Test | Hypothesis |
|---|---|
| Benefits above form | Reinforce value before ask |
| Demo preview | Video/GIF showing demo experience |
| "What You'll Learn" | Set expectations clearly |
| Testimonials near form | Reduce friction at decision point |
| FAQ below form | Address common objections |
| Video vs. text | Format for explaining value |
| Test | Hypothesis |
|---|---|
| CTA text | "Book Your Demo" vs. "Schedule 15-Min Call" |
| On-demand option | Instant demo alongside live option |
| Personalized messaging | Based on visitor data/source |
| Navigation removal | Reduce page distractions |
| Calendar integration | Inline booking vs. external link |
| Qualification routing | Self-serve for some, sales for others |
| Test | Hypothesis |
|---|---|
| Floating CTAs | Sticky CTA on blog posts |
| CTA placement | Inline vs. end-of-post only |
| Reading time display | Estimated reading time |
| Related resources | End-of-article recommendations |
| Gated vs. free | Content access strategy |
| Content upgrades | Specific to article topic |
| Test | Hypothesis |
|---|---|
| Navigation/filtering | Easier to find relevant content |
| Search functionality | Find specific resources |
| Featured resources | Highlight best content |
| Layout format | Grid vs. list view |
| Topic bundles | Grouped resources by theme |
| Download tracking | Gate some, track engagement |
| Test | Hypothesis |
|---|---|
| Headline matching | Match ad copy exactly |
| Visual matching | Match ad creative |
| Offer alignment | Same offer as ad promised |
| Audience-specific pages | Different pages per segment |
| Test | Hypothesis |
|---|---|
| Navigation removal | Single-focus page |
| CTA repetition | Multiple CTAs throughout |
| Form vs. button | Direct capture vs. click-through |
| Urgency/scarcity | If genuine, test messaging |
| Social proof density | Amount and placement |
| Video inclusion | Explain offer with video |
| Test | Hypothesis |
|---|---|
| Short vs. long | Quick conversion vs. complete argument |
| Above-fold only | Minimal scroll required |
| Section ordering | Most important content first |
| Footer removal | Eliminate navigation |
| Test | Hypothesis |
|---|---|
| Demo/screenshot | Show feature in action |
| Use case examples | How customers use it |
| Before/after | Impact visualization |
| Video walkthrough | Feature tour |
| Interactive demo | Try feature without signup |
| Test | Hypothesis |
|---|---|
| Trial CTA | Feature-specific trial offer |
| Related features | Cross-link to other features |
| Comparison | vs. competitors' version |
| Pricing mention | Connect to relevant plan |
| Case study link | Feature-specific success story |
| Test | Hypothesis |
|---|---|
| Chat widget | Impact on conversions |
| Cookie consent UX | Minimize friction |
| Page load speed | Performance vs. features |
| Mobile experience | Responsive optimization |
| Accessibility | Impact on conversion |
| Personalization | Dynamic content by segment |
| Test | Hypothesis |
|---|---|
| Menu structure | Information architecture |
| Search placement | Help visitors find content |
| CTA in nav | Always-visible conversion path |
| Breadcrumbs | Navigation clarity |
You are an expert in form optimization. Your goal is to maximize form completion rates while capturing the data that matters.
Check for product marketing context first:
If .agents/product-marketing.md exists (or .claude/product-marketing.md in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
Before providing recommendations, identify:
Form Type
- Lead capture (gated content, newsletter)
- Contact form
- Demo/sales request
- Application form
- Survey/feedback
- Checkout form
- Quote request
Current State
- How many fields?
- What's the current completion rate?
- Mobile vs. desktop split?
- Where do users abandon?
Business Context
- What happens with form submissions?
- Which fields are actually used in follow-up?
- Are there compliance/legal requirements?
Each field reduces completion rate. Rule of thumb:
- 3 fields: Baseline
- 4-6 fields: 10-25% reduction
- 7+ fields: 25-50%+ reduction
For each field, ask:
- Is this absolutely necessary before we can help them?
- Can we get this information another way?
- Can we ask this later?
Good:
Email
[name@company.com]
Bad:
[Enter your email address] ← Disappears on focus
Good: "Please enter a valid email address (e.g., name@company.com)"
Bad: "Invalid input"
Weak: "Submit" | "Send"
Strong: "[Action] + [What they get]"
Examples:
- "Get My Free Quote"
- "Download the Guide"
- "Request Demo"
- "Send Message"
- "Start Free Trial"
For each issue:
- Issue: What's wrong
- Impact: Estimated effect on conversions
- Fix: Specific recommendation
- Priority: High/Medium/Low
Ideas to A/B test with expected outcomes
Layout & Flow
- Single-step form vs. multi-step with progress bar
- 1-column vs. 2-column field layout
- Form embedded on page vs. separate page
- Vertical vs. horizontal field alignment
- Form above fold vs. after content
Field Optimization
- Reduce to minimum viable fields
- Add or remove phone number field
- Add or remove company/organization field
- Test required vs. optional field balance
- Use field enrichment to auto-fill known data
- Hide fields for returning/known visitors
Smart Forms
- Add real-time validation for emails and phone numbers
- Progressive profiling (ask more over time)
- Conditional fields based on earlier answers
- Auto-suggest for company names
Labels & Microcopy
- Test field label clarity and length
- Placeholder text optimization
- Help text: show vs. hide vs. on-hover
- Error message tone (friendly vs. direct)
CTAs & Buttons
- Button text variations ("Submit" vs. "Get My Quote" vs. specific action)
- Button color and size testing
- Button placement relative to fields
Trust Elements
- Add privacy assurance near form
- Show trust badges next to submit
- Add testimonial near form
- Display expected response time
Demo Request Forms
- Test with/without phone number requirement
- Add "preferred contact method" choice
- Include "What's your biggest challenge?" question
- Test calendar embed vs. form submission
Lead Capture Forms
- Email-only vs. email + name
- Test value proposition messaging above form
- Gated vs. ungated content strategies
- Post-submission enrichment questions
Contact Forms
- Add department/topic routing dropdown
- Test with/without message field requirement
- Show alternative contact methods (chat, phone)
- Expected response time messaging
When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or brand awareness. Also use when the user mentions "engineering as marketing," "free tool," "marketing too
View source ↗You are an expert in engineering-as-marketing strategy. Your goal is to help plan and evaluate free tools that generate leads, attract organic traffic, and build brand awareness.
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.
Before designing a tool strategy, understand:
Business Context - What's the core product? Who is the target audience? What problems do they have?
Goals - Lead generation? SEO/traffic? Brand awareness? Product education?
Resources - Technical capacity to build? Ongoing maintenance bandwidth? Budget for promotion?
| Type | Examples | Best For |
|---|---|---|
| Calculators | ROI, savings, pricing estimators | Decisions involving numbers |
| Generators | Templates, policies, names | Creating something quickly |
| Analyzers | Website graders, SEO auditors | Evaluating existing work |
| Testers | Meta tag preview, speed tests | Checking if something works |
| Libraries | Icon sets, templates, snippets | Reference material |
| Interactive | Tutorials, playgrounds, quizzes | Learning/understanding |
For detailed tool types and examples: See references/tool-types.md
What problems does your audience Google? - Search query research, common questions
What manual processes are tedious? - Spreadsheet tasks, repetitive calculations
What do they need before buying your product? - Assessments, planning, comparisons
What information do they wish they had? - Data they can't easily access, benchmarks
| Approach | Pros | Cons |
|---|---|---|
| Fully gated | Maximum capture | Lower usage |
| Partially gated | Balance of both | Common pattern |
| Ungated + optional | Maximum reach | Lower capture |
| Ungated entirely | Pure SEO/brand | No direct leads |
Tool landing page: "[thing] calculator", "[thing] generator", "free [tool type]"
Supporting content: "How to [use case]", "What is [concept]"
Free tools attract links because:
- Genuinely useful (people reference them)
- Unique (can't link to just any page)
- Shareable (social amplification)
When: Unique concept, core to brand, high strategic value, have dev capacity
Options: Outgrow, Involve.me, Typeform, Tally, Bubble, Webflow
When: Speed to market, limited dev resources, testing concept
When: Something good exists, white-label available, not core differentiator
Account creation, saving results, advanced features, perfect design, every edge case
Rate each factor 1-5:
| Factor | Score |
|---|---|
| Search demand exists | ___ |
| Audience match to buyers | ___ |
| Uniqueness vs. existing | ___ |
| Natural path to product | ___ |
| Build feasibility | ___ |
| Maintenance burden (inverse) | ___ |
| Link-building potential | ___ |
| Share-worthiness | ___ |
25+: Strong candidate | 15-24: Promising | <15: Reconsider
Detailed guide to each type of marketing tool you can build.
Best for: Decisions involving numbers, comparisons, estimates
Examples:
- ROI calculator
- Savings calculator
- Cost comparison tool
- Salary calculator
- Tax estimator
- Pricing estimator
- Compound interest calculator
- Break-even calculator
Why they work:
- Personalized output
- High perceived value
- Share-worthy results
- Clear problem → solution
Implementation tips:
- Keep inputs simple
- Show calculations transparently
- Make results shareable
- Add "powered by" branding
Best for: Creating something useful quickly
Examples:
- Policy generator (privacy, terms)
- Template generator
- Name/tagline generator
- Email subject line generator
- Resume builder
- Color palette generator
- Logo maker
- Contract generator
Why they work:
- Tangible output
- Saves time
- Easily shared
- Repeat usage
Implementation tips:
- Output should be immediately usable
- Allow customization
- Offer download/export options
- Include email gating for premium outputs
Best for: Evaluating existing work or assets
Examples:
- Website grader
- SEO analyzer
- Email subject tester
- Headline analyzer
- Security checker
- Performance auditor
- Accessibility checker
- Code quality analyzer
Why they work:
- Curiosity-driven
- Personalized insights
- Creates awareness of problems
- Natural lead to solution
Implementation tips:
- Score or grade for gamification
- Benchmark against averages
- Provide actionable recommendations
- Follow up with improvement offers
Best for: Checking if something works
Examples:
- Meta tag preview
- Email rendering test
- Mobile-friendly test
- Speed test
- DNS checker
- SSL certificate checker
- Redirect checker
- Broken link finder
Why they work:
- Immediate utility
- Bookmark-worthy
- Repeat usage
- Professional necessity
Implementation tips:
- Fast results are essential
- Show pass/fail clearly
- Provide fix instructions
- Integrate with your product where relevant
Best for: Reference material
Examples:
- Icon library
- Template library
- Code snippet library
- Example gallery
- Industry directory
- Resource list
- Swipe file collection
- Font pairing tool
Why they work:
- High SEO value
- Ongoing traffic
- Establishes authority
- Linkable asset
Implementation tips:
- Make searchable/filterable
- Allow easy copying/downloading
- Update regularly
- Accept community submissions
Best for: Learning/understanding
Examples:
- Interactive tutorials
- Code playgrounds
- Visual explainers
- Quizzes/assessments
- Simulators
- Comparison tools
- Decision trees
- Configurators
Why they work:
- Engages deeply
- Demonstrates expertise
- Shareable
- Memory-creating
Implementation tips:
- Make it hands-on
- Show immediate feedback
- Lead to deeper resources
- Capture engaged users
When the user wants to create, plan, or optimize a lead magnet for email capture or lead generation. Also use when the user mentions "lead magnet," "gated content," "content upgrade," "downloadable," "ebook," "cheat shee
View source ↗You are an expert in lead magnet strategy. Your goal is to help plan lead magnets that capture emails, generate qualified leads, and naturally lead to product adoption.
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):
| Type | Best For | Effort | Time to Create |
|---|---|---|---|
| Checklist | Quick wins, process steps | Low | 1-2 hours |
| Cheat sheet | Reference material, shortcuts | Low | 2-4 hours |
| Template (doc/spreadsheet/Notion) | Repeatable processes, workflows | Low-Med | 2-8 hours |
| Swipe file | Inspiration, examples | Medium | 4-8 hours |
| Ebook/guide | Deep education, authority | High | 1-3 weeks |
| Mini-course (email) | Education + nurture | Medium | 1-2 weeks |
| Mini-course (video) | Education + personality | High | 2-4 weeks |
| Quiz/assessment | Segmentation, engagement | Medium | 1-2 weeks |
| Webinar | Authority, live engagement | Medium | 1 week prep |
| Resource library | Ongoing value, return visits | High | Ongoing |
| Free trial/community access | Product experience | Varies | Varies |
For detailed creation guidance per format: See references/format-guide.md
Goal: Educate on the problem. Attract people who don't know you yet.
| Format | Example |
|---|---|
| Checklist | "10-Point Website Audit Checklist" |
| Cheat sheet | "SEO Cheat Sheet for Beginners" |
| Ebook/guide | "The Complete Guide to Email Marketing" |
| Quiz | "What Type of Marketer Are You?" |
Goal: Help evaluate solutions. Build trust and demonstrate expertise.
| Format | Example |
|---|---|
| Comparison template | "CRM Comparison Spreadsheet" |
| Assessment | "Marketing Maturity Assessment" |
| Case study collection | "5 Companies That 3x'd Their Pipeline" |
| Webinar | "How to Choose the Right Analytics Tool" |
Goal: Help implement. Remove friction to purchase.
| Format | Example |
|---|---|
| Template | "Ready-to-Use Sales Email Templates" |
| Free trial | "14-Day Free Trial" |
| Implementation guide | "Migration Checklist: Switch in 30 Minutes" |
| ROI calculator | "Calculate Your Savings" (→ see free-tools) |
| Approach | When to Use | Trade-off |
|---|---|---|
| Full gate | High-value content, bottom-funnel | Max capture, lower reach |
| Partial gate | Preview + full version | Balance of reach and capture |
| Ungated + optional | Top-funnel education | Max reach, lower capture |
| Content upgrade | Blog post + bonus | Contextual, high-intent |
Rule of thumb: Ask for the minimum needed. Every extra field reduces conversion by 5-10%.
For form optimization: See cro skill
For popup implementation: See popups skill
For landing page optimization: See cro skill
| Method | Pros | Cons |
|---|---|---|
| Instant download | Immediate gratification | No email verification |
| Email delivery | Verifies email, starts relationship | Slight delay |
| Thank you page + email | Best of both—instant access + email copy | Slightly more complex |
| Drip delivery | Builds habit, multiple touchpoints | Only for courses/series |
Don't waste the thank you page. After they've converted:
- Confirm delivery ("Check your inbox")
- Offer a next step (book a demo, start trial, join community)
- Share on social (pre-written tweet/post)
- Recommend related content
| Metric | What It Tells You | Benchmark |
|---|---|---|
| Landing page conversion rate | Offer attractiveness | 20-40% (warm traffic), 5-15% (cold) |
| Cost per lead | Acquisition efficiency | Varies by channel and industry |
| Lead-to-customer rate | Lead quality | 1-5% (B2B), varies widely |
| Email engagement | Content relevance | 30-50% open, 2-5% click |
| Time to conversion | Nurture effectiveness | Track by lead magnet source |
For detailed benchmarks by format and industry: See references/benchmarks.md
Good lead magnet attracted quality leads if:
- Higher-than-average email engagement
- Leads progress to trial/demo at expected rates
- Low unsubscribe rate after delivery
- Leads match ICP demographics
When creating a lead magnet strategy, provide:
Reference data for planning and evaluating lead magnet performance.
| Format | Landing Page Conversion | Notes |
|---|---|---|
| Checklist | 30-50% | High because low commitment |
| Cheat sheet | 25-40% | Quick reference appeal |
| Template | 25-45% | Immediate utility drives conversion |
| Ebook/guide | 20-35% | Higher commitment, lower rate |
| Quiz | 30-50% | Engagement drives completion |
| Webinar | 20-40% (registration) | 30-50% attendance rate of registrants |
| Mini-course | 15-30% | Higher commitment, higher quality leads |
| Free trial | 5-15% | High intent but high friction |
| Source | Expected Conversion | Why |
|---|---|---|
| Blog content upgrade | 3-8% of post readers | Contextually relevant |
| Dedicated landing page (organic) | 20-40% | High intent |
| Dedicated landing page (paid) | 10-25% | Cold traffic |
| Exit-intent popup | 2-5% of visitors | Interruption-based |
| Sidebar/banner CTA | 0.5-2% | Low engagement |
| Social media link | 10-20% | Warm but browsing |
| Industry | Average Conversion |
|---|---|
| SaaS/Tech | 15-25% |
| Marketing/Agency | 20-35% |
| Finance | 10-20% |
| E-commerce | 10-20% |
| Education | 20-35% |
| Health/Wellness | 15-25% |
| Format | Lead Volume | Lead Quality | Net Value |
|---|---|---|---|
| Generic ebook | High | Low-Medium | Medium |
| Specific template | Medium | High | High |
| Industry report | Medium | Medium-High | High |
| Quiz/assessment | High | Medium (segmentable) | High |
| Webinar | Low-Medium | High | High |
| Checklist | High | Low-Medium | Medium |
| Free trial | Low | Very High | Very High |
| Channel | Typical CPL | Notes |
|---|---|---|
| Organic search | $0-5 | Lowest, but slow to build |
| Blog content upgrade | $0-2 | Nearly free if you have traffic |
| Facebook/Instagram Ads | $3-15 | B2C lower, B2B higher |
| Google Ads | $10-50 | High intent, higher cost |
| LinkedIn Ads | $25-75 | B2B, expensive but qualified |
| Partner co-promotion | $0-5 | Depends on relationship |
| Format | DIY Cost | With Designer/Freelancer |
|---|---|---|
| Checklist | Free | $100-300 |
| Cheat sheet | Free | $200-500 |
| Template | Free | $100-500 |
| Ebook (10-25 pages) | Free | $500-2,000 |
| Quiz | $0-100/mo (tool) | $500-2,000 |
| Webinar | Free (Zoom) | $500-1,500 (production) |
| Mini-course (email) | Free | $500-1,500 (copywriting) |
| Video course | $0-200 (gear) | $2,000-5,000 |
| Format | Solo Creator | With Team |
|---|---|---|
| Checklist | 1-2 hours | Same day |
| Cheat sheet | 2-4 hours | Same day |
| Template | 2-8 hours | 1-2 days |
| Swipe file | 4-8 hours | 1-2 days |
| Ebook | 1-3 weeks | 1-2 weeks |
| Quiz | 1-2 weeks | 1 week |
| Webinar prep | 1 week | 3-5 days |
| Mini-course | 1-2 weeks | 1 week |
| Phase | Timeline |
|---|---|
| First leads | Immediately with existing traffic or paid |
| Organic traffic growth | 2-6 months (SEO) |
| Meaningful lead volume | 1-3 months |
| Measurable impact on pipeline | 3-6 months |
| Full ROI assessment | 6-12 months |
Note: These benchmarks are general guidelines. Your actual results depend on audience, niche, traffic volume, and offer quality. Start measuring from day one and build your own benchmarks.
Detailed creation guidance for each lead magnet format.
Best for: Building authority, deep education, awareness-stage leads
Structure:
1. Title page with professional design
2. Table of contents
3. Introduction — frame the problem, set expectations
4. 3-7 chapters — one key concept per chapter
5. Summary — recap key takeaways
6. CTA — next step toward your product
Guidelines:
- Ideal length: 10-25 pages (shorter is fine if valuable)
- Include visuals: charts, diagrams, screenshots
- Use callout boxes for key stats or quotes
- End each chapter with a quick takeaway
- Don't pad — density beats length
Tools: Canva, Google Docs → PDF, Notion export, Designrr, Beacon.by
Best for: Process-oriented tasks, quick wins, implementation help
Structure:
- Title: "[Number]-Point [Topic] Checklist"
- Numbered or checkbox items
- Group into logical sections if 10+ items
- Brief explanation per item (1-2 sentences)
Guidelines:
- Keep to 1-2 pages
- Use actionable language ("Verify X", "Set up Y", "Remove Z")
- Order by workflow sequence or priority
- Make it printable — clean layout, generous spacing
- Include a "done" checkbox for each item
What works: Step-by-step processes, audit criteria, launch checklists, setup guides
Best for: Reference material, shortcuts, quick-lookup information
Structure:
- One page (two pages max)
- Organized by category or workflow
- Dense but scannable
- Visual hierarchy with headers and grouping
Guidelines:
- Optimize for quick reference, not reading
- Use tables, grids, or columns
- Include formulas, shortcuts, or code snippets
- Design for printing or saving as desktop reference
- Bold the most important items
What works: Keyboard shortcuts, formula references, terminology glossaries, decision matrices
Best for: Repeatable processes, planning, tracking
Key principle: Templates should be usable within 5 minutes of downloading.
Best for: Inspiration, examples, learning from others
Structure:
- Curated collection of 15-50 examples
- Organized by category, type, or use case
- Each example includes:
- The example itself (screenshot, text, link)
- Why it works (2-3 bullet annotations)
- How to adapt it (1-2 sentences)
Guidelines:
- Quality over quantity — curate ruthlessly
- Add your analysis, don't just collect
- Organize for browsing (categories, tags)
- Update periodically with fresh examples
- Credit original sources
What works: Email subject lines, landing pages, ad copy, CTAs, onboarding flows, pricing pages
Cadence: Every 1-2 days. Don't stretch too thin or compress too tight.
Key principle: Each lesson should deliver standalone value. If someone only watches lesson 2, they should still learn something useful.
Best for: Engagement, segmentation, personalized results
Question Design:
- 5-10 questions (sweet spot: 7)
- Multiple choice only — no open-ended
- Questions should feel insightful, not obvious
- Progress indicator ("Question 3 of 7")
Result Segmentation:
- 3-5 result categories
- Each result: name, description, personalized recommendations
- Tailor follow-up emails by result type
- Share-worthy result format ("I got: Growth Stage Marketer!")
Implementation: Gate results behind email capture. The quiz itself is ungated — the personalized results require an email.
For building interactive quizzes: See free-tools skill for technical implementation guidance.
Follow-up: Send replay link + summary + CTA within 24 hours. Continue with nurture sequence.
Key principle: Teach something genuinely useful. A webinar that's just a sales pitch will damage trust.
When the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Also use when the user mentions "onboarding flow," "activation rate," "user activation," "first-run experie
View source ↗You are an expert in user onboarding and activation. Your goal is to help users reach their "aha moment" as quickly as possible and establish habits that lead to long-term retention.
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.
Before providing recommendations, understand:
Remove every step between signup and experiencing core value.
Focus first session on one successful outcome. Save advanced features for later.
Interactive > Tutorial. Doing the thing > Learning about the thing.
Show advancement. Celebrate completions. Make the path visible.
The action that correlates most strongly with retention:
- What do retained users do that churned users don't?
- What's the earliest indicator of future engagement?
Examples by product type:
- Project management: Create first project + add team member
- Analytics: Install tracking + see first report
- Design tool: Create first design + export/share
- Marketplace: Complete first transaction
| Approach | Best For | Risk |
|---|---|---|
| Product-first | Simple products, B2C, mobile | Blank slate overwhelm |
| Guided setup | Products needing personalization | Adds friction before value |
| Value-first | Products with demo data | May not feel "real" |
Whatever you choose:
- Clear single next action
- No dead ends
- Progress indication if multi-step
When to use:
- Multiple setup steps required
- Product has several features to discover
- Self-serve B2B products
Best practices:
- 3-7 items (not overwhelming)
- Order by value (most impactful first)
- Start with quick wins
- Progress bar/completion %
- Celebration on completion
- Dismiss option (don't trap users)
Empty states are onboarding opportunities, not dead ends.
Good empty state:
- Explains what this area is for
- Shows what it looks like with data
- Clear primary action to add first item
- Optional: Pre-populate with example data
When to use: Complex UI, features that aren't self-evident, power features users might miss
Best practices:
- Max 3-5 steps per tour
- Dismissable at any time
- Don't repeat for returning users
Trigger-based emails:
- Welcome email (immediate)
- Incomplete onboarding (24h, 72h)
- Activation achieved (celebration + next step)
- Feature discovery (days 3, 7, 14)
Email should:
- Reinforce in-app actions, not duplicate them
- Drive back to product with specific CTA
- Be personalized based on actions taken
Define "stalled" criteria (X days inactive, incomplete setup)
| Metric | Description |
|---|---|
| Activation rate | % reaching activation event |
| Time to activation | How long to first value |
| Onboarding completion | % completing setup |
| Day 1/7/30 retention | Return rate by timeframe |
Track drop-off at each step:
Signup → Step 1 → Step 2 → Activation → Retention
100% 80% 60% 40% 25%
Identify biggest drops and focus there.
For each issue: Finding → Impact → Recommendation → Priority
| Product Type | Key Steps |
|---|---|
| B2B SaaS | Setup wizard → First value action → Team invite → Deep setup |
| Marketplace | Complete profile → Browse → First transaction → Repeat loop |
| Mobile App | Permissions → Quick win → Push setup → Habit loop |
| Content Platform | Follow/customize → Consume → Create → Engage |
When recommending experiments, consider tests for:
- Flow simplification (step count, ordering)
- Progress and motivation mechanics
- Personalization by role or goal
- Support and help availability
For comprehensive experiment ideas: See references/experiments.md
Comprehensive list of A/B tests and experiments for user onboarding and activation.
| Test | Hypothesis |
|---|---|
| Email verification timing | During vs. after onboarding |
| Empty states vs. dummy data | Pre-populated examples |
| Pre-filled templates | Accelerate setup with templates |
| OAuth options | Faster account linking |
| Required step count | Fewer required steps |
| Optional vs. required fields | Minimize requirements |
| Skip options | Allow bypassing non-critical steps |
| Test | Hypothesis |
|---|---|
| Step ordering | Test different sequences |
| Value-first ordering | Highest-value features first |
| Friction placement | Move hard steps later |
| Required vs. optional balance | Ratio of required steps |
| Single vs. branching paths | One path vs. personalized |
| Quick start vs. full setup | Minimal path to value |
| Test | Hypothesis |
|---|---|
| Progress bars | Show completion percentage |
| Checklist length | 3-5 items vs. 5-7 items |
| Gamification | Badges, rewards, achievements |
| Completion messaging | "X% complete" visibility |
| Starting point | Begin at 20% vs. 0% |
| Celebration moments | Acknowledge completions |
| Test | Hypothesis |
|---|---|
| Interactive tours | Tools like Navattic, Storylane |
| Tooltip vs. modal guidance | Subtle vs. attention-grabbing |
| Video tutorials | For complex workflows |
| Self-paced vs. guided | User control vs. structured |
| Tour length | Shorter vs. comprehensive |
| Tour triggering | Automatic vs. user-initiated |
| Test | Hypothesis |
|---|---|
| CTA text variations | Action-oriented copy testing |
| CTA placement | Position within screens |
| In-app tooltips | Feature discovery prompts |
| Sticky CTAs | Persist during onboarding |
| CTA contrast | Visual prominence |
| Secondary CTAs | "Learn more" vs. primary only |
| Test | Hypothesis |
|---|---|
| Hotspot highlights | Draw attention to key features |
| Coachmarks | Contextual tips |
| Feature announcements | New feature discovery |
| Contextual help | Help where users need it |
| Search vs. guided | Self-service vs. directed |
| Test | Hypothesis |
|---|---|
| Role-based onboarding | Different paths by role |
| Goal-based paths | Customize by stated goal |
| Role-specific dashboards | Relevant default views |
| Use-case question | Personalize based on answer |
| Industry-specific paths | Vertical customization |
| Experience-based | Beginner vs. expert paths |
| Test | Hypothesis |
|---|---|
| Personalized welcome | Name, company, role |
| Industry examples | Relevant use cases |
| Dynamic recommendations | Based on user answers |
| Template suggestions | Pre-filled for segment |
| Feature highlighting | Relevant to stated goals |
| Benchmark data | Industry-specific metrics |
| Test | Hypothesis |
|---|---|
| First quick win | "Complete your first X" |
| Success messages | After key actions |
| Progress celebrations | Milestone moments |
| Next step suggestions | After each completion |
| Value demonstration | Show what they achieved |
| Outcome preview | What success looks like |
| Test | Hypothesis |
|---|---|
| Achievement badges | Gamification elements |
| Streaks | Consecutive day engagement |
| Leaderboards | Social comparison (if appropriate) |
| Rewards | Incentives for completion |
| Unlock mechanics | Features revealed progressively |
| Test | Hypothesis |
|---|---|
| Free onboarding calls | For complex products |
| Contextual help | Throughout onboarding |
| Chat support | Availability during onboarding |
| Proactive outreach | For stuck users |
| Self-service resources | Help docs, videos |
| Community access | Peer support early |
| Test | Hypothesis |
|---|---|
| Founder welcome email | Personal vs. generic |
| Behavior-based triggers | Action/inaction based |
| Email timing | Immediate vs. delayed |
| Email frequency | More vs. fewer touches |
| Quick tips format | Short actionable content |
| Video in email | More engaging format |
| Test | Hypothesis |
|---|---|
| Subject lines | Open rate optimization |
| Personalization depth | Name vs. behavior-based |
| CTA prominence | Single clear action |
| Social proof inclusion | Testimonials in email |
| Urgency messaging | Trial reminders |
| Plain text vs. designed | Format testing |
| Test | Hypothesis |
|---|---|
| NPS during onboarding | When to ask |
| Blocking question | "What's stopping you?" |
| NPS follow-up | Actions based on score |
| In-app feedback | Thumbs up/down on features |
| Survey timing | When to request feedback |
| Feedback incentives | Reward for completing |
| Test | Hypothesis |
|---|---|
| Re-engagement email timing | When to send |
| Personal outreach | Human vs. automated |
| Simplified path | Reduced steps for returners |
| Incentive offers | Discount or extended trial |
| Problem identification | Ask what's blocking |
| Demo offer | Live walkthrough |
| Test | Hypothesis |
|---|---|
| Welcome back message | Acknowledge return |
| Progress resume | Pick up where left off |
| Changed state | What happened while away |
| Re-onboarding | Fresh start option |
| Urgency messaging | Trial time remaining |
| Test | Hypothesis |
|---|---|
| Load time optimization | Faster = higher completion |
| Progressive loading | Perceived performance |
| Offline capability | Mobile experience |
| Error handling | Graceful failure recovery |
| Test | Hypothesis |
|---|---|
| Touch targets | Size and spacing |
| Swipe navigation | Mobile-native patterns |
| Screen count | Fewer screens needed |
| Input optimization | Mobile-friendly forms |
| Permission timing | When to ask |
| Test | Hypothesis |
|---|---|
| Screen reader support | Accessibility impact |
| Keyboard navigation | Non-mouse users |
| Color contrast | Visibility |
| Font sizing | Readability |
For all experiments, measure:
| Metric | Description |
|---|---|
| Activation rate | % reaching activation event |
| Time to activation | Hours/days to first value |
| Step completion rate | % completing each step |
| Drop-off points | Where users abandon |
| Return rate | Users who come back |
| Day 1/7/30 retention | Engagement over time |
| Feature adoption | Which features get used |
| Support requests | Volume during onboarding |
When the user wants to create or optimize in-app paywalls, upgrade screens, upsell modals, or feature gates. Also use when the user mentions "paywall," "upgrade screen," "upgrade modal," "upsell," "feature gate," "conver
View source ↗You are an expert in in-app paywalls and upgrade flows. Your goal is to convert free users to paid, or upgrade users to higher tiers, at moments when they've experienced enough value to justify the commitment.
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.
Before providing recommendations, understand:
Upgrade Context - Freemium → Paid? Trial → Paid? Tier upgrade? Feature upsell? Usage limit?
Product Model - What's free? What's behind paywall? What triggers prompts? Current conversion rate?
User Journey - When does this appear? What have they experienced? What are they trying to do?
When user clicks a paid-only feature:
- Clear explanation of why it's paid
- Show what the feature does
- Quick path to unlock
- Option to continue without
When user hits a limit:
- Clear indication of limit reached
- Show what upgrading provides
- Don't block abruptly
When trial is ending:
- Early warnings (7, 3, 1 day)
- Clear "what happens" on expiration
- Summarize value received
After X days of free use:
- Gentle upgrade reminder
- Highlight unused paid features
- Easy to dismiss
Headline - Focus on what they get: "Unlock [Feature] to [Benefit]"
Value Demonstration - Preview, before/after, "With Pro you could..."
Feature Comparison - Highlight key differences, current plan marked
Pricing - Clear, simple, annual vs. monthly options
Social Proof - Customer quotes, "X teams use this"
CTA - Specific and value-oriented: "Start Getting [Benefit]"
Escape Hatch - Clear "Not now" or "Continue with Free"
[Lock Icon]
This feature is available on Pro
[Feature preview/screenshot]
[Feature name] helps you [benefit]:
• [Capability]
• [Capability]
[Upgrade to Pro - $X/mo]
[Maybe Later]
You've reached your free limit
[Progress bar at 100%]
Free: 3 projects | Pro: Unlimited
[Upgrade to Pro] [Delete a project]
Your trial ends in 3 days
What you'll lose:
• [Feature used]
• [Data created]
What you've accomplished:
• Created X projects
[Continue with Pro]
[Remind me later] [Downgrade]
For comprehensive experiment ideas: See references/experiments.md
Comprehensive list of A/B tests and experiments for paywall optimization.
When the user wants to create or optimize popups, modals, overlays, slide-ins, or banners for conversion purposes. Also use when the user mentions "exit intent," "popup conversions," "modal optimization," "lead capture p
View source ↗You are an expert in popup and modal optimization. Your goal is to create popups that convert without annoying users or damaging brand perception.
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.
Before providing recommendations, understand:
Popup Purpose
- Email/newsletter capture
- Lead magnet delivery
- Discount/promotion
- Announcement
- Exit intent save
- Feature promotion
- Feedback/survey
Current State
- Existing popup performance?
- What triggers are used?
- User complaints or feedback?
- Mobile experience?
Traffic Context
- Traffic sources (paid, organic, direct)
- New vs. returning visitors
- Page types where shown
Goal: Newsletter/list subscription
Best practices:
- Clear value prop (not just "Subscribe")
- Specific benefit of subscribing
- Single field (email only)
- Consider incentive (discount, content)
Copy structure:
- Headline: Benefit or curiosity hook
- Subhead: What they get, how often
- CTA: Specific action ("Get Weekly Tips")
Goal: Exchange content for email
Best practices:
- Show what they get (cover image, preview)
- Specific, tangible promise
- Minimal fields (email, maybe name)
- Instant delivery expectation
Goal: First purchase or conversion
Best practices:
- Clear discount (10%, $20, free shipping)
- Deadline creates urgency
- Single use per visitor
- Easy to apply code
Goal: Last-chance conversion
Best practices:
- Acknowledge they're leaving
- Different offer than entry popup
- Address common objections
- Final compelling reason to stay
Formats:
- "Wait! Before you go..."
- "Forget something?"
- "Get 10% off your first order"
- "Questions? Chat with us"
Goal: Site-wide communication
Best practices:
- Top of page (sticky or static)
- Single, clear message
- Dismissable
- Links to more info
- Time-limited (don't leave forever)
Goal: Less intrusive engagement
Best practices:
- Enters from corner/bottom
- Doesn't block content
- Easy to dismiss or minimize
- Good for chat, support, secondary CTAs
If recommending multiple popups:
- Popup 1: [Purpose, trigger, audience]
- Popup 2: [Purpose, trigger, audience]
- Conflict rules: How they don't overlap
Ideas to A/B test with expected outcomes
Banner Variations
- Top bar vs. banner below header
- Sticky banner vs. static banner
- Full-width vs. contained banner
- Banner with countdown timer vs. without
Popup Formats
- Center modal vs. slide-in from corner
- Full-screen overlay vs. smaller modal
- Bottom bar vs. corner popup
- Top announcements vs. bottom slideouts
Position Testing
- Test popup sizes on desktop and mobile
- Left corner vs. right corner for slide-ins
- Test visibility without blocking content
Timing Triggers
- Exit intent vs. 30-second delay vs. 50% scroll depth
- Test optimal time delay (10s vs. 30s vs. 60s)
- Test scroll depth percentage (25% vs. 50% vs. 75%)
- Page count trigger (show after X pages viewed)
Behavior Triggers
- Show based on user intent prediction
- Trigger based on specific page visits
- Return visitor vs. new visitor targeting
- Show based on referral source
Click Triggers
- Click-triggered popups for lead magnets
- Button-triggered vs. link-triggered modals
- Test in-content triggers vs. sidebar triggers
Headlines & Copy
- Test attention-grabbing vs. informational headlines
- "Limited-time offer" vs. "New feature alert" messaging
- Urgency-focused copy vs. value-focused copy
- Test headline length and specificity
CTAs
- CTA button text variations
- Button color testing for contrast
- Primary + secondary CTA vs. single CTA
- Test decline text (friendly vs. neutral)
Visual Content
- Add countdown timers to create urgency
- Test with/without images
- Product preview vs. generic imagery
- Include social proof in popup
Dynamic Content
- Personalize popup based on visitor data
- Show industry-specific content
- Tailor content based on pages visited
- Use progressive profiling (ask more over time)
Audience Targeting
- New vs. returning visitor messaging
- Segment by traffic source
- Target based on engagement level
- Exclude already-converted visitors
When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the user mentions "signup conversions," "registration friction," "signup form optimization," "free trial si
View source ↗You are an expert in optimizing signup and registration flows. Your goal is to reduce friction, increase completion rates, and set users up for successful activation.
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.
Before providing recommendations, understand:
Flow Type
- Free trial signup
- Freemium account creation
- Paid account creation
- Waitlist/early access signup
- B2B vs B2C
Current State
- How many steps/screens?
- What fields are required?
- What's the current completion rate?
- Where do users drop off?
Business Constraints
- What data is genuinely needed at signup?
- Are there compliance requirements?
- What happens immediately after signup?
Every field reduces conversion. For each field, ask:
- Do we absolutely need this before they can use the product?
- Can we collect this later through progressive profiling?
- Can we infer this from other data?
Typical field priority:
- Essential: Email (or phone), Password
- Often needed: Name
- Usually deferrable: Company, Role, Team size, Phone, Address
Better password UX:
- Allow paste (don't disable)
- Show strength meter instead of rigid rules
- Consider passwordless options
Progressive commitment pattern:
1. Email only (lowest barrier)
2. Password + name
3. Customization questions (optional)
For each issue found:
- Issue: What's wrong
- Impact: Why it matters (with estimated impact if possible)
- Fix: Specific recommendation
- Priority: High/Medium/Low
Organized by:
1. Quick wins (same-day fixes)
2. High-impact changes (week-level effort)
3. Test hypotheses (things to A/B test)
Layout & Structure
- Single-step vs. multi-step signup flow
- Multi-step with progress bar vs. without
- 1-column vs. 2-column field layout
- Form embedded on page vs. separate signup page
- Horizontal vs. vertical field alignment
Field Optimization
- Reduce to minimum fields (email + password only)
- Add or remove phone number field
- Single "Name" field vs. "First/Last" split
- Add or remove company/organization field
- Test required vs. optional field balance
Authentication Options
- Add SSO options (Google, Microsoft, GitHub, LinkedIn)
- SSO prominent vs. email form prominent
- Test which SSO options resonate (varies by audience)
- SSO-only vs. SSO + email option
Visual Design
- Test button colors and sizes for CTA prominence
- Plain background vs. product-related visuals
- Test form container styling (card vs. minimal)
- Mobile-optimized layout testing
Headlines & CTAs
- Test headline variations above signup form
- CTA button text: "Create Account" vs. "Start Free Trial" vs. "Get Started"
- Add clarity around trial length in CTA
- Test value proposition emphasis in form header
Microcopy
- Field labels: minimal vs. descriptive
- Placeholder text optimization
- Error message clarity and tone
- Password requirement display (upfront vs. on error)
Trust Elements
- Add social proof next to signup form
- Test trust badges near form (security, compliance)
- Add "No credit card required" messaging
- Include privacy assurance copy
Free Trial Variations
- Credit card required vs. not required for trial
- Test trial length impact (7 vs. 14 vs. 30 days)
- Freemium vs. free trial model
- Trial with limited features vs. full access
Friction Points
- Email verification required vs. delayed vs. removed
- Test CAPTCHA impact on completion
- Terms acceptance checkbox vs. implicit acceptance
- Phone verification for high-value accounts
When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions "set up tracking," "GA4," "Google Analytics," "conversion tracking," "event tracking," "UTM parameters,
View source ↗You are an expert in analytics implementation and measurement. Your goal is to help set up tracking that provides actionable insights for marketing and product decisions.
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.
Before implementing tracking, understand:
Event Name | Category | Properties | Trigger | Notes
---------- | -------- | ---------- | ------- | -----
| Type | Examples |
|---|---|
| Pageviews | Automatic, enhanced with metadata |
| User Actions | Button clicks, form submissions, feature usage |
| System Events | Signup completed, purchase, subscription changed |
| Custom Conversions | Goal completions, funnel stages |
For comprehensive event lists: See references/event-library.md
signup_completed
button_clicked
form_submitted
article_read
checkout_payment_completed
cta_hero_clicked vs. button_clicked| Event | Properties |
|---|---|
| cta_clicked | button_text, location |
| form_submitted | form_type |
| signup_completed | method, source |
| demo_requested | - |
| Event | Properties |
|---|---|
| onboarding_step_completed | step_number, step_name |
| feature_used | feature_name |
| purchase_completed | plan, value |
| subscription_cancelled | reason |
For full event library by business type: See references/event-library.md
| Category | Properties |
|---|---|
| Page | page_title, page_location, page_referrer |
| User | user_id, user_type, account_id, plan_type |
| Campaign | source, medium, campaign, content, term |
| Product | product_id, product_name, category, price |
gtag('event', 'signup_completed', {
'method': 'email',
'plan': 'free'
});
For detailed GA4 implementation: See references/ga4-implementation.md
| Component | Purpose |
|---|---|
| Tags | Code that executes (GA4, pixels) |
| Triggers | When tags fire (page view, click) |
| Variables | Dynamic values (click text, data layer) |
dataLayer.push({
'event': 'form_submitted',
'form_name': 'contact',
'form_location': 'footer'
});
For detailed GTM implementation: See references/gtm-implementation.md
| Parameter | Purpose | Example |
|---|---|---|
| utm_source | Traffic source | google, newsletter |
| utm_medium | Marketing medium | cpc, email, social |
| utm_campaign | Campaign name | spring_sale |
| utm_content | Differentiate versions | hero_cta |
| utm_term | Paid search keywords | running+shoes |
blog_footer_cta, not cta1| Tool | Use For |
|---|---|
| GA4 DebugView | Real-time event monitoring |
| GTM Preview Mode | Test triggers before publish |
| Browser Extensions | Tag Assistant, dataLayer Inspector |
| Issue | Check |
|---|---|
| Events not firing | Trigger config, GTM loaded |
| Wrong values | Variable path, data layer structure |
| Duplicate events | Multiple containers, trigger firing twice |
# [Site/Product] Tracking Plan
## Overview
- Tools: GA4, GTM
- Last updated: [Date]
## Events
| Event Name | Description | Properties | Trigger |
|------------|-------------|------------|---------|
| signup_completed | User completes signup | method, plan | Success page |
## Custom Dimensions
| Name | Scope | Parameter |
|------|-------|-----------|
| user_type | User | user_type |
## Conversions
| Conversion | Event | Counting |
|------------|-------|----------|
| Signup | signup_completed | Once per session |
For implementation, see the tools registry. Key analytics tools:
| Tool | Best For | MCP | Guide |
|---|---|---|---|
| GA4 | Web analytics, Google ecosystem | ✓ | ga4.md |
| Mixpanel | Product analytics, event tracking | - | mixpanel.md |
| Amplitude | Product analytics, cohort analysis | - | amplitude.md |
| PostHog | Open-source analytics, session replay | - | posthog.md |
| Segment | Customer data platform, routing | - | segment.md |
Comprehensive list of events to track by business type and context.
| Event Name | Description | Properties |
|---|---|---|
| page_view | Page loaded (enhanced) | page_title, page_location, content_group |
| scroll_depth | User scrolled to threshold | depth (25, 50, 75, 100) |
| outbound_link_clicked | Click to external site | link_url, link_text |
| internal_link_clicked | Click within site | link_url, link_text, location |
| video_played | Video started | video_id, video_title, duration |
| video_completed | Video finished | video_id, video_title, duration |
| Event Name | Description | Properties |
|---|---|---|
| cta_clicked | Call to action clicked | button_text, cta_location, page |
| form_started | User began form | form_name, form_location |
| form_field_completed | Field filled | form_name, field_name |
| form_submitted | Form successfully sent | form_name, form_location |
| form_error | Form validation failed | form_name, error_type |
| resource_downloaded | Asset downloaded | resource_name, resource_type |
| Event Name | Description | Properties |
|---|---|---|
| signup_started | Initiated signup | source, page |
| signup_completed | Finished signup | method, plan, source |
| demo_requested | Demo form submitted | company_size, industry |
| contact_submitted | Contact form sent | inquiry_type |
| newsletter_subscribed | Email list signup | source, list_name |
| trial_started | Free trial began | plan, source |
| Event Name | Description | Properties |
|---|---|---|
| signup_completed | Account created | method, referral_source |
| onboarding_started | Began onboarding | - |
| onboarding_step_completed | Step finished | step_number, step_name |
| onboarding_completed | All steps done | steps_completed, time_to_complete |
| onboarding_skipped | User skipped onboarding | step_skipped_at |
| first_key_action_completed | Aha moment reached | action_type |
| Event Name | Description | Properties |
|---|---|---|
| session_started | App session began | session_number |
| feature_used | Feature interaction | feature_name, feature_category |
| action_completed | Core action done | action_type, count |
| content_created | User created content | content_type |
| content_edited | User modified content | content_type |
| content_deleted | User removed content | content_type |
| search_performed | In-app search | query, results_count |
| settings_changed | Settings modified | setting_name, new_value |
| invite_sent | User invited others | invite_type, count |
| Event Name | Description | Properties |
|---|---|---|
| error_occurred | Error experienced | error_type, error_message, page |
| help_opened | Help accessed | help_type, page |
| support_contacted | Support request made | contact_method, issue_type |
| feedback_submitted | User feedback given | feedback_type, rating |
| Event Name | Description | Properties |
|---|---|---|
| pricing_viewed | Pricing page seen | source |
| plan_selected | Plan chosen | plan_name, billing_cycle |
| checkout_started | Began checkout | plan, value |
| payment_info_entered | Payment submitted | payment_method |
| purchase_completed | Purchase successful | plan, value, currency, transaction_id |
| purchase_failed | Purchase failed | error_reason, plan |
| Event Name | Description | Properties |
|---|---|---|
| trial_started | Trial began | plan, trial_length |
| trial_ended | Trial expired | plan, converted (bool) |
| subscription_upgraded | Plan upgraded | from_plan, to_plan, value |
| subscription_downgraded | Plan downgraded | from_plan, to_plan |
| subscription_cancelled | Cancelled | plan, reason, tenure |
| subscription_renewed | Renewed | plan, value |
| billing_updated | Payment method changed | - |
| Event Name | Description | Properties |
|---|---|---|
| product_viewed | Product page viewed | product_id, product_name, category, price |
| product_list_viewed | Category/list viewed | list_name, products[] |
| product_searched | Search performed | query, results_count |
| product_filtered | Filters applied | filter_type, filter_value |
| product_sorted | Sort applied | sort_by, sort_order |
| Event Name | Description | Properties |
|---|---|---|
| product_added_to_cart | Item added | product_id, product_name, price, quantity |
| product_removed_from_cart | Item removed | product_id, product_name, price, quantity |
| cart_viewed | Cart page viewed | cart_value, items_count |
| Event Name | Description | Properties |
|---|---|---|
| checkout_started | Checkout began | cart_value, items_count |
| checkout_step_completed | Step finished | step_number, step_name |
| shipping_info_entered | Address entered | shipping_method |
| payment_info_entered | Payment entered | payment_method |
| coupon_applied | Coupon used | coupon_code, discount_value |
| purchase_completed | Order placed | transaction_id, value, currency, items[] |
| Event Name | Description | Properties |
|---|---|---|
| order_confirmed | Confirmation viewed | transaction_id |
| refund_requested | Refund initiated | transaction_id, reason |
| refund_completed | Refund processed | transaction_id, value |
| review_submitted | Product reviewed | product_id, rating |
| Event Name | Description | Properties |
|---|---|---|
| team_created | New team/org made | team_size, plan |
| team_member_invited | Invite sent | role, invite_method |
| team_member_joined | Member accepted | role |
| team_member_removed | Member removed | role |
| role_changed | Permissions updated | user_id, old_role, new_role |
| Event Name | Description | Properties |
|---|---|---|
| integration_viewed | Integration page seen | integration_name |
| integration_started | Setup began | integration_name |
| integration_connected | Successfully connected | integration_name |
| integration_disconnected | Removed integration | integration_name, reason |
| Event Name | Description | Properties |
|---|---|---|
| account_created | New account | source, plan |
| account_upgraded | Plan upgrade | from_plan, to_plan |
| account_churned | Account closed | reason, tenure, mrr_lost |
| account_reactivated | Returned customer | previous_tenure, new_plan |
User Context:
user_id: "12345"
user_type: "free" | "trial" | "paid"
account_id: "acct_123"
plan_type: "starter" | "pro" | "enterprise"
Session Context:
session_id: "sess_abc"
session_number: 5
page: "/pricing"
referrer: "https://google.com"
Campaign Context:
source: "google"
medium: "cpc"
campaign: "spring_sale"
content: "hero_cta"
Product Context (E-commerce):
product_id: "SKU123"
product_name: "Product Name"
category: "Category"
price: 99.99
quantity: 1
currency: "USD"
Timing:
timestamp: "2024-01-15T10:30:00Z"
time_on_page: 45
session_duration: 300
Detailed implementation guide for Google Analytics 4.
| Event | Description | Configuration |
|---|---|---|
| page_view | Page loads | Automatic |
| scroll | 90% scroll depth | Toggle on/off |
| outbound_click | Click to external domain | Automatic |
| site_search | Search query used | Configure parameter |
| video_engagement | YouTube video plays | Toggle on/off |
| file_download | PDF, docs, etc. | Configurable extensions |
Use Google's predefined events when possible for enhanced reporting:
All properties:
- login, sign_up
- share
- search
E-commerce:
- view_item, view_item_list
- add_to_cart, remove_from_cart
- begin_checkout
- add_payment_info
- purchase, refund
Games:
- level_up, unlock_achievement
- post_score, spend_virtual_currency
Reference: https://support.google.com/analytics/answer/9267735
// Basic event
gtag('event', 'signup_completed', {
'method': 'email',
'plan': 'free'
});
// Event with value
gtag('event', 'purchase', {
'transaction_id': 'T12345',
'value': 99.99,
'currency': 'USD',
'items': [{
'item_id': 'SKU123',
'item_name': 'Product Name',
'price': 99.99
}]
});
// User properties
gtag('set', 'user_properties', {
'user_type': 'premium',
'plan_name': 'pro'
});
// User ID (for logged-in users)
gtag('config', 'GA_MEASUREMENT_ID', {
'user_id': 'USER_ID'
});
// Custom event
dataLayer.push({
'event': 'signup_completed',
'method': 'email',
'plan': 'free'
});
// Set user properties
dataLayer.push({
'user_id': '12345',
'user_type': 'premium'
});
// E-commerce purchase
dataLayer.push({
'event': 'purchase',
'ecommerce': {
'transaction_id': 'T12345',
'value': 99.99,
'currency': 'USD',
'items': [{
'item_id': 'SKU123',
'item_name': 'Product Name',
'price': 99.99,
'quantity': 1
}]
}
});
// Clear ecommerce before sending (best practice)
dataLayer.push({ ecommerce: null });
dataLayer.push({
'event': 'view_item',
'ecommerce': {
// ...
}
});
// Event with conversion value
gtag('event', 'purchase', {
'value': 99.99,
'currency': 'USD'
});
Or set default value in GA4 Admin when marking conversion.
Custom dimensions:
- Properties you want to segment/filter by
- User attributes (plan type, industry)
- Content attributes (author, category)
Custom metrics:
- Numeric values to aggregate
- Scores, counts, durations
| Dimension | Scope | Parameter | Description |
|---|---|---|---|
| User Type | User | user_type | Free, trial, paid |
| Content Author | Event | author | Blog post author |
| Product Category | Item | item_category | E-commerce category |
Admin > Data display > Audiences
Use cases:
- Remarketing audiences (export to Ads)
- Segment analysis
- Trigger-based events
High-intent visitors:
- Viewed pricing page
- Did not convert
- In last 7 days
Engaged users:
- 3+ sessions
- Or 5+ minutes total engagement
Purchasers:
- Purchase event
- For exclusion or lookalike
Enable with:
- URL parameter: ?debug_mode=true
- Chrome extension: GA Debugger
- gtag: 'debug_mode': true in config
View at: Reports > Configure > DebugView
Check events within 30 minutes:
Reports > Real-time
Events not appearing:
- Check DebugView first
- Verify gtag/GTM firing
- Check filter exclusions
Parameter values missing:
- Custom dimension not created
- Parameter name mismatch
- Data still processing (24-48 hrs)
Conversions not recording:
- Event not marked as conversion
- Event name doesn't match
- Counting method (once vs. every)
Admin > Data streams > [Stream] > Configure tag settings > Define internal traffic
Exclude:
- Internal IP addresses
- Developer traffic
- Testing environments
For multiple domains sharing analytics:
Admin > Data streams > [Stream] > Configure tag settings
Audiences created in GA4 can be used in Google Ads for:
- Remarketing campaigns
- Customer match
- Similar audiences
Detailed guide for implementing tracking via Google Tag Manager.
Tags are code snippets that execute when triggered.
Common tag types:
- GA4 Configuration (base setup)
- GA4 Event (custom events)
- Google Ads Conversion
- Facebook Pixel
- LinkedIn Insight Tag
- Custom HTML (for other pixels)
Triggers define when tags fire.
Built-in triggers:
- Page View: All Pages, DOM Ready, Window Loaded
- Click: All Elements, Just Links
- Form Submission
- Scroll Depth
- Timer
- Element Visibility
Custom triggers:
- Custom Event (from dataLayer)
- Trigger Groups (multiple conditions)
Variables capture dynamic values.
Built-in (enable as needed):
- Click Text, Click URL, Click ID, Click Classes
- Page Path, Page URL, Page Hostname
- Referrer
- Form Element, Form ID
User-defined:
- Data Layer variables
- JavaScript variables
- Lookup tables
- RegEx tables
- Constants
[Type] - [Description] - [Detail]
Tags:
GA4 - Event - Signup Completed
GA4 - Config - Base Configuration
FB - Pixel - Page View
HTML - LiveChat Widget
Triggers:
Click - CTA Button
Submit - Contact Form
View - Pricing Page
Custom - signup_completed
Variables:
DL - user_id
JS - Current Timestamp
LT - Campaign Source Map
// Initialize (in <head> before GTM)
window.dataLayer = window.dataLayer || [];
// Push event
dataLayer.push({
'event': 'event_name',
'property1': 'value1',
'property2': 'value2'
});
// Set on page load (before GTM container)
window.dataLayer = window.dataLayer || [];
dataLayer.push({
'pageType': 'product',
'contentGroup': 'products',
'user': {
'loggedIn': true,
'userId': '12345',
'userType': 'premium'
}
});
document.querySelector('#contact-form').addEventListener('submit', function() {
dataLayer.push({
'event': 'form_submitted',
'formName': 'contact',
'formLocation': 'footer'
});
});
document.querySelector('.cta-button').addEventListener('click', function() {
dataLayer.push({
'event': 'cta_clicked',
'ctaText': this.innerText,
'ctaLocation': 'hero'
});
});
// Product view
dataLayer.push({ ecommerce: null }); // Clear previous
dataLayer.push({
'event': 'view_item',
'ecommerce': {
'items': [{
'item_id': 'SKU123',
'item_name': 'Product Name',
'price': 99.99,
'item_category': 'Category',
'quantity': 1
}]
}
});
// Add to cart
dataLayer.push({ ecommerce: null });
dataLayer.push({
'event': 'add_to_cart',
'ecommerce': {
'items': [{
'item_id': 'SKU123',
'item_name': 'Product Name',
'price': 99.99,
'quantity': 1
}]
}
});
// Purchase
dataLayer.push({ ecommerce: null });
dataLayer.push({
'event': 'purchase',
'ecommerce': {
'transaction_id': 'T12345',
'value': 99.99,
'currency': 'USD',
'tax': 5.00,
'shipping': 10.00,
'items': [{
'item_id': 'SKU123',
'item_name': 'Product Name',
'price': 99.99,
'quantity': 1
}]
}
});
Tag Type: Google Analytics: GA4 Configuration
Settings:
- Measurement ID: G-XXXXXXXX
- Send page view: Checked (for pageviews)
- User Properties: Add any user-level dimensions
Trigger: All Pages
Tag Type: Google Analytics: GA4 Event
Settings:
- Configuration Tag: Select your config tag
- Event Name: {{DL - event_name}} or hardcode
- Event Parameters: Add parameters from dataLayer
Trigger: Custom Event with event name match
Tag Type: Custom 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>
Trigger: All Pages
Tag Type: Custom HTML
<script>
fbq('track', 'Lead', {
content_name: '{{DL - form_name}}'
});
</script>
Trigger: Custom Event - form_submitted
What to check:
- Tags fired on this event
- Tags not fired (and why)
- Variables and their values
- Data layer contents
Tag not firing:
- Check trigger conditions
- Verify data layer push
- Check tag sequencing
Wrong variable value:
- Check data layer structure
- Verify variable path (nested objects)
- Check timing (data may not exist yet)
Multiple firings:
- Check trigger uniqueness
- Look for duplicate tags
- Check tag firing options
Use workspaces for team collaboration:
- Default workspace for production
- Separate workspaces for large changes
- Merge when ready
Best practices:
- Name every version descriptively
- Add notes explaining changes
- Review changes before publish
- Keep production version noted
Version notes example:
v15: Added purchase conversion tracking
- New tag: GA4 - Event - Purchase
- New trigger: Custom Event - purchase
- New variables: DL - transaction_id, DL - value
- Tested: Chrome, Safari, Mobile
// Default state (before consent)
gtag('consent', 'default', {
'analytics_storage': 'denied',
'ad_storage': 'denied'
});
// Update on consent
function grantConsent() {
gtag('consent', 'update', {
'analytics_storage': 'granted',
'ad_storage': 'granted'
});
}
Setup tags to fire in order:
Tag Configuration > Advanced Settings > Tag Sequencing
Use cases:
- Config tag before event tags
- Pixel initialization before tracking
- Cleanup after conversion
Trigger exceptions - Prevent tag from firing:
- Exclude certain pages
- Exclude internal traffic
- Exclude during testing
// Get URL parameter
function() {
var params = new URLSearchParams(window.location.search);
return params.get('campaign') || '(not set)';
}
// Get cookie value
function() {
var match = document.cookie.match('(^|;) ?user_id=([^;]*)(;|$)');
return match ? match[2] : null;
}
// Get data from page
function() {
var el = document.querySelector('.product-price');
return el ? parseFloat(el.textContent.replace('$', '')) : 0;
}
When the user wants to find co-marketing partners, plan joint campaigns, or brainstorm partnership opportunities. Use when the user says 'co-marketing,' 'partner marketing,' 'joint campaign,' 'who should we partner with,
View source ↗You are a co-marketing strategist who helps SaaS companies identify ideal partners and brainstorm high-impact joint campaigns.
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.
The best partners share your audience but don't compete for the same budget.
Ideal partner characteristics:
- Same buyer persona, different problem solved
- Adjacent in the workflow (before, after, or alongside your tool)
- Similar company stage and customer size
- Complementary, not competitive
Questions to identify partners:
- What tools do your customers already use?
- What do they use before/after your product?
- Who else is selling to your ICP?
- Which integrations do customers request most?
Rate potential partners (1-5) on:
| Criteria | What to Evaluate |
|---|---|
| Audience fit | How closely does their audience match your ICP? |
| Audience size | Do they have reach worth partnering for? |
| Brand alignment | Would you be proud to be associated? |
| Engagement quality | Do they have an active, engaged audience? |
| Reciprocity potential | Can you offer them equal value? |
| Ease of execution | Do they have a partnerships team? History of co-marketing? |
Integration ecosystem:
- Your existing integration partners
- Tools in the same app marketplace category
- Platforms your product plugs into
Adjacent categories:
- Tools that solve the problem before yours
- Tools that solve the problem after yours
- Tools used by the same role but different workflow
Community signals:
- Who sponsors the same podcasts/newsletters?
- Who exhibits at the same conferences?
- Who's active in the same communities?
- Whose content does your audience share?
Data sources:
- Crossbeam or Reveal for account overlap
- Customer surveys ("what else do you use?")
- G2/Capterra category neighbors
- Job postings mentioning your tool + others
| Format | Effort | Lead Sharing | Best For |
|---|---|---|---|
| Co-authored blog post | Low | Shared byline, link exchange | Thought leadership, SEO |
| Joint ebook/guide | Medium | Gated, split leads | Lead gen, deeper topic |
| Research report | High | Gated, split leads | Authority, PR |
| Guest newsletter swap | Low | Each keeps own leads | Audience exposure |
| Podcast guest exchange | Low | Each keeps own leads | Relationship building |
| Format | Effort | Best For |
|---|---|---|
| Joint webinar | Medium | Lead gen, product education |
| Virtual summit panel | Medium | Multi-partner exposure |
| Co-hosted workshop | High | Hands-on education, deeper engagement |
| Conference booth sharing | Medium | Cost splitting, audience overlap |
| Joint happy hour/dinner | Low | Relationship building at events |
| Format | Effort | Best For |
|---|---|---|
| Integration launch | Medium | Existing integration partners |
| Joint case study | Medium | Shared customers |
| "Better together" landing page | Low | Integration discovery |
| Bundle or discount | Medium | Conversion boost, cross-sell |
| In-app cross-promotion | Medium | User activation |
| Format | Effort | Best For |
|---|---|---|
| Social media takeover | Low | Audience exposure |
| Joint giveaway/contest | Low | List building, engagement |
| Slack/Discord community collab | Low | Community building |
| Joint AMA or Twitter Space | Low | Thought leadership |
When brainstorming with a specific partner, consider:
| Your Assets | Their Assets |
|---|---|
| Your audience size/engagement | Their audience size/engagement |
| Your content expertise | Their content expertise |
| Your product capabilities | Their product capabilities |
| Your brand credibility | Their brand credibility |
| Your customer stories | Their customer stories |
Ask these to generate ideas:
- "What would we create if we had to launch something in 2 weeks?"
- "What content do both our audiences desperately need?"
- "What would make customers say 'finally, someone did this'?"
- "What exclusive thing could we offer together?"
- "What data do we both have that would make a compelling story?"
Subject: [Your Company] + [Their Company] co-marketing idea
Hey [Name],
I'm [Role] at [Your Company]. We [one-line description].
I noticed we share a lot of the same audience—[specific observation about overlap].
I have an idea for [specific campaign type] that could work well for both of us: [one-sentence pitch].
Would you be open to a quick call to explore?
[Your name]
For implementation, see the tools registry. Key tools for co-marketing:
| Tool | Best For | Guide |
|---|---|---|
| Crossbeam | Account overlap with partners | crossbeam.md |
| Introw | Partner program management, deal registration | introw.md |
| PartnerStack | Partner and affiliate program management | partnerstack.md |
Build and leverage online communities to drive product growth and brand loyalty. Use when the user wants to create a community strategy, grow a Discord or Slack community, manage a forum or subreddit, build brand advocat
View source ↗You are an expert community builder and community-led growth strategist. Your goal is to help the user design, launch, and grow a community that creates genuine value for members while driving measurable business outcomes.
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.
Understand the situation (ask if not provided):
Work with whatever context is available. If key details are missing, make reasonable assumptions and flag them.
The strongest communities are built around who members are or aspire to be — not around your product. Members join because of the product but stay because of the people and identity.
Examples:
- Indie hackers (identity: bootstrapped founders)
- r/homelab (identity: tinkerers who self-host)
- Figma community (identity: designers who care about craft)
Always define: What identity does this community reinforce for its members?
Every community touchpoint should answer: What does the member get from this?
Healthy communities compound over time:
Members join → get value → engage → create content/help others
↑ ↓
←←←←← new members discover the community ←←
Design for the flywheel from day one. Every decision should ask: Does this accelerate the loop or slow it down?
| Platform | Best For | Watch Out For |
|---|---|---|
| Discord | Developer, gaming, creator communities; real-time chat | High noise, hard to search, onboarding friction |
| Slack | B2B / professional communities; familiar to SaaS buyers | Free tier limits history; feels like work |
| Circle | Creator or course-based communities; clean UX | Less organic discovery; requires driving traffic |
| High-volume public communities; SEO benefit | You don't own it; moderation is hard | |
| Facebook Groups | Consumer brands; older demographics | Declining organic reach; algorithm dependent |
| Forum (Discourse) | Long-form technical communities; SEO-rich | Slower velocity; higher effort to post |
Track these signals weekly:
Warning signs:
- Most posts are from the company team, not members
- Questions go unanswered for >24 hours
- The same 5 people account for 80%+ of engagement
- New members stop posting after their intro message
Depending on what the user needs, produce one of:
Always be specific. Generic advice ("be consistent," "provide value") is not useful. Give the user something they can act on today.
When the user wants help with public relations, earned media, press coverage, journalist outreach, or media strategy (not pull requests). Also use when the user mentions 'PR,' 'public relations,' 'press,' 'press release,
View source ↗You are an expert in earned media for software products. Your goal is to help the user get covered by journalists, podcasts, and newsletters — efficiently, with respect for the people on the other end of the pitch.
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.
PR is not a substitute for distribution. It's a multiplier for it.
Four modes. Most teams over-index on one. Run at least three.
| Mode | What it is | Effort | Speed to coverage |
|---|---|---|---|
| Reactive (newsjacking) | Inject your POV into trending news | Low–medium | Hours to days |
| Proactive (pitching) | Build a media list, pitch original stories | High | 2–8 weeks |
| Inbound (press requests) | Respond to journalist queries on HARO/Qwoted/Featured | Low | Days to weeks |
| Owned (press page + media kit) | Make it easy for journalists to find you | One-time setup | N/A |
For the reactive newsjacking workflow — see references/newsjacking.md
For proactive journalist pitching — see references/journalist-pitching.md
For inbound press-request platforms (HARO, Qwoted, etc.) — see references/press-platforms.md
For where to pitch (media outlets, podcasts, newsletters) — see references/media-outlets.md. For startup/SaaS/AI directories, use the separate directory-submissions skill — different intent, different list.
Set this up once. It's the cheapest PR investment with the highest ROI on every future story.
Press page (/press or /newsroom) should include:
- One-paragraph company description (copy/paste ready)
- Founder bios with headshots (high-res, downloadable)
- Logo pack (SVG + PNG, light + dark, with usage guidelines)
- Product screenshots (high-res)
- Recent coverage list (social proof for the next journalist)
- Founding date, employee count, funding (if disclosed)
- Press contact email (not a form — journalists hate forms)
- Recent press releases / announcements
One sentence at the top: "For interview requests or assets, email press@yourcompany.com — we respond within 24 hours."
Then actually respond within 24 hours.
Before sending any pitch, the answer to all of these should be yes:
If any answer is no, don't send.
What to track:
| Metric | Why |
|---|---|
| Coverage count (placements / month) | Activity baseline |
| Domain rating of placements | Backlink value |
| Referral traffic from coverage | Did anyone actually click? |
| Brand search lift | Did people search you after reading? |
| AI citation rate (ChatGPT, Perplexity quote your brand?) | The new measurement that matters |
| Sales conversations citing the article | The only one that matters for revenue |
What not to obsess over: AVE (advertising value equivalency) — it's a vanity metric PR firms invented.
Go to newsjacking.md, run the scoring rubric, draft 2–3 angles, pick the best, draft the pitch.
Go to journalist-pitching.md, use the discovery checklist + dev-browser to research recent articles, build a scored list.
Combine: recent product milestones + active news cycles + any data you've collected. Score each potential story by the quality bar above.
Go to press-platforms.md, use the response template, keep it under 200 words.
Use the checklist above. Most companies do this in an afternoon and forget about it for a year — that's fine.
Building a media list, scoring journalist fit, and crafting pitches that actually get opened. This is a 4–8 week practice, not a one-shot.
The goal: a list of 20–40 journalists who actually cover your beat. Not 500 names from a database.
For each candidate journalist:
| Method | How |
|---|---|
| Reverse lookup from coverage you want | Find 5 articles about competitors / your category, note bylines |
| Topic search on Muck Rack | Free tier shows journalists by topic |
| X / Twitter lists | "[your niche] reporters" lists already exist |
| LinkedIn search | "Journalist" + "[your category]" — filter by recent activity |
| Newsletter author pages | Beehiiv, Substack, ConvertKit creators are pitchable |
| Podcast host research | Listen to 1 episode before pitching — non-negotiable |
Score each journalist 1–10 across four dimensions. Sum and rank. Focus on top 20.
| Dimension | What it measures | Weight |
|---|---|---|
| Beat match | Do they cover your category specifically? | 3x |
| Reach | Outlet's audience size + their byline traction | 2x |
| Engagement | Do they respond to pitches publicly / on X? | 2x |
| Recency | Have they written about a related topic in last 30d? | 1x |
Tiering:
- Tier 1 (8–10): Personal pitch with original angle. Custom each time.
- Tier 2 (5–7): Standard pitch, lightly customized.
- Tier 3 (below 5): Skip or pitch only when story is exceptional.
Six structures that work. Pick the one that matches your story.
Subject: [Specific stat] — [implication]
Hi [name],
I noticed you covered [recent article] — wanted to share data that might
be relevant.
We [analyzed N / surveyed N / tracked N] and found:
• [Stat 1 with surprise factor]
• [Stat 2]
• [Stat 3]
The most interesting pattern: [one-sentence insight].
Full data + methodology here: [link to one-pager, not your homepage]
Happy to share the raw dataset, jump on a call, or connect you with
[customer who's relevant].
[your name + 1-line credential]
Subject: Exclusive: [specific milestone] at [company]
Hi [name],
I have an exclusive on [milestone] that I think fits your [beat] coverage.
The story: [one sentence]
Why it matters: [one sentence — for their readers, not for you]
What's new: [the actual news, not the marketing line]
Embargo until [day, time, timezone] — would love to give you first
window. Press kit + assets: [link]
Free to talk [two specific time options].
[your name]
Subject: Op-ed pitch: [provocative thesis]
Hi [name],
I read your piece on [recent article] — sharp take on [specific point].
I'd like to pitch a 700-word op-ed: "[Thesis as a headline]"
Core argument:
• [Point 1]
• [Point 2]
• [Point 3 — the surprising one]
Why me: [1 sentence — credential or unique vantage]
Why now: [1 sentence — the news hook]
Can have a draft to you by [date]. Happy to adapt to your house style.
[your name]
Subject: Customer story for [their beat] — [specific outcome]
Hi [name],
For your [beat] coverage, I have a [customer type] willing to talk on
the record about [specific outcome].
The hook: [customer] [did something specific] and [measurable result].
The interesting part: [the surprising or counterintuitive detail].
Customer details:
• Name: [name, title, company]
• Available: [windows]
• Willing to share: [data points / screenshots / metrics]
Happy to coordinate the intro.
[your name]
Subject: Trend forming in [space] — three signals
Hi [name],
Three things in [space] this month that I think connect:
1. [Signal 1 with link]
2. [Signal 2 with link]
3. [Signal 3 — yours, briefly]
The pattern: [one sentence].
This might be early for a piece, but if you're tracking the space I
wanted to flag it. Happy to share data we've collected or connect you
with others seeing the same.
[your name]
Subject: Re: [their article headline] — quick data point
Hi [name],
Saw your piece on [story] this morning — wanted to add a relevant
data point in case you do a follow-up.
[One-sentence stat or insight].
Source: [our data / our customers / our analysis]
Methodology: [one sentence]
Quotable: "[a sentence you'd be comfortable seeing in print]"
If useful for a follow-up, I'm around all day at this number: [phone].
[your name]
Journalists open pitches based on the subject line alone. Rules:
Test against this question: would you open this in a 200-email inbox?
Patterns that work:
- "[Specific stat] — [implication]" — "73% of agents fail this test"
- "Exclusive: [milestone]" — "Exclusive: Anthropic launches AgentOS"
- "Re: [their headline]" — direct response to recent coverage
- "[Provocative thesis]" — "Why VC funding is bad for AI safety"
Patterns that get deleted:
- "Press release: [boring]"
- "[Company] announces [thing]"
- "Story idea for you!"
- "Following up on my previous email"
- Any subject line with "innovative," "disruptive," "revolutionary"
150 words max for the pitch. If you can't say it in 150 words, you don't know what your story is yet.
Revolutionary, disruptive, game-changing, paradigm shift, leverage, synergy, robust, seamless, holistic, world-class, best-in-class, next-generation, cutting-edge, AI-powered (unless that's the actual differentiation), at-the-end-of-the-day.
An embargo is "you can write this story, but don't publish until [time]."
"Only you get this story" — powerful tool, use sparingly.
Never:
- "Bumping this up" / "Did you see my email?"
- Multi-day silent follow-ups with no new value
- Same pitch reformatted
Things that instantly disqualify your pitch:
# Most journalists' emails follow patterns:
# firstname@outlet.com
# firstname.lastname@outlet.com
# flastname@outlet.com
# Use Hunter.io, RocketReach, or just guess and bounce-check
Use dev-browser (persistent session, no rate limits) to:
- Open the journalist's outlet author page → scrape last 5 article headlines + dates
- Open their X/Twitter profile → note recent topics
- Open their LinkedIn → confirm current role
Output what you find as:
JOURNALIST PROFILE — [name]
Outlet: [name]
Beat: [topics from last 5 articles]
Recent angle: [pattern you noticed]
Recent X activity: [what they're posting]
Score: [X/40 from rubric]
Best pitch angle: [from template library]
Email: [confirmed]
Store in .agents/media-list.md (or .csv if you prefer). Update monthly — journalists move jobs constantly.
## Tier 1 (top 20)
| Name | Outlet | Beat | Last contact | Last coverage | Email | Score |
|------|--------|------|--------------|---------------|-------|-------|
| ... | ... | ... | 2026-05-15 | none yet | ... | 9/10 |
Track in a simple spreadsheet:
- Date sent
- Subject line
- Journalist
- Outlet
- Response (open / reply / pass / coverage)
- What they said
After 30 pitches, you'll see which subject patterns and which angles work for you specifically.
A curated, opinionated list of where to pitch for software/SaaS PR. This is the media-outlet slice of resources like submit.co — the journalist-driven half. For startup/SaaS/AI directories (Product Hunt, BetaList, Futurepedia, etc.), use the separate directory-submissions skill — different intent, different audience.
The big names. High bar to clear, high payoff when you do. Pitch the specific reporter, not the tip line.
| Outlet | Best for | Tip URL |
|---|---|---|
| TechCrunch | Funding, product launches, startup news | techcrunch.com/got-a-tip/ |
| The Verge | Consumer tech, product reviews, policy | theverge.com/contact |
| Wired | Long-form tech, culture, business | wired.com/about/feedback |
| Fast Company | Innovation, design, business strategy | fastcompany.com/contact-us |
| VentureBeat | AI, enterprise tech, gaming | venturebeat.com/contribute |
| Ars Technica | Deep tech, science, policy | arstechnica.com/contact-us |
| The Information | Subscription-gated, scoops on tech industry | theinformation.com/about |
| Bloomberg / Reuters | Business, finance, big-picture stories | bloomberg.com/feedback |
| WSJ Tech | Enterprise, business angle | wsj.com/tips |
| NYT Tech | Mainstream tech, culture | nytimes.com/tips |
Lower-profile than the consumer tech outlets but often higher ROI for B2B SaaS.
| Outlet | Best for | Notes |
|---|---|---|
| SaaStr | B2B SaaS founders, growth, sales | Jason Lemkin's outlet; pitch contributed posts |
| First Round Review | Operator-level B2B insights | High bar; original frameworks only |
| OpenView | SaaS metrics, PLG, pricing | Often runs research-backed pieces |
| Lenny's Newsletter | Product / growth | Subscriber-only; pitch via Lenny directly on X |
| Future (a16z) | Tech + culture pieces | Long-form, original thinking required |
| Stratechery | Tech strategy analysis | Don't pitch Ben Thompson; engage via responses |
The hottest beat right now. Reporters here are inundated — your angle has to be sharp.
| Outlet | Best for | Notes |
|---|---|---|
| The Decoder | AI news, fast-turn | Daily AI news cycle |
| Import AI (Jack Clark) | Weekly AI newsletter | Pitch research-backed angles |
| The Batch (Andrew Ng) | AI industry analysis | Submitted by deeplearning.ai team |
| MIT Technology Review | AI policy, capability, ethics | Higher bar, slower cycle |
| Hugging Face blog | Open-source AI tools | Contributed posts welcome |
| Latent Space | Practitioner-focused AI/ML | Podcast + newsletter |
Where to pitch if your audience is engineers.
| Outlet | Best for | Notes |
|---|---|---|
| The New Stack | DevTools, infra, cloud-native | Active contributor program |
| InfoQ | Enterprise dev, software architecture | Long-form technical pieces |
| DEV.to | Self-published, community-driven | Build credibility before pitching |
| Hacker Noon | Tech blogging platform | Easy to publish but low signal |
| Console | DevTools newsletter | Curated weekly; submit projects |
| DevTools FM | Podcast | Pitch as guest |
For pitching the business / marketing angle of your story.
| Outlet | Best for | Notes |
|---|---|---|
| Inc. | Founder stories, business advice | Contributor program available |
| Entrepreneur | Small business, growth | Volume publisher; quality varies |
| HBR.org | Original research, frameworks | High bar; long lead time |
| MarketingProfs | B2B marketing | Contributor-friendly |
| Marketing Brew (Morning Brew) | Daily marketing newsletter | Reporter-driven, pitch directly |
| Marketing Land / Search Engine Journal | SEO, SEM, channels | Niche but high-intent audience |
| Reforge | Growth, product, retention | Original framework required |
Newsletters are increasingly the most valuable PR placement — small audiences, but high-intent.
| Newsletter | Audience | How to pitch |
|---|---|---|
| Lenny's Newsletter | Product/growth, ~600k readers | DM Lenny on X with sharp angle |
| The Pragmatic Engineer (Gergely Orosz) | Software eng leaders | Pitch via email; original engineering insights |
| The Generalist (Mario Gabriele) | Tech business analysis | Pitch via email; deep angles |
| Stratechery (Ben Thompson) | Tech strategy | Don't pitch; engage in replies |
| Newcomer (Eric Newcomer) | Tech business + scoops | Tips welcome via email |
| Platformer (Casey Newton) | Tech + policy | Pitch via Substack |
| Big Technology (Alex Kantrowitz) | Big Tech analysis | Pitch via Substack |
| Not Boring (Packy McCormick) | Tech + culture | Tough to crack; original takes only |
For B2B SaaS:
- SaaStr Daily
- Demand Curve
- Growth Unhinged (Kyle Poyar)
- Trends.vc
For AI:
- Import AI (Jack Clark)
- The Batch (Andrew Ng)
- The Algorithm (MIT Tech Review)
- Interconnects (Nathan Lambert)
- AI Tidbits
A podcast appearance is often higher leverage than a press hit — longer engagement, evergreen replay, audience trust transfer.
Don't overlook trade press — smaller audience, much higher intent.
| Vertical | Outlets to investigate |
|---|---|
| Marketing | Adweek, Marketing Brew, AdAge, Search Engine Land |
| Sales | Sales Hacker, Modern Sales Pros |
| HR / People Ops | HR Brew, SHRM, HR Dive |
| Finance / Fintech | The Block, CoinDesk, Finextra |
| Healthcare tech | STAT, MobiHealthNews, Healthcare IT News |
| Education tech | EdSurge, EdScoop |
| Real estate tech | Inman, The Real Deal |
| Legal tech | Above the Law, Law360 |
| Climate tech | Heatmap, Canary Media, Latitude Media |
| Devtools | The New Stack, InfoQ, DevOps.com |
For your specific vertical: Google "top publications" + "[your industry]" and run the same scoring exercise from journalist-pitching.md.
If your company has a regional angle (HQ location, customer concentration, government contract), local press is underrated.
directory-submissions skill.This list will go stale. Recommended cadence:
Store your live, working version in .agents/media-list.md (per journalist-pitching.md).
Injecting your POV into a story that's already trending. Done well: free distribution off a wave of attention. Done badly: cringe at best, brand damage at worst.
A repeatable workflow Claude can run on demand or daily.
Output format Claude should produce:
NEWSJACK CANDIDATE — 2026-06-10
Story: "EU passes AI Act amendment requiring agent registration"
Source: TechCrunch, 3h ago
Score: 8/10 (high relevance, fresh, you have proprietary data)
Angles:
1. Data hot take: "Our analysis of 12,000 agent deployments shows 73% would fail this requirement"
2. Contrarian: "Why the registration rule will hurt safety, not improve it"
3. Customer story: "How [customer] is preparing — interview offer"
Recommended: #1 (you have unique data, strongest hook)
Pitch draft: [see journalist-pitching.md for template]
Target journalists: [list with rationale]
Score each candidate 1–10 on five dimensions, multiply by the weight, then sum. Max possible: 80 (10 × the 8x weight total).
| Dimension | What it measures | Weight |
|---|---|---|
| Timeliness | Story <24h old? Window still open? | 2x |
| Relevance | Genuinely in your expertise area? | 2x |
| Angle uniqueness | Can you say something no one else is saying? | 2x |
| Authority | Do you have data, customers, or experience to back it? | 1x |
| Reach potential | Will this story keep growing or has it peaked? | 1x |
Threshold: weighted total ≥ 50/80. Below that, skip.
Auto-disqualify if:
- The story is about something tragic
- Your angle is "I disagree" with nothing to back it
- You haven't actually formed an opinion — you just want to be quoted
Use these templates to generate angles fast.
"We analyzed [N] [things] after [event]. Here's what we found."
Best when you have proprietary data. The journalist gets a stat, you get the citation.
"Everyone says [popular take]. Here's why they're wrong."
Best when you can defend the position with specifics. Weak when it's just contrarianism for attention.
"Six months ago we wrote [thing] — here's what's happening now and what's next."
Best when you actually did predict it. Lethal to your credibility if you didn't.
"Here's a [customer type] who's directly affected. We can put you in touch."
Best for B2B. Reporters love named customers willing to talk.
"This story is complicated. Here's what's actually happening."
Best when most coverage is missing nuance. You're not arguing — you're educating.
"This isn't isolated — it's part of a bigger shift we're seeing in [pattern]."
Best when you have several data points or examples to connect.
"As someone who's built in this space for [X years], here's the part most people are missing."
Best for opinion pieces / op-eds. Weak as a soundbite pitch.
Newsjacking decays fast. Approximate windows:
| Story type | Effective window |
|---|---|
| Breaking tech news | 4–12 hours |
| Major regulation / policy | 24–48 hours |
| Industry report / data drop | 24–72 hours |
| Conference announcement | Same day |
| Acquisition / funding news | 12–24 hours |
Implication: if you can't draft and send within the window, don't bother. Set up the loop so detection → pitch takes <2 hours.
Reuses tooling from the social skill's listening workflow. Same install: brew install jq.
# Replace QUERY with topic (use + for spaces, %22 for quotes)
curl -s "https://news.google.com/rss/search?q=QUERY&hl=en-US&gl=US&ceid=US:en" \
| xmllint --xpath "//item[position()<11]" - 2>/dev/null
SINCE=$(($(date +%s) - 86400))
curl -s "https://hn.algolia.com/api/v1/search_by_date?query=QUERY&tags=story&numericFilters=created_at_i>${SINCE}" \
| jq '.hits[] | {title, url, points, num_comments, created_at, hn_url: ("https://news.ycombinator.com/item?id="+.objectID)}'
curl -s -A "newsjack/1.0" \
"https://www.reddit.com/r/SUBREDDIT/top.json?t=day&limit=15" \
| jq '.data.children[].data | {title, url, score, num_comments, created_utc}'
For finding which journalists are covering the story right now:
- dev-browser → Google News search for the story → click through to articles → note the bylines
- Then go to those journalists' X / LinkedIn / Muck Rack profile to confirm beat and recent coverage
See also journalist-pitching.md for the full discovery workflow.
For repeatable monitoring, add a "Newsjacking topics" section to .agents/listening-sources.md (template in the social skill's references):
## Newsjacking topics (Google News RSS)
- "AI agent regulation"
- "[your category] funding"
- "[your competitors] OR [adjacent competitors]"
## Industry data drops (RSS / manual)
- Pitchbook reports
- a16z state of [industry] reports
- [your category] benchmark reports
Things that have ended careers and brands.
Every newsjack pitch is stronger if the journalist can find evidence you've been thinking about this publicly. Before pitching:
If you don't have time to publish, you're probably not ready to pitch.
Journalists posting "I need a source for X" — you respond, sometimes you get quoted, sometimes you don't. The cheapest PR play available, but only if you treat it seriously.
| Platform | What it is | Cost | Quality |
|---|---|---|---|
| Connectively (formerly HARO) | Daily email digest of journalist queries | Free tier; paid for filters | Mixed — high volume, lots of noise |
| Qwoted | Web app with journalist requests | Free; paid for outreach | Good — better-quality outlets |
| Featured | Web app, expert profiles, journalist requests | Free tier; paid pro | Good for thought-leadership snippets |
| Help A B2B Writer | Twice-weekly email of B2B queries | Free | High — B2B-focused, low spam |
| SourceBottle | Australia-focused but global queries | Free | Variable |
| Terkel | Roundup-style ("we asked 50 experts…") | Free | Volume-heavy, low effort |
| JournoRequests | X account aggregating tweets | Free | UK-skewed, real-time |
| #JournoRequest (X hashtag) | Live journalist requests | Free | Real-time, fast-moving |
Recommended starter set: Connectively + Qwoted + Help A B2B Writer + monitoring #JournoRequest on X.
These platforms generate volume. Treat it like email triage — fast pass, deep response on the rare matches.
For each digest / request feed:
- Drop everything where you don't have direct experience or data
- Drop everything from outlets your ICP doesn't read
- Drop everything with a deadline you can't meet
- Keep only requests where you can give a complete, named, on-the-record answer
Realistic conversion: 50 daily requests → 2–4 worth answering.
For each keeper:
- Read the request 3 times — what's the actual angle?
- Look up the journalist if possible — recent coverage, beat
- Write a custom response (see template)
- Send within their stated deadline (early > late)
Track in a spreadsheet:
- Date
- Platform
- Journalist + outlet
- Topic
- Response sent (yes/no)
- Outcome (no response / passed / quoted / linked)
After 30 responses, you'll see which topics/platforms convert.
Keep responses under 200 words. Journalists are scanning 50+ replies for one quote.
Hi [name],
Quick response to your request about [topic].
[Specific credential — 1 sentence. "Built X for 5 years" / "Led marketing at Y" / "Have analyzed N companies in space"]
The most important thing about [topic]: [your actual point in 2 sentences].
[A specific example, story, or data point — this is what gets quoted.]
[If applicable: a contrarian or surprising angle that differentiates from typical answers.]
Happy to expand on any of this, share data, or be quoted directly.
Feel free to use this attribution:
[Your name], [your title], [your company]
Contact for follow-up: [email + phone]
Note the structure:
1. One-sentence intro
2. One-sentence credential
3. Two-sentence answer
4. Specific example (the quotable part)
5. Optional: differentiator
6. Clear offer
7. Pre-written attribution (saves them 30 seconds)
8. Contact info
After analyzing hundreds of quoted responses, the patterns:
Bad: "Companies should focus on customer experience."
Good: "When we A/B tested 47 onboarding flows, the version with a 30-second video at step 3 increased activation by 41%."
The good version is a quote. The bad version is filler.
Bad: "As a marketing expert..."
Good: "I've run growth at three Series B SaaS companies, all in B2B sales tooling."
Specificity beats title-stacking.
Bad: "It's important to track the right metrics."
Good: "We almost shut down because we were optimizing for MRR when our real problem was activation. Once we switched to tracking 7-day activation, everything else followed."
Stories make articles. Advice makes filler.
Most quotes come from responses sent in the first 6 hours. After 24 hours, your chances drop sharply. Treat deadlines as if they're 24h earlier than stated.
Most teams overinvest in these platforms because they're cheap. Be honest:
| Effort | Realistic outcome (90 days) |
|---|---|
| 5 hr/week, custom responses | 3–10 quoted placements |
| 1 hr/week, template responses | 0–2 placements |
| Outsourced to PR firm | Lots of submissions, few quotes |
A quote in a tier-1 outlet is worth:
- A backlink (DR depends on outlet)
- A sales-collateral asset ("As featured in...")
- AI-citation surface area
- Brand legitimacy in the abstract
A quote in a tier-3 outlet is worth:
- A backlink, often nofollow
- Maybe an Instagram screenshot
Decision rule: if you can sustain 5 hr/week of quality responses for 90 days, this is worth it. If you can only do 1 hr/week, skip it and invest in proactive pitching instead.
Before you start responding:
Without these, you're spamming and wasting their time and yours.
When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy. Also use when the user mentions 'referral,' 'affiliate,' 'ambassador,' 'word of mouth,' 'viral loop,'
View source ↗You are an expert in viral growth and referral marketing. Your goal is to help design and optimize programs that turn customers into growth engines.
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):
Best for:
- Existing customers recommending to their network
- Products with natural word-of-mouth
- Lower-ticket or self-serve products
Characteristics:
- Referrer is an existing customer
- One-time or limited rewards
- Higher trust, lower volume
Best for:
- Reaching audiences you don't have access to
- Content creators, influencers, bloggers
- Higher-ticket products that justify commissions
Characteristics:
- Affiliates may not be customers
- Ongoing commission relationship
- Higher volume, variable trust
Trigger Moment → Share Action → Convert Referred → Reward → (Loop)
High-intent moments:
- Right after first "aha" moment
- After achieving a milestone
- After exceptional support
- After renewing or upgrading
Ranked by effectiveness:
1. In-product sharing (highest conversion)
2. Personalized link
3. Email invitation
4. Social sharing
5. Referral code (works offline)
Single-sided rewards (referrer only): Simpler, works for high-value products
Double-sided rewards (both parties): Higher conversion, win-win framing
Tiered rewards: Gamifies referral process, increases engagement
For examples and incentive sizing: See references/program-examples.md
If few customers are referring:
- Ask at better moments
- Simplify sharing process
- Test different incentive types
- Make referral prominent in product
If referrals aren't converting:
- Improve landing experience for referred users
- Strengthen incentive for new users
- Ensure referrer's endorsement is visible
Incentive tests: Amount, type, single vs. double-sided, timing
Messaging tests: Program description, CTA copy, landing page copy
Placement tests: Where and when the referral prompt appears
| Problem | Fix |
|---|---|
| Low awareness | Add prominent in-app prompts |
| Low share rate | Simplify to one click |
| Low conversion | Optimize referred user experience |
| Fraud/abuse | Add verification, limits |
| One-time referrers | Add tiered/gamified rewards |
Program health:
- Active referrers (referred someone in last 30 days)
- Referral conversion rate
- Rewards earned/paid
Business impact:
- % of new customers from referrals
- CAC via referral vs. other channels
- LTV of referred customers
- Referral program ROI
Subject: You can now earn [reward] for sharing [Product]
We just launched our referral program!
Share [Product] with friends and earn [reward] for each signup.
They get [their reward] too.
[Unique referral link]
1. Share your link
2. Friend signs up
3. You both get [reward]
For detailed affiliate program design, commission structures, recruitment, and tools: See references/affiliate-programs.md
For implementation, see the tools registry. Key tools for referral programs:
| Tool | Best For | Guide |
|---|---|---|
| Rewardful | Stripe-native affiliate programs | rewardful.md |
| Tolt | SaaS affiliate programs | tolt.md |
| Mention Me | Enterprise referral programs | mention-me.md |
| Dub.co | Link tracking and attribution | dub-co.md |
| Stripe | Payment processing (for commission tracking) | stripe.md |
| Introw | Channel partner programs with tiers, deal registration, QBRs | introw.md |
| PartnerStack | Enterprise partner and affiliate programs | partnerstack.md |
Detailed guidance for building and managing affiliate programs.
Percentage of sale:
- Standard: 10-30% of first sale or first year
- Works for: E-commerce, SaaS with clear pricing
- Example: "Earn 25% of every sale you refer"
Flat fee per action:
- Standard: $5-500 depending on value
- Works for: Lead gen, trials, freemium
- Example: "$50 for every qualified demo"
Recurring commission:
- Standard: 10-25% of recurring revenue
- Works for: Subscription products
- Example: "20% of subscription for 12 months"
Tiered commission:
- Works for: Motivating high performers
- Example: "20% for 1-10 sales, 25% for 11-25, 30% for 26+"
How long after click does affiliate get credit?
| Duration | Use Case |
|---|---|
| 24 hours | High-volume, low-consideration purchases |
| 7-14 days | Standard e-commerce |
| 30 days | Standard SaaS/B2B |
| 60-90 days | Long sales cycles, enterprise |
| Lifetime | Premium affiliate relationships |
Subject: Partnership opportunity — [Your Product]
Hi [Name],
I've been following your content on [topic] — particularly [specific piece] — and think there could be a great fit for a partnership.
[Your Product] helps [audience] [achieve outcome], and I think your audience would find it valuable.
We offer [commission structure] for partners, plus [additional benefits: early access, co-marketing, etc.].
Would you be open to learning more?
[Your name]
Provide affiliates with:
- [ ] Unique tracking links/codes
- [ ] Product overview and key benefits
- [ ] Target audience description
- [ ] Comparison to competitors
- [ ] Creative assets (logos, banners, images)
- [ ] Sample copy and talking points
- [ ] Case studies and testimonials
- [ ] Demo access or free account
- [ ] FAQ and objection handling
- [ ] Payment terms and schedule
Full-featured platforms:
- ReferralCandy — E-commerce focused
- Ambassador — Enterprise referral programs
- Friendbuy — E-commerce and subscription
- GrowSurf — SaaS and tech companies
- Mention Me — AI-powered referral marketing
- Viral Loops — Template-based campaigns
Built-in options:
- Stripe (basic referral tracking)
- HubSpot (CRM-integrated)
- Segment (tracking and analytics)
Affiliate networks:
- ShareASale — Large merchant network
- Impact — Enterprise partnerships
- PartnerStack — SaaS focused
- Tapfiliate — Simple SaaS affiliate tracking
- FirstPromoter — SaaS affiliate management
Partner Relationship Management (PRM):
- Introw — Full PRM with deal registration, commissions, tiers, QBRs, and partner engagement tracking (integration guide)
Self-hosted:
- Rewardful — Stripe-integrated affiliates
- Refersion — E-commerce affiliates
Consider:
- Integration with your payment system
- Fraud detection capabilities
- Payout management
- Reporting and analytics
- Customization options
- Price vs. program scale
Technical:
- Email verification required
- Device fingerprinting
- IP address monitoring
- Delayed reward payout (after activation)
- Minimum activity threshold
Policy:
- Clear terms of service
- Maximum referrals per period
- Reward clawback for refunds/chargebacks
- Manual review for suspicious patterns
Structural:
- Require referred user to take meaningful action
- Cap lifetime rewards
- Pay rewards in product credit (less attractive to fraudsters)
Real-world examples of successful referral programs.
Program: Give 500MB storage, get 500MB storage
Why it worked:
- Reward directly tied to product value
- Low friction (just an email)
- Both parties benefit equally
- Gamified with progress tracking
Program: Give $10 ride credit, get $10 when they ride
Why it worked:
- Immediate, clear value
- Double-sided incentive
- Easy to share (code/link)
- Triggered at natural moments
Program: Tiered rewards for subscriber referrals
- 3 referrals: Newsletter stickers
- 5 referrals: T-shirt
- 10 referrals: Mug
- 25 referrals: Hoodie
Why it worked:
- Gamification drives ongoing engagement
- Physical rewards are shareable (more referrals)
- Low cost relative to subscriber value
- Built status/identity
Program: $10 credit per referral (education)
Why it worked:
- Targeted high-sharing audience (students)
- Product naturally spreads in teams
- Credit keeps users engaged
| Type | Pros | Cons | Best For |
|---|---|---|---|
| Cash/credit | Universally valued | Feels transactional | Marketplaces, fintech |
| Product credit | Drives usage | Only valuable if they'll use it | SaaS, subscriptions |
| Free months | Clear value | May attract freebie-seekers | Subscription products |
| Feature unlock | Low cost to you | Only works for gated features | Freemium products |
| Swag/gifts | Memorable, shareable | Logistics complexity | Brand-focused companies |
| Charity donation | Feel-good | Lower personal motivation | Mission-driven brands |
Calculate your maximum incentive:
Max Referral Reward = (Customer LTV × Gross Margin) - Target CAC
Example:
- LTV: $1,200
- Gross margin: 70%
- Target CAC: $200
- Max reward: ($1,200 × 0.70) - $200 = $640
Typical referral rewards:
- B2C: $10-50 or 10-25% of first purchase
- B2B SaaS: $50-500 or 1-3 months free
- Enterprise: Higher, often custom
Viral coefficient (K-factor):
K = Invitations × Conversion Rate
K > 1 = Viral growth (each user brings more than 1 new user)
K < 1 = Amplified growth (referrals supplement other acquisition)
Example:
- Average customer sends 3 invitations
- 15% of invitations convert
- K = 3 × 0.15 = 0.45
Referral rate:
Referral Rate = (Customers who refer) / (Total customers)
Benchmarks:
- Good: 10-25% of customers refer
- Great: 25-50%
- Exceptional: 50%+
Referrals per referrer:
Benchmarks:
- Average: 1-2 referrals per referrer
- Good: 2-5
- Exceptional: 5+
Referral Program ROI = (Revenue from referred customers - Program costs) / Program costs
Program costs = Rewards paid + Tool costs + Management time
Track separately:
- Cost per referred customer (CAC via referral)
- LTV of referred customers (often higher than average)
- Payback period for referral rewards
When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes. Also use when the user mentions 'RevOps,' 'revenue operations,' 'lead scoring,' 'lead routing,' 'MQL,'
View source ↗You are an expert in revenue operations. Your goal is to help design and optimize the systems that connect marketing, sales, and customer success into a unified revenue engine.
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):
Work with whatever the user gives you. If they have a clear problem area, start there. Don't block on missing inputs — use what you have and note what would strengthen the solution.
One system of record for every lead and account. If data lives in multiple places, it will conflict. Pick a CRM as the canonical source and sync everything to it.
Get stage definitions, scoring criteria, and routing rules right on paper before building workflows. Automating a broken process just creates broken results faster.
Every handoff between teams is a potential leak. Marketing-to-sales, SDR-to-AE, AE-to-CS — each needs an SLA, a tracking mechanism, and someone accountable for follow-through.
Marketing, sales, and customer success must agree on definitions. If marketing calls something an MQL but sales won't work it, the definition is wrong. Alignment meetings aren't optional.
| Stage | Entry Criteria | Exit Criteria | Owner |
|---|---|---|---|
| Subscriber | Opts in to content (blog, newsletter) | Provides company info or shows engagement | Marketing |
| Lead | Identified contact with basic info | Meets minimum fit criteria | Marketing |
| MQL | Passes fit + engagement threshold | Sales accepts or rejects within SLA | Marketing |
| SQL | Sales accepts and qualifies via conversation | Opportunity created or recycled | Sales (SDR/AE) |
| Opportunity | Budget, authority, need, timeline confirmed | Closed-won or closed-lost | Sales (AE) |
| Customer | Closed-won deal | Expands, renews, or churns | CS / Account Mgmt |
| Evangelist | High NPS, referral activity, case study | Ongoing program participation | CS / Marketing |
An MQL requires both fit and engagement:
Neither alone is sufficient. A perfect-fit company that never engages isn't an MQL. A student downloading every ebook isn't an MQL.
Define response times and document them:
- MQL alert sent to assigned rep
- Rep contacts within 4 hours (business hours)
- Rep qualifies or rejects within 48 hours
- Rejected MQLs go to recycling nurture with reason code
For complete lifecycle stage templates and SLA examples: See references/lifecycle-definitions.md
Explicit scoring (fit) — Who they are:
- Company size, industry, revenue
- Job title, seniority, department
- Tech stack, geography
Implicit scoring (engagement) — What they do:
- Page visits (especially pricing, demo, case studies)
- Content downloads, webinar attendance
- Email engagement (opens, clicks)
- Product usage (for PLG)
Negative scoring — Disqualifying signals:
- Competitor email domains
- Student/personal email
- Unsubscribes, spam complaints
- Job title mismatches (intern, student)
For detailed scoring templates and example models: See references/scoring-models.md
| Method | How It Works | Best For |
|---|---|---|
| Round-robin | Distribute evenly across reps | Equal territories, similar deal sizes |
| Territory-based | Assign by geography, vertical, or segment | Regional teams, industry specialists |
| Account-based | Named accounts go to named reps | ABM motions, strategic accounts |
| Skill-based | Route by deal complexity, product line, or language | Diverse product lines, global teams |
Response time is the single biggest factor in lead conversion:
- Contact within 5 minutes = 21x more likely to qualify (Lead Connect)
- After 30 minutes, conversion drops by 10x
- After 24 hours, the lead is effectively cold
Build routing rules that prioritize speed. Alert reps immediately. Escalate if SLA is missed.
For routing decision trees and platform-specific setup: See references/routing-rules.md
| Stage | Required Fields | Exit Criteria |
|---|---|---|
| Qualified | Contact info, company, source, fit score | Discovery call scheduled |
| Discovery | Pain points, current solution, timeline | Needs confirmed, demo scheduled |
| Demo/Evaluation | Technical requirements, decision makers | Positive evaluation, proposal requested |
| Proposal | Pricing, terms, stakeholder map | Proposal delivered and reviewed |
| Negotiation | Redlines, approval chain, close date | Terms agreed, contract sent |
| Closed Won | Signed contract, payment terms | Handoff to CS complete |
| Closed Lost | Loss reason, competitor (if any) | Post-mortem logged |
| Metric | What It Tells You |
|---|---|
| Stage conversion rates | Where deals die |
| Average time in stage | Where deals stall |
| Pipeline velocity | Revenue per day through the funnel |
| Coverage ratio | Pipeline value vs. quota (target 3-4x) |
| Win rate by source | Which channels produce real revenue |
For platform-specific workflow recipes: See references/automation-playbooks.md
| Deal Size | Approval Required |
|---|---|
| Standard pricing | Auto-approved |
| 10-20% discount | Sales manager |
| 20-40% discount | VP Sales |
| 40%+ discount or custom terms | Deal desk review |
| Multi-year / enterprise | Finance + Legal |
Document every exception. Track which non-standard terms get requested most — if everyone asks for the same exception, it should become standard. Review quarterly.
| Tool | Strength |
|---|---|
| Clearbit | Real-time enrichment, good for tech companies |
| Apollo | Contact data + sequences, strong for prospecting |
| ZoomInfo | Enterprise-grade, largest B2B database |
| Metric | Formula / Definition | Benchmark |
|---|---|---|
| Lead-to-MQL rate | MQLs / Total leads | 5-15% |
| MQL-to-SQL rate | SQLs / MQLs | 30-50% |
| SQL-to-Opportunity | Opportunities / SQLs | 50-70% |
| Pipeline velocity | (# deals x avg deal size x win rate) / avg sales cycle | Varies by ACV |
| CAC | Total sales + marketing spend / new customers | LTV:CAC > 3:1 |
| LTV:CAC ratio | Customer lifetime value / CAC | 3:1 to 5:1 healthy |
| Speed-to-lead | Time from form fill to first rep contact | < 5 minutes ideal |
| Win rate | Closed-won / total opportunities | 20-30% (varies) |
Build three views:
1. Marketing view — Lead volume, MQL rate, source attribution, cost per MQL
2. Sales view — Pipeline value, stage conversion, velocity, forecast accuracy
3. Executive view — CAC, LTV:CAC, revenue vs. target, pipeline coverage
When delivering RevOps recommendations, provide:
Format each as a standalone document the user can implement directly. Include platform-specific guidance when the CRM is known.
For implementation, see the tools registry. Key RevOps tools:
| Tool | What It Does | Guide |
|---|---|---|
| HubSpot | CRM, marketing automation, lead scoring, workflows | hubspot.md |
| Salesforce | Enterprise CRM, pipeline management, reporting | salesforce.md |
| Calendly | Meeting scheduling, round-robin routing | calendly.md |
| SavvyCal | Scheduling with priority-based availability | savvycal.md |
| Clearbit | Real-time lead enrichment and scoring | clearbit.md |
| Apollo | Contact data, enrichment, and outbound sequences | apollo.md |
| ActiveCampaign | Marketing automation for SMBs, lead scoring | activecampaign.md |
| Zapier | Cross-tool automation and workflow glue | zapier.md |
| Introw | Partner-sourced pipeline, commissions, deal registration, QBRs | introw.md |
| Crossbeam | Partner account overlaps and co-sell identification | crossbeam.md |
Platform-specific workflow recipes for HubSpot, Salesforce, scheduling tools, and cross-tool automation.
Name: MQL Notification and Task Creation
Trigger: Contact property "Lifecycle Stage" is changed to "Marketing Qualified Lead"
Actions:
1. Rotate contact owner among sales team (round-robin)
2. Send internal email notification to contact owner with lead context
3. Create task: "Follow up with [Contact Name]" — due in 4 hours
4. Send Slack notification to #sales-alerts channel
5. Enroll in "MQL Follow-Up" sequence (if using HubSpot Sequences)
Outcome: Every MQL gets assigned instantly with a clear SLA
Notes: Set enrollment criteria to exclude leads already owned by a rep
Name: MQL SLA Breach Alert
Trigger: Contact property "Lifecycle Stage" equals "MQL" AND "Days since last contacted" is greater than 0.5 (12 hours)
Actions:
1. Send internal email to contact owner: "SLA warning: [Contact Name] has not been contacted"
2. If still no activity after 24 hours → send alert to sales manager
3. If still no activity after 48 hours → reassign contact owner via rotation
4. Create task for new owner: "Urgent: Contact [Contact Name] — reassigned due to SLA breach"
Outcome: No MQL goes unworked for more than 48 hours
Notes: Exclude contacts where last activity type is "Call" or "Meeting" (already engaged)
Name: Auto-MQL on Score Threshold
Trigger: Contact property "HubSpot Score" is greater than or equal to 65
Actions:
1. Set lifecycle stage to "Marketing Qualified Lead"
2. Set "MQL Date" to current date
3. Suppress from marketing nurture workflows
4. Trigger MQL Alert workflow (recipe #1)
Outcome: Leads automatically promote to MQL when they hit the scoring threshold
Notes: Add suppression list for existing customers and competitors
Name: Meeting Booked Alert to AE
Trigger: Meeting activity is logged for contact (via Calendly/HubSpot meetings)
Actions:
1. Send internal email to contact owner with meeting details
2. Update contact property "Last Meeting Booked" to current date
3. If lifecycle stage is "Lead" → update to "MQL"
4. Create task: "Prepare for meeting with [Contact Name]" — due 1 hour before meeting
5. Send Slack notification to #meetings channel
Outcome: AEs are prepared for every meeting with full context
Notes: Include recent page views and content downloads in notification email
Name: Customer Onboarding Trigger
Trigger: Deal stage is changed to "Closed Won"
Actions:
1. Update associated contact lifecycle stage to "Customer"
2. Set "Customer Since" date to current date
3. Assign contact owner to CS team member (based on segment/territory)
4. Create task for CS: "Schedule kickoff call with [Company Name]" — due in 2 business days
5. Enroll contact in "Customer Onboarding" email sequence
6. Send internal notification to CS manager
7. Remove from all sales sequences
Outcome: Seamless handoff from sales to customer success
Notes: Include deal notes, contract value, and key stakeholders in CS notification
Name: Pipeline Hygiene — Stale Deal Detection
Trigger: Deal property "Days in current stage" is greater than [2x average for that stage]
Actions:
1. Send internal email to deal owner: "Deal stale alert: [Deal Name] has been in [Stage] for [X] days"
2. Create task: "Update or close [Deal Name]" — due in 3 business days
3. If no update after 7 days → alert sales manager
4. Add to "Stale Deals" dashboard list
Outcome: Pipeline stays clean and forecast stays accurate
Notes: Customize thresholds per stage (Discovery: 14 days, Proposal: 10 days, Negotiation: 21 days)
Name: MQL Recycling to Nurture
Trigger: Contact property "Sales Rejection Reason" is known (any value)
Actions:
1. Update lifecycle stage to "Recycled"
2. Reset engagement score to baseline (keep fit score)
3. Enroll in "Recycled Lead Nurture" sequence (lower frequency)
4. Set "Recycle Date" to current date
5. Set re-enrollment trigger: if HubSpot Score exceeds threshold again, re-trigger MQL workflow
Outcome: Rejected leads get a second chance without clogging the pipeline
Notes: Track recycled-to-MQL conversion rate as a separate metric
Name: Daily Lead Activity Summary
Trigger: Scheduled — daily at 8:00 AM local time
Actions:
1. Filter contacts: lifecycle stage is "SQL" or "Opportunity" AND had website activity in last 24 hours
2. Send digest email to each contact owner with their leads' activity
3. Include: pages visited, content downloaded, emails opened/clicked
Outcome: Sales reps start each day knowing which leads are active
Notes: Only include leads with meaningful activity (exclude single homepage visits)
Type: Record-Triggered Flow
Object: Lead
Trigger: Lead field "Status" is changed to "MQL"
Flow steps:
1. Get Records: Query "Rep Assignment" custom object for next available rep
2. Update Records: Set Lead Owner to assigned rep
3. Create Records: Create Task — "Contact MQL: {Lead.Name}" with due date = NOW + 4 hours
4. Action: Send email alert to new lead owner
5. Update Records: Update "Rep Assignment" last-assigned timestamp
Notes: Use a custom "Rep Assignment" object to manage round-robin state
Type: Scheduled-Triggered Flow
Schedule: Every 4 hours during business hours
Flow steps:
1. Get Records: Leads where Status = "MQL" AND LastActivityDate < TODAY - 1
2. Decision: Is lead older than 48 hours with no activity?
- YES → Reassign to next rep, create urgent task, alert manager
- NO → Send reminder email to current owner
Notes: Pair with Process Builder for real-time alerts on initial assignment
Type: Record-Triggered Flow
Object: Opportunity
Trigger: Stage field is updated
Flow steps:
1. Decision: Which stage was it changed to?
2. For each stage:
- Discovery: Create task "Complete discovery questionnaire"
- Demo: Create task "Prepare demo environment"
- Proposal: Create task "Send proposal" + alert deal desk if ACV > $25K
- Closed Won: Trigger CS handoff (create Case, assign CS owner, send welcome email)
- Closed Lost: Create task "Log loss reason" + add to win/loss analysis report
Type: Scheduled-Triggered Flow
Schedule: Daily at 7:00 AM
Flow steps:
1. Get Records: Open Opportunities where Days_In_Stage > Stage_SLA_Threshold
2. Loop through results:
- Create Task: "Update stale deal: {Opportunity.Name}"
- Send email to Opportunity Owner
- If Days_In_Stage > 2x threshold → send email to Owner's Manager
3. Update custom field "Stale Flag" = true for dashboard visibility
Calendly setup:
1. Create a team event type with all eligible reps
2. Distribution: "Optimize for equal distribution"
3. Availability: Each rep manages their own calendar
4. Buffer: 15 min before and after meetings
5. Minimum notice: 4 hours (avoid last-minute bookings)
CRM integration:
1. Calendly webhook fires on booking
2. Match invitee email to CRM contact
3. If contact exists → assign meeting to contact owner (override round-robin if owned)
4. If new contact → create lead, assign via routing rules, log meeting
5. Set lifecycle stage to MQL (meeting = high intent)
Advantages over Calendly:
- Priority-based scheduling (prefer certain time slots)
- Overlay calendars (show team availability in one view)
- Personalized booking links per rep
Integration pattern:
1. Create team scheduling link with priority rules
2. Webhook on booking → Zapier/Make → CRM
3. Match or create contact, assign owner, create task
4. Send confirmation with meeting prep materials
Booking form submitted
├─ Company size > 500? (form field)
│ ├─ YES → Route to enterprise AE calendar
│ └─ NO ↓
├─ Existing customer? (CRM lookup)
│ ├─ YES → Route to account owner's calendar
│ └─ NO ↓
└─ Round-robin across SDR team
Trigger: Meeting time passes + no meeting notes logged within 30 minutes
Actions:
1. Wait 30 minutes after scheduled meeting time
2. Check: Was a call or meeting logged?
- YES → No action
- NO → Send "Sorry we missed you" email to prospect
3. Create task: "Reschedule with [Contact Name]" — due next business day
4. If second no-show → flag contact and alert manager
Trigger: New form submission (Typeform, HubSpot, Webflow)
Actions:
1. Create/update contact in CRM
2. Enrich with Clearbit (if available)
3. Post to Slack #new-leads with enriched data
4. Create task in project management tool (Asana, Linear)
Trigger: New Calendly/SavvyCal booking
Actions:
1. Find or create CRM contact
2. Update lifecycle stage to MQL
3. Send prep email to assigned rep (include CRM link, LinkedIn profile, recent activity)
4. Create pre-meeting task
Trigger: CRM deal stage changed to "Closed Won"
Actions:
1. Create customer record in CS tool (Vitally, Gainsight, ChurnZero)
2. Add to onboarding project template
3. Send welcome email via email tool
4. Create Slack channel: #customer-[company-name]
5. Notify CS team in Slack
Trigger: CRM lead score crosses MQL threshold
Actions:
1. Update marketing automation platform status
2. Add to retargeting audience (Facebook, Google Ads)
3. Trigger SDR outreach sequence
4. Log event in analytics (Mixpanel, Amplitude)
Trigger: CRM task overdue (MQL follow-up task)
Actions:
1. Send Slack DM to rep
2. Send email to rep
3. If 2+ hours overdue → Slack DM to manager
4. If 4+ hours overdue → reassign in CRM (via webhook back to CRM)
Trigger: Schedule — every Monday at 8:00 AM
Actions:
1. Query CRM for pipeline summary (total value, new deals, stale deals, expected closes)
2. Format as summary
3. Post to Slack #sales-team
4. Send email digest to sales leadership
Complete templates for lead lifecycle stages, MQL criteria by business type, SLAs, and rejection/recycling workflows.
Entry criteria:
- Opted in to blog, newsletter, or content updates
- No company information required
Exit criteria:
- Provides company information via form or enrichment
- Visits 3+ pages in a session
- Downloads gated content
Owner: Marketing (automated)
Actions on entry:
- Add to newsletter nurture
- Begin tracking engagement score
Entry criteria:
- Identified contact with name + email + company
- May come from form fill, enrichment, or import
Exit criteria:
- Reaches MQL threshold (fit + engagement)
- Manually qualified by marketing/SDR
Owner: Marketing
Actions on entry:
- Enrich contact data (company size, industry, role)
- Begin scoring
- Add to relevant nurture sequence
Entry criteria:
- Meets fit score threshold AND engagement score threshold
- OR triggers high-intent action (demo request, pricing page + form fill)
Exit criteria:
- Sales accepts (becomes SQL)
- Sales rejects (recycled to nurture with reason code)
- No response within SLA (escalated to manager)
Owner: Marketing → Sales (handoff)
Actions on entry:
- Instant alert to assigned sales rep
- Create follow-up task with 4-hour SLA
- Pause marketing nurture sequences
- Log all recent activity for sales context
Entry criteria:
- Sales rep has had qualifying conversation
- Confirmed: budget, authority, need, or timeline (at least 2 of 4)
Exit criteria:
- Opportunity created with projected value
- Disqualified (recycled with reason code)
Owner: Sales (SDR or AE)
Actions on entry:
- Update lifecycle stage in CRM
- Notify AE if SDR-qualified
- Begin sales sequence if not already in conversation
Entry criteria:
- Formal opportunity created in CRM
- Deal value, close date, and stage assigned
Exit criteria:
- Closed-won or closed-lost
Owner: Sales (AE)
Actions on entry:
- Add to pipeline reporting
- Create deal tasks (proposal, demo, etc.)
- Notify CS if deal is likely to close
Entry criteria:
- Closed-won deal
- Contract signed and payment terms set
Exit criteria:
- Churns, expands, or renews
Owner: Customer Success / Account Management
Actions on entry:
- Trigger onboarding sequence
- Assign CS manager
- Schedule kickoff call
- Remove from all sales sequences
Entry criteria:
- NPS score 9-10, or active referral behavior
- Agreed to case study, testimonial, or referral program
Exit criteria:
- Ongoing program participation
Owner: Customer Success + Marketing
Actions on entry:
- Add to advocacy program
- Request case study or testimonial
- Invite to referral program
- Feature in marketing campaigns (with permission)
Fit score (40% weight):
| Attribute | Points |
|---|---|
| Company size 10-500 | +15 |
| Company size 500-5000 | +20 |
| Target industry | +10 |
| Decision-maker role | +15 |
| Uses complementary tool | +10 |
Engagement score (60% weight) — weight product usage heavily:
| Signal | Points |
|---|---|
| Created free account | +15 |
| Completed onboarding | +20 |
| Used core feature 3+ times | +25 |
| Invited team member | +20 |
| Hit usage limit | +15 |
| Visited pricing page | +10 |
MQL threshold: 65 points
Fit score (60% weight) — weight fit heavily:
| Attribute | Points |
|---|---|
| Company size 500+ | +20 |
| Target industry | +15 |
| VP+ title | +20 |
| Budget authority confirmed | +15 |
| Uses competitor product | +10 |
Engagement score (40% weight):
| Signal | Points |
|---|---|
| Requested demo | +25 |
| Attended webinar | +10 |
| Downloaded whitepaper | +10 |
| Visited pricing page 2+ times | +15 |
| Engaged with sales email | +10 |
MQL threshold: 70 points
Fit score (50% weight):
| Attribute | Points |
|---|---|
| Company size 50-1000 | +15 |
| Target industry | +10 |
| Manager+ title | +15 |
| Target geography | +10 |
Engagement score (50% weight):
| Signal | Points |
|---|---|
| Demo request | +25 |
| Free trial signup | +20 |
| Pricing page visit | +10 |
| Content download (2+) | +10 |
| Email click (3+) | +10 |
| Webinar attendance | +10 |
MQL threshold: 60 points
| Metric | Target | Escalation |
|---|---|---|
| First contact attempt | Within 4 business hours | Alert to sales manager at 4 hours |
| Qualification decision | Within 48 hours | Auto-escalate at 48 hours |
| Meeting scheduled (if qualified) | Within 5 business days | Weekly pipeline review flag |
| Metric | Target | Escalation |
|---|---|---|
| Discovery call completed | Within 3 business days of SQL | Alert to AE manager |
| Opportunity created | Within 5 business days of SQL | Pipeline review flag |
| Metric | Target | Escalation |
|---|---|---|
| Proposal delivered | Within 5 business days of demo | AE manager alert |
| Deal stale in stage | 2x average days for that stage | Pipeline review flag |
| Close date pushed 2+ times | Immediate | Forecast review required |
| Code | Reason | Recycle Action |
|---|---|---|
| FIT-01 | Company too small | Nurture; re-score if company grows |
| FIT-02 | Wrong industry | Archive; do not recycle |
| FIT-03 | Wrong role / no authority | Nurture; monitor for org changes |
| ENG-01 | No response after 3 attempts | Recycle to nurture in 90 days |
| ENG-02 | Interested but bad timing | Recycle to nurture; re-engage in 60 days |
| QUAL-01 | No budget | Recycle to nurture in 90 days |
| QUAL-02 | Using competitor, locked in | Recycle; trigger before contract renewal |
| QUAL-03 | Not a real project | Archive; do not recycle |
Decision trees, platform-specific configurations, territory routing, ABM routing, and speed-to-lead benchmarks.
Use this template to map your routing logic:
New Lead Arrives
│
├─ Is this a named/target account?
│ ├─ YES → Route to assigned account owner
│ └─ NO ↓
│
├─ Is ACV likely > $50K? (based on company size + industry)
│ ├─ YES → Route to enterprise AE team
│ └─ NO ↓
│
├─ Is this a PLG signup with team usage?
│ ├─ YES → Route to PLG sales specialist
│ └─ NO ↓
│
├─ Does lead match a territory?
│ ├─ YES → Route to territory owner
│ └─ NO ↓
│
└─ Default: Round-robin across available reps
└─ If no rep available: Assign to team queue with 1-hour SLA
Customize this tree for your business. The key principle: route to the most specific match first, fall back to general.
Using HubSpot's rotation tool:
- Navigate to Automation → Workflows
- Trigger: Contact property "Lifecycle Stage" equals "MQL"
- Action: Rotate contact owner among selected users
- Options: Even distribution, skip unavailable owners
- Add delay + task creation after assignment
Custom rotation with workflows:
1. Create a custom property "Rotation Counter" (number)
2. Workflow trigger: New MQL created
3. Branch by rotation counter value (0, 1, 2... for each rep)
4. Set contact owner to corresponding rep
5. Increment counter (reset at max)
6. Create follow-up task with SLA deadline
Using Lead Assignment Rules:
1. Setup → Feature Settings → Marketing → Lead Assignment Rules
2. Create rule entries in priority order (most specific first)
3. For round-robin: Use assignment rule + custom logic
Using Flow for advanced routing:
1. Create a Record-Triggered Flow on Lead creation
2. Get Records: Query a custom "Rep Queue" object for next available rep
3. Decision element: Check rep availability, capacity, territory
4. Update Records: Assign lead owner
5. Create Task: Follow-up task with SLA
6. Update "Rep Queue" to track last assignment
| Territory | Regions | Assigned Team |
|---|---|---|
| West | CA, WA, OR, NV, AZ, UT, CO, HI | Team West |
| Central | TX, IL, MN, MO, OH, MI, WI, IN | Team Central |
| East | NY, MA, PA, NJ, CT, VA, FL, GA | Team East |
| International | All non-US | International team |
| Segment | Company Size | Team |
|---|---|---|
| SMB | 1-50 employees | Inside sales |
| Mid-market | 51-500 employees | Mid-market AEs |
| Enterprise | 501-5000 employees | Enterprise AEs |
| Strategic | 5000+ employees | Strategic account team |
| Vertical | Industries | Specialist |
|---|---|---|
| Tech | SaaS, IT services, hardware | Tech vertical rep |
| Financial | Banking, insurance, fintech | Financial vertical rep |
| Healthcare | Hospitals, pharma, healthtech | Healthcare vertical rep |
| General | All others | General pool (round-robin) |
Combine multiple dimensions for precision:
Lead arrives
├─ Company size > 1000?
│ ├─ YES → Enterprise team
│ │ └─ Sub-route by geography
│ └─ NO ↓
├─ Industry = Healthcare or Financial?
│ ├─ YES → Vertical specialist
│ └─ NO ↓
└─ Round-robin across general pool
└─ Weighted by geography preference
| Tier | Account Type | Routing | Response SLA |
|---|---|---|---|
| Tier 1 | Top 20 strategic accounts | Named owner, instant alert | 1 hour |
| Tier 2 | Top 100 target accounts | Named owner, standard alert | 4 hours |
| Tier 3 | Target industry / size match | Territory or round-robin | Same business day |
When multiple contacts from the same account engage:
- Route all contacts to the same account owner
- Notify the owner of new contacts entering
- Track account-level engagement score (sum of all contacts)
- Trigger "buying committee" alert when 3+ contacts from one account engage
| Response Time | Relative Qualification Rate | Notes |
|---|---|---|
| Under 5 minutes | 21x more likely to qualify | Gold standard |
| 5-10 minutes | 10x more likely | Still strong |
| 10-30 minutes | 4x more likely | Acceptable for most |
| 30 min - 1 hour | 2x more likely | Below best practice |
| 1-24 hours | Baseline | Industry average |
| 24+ hours | 60% lower than baseline | Lead is effectively cold |
Source: Lead Connect, InsideSales.com
Trigger: New MQL created
Actions:
1. Assign to rep via routing rules (instant)
2. Send push notification + email to rep
3. Create task: "Contact [Lead Name] — 5 min SLA"
4. Start SLA timer
5. If no activity logged in 15 min → alert backup rep
6. If no activity in 30 min → alert manager
7. If no activity in 60 min → reassign via round-robin
Track these metrics weekly:
- Average time to first contact (from MQL creation to first call/email)
- Median time to first contact (less skewed by outliers)
- % of leads contacted within SLA (target: 90%+)
- Contact rate by time of day (identify coverage gaps)
- Conversion rate by response time (prove the ROI of speed)
Detailed scoring templates, example models by business type, and calibration guidance.
| Attribute | Criteria | Points |
|---|---|---|
| Company size | 1-10 employees | +5 |
| 11-50 employees | +10 | |
| 51-200 employees | +15 | |
| 201-1000 employees | +20 | |
| 1000+ employees | +15 (unless enterprise-focused, then +25) | |
| Industry | Primary target industry | +20 |
| Secondary target industry | +10 | |
| Non-target industry | 0 | |
| Revenue | Under $1M | +5 |
| $1M-$10M | +10 | |
| $10M-$100M | +15 | |
| $100M+ | +20 | |
| Geography | Primary market | +10 |
| Secondary market | +5 | |
| Non-target market | 0 |
| Attribute | Criteria | Points |
|---|---|---|
| Job title | C-suite (CEO, CTO, CMO) | +25 |
| VP level | +20 | |
| Director level | +15 | |
| Manager level | +10 | |
| Individual contributor | +5 | |
| Department | Primary buying department | +15 |
| Adjacent department | +5 | |
| Unrelated department | 0 | |
| Seniority | Decision maker | +20 |
| Influencer | +10 | |
| End user | +5 |
| Attribute | Criteria | Points |
|---|---|---|
| Tech stack | Uses complementary tool | +15 |
| Uses competitor | +10 (they understand the category) | |
| Uses tool you replace | +20 | |
| Tech maturity | Modern stack (cloud, SaaS-forward) | +10 |
| Legacy stack | +5 |
| Signal | Points | Decay |
|---|---|---|
| Demo request | +30 | None |
| Pricing page visit | +20 | -5 per week |
| Free trial signup | +25 | None |
| Contact sales form | +30 | None |
| Case study page (2+) | +15 | -5 per 2 weeks |
| Comparison page visit | +15 | -5 per week |
| ROI calculator used | +20 | -5 per 2 weeks |
| Signal | Points | Decay |
|---|---|---|
| Webinar registration | +10 | -5 per month |
| Webinar attendance | +15 | -5 per month |
| Whitepaper download | +10 | -5 per month |
| Blog visit (3+ in a week) | +10 | -5 per 2 weeks |
| Email click | +5 per click | -2 per month |
| Email open (3+) | +5 | -2 per month |
| Social media engagement | +5 | -2 per month |
| Signal | Points | Decay |
|---|---|---|
| Single blog visit | +2 | -2 per month |
| Newsletter open | +2 | -1 per month |
| Single email open | +1 | -1 per month |
| Visited homepage only | +1 | -1 per week |
| Signal | Points | Decay |
|---|---|---|
| Created account | +15 | None |
| Completed onboarding | +20 | None |
| Used core feature (3+ times) | +25 | -5 per month inactive |
| Invited team member | +25 | None |
| Hit usage limit | +20 | -10 per month |
| Exported data | +10 | -5 per month |
| Connected integration | +15 | None |
| Daily active for 5+ days | +20 | -10 per 2 weeks inactive |
| Signal | Points | Notes |
|---|---|---|
| Competitor email domain | -50 | Auto-flag for review |
| Student email (.edu) | -30 | May still be valid in some cases |
| Personal email (gmail, yahoo) | -10 | Less relevant for B2B; adjust for SMB |
| Unsubscribe from emails | -20 | Reduce engagement score |
| Bounce (hard) | -50 | Remove from scoring |
| Spam complaint | -100 | Remove from all sequences |
| Job title: Student/Intern | -25 | Low buying authority |
| Job title: Consultant | -10 | May be evaluating for client |
| No website visit in 90 days | -15 | Score decay |
| Invalid phone number | -10 | Data quality signal |
| Careers page visitor only | -30 | Likely a job seeker |
Weight: 30% fit / 70% engagement (heavily favor product usage)
Fit criteria:
- Company size 10-500: +15
- Target industry: +10
- Manager+ role: +10
- Uses complementary tool: +10
Engagement criteria:
- Created free account: +15
- Completed onboarding: +20
- Used core feature 3+ times: +25
- Invited team member: +25
- Hit usage limit: +20
- Pricing page visit: +15
Negative:
- Personal email: -10
- No login in 14 days: -15
- Competitor domain: -50
MQL threshold: 60 points
Recalibration: Monthly (fast feedback loop with high volume)
Weight: 60% fit / 40% engagement (fit is critical at this ACV)
Fit criteria:
- Company size 500+: +20
- Revenue $50M+: +15
- Target industry: +15
- VP+ title: +20
- Decision maker confirmed: +15
- Uses competitor: +10
Engagement criteria:
- Demo request: +30
- Multiple stakeholders engaged: +20
- Attended executive webinar: +15
- Downloaded ROI guide: +10
- Visited pricing page 2+: +15
Negative:
- Company too small (<100): -30
- Individual contributor only: -15
- Competitor domain: -50
MQL threshold: 75 points
Recalibration: Quarterly (longer sales cycles, smaller sample size)
Weight: 50% fit / 50% engagement (balanced approach)
Fit criteria:
- Company size 50-1000: +15
- Target industry: +10
- Manager-VP title: +15
- Target geography: +10
- Uses complementary tool: +10
Engagement criteria:
- Demo request or trial signup: +25
- Pricing page visit: +15
- Case study download: +10
- Webinar attendance: +10
- Email engagement (3+ clicks): +10
- Blog visits (5+ pages): +10
Negative:
- Personal email: -10
- No engagement in 30 days: -10
- Competitor domain: -50
- Student/intern title: -25
MQL threshold: 65 points
Recalibration: Quarterly
| Business Type | Recalibration Frequency | Why |
|---|---|---|
| PLG / High volume | Monthly | Fast feedback loop, lots of data |
| Mid-market | Quarterly | Moderate cycle length |
| Enterprise | Quarterly to semi-annually | Long cycles, small sample size |
When the user wants to create sales collateral, pitch decks, one-pagers, objection handling docs, or demo scripts. Also use when the user mentions 'sales deck,' 'pitch deck,' 'one-pager,' 'leave-behind,' 'objection handl
View source ↗You are an expert in B2B sales enablement. Your goal is to create sales collateral that reps actually use — decks, one-pagers, objection docs, demo scripts, and playbooks that help close deals.
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):
Value Proposition & Differentiators
- What do you sell and who is it for?
- What makes you different from the next best alternative?
- What outcomes can you prove?
Sales Motion
- How do you sell? (self-serve, inside sales, field sales, hybrid)
- Average deal size and sales cycle length
- Key personas involved in the buying decision
Collateral Needs
- What specific assets do you need?
- What stage of the funnel are they for?
- Who will use them? (AE, SDR, champion, prospect)
Current State
- What materials exist today?
- What's working and what's not?
- What do reps ask for most?
Involve reps in creation. Use their language, not marketing's. If reps rewrite your deck before sending it, you wrote the wrong deck. Test drafts with your top performers first.
Tailor to persona, deal stage, and use case. A deck for a CTO should look different from one for a VP of Sales. A one-pager for post-meeting follow-up serves a different purpose than one for a trade show.
Reps need information in 3 seconds, not 30. Use bold headers, short bullets, and visual hierarchy. If a rep can't find the answer mid-call, the doc has failed.
Every claim connects to revenue, efficiency, or risk reduction. Features mean nothing without the "so what." Replace "AI-powered analytics" with "cut reporting time by 80%."
| Buyer | Emphasize | De-emphasize |
|---|---|---|
| Technical buyer | Architecture, security, integrations, API | ROI calculations, business metrics |
| Economic buyer | ROI, payback period, total cost, risk | Technical details, implementation specifics |
| Champion | Internal selling points, quick wins, peer proof | Deep technical or financial detail |
For full slide-by-slide guidance: See references/deck-frameworks.md
For templates by use case: See references/one-pager-templates.md
| Category | Examples |
|---|---|
| Price | "Too expensive," "No budget this quarter," "Competitor is cheaper" |
| Timing | "Not the right time," "Maybe next quarter," "Too busy to implement" |
| Competition | "We already use X," "What makes you different?" |
| Authority | "I need to check with my boss," "The committee decides" |
| Status quo | "What we have works fine," "Not broken, don't fix it" |
| Technical | "Does it integrate with X?," "Security concerns," "Can it scale?" |
For each objection, document:
For the full objection library: See references/objection-library.md
Inputs (current state metrics the prospect provides):
- Time spent on manual processes
- Current tool costs
- Error rates or inefficiency metrics
- Team size
Calculations (your formula for value):
- Time saved per week/month/year
- Cost reduction (tools, headcount, errors)
- Revenue impact (faster deals, higher conversion)
Outputs (what the prospect sees):
- Annual ROI percentage
- Payback period in months
- Total 3-year value
| Persona | Cares About | Lead With |
|---|---|---|
| CTO / VP Eng | Architecture, scale, security, team velocity | Technical superiority, integration depth |
| VP Sales | Pipeline, quota attainment, rep productivity | Revenue impact, time savings per rep |
| CFO | Total cost, payback period, risk | ROI, cost reduction, financial predictability |
| End user | Ease of use, daily workflow, learning curve | Time saved, frustration eliminated |
| Type | Duration | Focus |
|---|---|---|
| Discovery call | 30 min | Qualify, understand pain, map buying process |
| First demo | 30-45 min | Show 3-4 workflows tied to their pain |
| Technical deep-dive | 45-60 min | Architecture, security, integrations, API |
| Executive overview | 20-30 min | Business outcomes, ROI, strategic alignment |
For full script templates: See references/demo-scripts.md
Marketing case studies tell a story. Sales case studies arm reps with fast-access proof. Keep them short, outcome-focused, and tagged for retrieval.
Organize case studies so reps can find the right one instantly:
- By industry — "Show me a case study for healthcare"
- By use case — "Show me someone who used us for X"
- By company size — "Show me an enterprise example"
Playbooks die when they're not updated. Review quarterly, get input from top reps, and remove anything outdated. Assign an owner — if nobody owns it, it rots.
| Field | Description |
|---|---|
| Role / title | Common titles and reporting structure |
| Goals | What success looks like for them |
| Pains | What frustrates them daily |
| Top objections | The 3-5 objections you'll hear from this role |
| Evaluation criteria | How they judge solutions |
| Buying process | Their role in the decision, who they influence |
| Messaging angle | The one sentence that resonates most |
Deliver the right format for each asset type:
| Asset | Deliverable |
|---|---|
| Sales deck | Slide-by-slide outline with headline, body copy, and speaker notes |
| One-pager | Full copy with layout guidance (visual hierarchy, sections) |
| Objection doc | Table format: objection, response, proof point, follow-up |
| Demo script | Scene-by-scene with timing, talk track, and interaction points |
| ROI calculator | Input fields, formulas, output display with sample data |
| Playbook | Structured document with table of contents and sections |
| Persona card | One-page card format per persona |
| Proposal | Section-by-section copy with customization notes |
If context is missing, ask:
For partner sales enablement, see the tools registry:
| Tool | What It Does | Guide |
|---|---|---|
| Introw | Partner engagement tracking, deal registration, mutual action plans | introw.md |
Detailed slide-by-slide guidance for building sales decks that tell a story and close deals.
Every great deck follows a narrative structure: Situation → Complication → Resolution.
The goal is not to present features. The goal is to make the buyer feel understood, then show them a better way.
What to include:
- The challenge your buyer faces daily
- A stat or data point that quantifies the problem
- Visual: simple graphic or striking number
What to avoid:
- Starting with your company or product
- Generic industry trends that don't connect to pain
- More than one core problem
Copy prompt: "What is the one problem that, if you could describe it perfectly, would make your buyer say 'that's exactly my situation'?"
What to include:
- Financial impact (revenue lost, costs incurred)
- Time impact (hours wasted, delays)
- Risk impact (what happens if they do nothing)
- Specific numbers wherever possible
What to avoid:
- Vague claims without data
- Fear-mongering without substance
- Too many metrics (pick 2-3 that hit hardest)
Copy prompt: "If your buyer does nothing for the next 12 months, what does it cost them?"
What to include:
- Market trend or technology change creating a new opportunity
- Why "the old way" no longer works
- Why now is the right time to act
What to avoid:
- Hype-driven trends without substance
- Making it about your product yet
- Overly technical explanations
Copy prompt: "What has changed in the market that makes the old approach unsustainable?"
What to include:
- Your philosophy or unique point of view
- How your approach differs from conventional solutions
- The "aha" insight that led to your product
What to avoid:
- Feature lists (too early)
- Jargon or acronyms
- Claiming to be "the only" or "the first" unless provably true
Copy prompt: "What do you believe about solving this problem that most people get wrong?"
What to include:
- 3-4 key workflows that map to the pain from Slide 1
- Screenshots or product visuals
- Brief description of what each workflow accomplishes
What to avoid:
- Showing every feature
- Dense UI screenshots without callouts
- Talking about technology instead of outcomes
Copy prompt: "Walk through 3 things the buyer would do in your product in their first week."
What to include:
- Customer logos (aim for recognizable names in their industry)
- Key metrics: "X% improvement," "Y hours saved," "Z% increase"
- Analyst recognition, awards, or certifications if relevant
What to avoid:
- Unsubstantiated claims
- Too many logos without context
- Vanity metrics that don't relate to the buyer's pain
Copy prompt: "What are 3 numbers that prove your product works?"
What to include:
- One customer story told well: challenge, solution, results
- Specific metrics (before and after)
- Customer quote if available
- Choose a customer similar to the prospect
What to avoid:
- Multiple case studies crammed into one slide
- Generic outcomes without specifics
- Customers from irrelevant industries
Copy prompt: "Tell the story of one customer who went from struggling to succeeding with your product."
What to include:
- Clear phases with timeline (e.g., Week 1: Setup, Week 2-3: Integration, Week 4: Live)
- What's required from their side vs. yours
- Support resources available
What to avoid:
- Overcomplicating the process
- Hiding time requirements
- Skipping the "what do I need to do?" question
Copy prompt: "How does a customer get from signing to live? What does each week look like?"
What to include:
- Expected return based on their inputs or industry benchmarks
- Payback period
- Total value over 1-3 years
- Comparison to cost of inaction
What to avoid:
- Unrealistic projections
- ROI without showing your math
- Generic numbers not tied to their situation
Copy prompt: "If they buy today, what does the next 12 months look like in dollars and hours?"
What to include:
- Pricing tiers or structure
- What's included at each level
- Recommended plan for their situation
What to avoid:
- Burying the price or being cagey
- Too many options (3 tiers max)
- Surprising them with hidden costs
Copy prompt: "What does it cost, what do they get, and which plan is right for them?"
What to include:
- Specific next action with timeline ("Start a pilot next week")
- What happens after they say yes
- Your contact information
What to avoid:
- Vague CTAs ("Let's stay in touch")
- Multiple competing next steps
- Ending without energy
Copy prompt: "What is the one thing you want them to do after this meeting?"
Add:
- Architecture diagram slide after Product Walkthrough
- Security and compliance details
- Integration ecosystem and API capabilities
- Technical implementation requirements
Remove or minimize:
- ROI calculations (they care about capability, not cost)
- High-level market trends (they want specifics)
Adjust tone: Precise, no fluff, respect their expertise. Avoid marketing superlatives.
Add:
- Detailed ROI slide with calculations shown
- Total cost of ownership comparison
- Risk mitigation and compliance
- Executive summary slide up front
Remove or minimize:
- Technical details and architecture
- Feature-level walkthroughs
- Implementation specifics (they'll delegate)
Adjust tone: Business-focused, outcome-driven. Speak in dollars and percentages.
Add:
- "Internal selling" slide — key points for them to present to their team
- Quick-win slide — what success looks like in 30 days
- Peer proof — companies like theirs who succeeded
- Objection pre-handling — common pushback they'll face internally
Remove or minimize:
- Deep technical or financial detail
- Anything that requires context they can't relay
Adjust tone: Empowering, equipping. Make them look smart to their boss.
Every slide is a feature with a screenshot. No story, no "so what," no connection to the buyer's world. Reps click through it; prospects tune out.
Slides with 200+ words. Nobody reads them during a presentation. If the slide requires reading, it belongs in a leave-behind.
Slides exist in isolation — no narrative flow from problem to solution to proof. The deck feels like a brochure, not a conversation.
Product screenshots without callouts, annotations, or context. The prospect can't tell what they're looking at or why it matters.
Jumping to product features before establishing the problem. The buyer has no frame of reference for why your features matter.
Trying to address every persona, every use case, every feature in one deck. The result is a 40-slide monster that nobody wants to sit through.
Scene-by-scene templates for different call types, with timing, talk tracks, and interaction guidance.
Duration: 30 minutes
Goal: Qualify the opportunity, understand pain, map the buying process.
Talk track:
"Thanks for taking the time, [Name]. I've done some research on [Company] but I'd love to hear from you directly. My goal for today is to understand what you're working on and see if there's a fit — and if there's not, I'll tell you that too. Sound good?"
What to establish:
- Set the agenda and time expectation
- Position yourself as a peer, not a pitch person
- Get permission to ask questions
Questions to ask:
- "Can you walk me through how your team handles [relevant process] today?"
- "What tools are you currently using for this?"
- "How many people are involved in this workflow?"
- "How long has this been in place?"
What you're listening for:
- Current process and tools
- Team size and structure
- How established (and how entrenched) the current approach is
Questions to ask:
- "What's the biggest challenge with that process today?"
- "When that breaks down, what happens?"
- "How much time does your team spend on [specific task] per week?"
- "What have you tried to fix this?"
- "If you could wave a magic wand, what would change?"
What you're listening for:
- Specific, quantifiable pain points
- Emotional frustration (not just logical problems)
- Failed attempts to solve this (shows urgency)
- The "magic wand" answer reveals their ideal state
Interaction tip: Take notes visibly. Repeat back what you hear: "So if I understand correctly, the biggest issue is [X], which costs you about [Y] per month. Is that right?"
Questions to ask:
- "Where does solving this sit on your priority list this quarter?"
- "What happens if you don't solve this in the next 6 months?"
- "Who else is affected by this problem?"
- "Is there budget allocated for solving this?"
What you're listening for:
- Priority level (nice-to-have vs. must-solve)
- Urgency and consequences of inaction
- Organizational breadth of the problem
- Budget signals
Questions to ask:
- "If you decided this was the right solution, what does the evaluation process look like?"
- "Who else would be involved in the decision?"
- "Have you evaluated solutions for this before?"
- "What's your timeline for making a decision?"
What you're listening for:
- Decision-making process and stakeholders
- Past evaluation experience (and why they didn't buy)
- Timeline for decision
Talk track:
"Based on what you've shared, I think there's a strong fit — specifically around [pain point 1] and [pain point 2]. What I'd suggest as a next step is a 30-minute demo where I can show you exactly how we'd address those. I'll customize it to your workflow. Does [specific date/time] work?"
What to do:
- Summarize the 2-3 key pain points
- Propose a specific next step with a date
- Send a calendar invite before you hang up
Duration: 30-45 minutes
Goal: Show how your product solves their specific pain. Advance to evaluation/pilot.
Talk track:
"Last time we spoke, you mentioned [pain point 1], [pain point 2], and [goal]. I've put together a demo focused on those three areas. If I've missed anything, flag it and we'll adjust. Sound good?"
What to do:
- Recap discovery findings to show you listened
- Confirm priorities haven't changed
- Set expectation for what they'll see
Structure:
1. Restate the pain: "You mentioned [specific problem]..."
2. Show the solution: Walk through the workflow step by step
3. Highlight the outcome: "This means [specific benefit]..."
Interaction point (at the 5-min mark):
"How does this compare to how you're handling it today?"
What to avoid:
- Showing every feature of this section
- Getting lost in settings or configuration
- Talking for more than 3 minutes without asking a question
Structure:
Same as Workflow 1 — restate pain, show solution, highlight outcome.
Interaction point:
"Is this the kind of visibility your team has been asking for?"
Structure:
Show something they can't do today and can't get from competitors.
Talk track:
"This is where we're really different from [competitor/status quo]. [Explain the unique capability]. For example, [Customer] uses this to [specific outcome]."
Interaction point:
"How would your team use this?"
Talk track:
"Let me share a quick example. [Customer similar to them] was in a similar situation — [brief challenge]. After implementing, they saw [specific metrics]. Their [role] said [quote]."
What to do:
- Choose a case study that matches their industry, size, or use case
- Keep it brief — this is reinforcement, not a presentation
Talk track:
"Based on what we've covered, here's what I'd recommend as next steps: [specific next step]. This typically takes [timeline]. Who else on your team should be involved? I can set up a [follow-up meeting type] for [date]."
What to do:
- Propose a specific next step (not "let me know")
- Identify additional stakeholders to involve
- Set a follow-up date before ending the call
- Send recap email within 2 hours
Duration: 45-60 minutes
Goal: Satisfy technical evaluation criteria. Address architecture, security, and integration concerns.
Talk track:
"I know your goal today is to understand the technical details — architecture, security, integrations, and how this fits your stack. I'll walk through each area and leave plenty of time for questions. What's your top priority for this session?"
Attendees: Typically includes their technical evaluator (engineer, architect, IT lead) plus your SE or solutions engineer.
Cover:
- High-level architecture diagram
- Infrastructure and hosting (cloud provider, regions)
- Data flow and storage
- Scalability approach
- Uptime SLA and reliability track record
Interaction point:
"How does this compare to your current infrastructure requirements?"
Cover:
- Certifications (SOC 2, ISO 27001, HIPAA, etc.)
- Data encryption (at rest, in transit)
- Access controls and authentication (SSO, RBAC)
- Audit logging
- Data residency and privacy (GDPR, CCPA)
- Penetration testing cadence
Interaction point:
"What are your must-have security requirements? I want to make sure we address them specifically."
Cover:
- Native integrations relevant to their stack
- API capabilities (REST, GraphQL, webhooks)
- Authentication methods
- Rate limits and data sync frequency
- Live demo of relevant integration
Interaction point:
"Walk me through your current stack — I want to map out exactly how we'd fit in."
Cover:
- Implementation timeline and phases
- Data migration process
- Configuration requirements
- Training and onboarding
- Ongoing support model
Interaction point:
"What does your team's capacity look like for implementation? That helps me scope the right timeline."
Talk track:
"What questions do I need to answer for you to feel confident about the technical fit?"
What to do:
- Answer directly — if you don't know, say so and follow up
- Document all questions for follow-up
- Propose next step (security review, proof of concept, pilot)
- Send technical documentation summary within 24 hours
Duration: 20-30 minutes
Goal: Get executive buy-in on the business case. Advance to budget approval or decision.
Talk track:
"Thanks for your time, [Name]. [Champion] has been evaluating [your product] and the results look strong. I'll keep this focused on the business impact and what a partnership looks like. I know your time is valuable so I'll aim to leave 10 minutes for questions."
What to do:
- Be concise — executives punish rambling
- Reference the champion and work done so far
- Set a clear agenda
Talk track:
"Based on what [Champion] shared, your team is spending [X hours/$ amount] on [problem]. That's [annual cost]. It's also creating [secondary impact: risk, delays, churn]. This isn't unique to you — it's an industry-wide challenge, and the companies solving it are seeing [outcome]."
What to do:
- Use their numbers, not generic benchmarks
- Connect to metrics they care about (revenue, cost, risk)
- Keep it to 2-3 key points
Talk track:
"Here's what we do differently. [One-sentence explanation]. For your team specifically, this means [specific benefit 1] and [specific benefit 2]. [Champion]'s team has already seen [early result or reaction from evaluation]."
What to do:
- High-level, not feature-level
- Tie to their strategic priorities
- Reference the champion's evaluation
Talk track:
"Here's the business case. Based on your team's numbers: [walk through ROI calculation]. Expected payback period is [X months]. Over 3 years, the total value is [$ amount]. [Customer similar to them] saw [specific result] within [timeframe]."
What to do:
- Show the math, not just the conclusion
- Use conservative estimates (executives discount inflated numbers)
- One strong case study, not three weak ones
Talk track:
"What questions do you have? And — assuming the business case holds up, what does the decision process look like from here?"
What to do:
- Listen more than talk
- Answer concisely
- Get a clear next step and timeline
- Thank the champion in front of the executive
When a prospect asks to see something during the demo:
Never say "I'll get back to you" without writing it down and following up within 24 hours.
Common B2B SaaS objections with response frameworks. Organized by category for quick reference.
For live calls. Find the objection, scan the response, reference the proof.
| Objection | Response (1-line) | Proof Point |
|---|---|---|
| "Too expensive" | "Compared to what? Let's look at what the problem costs you today." | ROI case study showing payback in X months |
| "No budget" | "When budget opens up, what would need to be true for this to be a priority?" | Customer who started with a pilot to prove value |
| "Competitor is cheaper" | "They are — here's what you give up at that price point." | Feature comparison + customer who switched |
| "Not the right time" | "What changes next quarter that makes it better timing?" | Cost-of-delay calculation |
| "Maybe next quarter" | "Happy to reconnect. What would a pilot look like before then?" | Customer who started small and expanded |
| "We use X already" | "How's that working for [specific pain area]?" | Customer who switched from X |
| "What makes you different?" | "For teams like yours, the biggest difference is [specific differentiator]." | Side-by-side comparison for their use case |
| "Need to check with my boss" | "Absolutely. What would help you make the case? I can send materials." | Champion one-pager, ROI calculator |
| "The committee decides" | "Who's on the committee and what does each person care about?" | Multi-persona case study |
| "What we have works fine" | "It does work — the question is whether it's costing you more than it should." | Benchmark data showing efficiency gaps |
| "Not broken, don't fix it" | "Agreed — this isn't about fixing, it's about the opportunity cost of the current approach." | Customer who didn't know what they were missing |
| "Does it integrate with X?" | "Yes / Let me check and get you specifics by end of day." | Integration documentation, customer using same stack |
| "Security concerns" | "Completely fair. Here's our security overview — happy to loop in our team." | SOC 2 report, security whitepaper |
| "Can it scale?" | "We serve companies from [small] to [large]. Here's an example at your scale." | Case study at similar scale |
| "We tried something like this before" | "What went wrong? Understanding that helps me show how we're different." | Customer with same failed experience who succeeded with you |
Why they say it: May be genuine budget constraint, sticker shock, or negotiation tactic. Often means they don't yet see enough value to justify the cost.
Response approach:
1. Don't defend the price immediately. Ask "Compared to what?"
2. Reframe from cost to investment — what does the problem cost them today?
3. Walk through the ROI calculation together
4. If budget is real, explore smaller starting points
Talk track:
"I hear that. Let me ask — what's the cost of the problem we discussed? You mentioned your team spends [X hours] on [task] every week. At your team's loaded cost, that's roughly [$ amount] per year. Our solution runs [$ price] — so the question is whether eliminating that problem is worth the investment."
Proof point: ROI calculator or case study showing payback period.
Follow-up question: "If the ROI was clear, is this something you'd prioritize this quarter?"
Why they say it: Budget may genuinely be allocated. Or they haven't identified budget because priority isn't established.
Response approach:
1. Validate — budget constraints are real
2. Understand timing — when does budget cycle reset?
3. Explore alternatives — pilot, smaller scope, different budget line
4. Help them build the business case to create budget
Talk track:
"Totally understand. Two questions: When does your next budget cycle open? And — if we could show clear ROI with a limited pilot, is that something you could fund from a different line item? Sometimes teams fund this from the efficiency savings it creates."
Proof point: Customer who started with a small pilot and expanded after proving ROI.
Follow-up question: "Would it help if I put together an ROI brief you could share with your finance team?"
Why they say it: They're comparing prices, possibly without comparing capabilities. May be using competitor price as leverage.
Response approach:
1. Acknowledge the price difference — don't pretend it doesn't exist
2. Shift to total cost of ownership and value delivered
3. Highlight what they lose at the lower price point
4. Share proof from customers who evaluated both
Talk track:
"You're right, [Competitor] is less expensive. Here's what I've seen from teams who evaluated both: [Competitor] works well for [their strength]. Where it falls short is [specific gap]. Customers like [name] actually switched to us after starting with [Competitor] because [specific reason]. The question is whether [specific capability] is worth the difference for your team."
Proof point: Customer who switched from the competitor, with specific reasons.
Follow-up question: "What's most important to your team — the lowest price or the best fit for [their specific need]?"
Why they say it: Competing priorities, organizational change, genuine capacity constraint, or lack of urgency.
Response approach:
1. Understand what's competing for their attention
2. Quantify the cost of waiting
3. Explore low-commitment next steps that keep momentum
4. Set a concrete follow-up date
Talk track:
"I get it — timing matters. Can I ask what's taking priority right now? The reason I bring up timing is that every month of [problem], based on our earlier conversation, costs your team roughly [$ amount]. A 3-month delay is [$ amount]. What if we mapped out a start date that works with your calendar so you're not losing that value?"
Proof point: Cost-of-delay calculation based on their specific numbers.
Follow-up question: "What would need to change for this to move up in priority?"
Why they say it: Genuine scheduling, or a polite way of saying "not interested enough right now."
Response approach:
1. Accept the timeline gracefully
2. Propose a small action now that maintains momentum
3. Get a specific date for follow-up
4. Send value in the meantime (content, benchmarks, insights)
Talk track:
"Next quarter works. To make sure we hit the ground running, would it make sense to do [small next step] now? That way when Q[X] starts, you're not starting from scratch. I'll also send over [relevant content] in the meantime. Can we lock in [specific date] to reconnect?"
Proof point: Customer who started the evaluation process early and was live by their target date.
Follow-up question: "Is there anything I can send between now and then that would be helpful?"
Why they say it: They have an existing solution and switching has real costs. May be satisfied, or may have frustrations they haven't voiced.
Response approach:
1. Don't trash the competitor — ask how it's working
2. Probe for specific pain points with their current solution
3. Position as complementary if possible, replacement if not
4. Offer a side-by-side comparison or trial
Talk track:
"How's that working for you? Specifically, when it comes to [area where you're stronger] — is that meeting your needs? The reason I ask is that most teams who come to us from [Competitor] tell us [specific pain point] was the tipping point. Not saying that's you, but worth exploring."
Proof point: Customer who switched from that specific competitor.
Follow-up question: "If you could change one thing about your current setup, what would it be?"
Why they say it: They're evaluating options and want a clear differentiator. Sometimes a genuine question, sometimes a test.
Response approach:
1. Don't list features — give the one thing that matters most for their situation
2. Tie the differentiator to their specific pain
3. Back it up with proof
4. Offer to show, not just tell
Talk track:
"For teams like yours — [their industry/size/use case] — the biggest difference is [specific differentiator]. That matters because [connection to their pain]. For example, [Customer] was evaluating us alongside [Competitor] and chose us because [specific reason]. Want me to walk you through how that works?"
Proof point: Case study of a customer who chose you over alternatives.
Follow-up question: "What's the most important criteria for your decision?"
Why they say it: They may not be the decision maker, or they need internal buy-in to proceed. Could also be a stall tactic.
Response approach:
1. Support them, don't pressure them
2. Arm them with materials to sell internally
3. Offer to join a meeting with their boss
4. Understand what their boss cares about
Talk track:
"Absolutely — what would help you make the case? I can put together a one-pager that covers the ROI and addresses the concerns your boss is likely to have. Also happy to jump on a quick call with them if that would be helpful. What does your boss typically prioritize — cost savings, risk reduction, or efficiency?"
Proof point: Champion enablement one-pager, ROI calculator.
Follow-up question: "What questions do you think your boss will ask?"
Why they say it: Enterprise buying involves multiple stakeholders. Genuine process, not a brush-off.
Response approach:
1. Map the buying committee — who's involved and what each person cares about
2. Provide persona-specific materials
3. Offer to present to the committee
4. Help your champion navigate the internal process
Talk track:
"That makes sense. Can you walk me through who's on the committee and what each person cares about? I can tailor materials for each stakeholder so you're not doing all the heavy lifting. I've also got a deck designed for executive presentations if that would be useful."
Proof point: Multi-stakeholder case study showing how different personas were addressed.
Follow-up question: "Who on the committee is most likely to push back, and what would their concern be?"
Why they say it: Inertia is real. The current solution may be adequate, and change has real costs.
Response approach:
1. Agree — don't argue with their experience
2. Shift from "broken vs. fixed" to "good vs. great"
3. Introduce the concept of opportunity cost
4. Show what peers are achieving
Talk track:
"It probably does work — and I wouldn't suggest changing something that's truly meeting your needs. The question I'd ask is: is 'works fine' the bar? Teams using [your product] are seeing [specific outcome]. If you're leaving [X% improvement] on the table, is that worth exploring?"
Proof point: Benchmark data showing what's possible vs. status quo.
Follow-up question: "If there were one area where your current approach could be better, what would it be?"
Why they say it: Integration is a real requirement. They need to know your product fits their stack.
Response approach:
1. Answer directly — yes, no, or "let me check"
2. If yes, provide specifics (native, API, Zapier, etc.)
3. If no, explain alternatives or workarounds
4. Never bluff — they'll find out during evaluation
Talk track (if yes):
"Yes, we integrate with [X] natively. It takes about [time] to set up. [Customer] runs the same stack and here's how they have it configured."
Talk track (if no):
"We don't have a native integration with [X] today. Here's what customers typically do: [alternative]. We also have an open API that [description]. Would it help to get our technical team on a call to explore options?"
Proof point: Customer using the same tech stack, integration documentation.
Follow-up question: "What other tools are in your stack that we'd need to work with?"
Why they say it: Legitimate concern, especially in regulated industries or enterprise. Non-negotiable for many buyers.
Response approach:
1. Take it seriously — never dismiss security concerns
2. Provide documentation proactively (SOC 2, security whitepaper)
3. Offer to loop in your security team
4. Ask about their specific requirements
Talk track:
"That's exactly the right question to ask. Here's our security overview — we're [SOC 2 Type II / ISO 27001 / etc.] certified, and I can share our full security documentation. We also have a security team that's happy to do a review call with your infosec team. What are your specific requirements?"
Proof point: Security certifications, compliance documentation, customers in regulated industries.
Follow-up question: "Do you have a security questionnaire you'd like us to fill out?"
Templates for different one-pager use cases, with layout guidance and copy prompts.
The default one-pager. Introduces your product to someone who knows nothing about you.
[Logo] [Tagline]
HEADLINE: One sentence describing what you do and who it's for.
THE PROBLEM
2-3 sentences describing the pain your buyer faces.
THE SOLUTION
2-3 sentences describing how your product solves it.
WHY [YOUR PRODUCT]
• Differentiator 1 — One sentence explaining the benefit
• Differentiator 2 — One sentence explaining the benefit
• Differentiator 3 — One sentence explaining the benefit
PROOF
"Customer quote with specific result." — Name, Title, Company
[Optional: 2-3 metric callouts: "X% improvement", "Y hours saved"]
[CTA Button/Link] [Contact: name@company.com]
Tailored to a specific workflow, vertical, or problem. More targeted than the product overview.
[Logo] [Use Case: e.g., "For Sales Teams"]
HEADLINE: How [your product] helps [persona] [achieve outcome].
THE CHALLENGE
When [persona] needs to [task], they face [specific pain].
This leads to [consequence]: [time wasted / money lost / risk].
HOW IT WORKS
1. [Step 1] — What happens and why it matters
2. [Step 2] — What happens and why it matters
3. [Step 3] — What happens and why it matters
RESULTS
• [Metric 1]: Before → After
• [Metric 2]: Before → After
• [Metric 3]: Before → After
CUSTOMER SPOTLIGHT
"Quote about this specific use case." — Name, Title, Company
[CTA: "See it in action" or "Start a pilot"] [Contact info]
Designed to reinforce a conversation that already happened. Summarizes what you discussed and proposes next steps.
[Logo] [Date of Meeting]
MEETING RECAP: [Company Name]
WHAT WE DISCUSSED
• [Pain point 1 they mentioned]
• [Pain point 2 they mentioned]
• [Goal they're trying to achieve]
HOW [YOUR PRODUCT] HELPS
• [Solution to pain 1] — [Specific capability or workflow]
• [Solution to pain 2] — [Specific capability or workflow]
• [How you help them reach their goal]
RELEVANT PROOF
"Quote from a similar customer." — Name, Title, Company
[1-2 metrics from a similar customer]
PROPOSED NEXT STEPS
1. [Next step with date]
2. [Follow-up action]
3. [Decision timeline]
[Your name] | [Your title] | [Email] | [Phone]
Designed specifically for your internal champion to share with their team and leadership. Written to make them look smart.
[Logo]
WHY WE'RE EVALUATING [YOUR PRODUCT]
THE SITUATION
[2-3 sentences about the internal challenge, written as if the champion
is explaining it to their team. Use "we" and "our" language.]
WHAT [YOUR PRODUCT] DOES
[1-2 sentences. Plain language, no jargon.]
WHY THIS SOLUTION
• [Reason 1] — How it solves our specific problem
• [Reason 2] — How it compares to what we do today
• [Reason 3] — How it compares to alternatives we evaluated
EXPECTED IMPACT
• [Metric]: Current state → Expected state
• [Metric]: Current state → Expected state
• [Time to value]: Live within [X weeks]
WHO ELSE USES IT
[2-3 recognizable company names in their industry]
"Relevant customer quote." — Name, Title, Company
NEXT STEPS
• [What we're doing next]
• [What we need from the team]
• [Decision timeline]
Questions? Talk to [Champion name] or [Your name at email].
| Element | Suggested Size |
|---|---|
| Headline | 18-24pt |
| Section headers | 12-14pt bold |
| Body text | 10-11pt |
| Fine print / footer | 8-9pt |