AIpkgs · box · detail

box

MarketingSkills

“42 marketing skills for founders and technical marketers — CRO, copywriting, cold email, prospecting, SEO, AI SEO, paid ads, ad creative, video, pricing, referrals, and growth.”

editionv0.1.0

imprintmarketingskills

manifest1 ln · 418 B

leaves172 · 1.4 MB

MarketingSkills

A box of 42 marketing skills for founders and technical marketers, covering conversion optimization, copywriting, cold email, prospecting, SEO, AI SEO, paid ads, ad creative, video, pricing, referrals, revenue operations, and growth.

Each skill is a self-contained SKILL.md (with supporting references/ and evals/) that activates when you describe the relevant marketing task.

Skills

ab-testing, ad-creative, ads, ai-seo, analytics, aso, churn-prevention, co-marketing, cold-email, community-marketing, competitor-profiling, competitors, content-strategy, copy-editing, copywriting, cro, customer-research, directory-submissions, emails, free-tools, image, launch, lead-magnets, marketing-ideas, marketing-psychology, onboarding, paywalls, popups, pricing, product-marketing, programmatic-seo, prospecting, referrals, revops, sales-enablement, schema, seo-audit, signup, site-architecture, sms, social, video.

Attribution

Imported from coreyhaines31/marketingskills by Corey Haines, under the MIT License (see LICENSE.txt).

Note: upstream skills link to a repo-level tools/ directory of integration references and CLI scripts. That directory is not part of the skill package format, so those ../../tools/... links are not bundled here — the skill instructions themselves are self-contained.

Install

npx @aipkgs/cli install aipkgs/marketingskills/MarketingSkills

tree1.4 MB

skills169
- ab-testing04
  - evals01
  - references02
- ad-creative04
  - evals01
  - references02
- ads06
  - evals01
  - references04
- ai-seo05
  - evals01
  - references03
- analytics05
  - evals01
  - references03
- aso07
  - evals01
  - references05
- churn-prevention04
  - evals01
  - references02
- co-marketing02
  - evals01
- cold-email07
  - evals01
  - references05
- community-marketing02
  - evals01
- competitor-profiling04
  - evals01
  - references02
- competitors04
  - evals01
  - references02
- content-strategy03
  - evals01
  - references01
- copy-editing05
  - evals01
  - references03
- copywriting04
  - evals01
  - references02
- cro04
  - evals01
  - references02
- customer-research03
  - evals01
  - references01
- directory-submissions05
  - evals01
  - references03
- emails05
  - evals01
  - references03
- free-tools03
  - evals01
  - references01
- image03
  - evals01
  - references01
- launch02
  - evals01
- lead-magnets04
  - evals01
  - references02
- marketing-ideas03
  - evals01
  - references01
- marketing-psychology02
  - evals01
- onboarding03
  - evals01
  - references01
- paywalls03
  - evals01
  - references01
- popups02
  - evals01
- pricing04
  - evals01
  - references02
- product-marketing02
  - evals01
- programmatic-seo03
  - evals01
  - references01
- prospecting07
  - evals01
  - references05
- referrals04
  - evals01
  - references02
- revops06
  - evals01
  - references04
- sales-enablement06
  - evals01
  - references04
- schema03
  - evals01
  - references01
- seo-audit04
  - evals01
  - references02
- signup02
  - evals01
- site-architecture05
  - evals01
  - references03
- sms05
  - evals01
  - references03
- social07
  - evals01
  - references05
- video03
  - evals01
  - references01

mdREADME.md

1.5 kB

# MarketingSkills

A box of 42 marketing skills for founders and technical marketers, covering

conversion optimization, copywriting, cold email, prospecting, SEO, AI SEO, paid

ads, ad creative, video, pricing, referrals, revenue operations, and growth.

Each skill is a self-contained `SKILL.md` (with supporting `references/` and

`evals/`) that activates when you describe the relevant marketing task.

## Skills

`ab-testing`, `ad-creative`, `ads`, `ai-seo`, `analytics`, `aso`,

`churn-prevention`, `co-marketing`, `cold-email`, `community-marketing`,

`competitor-profiling`, `competitors`, `content-strategy`, `copy-editing`,

`copywriting`, `cro`, `customer-research`, `directory-submissions`, `emails`,

`free-tools`, `image`, `launch`, `lead-magnets`, `marketing-ideas`,

`marketing-psychology`, `onboarding`, `paywalls`, `popups`, `pricing`,

`product-marketing`, `programmatic-seo`, `prospecting`, `referrals`, `revops`,

`sales-enablement`, `schema`, `seo-audit`, `signup`, `site-architecture`, `sms`,

`social`, `video`.

## Attribution

Imported from [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills)

by Corey Haines, under the MIT License (see `LICENSE.txt`).

> Note: upstream skills link to a repo-level `tools/` directory of integration

> references and CLI scripts. That directory is not part of the skill package

> format, so those `../../tools/...` links are not bundled here — the skill

> instructions themselves are self-contained.

## Install

```sh

npx @aipkgs/cli install aipkgs/marketingskills/MarketingSkills

```

jsonskills/ab-testing/evals/evals.json

7.7 kB

{

"skill_name": "ab-testing",

"evals": [

{

"id": 1,

"prompt": "I want to A/B test our homepage headline. We currently say 'The All-in-One Project Management Tool' and want to test something benefit-focused. We get about 15,000 visitors/month and our current signup rate is 3.2%.",

"expected_output": "Should check for product-marketing.md first. Should build a proper hypothesis using the framework: 'Because [observation], we believe [change] will cause [outcome], which we'll measure by [metric].' Should identify this as an A/B test (two variants). Should calculate or reference sample size needs based on 15,000 monthly visitors and 3.2% baseline. Should define primary metric (signup rate), secondary metrics, and guardrail metrics. Should warn about the peeking problem and recommend a fixed test duration. Should provide the test plan in the structured output format.",

"assertions": [

"Checks for product-marketing.md",

"Uses the hypothesis framework with observation, belief, outcome, and metric",

"Identifies as A/B test type",

"Addresses sample size calculation based on traffic and baseline rate",

"Defines primary metric (signup rate)",

"Defines secondary and guardrail metrics",

"Warns about the peeking problem",

"Provides structured test plan output"

"files": []

{

"id": 2,

"prompt": "we want to test like 4 different CTA button colors on our pricing page. is that a good idea?",

"expected_output": "Should trigger on casual phrasing. Should identify this as an A/B/n test (multiple variants). Should caution that testing 4 variants requires significantly more traffic than a simple A/B test. Should reference the sample size quick reference showing traffic multipliers for multiple variants. Should question whether button color alone is likely to produce meaningful lift vs testing CTA copy, placement, or surrounding context. Should recommend either reducing to 2 variants or ensuring sufficient traffic. Should still provide hypothesis framework and test setup if proceeding.",

"assertions": [

"Triggers on casual phrasing",

"Identifies as A/B/n test (multiple variants)",

"Cautions about increased traffic needs for 4 variants",

"References sample size requirements",

"Questions whether button color alone is high-impact",

"Suggests alternative higher-impact elements to test",

"Provides hypothesis framework"

"files": []

{

"id": 3,

"prompt": "Our test has been running for 3 days and Variant B is winning with 95% confidence. Should we call it?",

"expected_output": "Should immediately address the peeking problem. Should explain that checking results early inflates false positive rates. Should recommend running for the full pre-calculated duration regardless of early results. Should explain why early significance can be misleading (regression to the mean, day-of-week effects, audience mix shifts). Should provide guidance on when it IS appropriate to stop early (sequential testing methods). Should recommend the pre-test commitment to duration.",

"assertions": [

"Addresses the peeking problem directly",

"Explains why early significance is misleading",

"Recommends running for full pre-calculated duration",

"Mentions day-of-week effects or audience mix shifts",

"Explains false positive rate inflation from peeking",

"Mentions sequential testing as alternative approach"

"files": []

{

"id": 4,

"prompt": "Help me set up a multivariate test on our landing page. I want to test the headline, hero image, and CTA button simultaneously.",

"expected_output": "Should identify this as a Multivariate Test (MVT). Should explain that MVT tests combinations of elements and requires much more traffic than A/B tests. Should calculate or reference traffic needs (combinations multiply: e.g., 2 headlines × 2 images × 2 CTAs = 8 combinations). Should recommend MVT only if traffic supports it, otherwise suggest sequential A/B tests. Should build hypotheses for each element being tested. Should define interaction effects to watch for. Should provide structured test plan.",

"assertions": [

"Identifies as multivariate test (MVT)",

"Explains MVT tests combinations of elements",

"Addresses dramatically higher traffic requirements",

"Calculates number of combinations",

"Suggests sequential A/B tests as alternative if traffic insufficient",

"Builds hypotheses for each element",

"Provides structured test plan"

"files": []

{

"id": 5,

"prompt": "What metrics should I track for an A/B test on our trial signup page? We're testing a longer form (adds company size and role fields) against the current short form.",

"expected_output": "Should apply the metrics selection framework with three tiers: primary, secondary, and guardrail metrics. Primary: form completion rate (the direct conversion metric). Secondary: lead quality metrics (SQL conversion rate, activation rate post-signup). Guardrail: overall signup volume (ensure longer form doesn't tank total signups below acceptable threshold). Should explain the tradeoff between conversion quantity and lead quality. Should note that this test needs longer observation window to measure downstream metrics.",

"assertions": [

"Applies three-tier metric framework (primary, secondary, guardrail)",

"Identifies form completion rate as primary metric",

"Identifies lead quality as secondary metric",

"Defines guardrail metrics to protect against negative outcomes",

"Explains quantity vs quality tradeoff",

"Notes need for longer observation window for downstream metrics"

"files": []

{

"id": 6,

"prompt": "Can you help me write copy for our new landing page? We want to test it against the current version.",

"expected_output": "Should recognize this is primarily a copywriting task, not a test setup task. Should defer to or cross-reference the copywriting skill for writing the actual copy. May help frame the test hypothesis and setup, but should make clear that copywriting is the right skill for creating the page copy itself.",

"assertions": [

"Recognizes this as primarily a copywriting task",

"References or defers to copywriting skill",

"Does not attempt to write full page copy using test setup patterns",

"May offer to help with test hypothesis and setup"

"files": []

{

"id": 7,

"prompt": "We ran an A/B test on our pricing page for 4 weeks. Control: 2.1% conversion. Variant: 2.4% conversion. 12,000 visitors per variant. Is this statistically significant? Should we ship it?",

"expected_output": "Should evaluate the results against statistical significance criteria. Should calculate or estimate whether the sample size is sufficient to detect a 0.3 percentage point lift from a 2.1% baseline (this is a ~14% relative lift). Should reference the 95% confidence threshold. Should discuss practical significance vs statistical significance. Should recommend whether to ship, continue testing, or iterate. Should consider segment analysis if results are borderline.",

"assertions": [

"Evaluates against statistical significance criteria",

"Addresses whether sample size is sufficient for this effect size",

"References 95% confidence threshold",

"Distinguishes statistical significance from practical significance",

"Provides clear recommendation on shipping",

"Suggests segment analysis or follow-up if borderline"

"files": []

}

]

}

mdskills/ab-testing/references/sample-size-guide.md

7.3 kB

# Sample Size Guide

Reference for calculating sample sizes and test duration.

## Contents

- Sample Size Fundamentals (required inputs, what these mean)

- Sample Size Quick Reference Tables

- Duration Calculator (formula, examples, minimum duration rules, maximum duration guidelines)

- Online Calculators

- Adjusting for Multiple Variants

- Common Sample Size Mistakes

- When Sample Size Requirements Are Too High

- Sequential Testing

- Quick Decision Framework

## Sample Size Fundamentals

### Required Inputs

1. **Baseline conversion rate**: Your current rate

2. **Minimum detectable effect (MDE)**: Smallest change worth detecting

3. **Statistical significance level**: Usually 95% (α = 0.05)

4. **Statistical power**: Usually 80% (β = 0.20)

### What These Mean

**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.

---

## Sample Size Quick Reference Tables

### Conversion Rate: 1%

| 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 |

### Conversion Rate: 3%

| 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 |

### Conversion Rate: 5%

| 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 |

### Conversion Rate: 10%

| 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 |

### Conversion Rate: 20%

| 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 Calculator

### Formula

```

Duration (days) = (Sample per variant × Number of variants) / (Daily traffic × % exposed)

```

### Examples

**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!)

### Minimum Duration Rules

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)

### Maximum Duration Guidelines

Avoid running tests longer than 4-8 weeks:

- Novelty effects wear off

- External factors intervene

- Opportunity cost of other tests

---

## Online Calculators

### Recommended Tools

**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

---

## Adjusting for Multiple Variants

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.

---

## Common Sample Size Mistakes

### 1. Underpowered tests

**Problem**: Not enough sample to detect realistic effects

**Fix**: Be realistic about MDE, get more traffic, or don't test

### 2. Overpowered tests

**Problem**: Waiting for sample size when you already have significance

**Fix**: This is actually fine—you committed to sample size, honor it

### 3. Wrong baseline rate

**Problem**: Using wrong conversion rate for calculation

**Fix**: Use the specific metric and page, not site-wide averages

### 4. Ignoring segments

**Problem**: Calculating for full traffic, then analyzing segments

**Fix**: If you plan segment analysis, calculate sample for smallest segment

### 5. Testing too many things

**Problem**: Dividing traffic too many ways

**Fix**: Prioritize ruthlessly, run fewer concurrent tests

---

## When Sample Size Requirements Are Too High

Options when you can't get enough traffic:

1. **Increase MDE**: Accept only detecting larger effects (20%+ lift)

2. **Lower confidence**: Use 90% instead of 95% (risky, document it)

3. **Reduce variants**: Test only the most promising variant

4. **Combine traffic**: Test across multiple similar pages

5. **Test upstream**: Test earlier in funnel where traffic is higher

6. **Don't test**: Make decision based on qualitative data instead

7. **Longer test**: Accept longer duration (weeks/months)

---

## Sequential Testing

If you must check results before reaching sample size:

### What is it?

Statistical method that adjusts for multiple looks at data.

### When to use

- High-risk changes

- Need to stop bad variants early

- Time-sensitive decisions

### Tools that support it

- Optimizely (Stats Accelerator)

- VWO (SmartStats)

- PostHog (Bayesian approach)

### Tradeoff

- More flexibility to stop early

- Slightly larger sample size requirement

- More complex analysis

---

## Quick Decision Framework

### Can I run this test?

```

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

```

mdskills/ab-testing/references/test-templates.md

6.3 kB

# A/B Test Templates Reference

Templates for planning, documenting, and analyzing experiments.

## Contents

- Test Plan Template

- Results Documentation Template

- Test Repository Entry Template

- Quick Test Brief Template

- Stakeholder Update Template

- Experiment Prioritization Scorecard

- Hypothesis Bank Template

## Test Plan Template

```markdown

# 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

```

---

## Results Documentation Template

```markdown

# 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

|---------|--------|--------|-------------|

| Control | X | Y | Z% |

| Variant | X | Y | Z% |

### Primary Metric: [Metric Name]

|---------|-------|--------|-------------|

| 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 1] | X | Y | +Z% | Yes/No |

| [Metric 2] | X | Y | +Z% | Yes/No |

### Guardrail Metrics

|--------|---------|---------|--------|----------|

| [Metric 1] | X | Y | +Z% | Yes/No |

### Segment Analysis

**Mobile vs. Desktop**

|---------|---------|---------|------|

| Mobile | X% | Y% | +Z% |

| Desktop | X% | Y% | +Z% |

**New vs. Returning**

|---------|---------|---------|------|

| 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.]

```

---

## Test Repository Entry Template

For tracking all tests in a central location:

```markdown

|---------|------|------|-------|----------------|--------|------|------|

| 001 | Hero headline test | Homepage | 1/1-1/15 | CTR | Winner | +12% | [Link] |

```

---

## Quick Test Brief Template

For simple tests that don't need full documentation:

```markdown

## [Test Name]

**What**: [One sentence description]

**Why**: [One sentence hypothesis]

**Metric**: [Primary metric]

**Duration**: [X weeks]

**Result**: [TBD / Winner / Loser / Inconclusive]

**Learnings**: [Key takeaway]

```

---

## Stakeholder Update Template

```markdown

## 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)

```

---

## Experiment Prioritization Scorecard

For deciding which tests to run:

|--------|--------|--------|--------|--------|

| Potential impact | 30% | | | |

| Confidence in hypothesis | 25% | | | |

| Ease of implementation | 20% | | | |

| Risk if wrong | 15% | | | |

| Strategic alignment | 10% | | | |

Scoring: 1-5 (5 = best)

---

## Hypothesis Bank Template

For collecting test ideas:

```markdown

|----|-----------|-------------|------------|------------------|--------|

```

mdskills/ab-testing/SKILL.md

11 kB

---

description: 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 copy," "multivariate test," "hypothesis," "should I test this," "which version is better," "test two versions," "statistical significance," "how long should I run this test," "growth experiments," "experiment velocity," "experiment backlog," "ICE score," "experimentation program," or "experiment playbook." Use this whenever someone is comparing two approaches and wants to measure which performs better, or when they want to build a systematic experimentation practice. For tracking implementation, see analytics. For page-level conversion optimization, see cro.

metadata:

version: 2.0.0

---

# A/B Test Setup

You are an expert in experimentation and A/B testing. Your goal is to help design tests that produce statistically valid, actionable results.

## Initial Assessment

**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:

1. **Test Context** - What are you trying to improve? What change are you considering?

2. **Current State** - Baseline conversion rate? Current traffic volume?

3. **Constraints** - Technical complexity? Timeline? Tools available?

---

## Core Principles

### 1. Start with a Hypothesis

- Not just "let's see what happens"

- Specific prediction of outcome

- Based on reasoning or data

### 2. Test One Thing

- Single variable per test

- Otherwise you don't know what worked

### 3. Statistical Rigor

- Pre-determine sample size

- Don't peek and stop early

- Commit to the methodology

### 4. Measure What Matters

- Primary metric tied to business value

- Secondary metrics for context

- Guardrail metrics to prevent harm

---

## Hypothesis Framework

### Structure

```

Because [observation/data],

we believe [change]

will cause [expected outcome]

for [audience].

We'll know this is true when [metrics].

```

### Example

**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."

---

## Test Types

| 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 |

---

## Sample Size

### Quick Reference

|----------|----------|----------|----------|

**Calculators:**

- [Evan Miller's](https://www.evanmiller.org/ab-testing/sample-size.html)

- [Optimizely's](https://www.optimizely.com/sample-size-calculator/)

**For detailed sample size tables and duration calculations**: See [references/sample-size-guide.md](references/sample-size-guide.md)

---

## Metrics Selection

### Primary Metric

- Single metric that matters most

- Directly tied to hypothesis

- What you'll use to call the test

### Secondary Metrics

- Support primary metric interpretation

- Explain why/how the change worked

### Guardrail Metrics

- Things that shouldn't get worse

- Stop test if significantly negative

### Example: Pricing Page Test

- **Primary**: Plan selection rate

- **Secondary**: Time on page, plan distribution

- **Guardrail**: Support tickets, refund rate

---

## Designing Variants

### What to Vary

| 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 |

### Best Practices

- Single, meaningful change

- Bold enough to make a difference

- True to the hypothesis

---

## Traffic Allocation

| 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

---

## Implementation

### Client-Side

- JavaScript modifies page after load

- Quick to implement, can cause flicker

- Tools: PostHog, Optimizely, VWO

### Server-Side

- Variant determined before render

- No flicker, requires dev work

- Tools: PostHog, LaunchDarkly, Split

---

## Running the Test

### Pre-Launch Checklist

- [ ] Hypothesis documented

- [ ] Primary metric defined

- [ ] Sample size calculated

- [ ] Variants implemented correctly

- [ ] Tracking verified

- [ ] QA completed on all variants

### During the Test

**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

### The Peeking Problem

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.

---

## Analyzing Results

### Statistical Significance

- 95% confidence = p-value < 0.05

- Means <5% chance result is random

- Not a guarantee—just a threshold

### Analysis Checklist

1. **Reach sample size?** If not, result is preliminary

2. **Statistically significant?** Check confidence intervals

3. **Effect size meaningful?** Compare to MDE, project impact

4. **Secondary metrics consistent?** Support the primary?

5. **Guardrail concerns?** Anything get worse?

6. **Segment differences?** Mobile vs. desktop? New vs. returning?

### Interpreting Results

| 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 |

---

## Documentation

Document every test with:

- Hypothesis

- Variants (with screenshots)

- Results (sample, metrics, significance)

- Decision and learnings

**For templates**: See [references/test-templates.md](references/test-templates.md)

---

## Growth Experimentation Program

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.

### The Experiment Loop

```

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

```

### Hypothesis Generation

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 |

### ICE Prioritization

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.

### Experiment Velocity

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 |

### The Experiment Playbook

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.

### Experiment Cadence

**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?

---

## Common Mistakes

### Test Design

- Testing too small a change (undetectable)

- Testing too many things (can't isolate)

- No clear hypothesis

### Execution

- Stopping early

- Changing things mid-test

- Not checking implementation

### Analysis

- Ignoring confidence intervals

- Cherry-picking segments

- Over-interpreting inconclusive results

---

## Task-Specific Questions

1. What's your current conversion rate?

2. How much traffic does this page get?

3. What change are you considering and why?

4. What's the smallest improvement worth detecting?

5. What tools do you have for testing?

6. Have you tested this area before?

---

## Related Skills

- **cro**: For generating test ideas based on CRO principles

- **analytics**: For setting up test measurement

- **copywriting**: For creating variant copy

jsonskills/ad-creative/evals/evals.json

6.7 kB

{

"skill_name": "ad-creative",

"evals": [

{

"id": 1,

"prompt": "Generate ad creative for our Meta (Facebook/Instagram) campaign. We sell an AI writing assistant for content marketers. Main value prop: write blog posts 5x faster. Target audience: content marketing managers at B2B SaaS companies. Budget: $5k/month.",

"expected_output": "Should check for product-marketing.md first. Should generate creative following the angle-based approach: identify 3-5 angles (speed, quality, ROI, pain of blank page, competitive edge). For each angle, should generate primary text (≤125 chars), headline (≤40 chars), and description (≤30 chars) respecting Meta character limits. Should provide multiple variations per angle. Should suggest image/visual direction for each. Should organize output with angle name, hook, body, CTA for each variation. Should recommend which angles to test first.",

"assertions": [

"Checks for product-marketing.md",

"Uses angle-based generation approach",

"Identifies multiple angles (3-5)",

"Respects Meta character limits (125/40/30)",

"Generates multiple variations per angle",

"Suggests image or visual direction",

"Includes hook, body, and CTA for each",

"Recommends which angles to test first"

"files": []

{

"id": 2,

"prompt": "I need Google Ads copy for our CRM product. We're targeting the keyword 'best CRM for small business'. Need responsive search ads.",

"expected_output": "Should generate Google RSA creative respecting character limits: headlines (≤30 chars each, need 10-15 variations) and descriptions (≤90 chars each, need 4+ variations). Should note that pinning should be used sparingly as it reduces optimization. Should include the target keyword in headlines. Should provide multiple angle-based variations. Should suggest ad extensions (sitelinks, callouts, structured snippets). Should follow Google Ads best practices for RSA.",

"assertions": [

"Respects Google RSA character limits (30 char headlines, 90 char descriptions)",

"Generates 10-15 headline variations",

"Generates 4+ description variations",

"Includes target keyword in headlines",

"Notes pinning should be used sparingly per skill guidance",

"Suggests ad extensions",

"Uses angle-based variation approach"

"files": []

{

"id": 3,

"prompt": "Here's our ad performance data: Ad A (pain point angle) - CTR 2.1%, CPC $3.20, Conv rate 4.5%. Ad B (social proof angle) - CTR 1.4%, CPC $4.10, Conv rate 6.2%. Ad C (feature angle) - CTR 0.8%, CPC $5.50, Conv rate 2.1%. Help me iterate on these.",

"expected_output": "Should activate the iteration-from-performance mode (not generate-from-scratch). Should analyze the data: Ad A has best CTR, Ad B has best conversion rate (highest efficiency despite lower CTR), Ad C is underperforming on all metrics. Should recommend doubling down on the pain point angle (high CTR) and social proof angle (high conversion), while pausing or reworking the feature angle. Should generate new variations that combine winning elements (pain point hook + social proof). Should suggest specific iterations on Ad A and Ad B.",

"assertions": [

"Activates iteration mode based on performance data",

"Analyzes CTR, CPC, and conversion rate for each ad",

"Identifies winning angles from the data",

"Recommends pausing or reworking underperforming creative",

"Generates new variations combining winning elements",

"Provides specific iterations on top performers"

"files": []

{

"id": 4,

"prompt": "we need linkedin ads for our enterprise security product. audience is CISOs and IT directors.",

"expected_output": "Should trigger on casual phrasing. Should generate LinkedIn ad creative respecting character limits: introductory text (≤150 chars), headline (≤70 chars), description (≤100 chars). Should adapt tone and messaging for enterprise security audience (CISOs, IT directors) — more formal, compliance-focused, risk-reduction language. Should provide multiple angles relevant to security buyers (risk reduction, compliance, incident response time, cost of breaches). Should suggest ad format recommendations for LinkedIn (sponsored content, message ads, etc.).",

"assertions": [

"Triggers on casual phrasing",

"Respects LinkedIn character limits (150/70/100)",

"Adapts tone for enterprise security audience",

"Uses risk-reduction and compliance language",

"Provides multiple angles relevant to security buyers",

"Suggests LinkedIn ad format recommendations"

"files": []

{

"id": 5,

"prompt": "I need to generate a big batch of ad variations for a multi-platform campaign launching next week. We're a meal delivery service targeting busy professionals. Need ads for Google, Meta, and TikTok.",

"expected_output": "Should activate the batch generation workflow. Should generate creative for all three platforms respecting each platform's character limits: Google RSA (30/90), Meta (125/40/30), TikTok (80 chars recommended, 100 max). Should identify 3-5 angles that work across platforms (convenience, health, time savings, variety, cost vs eating out). Should generate variations per angle per platform. Should note platform-specific creative considerations (TikTok needs video concepts, not just text). Should organize output clearly by platform.",

"assertions": [

"Activates batch generation workflow",

"Generates for all three platforms",

"Respects each platform's character limits",

"Identifies angles that work across platforms",

"Notes TikTok needs video concepts",

"Organizes output by platform",

"Generates multiple variations per angle per platform"

"files": []

{

"id": 6,

"prompt": "Help me plan our overall paid advertising strategy. We have a $20k monthly budget and want to figure out which platforms to use and how to allocate spend.",

"expected_output": "Should recognize this is a paid advertising strategy task, not ad creative generation. Should defer to or cross-reference the ads skill, which handles campaign strategy, platform selection, and budget allocation. May briefly mention creative considerations but should make clear that ads is the right skill for strategy.",

"assertions": [

"Recognizes this as paid ads strategy, not creative generation",

"References or defers to ads skill",

"Does not attempt full campaign strategy using creative generation patterns"

"files": []

}

]

}

mdskills/ad-creative/references/generative-tools.md

24 kB

# Generative AI Tools for Ad Creative

Reference for using AI image generators, video generators, and code-based video tools to produce ad visuals at scale.

---

## When to Use Generative Tools

| 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 |

---

## Image Generation

### Nano Banana Pro (Gemini)

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:**

```bash

# 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](https://ai.google.dev/gemini-api/docs/image-generation)

---

### Flux (Black Forest Labs)

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:**

|-------|-------|---------|------|----------|

**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](https://replicate.com/black-forest-labs/flux-2-pro), [BFL API](https://docs.bfl.ml/)

---

### Ideogram

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](https://developer.ideogram.ai/), [Ideogram](https://ideogram.ai/)

---

### Other Image Tools

|------|----------|------------|-------|

---

## Video Generation

### Google Veo

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](https://cloud.google.com/vertex-ai/generative-ai/docs/video/overview)

---

### Kling (Kuaishou)

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](https://klingai.com/global/dev/model/video)

---

### Runway

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](https://docs.dev.runwayml.com/)

---

### Sora 2 (OpenAI)

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](https://platform.openai.com/docs/guides/video-generation)

---

### Seedance 2.0 (ByteDance)

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](https://seed.bytedance.com/en/seedance2_0)

---

### Higgsfield

Full-stack video creation platform with cinematic camera controls.

**Best for:** Social video ads, cinematic style, mobile-first content

**Platform:** [higgsfield.ai](https://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

---

### Video Tool Comparison

|------|-----------|-------|------------|-----|----------|

| **Veo 3.1** | 60 sec | Native | 1080p/4K | Gemini | Vertical social video |

| **Runway Gen-4** | 10 sec | No | 1080p | Official | Controlled, consistent |

---

## Voice & Audio Generation

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.

### When to Use Voice Tools

Many video generators (Veo, Kling, Sora, Seedance) now include native audio. Use standalone voice tools when you need:

- **Voiceover on silent video** — Runway Gen-4 and Remotion produce silent output

- **Brand voice consistency** — Clone a specific voice for all ads

- **Multi-language versions** — Same ad script in 20+ languages

- **Script iteration** — Re-record voiceover without reshooting video

- **Precise control** — Exact timing, emotion, and pacing

---

### ElevenLabs

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:**

```bash

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](https://elevenlabs.io/docs/api-reference/text-to-speech)

---

### OpenAI TTS

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](https://platform.openai.com/docs/guides/text-to-speech)

---

### Cartesia Sonic

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](https://docs.cartesia.ai/build-with-cartesia/tts-models/latest)

---

### Voicebox (Open Source)

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:**

```bash

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](https://voicebox.sh), or build from source:

```bash

git clone https://github.com/jamiepine/voicebox.git

cd voicebox && make setup && make dev

```

**Docs:** [GitHub](https://github.com/jamiepine/voicebox)

---

### Other Voice Tools

|------|----------|---------------|-----|

---

### Voice Tool Comparison

|------|---------|---------|-----------|---------|----------------|

| **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 |

### Choosing a Voice Tool

```

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)

```

### Workflow: Voice + Video

```

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)

```

---

## Code-Based Video: Remotion

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](https://www.remotion.dev/)

### Why Remotion for Ads

| 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 |

### Ad Creative Use Cases

**1. Dynamic product ads**

Feed a JSON array of products and render a unique video ad for each:

```tsx

// Simplified Remotion component for product ads

export const ProductAd: React.FC<{

productName: string;

price: string;

imageUrl: string;

tagline: string;

}> = ({productName, price, imageUrl, tagline}) => {

return (

<h1>{productName}</h1>

<p>{tagline}</p>

<div className="price">{price}</div>

</AbsoluteFill>

);

};

```

**2. A/B test video variations**

Render the same template with different headlines, CTAs, or color schemes:

```tsx

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

### Remotion Workflow for Ad Creative

```

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

```

### Getting Started

```bash

# 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": [...]}'

```

---

## Choosing the Right Tool

### Decision Tree

```

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

```

### Cost Comparison for 100 Ad Variations

| 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 |

### Recommended Workflow for Scaled Ad Production

1. **Generate hero creative** with AI (Nano Banana, Flux, Veo) — high-quality, exploratory

2. **Build templates** in Remotion based on winning creative patterns

3. **Batch produce variations** with Remotion using data (products, headlines, CTAs)

4. **Iterate** — use AI tools for new angles, Remotion for scale

This hybrid approach gives you the creative exploration of AI generators and the consistency and scale of code-based rendering.

---

## Platform-Specific Image Specs

When generating images for ads, request the correct dimensions:

|----------|-----------|-------------|-----------------|

| 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.

mdskills/ad-creative/references/platform-specs.md

6.4 kB

# Platform Specs Reference

Complete character limits, format requirements, and best practices for each ad platform.

---

## Google Ads

### Responsive Search Ads (RSAs)

|---------|----------------|----------|-------|

**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)

### Performance Max

| 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 |

### Display Ads

| Element | Character Limit |

|---------|----------------|

| Headline | 30 chars |

| Long headline | 90 chars |

| Description | 90 chars |

| Business name | 25 chars |

---

## Meta Ads (Facebook & Instagram)

### Single Image / Video / Carousel

|---------|-------------|---------|-------|

**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

### Lead Ads (Instant Form)

| Element | Limit |

|---------|-------|

| Greeting headline | 60 chars |

| Greeting description | 360 chars |

| Privacy policy text | 200 chars |

---

## LinkedIn Ads

### Single Image Ad

|---------|-------------|---------|-------|

### Carousel Ad

| Element | Limit |

|---------|-------|

| Intro text | 255 chars |

| Card headline | 45 chars |

| Card count | 2-10 cards |

### Message Ad (InMail)

| Element | Limit |

|---------|-------|

| Subject line | 60 chars |

| Message body | 1,500 chars |

| CTA button | 20 chars |

### Text Ad

| 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

---

## TikTok Ads

### In-Feed Ads

|---------|-------------|---------|-------|

### Spark Ads (Boosted Organic)

| 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)

---

## Twitter/X Ads

### Promoted Tweets

| Element | Limit | Notes |

|---------|-------|-------|

| Tweet text | 280 chars | Full tweet with image/video |

| Card headline | 70 chars | Website card |

| Card description | 200 chars | Website card |

### Website Cards

| 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

---

## Character Counting Tips

- **Spaces count** as characters on all platforms

- **Emojis** count as 1-2 characters depending on platform

- **Special characters** (|, &, etc.) count as 1 character

- **URLs** in body text count against limits

- **Dynamic keyword insertion** (`{KeyWord:default}`) can exceed limits — set safe defaults

- Always verify in the platform's ad preview before launching

---

## Multi-Platform Creative Adaptation

When creating for multiple platforms simultaneously, start with the most restrictive format:

1. **Google Search headlines** (30 chars) — forces the tightest messaging

2. **Expand to Meta headlines** (40 chars) — add a word or two

3. **Expand to LinkedIn intro text** (150 chars) — add context and proof

4. **Expand to Meta primary text** (125+ chars) — full hook and value prop

This cascading approach ensures your core message works everywhere, then gets enriched for platforms that allow more space.

mdskills/ad-creative/SKILL.md

13 kB

---

description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' 'ad performance optimization,' 'write me some ads,' 'Facebook ad copy,' 'Google ad headlines,' 'LinkedIn ad text,' or 'I need more ad variations.' Use this whenever someone needs to produce ad copy at scale or iterate on existing ads. For campaign strategy and targeting, see ads. For landing page copy, see copywriting."

metadata:

version: 2.0.0

---

# Ad Creative

You are an expert performance creative strategist. Your goal is to generate high-performing ad creative at scale — headlines, descriptions, and primary text that drive clicks and conversions — and iterate based on real performance data.

## Before Starting

**Check for product marketing context first:**

Gather this context (ask if not provided):

### 1. Platform & Format

- What platform? (Google Ads, Meta, LinkedIn, TikTok, Twitter/X)

- What ad format? (Search RSAs, display, social feed, stories, video)

- Are there existing ads to iterate on, or starting from scratch?

### 2. Product & Offer

- What are you promoting? (Product, feature, free trial, demo, lead magnet)

- What's the core value proposition?

- What makes this different from competitors?

### 3. Audience & Intent

- Who is the target audience?

- What stage of awareness? (Problem-aware, solution-aware, product-aware)

- What pain points or desires drive them?

### 4. Performance Data (if iterating)

- What creative is currently running?

- Which headlines/descriptions are performing best? (CTR, conversion rate, ROAS)

- Which are underperforming?

- What angles or themes have been tested?

### 5. Constraints

- Brand voice guidelines or words to avoid?

- Compliance requirements? (Industry regulations, platform policies)

- Any mandatory elements? (Brand name, trademark symbols, disclaimers)

---

## How This Skill Works

This skill supports two modes:

### Mode 1: Generate from Scratch

When starting fresh, you generate a full set of ad creative based on product context, audience insights, and platform best practices.

### Mode 2: Iterate from Performance Data

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

```

---

## Platform Specs

Platforms reject or truncate creative that exceeds these limits, so verify every piece of copy fits before delivering.

### Google Ads (Responsive Search Ads)

| Element | Limit | Quantity |

|---------|-------|----------|

| Headline | 30 characters | Up to 15 |

| Description | 90 characters | Up to 4 |

| Display URL path | 15 characters each | 2 paths |

**RSA rules:**

- Headlines must make sense independently and in any combination

- Pin headlines to positions only when necessary (reduces optimization)

- Include at least one keyword-focused headline

- Include at least one benefit-focused headline

- Include at least one CTA headline

### Meta Ads (Facebook/Instagram)

| Element | Limit | Notes |

|---------|-------|-------|

| Primary text | 125 chars visible (up to 2,200) | Front-load the hook |

| Headline | 40 characters recommended | Below the image |

| Description | 30 characters recommended | Below headline |

| URL display link | 40 characters | Optional |

### LinkedIn Ads

| Element | Limit | Notes |

|---------|-------|-------|

| Intro text | 150 chars recommended (600 max) | Above the image |

| Headline | 70 chars recommended (200 max) | Below the image |

| Description | 100 chars recommended (300 max) | Appears in some placements |

### TikTok Ads

| Element | Limit | Notes |

|---------|-------|-------|

| Ad text | 80 chars recommended (100 max) | Above the video |

| Display name | 40 characters | Brand name |

### Twitter/X Ads

| Element | Limit | Notes |

|---------|-------|-------|

| Tweet text | 280 characters | The ad copy |

| Headline | 70 characters | Card headline |

| Description | 200 characters | Card description |

For detailed specs and format variations, see [references/platform-specs.md](references/platform-specs.md).

---

## Generating Ad Visuals

For image and video ad creative, use generative AI tools and code-based video rendering. See [references/generative-tools.md](references/generative-tools.md) for the complete guide covering:

- **Image generation** — Nano Banana Pro (Gemini), Flux, Ideogram for static ad images

- **Video generation** — Veo, Kling, Runway, Sora, Seedance, Higgsfield for video ads

- **Voice & audio** — ElevenLabs, OpenAI TTS, Cartesia for voiceovers, cloning, multilingual

- **Code-based video** — Remotion for templated, data-driven video at scale

- **Platform image specs** — Correct dimensions for every ad placement

- **Cost comparison** — Pricing for 100+ ad variations across tools

**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

---

## Generating Ad Copy

### Step 1: Define Your Angles

Before writing individual headlines, establish 3-5 distinct **angles** — different reasons someone would click. Each angle should tap into a different motivation.

**Common angle categories:**

| Category | Example Angle |

|----------|---------------|

| Pain point | "Stop wasting time on X" |

| Outcome | "Achieve Y in Z days" |

| Social proof | "Join 10,000+ teams who..." |

| Curiosity | "The X secret top companies use" |

| Comparison | "Unlike X, we do Y" |

| Urgency | "Limited time: get X free" |

| Identity | "Built for [specific role/type]" |

| Contrarian | "Why [common practice] doesn't work" |

### Step 2: Generate Variations per Angle

For each angle, generate multiple variations. Vary:

- **Word choice** — synonyms, active vs. passive

- **Specificity** — numbers vs. general claims

- **Tone** — direct vs. question vs. command

- **Structure** — short punch vs. full benefit statement

### Step 3: Validate Against Specs

Before delivering, check every piece of creative against the platform's character limits. Flag anything that's over and provide a trimmed alternative.

### Step 4: Organize for Upload

Present creative in a structured format that maps to the ad platform's upload requirements.

---

## Iterating from Performance Data

When the user provides performance data, follow this process:

### Step 1: Analyze Winners

Look at the top-performing creative (by CTR, conversion rate, or ROAS — ask which metric matters most) and identify:

- **Winning themes** — What topics or pain points appear in top performers?

- **Winning structures** — Questions? Statements? Commands? Numbers?

- **Winning word patterns** — Specific words or phrases that recur?

- **Character utilization** — Are top performers shorter or longer?

### Step 2: Analyze Losers

Look at the worst performers and identify:

- **Themes that fall flat** — What angles aren't resonating?

- **Common patterns in low performers** — Too generic? Too long? Wrong tone?

### Step 3: Generate New Variations

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

### Step 4: Document the Iteration

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]

```

---

## Writing Quality Standards

### Headlines That Click

**Strong headlines:**

- Specific ("Cut reporting time 75%") over vague ("Save time")

- Benefits ("Ship code faster") over features ("CI/CD pipeline")

- Active voice ("Automate your reports") over passive ("Reports are automated")

- Include numbers when possible ("3x faster," "in 5 minutes," "10,000+ teams")

**Avoid:**

- Jargon the audience won't recognize

- Claims without specificity ("Best," "Leading," "Top")

- All caps or excessive punctuation

- Clickbait that the landing page can't deliver on

### Descriptions That Convert

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")

---

## Output Formats

### Standard Output

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)

```

### Bulk CSV Output

When generating at scale (10+ variations), offer CSV format for direct upload:

```csv

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"

```

### Iteration Report

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]

```

---

## Batch Generation Workflow

For large-scale creative production (Anthropic's growth team generates 100+ variations per cycle):

### 1. Break into sub-tasks

- **Headline generation** — Focused on click-through

- **Description generation** — Focused on conversion

- **Primary text generation** — Focused on engagement (Meta/LinkedIn)

### 2. Generate in waves

- Wave 1: Core angles (3-5 angles, 5 variations each)

- Wave 2: Extended variations on top 2 angles

- Wave 3: Wild card angles (contrarian, emotional, specific)

### 3. Quality filter

- Remove anything over character limit

- Remove duplicates or near-duplicates

- Flag anything that might violate platform policies

- Ensure headline/description combinations make sense together

---

## Common Mistakes

- **Writing headlines that only work together** — RSA headlines get combined randomly

- **Ignoring character limits** — Platforms truncate without warning

- **All variations sound the same** — Vary angles, not just word choice

- **No CTA headlines** — RSAs need action-oriented headlines to drive clicks; include at least 2-3

- **Generic descriptions** — "Learn more about our solution" wastes the slot

- **Iterating without data** — Gut feelings are less reliable than metrics

- **Testing too many things at once** — Change one variable per test cycle

- **Retiring creative too early** — Allow 1,000+ impressions before judging

---

## Tool Integrations

For pulling performance data and managing campaigns, see the [tools registry](../../tools/REGISTRY.md).

|----------|:---------------------:|:----------------:|-------|

### Workflow: Pull Data, Analyze, Generate

```bash

# 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

```

---

## Related Skills

- **ads**: For campaign strategy, targeting, budgets, and optimization

- **copywriting**: For landing page copy (where ad traffic lands)

- **ab-testing**: For structuring creative tests with statistical rigor

- **marketing-psychology**: For psychological principles behind high-performing creative

- **copy-editing**: For polishing ad copy before launch

jsonskills/ads/evals/evals.json

6.3 kB

{

"skill_name": "ads",

"evals": [

{

"id": 1,

"prompt": "Help me plan a paid advertising strategy. We're a B2B SaaS tool for HR teams, selling at $99/month per seat. We have $15k/month to spend on ads and want to generate demo requests. Where should we advertise?",

"expected_output": "Should check for product-marketing.md first. Should apply the platform selection guide based on B2B, HR audience, $99/month price point. Should recommend LinkedIn (B2B targeting by job title/industry), Google Ads (search intent for HR software keywords), and potentially Meta (retargeting). Should recommend campaign structure with naming conventions. Should define audience targeting strategy for each platform. Should set budget allocation across platforms. Should define success metrics and attribution approach. Should recommend starting structure and scaling plan.",

"assertions": [

"Checks for product-marketing.md",

"Applies platform selection guide",

"Recommends platforms appropriate for B2B HR audience",

"Recommends campaign structure with naming conventions",

"Defines audience targeting per platform",

"Sets budget allocation across platforms",

"Defines success metrics",

"Recommends starting structure and scaling plan"

"files": []

{

"id": 2,

"prompt": "Our Google Ads CPC is $12 and our cost per lead is $180. Is that good? We're getting about 80 leads/month from a $15k budget.",

"expected_output": "Should evaluate the metrics in context. Should assess: $12 CPC for B2B (reasonable depending on industry), $180 CPL (depends on LTV — need to compare against customer lifetime value), 80 leads/month from $15k (math checks out). Should apply the campaign optimization framework: check quality score, search term relevance, landing page conversion rate, negative keywords. Should recommend specific optimization levers to reduce CPC and CPL. Should frame performance against industry benchmarks if applicable. Should ask about downstream conversion rates (lead → demo → customer).",

"assertions": [

"Evaluates metrics in context",

"Compares CPL against LTV considerations",

"Applies campaign optimization framework",

"Recommends specific optimization levers",

"Asks about downstream conversion rates",

"Provides industry context for benchmarking"

"files": []

{

"id": 3,

"prompt": "we want to run retargeting ads for people who visited our site but didn't convert. how should we set this up?",

"expected_output": "Should trigger on casual phrasing. Should apply the retargeting strategies section, specifically the funnel-based approach. Should recommend audience segments: all visitors (broad), pricing page visitors (high intent), blog readers (lower intent), and cart/signup abandoners (highest intent). Should recommend different messaging and offers for each segment. Should address frequency capping to avoid ad fatigue. Should recommend retargeting platforms (Meta, Google Display, LinkedIn). Should include duration windows for each audience.",

"assertions": [

"Triggers on casual phrasing",

"Applies funnel-based retargeting approach",

"Recommends audience segments by intent level",

"Recommends different messaging per segment",

"Addresses frequency capping",

"Recommends retargeting platforms",

"Includes audience duration windows"

"files": []

{

"id": 4,

"prompt": "Should we advertise on TikTok? We sell accounting software to small businesses. Our current ads are on Google and Meta.",

"expected_output": "Should apply the platform selection guide for TikTok specifically. Should evaluate TikTok fit for accounting software + small business audience: likely a weaker fit than Google/Meta for this category (lower purchase intent, younger skewing audience, less B2B targeting). Should discuss when TikTok CAN work for B2B (brand awareness, creative content, younger business owners). Should provide an honest recommendation with caveats. Should suggest a small test budget approach if they want to try.",

"assertions": [

"Applies platform selection guide for TikTok",

"Evaluates fit for accounting + small business audience",

"Provides honest assessment of likely weaker fit",

"Discusses when TikTok can work for B2B",

"Suggests small test budget if proceeding",

"Compares to their existing Google/Meta performance"

"files": []

{

"id": 5,

"prompt": "How do we structure our Google Ads campaigns? We have 50+ keywords we want to target for our CRM product.",

"expected_output": "Should apply the campaign structure and naming conventions framework. Should recommend organizing campaigns by theme/intent (brand, competitor, product features, pain points). Should recommend ad group structure (tightly themed, 5-15 keywords per group). Should define naming conventions for campaigns and ad groups. Should recommend match types strategy. Should include negative keyword lists. Should provide a sample campaign structure.",

"assertions": [

"Applies campaign structure framework",

"Organizes campaigns by theme/intent",

"Recommends tight ad group structure",

"Defines naming conventions",

"Recommends match types strategy",

"Includes negative keyword lists",

"Provides sample campaign structure"

"files": []

{

"id": 6,

"prompt": "Can you write some ad copy for our Facebook ads? We need headlines and descriptions for 5 different angles.",

"expected_output": "Should recognize this is an ad creative generation task, not campaign strategy. Should defer to or cross-reference the ad-creative skill, which handles platform-specific ad copy generation with character limits, angle-based variation, and batch generation. May provide brief ad copy framework guidance but should make clear that ad-creative is the right skill for generating ad copy at scale.",

"assertions": [

"Recognizes this as ad creative generation",

"References or defers to ad-creative skill",

"Does not attempt bulk ad copy generation using campaign strategy patterns"

"files": []

}

]

}

mdskills/ads/references/ad-copy-templates.md

4.7 kB

# Ad Copy Templates Reference

Detailed formulas and templates for writing high-converting ad copy.

## Contents

- Primary Text Formulas (Problem-Agitate-Solve, Before-After-Bridge, Social Proof Lead, Feature-Benefit Bridge, Direct Response)

- Headline Formulas (For Search Ads, For Social Ads)

- CTA Variations (Soft CTAs, Hard CTAs, Urgency CTAs, Action-Oriented CTAs)

- Platform-Specific Copy Guidelines (Google Search Ads, Meta Ads, LinkedIn Ads)

- Copy Testing Priority

## Primary Text Formulas

### Problem-Agitate-Solve (PAS)

```

[Problem statement]

[Agitate the pain]

[Introduce solution]

[CTA]

```

**Example:**

> Spending hours on manual reporting every week?

> While you're buried in spreadsheets, your competitors are making decisions.

> [Product] automates your reports in minutes.

> Start your free trial →

---

### Before-After-Bridge (BAB)

```

[Current painful state]

[Desired future state]

[Your product as the bridge]

```

**Example:**

> Before: Chasing down approvals across email, Slack, and spreadsheets.

> After: Every approval tracked, automated, and on time.

> [Product] connects your tools and keeps projects moving.

---

### Social Proof Lead

```

[Impressive stat or testimonial]

[What you do]

[CTA]

```

**Example:**

> "We cut our reporting time by 75%." — Sarah K., Marketing Director

> [Product] automates the reports you hate building.

> See how it works →

---

### Feature-Benefit Bridge

```

[Feature]

[So that...]

[Which means...]

```

**Example:**

> Real-time collaboration on documents

> So your team always works from the latest version

> Which means no more version confusion or lost work

---

### Direct Response

```

[Bold claim/outcome]

[Proof point]

[CTA with urgency if genuine]

```

**Example:**

> Cut your reporting time by 80%

> Join 5,000+ marketing teams already using [Product]

> Start free → First month 50% off

---

## Headline Formulas

### For Search Ads

| Formula | Example |

|---------|---------|

| [Keyword] + [Benefit] | "Project Management That Teams Actually Use" |

| [Action] + [Outcome] | "Automate Reports \| Save 10 Hours Weekly" |

| [Question] | "Tired of Manual Data Entry?" |

| [Number] + [Benefit] | "500+ Teams Trust [Product] for [Outcome]" |

| [Keyword] + [Differentiator] | "CRM Built for Small Teams" |

| [Price/Offer] + [Keyword] | "Free Project Management \| No Credit Card" |

### For Social Ads

| Type | Example |

|------|---------|

| Outcome hook | "How we 3x'd our conversion rate" |

| Curiosity hook | "The reporting hack no one talks about" |

| Contrarian hook | "Why we stopped using [common tool]" |

| Specificity hook | "The exact template we use for..." |

| Question hook | "What if you could cut your admin time in half?" |

| Number hook | "7 ways to improve your workflow today" |

| Story hook | "We almost gave up. Then we found..." |

---

## CTA Variations

### Soft CTAs (awareness/consideration)

Best for: Top of funnel, cold audiences, complex products

- Learn More

- See How It Works

- Watch Demo

- Get the Guide

- Explore Features

- See Examples

- Read the Case Study

### Hard CTAs (conversion)

Best for: Bottom of funnel, warm audiences, clear offers

- Start Free Trial

- Get Started Free

- Book a Demo

- Claim Your Discount

- Buy Now

- Sign Up Free

- Get Instant Access

### Urgency CTAs (use when genuine)

Best for: Limited-time offers, scarcity situations

- Limited Time: 30% Off

- Offer Ends [Date]

- Only X Spots Left

- Last Chance

- Early Bird Pricing Ends Soon

### Action-Oriented CTAs

Best for: Active voice, clear next step

- Start Saving Time Today

- Get Your Free Report

- See Your Score

- Calculate Your ROI

- Build Your First Project

---

## Platform-Specific Copy Guidelines

### Google Search Ads

- **Headline limits:** 30 characters each (up to 15 headlines)

- **Description limits:** 90 characters each (up to 4 descriptions)

- Include keywords naturally

- Use all available headline slots

- Include numbers and stats when possible

- Test dynamic keyword insertion

### Meta Ads (Facebook/Instagram)

- **Primary text:** 125 characters visible (can be longer, gets truncated)

- **Headline:** 40 characters recommended

- Front-load the hook (first line matters most)

- Emojis can work but test

- Questions perform well

- Keep image text under 20%

### LinkedIn Ads

- **Intro text:** 600 characters max (150 recommended)

- **Headline:** 200 characters max (70 recommended)

- Professional tone (but not boring)

- Specific job outcomes resonate

- Stats and social proof important

- Avoid consumer-style hype

---

## Copy Testing Priority

When testing ad copy, focus on these elements in order of impact:

1. **Hook/angle** (biggest impact on performance)

2. **Headline**

3. **Primary benefit**

4. **CTA**

5. **Supporting proof points**

Test one element at a time for clean data.

mdskills/ads/references/audience-targeting.md

5.9 kB

# Audience Targeting Reference

Detailed targeting strategies for each major ad platform.

## Contents

- Google Ads Audiences (Search Campaign Targeting, Display/YouTube Targeting)

- Meta Audiences (Core Audiences, Custom Audiences, Lookalike Audiences)

- LinkedIn Audiences (Job-Based Targeting, Company-Based Targeting, High-Performing Combinations)

- Twitter/X Audiences

- TikTok Audiences

- Audience Size Guidelines

- Exclusion Strategy

## Google Ads Audiences

### Search Campaign Targeting

**Keywords:**

- Exact match: [keyword] — most precise, lower volume

- Phrase match: "keyword" — moderate precision and volume

- Broad match: keyword — highest volume, use with smart bidding

**Audience layering:**

- Add audiences in "observation" mode first

- Analyze performance by audience

- Switch to "targeting" mode for high performers

**RLSA (Remarketing Lists for Search Ads):**

- Bid higher on past visitors searching your terms

- Show different ads to returning searchers

- Exclude converters from prospecting campaigns

### Display/YouTube Targeting

**Custom intent audiences:**

- Based on recent search behavior

- Create from your converting keywords

- High intent, good for prospecting

**In-market audiences:**

- People actively researching solutions

- Pre-built by Google

- Layer with demographics for precision

**Affinity audiences:**

- Based on interests and habits

- Better for awareness

- Broad but can exclude irrelevant

**Customer match:**

- Upload email lists

- Retarget existing customers

- Create lookalikes from best customers

**Similar/lookalike audiences:**

- Based on your customer match lists

- Expand reach while maintaining relevance

- Best when source list is high-quality customers

---

## Meta Audiences

### Core Audiences (Interest/Demographic)

**Interest targeting tips:**

- Layer interests with AND logic for precision

- Use Audience Insights to research interests

- Start broad, let algorithm optimize

- Exclude existing customers always

**Demographic targeting:**

- Age and gender (if product-specific)

- Location (down to zip/postal code)

- Language

- Education and work (limited data now)

**Behavior targeting:**

- Purchase behavior

- Device usage

- Travel patterns

- Life events

### Custom Audiences

**Website visitors:**

- All visitors (last 180 days max)

- Specific page visitors

- Time on site thresholds

- Frequency (visited X times)

**Customer list:**

- Upload emails/phone numbers

- Match rate typically 30-70%

- Refresh regularly for accuracy

**Engagement audiences:**

- Video viewers (25%, 50%, 75%, 95%)

- Page/profile engagers

- Form openers

- Instagram engagers

**App activity:**

- App installers

- In-app events

- Purchase events

### Lookalike Audiences

**Source audience quality matters:**

- Use high-LTV customers, not all customers

- Purchasers > leads > all visitors

- Minimum 100 source users, ideally 1,000+

**Size recommendations:**

- 1% — most similar, smallest reach

- 1-3% — good balance for most

- 3-5% — broader, good for scale

- 5-10% — very broad, awareness only

**Layering strategies:**

- Lookalike + interest = more precision early

- Test lookalike-only as you scale

- Exclude the source audience

---

## LinkedIn Audiences

### Job-Based Targeting

**Job titles:**

- Be specific (CMO vs. "Marketing")

- LinkedIn normalizes titles, but verify

- Stack related titles

- Exclude irrelevant titles

**Job functions:**

- Broader than titles

- Combine with seniority level

- Good for awareness campaigns

**Seniority levels:**

- Entry, Senior, Manager, Director, VP, CXO, Partner

- Layer with function for precision

**Skills:**

- Self-reported, less reliable

- Good for technical roles

- Use as expansion layer

### Company-Based Targeting

**Company size:**

- 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5000+

- Key filter for B2B

**Industry:**

- Based on company classification

- Can be broad, layer with other criteria

**Company names (ABM):**

- Upload target account list

- Minimum 300 companies recommended

- Match rate varies

**Company growth rate:**

- Hiring rapidly = budget available

- Good signal for timing

### High-Performing Combinations

| Use Case | Targeting Combination |

|----------|----------------------|

| Enterprise sales | Company size 1000+ + VP/CXO + Industry |

| SMB sales | Company size 11-200 + Manager/Director + Function |

| Developer tools | Skills + Job function + Company type |

| ABM campaigns | Company list + Decision-maker titles |

| Broad awareness | Industry + Seniority + Geography |

---

## Twitter/X Audiences

### Targeting options:

- Follower lookalikes (accounts similar to followers of X)

- Interest categories

- Keywords (in tweets)

- Conversation topics

- Events

- Tailored audiences (your lists)

### Best practices:

- Follower lookalikes of relevant accounts work well

- Keyword targeting catches active conversations

- Lower CPMs than LinkedIn/Meta

- Less precise, better for awareness

---

## TikTok Audiences

### Targeting options:

- Demographics (age, gender, location)

- Interests (TikTok's categories)

- Behaviors (video interactions)

- Device (iOS/Android, connection type)

- Custom audiences (pixel, customer file)

- Lookalike audiences

### Best practices:

- Younger skew (18-34 primarily)

- Interest targeting is broad

- Creative matters more than targeting

- Let algorithm optimize with broad targeting

---

## Audience Size Guidelines

| Platform | Minimum Recommended | Ideal Range |

|----------|-------------------|-------------|

| Google Search | 1,000+ searches/mo | 5,000-50,000 |

| Google Display | 100,000+ | 500K-5M |

| Meta | 100,000+ | 500K-10M |

| LinkedIn | 50,000+ | 100K-500K |

| Twitter/X | 50,000+ | 100K-1M |

| TikTok | 100,000+ | 1M+ |

Too narrow = expensive, slow learning

Too broad = wasted spend, poor relevance

---

## Exclusion Strategy

Always exclude:

- Existing customers (unless upsell)

- Recent converters (7-14 days)

- Bounced visitors (<10 sec)

- Employees (by company or email list)

- Irrelevant page visitors (careers, support)

- Competitors (if identifiable)

mdskills/ads/references/conversion-tracking.md

11 kB

# Conversion Tracking Setup

How to set up conversion tracking pixels across ad platforms. This guide covers installation, event configuration, and validation — everything a marketer needs to ensure ad spend is properly attributed.

---

## Why This Matters

Without conversion tracking:

- Ad platforms can't optimize for your actual goals

- You're flying blind on ROAS and CPA

- Retargeting audiences can't be built

- You'll waste budget on impressions that don't convert

Get tracking right before spending a dollar on ads.

---

## Platform Pixels Overview

|----------|---------------|:----------:|------------|

---

## Google Ads

### Install the Google tag

Add to every page, in `<head>`:

```html

window.dataLayer = window.dataLayer || [];

function gtag(){dataLayer.push(arguments);}

gtag('js', new Date());

gtag('config', 'AW-XXXXXXXXX');

</script>

```

Replace `AW-XXXXXXXXX` with your Conversion ID from Google Ads > Tools > Conversions.

### Set up conversion actions

In Google Ads > Goals > Conversions > New conversion action:

|-----------|----------|-------|-------|

### Fire conversion events

```javascript

// Purchase

gtag('event', 'conversion', {

'send_to': 'AW-XXXXXXXXX/CONVERSION_LABEL',

'value': 99.00,

'currency': 'USD',

'transaction_id': 'ORDER-123'

});

// Lead / Sign up

gtag('event', 'conversion', {

'send_to': 'AW-XXXXXXXXX/CONVERSION_LABEL',

'value': 50.00,

'currency': 'USD'

});

```

### Enhanced Conversions

Sends hashed first-party data (email, phone) to improve attribution after cookie restrictions. Enable in Google Ads > Goals > Settings > Enhanced conversions.

```javascript

gtag('set', 'user_data', {

'email': 'user@example.com', // auto-hashed by gtag

'phone_number': '+11234567890'

});

```

### Google Tag Manager alternative

If using GTM instead of inline gtag.js:

1. Install GTM container on all pages

2. Create Google Ads conversion tags in GTM

3. Set triggers for conversion events (form submissions, purchases)

4. Use the Data Layer to pass dynamic values (order amount, transaction ID)

5. Test with GTM Preview mode before publishing

---

## Meta (Facebook/Instagram)

### Install the Meta Pixel

Add to every page, in `<head>`:

```html

!function(f,b,e,v,n,t,s)

{if(f.fbq)return;n=f.fbq=function(){n.callMethod?

n.callMethod.apply(n,arguments):n.queue.push(arguments)};

if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';

n.queue=[];t=b.createElement(e);t.async=!0;

t.src=v;s=b.getElementsByTagName(e)[0];

s.parentNode.insertBefore(t,s)}(window, document,'script',

'https://connect.facebook.net/en_US/fbevents.js');

fbq('init', 'YOUR_PIXEL_ID');

fbq('track', 'PageView');

</script>

```

Replace `YOUR_PIXEL_ID` from Meta Events Manager.

### Standard events

```javascript

// View a product or key page

fbq('track', 'ViewContent', {

content_name: 'Pro Plan',

content_category: 'Pricing',

value: 29.00,

currency: 'USD'

});

// Lead capture (form submit, demo request)

fbq('track', 'Lead', {

content_name: 'Demo Request',

value: 50.00,

currency: 'USD'

});

// Purchase

fbq('track', 'Purchase', {

value: 99.00,

currency: 'USD',

content_type: 'product',

contents: [{ id: 'pro-plan', quantity: 1 }]

});

// Add to cart (e-commerce)

fbq('track', 'AddToCart', {

content_ids: ['SKU-123'],

content_type: 'product',

value: 49.00,

currency: 'USD'

});

```

### Conversions API (CAPI)

Server-side tracking that works alongside the pixel. Required for accurate tracking after iOS 14+ and cookie restrictions.

Set up via:

- **Direct integration** — send events from your server to Meta's API

- **Partner integrations** — Shopify, WooCommerce, Segment, etc. have built-in CAPI support

- **Conversions API Gateway** — Meta's managed solution via AWS

Key: send the same events from both pixel (browser) AND CAPI (server), with a shared `event_id` for deduplication.

### Aggregated Event Measurement

Required for iOS 14+ tracking. In Events Manager > Aggregated Event Measurement:

1. Verify your domain

2. Configure and prioritize your top 8 events in order of business importance

3. Purchase should typically be #1, Lead #2

---

## LinkedIn

### Install the Insight Tag

Add to every page, before `</body>`:

```html

_linkedin_partner_id = "YOUR_PARTNER_ID";

window._linkedin_data_partner_ids = window._linkedin_data_partner_ids || [];

window._linkedin_data_partner_ids.push(_linkedin_partner_id);

(function(l) {

if (!l){window.lintrk = function(a,b){window.lintrk.q.push([a,b])};

window.lintrk.q=[]}

var s = document.getElementsByTagName("script")[0];

var b = document.createElement("script");

b.type = "text/javascript";b.async = true;

b.src = "https://snap.licdn.com/li.lms-analytics/insight.min.js";

s.parentNode.insertBefore(b, s);})(window.lintrk);

</script>

```

### Conversion tracking

LinkedIn supports two methods:

**URL-based**: Fires when someone visits a specific URL (e.g., `/thank-you`).

Set up in Campaign Manager > Analyze > Conversion Tracking > Create Conversion.

**Event-based**: Fire manually on specific actions:

```javascript

window.lintrk('track', { conversion_id: YOUR_CONVERSION_ID });

```

### LinkedIn CAPI

For server-side tracking, LinkedIn offers a Conversions API. Set up via partner integrations (Segment, Tealium) or direct API calls. Deduplicates with the Insight Tag automatically when configured correctly.

---

## TikTok

### Install the TikTok Pixel

Add to every page, in `<head>`:

```html

!function (w, d, t) {

w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];

ttq.methods=["page","track","identify","instances","debug","on","off",

"once","ready","alias","group","enableCookie","disableCookie","holdConsent",

"revokeConsent","grantConsent"],ttq.setAndDefer=function(t,e)

{t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};

for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);

ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;

n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e};

ttq.load=function(e,n){var r="https://analytics.tiktok.com/i18n/pixel/events.js",

o=n&&n.partner;ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=r,

ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},

ttq._o[e]=n||{};var s=document.createElement("script");

s.type="text/javascript",s.async=!0,s.src=r+"?sdkid="+e+"&lib="+t;

var a=document.getElementsByTagName("script")[0];

a.parentNode.insertBefore(s,a)};

ttq.load('YOUR_PIXEL_ID');

ttq.page();

}(window, document, 'ttq');

</script>

```

### Standard events

```javascript

// View content

ttq.track('ViewContent', {

content_id: 'pro-plan',

content_type: 'product',

content_name: 'Pro Plan',

value: 29.00,

currency: 'USD'

});

// Complete registration / sign up

ttq.track('CompleteRegistration', {

content_name: 'Free Trial'

});

// Purchase

ttq.track('Purchase', {

content_id: 'pro-plan',

content_type: 'product',

value: 99.00,

currency: 'USD',

quantity: 1

});

// Add to cart

ttq.track('AddToCart', {

content_id: 'SKU-123',

content_type: 'product',

value: 49.00,

currency: 'USD'

});

```

### Events API (server-side)

TikTok's Events API works like Meta's CAPI — send the same events from your server for better attribution. Use `event_id` for deduplication with browser pixel events.

### Advanced Matching

Pass hashed user data for better attribution:

```javascript

ttq.identify({

email: 'user@example.com', // auto-hashed

phone_number: '+11234567890'

});

```

---

## Validation Checklist

After installing any pixel, verify before going live:

### Browser-side checks

- [ ] Pixel fires on every page (check via browser extension)

- [ ] Conversion events fire at the right moment (after confirmed action, not on button click)

- [ ] Event parameters contain correct values (currency, amount, content IDs)

- [ ] No duplicate events firing on the same action

- [ ] Events fire on both desktop and mobile

### Platform-side checks

- [ ] Events appear in the platform's event manager/diagnostics

- [ ] Test conversions show correct values

- [ ] Event match quality is acceptable (Meta: score > 6)

- [ ] Server-side events are deduplicating with browser events (not double-counting)

### Debugging tools

| Platform | Tool |

|----------|------|

| Google | Google Tag Assistant, Chrome DevTools Network tab |

| Meta | Meta Pixel Helper (Chrome extension), Events Manager Test Events |

| LinkedIn | Insight Tag Validator in Campaign Manager |

| TikTok | TikTok Pixel Helper (Chrome extension), Events Manager |

| All | GTM Preview Mode (if using Google Tag Manager) |

---

## Common Mistakes

- **Firing purchase events on button click instead of confirmed payment** — always fire on the success/thank-you page or after server confirmation

- **Missing deduplication between pixel and server events** — without a shared `event_id`, you'll double-count conversions

- **Not testing on mobile** — many pixels break on mobile browsers or in-app webviews

- **Hardcoded test values** — remove test transaction amounts before going live

- **Forgetting to exclude internal traffic** — your team's visits inflate conversion data

- **Installing pixels without consent management** — GDPR/CCPA require user consent before firing tracking pixels in applicable regions

- **Pixel installed but no conversion actions created** — the pixel collects data, but the ad platform won't optimize without defined conversion actions

---

## When to Use Server-Side Tracking

Browser-only tracking is increasingly unreliable due to:

- iOS 14+ App Tracking Transparency

- Third-party cookie deprecation

- Ad blockers (30%+ of tech audiences)

**Use server-side (CAPI/Events API) when:**

- Running Meta or TikTok ads (strongly recommended)

- Your audience is tech-savvy (higher ad blocker usage)

- You need accurate purchase/revenue attribution

- You're spending >$5K/month on any platform

**Server-side is optional when:**

- Running Google Ads only (Enhanced Conversions covers most gaps)

- Low ad spend / testing phase

- B2B with LinkedIn only (Insight Tag is still reliable)

mdskills/ads/references/platform-setup-checklists.md

7.4 kB

# Platform Setup Checklists

Complete setup checklists for major ad platforms.

## Contents

- Google Ads Setup (Account Foundation, Conversion Tracking, Analytics Integration, Audience Setup, Campaign Readiness, Ad Extensions, Brand Protection)

- Meta Ads Setup (Business Manager Foundation, Pixel & Tracking, Domain & Aggregated Events, Audience Setup, Catalog, Creative Assets, Compliance)

- LinkedIn Ads Setup (Campaign Manager Foundation, Insight Tag & Tracking, Audience Setup, Lead Gen Forms, Document Ads, Creative Assets, Budget Considerations)

- Twitter/X Ads Setup (Account Foundation, Tracking, Audience Setup, Creative)

- TikTok Ads Setup (Account Foundation, Pixel & Tracking, Audience Setup, Creative)

- Universal Pre-Launch Checklist

## Google Ads Setup

### Account Foundation

- [ ] Google Ads account created and verified

- [ ] Billing information added

- [ ] Time zone and currency set correctly

- [ ] Account access granted to team members

### Conversion Tracking

- [ ] Google tag installed on all pages

- [ ] Conversion actions created (purchase, lead, signup)

- [ ] Conversion values assigned (if applicable)

- [ ] Enhanced conversions enabled

- [ ] Test conversions firing correctly

- [ ] Import conversions from GA4 (optional)

### Analytics Integration

- [ ] Google Analytics 4 linked

- [ ] Auto-tagging enabled

- [ ] GA4 audiences available in Google Ads

- [ ] Cross-domain tracking set up (if multiple domains)

### Audience Setup

- [ ] Remarketing tag verified

- [ ] Website visitor audiences created:

- All visitors (180 days)

- Key page visitors (pricing, demo, features)

- Converters (for exclusion)

- [ ] Customer match lists uploaded

- [ ] Similar audiences enabled

### Campaign Readiness

- [ ] Negative keyword lists created:

- Universal negatives (free, jobs, careers, reviews, complaints)

- Competitor negatives (if needed)

- Irrelevant industry terms

- [ ] Location targeting set (include/exclude)

- [ ] Language targeting set

- [ ] Ad schedule configured (if B2B, business hours)

- [ ] Device bid adjustments considered

### Ad Extensions

- [ ] Sitelinks (4-6 relevant pages)

- [ ] Callouts (key benefits, offers)

- [ ] Structured snippets (features, types, services)

- [ ] Call extension (if phone leads valuable)

- [ ] Lead form extension (if using)

- [ ] Price extensions (if applicable)

- [ ] Image extensions (where available)

### Brand Protection

- [ ] Brand campaign running (protect branded terms)

- [ ] Competitor campaigns considered

- [ ] Brand terms in negative lists for non-brand campaigns

---

## Meta Ads Setup

### Business Manager Foundation

- [ ] Business Manager created

- [ ] Business verified (if running certain ad types)

- [ ] Ad account created within Business Manager

- [ ] Payment method added

- [ ] Team access configured with proper roles

### Pixel & Tracking

- [ ] Meta Pixel installed on all pages

- [ ] Standard events configured:

- PageView (automatic)

- ViewContent (product/feature pages)

- Lead (form submissions)

- Purchase (conversions)

- AddToCart (if e-commerce)

- InitiateCheckout (if e-commerce)

- [ ] Conversions API (CAPI) set up for server-side tracking

- [ ] Event Match Quality score > 6

- [ ] Test events in Events Manager

### Domain & Aggregated Events

- [ ] Domain verified in Business Manager

- [ ] Aggregated Event Measurement configured

- [ ] Top 8 events prioritized in order of importance

- [ ] Web events prioritized for iOS 14+ tracking

### Audience Setup

- [ ] Custom audiences created:

- Website visitors (all, 30/60/90/180 days)

- Key page visitors

- Video viewers (25%, 50%, 75%, 95%)

- Page/Instagram engagers

- Customer list uploaded

- [ ] Lookalike audiences created (1%, 1-3%)

- [ ] Saved audiences for common targeting

### Catalog (E-commerce)

- [ ] Product catalog connected

- [ ] Product feed updating correctly

- [ ] Catalog sales campaigns enabled

- [ ] Dynamic product ads configured

### Creative Assets

- [ ] Images in correct sizes:

- Feed: 1080x1080 (1:1)

- Stories/Reels: 1080x1920 (9:16)

- Landscape: 1200x628 (1.91:1)

- [ ] Videos in correct formats

- [ ] Ad copy variations ready

- [ ] UTM parameters in all destination URLs

### Compliance

- [ ] Special Ad Categories declared (if housing, credit, employment, politics)

- [ ] Landing page complies with Meta policies

- [ ] No prohibited content in ads

---

## LinkedIn Ads Setup

### Campaign Manager Foundation

- [ ] Campaign Manager account created

- [ ] Company Page connected

- [ ] Billing information added

- [ ] Team access configured

### Insight Tag & Tracking

- [ ] LinkedIn Insight Tag installed on all pages

- [ ] Tag verified and firing

- [ ] Conversion tracking configured:

- URL-based conversions

- Event-specific conversions

- [ ] Conversion values set (if applicable)

### Audience Setup

- [ ] Matched Audiences created:

- Website retargeting audiences

- Company list uploaded (for ABM)

- Contact list uploaded

- [ ] Lookalike audiences created

- [ ] Saved audiences for common targeting

### Lead Gen Forms (if using)

- [ ] Lead gen form templates created

- [ ] Form fields selected (minimize for conversion)

- [ ] Privacy policy URL added

- [ ] Thank you message configured

- [ ] CRM integration set up (or CSV export process)

### Document Ads (if using)

- [ ] Documents uploaded (PDF, PowerPoint)

- [ ] Gating configured (full gate or preview)

- [ ] Lead gen form connected

### Creative Assets

- [ ] Single image ads: 1200x627 (1.91:1) or 1080x1080 (1:1)

- [ ] Carousel images ready

- [ ] Video specs met (if using)

- [ ] Ad copy within character limits:

- Intro text: 600 max, 150 recommended

- Headline: 200 max, 70 recommended

### Budget Considerations

- [ ] Budget realistic for LinkedIn CPCs ($8-15+ typical)

- [ ] Audience size validated (50K+ recommended)

- [ ] Daily vs. lifetime budget decided

- [ ] Bid strategy selected

---

## Twitter/X Ads Setup

### Account Foundation

- [ ] Ads account created

- [ ] Payment method added

- [ ] Account verified (if required)

### Tracking

- [ ] Twitter Pixel installed

- [ ] Conversion events created

- [ ] Website tag verified

### Audience Setup

- [ ] Tailored audiences created:

- Website visitors

- Customer lists

- [ ] Follower lookalikes identified

- [ ] Interest and keyword targets researched

### Creative

- [ ] Tweet copy within 280 characters

- [ ] Images: 1200x675 (1.91:1) or 1200x1200 (1:1)

- [ ] Video specs met (if using)

- [ ] Cards configured (website, app, etc.)

---

## TikTok Ads Setup

### Account Foundation

- [ ] TikTok Ads Manager account created

- [ ] Business verification completed

- [ ] Payment method added

### Pixel & Tracking

- [ ] TikTok Pixel installed

- [ ] Events configured (ViewContent, Purchase, etc.)

- [ ] Events API set up (recommended)

### Audience Setup

- [ ] Custom audiences created

- [ ] Lookalike audiences created

- [ ] Interest categories identified

### Creative

- [ ] Vertical video (9:16) ready

- [ ] Native-feeling content (not too polished)

- [ ] First 3 seconds are compelling hooks

- [ ] Captions added (most watch without sound)

- [ ] Music/sounds selected (licensed if needed)

---

## Universal Pre-Launch Checklist

Before launching any campaign:

- [ ] Conversion tracking tested with real conversion

- [ ] Landing page loads fast (<3 sec)

- [ ] Landing page mobile-friendly

- [ ] UTM parameters working

- [ ] Budget set correctly (daily vs. lifetime)

- [ ] Start/end dates correct

- [ ] Targeting matches intended audience

- [ ] Ad creative approved

- [ ] Team notified of launch

- [ ] Reporting dashboard ready

mdskills/ads/SKILL.md

14 kB

---

description: "When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' 'audience targeting,' 'Google Ads,' 'Facebook ads,' 'LinkedIn ads,' 'ad budget,' 'cost per click,' 'ad spend,' or 'should I run ads.' Use this for campaign strategy, audience targeting, bidding, and optimization. For bulk ad creative generation and iteration, see ad-creative. For landing page optimization, see cro."

metadata:

version: 2.0.1

---

# Paid Ads

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.

## Before Starting

**Check for product marketing context first:**

Gather this context (ask if not provided):

### 1. Campaign Goals

- What's the primary objective? (Awareness, traffic, leads, sales, app installs)

- What's the target CPA or ROAS?

- What's the monthly/weekly budget?

- Any constraints? (Brand guidelines, compliance, geographic)

### 2. Product & Offer

- What are you promoting? (Product, free trial, lead magnet, demo)

- What's the landing page URL?

- What makes this offer compelling?

### 3. Audience

- Who is the ideal customer?

- What problem does your product solve for them?

- What are they searching for or interested in?

- Do you have existing customer data for lookalikes?

### 4. Current State

- Have you run ads before? What worked/didn't?

- Do you have existing pixel/conversion data?

- What's your current funnel conversion rate?

---

## Platform Selection Guide

| 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 |

| **LinkedIn** | 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 |

---

## Campaign Structure Best Practices

### Account Organization

```

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...

```

### Naming Conventions

```

[Platform]_[Objective]_[Audience]_[Offer]_[Date]

Examples:

META_Conv_Lookalike-Customers_FreeTrial_2024Q1

GOOG_Search_Brand_Demo_Ongoing

LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24

```

### Budget Allocation

**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-30% at a time

- Wait 3-5 days between increases for algorithm learning

---

## Ad Copy Frameworks

### Key Formulas

**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](references/ad-copy-templates.md)

---

## Audience Targeting Overview

### Platform Strengths

| Platform | Key Targeting | Best Signals |

|----------|---------------|--------------|

| Google | Keywords, search intent | What they're searching |

| Meta | Interests, behaviors, lookalikes | Engagement patterns |

| LinkedIn | Job titles, companies, industries | Professional identity |

### Key Concepts

- **Lookalikes**: Base on best customers (by LTV), not all customers

- **Retargeting**: Segment by funnel stage (visitors vs. cart abandoners)

- **Exclusions**: Exclude existing customers and recent converters — showing ads to people who already bought wastes spend

**For detailed targeting strategies by platform**: See [references/audience-targeting.md](references/audience-targeting.md)

---

## Creative Best Practices

### Image Ads

- Clear product screenshots showing UI

- Before/after comparisons

- Stats and numbers as focal point

- Human faces (real, not stock)

- Bold, readable text overlay (keep under 20%)

### Video Ads Structure (15-30 sec)

1. Hook (0-3 sec): Pattern interrupt, question, or bold statement

2. Problem (3-8 sec): Relatable pain point

3. Solution (8-20 sec): Show product/benefit

4. CTA (20-30 sec): Clear next step

**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

### Creative Testing Hierarchy

1. Concept/angle (biggest impact)

2. Hook/headline

3. Visual style

4. Body copy

5. CTA

---

## Campaign Optimization

### Key Metrics by Objective

| Objective | Primary Metrics |

|-----------|-----------------|

| Awareness | CPM, Reach, Video view rate |

| Consideration | CTR, CPC, Time on site |

| Conversion | CPA, ROAS, Conversion rate |

### Optimization Levers

**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

### Bid Strategy Progression

1. Start with manual or cost caps

2. Gather conversion data (50+ conversions)

3. Switch to automated with targets based on historical data

4. Monitor and adjust targets based on results

---

## Retargeting Strategies

### Funnel-Based Approach

|--------------|----------|---------|------|

### Retargeting Windows

| 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 |

### Exclusions to Set Up

- Existing customers (unless upsell)

- Recent converters (7-14 day window)

- Bounced visitors (<10 sec)

- Irrelevant pages (careers, support)

---

## Reporting & Analysis

### Weekly Review

- Spend vs. budget pacing

- CPA/ROAS vs. targets

- Top and bottom performing ads

- Audience performance breakdown

- Frequency check (fatigue risk)

- Landing page conversion rate

### Attribution Considerations

- Platform attribution is inflated

- Use UTM parameters consistently

- Compare platform data to GA4

- Look at blended CAC, not just platform CPA

---

## Platform Setup

Before launching campaigns, ensure proper tracking and account setup.

**For complete setup checklists by platform**: See [references/platform-setup-checklists.md](references/platform-setup-checklists.md)

**For conversion pixel installation and event setup**: See [references/conversion-tracking.md](references/conversion-tracking.md)

### Universal Pre-Launch Checklist

- [ ] Conversion tracking tested with real conversion

- [ ] Landing page loads fast (<3 sec)

- [ ] Landing page mobile-friendly

- [ ] UTM parameters working

- [ ] Budget set correctly

- [ ] Targeting matches intended audience

---

## Google RSA Output Spec (mandatory when generating RSAs)

When the user requests Google Ads RSAs (Responsive Search Ads), output MUST comply with these platform limits and structural requirements. Do not output any RSA that violates them.

### Hard limits per RSA (enforce before responding)

- **Headlines:** exactly **15** per RSA, each **≤ 30 characters** (count characters, including spaces). Render as `1. ... (NN chars)` so the reader can verify.

- **Descriptions:** exactly **4** per RSA, each **≤ 90 characters**.

- **Paths:** up to 2 path fields, each **≤ 15 characters**.

- **Final URL:** present, https.

- **Pinning:** state any pinned positions explicitly. Default = unpinned unless user asks.

- **Per-account guardrail:** Google enforces **3 RSAs max per ad group**. When the user asks for >3, group them by ad group.

### Required sidecar artifacts (always include with RSA request)

1. **Ad group structure**, labeled `Ad group structure:` — list each ad group with its theme, target keywords (match types), and which RSAs map to it.

2. **Negative keyword list**, labeled `Negative keywords:` — minimum **8** entries, group-level vs campaign-level called out.

3. **Sitelinks** (≥ 4), **Callouts** (≥ 4 ≤25 chars), **Structured snippets** if relevant.

### Medical / CFM compliance (when product context indicates pt-BR medical practice)

If `.agents/product-marketing.md` indicates a Brazilian medical practice (CFM-regulated), the following terms are **forbidden** in headlines, descriptions, sitelinks, and callouts:

- Superlatives: `#1`, `melhor`, `o melhor`, `melhor do brasil`, `top`, `referência`

- Outcome promises: `garantido`, `garantia`, `cura`, `cura definitiva`, `100%`, `resultado garantido`, `livre da dor`

- Comparative claims vs other doctors/clinics

Use neutral framing: `atendimento`, `consulta`, `avaliação`, `segunda opinião`, `agende sua consulta`, `tire suas dúvidas`. Geo modifier (`Porto Alegre`, `POA`, `Zona Sul POA`) required where the prompt specifies a region.

### Output ORDER (mandatory — emit in this order to avoid truncation)

1. **Ad group structure** (short)

2. **Negative keywords** (≥8, MANDATORY — emit BEFORE RSAs so it isn't dropped if output runs long)

3. **Sitelinks** (≥4)

4. **Callouts** (≥4)

5. **RSA1, RSA2, RSA3** (largest section, last — safe to truncate gracefully)

### Output template (mandatory shape)

```

Ad group structure:

- AG1 [theme]: keywords (match types) → RSA1, RSA2

- AG2 [theme]: ...

Negative keywords:

Campaign-level:

- <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 — ...

```

### Self-check before responding

Before sending the output, run this checklist mentally:

- [ ] Each RSA has exactly 15 headlines, exactly 4 descriptions.

- [ ] Every headline is ≤30 chars; every description is ≤90 chars. Character counts printed.

- [ ] Negative keyword list labeled and ≥8 entries.

- [ ] Ad group structure labeled.

- [ ] If medical (CFM): no forbidden superlative/outcome words; geo modifier present where required; language is pt-BR.

If any check fails, rewrite before responding. Do not ship partial RSAs.

---

## Common Mistakes to Avoid

### Strategy

- Launching without conversion tracking

- Too many campaigns (fragmenting budget)

- Not giving algorithms enough learning time

- Optimizing for wrong metric

### Targeting

- Audiences too narrow or too broad

- Not excluding existing customers

- Overlapping audiences competing

### Creative

- Only one ad per ad set

- Not refreshing creative (fatigue)

- Mismatch between ad and landing page

### Budget

- Spreading too thin across campaigns

- Making big budget changes (disrupts learning)

- Stopping campaigns during learning phase

---

## Task-Specific Questions

1. What platform(s) are you currently running or want to start with?

2. What's your monthly ad budget?

3. What does a successful conversion look like (and what's it worth)?

4. Do you have existing creative assets or need to create them?

5. What landing page will ads point to?

6. Do you have pixel/conversion tracking set up?

---

## Tool Integrations

For implementation, see the [tools registry](../../tools/REGISTRY.md). Key advertising platforms:

|----------|----------|:---:|-------|

For tracking setup, see [references/conversion-tracking.md](references/conversion-tracking.md), [ga4.md](../../tools/integrations/ga4.md), [segment.md](../../tools/integrations/segment.md)

---

## Related Skills

- **ad-creative**: For generating and iterating ad headlines, descriptions, and creative at scale

- **copywriting**: For landing page copy that converts ad traffic

- **analytics**: For proper conversion tracking setup

- **ab-testing**: For landing page testing to improve ROAS

- **cro**: For optimizing post-click conversion rates

jsonskills/ai-seo/evals/evals.json

6.4 kB

{

"skill_name": "ai-seo",

"evals": [

{

"id": 1,

"prompt": "How do I make sure our SaaS product shows up in AI search results? We're a project management tool and we keep getting left out of ChatGPT and Perplexity recommendations when people ask about project management software.",

"expected_output": "Should check for product-marketing.md first. Should apply the three pillars framework: Structure (make content extractable), Authority (make content citable), Presence (be where AI looks). Should run through the AI Visibility Audit checklist across platforms (Google AI Overviews, ChatGPT, Perplexity, etc.). Should check content extractability (clear definitions, structured comparisons, statistics). Should reference Princeton GEO research findings (citations improve visibility +40%, statistics +37%). Should check AI bot access in robots.txt. Should provide a prioritized action plan.",

"assertions": [

"Checks for product-marketing.md",

"Applies three pillars framework (Structure, Authority, Presence)",

"Runs AI Visibility Audit across platforms",

"Checks content extractability",

"References Princeton GEO research findings",

"Checks AI bot access in robots.txt",

"Provides prioritized action plan"

"files": []

{

"id": 2,

"prompt": "Should we block AI crawlers like GPTBot and PerplexityBot in our robots.txt? We're worried about content theft.",

"expected_output": "Should address the AI bot access question directly. Should explain the tradeoff: blocking AI bots prevents training on your content but also prevents AI platforms from citing and recommending you. Should reference the specific bots and their purposes (GPTBot, Google-Extended, PerplexityBot, ClaudeBot, etc.). Should provide the recommended robots.txt configuration. Should explain that blocking may hurt AI visibility more than it protects content. Should provide a nuanced recommendation based on business goals.",

"assertions": [

"Addresses the blocking tradeoff directly",

"Explains impact on AI visibility vs content protection",

"Lists specific AI bot user agents",

"Provides recommended robots.txt configuration",

"Gives nuanced recommendation based on business goals",

"Explains what each bot does"

"files": []

{

"id": 3,

"prompt": "What kind of content gets cited most by AI systems? We want to create content specifically optimized for AI search.",

"expected_output": "Should reference the content types that get cited most, including comparisons (~33% of AI citations), definitive guides (~15%), and other high-citation content types. Should explain why these formats work (they provide the structured, extractable, authoritative information AI systems need). Should provide specific recommendations for creating AI-optimized content: clear definitions, structured data, original statistics, comparison tables, expert quotes. Should reference the Princeton GEO research on what increases citation probability.",

"assertions": [

"References specific content types with citation rates",

"Mentions comparisons as highest-cited format",

"Explains why these formats work for AI",

"Provides specific content creation recommendations",

"References Princeton GEO research",

"Mentions structured data, statistics, and clear definitions"

"files": []

{

"id": 4,

"prompt": "we noticed our competitors are showing up in google AI overviews but we're not. what do we need to change?",

"expected_output": "Should trigger on casual phrasing. Should focus specifically on Google AI Overviews visibility. Should explain how AI Overviews selects sources (authoritative, well-structured, directly answers queries). Should run through the Structure pillar checklist: content extractability, heading hierarchy, answer-first format, structured data. Should check Authority signals: domain authority, citations, E-E-A-T. Should recommend specific content structure changes. Should suggest monitoring approach.",

"assertions": [

"Triggers on casual phrasing",

"Focuses on Google AI Overviews specifically",

"Explains how AI Overviews selects sources",

"Checks Structure pillar (extractability, headings, answer-first)",

"Checks Authority signals",

"Recommends specific content structure changes",

"Suggests monitoring approach"

"files": []

{

"id": 5,

"prompt": "Can you audit our website for AI search readiness? We want to know how visible we are across ChatGPT, Perplexity, Google AI Overviews, and other AI platforms.",

"expected_output": "Should run the full AI Visibility Audit. Should check each platform in the landscape (Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, Copilot). Should evaluate all three pillars: Structure (content extractability, JSON-LD, clear definitions), Authority (citations, backlinks, E-E-A-T signals), Presence (AI bot access, platform-specific factors). Should provide findings organized by pillar. Should provide a prioritized action plan with specific fixes.",

"assertions": [

"Runs full AI Visibility Audit",

"Checks multiple AI platforms",

"Evaluates all three pillars (Structure, Authority, Presence)",

"Checks content extractability",

"Checks AI bot access",

"Provides findings organized by pillar",

"Provides prioritized action plan"

"files": []

{

"id": 6,

"prompt": "Our organic search traffic has dropped 30% this quarter. Can you do a full SEO audit to figure out what's going on?",

"expected_output": "Should recognize this is a traditional SEO audit request, not specifically an AI SEO task. Should defer to or cross-reference the seo-audit skill, which handles comprehensive traditional SEO audits including crawlability, technical foundations, on-page optimization, and content quality. May mention AI search as one factor to investigate but should make clear that seo-audit is the primary skill for this task.",

"assertions": [

"Recognizes this as a traditional SEO audit request",

"References or defers to seo-audit skill",

"Does not attempt a full traditional SEO audit using AI SEO patterns",

"May mention AI search as one factor to consider"

"files": []

}

]

}

mdskills/ai-seo/references/content-patterns.md

9.8 kB

# AEO and GEO Content Patterns

Reusable content block patterns optimized for answer engines and AI citation.

---

## Contents

- Answer Engine Optimization (AEO) Patterns (Definition Block, Step-by-Step Block, Comparison Table Block, Pros and Cons Block, FAQ Block, Listicle Block)

- Generative Engine Optimization (GEO) Patterns (Statistic Citation Block, Expert Quote Block, Authoritative Claim Block, Self-Contained Answer Block, Evidence Sandwich Block)

- Domain-Specific GEO Tactics (Technology Content, Health/Medical Content, Financial Content, Legal Content, Business/Marketing Content)

- Voice Search Optimization (Question Formats for Voice, Voice-Optimized Answer Structure)

## Answer Engine Optimization (AEO) Patterns

These patterns help content appear in featured snippets, AI Overviews, voice search results, and answer boxes.

### Definition Block

Use for "What is [X]?" queries.

```markdown

## 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:**

```markdown

## 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.

```

### Step-by-Step Block

Use for "How to [X]" queries. Optimal for list snippets.

```markdown

## 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:**

```markdown

## 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.

```

### Comparison Table Block

Use for "[X] vs [Y]" queries. Optimal for table snippets.

```markdown

## [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]

```

### Pros and Cons Block

Use for evaluation queries: "Is [X] worth it?", "Should I [X]?"

```markdown

## Advantages and Disadvantages of [Topic]

[1-sentence overview of the evaluation context]

### Pros

- **[Benefit category]**: [Specific explanation]

### Cons

- **[Drawback category]**: [Specific explanation]

**Verdict**: [1-2 sentence balanced conclusion with recommendation]

```

### FAQ Block

Use for topic pages with multiple common questions. Essential for FAQ schema.

```markdown

## 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

### Listicle Block

Use for "Best [X]", "Top [X]", "[Number] ways to [X]" queries.

```markdown

## [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]

```

---

## Generative Engine Optimization (GEO) Patterns

These patterns optimize content for citation by AI assistants like ChatGPT, Claude, Perplexity, and Gemini.

### Statistic Citation Block

Statistics increase AI citation rates by 15-30%. Always include sources.

```markdown

[Claim statement]. According to [Source/Organization], [specific statistic with number and timeframe]. [Context for why this matters].

```

**Example:**

```markdown

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.

```

### Expert Quote Block

Named expert attribution adds credibility and increases citation likelihood.

```markdown

"[Direct quote from expert]," says [Expert Name], [Title/Role] at [Organization]. [1 sentence of context or interpretation].

```

**Example:**

```markdown

"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.

```

### Authoritative Claim Block

Structure claims for easy AI extraction with clear attribution.

```markdown

[Topic] [verb: is/has/requires/involves] [clear, specific claim]. [Source] [confirms/reports/found] that [supporting evidence]. This [explains/means/suggests] [implication or action].

```

**Example:**

```markdown

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.

```

### Self-Contained Answer Block

Create quotable, standalone statements that AI can extract directly.

```markdown

**[Topic/Question]**: [Complete, self-contained answer that makes sense without additional context. Include specific details, numbers, or examples in 2-3 sentences.]

```

**Example:**

```markdown

**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.

```

### Evidence Sandwich Block

Structure claims with evidence for maximum credibility.

```markdown

[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].

```

---

## Domain-Specific GEO Tactics

Different content domains benefit from different authority signals.

### Technology Content

- Emphasize technical precision and correct terminology

- Include version numbers and dates for software/tools

- Reference official documentation

- Add code examples where relevant

### Health/Medical Content

- Cite peer-reviewed studies with publication details

- Include expert credentials (MD, RN, etc.)

- Note study limitations and context

- Add "last reviewed" dates

### Financial Content

- Reference regulatory bodies (SEC, FTC, etc.)

- Include specific numbers with timeframes

- Note that information is educational, not advice

- Cite recognized financial institutions

### Legal Content

- Cite specific laws, statutes, and regulations

- Reference jurisdiction clearly

- Include professional disclaimers

- Note when professional consultation is advised

### Business/Marketing Content

- Include case studies with measurable results

- Reference industry research and reports

- Add percentage changes and timeframes

- Quote recognized thought leaders

---

## Voice Search Optimization

Voice queries are conversational and question-based. Optimize for these patterns:

### Question Formats for Voice

- "What is..."

- "How do I..."

- "Where can I find..."

- "Why does..."

- "When should I..."

- "Who is..."

### Voice-Optimized Answer Structure

- Lead with direct answer (under 30 words ideal)

- Use natural, conversational language

- Avoid jargon unless targeting expert audience

- Include local context where relevant

- Structure for single spoken response

mdskills/ai-seo/references/content-types.md

2.5 kB

# AI SEO by Content Type

Tactical guidance for optimizing specific content types for AI search citation. These tactics work for non-Google AI engines (ChatGPT, Claude, Perplexity, Copilot) and don't hurt Google AI Overviews / AI Mode.

For the cross-cutting strategy, see [SKILL.md](../SKILL.md).

---

## SaaS Product Pages

**Goal:** Get cited in "What is [category]?" and "Best [category]" queries.

**Optimize:**

- Clear product description in first paragraph (what it does, who it's for)

- Feature comparison tables (you vs. category, not just competitors)

- Specific metrics ("processes 10,000 transactions/sec" not "blazing fast")

- Customer count or social proof with numbers

- Pricing transparency (AI cites pages with visible pricing) — add a `/pricing.md` file so AI agents can parse your plans without rendering your page (see "Machine-Readable Files" in the main skill)

- FAQ section addressing common buyer questions

---

## Blog Content

**Goal:** Get cited as an authoritative source on topics in your space.

**Optimize:**

- One clear target query per post (match heading to query)

- Definition in first paragraph for "What is" queries

- Original data, research, or expert quotes

- "Last updated" date visible

- Author bio with relevant credentials

- Internal links to related product/feature pages

---

## Comparison / Alternative Pages

**Goal:** Get cited in "[X] vs [Y]" and "Best [X] alternatives" queries.

**Optimize:**

- Structured comparison tables (not just prose)

- Fair and balanced (AI penalizes obviously biased comparisons)

- Specific criteria with ratings or scores

- Updated pricing and feature data

- Cite the `competitors` skill for building these pages

---

## Documentation / Help Content

**Goal:** Get cited in "How to [X] with [your product]" queries.

**Optimize:**

- Step-by-step format with numbered lists

- Code examples where relevant

- HowTo schema markup

- Screenshots with descriptive alt text

- Clear prerequisites and expected outcomes

---

## Local Business / Ecom (Google emphasis)

Google's AI features pull from product feeds and business profiles for local + ecom queries. Optimize:

- **Merchant Center feeds** kept current with accurate inventory, pricing, attributes

- **Google Business Profile** complete with hours, services, photos, posts, Q&A answered

- **Reviews** — recent + sufficient volume; respond to reviews to signal active management

- **Service area schema** for local services

- **Business Agent** (where available) for conversational customer engagement

mdskills/ai-seo/references/platform-ranking-factors.md

10 kB

# How Each AI Platform Picks Sources

Each 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.

---

## The Fundamentals

Every AI platform shares three baseline requirements:

1. **Your content must be in their index** — Each platform uses a different search backend (Google, Bing, Brave, or their own). If you're not indexed, you can't be cited.

2. **Your content must be crawlable** — AI bots need access via robots.txt. Block the bot, lose the citation.

3. **Your content must be extractable** — AI systems pull passages, not pages. Clear structure and self-contained paragraphs win.

Beyond these basics, each platform weights different signals. Here's what matters and where.

---

## Google AI Overviews

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

---

## ChatGPT

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

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

---

## Microsoft Copilot

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

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

---

## Allowing AI Bots in robots.txt

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.

---

## Where to Start

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

mdskills/ai-seo/SKILL.md

25 kB

---

description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' or 'optimize for Claude/Gemini.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema."

metadata:

version: 2.0.1

---

# AI SEO

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.

## Before Starting

**Check for product marketing context first:**

Gather this context (ask if not provided):

### 1. Current AI Visibility

- Do you know if your brand appears in AI-generated answers today?

- Have you checked ChatGPT, Perplexity, or Google AI Overviews for your key queries?

- What queries matter most to your business?

### 2. Content & Domain

- What type of content do you produce? (Blog, docs, comparisons, product pages)

- What's your domain authority / traditional SEO strength?

- Do you have existing structured data (schema markup)?

### 3. Goals

- Get cited as a source in AI answers?

- Appear in Google AI Overviews for specific queries?

- Compete with specific brands already getting cited?

- Optimize existing content or create new AI-optimized content?

### 4. Competitive Landscape

- Who are your top competitors in AI search results?

- Are they being cited where you're not?

---

## How AI Search Works

### The AI Search Landscape

| 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](references/platform-ranking-factors.md).

### Key Difference from Traditional SEO

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

### Google's Official Stance vs. Multi-Platform Reality

This is important to read once before doing anything else.

**Google's position** ([AI features optimization guide](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)):

> "The best practices for SEO continue to be relevant because our generative AI features on Google Search are rooted in our core Search ranking and quality systems."

Google explicitly says:

- **No special markup or files are required** for AI Overviews or AI Mode

- **Don't chunk content for AI** — write for people, organize with normal headings and paragraphs

- **Don't write separate content for AI** — that risks "scaled content abuse" spam policy

- **Helpful, reliable, people-first content** wins — same E-E-A-T standards as regular Search

- **No AI-specific Search Console reporting** — use standard SEO metrics

**Other AI engines (ChatGPT, Claude, Perplexity, Copilot) behave differently:**

- They actively reward extractable structure — passages, FAQs, comparison tables, definition blocks

- They parse `llms.txt`, structured pricing pages, and machine-readable files when present

- They cite third-party sources (Reddit, Wikipedia, review sites) more heavily than top-ranked pages

**What this means for the work:**

- The structural patterns in this skill (40–60 word answer blocks, FAQ schema, comparison tables) help **non-Google AI engines** materially. They also don't hurt Google — they're just normal good content organization.

- For Google AI Overviews / AI Mode specifically: optimize for people and core Search, full stop. Strong E-E-A-T, original information, semantic HTML, clean indexability.

- For ChatGPT/Claude/Perplexity: layer on the extractable structure + llms.txt + machine-readable files.

When in doubt, default to "write for people, organize for clarity" — that satisfies both camps.

### Query Fan-Out (Google AI Search)

Google's AI features don't just answer the one query a user typed — they generate **concurrent, related queries** under the hood and retrieve results for each.

Google's own example: a user asking "how to fix lawns" triggers fan-out queries about herbicides, chemical-free removal, weed prevention, etc. The AI synthesizes across all of them.

**Implications:**

- Single-page-per-keyword targeting is less effective. Cover the **full topical cluster** so you're retrievable for the fan-out variants too.

- Long-tail intent matters less than topical authority — Google's AI systems understand synonyms and semantic equivalence.

- A page that comprehensively answers a parent topic (with sub-questions covered) will be retrieved more often than narrow per-query pages.

**Action**: when planning content, brainstorm the 5–10 related queries the AI is likely to fan out to and make sure your content (or your site as a whole) covers them.

---

## AI Visibility Audit

Before optimizing, assess your current AI search presence.

### Step 1: Check AI Answers for Your Key Queries

Test 10-20 of your most important queries across platforms:

|-------|:-----------------:|:-------:|:----------:|:----------:|:-----------------:|

**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"

### Step 2: Analyze Citation Patterns

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?

### Step 3: Content Extractability Check

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? | |

### Step 4: AI Bot Access Check

Verify your robots.txt allows AI crawlers. Each AI platform has its own bot, and blocking it means that platform can't cite you:

- **GPTBot** and **ChatGPT-User** — OpenAI (ChatGPT)

- **PerplexityBot** — Perplexity

- **ClaudeBot** and **anthropic-ai** — Anthropic (Claude)

- **Google-Extended** — Google Gemini and AI Overviews

- **Bingbot** — Microsoft Copilot (via Bing)

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](references/platform-ranking-factors.md) for the full robots.txt configuration.

---

## Optimization Strategy

### The Three Pillars

```

1. Structure (make it extractable)

2. Authority (make it citable)

3. Presence (be where AI looks)

```

### Pillar 1: Structure — Make Content Extractable

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](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

### Pillar 2: Authority — Make Content Citable

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

### Pillar 3: Presence — Be Where AI Looks

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

### Machine-Readable Files for AI Agents

> **Google's stance**: not required for AI Overviews or AI Mode. Their guide explicitly says you don't need new markup, AI files, or markdown to appear in generative AI search.

> **Why include them anyway**: non-Google AI engines (ChatGPT, Claude, Perplexity) and autonomous buying agents do reward extractable structure. The files below help with those engines without harming Google.

AI agents aren't just answering questions — they're becoming buyers. When an AI agent evaluates tools on behalf of a user, it needs structured, parseable information. If your pricing is locked in a JavaScript-rendered page or a "contact sales" wall, agents will skip you and recommend competitors whose information they can actually read.

Add these machine-readable files to your site root:

**`/pricing.md` or `/pricing.txt`** — Structured pricing data for AI agents

```markdown

# 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](https://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).

### Schema Markup for AI

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.

---

## Agentic Experiences

Beyond AI search engines summarizing content, autonomous agents are starting to access sites directly — clicking, reading, comparing, even buying on behalf of users. Google's guide flags this as an emerging category to plan for.

**How agents access your site:**

- **Visual rendering** — they screenshot/read the page like a user would

- **DOM inspection** — they parse the page's HTML structure

- **Accessibility tree** — they rely on the same semantic information assistive tech uses (labels, roles, landmarks, headings)

**What to do:**

- **Render meaningful content without heavy JS gymnastics** — if the page is blank until 4 frameworks finish loading, agents see blank

- **Semantic HTML** — use `<main>`, `<nav>`, `<article>`, `<button>`, proper heading hierarchy, `alt` text on images

- **Clean accessibility tree** — every interactive element labelled; ARIA used correctly (or not at all when native HTML suffices)

- **Stable selectors / predictable layouts** — agents struggle with sites that re-render every interaction

- **Visible pricing, specs, contact info** — anything an agent would need to make a buying recommendation should be on a public, indexable page (this is where `/pricing.md` and similar files help)

**Emerging — Universal Commerce Protocol (UCP):**

Google references UCP as a forthcoming protocol that will give agents standardized hooks for commerce interactions (catalog discovery, pricing, checkout). Watch for adoption; for now, the structural recommendations above are the precursor.

For ecom and local business specifically, Google highlights:

- **Merchant Center feeds** + **Google Business Profile** for product/service visibility in AI Search

- **Business Agent** for conversational customer engagement (where applicable)

---

## Content Types That Get Cited Most

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)

---

## Monitoring AI Visibility

### What to Track

| 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 |

| Source attribution | Which of your pages get cited | Track referral traffic from AI sources |

### AI Visibility Monitoring Tools

| 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 |

### DIY Monitoring (No Tools)

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

### Search Console expectations

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.

---

## What NOT to Do

Google's guide calls these out explicitly — they hurt across both traditional Search and AI features.

1. **Write separate content "for AI"**. Same content should serve people and AI. Writing variants targeted at AI systems risks the **scaled content abuse spam policy** — Google's words.

2. **Chunk pages into AI-bait fragments**. Google's guide is direct: *"Don't break your content into tiny pieces for AI to better understand it."* Use normal paragraph + heading structure.

3. **Generate at scale for ranking manipulation**. AI-generated content is fine *if* it meets Search Essentials and spam policies. Mass-producing thin variations does not.

4. **Pursue inauthentic mentions**. Don't fabricate citations or bulk-spam Reddit/Wikipedia for AI visibility. Real participation only.

5. **Block AI crawlers if you want citation**. Blocking GPTBot, PerplexityBot, ClaudeBot, Google-Extended means those engines literally cannot cite you. Block training-only crawlers (CCBot) if you must, not the search-and-cite ones.

6. **Hide your main content behind JS that doesn't render**. Both core Search and AI agents need to see your content; JS-only rendering loses both audiences.

7. **Skip E-E-A-T fundamentals**. Author identity, first-hand experience, expertise signals, transparent sourcing — Google's guide leans heavily on these for AI features.

---

## AI SEO by Content Type

For tactical guidance on SaaS product pages, blog content, comparison/alternative pages, documentation, and local/ecom (Google's emphasis on Merchant Center + Business Profile), see [references/content-types.md](references/content-types.md).

---

## Common Mistakes

- **Ignoring AI search entirely** — ~45% of Google searches now show AI Overviews, and ChatGPT/Perplexity are growing fast

- **Treating AI SEO as separate from SEO** — Good traditional SEO is the foundation; AI SEO adds structure and authority on top

- **Writing for AI, not humans** — If content reads like it was written to game an algorithm, it won't get cited or convert

- **No freshness signals** — Undated content loses to dated content because AI systems weight recency heavily. Show when content was last updated

- **Gating all content** — AI can't access gated content. Keep your most authoritative content open

- **Ignoring third-party presence** — You may get more AI citations from a Wikipedia mention than from your own blog

- **No structured data** — Schema markup gives AI systems structured context about your content

- **Keyword stuffing** — Unlike traditional SEO where it's just ineffective, keyword stuffing actively reduces AI visibility by 10% (Princeton GEO study)

- **Hiding pricing behind "contact sales" or JS-rendered pages** — AI agents evaluating your product on behalf of buyers can't parse what they can't read. Add a `/pricing.md` file

- **Blocking AI bots** — If GPTBot, PerplexityBot, or ClaudeBot are blocked in robots.txt, those platforms can't cite you

- **Generic content without data** — "We're the best" won't get cited. "Our customers see 3x improvement in [metric]" will

- **Forgetting to monitor** — You can't improve what you don't measure. Check AI visibility monthly at minimum

---

## Tool Integrations

For implementation, see the [tools registry](../../tools/REGISTRY.md).

| 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 |

---

## Task-Specific Questions

1. What are your top 10-20 most important queries?

2. Have you checked if AI answers exist for those queries today?

3. Do you have structured data (schema markup) on your site?

4. What content types do you publish? (Blog, docs, comparisons, etc.)

5. Are competitors being cited by AI where you're not?

6. Do you have a Wikipedia page or presence on review sites?

---

## Related Skills

- **seo-audit**: For traditional technical and on-page SEO audits

- **schema**: For implementing structured data that helps AI understand your content

- **content-strategy**: For planning what content to create

- **competitors**: For building comparison pages that get cited

- **programmatic-seo**: For building SEO pages at scale

- **copywriting**: For writing content that's both human-readable and AI-extractable

jsonskills/analytics/evals/evals.json

6.2 kB

{

"skill_name": "analytics",

"evals": [

{

"id": 1,

"prompt": "Help me set up analytics tracking for our B2B SaaS product. We use GA4 and GTM. We need to track signups, feature usage, and upgrade events.",

"expected_output": "Should check for product-marketing.md first. Should apply the 'track for decisions' principle — ask what decisions the tracking will inform. Should use the event naming convention (object_action, lowercase with underscores). Should define essential events for SaaS: signup_completed, trial_started, feature_used, plan_upgraded, etc. Should provide GA4 implementation details with proper event parameters. Should include GTM data layer push examples. Should organize output as a tracking plan with event name, trigger, parameters, and purpose for each event.",

"assertions": [

"Checks for product-marketing.md",

"Applies 'track for decisions' principle",

"Uses object_action naming convention",

"Defines essential SaaS events (signup, feature usage, upgrade)",

"Provides GA4 implementation details",

"Includes GTM data layer examples",

"Output follows tracking plan format"

"files": []

{

"id": 2,

"prompt": "What UTM parameters should we use? We run ads on Google, Meta, and LinkedIn, plus send a weekly newsletter and post on LinkedIn organically.",

"expected_output": "Should apply the UTM parameter strategy framework. Should define consistent UTM conventions: source (google, meta, linkedin, newsletter), medium (cpc, paid-social, email, organic-social), campaign (naming convention with date or identifier). Should provide specific UTM examples for each channel mentioned. Should warn about common UTM mistakes (inconsistent casing, redundant parameters, missing medium). Should recommend a UTM tracking spreadsheet or naming convention document.",

"assertions": [

"Applies UTM parameter strategy",

"Defines source, medium, and campaign conventions",

"Provides specific UTM examples for each channel",

"Uses consistent naming conventions (lowercase)",

"Warns about common UTM mistakes",

"Recommends tracking documentation"

"files": []

{

"id": 3,

"prompt": "our tracking seems broken — we're seeing duplicate events and our conversion numbers in GA4 don't match what our database shows. help?",

"expected_output": "Should trigger on casual phrasing. Should apply the debugging and validation framework. Should systematically check for common issues: duplicate GTM tags firing, missing event deduplication, incorrect trigger conditions, cross-domain tracking issues, consent mode filtering. Should provide specific debugging steps: use GA4 DebugView, GTM Preview mode, browser developer tools. Should address the GA4 vs database discrepancy (common causes: consent mode, ad blockers, client-side vs server-side tracking, session timeout differences).",

"assertions": [

"Triggers on casual phrasing",

"Applies debugging and validation framework",

"Checks for duplicate tag firing",

"Provides specific debugging tools (GA4 DebugView, GTM Preview)",

"Addresses GA4 vs database discrepancy",

"Lists common causes of data mismatches",

"Provides systematic troubleshooting steps"

"files": []

{

"id": 4,

"prompt": "We're launching an e-commerce store and need to set up tracking from scratch. What events do we absolutely need?",

"expected_output": "Should reference the essential events by site type, specifically e-commerce. Should define the e-commerce event taxonomy: product_viewed, product_added_to_cart, cart_viewed, checkout_started, checkout_step_completed, purchase_completed, product_removed_from_cart. Should include enhanced e-commerce parameters (item_id, item_name, price, quantity, etc.). Should follow object_action naming convention. Should organize as a tracking plan with priorities (must-have vs nice-to-have).",

"assertions": [

"References essential events for e-commerce site type",

"Defines full e-commerce event taxonomy",

"Includes enhanced e-commerce parameters",

"Follows object_action naming convention",

"Organizes by priority (must-have vs nice-to-have)",

"Provides tracking plan format output"

"files": []

{

"id": 5,

"prompt": "We need to make sure our tracking is GDPR compliant. We have European users and we're using GA4, Hotjar, and Facebook Pixel.",

"expected_output": "Should apply the privacy and compliance framework. Should address GDPR requirements for each tool: consent before tracking, consent management platform (CMP) setup, GA4 consent mode configuration, conditional loading of Hotjar and Facebook Pixel. Should recommend a consent hierarchy (necessary, analytics, marketing). Should provide GTM implementation for consent-based tag firing. Should mention data retention settings in GA4. Should address cookie banner requirements.",

"assertions": [

"Applies privacy and compliance framework",

"Addresses GDPR requirements specifically",

"Recommends consent management platform",

"Covers GA4 consent mode configuration",

"Addresses conditional loading for each tool",

"Provides consent hierarchy",

"Mentions data retention settings"

"files": []

{

"id": 6,

"prompt": "Help me set up tracking for our A/B test. We want to measure which version of our pricing page converts better.",

"expected_output": "Should recognize this overlaps with A/B test setup, not just analytics tracking. Should defer to or cross-reference the ab-testing skill for the experiment design, hypothesis, and statistical analysis. May help with the tracking implementation (events to fire, parameters to include) but should make clear that ab-testing is the right skill for the experiment framework.",

"assertions": [

"Recognizes overlap with A/B test setup",

"References or defers to ab-testing skill",

"May help with tracking implementation specifics",

"Does not attempt to design the full experiment"

"files": []

}

]

}

mdskills/analytics/references/event-library.md

8.5 kB

# Event Library Reference

Comprehensive list of events to track by business type and context.

## Contents

- Marketing Site Events (navigation & engagement, CTA & form interactions, conversion events)

- Product/App Events (onboarding, core usage, errors & support)

- Monetization Events (pricing & checkout, subscription management)

- E-commerce Events (browsing, cart, checkout, post-purchase)

- B2B / SaaS Specific Events (team & collaboration, integration events, account events)

- Event Properties (Parameters)

- Funnel Event Sequences

## Marketing Site Events

### Navigation & Engagement

| 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 |

### CTA & Form Interactions

| 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 |

### Conversion Events

| 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 |

---

## Product/App Events

### Onboarding

| 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 |

### Core Usage

| 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 |

### Errors & Support

| 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 |

---

## Monetization Events

### Pricing & Checkout

| 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 |

### Subscription Management

| 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 | - |

---

## E-commerce Events

### Browsing

| 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 |

### Cart

| 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 |

### Checkout

| 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[] |

### Post-Purchase

| 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 |

---

## B2B / SaaS Specific Events

### Team & Collaboration

| 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 |

### Integration Events

| 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 |

### Account Events

| 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 |

---

## Event Properties (Parameters)

### Standard Properties to Include

**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

```

---

## Funnel Event Sequences

### Signup Funnel

1. signup_started

2. signup_step_completed (email)

3. signup_step_completed (password)

4. signup_completed

5. onboarding_started

### Purchase Funnel

1. pricing_viewed

2. plan_selected

3. checkout_started

4. payment_info_entered

5. purchase_completed

### E-commerce Funnel

1. product_viewed

2. product_added_to_cart

3. cart_viewed

4. checkout_started

5. shipping_info_entered

6. payment_info_entered

7. purchase_completed

mdskills/analytics/references/ga4-implementation.md

6.2 kB

# GA4 Implementation Reference

Detailed implementation guide for Google Analytics 4.

## Contents

- Configuration (data streams, enhanced measurement events, recommended events)

- Custom Events (gtag.js implementation, Google Tag Manager)

- Conversions Setup (creating conversions, conversion values)

- Custom Dimensions and Metrics (when to use, setup steps, examples)

- Audiences (creating audiences, audience examples)

- Debugging (DebugView, real-time reports, common issues)

- Data Quality (filters, cross-domain tracking, session settings)

- Integration with Google Ads (linking, audience export)

## Configuration

### Data Streams

- One stream per platform (web, iOS, Android)

- Enable enhanced measurement for automatic tracking

- Configure data retention (2 months default, 14 months max)

- Enable Google Signals (for cross-device, if consented)

### Enhanced Measurement Events (Automatic)

| 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 |

### Recommended Events

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

---

## Custom Events

### gtag.js Implementation

```javascript

// 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'

});

```

### Google Tag Manager (dataLayer)

```javascript

// 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': {

// ...

}

});

```

---

## Conversions Setup

### Creating Conversions

1. **Collect the event** - Ensure event is firing in GA4

2. **Mark as conversion** - Admin > Events > Mark as conversion

3. **Set counting method**:

- Once per session (leads, signups)

- Every event (purchases)

4. **Import to Google Ads** - For conversion-optimized bidding

### Conversion Values

```javascript

// Event with conversion value

gtag('event', 'purchase', {

'value': 99.99,

'currency': 'USD'

});

```

Or set default value in GA4 Admin when marking conversion.

---

## Custom Dimensions and Metrics

### When to Use

**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

### Setup Steps

1. Admin > Data display > Custom definitions

2. Create dimension or metric

3. Choose scope:

- **Event**: Per event (content_type)

- **User**: Per user (account_type)

- **Item**: Per product (product_category)

4. Enter parameter name (must match event parameter)

### Examples

|-----------|-------|-----------|-------------|

---

## Audiences

### Creating Audiences

Admin > Data display > Audiences

**Use cases:**

- Remarketing audiences (export to Ads)

- Segment analysis

- Trigger-based events

### Audience Examples

**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

---

## Debugging

### DebugView

Enable with:

- URL parameter: `?debug_mode=true`

- Chrome extension: GA Debugger

- gtag: `'debug_mode': true` in config

View at: Reports > Configure > DebugView

### Real-Time Reports

Check events within 30 minutes:

Reports > Real-time

### Common Issues

**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)

---

## Data Quality

### Filters

Admin > Data streams > [Stream] > Configure tag settings > Define internal traffic

**Exclude:**

- Internal IP addresses

- Developer traffic

- Testing environments

### Cross-Domain Tracking

For multiple domains sharing analytics:

1. Admin > Data streams > [Stream] > Configure tag settings

2. Configure your domains

3. List all domains that should share sessions

### Session Settings

Admin > Data streams > [Stream] > Configure tag settings

- Session timeout (default 30 min)

- Engaged session duration (10 sec default)

---

## Integration with Google Ads

### Linking

1. Admin > Product links > Google Ads links

2. Enable auto-tagging in Google Ads

3. Import conversions in Google Ads

### Audience Export

Audiences created in GA4 can be used in Google Ads for:

- Remarketing campaigns

- Customer match

- Similar audiences

mdskills/analytics/references/gtm-implementation.md

7.4 kB

# Google Tag Manager Implementation Reference

Detailed guide for implementing tracking via Google Tag Manager.

## Contents

- Container Structure (tags, triggers, variables)

- Naming Conventions

- Data Layer Patterns

- Common Tag Configurations (GA4 configuration tag, GA4 event tag, Facebook pixel)

- Preview and Debug

- Workspaces and Versioning

- Consent Management

- Advanced Patterns (tag sequencing, exception handling, custom JavaScript variables)

## Container Structure

### Tags

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

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

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

---

## Naming Conventions

### Recommended Format

```

[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

```

---

## Data Layer Patterns

### Basic Structure

```javascript

// Initialize (in <head> before GTM)

window.dataLayer = window.dataLayer || [];

// Push event

dataLayer.push({

'event': 'event_name',

'property1': 'value1',

'property2': 'value2'

});

```

### Page Load Data

```javascript

// Set on page load (before GTM container)

window.dataLayer = window.dataLayer || [];

dataLayer.push({

'pageType': 'product',

'contentGroup': 'products',

'user': {

'loggedIn': true,

'userId': '12345',

'userType': 'premium'

}

});

```

### Form Submission

```javascript

document.querySelector('#contact-form').addEventListener('submit', function() {

dataLayer.push({

'event': 'form_submitted',

'formName': 'contact',

'formLocation': 'footer'

});

```

### Button Click

```javascript

document.querySelector('.cta-button').addEventListener('click', function() {

dataLayer.push({

'event': 'cta_clicked',

'ctaText': this.innerText,

'ctaLocation': 'hero'

});

```

### E-commerce Events

```javascript

// 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

}]

}

});

```

---

## Common Tag Configurations

### GA4 Configuration Tag

**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

### GA4 Event Tag

**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

### Facebook Pixel - Base

**Tag Type:** Custom HTML

```html

!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

### Facebook Pixel - Event

**Tag Type:** Custom HTML

```html

fbq('track', 'Lead', {

content_name: '{{DL - form_name}}'

});

</script>

```

**Trigger:** Custom Event - form_submitted

---

## Preview and Debug

### Preview Mode

1. Click "Preview" in GTM

2. Enter site URL

3. GTM debug panel opens at bottom

**What to check:**

- Tags fired on this event

- Tags not fired (and why)

- Variables and their values

- Data layer contents

### Debug Tips

**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

---

## Workspaces and Versioning

### Workspaces

Use workspaces for team collaboration:

- Default workspace for production

- Separate workspaces for large changes

- Merge when ready

### Version Management

**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

```

---

## Consent Management

### Consent Mode Integration

```javascript

// 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'

});

}

```

### GTM Consent Overview

1. Enable Consent Overview in Admin

2. Configure consent for each tag

3. Tags respect consent state automatically

---

## Advanced Patterns

### Tag Sequencing

**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

### Exception Handling

**Trigger exceptions** - Prevent tag from firing:

- Exclude certain pages

- Exclude internal traffic

- Exclude during testing

### Custom JavaScript Variables

```javascript

// 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;

}

```

mdskills/analytics/SKILL.md

8.2 kB

---

description: When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions "set up tracking," "GA4," "Google Analytics," "conversion tracking," "event tracking," "UTM parameters," "tag manager," "GTM," "analytics implementation," "tracking plan," "how do I measure this," "track conversions," "attribution," "Mixpanel," "Segment," "are my events firing," or "analytics isn't working." Use this whenever someone asks how to know if something is working or wants to measure marketing results. For A/B test measurement, see ab-testing.

metadata:

version: 2.0.0

---

# Analytics Tracking

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.

## Initial Assessment

**Check for product marketing context first:**

Before implementing tracking, understand:

1. **Business Context** - What decisions will this data inform? What are key conversions?

2. **Current State** - What tracking exists? What tools are in use?

3. **Technical Context** - What's the tech stack? Any privacy/compliance requirements?

---

## Core Principles

### 1. Track for Decisions, Not Data

- Every event should inform a decision

- Avoid vanity metrics

- Quality > quantity of events

### 2. Start with the Questions

- What do you need to know?

- What actions will you take based on this data?

- Work backwards to what you need to track

### 3. Name Things Consistently

- Naming conventions matter

- Establish patterns before implementing

- Document everything

### 4. Maintain Data Quality

- Validate implementation

- Monitor for issues

- Clean data > more data

---

## Tracking Plan Framework

### Structure

```

Event Name | Category | Properties | Trigger | Notes

---------- | -------- | ---------- | ------- | -----

```

### Event Types

| 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](references/event-library.md)

---

## Event Naming Conventions

### Recommended Format: Object-Action

```

signup_completed

button_clicked

form_submitted

article_read

checkout_payment_completed

```

### Best Practices

- Lowercase with underscores

- Be specific: `cta_hero_clicked` vs. `button_clicked`

- Include context in properties, not event name

- Avoid spaces and special characters

- Document decisions

---

## Essential Events

### Marketing Site

| Event | Properties |

|-------|------------|

| cta_clicked | button_text, location |

| form_submitted | form_type |

| signup_completed | method, source |

| demo_requested | - |

### Product/App

| 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](references/event-library.md)

---

## Event Properties

### Standard Properties

| 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 |

### Best Practices

- Use consistent property names

- Include relevant context

- Don't duplicate automatic properties

- Avoid PII in properties

---

## GA4 Implementation

### Quick Setup

1. Create GA4 property and data stream

2. Install gtag.js or GTM

3. Enable enhanced measurement

4. Configure custom events

5. Mark conversions in Admin

### Custom Event Example

```javascript

gtag('event', 'signup_completed', {

'method': 'email',

'plan': 'free'

});

```

**For detailed GA4 implementation**: See [references/ga4-implementation.md](references/ga4-implementation.md)

---

## Google Tag Manager

### Container Structure

| Component | Purpose |

|-----------|---------|

| Tags | Code that executes (GA4, pixels) |

| Triggers | When tags fire (page view, click) |

| Variables | Dynamic values (click text, data layer) |

### Data Layer Pattern

```javascript

dataLayer.push({

'event': 'form_submitted',

'form_name': 'contact',

'form_location': 'footer'

});

```

**For detailed GTM implementation**: See [references/gtm-implementation.md](references/gtm-implementation.md)

---

## UTM Parameter Strategy

### Standard Parameters

| 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 |

### Naming Conventions

- Lowercase everything

- Use underscores or hyphens consistently

- Be specific but concise: `blog_footer_cta`, not `cta1`

- Document all UTMs in a spreadsheet

---

## Debugging and Validation

### Testing Tools

| Tool | Use For |

|------|---------|

| GA4 DebugView | Real-time event monitoring |

| GTM Preview Mode | Test triggers before publish |

| Browser Extensions | Tag Assistant, dataLayer Inspector |

### Validation Checklist

- [ ] Events firing on correct triggers

- [ ] Property values populating correctly

- [ ] No duplicate events

- [ ] Works across browsers and mobile

- [ ] Conversions recorded correctly

- [ ] No PII leaking

### Common Issues

| Issue | Check |

|-------|-------|

| Events not firing | Trigger config, GTM loaded |

| Wrong values | Variable path, data layer structure |

| Duplicate events | Multiple containers, trigger firing twice |

---

## Privacy and Compliance

### Considerations

- Cookie consent required in EU/UK/CA

- No PII in analytics properties

- Data retention settings

- User deletion capabilities

### Implementation

- Use consent mode (wait for consent)

- IP anonymization

- Only collect what you need

- Integrate with consent management platform

---

## Output Format

### Tracking Plan Document

```markdown

# [Site/Product] Tracking Plan

## Overview

- Tools: GA4, GTM

- Last updated: [Date]

## Events

|------------|-------------|------------|---------|

## Custom Dimensions

| Name | Scope | Parameter |

|------|-------|-----------|

| user_type | User | user_type |

## Conversions

| Conversion | Event | Counting |

|------------|-------|----------|

| Signup | signup_completed | Once per session |

```

---

## Task-Specific Questions

1. What tools are you using (GA4, Mixpanel, etc.)?

2. What key actions do you want to track?

3. What decisions will this data inform?

4. Who implements - dev team or marketing?

5. Are there privacy/consent requirements?

6. What's already tracked?

---

## Tool Integrations

For implementation, see the [tools registry](../../tools/REGISTRY.md). Key analytics tools:

|------|----------|:---:|-------|

| **GA4** | Web analytics, Google ecosystem | ✓ | [ga4.md](../../tools/integrations/ga4.md) |

---

## Related Skills

- **ab-testing**: For experiment tracking

- **seo-audit**: For organic traffic analysis

- **cro**: For conversion optimization (uses this data)

- **revops**: For pipeline metrics, CRM tracking, and revenue attribution

jsonskills/aso/evals/evals.json

7.2 kB

{

"skill_name": "aso",

"evals": [

{

"id": 1,

"prompt": "Here's our app on the App Store: https://apps.apple.com/us/app/example/id123456789. Can you audit our listing and tell me what to fix?",

"expected_output": "Should check for product-marketing.md first. Should detect this is an Apple App Store URL and run the full ASO audit workflow. Should fetch the listing and extract Apple-specific fields (title 30 chars, subtitle 30 chars, description, promotional text 170 chars, category, screenshots, video, ratings). Should classify the app's brand maturity tier (Dominant/Established/Challenger) before scoring. Should score all 6 dimensions (Title & Subtitle 20%, Description 15%, Visual Assets 25%, Ratings & Reviews 20%, Metadata & Freshness 10%, Conversion Signals 10%) with weighted total out of 100 and a grade. Should output a scorecard, top 3 quick wins, detailed findings, keyword suggestions, visual recommendations, and prioritized action plan with specific 'change X from Y to Z' recommendations including character counts.",

"assertions": [

"Checks for product-marketing.md",

"Identifies as Apple App Store URL",

"Classifies brand maturity tier",

"Scores all 6 dimensions with weights",

"Provides scorecard with grade",

"Lists top 3 quick wins",

"Recommendations include character counts",

"Recommendations are specific (X to Y format)"

"files": []

{

"id": 2,

"prompt": "We're a small fintech startup with about 5,000 downloads. Our Play Store listing has a 2.8 rating and we haven't updated the description in 8 months. Help us figure out what to fix first.",

"expected_output": "Should recognize this as a Challenger-tier Google Play app. Should immediately flag the always-flag issues: rating below 4.0 (critical), last update >3 months ago. Should apply strict Challenger scoring against textbook best practices. Should focus on Google Play-specific guidance: full description is indexed for search (target 2-3% keyword density), no hidden keyword field, feature graphic required (1024x500), max 8 screenshots, Android Vitals affect ranking. Should prioritize fixing the rating issue (response strategy, in-app review prompts) and refreshing the description with keyword strategy. Should recommend updating the listing soon to break the >3 month stale signal.",

"assertions": [

"Identifies as Google Play app",

"Classifies as Challenger tier",

"Flags rating below 4.0",

"Flags stale update (>3 months)",

"Notes Google Play indexes full description",

"Mentions feature graphic requirement",

"Recommends keyword strategy in description",

"Prioritizes rating improvement"

"files": []

{

"id": 3,

"prompt": "Instagram's App Store listing has just 'Instagram' as the title and barely any keywords. Should they fix that?",

"expected_output": "Should classify Instagram as a Dominant-tier app and apply tier-adjusted scoring. Should explain that brand-only titles are valid for Dominant apps (score 8+ if brand IS the keyword) because users search by brand name, not generic keywords. Should NOT flag this as a missed opportunity. Should explain the key principle: 'Is this a mistake or a deliberate choice by a team that has data I don't?' Should note that other dimensions (screenshots, description, what's new) are also evaluated against tier — lifestyle/brand photography and brief release notes are acceptable for Dominant apps. Should contrast with what would be a problem for a Challenger app.",

"assertions": [

"Classifies Instagram as Dominant tier",

"Explains brand-only titles are valid for Dominant",

"Does NOT flag the title as a problem",

"Contrasts Dominant vs Challenger treatment",

"Cites the 'mistake vs deliberate choice' principle"

"files": []

{

"id": 4,

"prompt": "Compare our app https://apps.apple.com/us/app/ourapp/id111 against these two competitors: https://apps.apple.com/us/app/competitor1/id222 and https://apps.apple.com/us/app/competitor2/id333",

"expected_output": "Should run Phase 3 competitor comparison. Should fetch and score all three apps with the same 6-dimension framework. Should build a side-by-side comparison table highlighting where the user's app is weaker or stronger across each dimension. Should identify keyword gaps — terms competitors target that the user's app doesn't. Should produce a prioritized list of competitor-informed changes. Should call out platform-specific considerations consistently across all three apps.",

"assertions": [

"Scores all 3 apps with same framework",

"Builds comparison table",

"Identifies where user's app is weaker",

"Identifies keyword gaps vs competitors",

"Produces competitor-informed action list"

"files": []

{

"id": 5,

"prompt": "We only have 3 screenshots and no preview video. Does this really matter that much?",

"expected_output": "Should explain that screenshot count and video presence are heavily weighted in the Visual Assets dimension (25% of total score). Should cite specific data: Apple allows up to 10 screenshots per device with the first 3 visible in search, and 90% of users never scroll past the 3rd. Should note Apple screenshot captions are indexed for search since June 2025. Should cite the conversion benchmark: app preview video delivers +20-40% conversion lift on iOS (note Google Play video has lower ROI — only ~6% tap play). Should recommend adding 5-8 screenshots minimum with caption text, and a 15-30s preview video. Should flag fewer than 5 screenshots as an always-flag issue across all tiers.",

"assertions": [

"Notes Visual Assets is 25% of score",

"Cites first 3 screenshots are most important",

"Mentions screenshot caption indexing (Apple, 2025)",

"Cites video conversion lift benchmark",

"Notes Google Play video has lower ROI",

"Recommends specific screenshot count and video specs",

"Flags <5 screenshots as always-flag issue"

"files": []

{

"id": 6,

"prompt": "Should I run a Custom Product Page experiment on iOS for our paid search campaigns?",

"expected_output": "Should reference Apple-specific facts: Custom Product Pages (CPP) — up to 70 — appear in organic search since July 2025 with +5.9% average conversion lift. Should explain CPPs let you test variants of screenshots, video, and promotional text against specific traffic sources (e.g., paid search keywords). Should recommend matching CPP variants to the keyword intent for the campaign. Should cross-reference the ab-testing skill for proper experiment design and the ads skill for the campaign side. Should note this is an iOS-only feature (Google Play has Store Listing Experiments and Custom Store Listings as equivalents).",

"assertions": [

"Identifies Custom Product Pages as iOS-specific",

"Cites +5.9% conversion lift benchmark",

"Explains CPP can match traffic source intent",

"Cross-references ab-testing or ads skill",

"Notes Google Play equivalents"

"files": []

}

]

}

mdskills/aso/references/apple-specs.md

5.9 kB

# Apple App Store — Official Specs & Guidelines

All data from developer.apple.com as of March 2026.

## Character Limits

| ----------------------- | ---------------- | ------------------------ | -------------------------------------------------------- |

**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.

## Screenshot Specs

| ---------------- | ------------- | ----- | -------------------------- |

| 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 Vision Pro | If applicable | 1-10 | 3840 x 2160 |

- Formats: JPEG, PNG

- Apple auto-scales from required base sizes to smaller devices

## App Preview Video Specs

- **Count:** Up to 3 per app

- **Duration:** 15-30 seconds

- **Max file size:** 500 MB

- **Codecs:** H.264 (10-12 Mbps, up to 30fps) or ProRes 422 HQ

- **Audio:** Stereo, 256 kbps AAC or PCM, 44.1/48 kHz

- **Formats:** .mov, .m4v, .mp4

- **Behavior:** Autoplays muted on product page (iOS 11+)

## Custom Product Pages (CPPs)

- **Max:** 70 additional pages (plus 1 default)

- **Customizable:** Screenshots, promotional text, app previews, deep links (iOS 18+)

- **Keywords:** Each keyword combo must be unique to a single CPP

- **Review:** Submitted to App Review independently of app updates

- **Organic search:** CPPs appear in organic search results since July 2025

- **Performance:** +2.5 percentage points higher conversion on average vs default

## Product Page Optimization (A/B Testing)

- **Treatments:** Up to 3 vs original

- **Testable:** App icons, screenshots, app preview videos

- **NOT testable:** Title, subtitle, description, keywords

- **Concurrent tests:** 1 per app

- **Max duration:** 90 days

- **Icon constraint:** All icon variants must be in the published app binary

- **Confidence:** Apple recommends 90% threshold (Bayesian method)

- **Cannot modify** a test once started

## In-App Events

- **Max approved:** 15 in App Store Connect at once

- **Max published:** 10 on App Store simultaneously

- **Max duration:** 31 days per event

- **Pre-event promotion:** Up to 14 days before start

- **Badge types:** Challenge, Competition, Live Event, Major Update, New Season, Premiere, Special Event

**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.

## Ratings & Reviews

- **SKStoreReviewController:** Max 3 prompts per 365-day period

- System controls display frequency (may show fewer than 3)

- Do not use custom buttons to request reviews

- Developers can respond to all reviews in App Store Connect

- Summary rating is territory-specific

## Metadata Rejection Triggers (App Review Guidelines)

| 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/

mdskills/aso/references/benchmarks.md

4.9 kB

# ASO Benchmarks & Conversion Data

Industry data from AppTweak, SplitMetrics, Sensor Tower, and others. Updated March 2026.

## Conversion Rate Benchmarks by Category

**Average CVR (page view to install):**

- iOS overall: **25.0%**

- Google Play overall: **27.3%**

| 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 Impact on Conversion

| 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:**

- **4.0 stars** = minimum for Apple featuring, user trust, conversion viability

- **4.5+ stars** = optimal zone. Sweet spot: 4.1-4.9

- **5.0 stars** can look suspicious to users

- **Below 3.5** = sharp visibility drop on both stores

- **79% of users** check ratings before downloading

- **50% reject** apps below 3 stars

Sources: AppFollow, MobileAction, Sensor Tower, Troof.ai

## Preview Video Impact

**iOS:** +20-40% conversion lift (video autoplays on product page)

**Google Play:** Minimal lift (only ~6% of visitors tap to play)

- Autoplay introduced in iOS 11 caused **+47% conversion jump**

- Users who watch video are **2x more likely to install**

- Average watch time: **4-6.5 seconds** (first 5 seconds are critical)

- 50%+ of viewers watch to the end

**Takeaway:** Video is high-ROI on iOS, low-ROI on Google Play.

Sources: StoreMaven, SplitMetrics, Leanplum

## Screenshot Impact

- **90% of users** do not scroll past the 3rd screenshot

- Average scroll rate: only **17%**

- Users spend **6-10 seconds** scanning before deciding

- **First screenshot decides everything**

- Well-designed screenshots lift conversion **20-35%**

- A/B test winners see **10-25% improvement**

- **Optimal count:** 4-5 for utility apps, 5-6 for complex apps

- More than 6: diminishing returns, can cause decision paralysis

- Top 200 apps update screenshots **2-4 times/year**

- Top Google Play games update visuals **up to 8x/year**

- **57% of top games** A/B tested screenshots at least 2x in 2024

Sources: AppTweak, ASOMobile, Sensor Tower

## Custom Product Pages (Apple CPPs)

- Average conversion lift: **+5.9% for apps**, **+3.5% for games**

- Best cases: up to **+8.6%**

- Organic referral: **+2.5 percentage points** (156% lift vs 1.6% baseline)

- Apple Ads CPP CVR: **55.8% in 2024** (up from 42.1% in 2023)

- **Only 31% of apps** and **26% of games** use CPPs (low adoption = opportunity)

- Screenshot reordering alone produced **+16.6% installs** in one case

Sources: AppTweak, SplitMetrics, MobileAction

## Custom Store Listings (Google Play CSLs)

- Up to **50 custom versions** per app

- Case study (Lockwood/Avakin Life): **+57% CVR** over 2 months

- Can target inactive/churned users (28+ days no activity)

Source: Phiture, MobileAction

## In-App Events (Apple)

- **55% of top 200 apps** use them regularly

- +**15-20% more impressions** from editorial/browse placements

- One case: **+124% surge** in total impressions

- One case: **+50% impressions AND first-time downloads**

- Search CVR uptick: **+10.3%**

- Re-downloads increase: **+15.5%**

- **Boost is short-lived** -- KPIs drop to baseline when event ends

- Optimal: **2-4 active events per month**

Sources: Phiture, AppTweak, Appalize

## Promotional Content (Google Play)

- Apps with featuring see **2x explore acquisitions** (official Google)

- +2% 28-day active users and +4% revenue on average

Source: Google Play Console documentation

## A/B Test Impact Thresholds

| Improvement | Classification |

| ----------- | ---------------------------------- |

| >10% | Strong winner -- apply immediately |

| 5-10% | Meaningful winner |

| 2-5% | Marginal winner |

| <2% | Noise -- not significant |

Source: SplitMetrics, MobileAction

mdskills/aso/references/google-play-specs.md

5.9 kB

# Google Play Store — Official Specs & Guidelines

All data from support.google.com and developer.android.com as of March 2026.

## Character Limits

| ----------------- | ----------- | ---------------------- | ------------------------------------- |

## Prohibited in Metadata (enforced since Sept 2021)

**Title, Icon, Developer Name:**

- Emojis, emoticons, repeated special characters

- ALL CAPS (unless registered brand)

- Performance claims: "top," "best," "#1," "free," "no ads"

- Misleading store performance or endorsement

- Calls-to-action: "update now," "download now"

**Short Description:**

- Same performance claims as title

- Calls-to-action

- Unattributed testimonials

**Screenshots, Feature Graphic, Video:**

- Time-sensitive taglines

- Calls-to-action ("Download now," "Play now")

- Must authentically showcase app functionality

## Screenshot Specs

| ---------- | ----- | ----- | ------------ | -------------- | ------------- |

| 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 |

- **Recommended phone size:** 1080x1920 (portrait)

- **Format:** JPEG or 24-bit PNG (no alpha)

- **Max file size:** 8 MB each

**Note:** Google Play max is 8 screenshots per device, not 10 like Apple.

## Feature Graphic

- **Dimensions:** 1024 x 500 px (exact, required)

- **Format:** JPEG or 24-bit PNG (no alpha)

- Displayed at top of listing and in featured placements

## App Icon

- **Dimensions:** 512 x 512 px

- **Format:** 32-bit PNG (with alpha)

- **Max file size:** 1,024 KB

- **Shape:** Full square (Google applies 30% corner radius automatically)

- **Prohibited:** Ranking claims, download counts, deal text, emoji

## Preview Video

- **Format:** YouTube URL (public or unlisted)

- **Duration:** 30 seconds to 2 minutes recommended

- No ads, no monetization, must be embeddable, not age-restricted

- **Does NOT autoplay** (only ~6% of visitors tap to play)

## Store Listing Experiments (A/B Testing)

- **Variants:** Up to 3 per experiment (plus control)

- **Testable:** Icon, feature graphic, screenshots, video, short description, full description

- **Concurrent:** Cannot run more than 1 default graphics experiment simultaneously

- **Audience:** Signed-in Google Play users only

- **Metrics:** First-time installers + retained first-time installers (1-day retention)

- **Duration:** Run at least 7 days (weekday/weekend variance)

- **Localized:** Test across up to 5 languages simultaneously

## Custom Store Listings

- **Max:** 50 per app (100 for Play partners)

- **Customizable:** Title, short/full description, icon, screenshots, feature graphic, video

- **Targeting:** Country/region, pre-registration, install state, Google Ads campaigns, inactive/churned users (28+ days)

- **2025 addition:** Gemini AI auto-generates text for CSLs in Play Console

## Promotional Content (LiveOps)

| 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 |

- Submit **4+ days** before start (standard review)

- Submit **14+ days** before for featuring requests

- **Impact:** "Over twice as many explore acquisitions during featuring" (official Google)

## Android Vitals — Ranking Thresholds

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.

## Search Ranking — Official Factors

Google confirms these affect ranking:

1. **Metadata relevance** — Title carries most weight. NLP scans title + short desc + full desc.

2. **App quality** — Android Vitals (crash/ANR rates)

3. **Ratings and reviews** — Star rating + review text. 85% of featured apps have 4.0+

4. **Install volume and velocity** — Total installs + daily/weekly frequency

5. **Engagement and retention** — Session frequency, duration, retention rates

6. **Update frequency** — Regular updates signal active maintenance

7. **Localization** — Regional keyword/visual adaptation. 59% of US apps localize titles.

Sources: support.google.com/googleplay/android-developer/answer/4448378,

support.google.com/googleplay/android-developer/answer/9898842,

developer.android.com/topic/performance/vitals

mdskills/aso/references/report-template.md

5.0 kB

# ASO Audit Report Template

Use this structure for all ASO audit reports.

---

## Header

```

# 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})

```

---

## Score Card

```

|-----------|-------|-------|-----------|

| 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

---

## Top 3 Quick Wins

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. ...

```

---

## Detailed Findings

### Title & Subtitle Analysis

```

**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}

```

### Description Analysis

```

**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}

```

### Visual Assets Analysis

```

**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}

```

### Ratings & Reviews Analysis

```

**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}

```

### Metadata & Freshness

```

**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}

```

### Conversion Signals

```

**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 Suggestions

```

|---------|-----------|----------------|----------|

| {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.

---

## Competitor Comparison (if applicable)

```

| Metric | {Your App} | {Competitor 1} | {Competitor 2} |

|--------|-----------|----------------|----------------|

| Title keywords | ... | ... | ... |

| Rating | ... | ... | ... |

| Screenshots | ... | ... | ... |

| Video | ... | ... | ... |

| Description keywords | ... | ... | ... |

| Last updated | ... | ... | ... |

| Overall ASO score | ... | ... | ... |

```

---

## Priority Action Plan

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}

```

---

## Limitations

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).

mdskills/aso/references/scoring-criteria.md

13 kB

# ASO Scoring Criteria

Score each dimension 0-10 using the rubrics below.

**Apply brand maturity tier adjustments** from Phase 1.5 of the main skill.

---

## Brand Maturity Adjustments (apply to all dimensions)

Before scoring, determine the app's tier: **Dominant**, **Established**, or **Challenger**.

**Dominant apps (Instagram, Uber, Spotify, WhatsApp, Netflix):**

- Brand-only titles score 8+ (the brand IS the keyword)

- Lifestyle/brand screenshots score same as captioned UI screenshots

- Generic What's New at weekly+ cadence scores 8+

- Missing in-app events for utility apps is not a penalty

- Description scored on conversion quality only, not keyword presence

- Localization scored relative to actual market footprint

- Missing preview video is acceptable if brand awareness is near-universal

**Established apps (Duolingo, Strava, Notion, Calm, Cash App):**

- Brand-first titles with 1-2 keywords score normally

- Strategic description/visual choices get benefit of the doubt

- All other dimensions scored normally

**Challenger apps (most apps):**

- Scored strictly against textbook ASO — every character and feature matters

**Key principle:** Before docking points, ask: "Is this a mistake or a data-informed

choice by a team with more information than I have?"

---

## 1. Title & Subtitle (Weight: 20%)

**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:**

- Characters used vs limit (title: 30, subtitle/short desc: 30/80). "Near max" = within 3 chars of the limit (27+/30, 77+/80)

- Primary keyword in title

- Keyword duplication between title and subtitle

- Whether app purpose is immediately clear

- Unnecessary words (articles, prepositions) consuming space

- Special characters or claims ("#1", "best") that risk rejection (Apple)

---

## 2. Description (Weight: 15%)

### Apple App Store

| 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 |

### Google Play

| 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:**

- First 3 lines quality (visible before "Read More")

- Feature-benefit framing (not just feature lists)

- Social proof (downloads, awards, press mentions)

- Call to action

- Keyword density (Google Play only - count target keywords / total words)

- HTML formatting usage (Google Play)

- Promotional text presence and quality (Apple)

---

## 3. Visual Assets (Weight: 25%)

| 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:**

- Screenshot count (minimum 5, ideal 8-10)

- Caption/overlay text on screenshots (one message per screen, 5-7 words max)

- First 3 screenshots (highest conversion impact on Apple)

- Preview video presence and quality

- Icon distinctiveness (no text in icon, bold shapes, stands out)

- Feature graphic presence (Google Play - mandatory for featured placements)

- Screenshot storytelling flow (do they tell a coherent story?)

- Localized visual assets (for non-English markets)

- Caption keywords (Apple - indexed since June 2025)

---

## 4. Ratings & Reviews (Weight: 20%)

| 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:**

- Average rating (target: 4.0+ minimum, 4.5+ ideal)

- Total rating count

- Recent review sentiment (last 5-10 visible reviews)

- Common complaint themes (bugs, crashes, pricing, UX)

- Developer response presence and quality

- Rating trend (improving or declining, if visible)

- Review recency (fresh reviews signal active user base)

---

## 5. Metadata & Freshness (Weight: 10%)

| 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:**

- Last update date and recency

- Number of supported languages/localizations

- Category selection (is it the best fit? less competitive alternative?)

- In-app events (Apple) or promotional content (Google) presence

- Data safety / privacy nutrition label completeness

- Age rating appropriateness

- Version history quality (do release notes communicate value?)

- What's New text quality

---

## 6. Conversion Signals (Weight: 10%)

| 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:**

- Price transparency (free, freemium, paid - is it clear?)

- In-app purchase list quality (do IAP names communicate value?)

- Download range (Google Play - 10K+, 100K+, 1M+ signals trust)

- Developer name/brand recognition

- "Editors' Choice" or featured badges

- Press mentions or awards in description

- Related apps from same developer (portfolio trust signal)

- Privacy practices transparency

---

## Calculating Final Score

```

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

```

mdskills/aso/SKILL.md

15 kB

---

description: "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,' 'audit my listing,' 'why aren't people downloading my app,' 'improve my app conversion,' 'keyword optimization for app,' or 'compare my app to competitors.' Use when the user shares an App Store or Google Play URL and wants to improve it."

metadata:

version: 2.0.0

---

# ASO Audit

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.

## When to Use

- User shares an App Store or Google Play URL

- User asks to audit or optimize an app listing

- User wants to compare their app against competitors

- User asks about app store ranking, visibility, or download conversion

## Before Auditing

**Check for product marketing context first:**

## Phase 1 — Identify Store & Fetch

### Detect store type from URL

```

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}"`

### Fetch the listing

Use WebFetch to retrieve the listing page. Extract every available field:

**Apple App Store fields:**

- App name (title) — 30 char limit

- Subtitle — 30 char limit

- Description (long) — not indexed for search, but matters for conversion

- Promotional text — 170 chars, updatable without new release

- Category (primary + secondary)

- Screenshots (count, order, caption text)

- Preview video (presence, duration)

- Rating (average + count)

- Recent reviews (visible ones)

- Price / in-app purchases

- Developer name

- Last updated date

- Version history notes

- Age rating

- Size

- Languages / localizations listed

- In-app events (if any visible)

**Google Play fields:**

- App name (title) — 30 char limit

- Short description — 80 char limit

- Full description — 4,000 char limit, IS indexed for search

- Category + tags

- Feature graphic (presence)

- Screenshots (count, order)

- Preview video (presence)

- Rating (average + count)

- Recent reviews (visible ones)

- Price / in-app purchases

- Developer name

- Last updated date

- What's new text

- Downloads range

- Content rating

- Data safety section

- Languages listed

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.

### Visual asset assessment

WebFetch cannot extract screenshot images or caption text. **Take a screenshot

of the listing page** to get visual data:

1. Navigate to the listing URL and capture a full-page screenshot

2. Assess the screenshot for: icon quality, screenshot count, caption text,

messaging quality, preview video presence, feature graphic (Google Play)

3. If browser tools are unavailable, ask the user to share a screenshot of the

listing page

**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.

---

## Phase 1.5 — Assess Brand Maturity

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 definitions

| 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 |

### How tier affects scoring

**Dominant apps** get adjusted scoring in these areas:

- **Title:** Brand-only or brand-first titles are valid (score 8+ if brand is the keyword). These apps don't need generic keyword discovery.

- **Description:** Score purely on conversion quality, not keyword presence. If the app is a household name, a well-crafted brand description beats a keyword-stuffed one.

- **Visual Assets:** Lifestyle/brand photography instead of UI demos is a legitimate conversion strategy. No video is acceptable if the product is hard to demo in 30s or brand awareness is near-universal.

- **What's New:** Generic release notes at weekly+ cadence are acceptable (score 8+). At scale, detailed changelogs have minimal ROI and risk backlash.

- **In-app events:** Missing events for utility apps with massive install bases (Uber, WhatsApp) is not a penalty. These apps don't need discovery help.

- **Localization:** Score relative to actual market, not absolute count. A US-only fintech with 2 languages (English + Spanish) is appropriately localized.

**Established apps** get partial adjustment:

- Brand-first titles are fine but should still include 1-2 keywords

- Strategic description choices get benefit of the doubt

- Other dimensions scored normally

**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.

---

## Phase 2 — Score Each Dimension

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 triggers

- `references/google-play-specs.md` — Official Google Play limits, screenshot specs, Android Vitals thresholds, policies

- `references/benchmarks.md` — Conversion data, rating impact, video lift, screenshot behavior, CPP/event benchmarks

### Dimensions and Weights

| --- | -------------------- | ------ | ------------------------------------------------------------------------- |

| 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 interpretation

| 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 |

---

## Phase 3 — Competitor Comparison (Optional)

If the user provides competitor URLs or asks for comparison:

1. Fetch 2-3 top competitors in the same category

2. Run the same scoring on each

3. Build a comparison table highlighting where the user's app is weaker/stronger

4. Identify keyword gaps — terms competitors rank for that the user's app doesn't target

If no competitors are specified, suggest the user provide 2-3 or offer to search

for top apps in their category.

---

## Phase 4 — Generate Report

Use the template in `references/report-template.md` to structure the output.

The report must include:

1. **Score card** — table with all 6 dimensions, scores, and grade

2. **Top 3 quick wins** — changes that take <1 hour and have highest impact

3. **Detailed findings** — per-dimension breakdown with specific issues and fixes

4. **Keyword suggestions** — based on title/description analysis and competitor gaps

5. **Visual asset recommendations** — specific screenshot/video improvements

6. **Priority action plan** — ordered list of changes by impact vs effort

### Report rules

- Every recommendation must be **specific and actionable** ("Change subtitle from X to Y" not "Improve subtitle")

- Include character counts for all text recommendations

- Flag platform-specific differences (Apple vs Google) when relevant

- Note what CANNOT be assessed without paid tools (search volume, exact rankings)

- When suggesting keyword changes, explain WHY each keyword matters

---

## Platform-Specific Rules

### Apple App Store — Key Facts

- Title (30 chars) + Subtitle (30 chars) + Keyword field (100 **bytes**, hidden) = indexed text

- Keywords field is bytes not chars — Arabic/CJK use 2-3 bytes per char

- Long description is NOT indexed for search — optimize for conversion only

- Promotional text (170 chars) does NOT affect search (Apple confirmed)

- Never repeat words across title/subtitle/keyword field (Apple indexes each word once)

- Keyword field: commas, no spaces ("photo,editor,filter" not "photo, editor, filter")

- Screenshots: up to 10 per device. First 3 visible in search — 90% never scroll past 3rd

- Screenshot captions indexed since June 2025 (AI extraction)

- In-app events: max 10 published at once, max 31 days each. Indexed and appear in search

- Custom Product Pages (up to 70) in organic search since July 2025. +5.9% avg conversion lift

- App preview video: up to 3, 15-30s each. Autoplays muted — +20-40% conversion lift

- SKStoreReviewController: max 3 prompts per 365 days

- Apple has human editorial curation — quality and design matter more

- See `references/apple-specs.md` for full specs, dimensions, and rejection triggers

### Google Play — Key Facts

- Title (30 chars) + Short description (80 chars) + Full description (4,000 chars) = indexed text

- Full description IS indexed — target 2-3% keyword density naturally

- No hidden keyword field — all keywords must be in visible text

- Google NLP/semantic understanding — keyword stuffing detected and penalized

- Prohibited in title: emojis, ALL CAPS, "best"/"#1"/"free", CTAs (enforced since 2021)

- Screenshots: min 2, **max 8** per device (not 10 like Apple)

- Feature graphic (1024x500, exact) required for featured placements

- Video does NOT autoplay — only ~6% of users tap play (low ROI vs iOS)

- Android Vitals directly affect ranking: crash >1.09% or ANR >0.47% = reduced visibility

- Promotional Content: submit 14 days early for featuring. Apps see 2x explore acquisitions

- Custom Store Listings: up to 50 (can target churned users, specific countries, ad campaigns)

- Store Listing Experiments: test up to 3 variants, run 7+ days, 1 experiment at a time

- See `references/google-play-specs.md` for full specs and policy details

### What Apple Indexes vs What Google Indexes

| 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 |

---

## Common Issues Checklist

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):**

- [ ] Rating below 4.0

- [ ] Last update > 3 months ago

- [ ] Google Play description has no keyword strategy (under 1% density)

- [ ] Google Play missing feature graphic

- [ ] Apple keyword field likely has repeated words (inferred from title+subtitle)

- [ ] Category mismatch — app would face less competition in a different category

- [ ] Fewer than 5 screenshots

**Flag for Challenger/Established only** _(not mistakes for Dominant apps):_

- [ ] Title wastes characters on brand name only (no keywords) _(Dominant: brand IS the keyword)_

- [ ] Subtitle/short description duplicates title keywords

- [ ] Description first 3 lines are generic _(Dominant: may be brand-voice choice)_

- [ ] No preview video _(Dominant: may be rational if product is hard to demo)_

- [ ] Screenshots are just UI dumps with no messaging/captions _(Dominant: lifestyle/brand shots may convert better)_

- [ ] Only 1-2 localizations _(score relative to actual market, not absolute count)_

- [ ] No in-app events or promotional content _(Dominant utility apps may not need discovery help)_

**Flag for all tiers but note context:**

- [ ] No developer responses to negative reviews _(note volume — responding at 10M+ reviews is a different challenge than at 1K)_

- [ ] Generic "What's New" text _(acceptable at weekly+ release cadence for Established/Dominant)_

---

## Task-Specific Questions

1. What is the App Store or Google Play URL?

2. Is this your app or a competitor's?

3. What category does the app compete in?

4. Do you have competitor URLs to compare against?

5. Are you focused on search visibility, conversion rate, or both?

6. Do you have access to App Store Connect or Google Play Console data?

---

## Related Skills

- **cro**: For optimizing the conversion of web-based landing pages that drive app installs

- **ad-creative**: For creating App Store and Google Play ad creatives

- **analytics**: For setting up install attribution and in-app event tracking

- **customer-research**: For understanding user needs and language to inform listing copy

jsonskills/churn-prevention/evals/evals.json

6.5 kB

{

"skill_name": "churn-prevention",

"evals": [

{

"id": 1,

"prompt": "Our SaaS product has a 7% monthly churn rate and we need to bring it down. We're a $49/month project management tool with about 2,000 paying customers. Can you help us design a churn prevention strategy?",

"expected_output": "Should check for product-marketing.md first. Should address both voluntary and involuntary churn. Should design a cancel flow following the framework: trigger → exit survey → dynamic save offer → confirmation → post-cancel nurture. Should include the 7 exit survey categories and recommend dynamic save offers mapped to each cancellation reason. Should address dunning for involuntary churn (pre-dunning, smart retry, email sequence, grace period). Should recommend a health score model. Should provide prioritized implementation plan.",

"assertions": [

"Checks for product-marketing.md",

"Addresses both voluntary and involuntary churn",

"Designs cancel flow with proper stages",

"Includes exit survey with multiple categories",

"Maps save offers to cancellation reasons",

"Addresses dunning stack for payment recovery",

"Recommends health score model",

"Provides prioritized implementation plan"

"files": []

{

"id": 2,

"prompt": "We keep losing customers because their credit cards expire. About 15% of our churn is from failed payments. How do we fix this?",

"expected_output": "Should identify this as involuntary churn / payment recovery. Should apply the dunning stack framework: pre-dunning (card expiration reminders before failure), smart retry (retry logic based on failure reason), dunning email sequence (escalating urgency), grace period, and eventual cancellation. Should provide specific timing for each stage. Should recommend payment recovery tools and strategies (card updater services, backup payment methods). Should include recovery rate benchmarks.",

"assertions": [

"Identifies as involuntary churn / payment recovery",

"Applies dunning stack framework",

"Includes pre-dunning card expiration reminders",

"Includes smart retry logic",

"Provides dunning email sequence with escalating urgency",

"Recommends grace period before cancellation",

"Mentions card updater services or backup payment methods",

"Includes recovery benchmarks"

"files": []

{

"id": 3,

"prompt": "what should we show users when they click the cancel button? right now they just go straight to cancellation with no attempt to save them",

"expected_output": "Should trigger on casual phrasing. Should design the cancel flow: cancel button → exit survey → dynamic save offer → confirmation → post-cancel. Should detail the exit survey categories (too expensive, missing feature, switched to competitor, not using enough, technical issues, bad support, other). Should provide dynamic save offers matched to each reason (e.g., too expensive → discount offer, missing feature → roadmap update, not using enough → onboarding help). Should include copy recommendations for each screen. Should warn against dark patterns (making it impossible to cancel).",

"assertions": [

"Triggers on casual phrasing",

"Designs multi-step cancel flow",

"Includes exit survey with 7 categories",

"Provides dynamic save offers mapped to reasons",

"Includes copy recommendations",

"Warns against dark patterns",

"Includes confirmation and post-cancel steps"

"files": []

{

"id": 4,

"prompt": "How do we identify which customers are at risk of churning before they actually cancel? We want to be proactive.",

"expected_output": "Should apply the health score model framework. Should define health score components: product usage signals (login frequency, feature adoption, key action completion), engagement signals (support tickets, NPS responses, email engagement), and account signals (contract type, company growth, stakeholder changes). Should recommend scoring methodology (0-100 scale). Should define risk tiers and recommended interventions for each tier. Should suggest data sources and implementation approach.",

"assertions": [

"Applies health score model framework",

"Defines usage-based health signals",

"Defines engagement-based health signals",

"Defines account-based health signals",

"Recommends scoring methodology",

"Defines risk tiers with interventions",

"Suggests data sources and implementation"

"files": []

{

"id": 5,

"prompt": "Our exit survey shows that 40% of cancellations say 'too expensive' as the reason. What save offers should we try?",

"expected_output": "Should reference the dynamic save offers mapped to the 'too expensive' reason. Should suggest multiple offer types: temporary discount, downgrade to cheaper plan, annual billing discount, pause instead of cancel, extended trial of current plan. Should recommend testing different offers to find what works best. Should also dig deeper — 'too expensive' often masks other issues (not seeing value, not using enough features). Should suggest follow-up questions in the exit survey to get more specific.",

"assertions": [

"References save offers for 'too expensive' reason",

"Suggests multiple offer types (discount, downgrade, pause)",

"Recommends testing different offers",

"Notes that 'too expensive' often masks other issues",

"Suggests deeper follow-up questions",

"Provides specific save offer copy or structure"

"files": []

{

"id": 6,

"prompt": "We want to set up a win-back email sequence for customers who already cancelled. Can you help write those emails?",

"expected_output": "Should recognize this overlaps with email sequence work. Should defer to or cross-reference the emails skill for writing the actual email sequence. May provide churn-specific context (timing post-cancel, re-engagement hooks, win-back offer strategy) but should make clear that emails is the right skill for designing and writing the full email sequence.",

"assertions": [

"Recognizes overlap with email sequence work",

"References or defers to emails skill",

"May provide churn-specific context for the sequence",

"Does not attempt to write a full email sequence"

"files": []

}

]

}

mdskills/churn-prevention/references/cancel-flow-patterns.md

10 kB

# Cancel Flow Patterns

Detailed cancel flow patterns by business type, billing provider, and industry.

---

## Cancel Flow by Business Type

### B2C / Self-Serve SaaS

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]."

---

### B2B / Team Plans

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 |

---

### Freemium / Free-to-Paid

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

---

## Cancel Flow by Billing Interval

### Monthly Subscribers

- More price-sensitive, shorter commitment

- Discount offers work well (20-30% for 2-3 months)

- Pause is effective (1-2 months)

- Suggest annual plan at a discount as an alternative

**Offer priority:**

1. Discount (if reason = price)

2. Pause (if reason = not using / temporary)

3. Annual plan switch (if engaged but price-sensitive)

### Annual Subscribers

- Higher commitment, often cancelling for stronger reasons

- Prorate refund expectations matter

- Longer save window (they've already paid)

- Personal outreach more justified (higher LTV at stake)

**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

---

## Save Offer Patterns

### The Discount Ladder

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

### The Pause Playbook

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."

### The Downgrade Path

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

### The Competitor Switch Handler

When the cancel reason is "switching to competitor":

1. **Ask which competitor** (optional, don't force it)

2. **Show a comparison** if you have one (see competitors skill)

3. **Offer a migration credit** ("We'll match their price for 3 months")

4. **Request a feedback call** ("15 minutes to understand what we're missing")

This data is gold for product and marketing teams.

---

## Post-Cancel Experience

What happens after cancel matters for:

- Win-back potential

- Word of mouth

- Review sentiment

### Confirmation Page

```

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.

```

### Post-Cancel Sequence

| 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.

---

## Segmentation Rules

The most effective cancel flows use segmentation to show different offers to different customers.

### Segmentation Dimensions

| 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) |

### Segment-Specific Flows

**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

---

## Implementation Checklist

### Phase 1: Foundation (Week 1)

- [ ] Add cancel flow (survey + 1 offer + confirmation)

- [ ] Set up exit survey with 5-7 reason categories

- [ ] Map one offer per reason (simple 1:1 mapping)

- [ ] Track cancel reasons and save rate in analytics

- [ ] Enable pre-dunning card expiry emails

### Phase 2: Optimization (Weeks 2-4)

- [ ] Add fallback offers (primary + secondary per reason)

- [ ] Implement pause subscription option

- [ ] Set up dunning email sequence (4 emails over 10 days)

- [ ] Enable smart retries (Stripe Smart Retries or equivalent)

- [ ] Add MRR-based routing for high-value accounts

### Phase 3: Advanced (Month 2+)

- [ ] Build health score from usage signals

- [ ] Set up proactive intervention triggers

- [ ] A/B test discount amounts and offer types

- [ ] Segment flows by plan, tenure, and usage

- [ ] Post-cancel win-back sequence (coordinate with emails skill)

- [ ] Cohort analysis: churn by channel, plan, tenure

---

## Compliance Notes

### FTC Click-to-Cancel Rule (US)

- Cancellation must be as easy as signup

- Cannot require a phone call to cancel if signup was online

- Cannot add excessive steps to discourage cancellation

- Save offers are allowed but "continue cancelling" must be clear

### GDPR / Data Retention (EU)

- Inform users about data retention period post-cancel

- Offer data export before account deletion

- Honor deletion requests within 30 days

- Don't use post-cancel data for marketing without consent

### General Best Practices

- Always show a clear path to complete cancellation

- Never hide the cancel button (dark pattern)

- Process cancellation even if save flow has errors

- Confirm cancellation with email receipt

mdskills/churn-prevention/references/dunning-playbook.md

12 kB

# Dunning Playbook

Complete guide to recovering failed payments and reducing involuntary churn.

---

## Why Dunning Matters

- Failed payments cause 30-50% of all subscription churn

- Most failed payments are recoverable with the right strategy

- Subscription businesses lose an estimated $129 billion annually to involuntary churn

- Effective dunning recovers 50-60% of failed payments

---

## The Dunning Timeline

```

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

```

---

## Pre-Dunning: Prevent Failures Before They Happen

### Card Expiry Management

| 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

```

### Card Updater Services

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

### Backup Payment Methods

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)

### Pre-Billing Notifications

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

---

## Smart Retry Strategy

### Decline Type Classification

|------|------|---------|--------|

### Retry Schedule by Provider

**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

---

## Dunning Email Sequence

### Email 1: Payment Failed (Day 0)

**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

```

### Email 2: Reminder (Day 3)

**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

```

### Email 3: Urgency (Day 7)

**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

```

### Email 4: Final Warning (Day 10)

**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

```

---

## Grace Period Management

### What Happens During Grace Period

| 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 |

### Access Degradation Options

**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

### Post-Grace Period

| 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) |

---

## Provider-Specific Setup

### Stripe

**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

### Chargebee

**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

### Paddle

**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

### Recurly

**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

---

## In-App Dunning

Don't rely on email alone. Show payment failures in the app:

### Banner Pattern

```

┌──────────────────────────────────────────────────────┐

│ ⚠ 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

### Modal Pattern (for final warning)

```

┌─────────────────────────────────────┐

│ │

│ 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] │

│ │

└─────────────────────────────────────┘

```

---

## Measuring Dunning Performance

### Key Metrics

| 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 |

### Benchmarking

**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% |

### ROI Calculation

```

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

```

mdskills/churn-prevention/SKILL.md

18 kB

---

description: "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 offer,' 'dunning,' 'failed payment recovery,' 'win-back,' 'retention,' 'exit survey,' 'pause subscription,' 'involuntary churn,' 'people keep canceling,' 'churn rate is too high,' 'how do I keep users,' or 'customers are leaving.' Use this whenever someone is losing subscribers or wants to build systems to prevent it. For post-cancel win-back email sequences, see emails. For in-app upgrade paywalls, see paywalls."

metadata:

version: 2.0.0

---

# Churn Prevention

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.

## Before Starting

**Check for product marketing context first:**

Gather this context (ask if not provided):

### 1. Current Churn Situation

- What's your monthly churn rate? (Voluntary vs. involuntary if known)

- How many active subscribers?

- What's the average MRR per customer?

- Do you have a cancel flow today, or does cancel happen instantly?

### 2. Billing & Platform

- What billing provider? (Stripe, Chargebee, Paddle, Recurly, Braintree)

- Monthly, annual, or both billing intervals?

- Do you support plan pausing or downgrades?

- Any existing retention tooling? (Churnkey, ProsperStack, Raaft)

### 3. Product & Usage Data

- Do you track feature usage per user?

- Can you identify engagement drop-offs?

- Do you have cancellation reason data from past churns?

- What's your activation metric? (What do retained users do that churned users don't?)

### 4. Constraints

- B2B or B2C? (Affects flow design)

- Self-serve cancellation required? (Some regulations mandate easy cancel)

- Brand tone for offboarding? (Empathetic, direct, playful)

---

## How This Skill Works

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:

1. **Build a cancel flow** — Design from scratch with survey, save offers, and confirmation

2. **Optimize an existing flow** — Analyze cancel data and improve save rates

3. **Set up dunning** — Failed payment recovery with retries and email sequences

---

## Cancel Flow Design

### The Cancel Flow Structure

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.

### Exit Survey Design

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?"

### Dynamic Save Offers

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) | — |

### Save Offer Types

**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

### Cancel Flow UI Patterns

```

┌─────────────────────────────────────┐

│ 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](references/cancel-flow-patterns.md).

---

## Churn Prediction & Proactive Retention

The best save happens before the customer ever clicks "Cancel."

### Risk Signals

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 |

### Health Score Model

Build a simple health score (0-100) from weighted signals:

```

Health Score = (

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 |

### Proactive Interventions

**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 |

---

## Involuntary Churn: Payment Recovery

Failed payments cause 30-50% of all churn but are the most recoverable.

### The Dunning Stack

```

Pre-dunning → Smart retry → Dunning emails → Grace period → Hard cancel

```

### Pre-Dunning (Prevent Failures)

- **Card expiry alerts**: Email 30, 15, and 7 days before card expires

- **Backup payment method**: Prompt for a second payment method at signup

- **Card updater services**: Visa/Mastercard auto-update programs (reduces hard declines 30-50%)

- **Pre-billing notification**: Email 3-5 days before charge for annual plans

### Smart Retry Logic

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.

### Dunning Email Sequence

|-------|--------|------|---------|

| 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

### Recovery Benchmarks

|--------|------|---------|------|

| 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](references/dunning-playbook.md).

---

## Metrics & Measurement

### Key Churn Metrics

| 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 |

### Cohort Analysis

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?

### Cancel Flow A/B Tests

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](../../tools/integrations/posthog.md) for setup.

---

## Common Mistakes

- **No cancel flow at all** — Instant cancel leaves money on the table. Even a simple survey + one offer saves 10-15%

- **Making cancellation hard to find** — Hidden cancel buttons breed resentment and bad reviews. Many jurisdictions require easy cancellation (FTC Click-to-Cancel rule)

- **Same offer for every reason** — A blanket discount doesn't address "missing feature" or "not using it"

- **Discounts too deep** — 50%+ discounts train customers to cancel-and-return for deals

- **Ignoring involuntary churn** — Often 30-50% of total churn and the easiest to fix

- **No dunning emails** — Letting payment failures silently cancel accounts

- **Guilt-trip copy** — "Are you sure you want to abandon us?" damages brand trust

- **Not tracking save offer LTV** — A "saved" customer who churns 30 days later wasn't really saved

- **Pausing too long** — Pauses beyond 3 months rarely reactivate. Set limits.

- **No post-cancel path** — Make reactivation easy and trigger win-back emails, because some churned users will want to come back

---

## Tool Integrations

For implementation, see the [tools registry](../../tools/REGISTRY.md).

### Retention Platforms

| 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 |

### Billing Providers (Dunning)

|----------|:------------:|:--------------:|:------------:|

### Related CLI Tools

| 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 |

---

## Related Skills

- **emails**: For win-back email sequences after cancellation

- **paywalls**: For in-app upgrade moments and trial expiration

- **pricing**: For plan structure and annual discount strategy

- **onboarding**: For activation to prevent early churn

- **analytics**: For setting up churn signal events

- **ab-testing**: For testing cancel flow variations with statistical rigor

jsonskills/co-marketing/evals/evals.json

6.7 kB

{

"skill_name": "co-marketing",

"evals": [

{

"id": 1,

"prompt": "We make a project management tool for design agencies. Who should we look for as co-marketing partners?",

"expected_output": "Should check for product-marketing.md first. Should apply the Partner Identification Framework with audience overlap analysis. Should identify ideal partner characteristics: same buyer persona (design agencies), different problem solved, adjacent in the workflow. Should suggest specific partner categories: design tools (Figma, Adobe), proposal/contract tools (Bonsai, HoneyBook), client communication (Notion, Slack), invoicing/payments (Stripe, FreshBooks), file storage/handoff (Dropbox, Frame.io). Should recommend audience scoring criteria. Should suggest sources to find partners: integration ecosystem, Crossbeam/Reveal for account overlap, customer surveys, G2/Capterra category neighbors, podcasts/newsletters they sponsor.",

"assertions": [

"Checks for product-marketing.md",

"Identifies same persona / different problem characteristic",

"Suggests specific partner categories in workflow",

"Mentions Crossbeam or account overlap data",

"Lists multiple sources to find partners",

"Applies scoring criteria"

"files": []

{

"id": 2,

"prompt": "We're partnering with a competitor — wait, not a competitor, a complementary CRM company. Help us brainstorm 5 campaign ideas we could run together.",

"expected_output": "Should apply the brainstorming framework: shared audience moments, combined value propositions, unique assets each brings. Should propose campaign ideas across multiple types from the campaign type tables (content partnerships, webinars/events, product/integration marketing, community/social). Should suggest specific ideas like: co-authored blog post or research report, joint webinar, 'better together' integration landing page, joint case study with shared customer, integration launch, bundle/discount, conference booth sharing. Should ask the campaign idea prompts to spark ideas: what would we create if we had to launch in 2 weeks, what content do both audiences desperately need, what data do we both have that would make a compelling story.",

"assertions": [

"Applies brainstorming framework",

"Proposes campaigns across multiple types (content, events, integration, community)",

"Suggests specific actionable ideas",

"Mentions integration or 'better together' angle",

"Uses brainstorming prompts"

"files": []

{

"id": 3,

"prompt": "Draft a cold outreach email to a potential co-marketing partner. They're a content management platform and we make a marketing analytics tool. Both serve B2B marketing teams.",

"expected_output": "Should use the cold outreach template structure. Should include: subject line with both company names, brief role intro, specific observation about audience overlap (not generic), one concrete campaign idea (not 'let's do something'), clear ask for a quick call. Should keep it short and personal. Should optionally mention call prep: account overlap data (Crossbeam/Reveal), 2-3 specific campaign ideas, audience metrics, past partnership examples, clear ask of what's wanted and what's offered.",

"assertions": [

"Includes subject with both company names",

"Specific observation about audience overlap",

"Includes one concrete campaign idea",

"Includes clear ask for a call",

"Keeps it short and personal",

"Mentions what to prepare for the call"

"files": []

{

"id": 4,

"prompt": "We've identified 5 potential partners but only have time for one campaign this quarter. How should we pick?",

"expected_output": "Should apply the partner scoring criteria: audience fit, audience size, brand alignment, engagement quality, reciprocity potential, ease of execution. Should recommend scoring each partner 1-5 across these criteria. Should weight by current goal (e.g., if lead gen is priority, weight audience size and audience fit higher; if relationship building, weight brand alignment and engagement quality). Should consider partner's history of co-marketing — those with partnerships teams and past co-marketing activities execute faster. Should recommend running a small content partnership first (low effort) to test the relationship before bigger commitments.",

"assertions": [

"Applies partner scoring criteria",

"Includes all 6 scoring dimensions",

"Weights by goal",

"Considers ease of execution / partnership history",

"Recommends starting with low-effort format"

"files": []

{

"id": 5,

"prompt": "Our partnership webinar with another SaaS company got 200 signups. How do we split the leads?",

"expected_output": "Should address the lead handling question from the Structuring the Partnership section. Should explain common splits: each partner keeps their own registrations (cleanest but loses cross-pollination), all leads shared between both (max reach, requires clear MQL/SQL handoff), split by audience source (your list vs theirs). Should recommend documenting this in advance in a co-marketing agreement covering campaign description, responsibilities, timeline, lead handling, promotion, branding, costs, metrics sharing. Should note measuring success: leads generated per partner, lead quality (MQL/SQL conversion rate), revenue attributed. Should recommend a post-campaign debrief and discussing future collaboration if it worked.",

"assertions": [

"Explains lead split options",

"Recommends documenting in agreement",

"Lists agreement components",

"Mentions measuring lead quality not just volume",

"Recommends post-campaign debrief"

"files": []

{

"id": 6,

"prompt": "Our customer success team wants us to launch a referral program. Can you help us design one?",

"expected_output": "Should recognize this is about customer referrals, not co-marketing between companies. Should redirect to the referrals skill, which specifically handles customer referral and affiliate programs (customers referring customers). Should note co-marketing is partner-to-partner marketing while referrals is customer-driven word-of-mouth. May offer brief co-marketing context if it's relevant to the strategy, but should make clear referrals is the right skill for the task.",

"assertions": [

"Recognizes this is customer referral, not co-marketing",

"Defers to referrals skill",

"Distinguishes co-marketing from referral programs",

"Does not attempt full co-marketing strategy"

"files": []

}

]

}

mdskills/co-marketing/SKILL.md

9.9 kB

---

description: "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,' 'integration marketing,' 'cross-promotion,' 'collaborate with another company,' 'partnership ideas,' or 'co-brand.' For customer referral programs, see referrals. For launch-specific partnerships, see launch."

metadata:

version: 2.0.0

---

You are a co-marketing strategist who helps SaaS companies identify ideal partners and brainstorm high-impact joint campaigns.

## Before Starting

**Check for product marketing context first:**

## When to Use This Skill

- Finding potential co-marketing partners

- Brainstorming campaign ideas with a specific partner

- Planning joint launches or promotions

- Evaluating partnership fit

- Structuring co-marketing agreements

---

## Partner Identification Framework

### 1. Audience Overlap Analysis

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?

### 2. Partner Scoring Criteria

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? |

### 3. Where to Find Partners

**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

---

## Co-Marketing Campaign Types

### Content Partnerships

|--------|--------|--------------|----------|

### Webinars & Events

| 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 |

### Product & Integration Marketing

| 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 |

### Community & Social

| 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 |

---

## Brainstorming Partner Campaigns

When brainstorming with a specific partner, consider:

### 1. Shared Audience Moments

- What trigger events matter to both audiences?

- What seasonal moments align with both products?

- What industry trends affect both customer bases?

### 2. Combined Value Propositions

- What can customers achieve with both tools that they can't with one?

- What workflow does the combination enable?

- What pain point does the integration solve?

### 3. Unique Assets Each Brings

| 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 |

### 4. Campaign Idea Prompts

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?"

---

## Approaching Potential Partners

### Cold Outreach Template

```

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]

```

### What to Prepare for the Call

1. **Account overlap data** (if available via Crossbeam/Reveal)

2. **2-3 specific campaign ideas** (not just "let's do something")

3. **Your audience metrics** (list size, traffic, engagement)

4. **Examples of past partnerships** (shows you can execute)

5. **Clear ask** (what you want from them, what you'll provide)

---

## Structuring the Partnership

### Key Questions to Align On

- **Lead ownership**: How are leads split or shared?

- **Promotion commitments**: What will each party do to promote?

- **Asset creation**: Who creates what? Who approves?

- **Timeline**: When does each phase happen?

- **Success metrics**: How will you measure success?

- **Follow-up**: Will you do more together if it works?

### Simple Co-Marketing Agreement Outline

1. **Campaign description**: What you're doing together

2. **Responsibilities**: Who does what

3. **Timeline**: Key dates and deadlines

4. **Lead handling**: How leads are captured, shared, followed up

5. **Promotion**: Minimum commitments from each side

6. **Branding**: Logo usage, approval process

7. **Costs**: Who pays for what (if any)

8. **Metrics sharing**: What data you'll share post-campaign

---

## Measuring Co-Marketing Success

### Quantitative Metrics

- Leads generated (total and per partner)

- Lead quality (MQL/SQL conversion rate)

- Revenue attributed

- Audience growth (new subscribers, followers)

- Content engagement (views, downloads, shares)

### Qualitative Metrics

- Ease of collaboration

- Partner responsiveness

- Audience reception

- Brand lift

- Relationship strengthened for future campaigns

---

## Co-Marketing Checklist

### Partner Identification

- [ ] List tools your customers already use

- [ ] Check Crossbeam/Reveal for account overlap

- [ ] Score top 5 potential partners

- [ ] Research their past co-marketing activities

### Campaign Planning

- [ ] Agree on campaign type and goals

- [ ] Define lead sharing arrangement

- [ ] Assign responsibilities and deadlines

- [ ] Set success metrics

### Execution

- [ ] Create shared assets (landing page, content, etc.)

- [ ] Coordinate promotion schedules

- [ ] Brief both teams on talking points

### Post-Campaign

- [ ] Share metrics with partner

- [ ] Debrief on what worked/didn't

- [ ] Discuss future collaboration opportunities

---

## Task-Specific Questions

1. Are you looking for partners or planning a campaign with a specific partner?

2. What type of co-marketing are you most interested in? (content, events, integrations, community)

3. What's your audience size? (email list, social following, traffic)

4. Do you have existing integration partners?

5. Have you done co-marketing before? What worked/didn't?

6. What's your timeline and budget for co-marketing?

---

## Tool Integrations

For implementation, see the [tools registry](../../tools/REGISTRY.md). Key tools for co-marketing:

| Tool | Best For | Guide |

|------|----------|-------|

| **Crossbeam** | Account overlap with partners | [crossbeam.md](../../tools/integrations/crossbeam.md) |

| **Introw** | Partner program management, deal registration | [introw.md](../../tools/integrations/introw.md) |

| **PartnerStack** | Partner and affiliate program management | [partnerstack.md](../../tools/integrations/partnerstack.md) |

---

## Related Skills

- **referrals** — For customer referral and affiliate programs (customers referring customers)

- **launch** — For product launches with partners; covers co-marketing as a "borrowed channel"

- **content-strategy** — For content planning including co-created content

- **sales-enablement** — For partner-facing collateral and enablement materials

jsonskills/cold-email/evals/evals.json

6.9 kB

{

"skill_name": "cold-email",

"evals": [

{

"id": 1,

"prompt": "Write a cold email to VP of Marketing at mid-size B2B SaaS companies. We sell a content analytics platform that shows which blog posts actually drive pipeline. Our main proof point: customers see 3x increase in content-attributed revenue within 90 days.",

"expected_output": "Should check for product-marketing.md first. Should write like a peer, not a vendor. Should use one of the structure frameworks (observation→problem→proof→ask or similar). Subject line should be 2-4 words, lowercase, internal-looking. Every sentence should earn its place. Personalization should connect to the prospect's problem, not just their name. Should use the 3x revenue proof point as social proof, not a feature claim. CTA should be low-friction (not 'book a demo'). Should provide 2-3 variations. Should include a quality check against the guidelines.",

"assertions": [

"Checks for product-marketing.md",

"Writes like a peer, not a vendor",

"Uses a structure framework from the skill",

"Subject line is short, lowercase, internal-looking",

"Every sentence earns its place (concise)",

"Personalization connects to prospect's problem",

"Uses proof point as social proof",

"CTA is low-friction",

"Provides 2-3 variations"

"files": []

{

"id": 2,

"prompt": "Help me write a cold email to CTOs at enterprise companies. I sell cybersecurity training. My current email has a 2% open rate and 0% reply rate.",

"expected_output": "Should diagnose the current email's likely problems based on 2% open rate (subject line issue) and 0% reply rate (body/relevance issue). Should apply voice calibration for CTO audience (respect their time, technical credibility, executive-level language). Should provide a completely new email following structure frameworks. Subject line should be 2-4 words, look internal. Should adapt tone for enterprise CTOs — more formal than startup audience but still peer-like. Should provide the email plus analysis of why each element works.",

"assertions": [

"Diagnoses problems from the performance data",

"Identifies subject line as likely open rate issue",

"Applies voice calibration for CTO audience",

"Subject line is short, lowercase, internal-looking",

"Adapts tone for enterprise audience",

"Uses structure framework from the skill",

"Explains why each element works"

"files": []

{

"id": 3,

"prompt": "write me a follow-up sequence. prospect didn't reply to my first email about our HR software. how many should I send and how far apart?",

"expected_output": "Should trigger on casual phrasing. Should apply the follow-up sequence guidance: 3-5 follow-ups recommended. Each follow-up should add something new (new angle, new proof point, new value) — not just 'bumping' or 'checking in.' Should provide timing recommendations between emails. Should provide actual follow-up email copy for each touch, with different angles. Should include a breakup email at the end. Should note that each follow-up should be shorter than the previous.",

"assertions": [

"Triggers on casual phrasing",

"Recommends 3-5 follow-up emails",

"Each follow-up adds something new",

"Does not use 'just bumping' or 'checking in' language",

"Provides timing between emails",

"Provides actual copy for each follow-up",

"Includes a breakup email",

"Follow-ups get progressively shorter"

"files": []

{

"id": 4,

"prompt": "Review this cold email and tell me what's wrong: 'Dear Sir/Madam, I hope this email finds you well. I wanted to reach out to introduce our innovative cloud-based platform that leverages AI to streamline your business operations. We have helped over 500 companies transform their workflows. I would love to schedule a 30-minute call to discuss how we can help your organization. Best regards, John'",

"expected_output": "Should apply the quality check framework. Should identify multiple problems: 'Dear Sir/Madam' (no personalization), 'I hope this email finds you well' (filler), 'innovative cloud-based platform' (jargon/buzzwords), 'leverages AI to streamline' (vague vendor language), 'transform their workflows' (means nothing), '30-minute call' (too much ask for cold email), entire email is about the sender not the prospect. Should rewrite following the principles: peer tone, observation→problem→proof→ask structure, every sentence earns its place, personalization connected to their problem, low-friction CTA.",

"assertions": [

"Identifies lack of personalization",

"Identifies filler phrases",

"Identifies jargon and buzzwords",

"Identifies vendor language vs peer language",

"Identifies CTA as too high-friction",

"Notes email is sender-focused not prospect-focused",

"Provides a rewritten version",

"Rewrite follows cold email principles"

"files": []

{

"id": 5,

"prompt": "What are the best subject lines for cold emails? I want to maximize open rates.",

"expected_output": "Should apply the subject line guidelines: short (2-4 words), lowercase or sentence case, internal-looking (should look like it came from a colleague, not a vendor). Should provide examples following these principles. Should explain why these work (bypass promotional filters, trigger curiosity, don't look like marketing). Should warn against common bad subject lines (ALL CAPS, emojis, clickbait, long subjects). Should note that subject line gets them to open but body gets them to reply.",

"assertions": [

"Applies subject line guidelines (2-4 words, lowercase, internal-looking)",

"Provides specific examples",

"Explains why the format works",

"Warns against common bad subject line patterns",

"Notes distinction between open rate and reply rate"

"files": []

{

"id": 6,

"prompt": "Can you help me set up an automated email drip campaign for leads who download our whitepaper?",

"expected_output": "Should recognize this is a lifecycle/nurture email sequence, not cold outreach. Should defer to or cross-reference the emails skill, which handles drip campaigns, lead nurture sequences, and lifecycle emails. Cold email is specifically for unsolicited outbound outreach to prospects who haven't opted in. Should make this distinction clear.",

"assertions": [

"Recognizes this as lifecycle/nurture email, not cold outreach",

"References or defers to emails skill",

"Explains the distinction between cold email and lifecycle email",

"Does not attempt to design a nurture sequence using cold email patterns"

"files": []

}

]

}

mdskills/cold-email/references/benchmarks.md

5.7 kB

# Benchmarks, Data & Expert Methods

## Core Performance Metrics (2024–2025)

| -------------------------- | ------- | ------ | --------- | ------------------------ |

| 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 |

## Realistic Funnel Model

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.

## Performance Levers (ranked by impact)

1. **Hook type** — Timeline hooks outperform problem hooks by 3.4x in meetings

2. **Personalization depth** — Up to 250% more replies

3. **Brevity** — 25–75 words optimal, 83% more replies under 75 words

4. **Targeting precision** — ≤50 contacts per campaign = 2.76x higher reply rates

5. **Follow-up strategy** — First follow-up adds 49% more replies

6. **Reading level** — 3rd–5th grade = 67% more replies

7. **Send timing** — Thursday peaks at 6.87% reply rate

## Declining Effectiveness Trend

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.

## Response Rates by Seniority

- **Entry-level:** Highest engagement at 8% reply, 50% open

- **C-level:** 23% more likely to respond than non-C-suite when they engage (6.4% vs 5.2%)

- **CTOs/VP Tech:** 7.68% reply

- **CEOs/Founders:** 7.63% reply

- **Heads of Sales:** 6.60% (most targeted role, highest saturation)

## Industry Variation

**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%).

## Top 15 Mistakes (ranked by impact)

1. **Too long** — 70% of emails above 10th-grade level. Under 75 words = 83% more replies

2. **Too self-focused** — "We are a leading..." signals sales pitch. Count I/We sentences

3. **No clear value prop** — 71% of decision-makers ignore irrelevant emails

4. **Generic templates** — {{FirstName}} isn't personalization. Recipients detect instantly

5. **Feature dumping** — "Great reps lead with problems" (Lavender). One proof point beats ten features

6. **False personalization** — "Loved your post!" without specifics is transparent

7. **Asking too much too soon** — 30-min call in first email = "proposing on first date"

8. **Pushy language** — "Act Now" stacking increases spam flagging by 67%

9. **No CTA** — Without a clear next step, momentum dies

10. **"Just checking in" follow-ups** — "I never heard back" = 12% drop in bookings

11. **Wrong tone for audience** — Founder ≠ RevOps lead ≠ sales leader

12. **Jargon/buzzwords** — "Leverage synergistic platform" → "We help you book more meetings"

13. **Unsubstantiated claims** — "300% more leads" without proof triggers skepticism

14. **Too many contacts per company** — 1–2 people = 7.8% reply; 10+ = 3.8%

15. **Fake urgency** — Fake "Re:" / "Fwd:" / countdown timers destroy trust

## Cultural Calibration

| ------------ | --------------- | ------------------------ | -------------------- | ----------------------- |

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 Quick Reference

| 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 |

mdskills/cold-email/references/follow-up-sequences.md

3.8 kB

# Follow-Up Sequences

55% of replies come from follow-ups, not the initial email. Yet 48% of salespeople never follow up even once.

## How Many: 3–5 Total Emails

- Highest single-email reply rate: **8.4%** (Belkins).

- 4–7 email campaigns achieve **27% reply rates** vs 9% for 1–3 emails (Woodpecker, 20M emails).

- By 4th follow-up, response rates drop **55%** and spam complaints **triple**.

- Resolution: longer sequences catch different timing windows. Cap at 4 follow-ups (5 total emails). Each must add genuinely new value.

## Optimal Cadence

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).

## Angle Rotation

Each follow-up must stand alone while building toward the goal. Never just "bump this up."

| Email | 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.

## The Breakup Email

Leverages loss aversion — removing pressure while creating scarcity through withdrawal. Close.com reports **10–15% response rates** from breakup emails with cold prospects.

**Structure:**

1. Acknowledge you've reached out multiple times

2. Validate their potential lack of interest

3. State this is your final email for now

4. Leave the door open

**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.

## Phrases That Kill Response Rates

- "I never heard back" → **12% drop** in meeting booking rate (Gong)

- "Just checking in" → Zero value, signals laziness

- "Bumping this to the top of your inbox" → Presumptuous

- "Did you see my last email?" → Guilt-tripping

- "Following up on my previous message" → Generic, adds nothing

## CTA Adjustment by Seniority

**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.

mdskills/cold-email/references/frameworks.md

5.3 kB

# Cold Email Copywriting Frameworks

Frameworks beat templates — they teach thinking patterns, not copy-paste shortcuts.

## PAS — Problem, Agitate, Solution (default)

**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?

## BAB — Before, After, Bridge

**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?

## QVC — Question, Value, CTA

**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?

## AIDA — Attention, Interest, Desire, Action

**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?

## PPP — Praise, Picture, Push

**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?

## Star-Story-Solution

**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}}.

## SCQ — Situation, Complication, Question

**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?

## ACCA — Awareness, Comprehension, Conviction, Action

**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?

## 3C's (Alex Berman)

**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?

## Mouse Trap (Lavender/Will Allred)

**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?

## Justin Michael Method

**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.

## Vanilla Ice Cream (Lavender)

**Structure:** Observation → Problem/Insight → Credibility → Solution → Call-to-Conversation.

**Best for:** Universal "base" framework that works everywhere. Five parts.

## PASTOR (Ray Edwards)

**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.

mdskills/cold-email/references/personalization.md

4.3 kB

# Personalization at Scale

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).

## Four Levels of Personalization

### Level 1 — Basic (merge tags)

First name, company name, job title. Table stakes, no longer differentiating. ~5% lift.

### Level 2 — Industry/segment

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.

### Level 3 — Role-level

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.

### Level 4 — Individual (gold standard)

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.

## Research Signal Stack

| 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" |

## The 3-Minute Personalization System

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**.

## The Four -Graphic Principles (Becc Holland)

- **Demographic** — Age, profession, background

- **Technographic** — Tech stack, tools used

- **Firmographic** — Company size, funding, industry, growth stage

- **Psychographic** — Values, passions, beliefs (highest-impact dimension)

Tapping into what prospects are passionate about drives significantly higher response rates.

## Observation-Based Openers (highest performing)

**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]."

## What Feels Fake (avoid)

- AI-generated emails with similar phrasing ("I hope this email finds you well")

- Generic attention hacks disconnected from problem ("Cool that you went to UCLA!" → pitch)

- Over-personalizing to creepiness

- "I saw your LinkedIn profile and wanted to reach out" — signals mass automation

## The "So What?" Test

After writing any opening line, read from prospect's perspective: "So what? Why would I care?" If the answer is nothing, rewrite.

mdskills/cold-email/references/subject-lines.md

2.9 kB

# Subject Line Optimization

The subject line determines whether the email gets read. The data is counterintuitive: **short, boring, internal-looking subject lines win decisively.**

## Length: 2–4 words

- 2-word subject lines get **60% more opens** than 5-word (Lavender).

- Going from 2 to 4 words reduces replies by **17.5%**.

- 2–4 words yield **46% open rates** vs 34% for 10 words (Belkins, 5.5M emails).

- Mobile truncates at 30–35 characters — brevity is practical necessity.

## Internal Camouflage Principle

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"

## Capitalization: lowercase wins

All-lowercase has highest open rates (Gong, 85M+ emails). Lowercase looks more personal/internal. For cold outreach specifically, lowercase beats title case.

## Personalization: context over name

Personalized subject lines boost opens **26–50%**, but type matters:

- **First name in subject line → 12% fewer replies.** Signals automation.

- **Contextual personalization works:** pain points, competitors, trigger events, industry challenges.

- Use {{painPoint}}, {{competitor}}, {{commonGround}} — not {{firstName}}.

## Questions: only when highly specific

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.

## What to Avoid

| 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 |

## C-Suite Subject Lines

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.

mdskills/cold-email/SKILL.md

7.2 kB

---

description: 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 user mentions "cold outreach," "prospecting email," "outbound email," "email to leads," "reach out to prospects," "sales email," "follow-up email sequence," "nobody's replying to my emails," or "how do I write a cold email." Covers subject lines, opening lines, body copy, CTAs, personalization, and multi-touch follow-up sequences. For warm/lifecycle email sequences, see emails. For sales collateral beyond emails, see sales-enablement.

metadata:

version: 2.0.0

---

# Cold Email Writing

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.

## Before Writing

**Check for product marketing context first:**

Understand the situation (ask if not provided):

1. **Who are you writing to?** — Role, company, why them specifically

2. **What do you want?** — The outcome (meeting, reply, intro, demo)

3. **What's the value?** — The specific problem you solve for people like them

4. **What's your proof?** — A result, case study, or credibility signal

5. **Any research signals?** — Funding, hiring, LinkedIn posts, company news, tech stack changes

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.

---

## Writing Principles

### Write like a peer, not a vendor

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.

### Every sentence must earn its place

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.

### Personalization must connect to the problem

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](references/personalization.md) for the 4-level system and research signals.

### Lead with their world, not yours

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.

### One ask, low friction

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.

---

## Voice & Tone

**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:**

- C-suite: ultra-brief, peer-level, understated

- Mid-level: more specific value, slightly more detail

- Technical: precise, no fluff, respect their intelligence

**What it should NOT sound like:**

- A template with fields swapped in

- A pitch deck compressed into paragraph form

- A LinkedIn DM from someone you've never met

- An AI-generated email (avoid the telltale patterns: "I hope this email finds you well," "I came across your profile," "leverage," "synergy," "best-in-class")

---

## Structure

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:**

- **Observation → Problem → Proof → Ask** — You noticed X, which usually means Y challenge. We helped Z with that. Interested?

- **Question → Value → Ask** — Struggling with X? We do Y. Company Z saw [result]. Worth a look?

- **Trigger → Insight → Ask** — Congrats on X. That usually creates Y challenge. We've helped similar companies with that. Curious?

- **Story → Bridge → Ask** — [Similar company] had [problem]. They [solved it this way]. Relevant to you?

For the full catalog of frameworks with examples, see [frameworks.md](references/frameworks.md).

---

## Subject Lines

Short, boring, internal-looking. The subject line's only job is to get the email opened — not to sell.

- 2-4 words, lowercase, no punctuation tricks

- Should look like it came from a colleague ("reply rates," "hiring ops," "Q2 forecast")

- No product pitches, no urgency, no emojis, no prospect's first name

See [subject-lines.md](references/subject-lines.md) for the full data.

---

## Follow-Up Sequences

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.

- 3-5 total emails, increasing gaps between them

- Each email should stand alone (they may not have read the previous ones)

- The breakup email is your last touch — honor it

See [follow-up-sequences.md](references/follow-up-sequences.md) for cadence, angle rotation, and breakup email templates.

---

## Quality Check

Before presenting, gut-check:

- Does it sound like a human wrote it? (Read it aloud)

- Would YOU reply to this if you received it?

- Does every sentence serve the reader, not the sender?

- Is the personalization connected to the problem?

- Is there one clear, low-friction ask?

---

## What to Avoid

- Opening with "I hope this email finds you well" or "My name is X and I work at Y"

- Jargon: "synergy," "leverage," "circle back," "best-in-class," "leading provider"

- Feature dumps — one proof point beats ten features

- HTML, images, or multiple links

- Fake "Re:" or "Fwd:" subject lines

- Identical templates with only {{FirstName}} swapped

- Asking for 30-minute calls in first touch

- "Just checking in" follow-ups

---

## Data & Benchmarks

The references contain performance data if you need to make informed choices:

- [benchmarks.md](references/benchmarks.md) — Reply rates, conversion funnels, expert methods, common mistakes

- [personalization.md](references/personalization.md) — 4-level personalization system, research signals

- [subject-lines.md](references/subject-lines.md) — Subject line data and optimization

- [follow-up-sequences.md](references/follow-up-sequences.md) — Cadence, angles, breakup emails

- [frameworks.md](references/frameworks.md) — All copywriting frameworks with examples

Use this data to inform your writing — not as a checklist to satisfy.

---

## Related Skills

- **prospecting**: For building and qualifying the prospect list that this skill writes outreach against — the natural upstream step before cold-email

- **copywriting**: For landing pages and web copy

- **emails**: For lifecycle/nurture email sequences (not cold outreach)

- **social**: For LinkedIn and social posts

- **product-marketing**: For establishing foundational positioning

- **revops**: For lead scoring, routing, and pipeline management

jsonskills/community-marketing/evals/evals.json

7.5 kB

{

"skill_name": "community-marketing",

"evals": [

{

"id": 1,

"prompt": "We're a B2B SaaS that wants to start a community. Should we use Discord or Slack?",

"expected_output": "Should check for product-marketing.md first. Should apply the platform selection guide. Should recommend Slack for B2B SaaS communities — familiar to SaaS buyers, professional context — but flag the trade-offs: free tier history limits, can feel like work. Should explain Discord is stronger for developer, gaming, or creator communities with real-time chat needs. Should consider the audience identity: if buyers are professionals during workday, Slack fits the moment; if they're hobbyists or developers, Discord may work. Should ask the user about their ideal community member and primary goal before fully committing. Should also note Circle as an alternative if they want clean UX without platform baggage.",

"assertions": [

"Checks for product-marketing.md",

"Recommends Slack for B2B context",

"Notes Slack free tier limitations",

"Compares Discord use case",

"Mentions Circle or other alternatives",

"Asks about audience identity or goal"

"files": []

{

"id": 2,

"prompt": "We just launched our community 3 weeks ago. We have 40 members but only 2-3 people post regularly. Everyone else just lurks. What do we do?",

"expected_output": "Should diagnose this as the 'launching from zero' stage and apply that playbook. Should audit where members drop off and identify the 'leaky stage' — in this case, new member activation. Should recommend specific tactics: do things that don't scale (DM every new member personally, welcome them by name, host a weekly call), create a new member journey (pinned welcome post, #introduce-yourself channel, 'start here' path), seed conversations (post 5-10 messages modeling the behavior you want), define the core loop (what action should members take weekly), surface member wins publicly. Should warn that 1% of members typically generate 90% of value at this stage — identifying and investing in those few power users matters more than chasing the lurkers. Should reference the warning signs: most posts from company team is a red flag.",

"assertions": [

"Diagnoses as launch-stage / new member activation problem",

"Applies 'launching from zero' playbook",

"Recommends DMs to new members",

"Recommends new member journey design",

"Recommends seeding conversations",

"Mentions the 1% / 90% power user dynamic",

"Mentions warning sign of company-dominated posts"

"files": []

{

"id": 3,

"prompt": "Help me write community guidelines for our Discord. We're building a community for indie game developers.",

"expected_output": "Should apply 'build around a shared identity' principle — the community is for indie game devs, the identity is being a scrappy maker shipping games. Should write guidelines that describe the *vibe*, not just the rules. Should answer: what does great participation look like here? Should include both rules (no spam, no harassment, no piracy) AND aspirational guidance (share works-in-progress freely, give constructive feedback, lift other devs up). Should reinforce the identity throughout. Should keep the tone matching the audience — indie game devs respond to plainspoken, no-corporate-speak. May suggest channels structure that reinforces the identity (e.g., #devlog, #playtest-requests, #publishing-tips).",

"assertions": [

"Reinforces shared identity (indie game devs)",

"Describes vibe, not just rules",

"Includes both rules and aspirational guidance",

"Tone matches audience (indie maker)",

"May suggest channel structure"

"files": []

{

"id": 4,

"prompt": "Design an ambassador program for our community. We have about 5,000 members and a few that always help others. Want to give them more recognition.",

"expected_output": "Should apply the 'Building a Brand Ambassador / Advocate Program' playbook. Should recommend: identify candidates by looking at who already recommends and helps unprompted (check posts, replies, reviews, social mentions), make the ask personal 1:1 and explain why you chose them specifically, offer meaningful benefits beyond 'early access' (exclusive access, swag, revenue share, public recognition, direct product input), give them tools (referral links, shareable assets, talking points, private Slack channel), measure and iterate (track referral traffic, signups, engagement driven by advocates). Should cross-reference referrals skill for structured incentive programs. Should warn against generic forms and impersonal asks.",

"assertions": [

"Identifies candidates from existing helpful behavior",

"Recommends personal 1:1 ask",

"Suggests meaningful benefits beyond early access",

"Mentions tools/assets to enable advocates",

"Includes measurement plan",

"May cross-reference referrals skill"

"files": []

{

"id": 5,

"prompt": "Our community feels dead. Members joined 6 months ago but most haven't posted in months. How do I tell if it's salvageable?",

"expected_output": "Should run the Health Audit Report output format. Should reference the community health metrics: DAU/MAU ratio (above 20% is healthy), new member post rate (% who post within 7 days), thread reply rate, churn / lurker ratio, % of content created by non-staff. Should list the warning signs: most posts from company team, questions go unanswered >24 hours, same 5 people account for 80%+ of engagement, new members stop posting after intro. Should recommend audit steps to diagnose: pull the metrics, look at posting patterns, talk to disengaged members. Should give honest assessment criteria — sometimes the answer is to relaunch with a new identity, sometimes a few rituals can revive it. Should propose the top 3 priorities to fix based on common patterns.",

"assertions": [

"Uses Health Audit Report format",

"References specific health metrics with benchmarks",

"Lists warning signs",

"Recommends concrete audit steps",

"Considers that some communities can't be saved",

"Proposes top 3 priorities"

"files": []

{

"id": 6,

"prompt": "We use our community mainly for support. How do we reduce ticket volume without making customers feel ignored?",

"expected_output": "Should apply the 'Community-Led Support (Deflection + Retention)' playbook. Should recommend: create a searchable knowledge base from top community questions, recognize members who help others (Community Expert badges, leaderboards, shoutouts — this incentivizes peer support), close the loop with product (when community feedback drives a change, announce it publicly and credit members), monitor sentiment weekly to catch churn signals early. Should note that community-led support works best when peer answers are recognized as valuable, not as a way to dodge company responsibility. Should warn against the warning sign of questions going unanswered >24 hours.",

"assertions": [

"Applies community-led support playbook",

"Recommends searchable knowledge base from community Q&A",

"Recommends recognizing peer helpers",

"Mentions closing the loop with product",

"Warns about unanswered questions threshold",

"Notes peer support must feel valued, not used"

"files": []

}

]

}

mdskills/community-marketing/SKILL.md

8.7 kB

---

description: "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 advocates, increase word-of-mouth, drive community-led growth, engage users post-signup, or turn customers into evangelists. Trigger phrases: \"build a community,\" \"community strategy,\" \"Discord community,\" \"Slack community,\" \"community-led growth,\" \"brand advocates,\" \"user community,\" \"forum strategy,\" \"community engagement,\" \"grow our community,\" \"ambassador program,\" \"community flywheel.\""

metadata:

version: 2.0.0

---

# Community Marketing

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.

## Before You Start

**Check for product marketing context first:**

Understand the situation (ask if not provided):

1. **What is the product or brand?** — What problem does it solve, who uses it

2. **What community platform(s) are in play?** — Discord, Slack, Circle, Reddit, Facebook Groups, forum, etc.

3. **What stage is the community at?** — Pre-launch, 0–100 members, 100–1k, scaling, or established

4. **What is the primary community goal?** — Retention, activation, word-of-mouth, support deflection, product feedback, revenue

5. **Who is the ideal community member?** — Role, motivation, what they hope to get from joining

Work with whatever context is available. If key details are missing, make reasonable assumptions and flag them.

---

## Community Strategy Principles

### Build around a shared identity, not just a product

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?**

### Value must flow to members first

Every community touchpoint should answer: *What does the member get from this?*

- Exclusive knowledge or early access

- Peer connections they can't get elsewhere

- Recognition and status within a group they respect

- Direct influence on the product roadmap

- Career opportunities, visibility, or credibility

### The Community Flywheel

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?*

---

## Playbooks by Goal

### Launching a Community from Zero

1. **Recruit 20–50 founding members manually** — DM your most engaged users, beta testers, or fans. Don't open publicly until there is baseline activity.

2. **Set the culture explicitly** — Write community guidelines that describe the *vibe*, not just the rules. What does great participation look like here?

3. **Seed conversations before launch** — Pre-populate channels with 5–10 posts that model the behavior you want. Questions, wins, resources.

4. **Do things that don't scale at first** — Reply to every post. Welcome every new member by name. Host a weekly call. You are buying social proof.

5. **Define your core loop** — What action do you want members to take weekly? Make it easy and reward it publicly.

### Growing an Existing Community

1. **Audit where members drop off** — Are people joining but not posting? Posting once and disappearing? Identify the leaky stage.

2. **Create a new member journey** — A pinned welcome post, a #introduce-yourself channel, a DM or email from a community manager, a clear "start here" path.

3. **Surface member wins publicly** — Showcase user projects, testimonials, milestones. This reinforces identity and signals that participation has rewards.

4. **Run recurring community rituals** — Weekly threads (e.g., "What are you working on?"), monthly AMAs, seasonal challenges. Rituals create habit.

5. **Identify and invest in power users** — 1% of members generate 90% of value. Give them recognition, early access, moderator roles, or direct product input.

### Building a Brand Ambassador / Advocate Program

1. **Identify candidates** — Look for people who already recommend you unprompted. Check reviews, social mentions, community posts.

2. **Make the ask personal** — Don't send a generic form. Reach out 1:1 and explain why you chose them specifically.

3. **Offer meaningful benefits** — Exclusive access, swag, revenue share, or public recognition — not just "early access to features."

4. **Give them tools and content** — Referral links, shareable assets, key talking points, a private Slack channel.

5. **Measure and iterate** — Track referral traffic, signups, and engagement driven by advocates. Double down on what works.

### Community-Led Support (Deflection + Retention)

1. **Create a searchable knowledge base** from top community questions

2. **Recognize members who help others** — "Community Expert" badges, leaderboards, shoutouts

3. **Close the loop with product** — When community feedback drives a change, announce it publicly and credit the members who raised it

4. **Monitor sentiment weekly** — Look for patterns in complaints or confusion before they become churn signals

---

## Platform Selection Guide

| 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 |

| Reddit | 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 |

---

## Community Health Metrics

Track these signals weekly:

- **DAU/MAU ratio** — Stickiness. Above 20% is healthy for most communities.

- **New member post rate** — % of new members who post within 7 days of joining

- **Thread reply rate** — % of posts that receive at least one reply

- **Churn / lurker ratio** — Members who joined but haven't posted in 30+ days

- **Content created by non-staff** — % of posts not written by the company team

**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

---

## Output Formats

Depending on what the user needs, produce one of:

- **Community Strategy Doc** — Platform choice, identity definition, core loop, 90-day launch plan

- **Channel Architecture** — Recommended channels/categories with purpose and posting guidelines for each

- **New Member Journey** — Welcome sequence: pinned post, DM template, first-week prompts

- **Community Ritual Calendar** — Weekly/monthly recurring events and threads

- **Ambassador Program Brief** — Criteria, benefits, outreach template, tracking plan

- **Health Audit Report** — Current metrics, diagnosis, top 3 priorities to fix

Always be specific. Generic advice ("be consistent," "provide value") is not useful. Give the user something they can act on today.

---

## Task-Specific Questions

1. What platform are you building on (or considering)?

2. What stage is the community at? (Pre-launch, early, growing, established)

3. What's the primary business goal? (Retention, activation, word-of-mouth, support deflection)

4. Who is the ideal community member and what motivates them?

5. Do you have existing users or customers to seed from?

6. How much time can you dedicate to community management weekly?

---

## Related Skills

- **referrals**: For structured referral and ambassador incentive programs

- **churn-prevention**: For retention strategies that complement community engagement

- **social**: For content creation across social platforms

- **customer-research**: For understanding your community members' needs and language

jsonskills/competitor-profiling/evals/evals.json

7.3 kB

{

"skill_name": "competitor-profiling",

"evals": [

{

"id": 1,

"prompt": "Profile these three competitors for us: https://competitor1.com, https://competitor2.com, https://competitor3.com. We need this for sales enablement and to find positioning gaps.",

"expected_output": "Should check for product-marketing.md first. Should run the full research process: Phase 1 site scraping (Firecrawl map + scrape of homepage, pricing, features, about, customers, integrations, changelog), Phase 2 SEO and market data (DataForSEO for backlinks, ranked keywords, traffic, competitors), Phase 3 synthesis. Should save raw data to competitor-profiles/raw/<slug>/<YYYY-MM-DD>/ with scrapes/, seo/, reviews/ subfolders before synthesizing. Should produce one markdown file per competitor following the profile template (At a Glance, Positioning & Messaging, Product & Features, Pricing, Customers & Social Proof, SEO & Content Strategy, Strengths & Weaknesses, Competitive Implications). Should produce a _summary.md after individual profiles with comparison table, positioning map, key takeaways, gaps and opportunities. Should parallelize scraping when handling multiple competitors and use consistent metrics across all three for comparability.",

"assertions": [

"Checks for product-marketing.md",

"Runs all three phases (scraping, SEO data, synthesis)",

"Saves raw data to competitor-profiles/raw/ with date subfolder",

"Produces individual profile per competitor",

"Produces _summary.md after individual profiles",

"Uses consistent metrics across competitors",

"Parallelizes scraping when possible"

"files": []

{

"id": 2,

"prompt": "We have 12 competitors. Profile all of them.",

"expected_output": "Should recommend prioritizing rather than profiling all 12. Should suggest profiling the top 5 first based on domain overlap or market similarity (handling-multiple-competitors guidance). Should default to quick scan mode for a list this size, not deep profile. Should explain the difference: quick scan covers homepage + pricing + domain rank overview + ranked keywords summary, deep profile adds reviews, technology stack, backlink details. Should offer deep profile only if user requests or for 3 or fewer competitors. Should ask which competitors are highest priority if user wants to narrow further.",

"assertions": [

"Recommends prioritization over profiling all 12",

"Suggests top 5 based on relevance",

"Defaults to quick scan for large list",

"Explains quick scan vs deep profile difference",

"Asks user to prioritize"

"files": []

{

"id": 3,

"prompt": "I have an existing profile of Notion from 4 months ago. Should I update it or start fresh?",

"expected_output": "Should explain profile updating process from the Updating Profiles section. Should recommend updating rather than starting fresh — preserves history and enables diffing. Should explain what to re-pull: pricing page first (most volatile), SEO metrics (traffic and rankings shift monthly), changelog scan for product changes. Should update the Generated date. Should add a Change Log section at the bottom noting what changed since last profile. Should also save the new raw data to a new <YYYY-MM-DD> folder rather than overwriting prior data — supports diffing over time.",

"assertions": [

"Recommends updating over starting fresh",

"Lists what to re-pull (pricing, SEO, changelog)",

"Mentions adding Change Log section",

"Says to save raw data to new date folder",

"Says never overwrite prior date's data"

"files": []

{

"id": 4,

"prompt": "What pages should I scrape for a competitor profile?",

"expected_output": "Should list the prioritized page types from Phase 1: 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). Should explain what to extract from each: homepage (headline, value prop, primary CTA, social proof, target audience signals), pricing (tiers, prices, feature breakdown, billing options, free tier/trial details), features (categories, key capabilities, how they describe each feature), about (founding story, team size, funding, mission, HQ), customers (named customers, logos, industries, case study themes), integrations (count, key integrations, categories), changelog (release velocity, recent focus areas, product direction signals). Should mention optional review scraping (G2, Capterra, Product Hunt, TrustRadius).",

"assertions": [

"Lists all key page types in priority order",

"Specifies what to extract from each page type",

"Includes changelog as product direction signal",

"Mentions optional review scraping",

"References Firecrawl Map then Scrape workflow"

"files": []

{

"id": 5,

"prompt": "I want a profile but I don't care about SEO data — just pricing, positioning, and customer logos. Can you skip the DataForSEO calls?",

"expected_output": "Should accept the scoped request and skip Phase 2. Should run Phase 1 (Firecrawl scraping of homepage, pricing, customers pages) and Phase 3 synthesis only. Should explain that without SEO data, the profile won't include Domain Rank, organic traffic estimates, ranked keywords, referring domains, or top organic pages — but the positioning, pricing, and customer sections will be complete. Should produce an abbreviated profile flagging the SEO section as 'not collected per user request' rather than leaving placeholders. Should still save raw scrapes to disk for reuse.",

"assertions": [

"Skips Phase 2 (DataForSEO) as requested",

"Runs Phase 1 and Phase 3",

"Explains what's missing without SEO data",

"Flags SEO section as skipped, not blank",

"Still saves raw data"

"files": []

{

"id": 6,

"prompt": "Should I trust the customer logo wall on the competitor's homepage as evidence of who their customers are?",

"expected_output": "Should apply the 'Facts Over Opinions' and 'Honest Assessment' principles. Should explain that customer logos are a positioning claim, not necessarily an accurate customer breakdown — companies often show their best-known logos regardless of share of revenue. Should recommend cross-referencing: check case studies for actual usage details, search for press releases naming customers, look at customer reviews on G2/Capterra/TrustRadius for company name signals, check their LinkedIn for posts about customers. Should note: if they claim '10,000 customers' but have weak traffic/backlink profile, the claim should be flagged in the profile. Should distinguish between named customers (verifiable claims) and 'industries served' (positioning statement). Always include the date the data was pulled.",

"assertions": [

"Treats logos as positioning claim, not customer breakdown",

"Recommends cross-referencing case studies and reviews",

"Mentions checking traffic/backlink profile against claim scale",

"Distinguishes verifiable named customers from claims",

"Notes including date pulled"

"files": []

}

]

}

mdskills/competitor-profiling/references/templates.md

4.6 kB

# Profile Templates

Ready-to-use templates for competitor profile sections and the summary document.

## Contents

- Quick Scan Template

- Summary Comparison Table

- Positioning Map

- Competitive SWOT

- Profile Update Changelog

---

## Quick Scan Template

Abbreviated profile for when speed matters more than depth.

```markdown

# [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] |

## Key Takeaway

[2-3 sentences: what makes this competitor notable, where they're strong, where they're weak]

```

---

## Summary Comparison Table

Use after profiling all competitors to create a side-by-side view.

```markdown

# Competitive Landscape Summary

**Generated**: [date]

**Your product**: [name]

**Competitors profiled**: [count]

## Side-by-Side Comparison

|-----------|---------------|----------------|----------------|----------------|

| **Starting price** | $[X]/mo | $[X]/mo | $[X]/mo | $[X]/mo |

```

---

## Positioning Map

Visual representation of where competitors sit along two key dimensions. Choose the two axes most relevant to your market.

### Common Axis Pairs

| 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 |

### Format

```markdown

## 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]

```

---

## Competitive SWOT

Per-competitor SWOT relative to your product.

```markdown

## 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]

```

---

## Profile Update Changelog

Append to the bottom of any profile when updating it.

```markdown

---

## 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 |

```

mdskills/competitor-profiling/references/tool-reference.md

6.9 kB

# MCP Tool Reference for Competitor Profiling

Quick reference for the Firecrawl and DataForSEO MCP tools used in competitor profiling.

## Contents

- Firecrawl Tools (site scraping)

- DataForSEO Tools (SEO & market data)

- Recommended Execution Order

- Error Handling

---

## Firecrawl Tools

### firecrawl_map

**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`.

### firecrawl_scrape

**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.

### firecrawl_search

**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`

### firecrawl_crawl

**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.

### firecrawl_extract

**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.

---

## DataForSEO MCP Tools

### Domain-Level Intelligence

#### backlinks_summary

**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`

#### backlinks_referring_domains

**Purpose**: List top referring domains — shows where their link equity comes from.

**Input**: Target domain + limit

**Key metrics**: Per-domain: `rank`, `backlinks`, `domain` name

#### dataforseo_labs_google_domain_rank_overview

**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 $)

#### dataforseo_labs_google_ranked_keywords

**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.

#### dataforseo_labs_google_keywords_for_site

**Purpose**: Keywords relevant to a domain — broader than ranked keywords, includes opportunities.

**Input**: Target domain

**Key metrics**: `keyword`, `search_volume`, `competition`, `cpc`

### Competitive Analysis

#### dataforseo_labs_google_competitors_domain

**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.

#### dataforseo_labs_google_domain_intersection

**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.

#### dataforseo_labs_google_relevant_pages

**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.

### Technology Detection

#### domain_analytics_technologies_domain_technologies

**Purpose**: Detect the technology stack a domain uses.

**Input**: Target domain

**Key metrics**: Technologies grouped by category (CMS, analytics, marketing, payments, etc.)

### Backlink Deep Dive

#### backlinks_backlinks

**Purpose**: List individual backlinks to a domain.

**Input**: Target domain + limit

**Key metrics**: `url_from`, `url_to`, `anchor`, `domain_from_rank`, `is_new`

#### backlinks_bulk_ranks

**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.

---

## Recommended Execution Order

### Quick Scan (per competitor)

```

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

```

### Deep Profile (per competitor)

```

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

```

### Multi-Competitor (3+ competitors)

```

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

```

---

## Error Handling

| 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 |

mdskills/competitor-profiling/SKILL.md

14 kB

---

description: "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 competitor,' 'competitive intelligence,' 'competitor deep dive,' 'who are my competitors,' 'competitor landscape,' 'competitor dossier,' 'competitive audit,' or 'research these competitors.' Input is a list of competitor URLs. Output is structured competitor profile markdown files. For creating comparison/alternative pages from profiles, see competitors. For sales-specific battle cards, see sales-enablement."

metadata:

version: 2.0.0

---

# Competitor Profiling

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.

## Initial Assessment

**Check for product marketing context first:**

Before profiling, confirm:

1. **Competitor URLs** — the list of competitor website URLs to profile

2. **Your product** — what you do (if not in product marketing context)

3. **Depth level** — quick scan (key facts only) or deep profile (full research)

4. **Focus areas** — any specific dimensions to prioritize (e.g., pricing, positioning, SEO strength, content strategy)

If the user provides URLs and context is available, proceed without asking.

---

## Core Principles

### 1. Facts Over Opinions

Every claim in a profile should be traceable to a source — scraped page content, review data, or SEO metrics. Label inferences clearly.

### 2. Structured and Comparable

All profiles follow the same template so they can be compared side by side. Consistency matters more than completeness on any single profile.

### 3. Current Data

Profiles are snapshots. Always include the date generated. Flag anything that looks stale (e.g., "pricing page last updated 2023").

### 4. Honest Assessment

Don't exaggerate competitor weaknesses or downplay their strengths. Accurate profiles are useful profiles.

---

## Saving Raw Data

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 time

- Save each Firecrawl scrape as raw markdown to `scrapes/<page-name>.md`

- Save each DataForSEO response as raw JSON to `seo/<endpoint-name>.json`

- Save each review source to `reviews/<source>.md` (cleaned text) or `.json` (raw)

- Always create the date folder fresh on a new run; never overwrite a prior date's data

The synthesized profile (`<competitor-slug>.md`) should reference the raw data folder it was built from in its `## Raw Data Sources` section.

---

## Research Process

### Phase 1: Site Scraping (Firecrawl)

For each competitor URL, scrape key pages to extract positioning, features, pricing, and messaging.

#### Step 1: Map the site

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)

#### Step 2: Scrape key pages

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 |

#### Step 3: Scrape competitor reviews (optional but high-value)

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.

---

### Phase 2: SEO & Market Data (DataForSEO)

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](references/tool-reference.md).

#### Domain Authority & Backlinks

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

#### Keyword & Traffic Intelligence

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

#### Competitive Positioning Data

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

---

### Phase 3: Synthesis

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).

---

## Output Format

### Profile Document Structure

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](references/templates.md)

Each profile follows this structure:

```markdown

# [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]

```

---

### Summary Document

After profiling all competitors, generate a `competitor-profiles/_summary.md` that includes:

1. **Competitor landscape overview** — one paragraph summarizing the competitive field

2. **Comparison table** — key metrics side by side for all profiled competitors

3. **Positioning map** — where each competitor sits (e.g., simple↔complex, cheap↔premium)

4. **Key takeaways** — 3-5 strategic observations from the research

5. **Gaps and opportunities** — where the market is underserved

---

## Quick Scan vs. Deep Profile

### Quick Scan (faster, lower cost)

- Scrape: homepage + pricing page only

- SEO: domain rank overview + ranked keywords summary

- Skip: reviews, technology stack, backlink details

- Output: abbreviated profile (At a Glance + Positioning + Pricing + SEO summary)

### Deep Profile (comprehensive)

- Scrape: all key pages + review sites

- SEO: full backlink analysis + keyword intelligence + competitor discovery

- Include: technology stack, content strategy analysis, review mining

- Output: full profile template

Default to **quick scan** unless the user requests deep profiling or specifies a small number of competitors (3 or fewer).

---

## Handling Multiple Competitors

When profiling more than one competitor:

1. **Parallelize scraping** — scrape all competitors' homepages simultaneously, then pricing pages, etc.

2. **Use consistent metrics** — pull the same DataForSEO metrics for every competitor so profiles are comparable

3. **Build the summary last** — after all individual profiles are complete

4. **Prioritize by relevance** — if the user has 10+ competitors, suggest profiling the top 5 first based on domain overlap or market similarity

---

## Updating Profiles

Profiles are snapshots. When updating:

- Check pricing pages first (most volatile)

- Re-pull SEO metrics (traffic and rankings shift monthly)

- Scan changelog for product changes

- Update the "Generated" date

- Note what changed since last profile in a `## Change Log` section at the bottom

---

## Task-Specific Questions

Only ask if not answered by context or input:

1. What competitor URLs should I profile?

2. Quick scan or deep profile?

3. Any specific dimensions to focus on (pricing, SEO, positioning)?

4. Should I compare findings against your product?

---

## Related Skills

- **competitors**: For creating comparison/alternative pages from these profiles

- **prospecting**: For broader list-building qualification (this skill does deep research on specific accounts; prospecting builds the initial list)

- **customer-research**: For mining reviews and community sentiment in depth

- **content-strategy**: For using competitor content gaps to plan your own content

- **seo-audit**: For auditing your own site relative to competitors

- **sales-enablement**: For turning profiles into battle cards and sales collateral

- **ads**: For analyzing competitor ad strategies

- **pricing**: For deeper pricing analysis informed by competitor profiles

jsonskills/competitors/evals/evals.json

6.5 kB

{

"skill_name": "competitors",

"evals": [

{

"id": 1,

"prompt": "Create a 'Best Asana Alternatives' page for our project management tool. We compete mainly on price (we're $8/user vs their $24/user) and simplicity (they've become bloated). Target audience is small teams (5-20 people).",

"expected_output": "Should check for product-marketing.md first. Should identify this as the plural alternatives format ([Competitor] Alternatives). Should include the essential sections: TL;DR comparison, brief paragraphs on each alternative (including the user's product positioned first or prominently), feature comparison table, pricing comparison, who each alternative is best for. Should use the modular content architecture approach. Should address SEO considerations for the target keyword 'Asana alternatives.' Should position the user's product with the stated differentiators (price, simplicity).",

"assertions": [

"Checks for product-marketing.md",

"Identifies as plural alternatives format",

"Includes TL;DR comparison section",

"Includes feature comparison table",

"Includes pricing comparison",

"Includes 'who it's best for' per alternative",

"Positions user's product prominently with differentiators",

"Addresses SEO for target keyword"

"files": []

{

"id": 2,

"prompt": "Write a 'HubSpot vs Salesforce' comparison page. We're HubSpot and want to show why we're the better choice for SMBs.",

"expected_output": "Should identify this as the 'you vs competitor' format. Should include structured comparison sections: overview of both, feature-by-feature comparison, pricing comparison, pros/cons of each, who each is best for, and migration path. Should be factually accurate about the competitor while strategically positioning the user's product. Should include a TL;DR at the top. Should address the SMB angle throughout. Should use the centralized competitor data architecture pattern.",

"assertions": [

"Identifies as 'you vs competitor' format",

"Includes structured comparison sections",

"Includes feature-by-feature comparison",

"Includes pricing comparison",

"Includes TL;DR at the top",

"Factually accurate about competitor",

"Strategically positions user's product for SMBs",

"Includes migration path or switching section"

"files": []

{

"id": 3,

"prompt": "we need a page targeting 'mailchimp alternative' (singular). we're an email marketing platform focused on e-commerce brands.",

"expected_output": "Should trigger on casual phrasing. Should identify this as the singular alternative format ([Competitor] Alternative — positioning your product as THE alternative). Should focus the entire page on why the user's product is the best Mailchimp alternative for e-commerce. Should include: why people switch from Mailchimp, what the user's product does better (e-commerce specific features), feature comparison, pricing comparison, migration guide, customer testimonials. Should optimize for the singular keyword 'Mailchimp alternative.'",

"assertions": [

"Triggers on casual phrasing",

"Identifies as singular alternative format",

"Focuses on user's product as THE alternative",

"Includes why people switch from Mailchimp",

"Highlights e-commerce-specific advantages",

"Includes feature and pricing comparison",

"Includes migration guide",

"Optimizes for singular keyword"

"files": []

{

"id": 4,

"prompt": "Can you create a comparison page for 'Notion vs Coda'? We're a third-party review site, not affiliated with either product.",

"expected_output": "Should identify this as the 'competitor vs competitor' format (third-party perspective). Should maintain objectivity since the user isn't either product. Should include balanced comparison: overview of both, feature comparison, pricing, pros/cons, use case recommendations. Should use the essential page sections from the skill. Should suggest how to monetize the page (affiliate links, CTA to the user's own product if relevant). Should address SEO for the 'Notion vs Coda' keyword.",

"assertions": [

"Identifies as 'competitor vs competitor' format",

"Maintains objectivity (third-party perspective)",

"Includes balanced feature comparison",

"Includes pricing comparison",

"Includes use case recommendations",

"Addresses SEO considerations",

"Suggests monetization approach"

"files": []

{

"id": 5,

"prompt": "We want to build a whole competitor comparison hub. We have 5 main competitors and want to create alternative pages for each, plus head-to-head comparisons. How should we structure this?",

"expected_output": "Should apply the centralized competitor data architecture. Should recommend a hub structure with: individual alternative pages for each competitor (5 singular pages), a 'best alternatives' roundup page, head-to-head comparison pages for key matchups. Should address internal linking strategy between these pages. Should recommend the research process for gathering competitive data. Should address URL structure and site architecture for the hub.",

"assertions": [

"Applies centralized competitor data architecture",

"Recommends hub structure with multiple page types",

"Suggests individual and roundup alternative pages",

"Addresses internal linking between comparison pages",

"Recommends research process for competitive data",

"Addresses URL structure"

"files": []

{

"id": 6,

"prompt": "I need to create a battle card for our sales team comparing us to Zendesk. It should help reps handle competitive objections during sales calls.",

"expected_output": "Should recognize this as internal sales enablement material, not a public comparison page. Should defer to or cross-reference the sales-enablement skill, which handles battle cards, objection handling docs, and internal competitive collateral. May provide some competitive positioning advice but should make clear that sales-enablement is the right skill for internal sales materials.",

"assertions": [

"Recognizes this as internal sales enablement material",

"References or defers to sales-enablement skill",

"Does not attempt to create internal battle card using public comparison page patterns"

"files": []

}

]

}

mdskills/competitors/references/content-architecture.md

7.4 kB

# Content Architecture for Competitor Pages

How to structure and maintain competitor data for scalable comparison pages.

## Contents

- Centralized Competitor Data

- Competitor Data Template

- Your Product Data

- Page Generation

- Index Page Structure (alternatives index, vs comparisons index, index page best practices)

- Footer Navigation

## Centralized Competitor Data

Create a single source of truth for each competitor:

```

competitor_data/

├── notion.md

├── airtable.md

├── monday.md

└── ...

```

---

## Competitor Data Template

Per competitor, document:

```yaml

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"

```

---

## Your Product Data

Same structure for yourself—be honest:

```yaml

# ... same fields

strengths:

- [Your real strengths]

weaknesses:

- [Your honest weaknesses]

best_for:

- [Your ideal customers]

not_ideal_for:

- [Who should use something else]

```

---

## Page Generation

Each page pulls from centralized data:

- **[Competitor] Alternative page**: Pulls competitor data + your data

- **[Competitor] Alternatives page**: Pulls competitor data + your data + other alternatives

- **You vs [Competitor] page**: Pulls your data + competitor data

- **[A] vs [B] page**: Pulls both competitor data + your 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

---

## Index Page Structure

### Alternatives Index

**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**:

```markdown

## 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]

```

---

### Vs Comparisons Index

**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

---

### Index Page Best Practices

**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

---

## Footer Navigation

The site footer appears on all marketing pages, making it a powerful internal linking opportunity for competitor pages.

### Option 1: Link to Index Pages (Minimum)

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.

### Option 2: Footer Columns by Format (Recommended for SEO)

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

### Why Footer Links Matter

1. **Sitewide distribution**: Footer links appear on every marketing page, passing link equity from your entire site to comparison content

2. **Crawl efficiency**: Search engines discover all comparison pages quickly

3. **User discovery**: Visitors evaluating your product can easily find comparisons

4. **Competitive positioning**: Signals to search engines that you're a key player in the space

### Implementation Notes

- Update footer when adding new high-priority comparison pages

- Keep footer clean—don't list every comparison, just the top ones

- Match column headers to your URL structure (e.g., "vs" column → `/vs/` URLs)

- Consider mobile: columns may stack, so order by priority

mdskills/competitors/references/templates.md

5.3 kB

# Section Templates for Competitor Pages

Ready-to-use templates for each section of competitor comparison pages.

## Contents

- TL;DR Summary

- Paragraph Comparison (Not Just Tables)

- Feature Comparison Section

- Pricing Comparison Section

- Service & Support Comparison

- Who It's For Section

- Migration Section

- Social Proof Section

- Comparison Table Best Practices (beyond checkmarks, organize by category, include ratings where useful)

## TL;DR Summary

Start every page with a quick summary for scanners:

```markdown

**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].

```

---

## Paragraph Comparison (Not Just Tables)

For each major dimension, write a paragraph:

```markdown

## 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.

```

---

## Feature Comparison Section

Go beyond checkmarks:

```markdown

## 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 Comparison Section

```markdown

## 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 Comparison

```markdown

## 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 It's For Section

```markdown

## 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]

```

---

## Migration Section

```markdown

## Switching from [Competitor]

### What transfers

- [Data type]: [How easily, any caveats]

### What needs reconfiguration

- [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]

```

---

## Social Proof Section

Focus on switchers:

```markdown

## 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]

```

---

## Comparison Table Best Practices

### Beyond Checkmarks

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 |

### Organize by Category

Group features into meaningful categories:

- Core functionality

- Collaboration

- Integrations

- Security & compliance

- Support & service

### Include Ratings Where Useful

|----------|-----|-----------|-------|

| Ease of use | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | [Brief note] |

| Feature depth | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | [Brief note] |

mdskills/competitors/SKILL.md

8.1 kB

---

description: "When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' 'competitive landing pages,' 'how do we compare to X,' 'battle card,' or 'competitor teardown.' Use this for any content that positions your product against competitors. Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. For sales-specific competitor docs, see sales-enablement."

metadata:

version: 2.0.0

---

# Competitor & Alternative Pages

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.

## Initial Assessment

**Check for product marketing context first:**

Before creating competitor pages, understand:

1. **Your Product**

- Core value proposition

- Key differentiators

- Ideal customer profile

- Pricing model

- Strengths and honest weaknesses

2. **Competitive Landscape**

- Direct competitors

- Indirect/adjacent competitors

- Market positioning of each

- Search volume for competitor terms

3. **Goals**

- SEO traffic capture

- Sales enablement

- Conversion from competitor users

- Brand positioning

---

## Core Principles

### 1. Honesty Builds Trust

- Acknowledge competitor strengths

- Be accurate about your limitations

- Don't misrepresent competitor features

- Readers are comparing—they'll verify claims

### 2. Depth Over Surface

- Go beyond feature checklists

- Explain *why* differences matter

- Include use cases and scenarios

- Show, don't just tell

### 3. Help Them Decide

- Different tools fit different needs

- Be clear about who you're best for

- Be clear about who competitor is best for

- Reduce evaluation friction

### 4. Modular Content Architecture

- Competitor data should be centralized

- Updates propagate to all pages

- Single source of truth per competitor

---

## Page Formats

### Format 1: [Competitor] Alternative (Singular)

**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

---

### Format 2: [Competitor] Alternatives (Plural)

**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.

---

### Format 3: You vs [Competitor]

**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

---

### Format 4: [Competitor A] vs [Competitor B]

**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.

---

## Essential Sections

### TL;DR Summary

Start every page with a quick summary for scanners—key differences in 2-3 sentences.

### Paragraph Comparisons

Go beyond tables. For each dimension, write a paragraph explaining the differences and when each matters.

### Feature Comparison

For each category: describe how each handles it, list strengths and limitations, give bottom line recommendation.

### Pricing Comparison

Include tier-by-tier comparison, what's included, hidden costs, and total cost calculation for sample team size.

### Who It's For

Be explicit about ideal customer for each option. Honest recommendations build trust.

### Migration Section

Cover what transfers, what needs reconfiguration, support offered, and quotes from customers who switched.

**For detailed templates**: See [references/templates.md](references/templates.md)

---

## Content Architecture

### Centralized Competitor Data

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](references/content-architecture.md)

---

## Research Process

### Deep Competitor Research

For each competitor, gather:

1. **Product research**: Sign up, use it, document features/UX/limitations

2. **Pricing research**: Current pricing, what's included, hidden costs

3. **Review mining**: G2, Capterra, TrustRadius for common praise/complaint themes

4. **Customer feedback**: Talk to customers who switched (both directions)

5. **Content research**: Their positioning, their comparison pages, their changelog

### Ongoing Updates

- **Quarterly**: Verify pricing, check for major feature changes

- **When notified**: Customer mentions competitor change

- **Annually**: Full refresh of all competitor data

---

## SEO Considerations

### Keyword Targeting

| 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] |

### Internal Linking

- Link between related competitor pages

- Link from feature pages to relevant comparisons

- Create hub page linking to all competitor content

### Schema Markup

Consider FAQ schema for common questions like "What is the best alternative to [Competitor]?"

---

## Output Format

### Competitor Data File

Complete competitor profile in YAML format for use across all comparison pages.

### Page Content

For each page: URL, meta tags, full page copy organized by section, comparison tables, CTAs.

### Page Set Plan

Recommended pages to create with priority order based on search volume.

---

## Task-Specific Questions

1. What are common reasons people switch to you?

2. Do you have customer quotes about switching?

3. What's your pricing vs. competitors?

4. Do you offer migration support?

---

## Related Skills

- **programmatic-seo**: For building competitor pages at scale

- **copywriting**: For writing compelling comparison copy

- **seo-audit**: For optimizing competitor pages

- **schema**: For FAQ and comparison schema

- **sales-enablement**: For internal sales collateral, decks, and objection docs

jsonskills/content-strategy/evals/evals.json

6.4 kB

{

"skill_name": "content-strategy",

"evals": [

{

"id": 1,

"prompt": "Help me build a content strategy for our B2B SaaS product. We sell expense management software to finance teams at companies with 50-500 employees. We currently have no blog and want to start from scratch.",

"expected_output": "Should check for product-marketing.md first. Should establish content pillars (3-5 core topic areas). Should map content types by buyer stage (awareness → consideration → decision → implementation). Should identify keyword research opportunities by buyer stage. Should recommend a mix of searchable (SEO-driven) and shareable (thought leadership, data) content. Should use the prioritization scoring framework (customer impact 40%, content-market fit 30%, search potential 20%, resources 10%). Should provide an initial content calendar or publishing cadence. Should recommend content types appropriate for starting from scratch.",

"assertions": [

"Checks for product-marketing.md",

"Establishes 3-5 content pillars",

"Maps content by buyer stage (awareness through implementation)",

"Includes keyword research by buyer stage",

"Recommends mix of searchable and shareable content",

"Uses prioritization scoring framework",

"Provides publishing cadence or calendar",

"Recommends appropriate starting content types"

"files": []

{

"id": 2,

"prompt": "We have 200+ blog posts but traffic has been flat for a year. Our content feels random — no clear strategy. How do we fix this?",

"expected_output": "Should diagnose the 'random content' problem. Should recommend a content audit process to evaluate existing posts. Should introduce content pillars and topical clustering to organize the existing library. Should identify hub-and-spoke opportunities from existing content. Should recommend which posts to update, consolidate, or retire. Should use the prioritization framework to plan next steps. Should address topical authority building through clusters.",

"assertions": [

"Diagnoses the 'random content' problem",

"Recommends content audit for existing posts",

"Introduces content pillars and topical clustering",

"Identifies hub-and-spoke opportunities",

"Recommends update, consolidate, or retire decisions",

"Uses prioritization framework",

"Addresses topical authority building"

"files": []

{

"id": 3,

"prompt": "what kind of content should we be creating? we're a developer tool (API testing platform) and our audience is backend developers and QA engineers",

"expected_output": "Should trigger on casual phrasing. Should recommend content types appropriate for a developer audience: technical tutorials, documentation-style guides, use-case content, template/example libraries, data-driven benchmarks. Should note that developer audiences prefer depth, accuracy, and practical value over marketing fluff. Should suggest content pillars aligned with developer interests. Should use the ideation sources framework (keyword data, community forums like Stack Overflow/Reddit, competitor gaps).",

"assertions": [

"Triggers on casual phrasing",

"Recommends content types for developer audience",

"Emphasizes technical depth and practical value",

"Notes developers prefer substance over marketing",

"Suggests content pillars for developer tool",

"Uses ideation sources framework",

"Mentions developer community channels"

"files": []

{

"id": 4,

"prompt": "How should we prioritize which content to create first? We have a list of 50 blog post ideas but limited resources — one content marketer writing 2 posts per week.",

"expected_output": "Should apply the prioritization scoring framework: customer impact (40%), content-market fit (30%), search potential (20%), resources required (10%). Should help score or rank the content ideas using this framework. Should recommend focusing on high-impact, lower-effort content first. Should consider the buyer stage distribution (don't write only top-of-funnel). Should provide a practical workflow for the single content marketer to use going forward.",

"assertions": [

"Applies prioritization scoring framework with weights",

"Explains each scoring dimension",

"Recommends focusing on high-impact, lower-effort first",

"Considers buyer stage distribution",

"Provides practical workflow for limited resources"

"files": []

{

"id": 5,

"prompt": "We want to build topical authority in 'employee engagement.' What does a content cluster look like for this topic?",

"expected_output": "Should apply the hub-and-spoke content cluster model. Should design a pillar page for 'employee engagement' (comprehensive, 3000+ word guide). Should identify 8-15 supporting spoke articles targeting long-tail keywords related to employee engagement. Should map the internal linking structure between hub and spokes. Should address keyword research for the cluster. Should recommend content types for each piece (guide, how-to, template, data-driven, etc.).",

"assertions": [

"Applies hub-and-spoke content cluster model",

"Designs a pillar page for the core topic",

"Identifies 8-15 supporting spoke articles",

"Maps internal linking between hub and spokes",

"Addresses keyword research for the cluster",

"Recommends content types for each piece"

"files": []

{

"id": 6,

"prompt": "Can you write a blog post about remote work best practices for our HR software blog?",

"expected_output": "Should recognize this is a copywriting/content creation task, not a content strategy task. Should defer to or cross-reference the copywriting skill for writing individual pieces of content. May provide strategic context (where this fits in the content strategy, keyword targeting, audience) but should make clear that copywriting is the right skill for writing the actual content.",

"assertions": [

"Recognizes this as content creation, not strategy",

"References or defers to copywriting skill",

"Does not attempt to write the full blog post",

"May provide strategic context for the piece"

"files": []

}

]

}

mdskills/content-strategy/references/headless-cms.md

8.2 kB

# Headless CMS Guide

Reference for choosing, modeling, and implementing a headless CMS for marketing content.

## When to Use This Reference

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.

---

## Headless vs Traditional CMS

A headless CMS separates content management from presentation. Content is stored in a structured backend and delivered via API to any frontend.

### When Headless Makes Sense

- Multiple frontends consume the same content (web, mobile, email)

- Developers want full control over the frontend stack

- Content needs to be reused across channels

- You're building with a modern framework (Next.js, Remix, Astro)

- Marketing needs structured, reusable content blocks

### When Traditional Works Better

- Small team with no dedicated developers

- Simple blog or brochure site

- WYSIWYG editing is a hard requirement

- Budget is tight and WordPress/Webflow does the job

### Decision Checklist

| 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 |

---

## Content Modeling for Marketing

### Core Principles

1. **Think in types, not pages.** A "Landing Page" is a content type with fields — not an HTML file. This lets you reuse components across pages.

2. **Separate content from presentation.** Store the headline text, not the styled headline. Presentation belongs in the frontend.

3. **Design for reuse.** If testimonials appear on 5 pages, create a Testimonial type and reference it — don't duplicate.

4. **Keep models flat.** Deeply nested structures are hard to query and maintain. Prefer references over nesting.

### Common Marketing Content Types

| 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 |

### SEO Fields Checklist

Every page-level content type needs:

- `metaTitle` — 50-60 characters

- `metaDescription` — 150-160 characters

- `ogImage` — 1200x630px social preview

- `slug` — URL path segment

- `canonicalUrl` — optional override

- `noIndex` — boolean for excluding from search

- `structuredData` — optional JSON-LD override

---

## Editorial Workflows

### Draft → Review → Publish Cycle

1. **Draft** — Author creates or edits content

2. **Review** — Editor reviews for accuracy, brand voice, SEO

3. **Approve** — Stakeholder signs off

4. **Schedule** — Set publish date/time

5. **Publish** — Content goes live via API

### Preview APIs

All major headless CMS platforms support draft previews:

- **Sanity**: Real-time preview with `useLiveQuery` or Presentation tool

- **Contentful**: Preview API (`preview.contentful.com`) with separate access token

- **Strapi**: Draft & Publish system with `status=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.

### Roles and Permissions

|------|:----------:|:--------:|:-----------:|:----------:|

| 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.

---

## Platform Comparison

|---------|--------|------------|--------|

### Sanity

**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.

### Contentful

**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.

### Strapi

**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.

### Others Worth Knowing

- **Hygraph** — GraphQL-native, strong for federation and multi-source content

- **Keystatic** — Git-based, good for developer-content hybrid workflows

- **Payload** — TypeScript-first, self-hosted, code-configured like Sanity

- **Builder.io** — Visual editor with headless backend, good for non-technical marketers

- **Prismic** — Slice-based content modeling, strong Next.js integration

---

## Integration with Marketing Skills

### Programmatic SEO

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.

### Copywriting

CMS content models enforce consistent structure. Define fields that match your copy frameworks (headline, subheadline, social proof, CTA). See **copywriting** skill.

### Site Architecture

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.

### Email Sequences

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.

---

## Implementation Checklist

- [ ] Define content types based on page types and reusable blocks

- [ ] Add SEO fields to every page-level content type

- [ ] Set up preview/draft mode in your frontend

- [ ] Configure roles and permissions for your team

- [ ] Create sample content for each type before building frontend

- [ ] Set up webhook notifications for content changes (rebuild triggers)

- [ ] Document content guidelines for editors (field descriptions, character limits)

- [ ] Test content delivery performance (CDN, caching, ISR)

- [ ] Plan migration strategy if moving from existing CMS

---

## Relevant Integration Guides

- [Sanity](../../../tools/integrations/sanity.md) — GROQ queries, mutations, CLI

- [Contentful](../../../tools/integrations/contentful.md) — Delivery/Management APIs, publishing

- [Strapi](../../../tools/integrations/strapi.md) — REST CRUD, filters, document API

mdskills/content-strategy/SKILL.md

12 kB

---

description: 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 strategy," "topic clusters," "content planning," "editorial calendar," "content marketing," "content roadmap," "what content should I create," "blog topics," "content pillars," or "I don't know what to write." Use this whenever someone needs help deciding what content to produce, not just writing it. For writing individual pieces, see copywriting. For SEO-specific audits, see seo-audit. For social media content specifically, see social.

metadata:

version: 2.0.0

---

# Content Strategy

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.

## Before Planning

**Check for product marketing context first:**

Gather this context (ask if not provided):

### 1. Business Context

- What does the company do?

- Who is the ideal customer?

- What's the primary goal for content? (traffic, leads, brand awareness, thought leadership)

- What problems does your product solve?

### 2. Customer Research

- What questions do customers ask before buying?

- What objections come up in sales calls?

- What topics appear repeatedly in support tickets?

- What language do customers use to describe their problems?

### 3. Current State

- Do you have existing content? What's working?

- What resources do you have? (writers, budget, time)

- What content formats can you produce? (written, video, audio)

### 4. Competitive Landscape

- Who are your main competitors?

- What content gaps exist in your market?

---

## Searchable vs Shareable

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.

### When Writing Searchable Content

- Target a specific keyword or question

- Match search intent exactly—answer what the searcher wants

- Use clear titles that match search queries

- Structure with headings that mirror search patterns

- Place keywords in title, headings, first paragraph, URL

- Provide comprehensive coverage (don't leave questions unanswered)

- Include data, examples, and links to authoritative sources

- Optimize for AI/LLM discovery: clear positioning, structured content, brand consistency across the web

### When Writing Shareable Content

- Lead with a novel insight, original data, or counterintuitive take

- Challenge conventional wisdom with well-reasoned arguments

- Tell stories that make people feel something

- Create content people want to share to look smart or help others

- Connect to current trends or emerging problems

- Share vulnerable, honest experiences others can learn from

---

## Content Types

### Searchable Content Types

**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

### Shareable Content Types

**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 and Topic Clusters

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.

### How to Identify Pillars

1. **Product-led**: What problems does your product solve?

2. **Audience-led**: What does your ICP need to learn?

3. **Search-led**: What topics have volume in your space?

4. **Competitor-led**: What are competitors ranking for?

### Pillar Structure

```

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

```

### Pillar Criteria

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

---

## Keyword Research by Buyer Stage

Map topics to the buyer's journey using proven keyword modifiers:

### Awareness Stage

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"

### Consideration Stage

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"

### Decision Stage

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"

### Implementation Stage

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]"

---

## Content Ideation Sources

### 1. Keyword Data

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:

### 2. Call Transcripts

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.

### 3. Survey Responses

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)

### 4. Forum Research

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.

### 5. Competitor Analysis

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

### 6. Sales and Support Input

Extract from customer-facing teams:

- Common objections

- Repeated questions

- Support ticket patterns

- Success stories

- Feature requests and underlying problems

---

## Prioritizing Content Ideas

Score each idea on four factors:

### 1. Customer Impact (40%)

- How frequently did this topic come up in research?

- What percentage of customers face this challenge?

- How emotionally charged was this pain point?

- What's the potential LTV of customers with this need?

### 2. Content-Market Fit (30%)

- Does this align with problems your product solves?

- Can you offer unique insights from customer research?

- Do you have customer stories to support this?

- Will this naturally lead to product interest?

### 3. Search Potential (20%)

- What's the monthly search volume?

- How competitive is this topic?

- Are there related long-tail opportunities?

- Is search interest growing or declining?

### 4. Resource Requirements (10%)

- Do you have expertise to create authoritative content?

- What additional research is needed?

- What assets (graphics, data, examples) will you need?

### Scoring Template

|------|----------------------|-------------------------|----------------------|-----------------|-------|

| Topic A | 8 | 9 | 7 | 6 | 8.0 |

| Topic B | 6 | 7 | 9 | 8 | 7.1 |

---

## Output Format

When creating a content strategy, provide:

### 1. Content Pillars

- 3-5 pillars with rationale

- Subtopic clusters for each pillar

- How pillars connect to product

### 2. Priority Topics

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)

### 3. Topic Cluster Map

Visual or structured representation of how content interconnects.

---

## Task-Specific Questions

1. What patterns emerge from your last 10 customer conversations?

2. What questions keep coming up in sales calls?

3. Where are competitors' content efforts falling short?

4. What unique insights from customer research aren't being shared elsewhere?

5. Which existing content drives the most conversions, and why?

---

## References

- **[Headless CMS Guide](references/headless-cms.md)**: CMS selection, content modeling for marketing, editorial workflows, platform comparison (Sanity, Contentful, Strapi)

---

## Related Skills

- **copywriting**: For writing individual content pieces

- **seo-audit**: For technical SEO and on-page optimization

- **ai-seo**: For optimizing content for AI search engines and getting cited by LLMs

- **programmatic-seo**: For scaled content generation

- **site-architecture**: For page hierarchy, navigation design, and URL structure

- **emails**: For email-based content

- **social**: For social media content

jsonskills/copy-editing/evals/evals.json

7.4 kB

{

"skill_name": "copy-editing",

"evals": [

{

"id": 1,

"prompt": "Edit this homepage copy for us: 'Welcome to CloudSync! We are very excited to offer you an innovative, cutting-edge platform that seamlessly integrates with your existing tools. Our powerful solution helps businesses of all sizes optimize their workflows and drive meaningful results. Get started today and experience the difference!'",

"expected_output": "Should check for product-marketing.md first. Should apply the Seven Sweeps Framework systematically. Sweep 1 (Clarity): identify vague language ('optimize workflows,' 'drive meaningful results,' 'experience the difference'). Sweep 2 (Voice & Tone): flag 'Welcome to' as weak opening, 'we are very excited' as company-focused. Sweep 3 (So What): question what specific value is being offered. Sweep 4 (Prove It): note no proof points, stats, or evidence. Sweep 5 (Specificity): flag 'businesses of all sizes,' 'existing tools,' 'powerful solution' as generic. Sweep 6 (Heightened Emotion): assess emotional impact. Sweep 7 (Zero Risk): check for trust signals. Should provide a rewritten version addressing all issues.",

"assertions": [

"Checks for product-marketing.md",

"Applies Seven Sweeps Framework",

"Identifies vague language (Clarity sweep)",

"Flags weak opening and company-focused language (Voice & Tone sweep)",

"Questions missing value proposition (So What sweep)",

"Notes missing proof points (Prove It sweep)",

"Flags generic terms (Specificity sweep)",

"Provides a rewritten version"

"files": []

{

"id": 2,

"prompt": "Quick edit on this CTA section: 'Ready to take your business to the next level? Our team of dedicated professionals is standing by to help you achieve your goals. Click here to learn more about how we can help you succeed.'",

"expected_output": "Should apply the quick-pass editing checks. Should identify: 'take your business to the next level' (cliché), 'team of dedicated professionals' (filler), 'standing by' (passive), 'click here' (weak CTA), 'learn more' (vague action), 'help you succeed' (generic). Should apply word-level, sentence-level, and paragraph-level checks. Should rewrite with specific value prop, active voice, and strong action-oriented CTA. Should be concise since this was requested as a 'quick edit.'",

"assertions": [

"Identifies clichés and filler phrases",

"Flags 'click here' and 'learn more' as weak",

"Applies word-level and sentence-level checks",

"Rewrites with specific value and strong CTA",

"Uses active voice in rewrite",

"Keeps response concise for a quick edit"

"files": []

{

"id": 3,

"prompt": "edit this product description, it feels too long and wordy: 'Our comprehensive project management solution provides teams with a robust set of tools that enable them to efficiently plan, execute, and monitor their projects from start to finish. With our intuitive interface, powerful analytics dashboard, and seamless integration capabilities, you can ensure that every aspect of your project is managed with precision and care. Whether you're a small startup or a large enterprise, our platform scales to meet your unique needs and requirements, helping you deliver projects on time and within budget every single time.'",

"expected_output": "Should trigger on casual phrasing. Should apply the Clarity and Specificity sweeps primarily. Should identify: redundancy ('plan, execute, and monitor' overlaps with 'from start to finish'), filler words ('comprehensive,' 'robust,' 'efficiently,' 'seamless,' 'unique'), hedge phrases ('ensuring every aspect,' 'with precision and care'), and generic claims ('scales to meet your needs,' 'on time and within budget every single time'). Should cut the copy significantly (probably by 50%+). Should provide a tighter rewrite that says the same thing in fewer, more specific words.",

"assertions": [

"Triggers on casual phrasing",

"Identifies redundancy in the copy",

"Identifies filler words and hedge phrases",

"Identifies generic claims",

"Cuts copy significantly (50%+ reduction)",

"Provides tighter rewrite with specific language"

"files": []

{

"id": 4,

"prompt": "Review this testimonial section and improve it: 'CloudSync is great! It really helped our company. The team was very responsive and the product works well. We would recommend it to anyone looking for a solution. - John S., CEO'",

"expected_output": "Should apply the Prove It and Specificity sweeps. Should identify the testimonial as too vague to be persuasive ('great,' 'really helped,' 'works well,' 'anyone looking for a solution'). Should recommend replacing with specific results ('reduced project delivery time by 30%'), specific context ('team of 45 engineers'), and specific outcomes. Should suggest questions to ask the customer for a better testimonial. Should not fabricate specific numbers but should provide a template showing what a strong testimonial looks like.",

"assertions": [

"Applies Prove It and Specificity sweeps",

"Identifies testimonial as too vague",

"Recommends specific results and context",

"Suggests questions to get better testimonial",

"Does not fabricate specific numbers",

"Provides template for strong testimonial"

"files": []

{

"id": 5,

"prompt": "I need you to apply the 'So What' and 'Zero Risk' sweeps to this pricing page copy: 'Our Pro plan includes unlimited projects, advanced reporting, priority support, and custom integrations. Starting at $99/month.'",

"expected_output": "Should apply specifically the So What and Zero Risk sweeps as requested. So What: for each feature, ask 'so what does this mean for the customer?' — unlimited projects (what does that enable?), advanced reporting (what decisions can they make?), priority support (what does that mean in practice? response time?), custom integrations (which ones? what workflow does it enable?). Zero Risk: identify missing trust signals — no guarantee, no trial mention, no social proof near pricing, no 'cancel anytime' assurance. Should provide rewritten copy addressing both sweeps.",

"assertions": [

"Applies So What sweep to each feature",

"Translates features to customer benefits",

"Applies Zero Risk sweep",

"Identifies missing trust signals",

"Suggests guarantee, trial, or cancel-anytime language",

"Provides rewritten copy addressing both sweeps"

"files": []

{

"id": 6,

"prompt": "Write fresh homepage copy for our new product. We're launching a CRM for real estate agents.",

"expected_output": "Should recognize this is a copywriting-from-scratch task, not copy editing. Should defer to or cross-reference the copywriting skill, which handles writing new copy from scratch. Copy-editing is specifically for improving existing copy. Should make this distinction clear.",

"assertions": [

"Recognizes this as writing new copy, not editing existing copy",

"References or defers to copywriting skill",

"Explains that copy-editing is for improving existing copy",

"Does not attempt to write full page copy from scratch"

"files": []

}

]

}

mdskills/copy-editing/references/content-refresh.md

2.2 kB

# Content Refresh Editing

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.

## When to Refresh

- **Traffic declining** on a page that used to perform well

- **Stats or data** are more than 12 months old

- **Product has changed** — features, pricing, or positioning no longer match

- **Competitors updated** their version of the same content

- **AI search visibility** matters — outdated content gets cited less (see ai-seo skill)

## Content Refresh Checklist

1. **Freshness pass** — Update all dates, stats, and examples. Replace "in 2024" with current data. Remove references to deprecated features or tools.

2. **Accuracy pass** — Verify all claims are still true. Check that linked resources still exist. Confirm pricing and feature descriptions match current state.

3. **Voice pass** — Does the tone match your current brand voice? Older content often reflects an earlier stage of the company.

4. **SEO pass** — Has search intent shifted for this topic? Are there new keywords or questions to address? Add "Last updated: [date]" prominently.

5. **Proof pass** — Can you add newer testimonials, case studies, or data points that didn't exist when this was first published?

6. **Structure pass** — Add comparison tables, FAQ sections, or other scannable formats that make the content easier to consume.

## Refresh vs. Rewrite

| 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 |

## Refresh Cadence

- **Pricing and product pages**: Every quarter, or when pricing/features change

- **High-traffic blog posts**: Every 6 months

- **Comparison and alternatives pages**: Every 3-6 months (competitors change fast)

- **Evergreen guides**: Annually, unless traffic drops sooner

- **Low-traffic pages**: Only when traffic data suggests an opportunity

mdskills/copy-editing/references/plain-english-alternatives.md

8.1 kB

# Plain English Alternatives

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

---

## Contents

- A

- B

- C

- D

- E

- F

- G-H

- I

- L-M

- N-O

- P

- R

- S

- T-U

- V-Z

- Phrases to Remove Entirely

## A

| 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 |

---

## B

| Complex | Plain Alternative |

|---------|-------------------|

| belated | late |

| beneficial | helpful, useful |

| bestow | give |

| by means of | by |

---

## C

| 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 |

---

## D

| 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 |

---

## E

| 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 |

---

## F

| 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 |

---

## G-H

| Complex | Plain Alternative |

|---------|-------------------|

| generate | produce, create |

| henceforth | from now on |

| hitherto | until now |

---

## I

| 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 |

---

## L-M

| 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 |

---

## N-O

| 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 |

---

## P

| 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 |

---

## R

| 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 |

---

## S

| 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 |

---

## T-U

| 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 |

---

## V-Z

| 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 |

---

## Phrases to Remove Entirely

These phrases often add nothing. Delete them:

- a total of

- absolutely

- actually

- all things being equal

- as a matter of fact

- at the end of the day

- at this moment in time

- basically

- currently (when "now" or nothing works)

- I am of the opinion that (use: I think)

- in due course (use: soon, or say when)

- in the final analysis

- it should be understood

- last but not least

- obviously

- of course

- quite

- really

- the fact of the matter is

- to all intents and purposes

- very

mdskills/copy-editing/SKILL.md

15 kB

---

description: "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 this better,' 'copy sweep,' 'tighten this up,' 'this reads awkwardly,' 'clean up this text,' 'too wordy,' 'sharpen the messaging,' 'refresh this content,' 'update this page,' 'this content is outdated,' or 'content audit.' Use this when the user already has copy and wants it improved or refreshed rather than rewritten from scratch. For writing new copy, see copywriting."

metadata:

version: 2.0.0

---

# Copy Editing

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.

## Core Philosophy

**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

---

## The Seven Sweeps Framework

Edit copy through seven sequential passes, each focusing on one dimension. After each sweep, loop back to check previous sweeps aren't compromised.

### Sweep 1: Clarity

**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.

---

### Sweep 2: Voice and Tone

**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.

---

### Sweep 3: So What

**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.

---

### Sweep 4: Prove It

**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.

---

### Sweep 5: Specificity

**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.

---

### Sweep 6: Heightened Emotion

**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.

---

### Sweep 7: Zero Risk

**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.

---

## Expert Panel Scoring

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.

### How It Works

1. **Assemble 3-5 expert personas** relevant to the copy type

2. **Each persona scores the copy 1-10** on their area of expertise

3. **Collect specific critiques** — not just scores, but what to fix

4. **Revise based on feedback** — address the lowest-scoring areas first

5. **Re-score after revisions** — iterate until all personas score 7+, with an average of 8+ across the panel

### Recommended Expert Panels

**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)

### Scoring Rubric

| 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. |

### When to Use

- **Always** for launch copy, pricing pages, and high-traffic landing pages

- **Recommended** for email sequences, sales pages, and ad copy

- **Optional** for blog posts, social content, and internal docs

- **Skip** for quick updates, minor edits, and low-stakes content

---

## Quick-Pass Editing Checks

Use these for faster reviews when a full seven-sweep process isn't needed.

### Word-Level Checks

**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")

### Sentence-Level Checks

- One idea per sentence

- Vary sentence length (mix short and long)

- Front-load important information

- Max 3 conjunctions per sentence

- No more than 25 words (usually)

### Paragraph-Level Checks

- One topic per paragraph

- Short paragraphs (2-4 sentences for web)

- Strong opening sentences

- Logical flow between paragraphs

- White space for scannability

---

## Copy Editing Checklist

For a final QA pass before delivering edits, work through the full checklist in [references/checklist.md](references/checklist.md) — covering all seven sweeps plus pre-start and final-check items.

---

## Common Copy Problems & Fixes

### Problem: Wall of Features

**Symptom:** List of what the product does without why it matters

**Fix:** Add "which means..." after each feature to bridge to benefits

### Problem: Corporate Speak

**Symptom:** "Leverage synergies to optimize outcomes"

**Fix:** Ask "How would a human say this?" and use those words

### Problem: Weak Opening

**Symptom:** Starting with company history or vague statements

**Fix:** Lead with the reader's problem or desired outcome

### Problem: Buried CTA

**Symptom:** The ask comes after too much buildup, or isn't clear

**Fix:** Make the CTA obvious, early, and repeated

### Problem: No Proof

**Symptom:** "Customers love us" with no evidence

**Fix:** Add specific testimonials, numbers, or case references

### Problem: Generic Claims

**Symptom:** "We help businesses grow"

**Fix:** Specify who, how, and by how much

### Problem: Mixed Audiences

**Symptom:** Copy tries to speak to everyone, resonates with no one

**Fix:** Pick one audience and write directly to them

### Problem: Feature Overload

**Symptom:** Listing every capability, overwhelming the reader

**Fix:** Focus on 3-5 key benefits that matter most to the audience

---

## Working with Copy Sweeps

When editing collaboratively:

1. **Run a sweep and present findings** - Show what you found, why it's an issue

2. **Recommend specific edits** - Don't just identify problems; propose solutions

3. **Request the updated copy** - Let the author make final decisions

4. **Verify previous sweeps** - After each round of edits, re-check earlier sweeps

5. **Repeat until clean** - Continue until a full sweep finds no new issues

This iterative process ensures each edit doesn't create new problems while respecting the author's ownership of the copy.

---

## References

- [Plain English Alternatives](references/plain-english-alternatives.md): Replace complex words with simpler alternatives

- [Content Refresh](references/content-refresh.md): Full checklist, refresh vs. rewrite matrix, and cadence guide

- [Copy Editing Checklist](references/checklist.md): Full QA checklist across all seven sweeps

---

## Content Refresh Editing

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](references/content-refresh.md)

---

## Task-Specific Questions

1. What's the goal of this copy? (Awareness, conversion, retention)

2. What action should readers take?

3. Are there specific concerns or known issues?

4. What proof/evidence do you have available?

5. Is this new copy or a refresh of existing content?

---

## Related Skills

- **copywriting**: For writing new copy from scratch (use this skill to edit after your first draft is complete)

- **cro**: For broader page optimization beyond copy

- **marketing-psychology**: For understanding why certain edits improve conversion

- **ab-testing**: For testing copy variations

---

## When to Use Each Skill

| 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 |

jsonskills/copywriting/evals/evals.json

7.9 kB

{

"skill_name": "copywriting",

"evals": [

{

"id": 1,

"prompt": "Write homepage copy for a SaaS tool that automates employee onboarding. Target audience is HR directors at mid-size companies (200-2000 employees). Main differentiator is that it integrates with all major HRIS systems and cuts onboarding time from 2 weeks to 2 days.",

"expected_output": "Should check for product-marketing.md first. Should write full page copy organized by section: Headline, Subheadline, CTA (above the fold), then Social Proof, Problem/Pain, Solution/Benefits, How It Works, Objection Handling, and Final CTA. Should follow copywriting principles: clarity over cleverness, benefits over features, specificity (use the '2 weeks to 2 days' stat), customer language. Headline should communicate core value proposition. CTAs should be action-oriented ('Start Free Trial' not 'Submit'). Should provide 2-3 headline alternatives with rationale. Should include annotations explaining key copy choices. Should include meta content (SEO page title and meta description).",

"assertions": [

"Checks for product-marketing.md",

"Writes full page copy organized by section",

"Includes Headline, Subheadline, and CTA above the fold",

"Includes Social Proof, Problem/Pain, Solution/Benefits, How It Works sections",

"Uses the '2 weeks to 2 days' specificity in copy",

"CTAs are action-oriented, not generic",

"Provides 2-3 headline alternatives with rationale",

"Includes annotations explaining copy choices",

"Includes meta content (SEO title and meta description)"

"files": []

{

"id": 2,

"prompt": "Rewrite this headline: 'An Innovative AI-Powered Platform for Streamlined Business Operations' — it's for a B2B SaaS tool that helps small businesses manage invoicing and payments.",

"expected_output": "Should identify problems: jargon ('innovative,' 'AI-powered,' 'streamlined,' 'business operations'), too vague, company language not customer language. Should apply copywriting principles — specificity over vagueness, benefits over features, customer language over company language. Should provide 2-3 alternative headlines using formulas like '{Achieve outcome} without {pain point}' or 'The {category} for {audience}'. Each alternative should include rationale. Should also suggest a subheadline that adds specificity.",

"assertions": [

"Identifies jargon in original headline",

"Identifies vagueness as a problem",

"Identifies company language vs customer language issue",

"Provides 2-3 alternative headlines",

"Alternatives use headline formulas from the skill",

"Each alternative includes rationale",

"Suggests a subheadline"

"files": []

{

"id": 3,

"prompt": "i need copy for my pricing page. we have three plans: starter ($29/mo), pro ($79/mo), business ($199/mo). it's a social media scheduling tool for marketers",

"expected_output": "Should trigger on the casual phrasing. Should ask or infer audience context. Should apply Pricing Page guidance: help visitors choose the right plan, address 'which is right for me?' anxiety, make recommended plan obvious. Should write plan names, descriptions, feature lists with benefit-oriented copy (not just feature names). Should include a page headline that addresses the pricing decision. CTAs should be specific per plan. Should handle objection handling (FAQ copy). Should provide alternatives for key elements.",

"assertions": [

"Triggers on casual phrasing",

"Applies Pricing Page guidance",

"Addresses 'which plan is right for me' anxiety",

"Makes recommended plan obvious",

"Writes benefit-oriented feature copy, not just feature names",

"Includes page headline",

"CTAs are specific per plan",

"Includes FAQ or objection handling copy",

"Provides alternatives for key elements"

"files": []

{

"id": 4,

"prompt": "Write copy for our About page. We're a 3-person startup that built a developer tool for database migrations. Founded because we kept losing data during migrations at our last jobs. Tone should be professional but human.",

"expected_output": "Should apply About Page guidance: tell the story of why you exist, connect mission to customer benefit, still include a CTA. Should adapt voice and tone to 'professional but human' as specified. Should tell the founder origin story authentically. Should connect the personal pain to the customer's pain. Should include a CTA even on the About page. Copy should follow style rules: active voice, confident, specific. Should NOT be overly corporate or generic.",

"assertions": [

"Applies About Page guidance",

"Tells the story of why the company exists",

"Connects mission to customer benefit",

"Includes a CTA",

"Adapts tone to professional but human",

"Uses the founder origin story",

"Connects personal pain to customer pain",

"Uses active voice",

"Avoids corporate jargon"

"files": []

{

"id": 5,

"prompt": "Can you improve this CTA? We currently have 'Learn More' on our feature page for our analytics dashboard product.",

"expected_output": "Should immediately identify 'Learn More' as a weak CTA per the guidelines. Should apply the CTA formula: [Action Verb] + [What They Get] + [Qualifier]. Should provide 2-3 strong alternatives like 'See the Dashboard in Action,' 'Start Your Free Trial,' or 'Explore Analytics Features.' Each alternative should include rationale and context for when it works best. Should also consider CTA hierarchy — whether this is a primary or secondary CTA, and suggest complementary CTAs if relevant.",

"assertions": [

"Identifies 'Learn More' as a weak CTA",

"Applies the CTA formula from the skill",

"Provides 2-3 strong alternatives",

"Each alternative includes rationale",

"Considers CTA hierarchy (primary vs secondary)",

"Suggests complementary CTAs"

"files": []

{

"id": 6,

"prompt": "Write me a 5-email welcome sequence for new trial users of our project management tool.",

"expected_output": "Should recognize this is an email copywriting task, not page copywriting. Should defer to or cross-reference the emails skill, which specifically handles email sequences, drip campaigns, and lifecycle emails. May provide brief general guidance but should make clear that emails is the right skill for this task.",

"assertions": [

"Recognizes this as email sequence work",

"References or defers to emails skill",

"Does not attempt to write a full email sequence using page copywriting patterns"

"files": []

{

"id": 7,

"prompt": "Review this copy and tell me what's wrong: 'We are extremely excited to announce our revolutionary, cutting-edge platform that will totally transform how businesses optimize their workflows! Sign up now!!'",

"expected_output": "Should apply the Quick Quality Check. Should identify: exclamation points (remove them), marketing buzzwords without substance ('revolutionary,' 'cutting-edge,' 'totally transform,' 'optimize'), passive/weak constructions ('we are excited to announce'), vague language ('workflows'). Should apply writing style rules: simple over complex, specific over vague, confident over qualified, show over tell. Should rewrite the copy following these principles. Should provide 2-3 alternatives.",

"assertions": [

"Identifies exclamation point overuse",

"Identifies marketing buzzwords without substance",

"Identifies vague language",

"Applies writing style rules",

"Rewrites the copy following principles",

"Provides alternatives",

"Result is specific, clear, and jargon-free"

"files": []

}

]

}

mdskills/copywriting/references/copy-frameworks.md

7.7 kB

# Copy Frameworks Reference

Headline formulas, page section types, and structural templates.

## Contents

- Headline Formulas (outcome-focused, problem-focused, audience-focused, differentiation-focused, proof-focused, additional formulas)

- Landing Page Section Types (core sections, supporting sections)

- Page Structure Templates (feature-heavy page, varied engaging page, compact landing page, enterprise/B2B landing page, product launch page)

- Section Writing Tips (problem section, benefits section, how it works section, testimonial selection)

## Headline Formulas

### Outcome-Focused

**{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

---

### Problem-Focused

**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.

---

### Audience-Focused

**{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

---

### Differentiation-Focused

**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

---

### Proof-Focused

**[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

---

### Additional Formulas

**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

---

## Landing Page Section Types

### Core Sections

**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)

---

### Supporting Sections

**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"

---

## Page Structure Templates

### Feature-Heavy Page (Weak)

```

1. Hero

2. Feature 1

3. Feature 2

4. Feature 3

5. Feature 4

6. CTA

```

This is a list, not a persuasive narrative.

---

### Varied, Engaging Page (Strong)

```

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.

---

### Compact Landing Page

```

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.

---

### Enterprise/B2B Landing Page

```

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.

---

### Product Launch Page

```

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.

---

## Section Writing Tips

### Problem Section

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

### Benefits Section

For each benefit, include:

- **Headline**: The outcome they get

- **Body**: How it works (1-2 sentences)

- **Proof**: Number, testimonial, or example (optional)

### How It Works Section

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

### Testimonial Selection

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!"

mdskills/copywriting/references/natural-transitions.md

5.6 kB

# Natural Transitions

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

---

## Contents

- Previewing Content Structure

- Introducing a New Topic

- Referring Back

- Moving Between Sections

- Indicating Addition

- Indicating Contrast

- Indicating Similarity

- Indicating Cause and Effect

- Giving Examples

- Emphasising Key Points

- Providing Evidence (neutral attribution, expert quotes, supporting claims)

- Summarising Sections

- Concluding Content

- Question-Based Transitions

- List Introductions

- Hedging Language

- Best Practice Guidelines

- Transitions to Avoid (AI Tells)

## Previewing Content Structure

Use to orient readers and set expectations:

- Here's what we'll cover...

- This guide walks you through...

- Below, you'll find...

- We'll start with X, then move to Y...

- First, let's look at...

- Let's break this down step by step.

- The sections below explain...

---

## Introducing a New Topic

- When it comes to X,...

- Regarding X,...

- Speaking of X,...

- Now let's talk about X.

- Another key factor is...

- X is worth exploring because...

---

## Referring Back

Use to connect ideas and reinforce key points:

- As mentioned earlier,...

- As we covered above,...

- Remember when we discussed X?

- Building on that point,...

- Going back to X,...

- Earlier, we explained that...

---

## Moving Between Sections

- Now let's look at...

- Next up:...

- Moving on to...

- With that covered, let's turn to...

- Now that you understand X, here's Y.

- That brings us to...

---

## Indicating Addition

- Also,...

- Plus,...

- On top of that,...

- What's more,...

- Another benefit is...

- Beyond that,...

- In addition,...

- There's also...

**Note:** Use "moreover" and "furthermore" sparingly. They can sound AI-generated when overused.

---

## Indicating Contrast

- However,...

- But,...

- That said,...

- On the flip side,...

- In contrast,...

- Unlike X, Y...

- While X is true, Y...

- Despite this,...

---

## Indicating Similarity

- Similarly,...

- Likewise,...

- In the same way,...

- Just like X, Y also...

- This mirrors...

- The same applies to...

---

## Indicating Cause and Effect

- So,...

- This means...

- As a result,...

- That's why...

- Because of this,...

- This leads to...

- The outcome?...

- Here's what happens:...

---

## Giving Examples

- For example,...

- For instance,...

- Here's an example:...

- Take X, for instance.

- Consider this:...

- A good example is...

- To illustrate,...

- Like when...

- Say you want to...

---

## Emphasising Key Points

- Here's the key takeaway:...

- The important thing is...

- What matters most is...

- Don't miss this:...

- Pay attention to...

- This is critical:...

- The bottom line?...

---

## Providing Evidence

Use when citing sources, data, or expert opinions:

### Neutral attribution

- According to [Source],...

- [Source] reports that...

- Research shows that...

- Data from [Source] indicates...

- A study by [Source] found...

### Expert quotes

- As [Expert] puts it,...

- [Expert] explains,...

- In the words of [Expert],...

- [Expert] notes that...

### Supporting claims

- This is backed by...

- Evidence suggests...

- The numbers confirm...

- This aligns with findings from...

---

## Summarising Sections

- To recap,...

- Here's the short version:...

- In short,...

- The takeaway?...

- So what does this mean?...

- Let's pull this together:...

- Quick summary:...

---

## Concluding Content

- Wrapping up,...

- The bottom line is...

- Here's what to do next:...

- To sum up,...

- Final thoughts:...

- Ready to get started?...

- Now it's your turn.

**Note:** Avoid "In conclusion" at the start of a paragraph. It's overused and signals AI writing.

---

## Question-Based Transitions

Useful for conversational tone and featured snippet optimization:

- So what does this mean for you?

- But why does this matter?

- How do you actually do this?

- What's the catch?

- Sound complicated? It's not.

- Wondering where to start?

- Still not sure? Here's the breakdown.

---

## List Introductions

For numbered lists and step-by-step content:

- Here's how to do it:

- Follow these steps:

- The process is straightforward:

- Here's what you need to know:

- Key things to consider:

- The main factors are:

---

## Hedging Language

For claims that need qualification or aren't absolute:

- may, might, could

- tends to, generally

- often, usually, typically

- in most cases

- it appears that

- evidence suggests

- this can help

- many experts believe

---

## Best Practice Guidelines

1. **Match tone to audience**: B2B content can be slightly more formal; B2C often benefits from conversational transitions

2. **Vary your transitions**: Repeating the same phrase gets noticed (and not in a good way)

3. **Don't over-signpost**: Trust your reader; every sentence doesn't need a transition

4. **Use for scannability**: Transitions at paragraph starts help skimmers navigate

5. **Keep it natural**: Read aloud; if it sounds forced, simplify

6. **Front-load key info**: Put the important word or phrase early in the transition

---

## Transitions to Avoid (AI Tells)

These phrases are overused in AI-generated content:

- "That being said,..."

- "It's worth noting that..."

- "At its core,..."

- "In today's digital landscape,..."

- "When it comes to the realm of..."

- "This begs the question..."

- "Let's delve into..."

See the seo-audit skill's `references/ai-writing-detection.md` for a complete list of AI writing tells.

mdskills/copywriting/SKILL.md

7.4 kB

---

description: 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," "improve this copy," "rewrite this page," "marketing copy," "headline help," "CTA copy," "value proposition," "tagline," "subheadline," "hero section copy," "above the fold," "this copy is weak," "make this more compelling," or "help me describe my product." Use this whenever someone is working on website text that needs to persuade or convert. For email copy, see emails. For popup copy, see popups. For editing existing copy, see copy-editing.

metadata:

version: 2.0.0

---

# Copywriting

You are an expert conversion copywriter. Your goal is to write marketing copy that is clear, compelling, and drives action.

## Before Writing

**Check for product marketing context first:**

Gather this context (ask if not provided):

### 1. Page Purpose

- What type of page? (homepage, landing page, pricing, feature, about)

- What is the ONE primary action you want visitors to take?

### 2. Audience

- Who is the ideal customer?

- What problem are they trying to solve?

- What objections or hesitations do they have?

- What language do they use to describe their problem?

### 3. Product/Offer

- What are you selling or offering?

- What makes it different from alternatives?

- What's the key transformation or outcome?

- Any proof points (numbers, testimonials, case studies)?

### 4. Context

- Where is traffic coming from? (ads, organic, email)

- What do visitors already know before arriving?

---

## Copywriting Principles

### Clarity Over Cleverness

If you have to choose between clear and creative, choose clear.

### Benefits Over Features

Features: What it does. Benefits: What that means for the customer.

### Specificity Over Vagueness

- Vague: "Save time on your workflow"

- Specific: "Cut your weekly reporting from 4 hours to 15 minutes"

### Customer Language Over Company Language

Use words your customers use. Mirror voice-of-customer from reviews, interviews, support tickets.

### One Idea Per Section

Each section should advance one argument. Build a logical flow down the page.

---

## Writing Style Rules

### Core Principles

1. **Simple over complex** — "Use" not "utilize," "help" not "facilitate"

2. **Specific over vague** — Avoid "streamline," "optimize," "innovative"

3. **Active over passive** — "We generate reports" not "Reports are generated"

4. **Confident over qualified** — Remove "almost," "very," "really"

5. **Show over tell** — Describe the outcome instead of using adverbs

6. **Honest over sensational** — Fabricated statistics or testimonials erode trust and create legal liability

### Quick Quality Check

- Jargon that could confuse outsiders?

- Sentences trying to do too much?

- Passive voice constructions?

- Exclamation points? (remove them)

- Marketing buzzwords without substance?

For thorough line-by-line review, use the **copy-editing** skill after your draft.

---

## Best Practices

### Be Direct

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.

### Use Rhetorical Questions

Questions engage readers and make them think about their own situation.

- "Hate returning stuff to Amazon?"

- "Tired of chasing approvals?"

### Use Analogies When Helpful

Analogies make abstract concepts concrete and memorable.

### Pepper in Humor (When Appropriate)

Puns and wit make copy memorable—but only if it fits the brand and doesn't undermine clarity.

---

## Page Structure Framework

### Above the Fold

**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](references/copy-frameworks.md)

**For natural transition phrases**: See [references/natural-transitions.md](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"

### Core Sections

| 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](references/copy-frameworks.md)

---

## CTA Copy Guidelines

**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"

---

## Page-Specific Guidance

### Homepage

- Serve multiple audiences without being generic

- Lead with broadest value proposition

- Provide clear paths for different visitor intents

### Landing Page

- Single message, single CTA

- Match headline to ad/traffic source

- Complete argument on one page

### Pricing Page

- Help visitors choose the right plan

- Address "which is right for me?" anxiety

- Make recommended plan obvious

### Feature Page

- Connect feature → benefit → outcome

- Show use cases and examples

- Clear path to try or buy

### About Page

- Tell the story of why you exist

- Connect mission to customer benefit

- Still include a CTA

---

## Voice and Tone

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

---

## Output Format

When writing copy, provide:

### Page Copy

Organized by section:

- Headline, Subheadline, CTA

- Section headers and body copy

- Secondary CTAs

### Annotations

For key elements, explain:

- Why you made this choice

- What principle it applies

### Alternatives

For headlines and CTAs, provide 2-3 options:

- Option A: [copy] — [rationale]

- Option B: [copy] — [rationale]

### Meta Content (if relevant)

- Page title (for SEO)

- Meta description

---

## Related Skills

- **copy-editing**: For polishing existing copy (use after your draft)

- **cro**: If page structure/strategy needs work, not just copy

- **emails**: For email copywriting

- **popups**: For popup and modal copy

- **ab-testing**: To test copy variations

jsonskills/cro/evals/evals.json

7.5 kB

{

"skill_name": "cro",

"evals": [

{

"id": 1,

"prompt": "Here's my SaaS landing page: https://example.com/product. We get about 5,000 visitors/month from Google Ads but only 1.2% convert to free trial signups. Can you help me figure out what's wrong?",

"expected_output": "Should check for product-marketing.md first. Should identify page type (landing page) and conversion goal (free trial signup). Should analyze across the CRO framework dimensions: value proposition clarity, headline effectiveness, CTA placement/copy/hierarchy, visual hierarchy, trust signals, objection handling, and friction points. Should provide recommendations organized as Quick Wins, High-Impact Changes, and Test Ideas. Should note the message match issue between Google Ads and landing page. Should provide 2-3 headline and CTA copy alternatives with rationale.",

"assertions": [

"Checks for product-marketing.md",

"Identifies page type as landing page",

"Identifies conversion goal as free trial signup",

"Analyzes value proposition clarity",

"Analyzes CTA placement and copy",

"Notes message match between ads and landing page",

"Output has Quick Wins section",

"Output has High-Impact Changes section",

"Output has Test Ideas section",

"Provides 2-3 headline or CTA alternatives"

"files": []

{

"id": 2,

"prompt": "Our pricing page has three tiers but nobody picks the middle one. 60% choose the cheapest plan and 30% bounce entirely. What should we change?",

"expected_output": "Should apply the Pricing Page CRO framework. Should address plan comparison clarity, recommended plan indication, and 'which plan is right for me?' anxiety. Should analyze whether the middle tier's value proposition is differentiated enough. Should recommend trust signals and social proof near pricing. Should suggest specific experiments like changing plan names, adjusting feature differentiation, adding an annual toggle, or highlighting the recommended plan visually. Output should include Quick Wins, High-Impact Changes, and Test Ideas sections.",

"assertions": [

"Applies Pricing Page CRO framework",

"Addresses recommended plan indication",

"Addresses 'which plan is right for me' anxiety",

"Analyzes middle tier differentiation",

"Suggests specific experiments",

"Output has Quick Wins section",

"Output has High-Impact Changes section",

"Output has Test Ideas section"

"files": []

{

"id": 3,

"prompt": "this page isn't converting. can you take a look? it's our homepage for a B2B project management tool",

"expected_output": "Should trigger on the casual 'this page isn't converting' phrasing. Should identify this as a Homepage CRO analysis. Should ask clarifying questions about current conversion rate, traffic sources, and conversion goal. Should apply the full CRO Analysis Framework starting with value proposition clarity. Should address the homepage-specific guidance: serving multiple audiences, leading with broadest value prop, and providing clear paths for different visitor intents. Should provide structured output with Quick Wins, High-Impact Changes, Test Ideas, and Copy Alternatives.",

"assertions": [

"Triggers on casual phrasing",

"Identifies as Homepage CRO",

"Asks about current conversion rate",

"Asks about traffic sources",

"Applies CRO Analysis Framework",

"Addresses serving multiple audiences",

"Addresses clear paths for different visitor intents",

"Output has structured sections"

"files": []

{

"id": 4,

"prompt": "We have a blog that gets 20k organic visits/month but almost nobody clicks through to our product. How do we get more conversions from blog readers?",

"expected_output": "Should apply the Blog Post CRO framework. Should recommend contextual CTAs matching content topics and inline CTAs at natural stopping points. Should analyze whether CTAs are relevant to the content topic or generic. Should suggest specific CTA placements: within content, end of post, sidebar, sticky bar. Should recommend testing different CTA formats (inline text links, banner cards, exit-intent). Should cross-reference copywriting skill for CTA copy improvement.",

"assertions": [

"Applies Blog Post CRO framework",

"Recommends contextual CTAs matching content",

"Recommends inline CTAs at natural stopping points",

"Suggests specific CTA placements",

"Suggests testing different CTA formats",

"Cross-references copywriting or related skill"

"files": []

{

"id": 5,

"prompt": "We redesigned our landing page and conversions dropped from 4.2% to 2.8%. Here's the new page. What went wrong?",

"expected_output": "Should approach this as a diagnostic CRO audit focused on what changed. Should systematically compare against the CRO framework dimensions to identify likely regression causes. Should check for common redesign mistakes: losing trust signals, weaker value proposition clarity, CTA hierarchy changes, added friction, broken message match with traffic sources. Should provide specific fixes organized by likely impact. Should recommend reverting high-risk changes while testing others.",

"assertions": [

"Approaches as diagnostic audit",

"Checks for lost trust signals",

"Checks for weakened value proposition",

"Checks for CTA hierarchy changes",

"Checks for added friction",

"Checks for broken message match with traffic sources",

"Provides fixes organized by impact",

"Recommends reverting high-risk changes"

"files": []

{

"id": 6,

"prompt": "Our signup form has too many fields and people keep abandoning it halfway through. Can you help optimize it?",

"expected_output": "Should recognize this is about signup form optimization, not general page CRO. Should defer to or cross-reference the signup skill, which specifically handles signup, registration, and account creation flows. May provide some general friction reduction advice but should make clear that signup is the right skill for this task.",

"assertions": [

"Recognizes this as signup flow optimization",

"References or defers to signup skill",

"Does not attempt full cro analysis on a form"

"files": []

{

"id": 7,

"prompt": "Review this feature page for our API monitoring tool. Most traffic comes from organic search for 'API monitoring tools'. We want them to start a free trial.",

"expected_output": "Should apply the Feature Page CRO framework: connect feature to benefit, show use cases and examples, clear path to try/buy. Should reference the experiments section and suggest prioritized test ideas for hero section, trust signals, and CTA variations. Should note the organic search traffic source and check for message match with search intent. Should cross-reference ab-testing skill for proper test implementation.",

"assertions": [

"Applies Feature Page CRO framework",

"Connects features to benefits",

"Suggests use cases and examples",

"Provides clear path to try/buy",

"Notes organic traffic source and search intent match",

"Suggests specific experiment hypotheses",

"Cross-references ab-testing skill"

"files": []

}

]

}

mdskills/cro/references/experiments.md

7.7 kB

# Page CRO Experiment Ideas

Comprehensive list of A/B tests and experiments organized by page type.

## Contents

- Homepage Experiments (Hero Section, Trust & Social Proof, Features & Content, Navigation & UX)

- Pricing Page Experiments (Price Presentation, Pricing UX, Objection Handling, Trust Signals)

- Demo Request Page Experiments (Form Optimization, Page Content, CTA & Routing)

- Resource/Blog Page Experiments (Content CTAs, Resource Section)

- Landing Page Experiments (Message Match, Conversion Focus, Page Length)

- Feature Page Experiments (Feature Presentation, Conversion Path)

- Cross-Page Experiments (Site-Wide Tests, Navigation Tests)

## Homepage Experiments

### Hero Section

| 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 |

### Trust & Social Proof

| 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 |

### Features & Content

| 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 |

### Navigation & UX

| 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 |

---

## Pricing Page Experiments

### Price Presentation

| 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" |

### Pricing UX

| 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 |

### Objection Handling

| 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 |

### Trust Signals

| 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 |

---

## Demo Request Page Experiments

### Form Optimization

| 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 |

### Page Content

| 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 |

### CTA & Routing

| 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 |

---

## Resource/Blog Page Experiments

### Content CTAs

| 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 |

### Resource Section

| 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 |

---

## Landing Page Experiments

### Message Match

| 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 |

### Conversion Focus

| 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 |

### Page Length

| 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 |

---

## Feature Page Experiments

### Feature Presentation

| 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 |

### Conversion Path

| 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 |

---

## Cross-Page Experiments

### Site-Wide Tests

| 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 |

### Navigation Tests

| Test | Hypothesis |

|------|------------|

| Menu structure | Information architecture |

| Search placement | Help visitors find content |

| CTA in nav | Always-visible conversion path |

| Breadcrumbs | Navigation clarity |

mdskills/cro/references/form.md

10 kB

# Form CRO

You are an expert in form optimization. Your goal is to maximize form completion rates while capturing the data that matters.

## Initial Assessment

**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:

1. **Form Type**

- Lead capture (gated content, newsletter)

- Contact form

- Demo/sales request

- Application form

- Survey/feedback

- Checkout form

- Quote request

2. **Current State**

- How many fields?

- What's the current completion rate?

- Mobile vs. desktop split?

- Where do users abandon?

3. **Business Context**

- What happens with form submissions?

- Which fields are actually used in follow-up?

- Are there compliance/legal requirements?

---

## Core Principles

### 1. Every Field Has a Cost

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?

### 2. Value Must Exceed Effort

- Clear value proposition above form

- Make what they get obvious

- Reduce perceived effort (field count, labels)

### 3. Reduce Cognitive Load

- One question per field

- Clear, conversational labels

- Logical grouping and order

- Smart defaults where possible

---

## Field-by-Field Optimization

### Email Field

- Single field, no confirmation

- Inline validation

- Typo detection (did you mean gmail.com?)

- Proper mobile keyboard

### Name Fields

- Single "Name" vs. First/Last — test this

- Single field reduces friction

- Split needed only if personalization requires it

### Phone Number

- Make optional if possible

- If required, explain why

- Auto-format as they type

- Country code handling

### Company/Organization

- Auto-suggest for faster entry

- Enrichment after submission (Clearbit, etc.)

- Consider inferring from email domain

### Job Title/Role

- Dropdown if categories matter

- Free text if wide variation

- Consider making optional

### Message/Comments (Free Text)

- Make optional

- Reasonable character guidance

- Expand on focus

### Dropdown Selects

- "Select one..." placeholder

- Searchable if many options

- Consider radio buttons if < 5 options

- "Other" option with text field

### Checkboxes (Multi-select)

- Clear, parallel labels

- Reasonable number of options

- Consider "Select all that apply" instruction

---

## Form Layout Optimization

### Field Order

1. Start with easiest fields (name, email)

2. Build commitment before asking more

3. Sensitive fields last (phone, company size)

4. Logical grouping if many fields

### Labels and Placeholders

- Labels: Keep visible (not just placeholder) — placeholders disappear when typing, leaving users unsure what they're filling in

- Placeholders: Examples, not labels

- Help text: Only when genuinely helpful

**Good:**

```

[name@company.com]

```

**Bad:**

```

[Enter your email address] ← Disappears on focus

```

### Visual Design

- Sufficient spacing between fields

- Clear visual hierarchy

- CTA button stands out

- Mobile-friendly tap targets (44px+)

### Single Column vs. Multi-Column

- Single column: Higher completion, mobile-friendly

- Multi-column: Only for short related fields (First/Last name)

- When in doubt, single column

---

## Multi-Step Forms

### When to Use Multi-Step

- More than 5-6 fields

- Logically distinct sections

- Conditional paths based on answers

- Complex forms (applications, quotes)

### Multi-Step Best Practices

- Progress indicator (step X of Y)

- Start with easy, end with sensitive

- One topic per step

- Allow back navigation

- Save progress (don't lose data on refresh)

- Clear indication of required vs. optional

### Progressive Commitment Pattern

1. Low-friction start (just email)

2. More detail (name, company)

3. Qualifying questions

4. Contact preferences

---

## Error Handling

### Inline Validation

- Validate as they move to next field

- Don't validate too aggressively while typing

- Clear visual indicators (green check, red border)

### Error Messages

- Specific to the problem

- Suggest how to fix

- Positioned near the field

- Don't clear their input

**Good:** "Please enter a valid email address (e.g., name@company.com)"

**Bad:** "Invalid input"

### On Submit

- Focus on first error field

- Summarize errors if multiple

- Preserve all entered data

- Don't clear form on error

---

## Submit Button Optimization

### Button Copy

Weak: "Submit" | "Send"

Strong: "[Action] + [What they get]"

Examples:

- "Get My Free Quote"

- "Download the Guide"

- "Request Demo"

- "Send Message"

- "Start Free Trial"

### Button Placement

- Immediately after last field

- Left-aligned with fields

- Sufficient size and contrast

- Mobile: Sticky or clearly visible

### Post-Submit States

- Loading state (disable button, show spinner)

- Success confirmation (clear next steps)

- Error handling (clear message, focus on issue)

---

## Trust and Friction Reduction

### Near the Form

- Privacy statement: "We'll never share your info"

- Security badges if collecting sensitive data

- Testimonial or social proof

- Expected response time

### Reducing Perceived Effort

- "Takes 30 seconds"

- Field count indicator

- Remove visual clutter

- Generous white space

### Addressing Objections

- "No spam, unsubscribe anytime"

- "We won't share your number"

- "No credit card required"

---

## Form Types: Specific Guidance

### Lead Capture (Gated Content)

- Minimum viable fields (often just email)

- Clear value proposition for what they get

- Consider asking enrichment questions post-download

- Test email-only vs. email + name

### Contact Form

- Essential: Email/Name + Message

- Phone optional

- Set response time expectations

- Offer alternatives (chat, phone)

### Demo Request

- Name, Email, Company required

- Phone: Optional with "preferred contact" choice

- Use case/goal question helps personalize

- Calendar embed can increase show rate

### Quote/Estimate Request

- Multi-step often works well

- Start with easy questions

- Technical details later

- Save progress for complex forms

### Survey Forms

- Progress bar essential

- One question per screen for engagement

- Skip logic for relevance

- Consider incentive for completion

---

## Mobile Optimization

- Larger touch targets (44px minimum height)

- Appropriate keyboard types (email, tel, number)

- Autofill support

- Single column only

- Sticky submit button

- Minimal typing (dropdowns, buttons)

---

## Measurement

### Key Metrics

- **Form start rate**: Page views → Started form

- **Completion rate**: Started → Submitted

- **Field drop-off**: Which fields lose people

- **Error rate**: By field

- **Time to complete**: Total and by field

- **Mobile vs. desktop**: Completion by device

### What to Track

- Form views

- First field focus

- Each field completion

- Errors by field

- Submit attempts

- Successful submissions

---

## Output Format

### Form Audit

For each issue:

- **Issue**: What's wrong

- **Impact**: Estimated effect on conversions

- **Fix**: Specific recommendation

- **Priority**: High/Medium/Low

### Recommended Form Design

- **Required fields**: Justified list

- **Optional fields**: With rationale

- **Field order**: Recommended sequence

- **Copy**: Labels, placeholders, button

- **Error messages**: For each field

- **Layout**: Visual guidance

### Test Hypotheses

Ideas to A/B test with expected outcomes

---

## Experiment Ideas

### Form Structure Experiments

**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

---

### Copy & Design Experiments

**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

---

### Form Type-Specific Experiments

**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

---

### Mobile & UX Experiments

- Larger touch targets for mobile

- Test appropriate keyboard types by field

- Sticky submit button on mobile

- Auto-focus first field on page load

- Test form container styling (card vs. minimal)

---

## Task-Specific Questions

1. What's your current form completion rate?

2. Do you have field-level analytics?

3. What happens with the data after submission?

4. Which fields are actually used in follow-up?

5. Are there compliance/legal requirements?

6. What's the mobile vs. desktop split?

---

## Related Skills

- **signup**: For account creation forms

- **popups**: For forms inside popups/modals

- **cro**: For the page containing the form

- **ab-testing**: For testing form changes

mdskills/cro/SKILL.md

6.0 kB

---

description: "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 user says 'CRO,' 'conversion rate optimization,' 'this page isn't converting,' 'improve conversions,' 'why isn't this page working,' 'my landing page sucks,' 'form abandonment,' 'nobody's converting,' 'low conversion rate,' or 'this page needs work.' Use this even if the user just shares a URL and asks for feedback. For signup/registration flows, see signup. For post-signup activation, see onboarding. For popups/modals, see popups."

metadata:

version: 2.0.0

---

# Conversion Rate Optimization (CRO)

You are a conversion rate optimization expert. Your goal is to analyze marketing pages and provide actionable recommendations to improve conversion rates.

## Initial Assessment

**Check for product marketing context first:**

Before providing recommendations, identify:

1. **Page Type**: Homepage, landing page, pricing, feature, blog, about, other

2. **Primary Conversion Goal**: Sign up, request demo, purchase, subscribe, download, contact sales

3. **Traffic Context**: Where are visitors coming from? (organic, paid, email, social)

---

## CRO Analysis Framework

Analyze the page across these dimensions, in order of impact:

### 1. Value Proposition Clarity (Highest 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

### 2. Headline Effectiveness

**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..."

### 3. CTA Placement, Copy, and Hierarchy

**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?

### 4. Visual Hierarchy and Scannability

**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?

### 5. Trust Signals and Social Proof

**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

### 6. Objection Handling

**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

### 7. Friction Points

**Look for:**

- Too many form fields

- Unclear next steps

- Confusing navigation

- Required information that shouldn't be required

- Mobile experience issues

- Long load times

---

## Output Format

Structure your recommendations as:

### Quick Wins (Implement Now)

Easy changes with likely immediate impact.

### High-Impact Changes (Prioritize)

Bigger changes that require more effort but will significantly improve conversions.

### Test Ideas

Hypotheses worth A/B testing rather than assuming.

### Copy Alternatives

For key elements (headlines, CTAs), provide 2-3 alternatives with rationale.

---

## Page-Specific Frameworks

### Homepage CRO

- Clear positioning for cold visitors

- Quick path to most common conversion

- Handle both "ready to buy" and "still researching"

### Landing Page CRO

- Message match with traffic source

- Single CTA (remove navigation if possible)

- Complete argument on one page

### Pricing Page CRO

- Clear plan comparison

- Recommended plan indication

- Address "which plan is right for me?" anxiety

### Feature Page CRO

- Connect feature to benefit

- Use cases and examples

- Clear path to try/buy

### Blog Post CRO

- Contextual CTAs matching content topic

- Inline CTAs at natural stopping points

---

## Experiment Ideas

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](references/experiments.md)

---

## Task-Specific Questions

1. What's your current conversion rate and goal?

2. Where is traffic coming from?

3. What does your signup/purchase flow look like after this page?

4. Do you have user research, heatmaps, or session recordings?

5. What have you already tried?

---

## Related Skills

- **signup**: If the issue is in the signup process itself

- **popups**: If considering popups as part of the strategy

- **copywriting**: If the page needs a complete copy rewrite

- **ab-testing**: To properly test recommended changes

---

## Form Optimization

For detailed form CRO guidance — including field optimization, multi-step forms, error handling, and form-specific experiments — see [references/form.md](references/form.md).

jsonskills/customer-research/evals/evals.json

11 kB

{

"skill_name": "customer-research",

"evals": [

{

"id": 1,

"prompt": "I have 20 customer interview transcripts. Help me analyze them.",

"expected_output": "Should check for product-marketing.md first. Should ask about the goal before analyzing (improve messaging, build personas, find product gaps, etc.). Should apply the extraction framework: jobs to be done, pain points, trigger events, desired outcomes, language/vocabulary, alternatives considered. Should recommend clustering by theme, frequency + intensity scoring, and identifying money quotes. Should ask which deliverable is needed.",

"assertions": [

"Checks for product-marketing.md",

"Asks about the goal before diving in (improve messaging, build personas, find gaps, etc.)",

"Mentions extracting jobs to be done, pain points, and desired outcomes",

"Suggests organizing quotes by theme",

"References frequency and intensity scoring",

"Asks which deliverable is needed"

"files": []

{

"id": 2,

"prompt": "I want to do ICP research but I don't have any customer interviews yet.",

"expected_output": "Should check for product-marketing.md first. Should recommend digital watering hole research as a starting point. Should mention Reddit, G2, Capterra, forums, or niche communities as sources. Should offer to plan a research approach and explain what to extract from online sources. Should note this is Mode 2 and ask what product/category to research.",

"assertions": [

"Checks for product-marketing.md",

"Recommends digital watering hole research as an alternative",

"Mentions Reddit, G2, or review sites as starting points",

"Asks what product or category to research",

"Offers to help extract insights from online sources"

"files": []

{

"id": 3,

"prompt": "Mine Reddit and G2 to understand what people hate about project management software.",

"expected_output": "Should check for product-marketing.md first. Should identify relevant subreddits (r/projectmanagement, r/productivity, r/agile) and search strategies. Should recommend reading 3-star and 1-star G2 reviews and competitor 4-star reviews. Should plan to extract verbatim quotes, pain themes, and switching triggers. Should apply the extraction table (source, quote, context, sentiment, theme tag, profile signals).",

"assertions": [

"Checks for product-marketing.md",

"Identifies relevant subreddits or search strategies for project management",

"Suggests reading 3-star and 1-star G2 reviews",

"Recommends competitor 4-star reviews for buried complaints",

"Plans to extract verbatim quotes and pain themes",

"Mentions what to look for: complaints, workarounds, switching triggers"

"files": []

{

"id": 4,

"prompt": "Build me a customer persona for a marketing manager at a B2B SaaS company.",

"expected_output": "Should check for product-marketing.md first. Should ask if there is existing research to build from before generating a persona. Should warn against inventing details without data. Should use the persona structure: profile, primary JTBD, trigger events, top pains, desired outcomes, objections, alternatives, key vocabulary, how to reach them. Should note that personas should be built from at least 5-10 data points.",

"assertions": [

"Checks for product-marketing.md",

"Asks if there is existing research to build from before inventing details",

"Warns against creating personas without data",

"Includes jobs to be done, pains, triggers, and desired outcomes in persona structure",

"Mentions the need to capture actual customer vocabulary",

"Notes minimum data threshold (5-10 data points)"

"files": []

{

"id": 5,

"prompt": "I have 6 months of customer support tickets. What insights can I pull from them?",

"expected_output": "Should check for product-marketing.md first. Should recommend categorizing tickets before analyzing (bugs vs. confusion vs. feature requests vs. expectation mismatches). Should warn against treating all tickets as equal signal. Should suggest extracting recurring language, patterns, and 'I wish it could…' phrases. Should ask about the goal — product improvement, messaging, reducing support load, or something else.",

"assertions": [

"Checks for product-marketing.md",

"Recommends categorizing tickets before analyzing (bugs vs confusion vs feature requests)",

"Warns against treating all tickets as equal signal",

"Mentions extracting recurring language and patterns",

"Asks about the goal — product improvement, messaging, or something else"

"files": []

{

"id": 6,

"prompt": "What are customers saying about my competitors on review sites?",

"expected_output": "Should check for product-marketing.md first. Should ask which competitors to research. Should recommend G2 and Capterra as primary sources. Should specifically call out reading competitor 4-star reviews for buried complaints. Should describe what to extract: what they love (battlecard intel), what frustrates them (opportunities), unmet needs. Should use the review mining template.",

"assertions": [

"Checks for product-marketing.md",

"Recommends reading competitor 4-star reviews specifically for buried complaints",

"Mentions G2 or Capterra as sources",

"Describes what to extract: what they love, what frustrates them, unmet needs",

"Frames as competitive intelligence input"

"files": []

{

"id": 7,

"prompt": "Help me do voice of customer research for a new SaaS in the HR space.",

"expected_output": "Should check for product-marketing.md first. Should ask about the specific ICP segment within HR (recruiter, HR generalist, CHRO, etc.). Should suggest relevant digital watering holes: r/humanresources, r/recruiting, HR Slack communities, G2 HR category, LinkedIn. Should plan to extract verbatim language for copy use. Should offer to produce a VOC quote bank as a deliverable.",

"assertions": [

"Checks for product-marketing.md",

"Asks about target ICP segment within HR",

"Suggests relevant digital watering holes (subreddits, G2 categories, communities)",

"Plans to extract verbatim language for copy use",

"Mentions organizing findings into a VOC quote bank"

"files": []

{

"id": 8,

"prompt": "I want to understand why customers churn. I have exit survey results.",

"expected_output": "Should check for product-marketing.md first. Should recommend segmenting churn reasons before analyzing — do not average across different causes. Should suggest pairing open-ended responses with quantitative data. Should ask if win/loss interview data or support tickets are also available. Should apply confidence labels (high/med/low) based on sample size and source consistency.",

"assertions": [

"Checks for product-marketing.md",

"Recommends segmenting churn reasons before analyzing",

"Warns against averaging across different churn causes",

"Suggests pairing open-ended responses with quantitative data",

"Asks if win/loss interview data is also available"

"files": []

{

"id": 9,

"prompt": "Find the digital watering holes where DevOps engineers talk shop.",

"expected_output": "Should check for product-marketing.md first. Should identify specific relevant communities: r/devops, r/sysadmin, Hacker News, DevOps-focused Discord/Slack groups, LinkedIn, Stack Overflow. Should suggest what to search for in those communities. Should describe what signal to extract from each source type and reference source-guides.md for detailed playbooks.",

"assertions": [

"Checks for product-marketing.md",

"Mentions specific relevant communities (r/devops, Hacker News, LinkedIn, Discord)",

"Suggests what to search for in those communities",

"Describes what signal to extract from each source type"

"files": []

{

"id": 10,

"prompt": "Turn my customer research into messaging I can use on my homepage.",

"expected_output": "Should check for product-marketing.md first. Should extract VOC language and top themes before moving to copy. Should identify the highest-signal quotes and language patterns. Should produce a VOC summary or quote bank, then hand off to the copywriting skill for the actual copy writing step rather than writing homepage copy directly.",

"assertions": [

"Checks for product-marketing.md",

"Extracts the VOC language and themes first before jumping to copy",

"Identifies the highest-signal quotes for messaging",

"References the copywriting skill for the actual copy writing step"

"files": []

{

"id": 11,

"prompt": "I run a mobile fitness app and want to understand why users drop off after week 2.",

"expected_output": "Should check for product-marketing.md first. Should recognize this as a B2C research scenario. Should suggest B2C-appropriate sources: app store reviews (1-3 star), Reddit fitness communities, YouTube comment sections on fitness apps, TikTok/Instagram comments. Should also recommend in-app surveys and analyzing support tickets/reviews. Should frame around activation and habit formation research.",

"assertions": [

"Checks for product-marketing.md",

"Recognizes this as a B2C research scenario",

"Suggests app store reviews as a primary source",

"Mentions Reddit or community sources relevant to fitness/consumer apps",

"Frames around understanding drop-off triggers and desired outcomes"

"files": []

{

"id": 12,

"prompt": "I have no existing research and don't know who my best customers are yet.",

"expected_output": "Should check for product-marketing.md first. Should treat this as a bootstrap research scenario. Should recommend starting with hypothesis formation before gathering data. Should suggest a minimum viable research plan: 5-10 customer interviews + digital watering hole scan. Should provide interview recruiting tips and what questions to ask. Should warn against building personas before collecting any data.",

"assertions": [

"Checks for product-marketing.md",

"Recognizes this as a zero-research bootstrap scenario",

"Recommends forming hypotheses before gathering data",

"Suggests a minimum viable research plan (interviews + online sources)",

"Warns against building personas without any data"

"files": []

}

]

}

mdskills/customer-research/references/source-guides.md

16 kB

# Customer Research — Source Guides

Detailed, source-by-source playbooks for gathering customer intelligence from online watering holes.

---

## Reddit Research

### Finding the Right Subreddits

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](https://www.reddit.com/subreddits/search) 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

### Search Operators

```

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"

```

### What to Look For

**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

### Tools

- Reddit's native search (limited but fast)

- Google: `site:reddit.com [query]` (better results)

- Pullpush.io — search archived Reddit posts (good for older threads)

---

## G2 and Review Site Mining

### Your Own Product Reviews

Read in this order for maximum signal:

1. **3-star reviews** — these are the most honest. Customer liked it enough to stay but felt something was missing.

2. **1-star reviews** — understand the failure modes. Separate product issues from support/onboarding issues.

3. **5-star reviews** — extract the "what they love" language. These are your proof points.

4. **4-star reviews** — often contain "the only thing I wish…" buried in praise.

**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

### Competitor Reviews on G2

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.

### Review Mining Template

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…" |

---

## Indie Hackers and Product Hunt

### Indie Hackers

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.

### Product Hunt

**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

---

## Hacker News

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

---

## LinkedIn Research

### Posts and Comments

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

### Job Postings

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]"`

---

## YouTube Comments

### Finding High-Signal Videos

- Tutorial videos for problems your product solves

- "Best tools for X in [year]" roundup videos

- Competitor product demos and walkthroughs

**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

---

## Twitter / X Research

### Search Operators

```

"[competitor]" -filter:replies min_faves:10

"[problem keyword]" "anyone know" OR "recommend" OR "alternative"

"[category] is broken" OR "frustrated with [category]"

```

### What to Find

- Real-time complaints about competitors

- Practitioners discussing their stack

- Influencers/thought leaders your ICP follows (useful for distribution)

---

## Blog Post and Forum Research

### Comparison Content

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.

### Niche Communities

- **Slack communities**: Many industries have public or semi-public Slack groups. Search "[industry] Slack community".

- **Discord servers**: Growing for developer and creator communities.

- **Facebook Groups**: Still strong for SMB, e-commerce, agency, and coach/consultant ICP.

- **Circle/Mighty Networks communities**: Check if there are paid communities in your ICP's space.

---

## B2C and Consumer App Research

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.

### App Store Reviews (iOS App Store / Google Play)

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.

### Amazon Reviews (for physical products or software with Amazon presence)

Same priority order as app stores: 3-star reviews first.

**G2 analog for consumer SaaS**: Trustpilot, Sitejabber, and product-specific review aggregators.

### Reddit Consumer Communities

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]"`

### TikTok and Instagram Comments

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

### YouTube Comments (Consumer)

Same approach as B2B but different video types:

- "X app honest review" or "X app after 6 months"

- "Best [category] apps [year]" comparison videos

- Unboxing or "setup" videos for hardware/physical products

Comments on review videos are especially valuable — these are people actively in the consideration phase.

### Consumer Community Platforms

- **Facebook Groups**: Still dominant for many consumer verticals (parenting, fitness, local services, hobbies)

- **Discord servers**: Growing for gaming, creator tools, productivity, crypto, lifestyle communities

- **Nextdoor**: Useful for local service businesses

- **Quora**: Long-form questions reveal decision anxiety and evaluation criteria

---

## SparkToro (Audience Intelligence)

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.

### When to Use SparkToro vs. Manual Research

- **SparkToro first** when you need to understand where your ICP spends time, what content they consume, and which influencers they follow — it answers these questions in seconds with aggregated data

- **Manual research first** (Reddit, G2, communities) when you need raw language, exact quotes, emotional context, and the "why" behind behavior

- **Best together**: Use SparkToro to identify which podcasts, subreddits, and websites matter, then go mine those sources manually for voice-of-customer language

### Key Queries to Run

**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

### What to Extract

| 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 |

### Source Weighting

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")

### Limitations

- Free tier: 5 reports/month, shallow results (top 5–10)

- No public API — all research done through web interface

- Skews English-language, US-centric

- Shows what audiences do, not why — pair with qualitative sources

See [tools/integrations/sparktoro.md](../../../tools/integrations/sparktoro.md) for full tool details and pricing.

---

## Organizing Your Research

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.

---

## Source Reliability and Confidence Scoring

Not all sources carry equal weight. Use this guide when assigning confidence labels.

### Source Weighting

| 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 |

### Confidence Labels in Practice

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.

```

### Recency Window

- **Use as primary source**: Data from the last 12 months

- **Use with caution**: 12-24 months (product and market may have shifted)

- **Use only for baseline context**: 2+ years old

When a theme appears consistently across old and new data, that's a durable signal worth acting on.

mdskills/customer-research/SKILL.md

12 kB

---

description: When the user wants to conduct, analyze, or synthesize customer research. Use when the user mentions "customer research," "ICP research," "talk to customers," "analyze transcripts," "customer interviews," "survey analysis," "support ticket analysis," "voice of customer," "VOC," "build personas," "customer personas," "jobs to be done," "JTBD," "what do customers say," "what are customers struggling with," "Reddit mining," "G2 reviews," "review mining," "digital watering holes," "community research," "forum research," "competitor reviews," "customer sentiment," or "find out why customers churn/convert/buy." Use for both analyzing existing research assets AND gathering new research from online sources. For writing copy informed by research, see copywriting. For acting on research to improve pages, see cro.

metadata:

version: 2.0.0

---

# Customer Research

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.

## Before Starting

**Check for product marketing context first:**

---

## Two Modes of Research

### Mode 1: Analyze Existing Assets

You have raw research material (transcripts, surveys, reviews, tickets). Your job is to extract signal.

### Mode 2: Go Find Research

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.

---

## Mode 1: Analyzing Existing Research Assets

### Asset Types

**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

### Extraction Framework

For each asset, extract:

1. **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

2. **Pain Points** — what's frustrating, broken, or inadequate about their current situation?

- Prioritize pains mentioned unprompted and with emotional language

3. **Trigger Events** — what changed that made them seek a solution?

- Common triggers: team growth, new hire, missed target, embarrassing incident, competitor doing something

4. **Desired Outcomes** — what does success look like in their words?

- Capture exact quotes, not paraphrases

5. **Language and Vocabulary** — exact words and phrases customers use

- This is gold for copy. "We were drowning in spreadsheets" > "manual process inefficiency"

6. **Alternatives Considered** — what else did they look at or try?

- Includes doing nothing, hiring someone, or building internally

### Synthesis Steps

After extracting from individual assets:

1. **Cluster by theme** — group similar pains, outcomes, and triggers across assets

2. **Frequency + intensity scoring** — how often does a theme appear, and how strongly is it felt?

3. **Segment by customer profile** — do patterns differ by company size, role, use case, or tenure?

4. **Identify the "money quotes"** — 5-10 verbatim quotes that best represent each theme

5. **Flag contradictions** — where do customers say one thing but do another?

### Research Quality Guardrails

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.

---

## Mode 2: Digital Watering Hole Research

Online communities are where customers speak without a filter. The goal is to find authentic, unmoderated language about the problem space.

### Where to Look

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

### What to Extract from Each Source

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 |

### Research Synthesis Template

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]

**Implications**: What this means for messaging / product / positioning

### Theme 2: ...

```

---

## Persona Generation

Personas should be built from research, not invented. Don't create a persona until you have at least 5-10 data points (interviews, reviews, or community posts) from a consistent segment.

### Persona Structure

```

## [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]"

**How to Reach Them**

- Channels: [where they spend time]

- Content they consume: [formats, topics]

- Influencers/communities they trust: [specific names if known]

```

### Persona Anti-Patterns

- **Don't name them cutely** ("Marketing Mary") unless your team finds it helpful — it's often a distraction

- **Don't average across segments** — a persona that represents everyone represents no one

- **Don't invent details** — if you don't have data on something, leave it blank rather than filling it in

- **Revisit quarterly** — personas decay as your market and product evolve

---

## Deliverable Formats

Depending on what the user needs, offer:

1. **Research synthesis report** — themes, quotes, patterns, and implications

2. **VOC quote bank** — organized verbatim quotes by theme, for use in copy

3. **Persona document** — 1-3 personas built from the research

4. **Jobs-to-be-done map** — functional, emotional, and social jobs by segment

5. **Competitive intelligence summary** — what customers say about competitors vs. you

6. **Research gap analysis** — what you still don't know and how to find it

Ask the user which deliverable(s) they need before generating output.

---

## Questions to Ask Before Proceeding

If context is unclear:

1. **What's the goal?** Improve messaging? Build personas? Find product gaps? Understand churn?

2. **What do you already have?** (transcripts, surveys, tickets, G2 reviews, nothing)

3. **Who is the target segment?** (all customers, a specific tier, churned users, prospects who didn't buy)

4. **What's your product?** (if not in the product marketing context file)

5. **What do you want delivered?** (synthesis report, persona, quote bank, competitive intel)

Don't ask all five at once — lead with #1 and #2, then follow up as needed.

---

## Related Skills

| 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` |

jsonskills/directory-submissions/evals/evals.json

8.2 kB

{

"skill_name": "directory-submissions",

"evals": [

{

"id": 1,

"prompt": "We're launching our AI SaaS in 3 weeks. Help me plan all the directories we should submit to.",

"expected_output": "Should check for product-marketing.md first. Should run Phase 0 readiness assessment with the 9 questions before recommending submissions. Should reject submission if any of items 1-7 are 'no' (hard block) and explain why. Should recommend tier mix: Tier 1 flagship launch (~15 — Product Hunt as anchor, BetaList, HN Show HN, Fazier, DevHunt), Tier 2 startup/SaaS (~50), Tier 3 AI directories (~40 — TAAFT, Futurepedia, Toolify), Tier 4 MCP/agent if applicable. Should map the 3-week Product Hunt prep timeline to calendar dates. Should warn against submitting before destination pages exist. Should reference references/directory-list.md and references/positioning-variations.md. Should recommend the 10-in-30 reviews protocol for G2/Capterra. Should set day-30 and day-90 targets from the KPI table.",

"assertions": [

"Checks for product-marketing.md",

"Runs Phase 0 readiness assessment",

"Recommends tier mix appropriate to AI SaaS",

"Maps 3-week PH timeline to calendar dates",

"Names Product Hunt as anchor",

"Recommends 10-in-30 reviews protocol",

"Sets day-30 and day-90 KPI targets",

"References directory-list.md or positioning-variations.md"

"files": []

{

"id": 2,

"prompt": "Can I just copy-paste the same description into every directory?",

"expected_output": "Should refuse and explain Rule 3: positioning varies by directory type. Should explain AI engines penalize duplicate content — directories cross-referenced by Claude, ChatGPT, Perplexity will de-rank repetitive copy. Should explain different framing per surface: startup directories lead with outcome (audience is founders), SaaS directories lead with alternative framing (people search '[competitor] alternative'), AI directories lead with AI-first architecture, agent/MCP directories lead with the agent/MCP angle, B2B review sites lead with ROI + use case. Should recommend preparing distinct variants per tier: tagline under 10 words, 60-char short description, 150-word long description, 5-8 category tags. Should reference references/positioning-variations.md.",

"assertions": [

"Refuses the request",

"Cites Rule 3 (positioning varies by directory type)",

"Notes AI engines penalize duplicate content",

"Lists different framing per surface type",

"Specifies variant lengths (tagline, short, long)",

"References positioning-variations.md"

"files": []

{

"id": 3,

"prompt": "Should we pay for one of those directory submission services that submits to 200 directories for $99?",

"expected_output": "Should say no, citing 'What NOT to Do' rule 1: don't pay for directory submission services. Should explain the whole point is these are free — it's an afternoon of copy-paste. Should warn that mass-submission services typically submit to low-quality spam directories (DR under 10, no traffic, no editorial quality) which dilute the backlink profile and can trigger Google spam detection. Should recommend the alternative: manually submit to Tier 1-4 directories with appropriate positioning variants and tracker. Should reinforce that the value comes from quality directories with editorial standards, not raw volume.",

"assertions": [

"Refuses the service",

"Cites 'don't pay for submission services' rule",

"Warns about low-DR spam directories",

"Warns about Google spam penalty risk",

"Recommends manual submission to quality directories"

"files": []

{

"id": 4,

"prompt": "Walk me through how to launch on Product Hunt next month. We've never done it before.",

"expected_output": "Should apply the Product Hunt Deep Dive playbook. Should map the 3-week prep timeline: Day -21 to -14 (warm up hunter account, upvote and comment on 3 launches/day), Day -14 (create Upcoming page), Day -10 (optional book a hunter — trade not cash), Day -7 (draft launch-day assets: 1270x760 gallery images, tagline, 260-char description, first comment), Day -3 (email list warm-up), Day -1 (final check). Should explain launch day: launch at 12:01 AM Pacific Time on Tuesday/Wednesday/Thursday only, first 2 hours are everything (need 50+ supporters), post the first comment yourself, reply to every comment in under 30 minutes, share to multiple channels. Should warn never ask for upvotes — ask for feedback. Should warn don't DM strangers — community flags this. Should explain post-launch: write a launch recap blog post with numbers + lessons, cross-post to Indie Hackers, only submit to Show HN if there's a technical angle. Should note 80% of failed launches fail from no warm audience or asking for upvotes.",

"assertions": [

"Maps 3-week timeline with specific day markers",

"Notes 12:01 AM Pacific Time launch",

"Restricts to Tue/Wed/Thu",

"Emphasizes first 2 hours / 50+ supporters",

"Warns never ask for upvotes",

"Recommends asking for feedback",

"Warns against DMing strangers",

"Includes post-launch recap and cross-posting"

"files": []

{

"id": 5,

"prompt": "We want to list on G2 but we only have 4 customers right now. Worth doing?",

"expected_output": "Should explain G2 and Capterra listings are worthless without reviews — 10 reviews is the magic threshold for Grid appearance. Should recommend NOT submitting yet, or claim the listing but plan a review drive in parallel. Should explain the 10-in-30 protocol: identify 20 users who completed a meaningful action, send each a personal email with direct review URL (reduces friction ~70%), offer a modest thank-you ($25 Amazon gift card is allowed by G2/TrustRadius), follow up once after 5 days, target 50% conversion. Should note the Users Love Us badge is free (20 reviews at 4.0+) but Grid/Momentum/Index/Award badges require a paid G2 plan ($2,999+/year as of Summer 2025) — and recommend NOT spending on paid G2 in year one. Should mention G2 Summer report cutoff ~April 28 and Fall ~July 28. Should suggest waiting until ~10 users are realistic before submitting.",

"assertions": [

"Explains 10-review threshold for Grid",

"Recommends NOT submitting yet OR claim + plan review drive",

"Lays out 10-in-30 protocol",

"Notes incentive ($25 gift card) is allowed",

"Mentions Users Love Us badge requirements",

"Warns against paying for G2 plan in year one",

"Mentions Summer/Fall report cutoffs"

"files": []

{

"id": 6,

"prompt": "We submitted to 50 directories last week. Now what?",

"expected_output": "Should warn against treating submissions as the strategy. Should reference 'What NOT to Do' rule 11: don't over-index on launch spike. Flywheel is templates + alternatives + reviews + ongoing content. Should recommend verifying the dofollow status of acquired backlinks (curl -sIL | grep -i rel=). Should pivot to ongoing distribution: destination pages strategy (alternative pages converting 5-15%, use-case/ICP pages, template gallery if applicable, 'best of' listicles you write yourself, integration pages), GEO tactics for AI citation (single H1, FAQ schema, comparison tables, get cited on Reddit/HN, claim Crunchbase/LinkedIn/Wikidata), community presence (Reddit 90/10 rule, LinkedIn 3-5 posts/week, Twitter build-in-public, Indie Hackers, Dev.to/Hashnode). Should remind to track weekly KPIs (DR, referring domains, indexed pages, organic clicks, signups from directory referrals) and investigate if numbers aren't moving rather than submitting more.",

"assertions": [

"Warns against over-indexing on launch spike",

"Recommends verifying dofollow status of backlinks",

"Pivots to destination pages strategy",

"Mentions GEO tactics",

"Includes ongoing community distribution",

"Recommends tracking weekly KPIs",

"Says investigate before submitting more"

"files": []

}

]

}

mdskills/directory-submissions/references/directory-list.md

25 kB

# Directory List — Full Reference

Canonical 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.

---

## Tier 1 — Flagship Launch Platforms

Submit only during launch week. These are time-sensitive with limited re-submission windows.

|---|---|---|---|---|

---

## Tier 2 — Startup / SaaS / Software Directories

Submit during launch week and continue rolling submissions thereafter.

|---|---|---|---|---|

| **G2** | 92 | Yes | Free listing | 10 reviews required for Grid appearance. Paid badges start at $2,999/yr. |

| **F6S** | 65 | Yes | Free | Startup platform used by accelerators. |

| **Inc42** | 75 | Yes | Free | Indian startup media + directory. |

---

## Tier 3 — AI Tool Directories

Relevant only for AI-native products. Submit during weeks 1–3.

### Tier 3A — Flagship AI directories

|---|---|---|---|

| **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. |

### Tier 3B — Mid-tier AI directories

| 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. |

---

## Tier 4 — AI Agent & MCP Server Registries

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. |

---

## Tier 5 — No-Code Directories

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. |

---

## Tier 6 — "Best of" Listicles (Editorial Outreach)

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.

---

## Tier 7 — Integration Marketplaces

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. |

---

## Tier 8 — Profile & Content Platforms

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.

|---|---|---|---|---|

---

## Tier 9 — Local Business & General Directories

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.

|---|---|---|---|

| **Spoke** | 70 | B2B | Business profile directory. |

---

## Tier 10 — Forums & Communities

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.

|---|---|---|---|

---

## Tier 11 — Press Release, Article & Blog Directory Sites

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.

### Article & Blog Directories

|---|---|---|---|

### Press Release Distribution

| 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. |

### Marketing & General Directories

| 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. |

---

## Tier 12 — Social Bookmarking & Curation

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. |

---

## Tier 13 — Niche Vertical Directories

Industry-specific directories. Only submit if your product genuinely fits the vertical — forced listings get rejected and waste time.

### Legal

| Directory | DR | Notes |

|---|---|---|

| **Justia** | 85 | Legal services directory. |

| **Lawyers.com** | 82 | Legal directory. |

| **HG.org** | 75 | Legal resources directory. |

### Home & Construction

| 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. |

### Hospitality & Food

| Directory | DR | Notes |

|---|---|---|

| **AllMenus** | 76 | Restaurant directory. |

### Design & Creative

| Directory | DR | Notes |

|---|---|---|

| **LandBook** | 72 | Web design inspiration gallery. Submit landing pages. |

| **Curated.design** | 52 | Design inspiration directory. |

| **Webdesign Inspiration** | 45 | Website design showcase. |

### Health & Fitness

| 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. |

### Real Estate

| Directory | DR | Notes |

|---|---|---|

| **Placester** | 60 | Real estate marketing directory. |

### B2B & International

| Directory | DR | Notes |

|---|---|---|

| **Sulekha** | 73 | Indian business directory. |

| **EU-Business** | 46 | European business directory. |

### Events

| Directory | DR | Notes |

|---|---|---|

| **Evensi Events** | 62 | Event discovery platform. |

### Education

| Directory | DR | Notes |

|---|---|---|

| *(TeachersPayTeachers listed in Tier 8 — Profile Platforms)* | | |

---

## Verification

After any submission goes live, verify the backlink exists and is dofollow. You can:

1. **Manual:** Open the listing, right-click your product link, "Inspect" → check for `rel="nofollow"` or `rel="ugc"`. If absent, the link is dofollow.

2. **curl:** `curl -sIL https://directory.com/your-listing | grep -i link`

3. **SEO tools:** Ahrefs Site Explorer → Backlinks → filter by this directory's domain.

**Re-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.

mdskills/directory-submissions/references/positioning-variations.md

9.1 kB

# Positioning Variations Library

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.

---

## Framework: Lead Sentence Varies by Tier

| 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. |

---

## Template: Startup / Launch Directories

**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]

---

## Template: SaaS / Software Directories

**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] integrations

> Trusted by [audience examples]. Start free at [url].

**Tags:** [competitor] alternative, [category], [audience], [differentiator], [top 3 features]

---

## Template: AI Directories

**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]

---

## Template: Agent / MCP Registries

**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]

---

## Template: No-Code Directories

**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]

---

## Template: Dev / Technical Directories

**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]

---

## Template: B2B Review Platforms

**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]

---

## Category Tag Library

Pull 5–8 tags per submission from the relevant sections. Never repeat the exact same tag set across two directories in the same tier.

### Universal

[category], [audience], [differentiator], [use case], AI, no-code, SaaS, [tech stack]

### Industry

B2B, B2C, DTC, ecommerce, fintech, edtech, healthtech, martech, devtools, productivity, creator tools, agency tools

### Job-to-be-done

lead generation, lead qualification, customer onboarding, product recommendation, sales enablement, marketing automation, survey, assessment, calculator, quiz, intake form

### AI-specific

AI agent, LLM, generative AI, conversational AI, RAG, MCP, agent framework, AI form, AI quiz, AI assistant, AI automation

### Technical

open source, self-hosted, API-first, webhook, Zapier, no-code, low-code, embeddable, white-label, multi-tenant, SSO, SAML

---

## Do / Don't Quick Reference

**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

csvskills/directory-submissions/references/submission-tracker-template.csv

19 kB

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,,,

mdskills/directory-submissions/SKILL.md

23 kB

---

description: 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 to directories," "backlinks from directories," "list my product," "submit to Product Hunt," "BetaList," "TAAFT," "Futurepedia," "G2 listing," "Capterra listing," "AlternativeTo," "SaaSHub," "AI directories," "MCP registry," "agent directory," "dofollow backlinks," "launch directories," or "directory tracker." Use this whenever someone is planning the directory layer of a product launch or an ongoing backlink campaign. For the broader launch moment, see launch. For programmatic SEO pages that should live behind these backlinks, see programmatic-seo. For AI citation optimization, see ai-seo.

metadata:

version: 2.0.0

---

# Directory Submissions

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.

## Before Starting

**Check for product marketing context first:**

---

## Core Philosophy

Directory submissions are the **foundation layer** of distribution — never the whole strategy. They do three things well:

1. **Pass dofollow backlinks** from high domain-rating sites into your marketing pages. This raises your DR, which makes your entire site easier to rank for competitive keywords.

2. **Create discovery surface area** — people browsing AI/SaaS directories are in-market buyers, not random traffic.

3. **Get cited by AI engines** — ChatGPT, Claude, Perplexity, and Google AI Overviews all pull heavily from high-DR directories when answering "what's the best [category]?" queries. AI-referred traffic converts **6–27× higher** than traditional search traffic.

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`.

---

## The Three Hard Rules

### Rule 1: Foundation before submission

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`.

### Rule 2: Destination pages before directories

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.

### Rule 3: Positioning varies by directory type

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. |

---

## Workflow

### Step 1: Readiness assessment (Phase 0)

Ask the user these 9 questions. If any are "no", they're not ready — help them build the missing piece first.

1. Is the product publicly accessible (no password wall)?

2. Is there a pricing page (even "free while in beta")?

3. Are privacy policy + terms live?

4. Logo assets in PNG + SVG + square + favicon?

5. 5–8 real screenshots + 60–90s demo video?

6. Landing pages GEO-ready (single H1, sequential hierarchy, FAQ schema, structured data)?

7. At least 3 alternative pages and 3 use-case pages live and indexed?

8. Template gallery or lead magnet asset (if applicable to category)?

9. At least 20 beta/early users who could leave a review on G2?

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.

### Step 2: Choose the tiers

Full catalog in `references/directory-list.md`. Summary:

|---|---|---|---|

**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.

### Step 3: Prepare asset variations

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.

### Step 4: Batch submit

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 Deep Dive (The Anchor Event)

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.

### 3-week prep timeline

- **Day -21 to -14:** Warm up hunter account. Upvote + thoughtfully comment on 3 launches/day. Follow 100+ active makers. Build history so your account looks real to the algorithm.

- **Day -14:** Create "Upcoming" page on PH. Drive traffic to it to collect "notify on launch" subscribers.

- **Day -10:** (Optional) book a hunter. Don't pay cash — trade a feature, shoutout, or intro. A known hunter adds ~15% to day-one momentum but isn't required.

- **Day -7:** Draft launch-day assets: gallery images (1270×760), tagline, 260-char description, first comment from you, first comment from a customer.

- **Day -3:** Email list warm-up. "We're launching Tuesday. Here's what to expect. Reply if you want a heads up."

- **Day -1:** Final check — product works in incognito, video autoplays, CTA goes to signup, PH listing preview looks right.

### Launch day execution

- **Launch at 12:01 AM Pacific Time.** Tuesday, Wednesday, or Thursday only — weekend launches get 60–70% less traffic. The 12:01 AM PT start maximizes your 24-hour window.

- **First 2 hours are everything.** Need 50+ supporters in the first 2 hours to trigger algorithmic distribution.

- **Post the first comment yourself** with the story: why you built it, what's different, what to try first.

- **Reply to every comment** in under 30 minutes. PH measures maker responsiveness.

- **Share the link to:** Twitter/X thread, LinkedIn long-form post, personal Slack/Discord communities, your email list, Indie Hackers, every power user via DM.

- **Never ask for upvotes.** Ask for **feedback**. "Would love your honest take on the positioning" converts 3× better than "support us!" and doesn't trigger the algorithm's anti-manipulation filters.

- **Don't message strangers.** The community flags this and moderators will hide your post.

### Post-launch

- Write a launch recap blog post with numbers + lessons. Honest, not bragging. Publish on day 2.

- Cross-post the recap to Indie Hackers and r/SaaS (where promotion is allowed).

- Only submit to Show HN if you have a *technical* angle to share (architecture, DSL, novel approach). A generic "we launched a SaaS" post will get flagged to death.

---

## Reviews Playbook (G2 / Capterra / TrustRadius)

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.

### The 10-in-30 protocol

1. **Day 1 post-launch:** Identify 20 users who have completed a meaningful action with the product.

2. **Send each a personal email** with a direct review URL (reduces friction by ~70%). No forms, no landing pages — direct link.

3. **Offer a modest thank-you.** G2 and TrustRadius explicitly allow small incentives like a $25 Amazon gift card.

4. **Follow up once** after 5 days. Don't follow up twice — it becomes annoying and damages the relationship.

5. **Target:** 50% conversion → 10 reviews from 20 asks.

### Critical deadlines

- **G2 Summer reports:** cut off ~April 28. Plan review drives to land before this.

- **G2 Fall reports:** cut off ~July 28.

- Missing a cutoff means waiting 3 months for the next grid update.

### Badges and paid plans

- **"Users Love Us" badge** is still free: requires 20 reviews at 4.0+ average.

- **Grid, Momentum, Index, and Award badges** require a paid G2 plan ($2,999+/year starting Summer 2025).

- **Do not spend on paid G2 in year one.** The free listing + Users Love Us badge is sufficient.

### Cross-platform

- TrustRadius follows similar mechanics but smaller volume.

- Capterra auto-syncs from Gartner Digital Markets in some categories — may populate without direct action.

---

## Destination Pages Strategy (What the Backlinks Point At)

Directories are useless if the backlinks land on a generic homepage. Build these destination pages *before* submitting:

### 1. Alternative pages (highest ROI)

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.

### 2. Use-case / ICP pages

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.

### 3. Template / asset gallery (if applicable)

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.

### 4. "Best of" listicles you wrote yourself

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.

### 5. Integration pages (when integrations ship)

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).

---

## GEO (Generative Engine Optimization)

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.

### Tactics that get pages cited

1. **One H1 per page, sequential heading hierarchy.** 2.8× higher citation rate. 87% of cited pages use a single H1.

2. **Dense, factual content with citable stats.** AI engines prefer specific numbers ("3× faster than X") over vague claims.

3. **FAQ schema on every landing page.** AI engines heavily weight `FAQPage` JSON-LD for answer extraction.

4. **Comparison tables.** Extractable, structured — exactly what an AI answer needs.

5. **Explicit "what it is" paragraph in the first 100 words.**

6. **Get cited on Reddit and Hacker News.** Claude and Perplexity index these heavily. Genuine mentions on r/SaaS and HN count as training fuel.

7. **Publish original research.** "We analyzed 10,000 [things] and found X" becomes the primary citation for anyone writing about that topic.

8. **Claim Crunchbase, LinkedIn company page, and Wikidata entries.** All three feed AI training corpora.

9. **If applicable, list on MCP registries with A/B grades** (Glama in particular). LLMs pull from these when answering MCP questions.

### Measurement

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.

---

## Community & Ongoing Distribution

Directories are one-shot. Community is ongoing. Both feed the same funnel.

### Reddit (90/10 rule)

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.

### LinkedIn (B2B primary channel)

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×)

### Twitter/X (indie hacker + dev channel)

Build-in-public threads on architecture, revenue, decisions. Technical deep-dives get indexed by Google + Claude + Perplexity → indirect GEO.

### Indie Hackers

- Launch a build-in-public thread on PH launch day.

- Post weekly updates: revenue, ships, lessons. Zero-revenue posts work if the lesson is honest.

- Comment 10× more than you post to build karma before your own links.

### Dev.to + Hashnode

Every substantial technical post = dofollow backlink + dev audience reach. Cross-post with canonical URL back to main blog.

---

## KPIs & Tracking

Track weekly. If a number isn't moving, investigate — don't just submit more directories.

|---|---|---|---|

| 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 |

---

## What NOT to Do

1. **Don't pay for directory submission services** ($60–$200 packages). The whole point is these are free. It's an afternoon of copy-paste.

2. **Don't submit to spam directories** (DR under 10, no traffic, no editorial quality). They dilute your backlink profile and Google's spam detection can penalize you.

3. **Don't submit with the wrong positioning.** Re-read the positioning table per tier. Generic descriptions waste the listing.

4. **Don't treat directories as your entire GTM.** They're the foundation. Content + community + reviews are what actually convert.

5. **Don't skip reviews on G2/Capterra.** Zero-review listings are dead. Run the 10-in-30 protocol or don't submit.

6. **Don't ask for upvotes on Product Hunt.** The 2026 algorithm penalizes it. Ask for **feedback**.

7. **Don't amend old directory listings every week.** Submit once, check quarterly.

8. **Don't submit before the destination page exists.** Link equity needs a destination.

9. **Don't duplicate descriptions across directories.** AI engines penalize duplicate content.

10. **Don't lie on comparison pages.** AI engines cross-reference and de-rank lies.

11. **Don't over-index on launch-day spike.** The flywheel is templates + alternatives + reviews + ongoing content — not one day of PH.

12. **Don't forget Crunchbase, LinkedIn company page, and Wikidata.** These feed AI training corpora and matter for GEO.

---

## Task-Specific Questions

1. **What are you launching?** (Category changes tier mix — AI vs traditional SaaS vs no-code vs dev tool.)

2. **When is launch day?** (Phase 0 assets need 7 days of prep.)

3. **Do you have destination pages built?** (Alternatives, use cases, templates — if not, build first.)

4. **Product Hunt hunter lined up?** (Optional but adds ~15% day-one lift. 3-week warm-up required regardless.)

5. **How many beta users can you ask for reviews?** (Need 20 to hit 10.)

6. **Do you have an MCP or agent angle?** (If yes, Tier 4 registries are a real moat.)

7. **Existing integrations?** (If yes, Tier 7 marketplaces are the highest-DR backlinks available.)

8. **Email list size?** (Needed for PH launch day warm traffic — 100+ is the minimum.)

9. **Current DR and referring domain count?** (Baseline for measuring the compounding effect.)

---

## Output Format

When the user asks for a directory plan, return:

1. **Readiness assessment** — which Phase 0 items are missing, which block submission

2. **Tier selection** — which tiers apply, which to skip, why

3. **Submission order** — week 1 / week 2 / week 3 batches

4. **Destination page list** — what to build first if missing

5. **Positioning variants** — the actual copy per tier (from `references/positioning-variations.md`)

6. **PH 3-week prep timeline** — mapped to calendar dates if launch day known

7. **Reviews 10-in-30 plan** — who to ask, when, how

8. **Weekly targets** — directories submitted, reviews, DR movement

9. **Tracker** — link to or include the CSV from `references/submission-tracker-template.csv`

Keep the plan actionable. Every item should be something the user can do today.

---

## Related Skills

- **launch** — broader launch moment, ORB framework, five-phase approach

- **programmatic-seo** — destination pages (alternatives, integrations, templates) that backlinks should flow into

- **competitors** — `/alternatives/[tool]` page pattern

- **ai-seo** — GEO optimization for AI citation

- **content-strategy** — editorial content that attracts "best of" listicle inclusions

- **free-tools** — lead magnets for destination pages

- **community-marketing** — Reddit, Indie Hackers, Slack community mechanics

- **schema** — FAQ + Product + Organization JSON-LD for GEO

jsonskills/emails/evals/evals.json

6.5 kB

{

"skill_name": "emails",

"evals": [

{

"id": 1,

"prompt": "Create a welcome email sequence for new users who sign up for our project management tool's free trial. The trial is 14 days. We want to get them to their aha moment (creating their first project and inviting a team member).",

"expected_output": "Should check for product-marketing.md first. Should create a welcome sequence (5-7 emails) following the core principles: one email one job, value before ask. Should map each email to a specific goal in the 14-day trial journey. Should include timing/delays between emails. Each email should follow the email copy structure: hook → context → value → CTA → sign-off. Should include subject lines following the subject line strategy. Should align sequence with the aha moment (first project + team invite). Output should follow the structured format with sequence overview and per-email specs.",

"assertions": [

"Checks for product-marketing.md",

"Creates 5-7 email welcome sequence",

"Follows one email one job principle",

"Maps emails to trial timeline (14 days)",

"Includes timing between emails",

"Each email has hook, context, value, CTA",

"Includes subject lines for each email",

"Aligns with stated aha moment",

"Output follows structured per-email format"

"files": []

{

"id": 2,

"prompt": "We need a lead nurture sequence for people who download our 'State of DevOps 2024' report. Goal is to get them to book a demo of our CI/CD platform.",

"expected_output": "Should create a lead nurture sequence (6-8 emails). Should follow value before ask — first emails should provide related value, not immediately push for demo. Should map the sequence from awareness (report download) through consideration (related content, case studies) to decision (demo request). Should include timing between emails. Each email should have clear subject line, hook, single CTA. Should gradually increase commitment asks across the sequence.",

"assertions": [

"Creates 6-8 email lead nurture sequence",

"Follows value before ask principle",

"Maps from awareness through consideration to decision",

"Includes timing between emails",

"Each email has clear subject line and single CTA",

"Gradually increases commitment asks",

"Connects to original download topic"

"files": []

{

"id": 3,

"prompt": "our email open rates have tanked. used to be 35% now we're at 18%. what's going on and how do we fix our subject lines?",

"expected_output": "Should trigger on casual phrasing. Should diagnose potential causes of declining open rates: sender reputation, list hygiene, subject line quality, sending frequency, deliverability issues. Should apply the subject line strategy from the skill: test curiosity vs benefit vs urgency patterns, personalization, optimal length. Should recommend a re-engagement campaign to clean the list. Should provide specific subject line formulas and examples. Should suggest testing framework for subject lines.",

"assertions": [

"Triggers on casual phrasing",

"Diagnoses potential causes beyond just subject lines",

"Addresses sender reputation and deliverability",

"Recommends list hygiene or re-engagement",

"Applies subject line strategy with specific patterns",

"Provides subject line formulas and examples",

"Suggests testing framework"

"files": []

{

"id": 4,

"prompt": "Build a re-engagement sequence for subscribers who haven't opened any emails in 90 days. We have about 5,000 inactive subscribers.",

"expected_output": "Should create a re-engagement sequence (3-4 emails). Should follow the re-engagement pattern: first email acknowledges absence and offers value, middle emails escalate with compelling reasons to re-engage, final email is a clear 'last chance' before removal. Should recommend aggressive subject lines to break through. Should include a sunset policy (remove non-responders after sequence completes). Should address the impact on deliverability of keeping inactive subscribers.",

"assertions": [

"Creates 3-4 email re-engagement sequence",

"Acknowledges absence in first email",

"Escalates through the sequence",

"Includes 'last chance' final email",

"Recommends sunset policy for non-responders",

"Addresses deliverability impact of inactive subscribers",

"Uses compelling subject lines"

"files": []

{

"id": 5,

"prompt": "What's the ideal timing for our onboarding email sequence? We send the first email immediately after signup, but we're not sure about the rest.",

"expected_output": "Should provide timing guidance for onboarding sequences. Should reference the timing and delays framework: immediate first email (welcome/confirmation), then suggest data-driven timing based on user behavior triggers vs fixed time delays. Should recommend behavior-triggered emails when possible (user completed action → next email) with time-based fallbacks. Should provide typical timing patterns for SaaS onboarding (day 0, day 1, day 3, day 5, day 7, etc.). Should note that optimal timing depends on product complexity and trial length.",

"assertions": [

"Provides timing guidance for onboarding sequences",

"Recommends immediate first email",

"Discusses behavior-triggered vs time-based timing",

"Provides typical timing patterns",

"Notes timing depends on product and trial length",

"Recommends behavior triggers with time-based fallbacks"

"files": []

{

"id": 6,

"prompt": "Help me optimize our post-signup onboarding experience. Users sign up but 60% never complete setup.",

"expected_output": "Should recognize this is an in-app onboarding optimization task, not an email sequence task. Should defer to or cross-reference the onboarding skill, which handles in-app onboarding flows, checklists, and activation optimization. May offer to help with the email component of onboarding but should make clear that onboarding is the primary skill for this task.",

"assertions": [

"Recognizes this as in-app onboarding optimization",

"References or defers to onboarding skill",

"Does not attempt full onboarding redesign using email patterns",

"May offer email component support"

"files": []

}

]

}

mdskills/emails/references/copy-guidelines.md

2.3 kB

# Email Copy Guidelines

## Contents

- Structure

- Formatting

- Tone

- Length

- CTA Buttons vs. Links

- Personalization (merge fields, dynamic content, triggered emails)

- Segmentation Strategies (by behavior, by stage, by profile)

- Testing and Optimization (what to test, how to test, metrics to track)

## Structure

1. **Hook**: First line grabs attention

2. **Context**: Why this matters to them

3. **Value**: The useful content

4. **CTA**: What to do next

5. **Sign-off**: Human, warm close

## Formatting

- Short paragraphs (1-3 sentences)

- White space between sections

- Bullet points for scanability

- Bold for emphasis (sparingly)

- Mobile-first (most read on phone)

## Tone

- Conversational, not formal

- First-person (I/we) and second-person (you)

- Active voice

- Match your brand but lean friendly

- Read it out loud—does it sound human?

## Length

- Shorter is usually better

- 50-125 words for transactional

- 150-300 words for educational

- 300-500 words for story-driven

- If it's long, it better be good

## CTA Buttons vs. Links

- Buttons: Primary actions, high-visibility

- Links: Secondary actions, in-text

- One clear primary CTA per email

- Button text: Action + outcome

---

## Personalization

### Merge Fields

- First name (fallback to "there" or "friend")

- Company name (B2B)

- Relevant data (usage, plan, etc.)

### Dynamic Content

- Based on segment

- Based on behavior

- Based on stage

### Triggered Emails

- Action-based sends

- More relevant than time-based

- Examples: Feature used, milestone hit, inactivity

---

## Segmentation Strategies

### By Behavior

- Openers vs. non-openers

- Clickers vs. non-clickers

- Active vs. inactive

### By Stage

- Trial vs. paid

- New vs. long-term

- Engaged vs. at-risk

### By Profile

- Industry/role (B2B)

- Use case / goal

- Company size

---

## Testing and Optimization

### What to Test

- Subject lines (highest impact)

- Send times

- Email length

- CTA placement and copy

- Personalization level

- Sequence timing

### How to Test

- A/B test one variable at a time

- Sufficient sample size

- Statistical significance

- Document learnings

### Metrics to Track

- Open rate (benchmark: 20-40%)

- Click rate (benchmark: 2-5%)

- Unsubscribe rate (keep under 0.5%)

- Conversion rate (specific to sequence goal)

- Revenue per email (if applicable)

mdskills/emails/references/email-types.md

14 kB

# Email Types Reference

A comprehensive guide to lifecycle and campaign emails. Use this as an audit checklist and implementation reference.

## Contents

- Onboarding Emails (new users series, new customers series, key onboarding step reminder, new user invite)

- Retention Emails (upgrade to paid, upgrade to higher plan, ask for review, offer support proactively, product usage report, NPS survey, referral program)

- Billing Emails (switch to annual, failed payment recovery, cancellation survey, upcoming renewal reminder)

- Usage Emails (daily/weekly/monthly summary, key event or milestone notifications)

- Win-Back Emails (expired trials, cancelled customers)

- Campaign Emails (monthly roundup/newsletter, seasonal promotions, product updates, industry news roundup, pricing update)

- Email Audit Checklist (onboarding, retention, billing, usage, win-back, campaigns)

## Onboarding Emails

### New Users Series

**Trigger**: User signs up (free or trial)

**Goal**: Activate user, drive to aha moment

**Typical sequence**: 5-7 emails over 14 days

- Email 1: Welcome + single next step (immediate)

- Email 2: Quick win / getting started (day 1)

- Email 3: Key feature highlight (day 3)

- Email 4: Success story / social proof (day 5)

- Email 5: Check-in + offer help (day 7)

- Email 6: Advanced tip (day 10)

- Email 7: Upgrade prompt or next milestone (day 14)

**Key metrics**: Activation rate, feature adoption

---

### New Customers Series

**Trigger**: User converts to paid

**Goal**: Reinforce purchase decision, drive adoption, reduce early churn

**Typical sequence**: 3-5 emails over 14 days

- Email 1: Thank you + what's next (immediate)

- Email 2: Getting full value — setup checklist (day 2)

- Email 3: Pro tips for paid features (day 5)

- Email 4: Success story from similar customer (day 7)

- Email 5: Check-in + introduce support resources (day 14)

**Key point**: Different from new user series—they've committed. Focus on reinforcement and expansion, not conversion.

---

### Key Onboarding Step Reminder

**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

---

### New User Invite

**Trigger**: Existing user invites teammate

**Goal**: Activate the invited user

**Recipient**: The person being invited

- Email 1: You've been invited (immediate)

- Email 2: Reminder if not accepted (day 2)

- Email 3: Final reminder (day 5)

**Copy approach**:

- Personalize with inviter's name

- Explain what they're joining

- Single CTA to accept invite

- Social proof optional

---

## Retention Emails

### Upgrade to Paid

**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

---

### Upgrade to Higher Plan

**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

---

### Ask for Review

**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

---

### Offer Support Proactively

**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

---

### Product Usage Report

**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.

---

### NPS Survey

**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

---

### Referral Program

**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

---

## Billing Emails

### Switch to Annual

**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)

---

### Failed Payment Recovery

**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

---

### Cancellation Survey

**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).

---

### Upcoming Renewal Reminder

**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

---

## Usage Emails

### Daily/Weekly/Monthly Summary

**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.

---

### Key Event or Milestone Notifications

**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

---

## Win-Back Emails

### Expired Trials

**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

---

### Cancelled Customers

**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.

---

## Campaign Emails

### Monthly Roundup / Newsletter

**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

---

### Seasonal Promotions

**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

---

### Product Updates

**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)

---

### Industry News Roundup

**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.

---

### Pricing Update

**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.

---

## Email Audit Checklist

Use this to audit your current email program:

### Onboarding

- [ ] New users series

- [ ] New customers series

- [ ] Key onboarding step reminders

- [ ] New user invite sequence

### Retention

- [ ] Upgrade to paid sequence

- [ ] Upgrade to higher plan triggers

- [ ] Ask for review (timed properly)

- [ ] Proactive support outreach

- [ ] Product usage reports

- [ ] NPS survey

- [ ] Referral program emails

### Billing

- [ ] Switch to annual campaign

- [ ] Failed payment recovery sequence

- [ ] Cancellation survey

- [ ] Upcoming renewal reminders

### Usage

- [ ] Daily/weekly/monthly summaries

- [ ] Key event notifications

- [ ] Milestone celebrations

### Win-Back

- [ ] Expired trial sequence

- [ ] Cancelled customer sequence

### Campaigns

- [ ] Monthly roundup / newsletter

- [ ] Seasonal promotion calendar

- [ ] Product update announcements

- [ ] Pricing update communications

mdskills/emails/references/sequence-templates.md

3.8 kB

# Email Sequence Templates

Detailed templates for common email sequences.

## Contents

- Welcome Sequence (Post-Signup)

- Lead Nurture Sequence (Pre-Sale)

- Re-Engagement Sequence

- Onboarding Sequence (Product Users)

## Welcome Sequence (Post-Signup)

**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)

---

## Lead Nurture Sequence (Pre-Sale)

**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

---

## Re-Engagement Sequence

**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

---

## Onboarding Sequence (Product Users)

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

mdskills/emails/SKILL.md

8.4 kB

---

description: 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," "onboarding emails," "welcome sequence," "re-engagement emails," "email automation," "lifecycle emails," "trigger-based emails," "email funnel," "email workflow," "what emails should I send," "welcome series," or "email cadence." Use this for any multi-email automated flow. For cold outreach emails, see cold-email. For in-app onboarding, see onboarding.

metadata:

version: 2.0.0

---

# Email Sequence Design

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.

## Initial Assessment

**Check for product marketing context first:**

Before creating a sequence, understand:

1. **Sequence Type**

- Welcome/onboarding sequence

- Lead nurture sequence

- Re-engagement sequence

- Post-purchase sequence

- Event-based sequence

- Educational sequence

- Sales sequence

2. **Audience Context**

- Who are they?

- What triggered them into this sequence?

- What do they already know/believe?

- What's their current relationship with you?

3. **Goals**

- Primary conversion goal

- Relationship-building goals

- Segmentation goals

- What defines success?

---

## Core Principles

### 1. One Email, One Job

- Each email has one primary purpose

- One main CTA per email

- Don't try to do everything

### 2. Value Before Ask

- Lead with usefulness

- Build trust through content

- Earn the right to sell

### 3. Relevance Over Volume

- Fewer, better emails win

- Segment for relevance

- Quality > frequency

### 4. Clear Path Forward

- Every email moves them somewhere

- Links should do something useful

- Make next steps obvious

---

## Email Sequence Strategy

### Sequence Length

- Welcome: 3-7 emails

- Lead nurture: 5-10 emails

- Onboarding: 5-10 emails

- Re-engagement: 3-5 emails

Depends on:

- Sales cycle length

- Product complexity

- Relationship stage

### Timing/Delays

- Welcome email: Immediately

- Early sequence: 1-2 days apart

- Nurture: 2-4 days apart

- Long-term: Weekly or bi-weekly

Consider:

- B2B: Avoid weekends

- B2C: Test weekends

- Time zones: Send at local time

### Subject Line Strategy

- Clear > Clever

- Specific > Vague

- Benefit or curiosity-driven

- 40-60 characters ideal

- Test emoji (they're polarizing)

**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]"

### Preview Text

- Extends the subject line

- ~90-140 characters

- Don't repeat subject line

- Complete the thought or add intrigue

---

## Sequence Types Overview

### Welcome Sequence (Post-Signup)

**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)

### Lead Nurture Sequence (Pre-Sale)

**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)

### Re-Engagement Sequence

**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)

### Onboarding Sequence (Product Users)

**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](references/sequence-templates.md)

---

## Email Types by Category

### Onboarding Emails

- New users series

- New customers series

- Key onboarding step reminders

- New user invites

### Retention Emails

- Upgrade to paid

- Upgrade to higher plan

- Ask for review

- Proactive support offers

- Product usage reports

- NPS survey

- Referral program

### Billing Emails

- Switch to annual

- Failed payment recovery

- Cancellation survey

- Upcoming renewal reminders

### Usage Emails

- Daily/weekly/monthly summaries

- Key event notifications

- Milestone celebrations

### Win-Back Emails

- Expired trials

- Cancelled customers

### Campaign Emails

- Monthly roundup / newsletter

- Seasonal promotions

- Product updates

- Industry news roundup

- Pricing updates

**For detailed email type reference**: See [references/email-types.md](references/email-types.md)

---

## Email Copy Guidelines

### Structure

1. **Hook**: First line grabs attention

2. **Context**: Why this matters to them

3. **Value**: The useful content

4. **CTA**: What to do next

5. **Sign-off**: Human, warm close

### Formatting

- Short paragraphs (1-3 sentences)

- White space between sections

- Bullet points for scanability

- Bold for emphasis (sparingly)

- Mobile-first (most read on phone)

### Tone

- Conversational, not formal

- First-person (I/we) and second-person (you)

- Active voice

- Read it out loud—does it sound human?

### Length

- 50-125 words for transactional

- 150-300 words for educational

- 300-500 words for story-driven

### CTA Guidelines

- Buttons for primary actions

- Links for secondary actions

- One clear primary CTA per email

- Button text: Action + outcome

**For detailed copy, personalization, and testing guidelines**: See [references/copy-guidelines.md](references/copy-guidelines.md)

---

## Output Format

### Sequence Overview

```

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]

```

### For Each Email

```

Email [#]: [Name/Purpose]

Send: [Timing]

Subject: [Subject line]

Preview: [Preview text]

Body: [Full copy]

CTA: [Button text] → [Link destination]

Segment/Conditions: [If applicable]

```

### Metrics Plan

What to measure and benchmarks

---

## Task-Specific Questions

1. What triggers entry to this sequence?

2. What's the primary goal/conversion action?

3. What do they already know about you?

4. What other emails are they receiving?

5. What's your current email performance?

---

## Tool Integrations

For implementation, see the [tools registry](../../tools/REGISTRY.md). Key email tools:

|------|----------|:---:|-------|

| **Kit** | Creator/newsletter focused | - | [kit.md](../../tools/integrations/kit.md) |

---

## Related Skills

- **lead-magnets**: For planning lead magnets that feed into nurture sequences

- **churn-prevention**: For cancel flows, save offers, and dunning strategy (email supports this)

- **onboarding**: For in-app onboarding (email supports this)

- **copywriting**: For landing pages emails link to

- **ab-testing**: For testing email elements

- **popups**: For email capture popups

- **revops**: For lifecycle stages that trigger email sequences

jsonskills/free-tools/evals/evals.json

6.1 kB

{

"skill_name": "free-tools",

"evals": [

{

"id": 1,

"prompt": "We want to build a free tool to drive leads for our SEO software. We're thinking about an SEO audit tool or a keyword research tool. Which would be better and how should we approach it?",

"expected_output": "Should check for product-marketing.md first. Should apply the evaluation scorecard to compare both tool ideas across dimensions (audience alignment, lead quality, build effort, SEO value, maintenance burden, competitive differentiation). Should reference the tool types from the skill (analyzers, testers). Should recommend the stronger option with rationale. Should discuss lead capture gating strategy (what's free vs what requires email). Should address MVP scope — what's the minimum valuable version. Should provide implementation recommendations.",

"assertions": [

"Checks for product-marketing.md",

"Applies evaluation scorecard to compare options",

"References tool types from the skill",

"Recommends one option with clear rationale",

"Discusses lead capture gating strategy",

"Addresses MVP scope",

"Provides implementation recommendations"

"files": []

{

"id": 2,

"prompt": "I want to build a free ROI calculator for our HR software. Users input their company size and current processes, and it shows how much time and money they'd save.",

"expected_output": "Should identify this as a calculator tool type. Should apply the ideation framework to validate the concept. Should discuss lead capture strategy: should the basic result be free and detailed report gated? Should address the build vs buy decision. Should recommend MVP scope (what inputs, what outputs, what formula). Should discuss SEO considerations for the tool page. Should reference the evaluation scorecard to score the idea.",

"assertions": [

"Identifies as calculator tool type",

"Applies ideation framework to validate",

"Discusses lead capture gating strategy",

"Addresses build vs buy decision",

"Recommends MVP scope (inputs, outputs, formula)",

"Discusses SEO considerations",

"References evaluation scorecard"

"files": []

{

"id": 3,

"prompt": "give me some ideas for free tools we could build. we sell email marketing software for e-commerce brands.",

"expected_output": "Should trigger on casual phrasing. Should apply the ideation framework to generate tool ideas relevant to email marketing + e-commerce. Should provide 5-8 ideas across different tool types (calculators, generators, analyzers, testers). Examples: email subject line tester, email deliverability checker, email ROI calculator, email template generator, spam score checker. Should briefly score each against the evaluation dimensions. Should recommend top 2-3 to pursue.",

"assertions": [

"Triggers on casual phrasing",

"Applies ideation framework",

"Generates ideas across multiple tool types",

"Ideas are relevant to email marketing + e-commerce",

"Provides 5-8 ideas",

"Briefly evaluates each idea",

"Recommends top 2-3 to pursue"

"files": []

{

"id": 4,

"prompt": "We built a free website speed test tool 6 months ago but it's barely getting any traffic. What went wrong and how do we fix it?",

"expected_output": "Should diagnose why the tool isn't getting traffic. Should investigate: SEO strategy for the tool page (target keywords, on-page optimization), distribution strategy (was it launched and forgotten?), competitive landscape (are there dominant free tools already?), tool quality and UX (does it provide unique value?). Should apply the engineering as marketing principles. Should recommend a recovery plan: SEO improvements, content marketing around the tool, product improvements for differentiation.",

"assertions": [

"Diagnoses potential traffic issues",

"Investigates SEO strategy for the tool",

"Assesses competitive landscape",

"Questions unique value proposition",

"Applies engineering as marketing principles",

"Recommends recovery plan with specific actions"

"files": []

{

"id": 5,

"prompt": "Should we gate our free tool behind an email capture or make it completely free? We want leads but don't want to kill usage.",

"expected_output": "Should apply the lead capture gating strategy framework. Should present the spectrum: fully ungated → partial gating (basic results free, detailed report gated) → fully gated. Should recommend partial gating as the typical best approach — give enough value to demonstrate the tool's worth, gate the detailed/actionable output. Should discuss tradeoffs: ungated = more SEO value and usage, gated = more leads but fewer users. Should provide specific gating recommendations based on tool type.",

"assertions": [

"Applies lead capture gating strategy",

"Presents gating spectrum (ungated to fully gated)",

"Recommends partial gating approach",

"Discusses tradeoffs of each approach",

"Provides specific gating recommendations",

"Addresses SEO impact of gating decisions"

"files": []

{

"id": 6,

"prompt": "How do I optimize the landing page for our free tool to get more signups? The tool itself is great but nobody finds it.",

"expected_output": "Should recognize this is a landing page conversion optimization task, not a free tool strategy task. Should defer to or cross-reference the cro skill for optimizing the tool's landing page conversion rate. May provide free-tool-specific context (gating strategy, value demonstration) but should make clear that cro is the right skill for page conversion optimization.",

"assertions": [

"Recognizes this as page CRO, not free tool strategy",

"References or defers to cro skill",

"May provide free-tool-specific context",

"Does not attempt full page CRO using free tool strategy patterns"

"files": []

}

]

}

mdskills/free-tools/references/tool-types.md

3.9 kB

# Free Tool Types Reference

Detailed guide to each type of marketing tool you can build.

## Contents

- Calculators

- Generators

- Analyzers/Auditors

- Testers/Validators

- Libraries/Resources

- Interactive Educational

- Tool Concept Examples by Industry (SaaS product, agency/services, e-commerce, developer tools, finance)

## Calculators

**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

---

## Generators

**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

---

## Analyzers/Auditors

**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

---

## Testers/Validators

**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

---

## Libraries/Resources

**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

---

## Interactive Educational

**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

---

## Tool Concept Examples by Industry

### SaaS Product

- Product ROI calculator

- Competitor comparison tool

- Readiness assessment quiz

- Template library for use case

- Feature configurator

### Agency/Services

- Industry benchmark tool

- Project scoping calculator

- Portfolio review tool

- Cost estimator

- Proposal generator

### E-commerce

- Product finder quiz

- Comparison tool

- Size/fit calculator

- Savings calculator

- Gift finder

### Developer Tools

- Code snippet library

- Testing/preview tool

- Documentation generator

- Interactive tutorials

- API playground

### Finance

- Financial calculators

- Investment comparison

- Budget planner

- Tax estimator

- Loan calculator

mdskills/free-tools/SKILL.md

5.8 kB

---

description: 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 tool," "calculator," "generator," "interactive tool," "lead gen tool," "build a tool for leads," "free resource," "ROI calculator," "grader tool," "audit tool," "should I build a free tool," or "tools for lead gen." Use this whenever someone wants to build something useful and give it away to attract leads or earn links. For downloadable content lead magnets (ebooks, checklists, templates), see lead-magnets.

metadata:

version: 2.0.0

---

# Free Tool Strategy (Engineering as Marketing)

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.

## Initial Assessment

**Check for product marketing context first:**

Before designing a tool strategy, understand:

1. **Business Context** - What's the core product? Who is the target audience? What problems do they have?

2. **Goals** - Lead generation? SEO/traffic? Brand awareness? Product education?

3. **Resources** - Technical capacity to build? Ongoing maintenance bandwidth? Budget for promotion?

---

## Core Principles

### 1. Solve a Real Problem

- Tool must provide genuine value

- Solves a problem your audience actually has

- Useful even without your main product

### 2. Adjacent to Core Product

- Related to what you sell

- Natural path from tool to product

- Educates on problem you solve

### 3. Simple and Focused

- Does one thing well

- Low friction to use

- Immediate value

### 4. Worth the Investment

- Lead value × expected leads > build cost + maintenance

---

## Tool Types Overview

| 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](references/tool-types.md)

---

## Ideation Framework

### Start with Pain Points

1. **What problems does your audience Google?** - Search query research, common questions

2. **What manual processes are tedious?** - Spreadsheet tasks, repetitive calculations

3. **What do they need before buying your product?** - Assessments, planning, comparisons

4. **What information do they wish they had?** - Data they can't easily access, benchmarks

### Validate the Idea

- **Search demand**: Is there search volume? How competitive?

- **Uniqueness**: What exists? How can you be 10x better?

- **Lead quality**: Does this audience match buyers?

- **Build feasibility**: How complex? Can you scope an MVP?

---

## Lead Capture Strategy

### Gating Options

| 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 |

### Lead Capture Best Practices

- Value exchange clear: "Get your full report"

- Minimal friction: Email only

- Show preview of what they'll get

- Optional: Segment by asking one qualifying question

---

## SEO Considerations

### Keyword Strategy

**Tool landing page**: "[thing] calculator", "[thing] generator", "free [tool type]"

**Supporting content**: "How to [use case]", "What is [concept]"

### Link Building

Free tools attract links because:

- Genuinely useful (people reference them)

- Unique (can't link to just any page)

- Shareable (social amplification)

---

## Build vs. Buy

### Build Custom

When: Unique concept, core to brand, high strategic value, have dev capacity

### Use No-Code Tools

Options: Outgrow, Involve.me, Typeform, Tally, Bubble, Webflow

When: Speed to market, limited dev resources, testing concept

### Embed Existing

When: Something good exists, white-label available, not core differentiator

---

## MVP Scope

### Minimum Viable Tool

1. Core functionality only—does the one thing, works reliably

2. Essential UX—clear input, obvious output, mobile works

3. Basic lead capture—email collection, leads go somewhere useful

### What to Skip Initially

Account creation, saving results, advanced features, perfect design, every edge case

---

## Evaluation Scorecard

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

---

## Task-Specific Questions

1. What existing tools does your audience use for workarounds?

2. How do you currently generate leads?

3. What technical resources are available?

4. What's the timeline and budget?

---

## Related Skills

- **lead-magnets**: For downloadable content lead magnets (ebooks, checklists, templates)

- **cro**: For optimizing the tool's landing page

- **seo-audit**: For SEO-optimizing the tool

- **analytics**: For measuring tool usage

- **emails**: For nurturing leads from the tool

jsonskills/image/evals/evals.json

6.8 kB

{

"skill_name": "image",

"evals": [

{

"id": 1,

"prompt": "I need a hero image for a blog post about email deliverability. Make it visually striking.",

"expected_output": "Should check for product-marketing.md first. Should recommend AI generation as the approach for a one-off blog hero. Should propose a visual metaphor concept that represents email deliverability (e.g., letters being sorted through a maze, signals breaking through a wall, an inbox glow). Should specify 1200x630 (works for both hero and OG image). Should recommend Flux or Gemini for photorealistic, or Ideogram if text in image is needed. Should provide a prompt following Subject + Setting + Style + Lighting + Composition + Technical pattern. Should mention WebP optimization (target <200KB, JPEG fallback). Should not suggest using AI for product UI screenshots.",

"assertions": [

"Checks for product-marketing.md",

"Recommends AI generation for one-off hero",

"Proposes visual metaphor for topic",

"Specifies 1200x630 dimensions",

"Recommends Flux, Gemini, or Ideogram",

"Provides structured prompt",

"Mentions WebP optimization"

"files": []

{

"id": 2,

"prompt": "Generate me an image of our app's dashboard.",

"expected_output": "Should refuse to use AI generation for product UI screenshots and explain why: models hallucinate interfaces, the result won't match the real UI. Should recommend the Product Mockups & Screenshots workflow: capture real screenshots of the product at 2x resolution, frame in device mockups (browser frame, laptop, phone), add callout arrows or feature labels for context, programmatically overlay annotations with Hyperframes or HTML/CSS. Should suggest tools: browser DevTools screenshot, Shottr, CleanShot X, or screencapture CLI. Should warn this is Common Mistake #1: using AI for product UI.",

"assertions": [

"Refuses to use AI generation for product UI",

"Explains models hallucinate UI",

"Recommends real screenshots at 2x resolution",

"Mentions device mockups for framing",

"Suggests specific screenshot tools",

"Notes this as a common mistake"

"files": []

{

"id": 3,

"prompt": "Need a Twitter/X header banner for our company. We just want to show our product and tagline.",

"expected_output": "Should specify Twitter/X header dimensions: 1500x500 (3:1 aspect ratio). Should warn the banner is partially obscured by the avatar — center critical content and avoid important elements near the avatar overlap area. Should recommend keeping text minimal (seen at small sizes on mobile). Should suggest design tools (Canva or Figma) over AI generation since brand consistency matters. Should recommend Ideogram if heavy text rendering is needed since other AI models butcher text. Should suggest using brand colors + tagline + optional product shot. Should remind to test at actual display size by zooming out.",

"assertions": [

"Specifies 1500x500 dimensions",

"Warns about avatar overlap area",

"Recommends minimal text",

"Suggests Canva or Figma over AI",

"Mentions Ideogram for text-heavy designs",

"Recommends testing at display size"

"files": []

{

"id": 4,

"prompt": "I need 5 versions of the same hero image for Twitter, LinkedIn, Instagram feed, Instagram stories, and Facebook. What's the fastest way?",

"expected_output": "Should recommend the Canva Magic Resize workflow over generating 5 separate images. Should list dimensions: Twitter/X 1200x675 (16:9), LinkedIn 1200x627 (1.91:1), Instagram feed 1080x1080 (1:1 — note 1080x1350 / 4:5 also strong), Instagram Stories 1080x1920 (9:16), Facebook 1200x630 (1.91:1). Should explain workflow: create the hero concept at highest resolution needed, use Canva Magic Resize for variants, manually crop if needed, add text overlays programmatically if required (Ideogram or post-processing), export at each platform's specs. Should note this is what Canva Magic Resize is specifically designed for.",

"assertions": [

"Recommends Canva Magic Resize",

"Lists dimensions for all 5 platforms",

"Notes Instagram 4:5 variant",

"Suggests programmatic text overlays for variants",

"Says start at highest resolution"

"files": []

{

"id": 5,

"prompt": "What's the best image format for our website?",

"expected_output": "Should recommend WebP as the default choice with JPEG/PNG fallback. Should explain the format guide: WebP for photos and graphics (lossy + lossless, ~96% browser support), AVIF for highest compression (~94% support, newer), JPEG as universal fallback (lossy only), PNG for transparency and screenshots (lossless, universal), SVG for logos and icons (vector, scales, universal). Should reference the optimization checklist: resize to display size, compress (target quality 75-85% for photos), lazy load below-the-fold, set explicit width/height attributes (prevents CLS), use a CDN with auto-optimization (Cloudflare, Vercel, Imgix, Cloudinary), add descriptive alt text. Should provide a quick cwebp or mogrify command. Should note skipping image optimization is the #1 page speed killer.",

"assertions": [

"Recommends WebP as default",

"Mentions JPEG/PNG fallback strategy",

"Lists optimization checklist items",

"Mentions lazy loading",

"Mentions explicit dimensions to prevent CLS",

"Provides command line tool example"

"files": []

{

"id": 6,

"prompt": "We're a SaaS that just launched. Need OG images for every blog post we ship — about 2 per week. Doing it manually is killing us.",

"expected_output": "Should recommend Dynamic OG Images programmatic approach. Should explain options: Vercel OG (@vercel/og) generates images at the edge using JSX — best for programmatic SEO since you can dynamically pull post title, author, image into a template; Satori converts HTML/CSS to SVG (powers Vercel OG); Cloudinary for URL-based text overlay on template images. Should explain you build the template once with your branding then it generates unique OG images per page using post metadata. Should mention required meta tags: og:image (1200x630), og:image:width, og:image:height, twitter:card summary_large_image, twitter:image. Should note this is best for programmatic SEO.",

"assertions": [

"Recommends programmatic OG image generation",

"Names Vercel OG, Satori, or Cloudinary",

"Mentions template + dynamic data approach",

"Lists required og:image meta tags",

"Specifies 1200x630 dimensions",

"Notes this is best for high-volume blogs"

"files": []

}

]

}

mdskills/image/references/ai-image-prompting.md

7.9 kB

# AI Image Prompting Guide

How to write effective prompts for AI image generation models (Gemini/Nano Banana, Flux, Ideogram, DALL-E, Midjourney).

---

## Prompt Structure

A strong image prompt follows this formula:

```

[Subject] + [Setting/context] + [Visual style] + [Lighting] + [Composition] + [Technical specs]

```

### Example Prompts by Use Case

**Blog hero — SaaS product:**

```

A clean workspace with a laptop displaying a colorful analytics dashboard,

minimalist desk with a coffee cup and notebook,

bright natural window lighting from the right,

shallow depth of field, commercial photography style,

1200x630, high resolution

```

**Social media graphic — announcement:**

```

Abstract flowing gradient in deep purple and electric blue,

geometric shapes forming a network pattern,

dramatic rim lighting on edges,

modern tech aesthetic, clean and minimal,

1080x1080, vibrant colors

```

**Product lifestyle shot:**

```

A person in a modern office smiling while looking at a tablet,

showing a project management interface on screen,

warm candid photography, natural lighting,

medium shot, shallow depth of field, editorial style

```

**Profile banner — professional:**

```

Wide panoramic abstract background in navy blue and teal,

subtle geometric grid pattern with soft gradient,

clean corporate aesthetic, muted lighting,

1584x396, no text, space for logo overlay on left third

```

**Directory listing — Product Hunt:**

```

Product screenshot on a clean gradient background,

soft shadow underneath, slight 3D perspective tilt,

modern SaaS product presentation style,

1270x760, bright and professional

```

---

## Style Keywords

### Photorealistic

- "commercial photography"

- "shot on Canon EOS R5"

- "editorial style"

- "natural lighting"

- "shallow depth of field"

### Clean/Corporate

- "clean modern aesthetic"

- "minimal design"

- "professional corporate style"

- "bright and airy"

- "white background"

### Illustrative

- "flat vector illustration"

- "isometric 3D render"

- "hand-drawn sketch style"

- "watercolor illustration"

- "line art"

### Abstract/Brand

- "flowing gradient"

- "geometric pattern"

- "abstract data visualization"

- "particle effects"

- "holographic iridescent"

### Tech/SaaS

- "dark mode UI aesthetic"

- "neon accent lighting"

- "glassmorphism"

- "futuristic minimal"

- "developer-focused"

---

## Lighting Keywords

| Term | Effect | Best For |

|------|--------|----------|

| **Natural light** | Warm, organic feel | Lifestyle, editorial |

| **Studio lighting** | Even, controlled | Product shots |

| **Rim lighting** | Edge highlights, dramatic | Hero images, abstract |

| **Soft directional** | Gentle shadows, dimensional | Blog headers |

| **Volumetric** | Light rays, atmospheric | Dramatic, cinematic |

| **Flat/even** | No shadows, clean | Icons, diagrams |

| **Golden hour** | Warm orange tones | Lifestyle, outdoor |

| **High key** | Bright, minimal shadows | Clean, corporate |

---

## Composition Keywords

| Term | Effect | Best For |

|------|--------|----------|

| **Rule of thirds** | Subject off-center | Editorial, lifestyle |

| **Centered** | Subject in middle | Product shots, icons |

| **Wide/panoramic** | Expansive view | Banners, headers |

| **Close-up/macro** | Detail focus | Texture, product detail |

| **Bird's eye/overhead** | Top-down view | Desk setups, flat lays |

| **Negative space** | Room for text overlay | Blog headers, banners |

| **Symmetrical** | Balanced, formal | Corporate, luxury |

---

## Model-Specific Tips

### Gemini Image (Google)

- Best all-around for marketing images — good quality, reasonable cost

- Supports **image editing** — upload an existing image and describe changes

- Decent text rendering — can handle short headlines

- Specify "high resolution" for best output

- Works well with detailed, descriptive prompts

- Same API as text generation — easy to integrate

### Flux (Black Forest Labs)

- **Multi-image reference** is the killer feature — upload product screenshots, brand assets, or style references

- Best for **brand consistency** across a set of images

- Use Flux Pro for final assets, Flux Dev for rapid iteration

- Flux Klein for high-volume batch generation (cheapest)

- Style transfer via reference images > style keywords in prompt

- Prompts can be shorter than other models — the references do heavy lifting

### Ideogram

- **Best text rendering** of any model (industry-leading accuracy)

- Use when you need headlines, taglines, or brand names in the image

- Style reference system (up to 3 images) for brand consistency

- Supports "Magic Prompt" auto-enhancement

- Keep text requests simple — 3-5 words max for reliability

- Best for social graphics and banners that need text baked in

### GPT Image (OpenAI)

- Current models: `gpt-image-1` and variants (DALL-E 3 is deprecated)

- Integrated with ChatGPT — conversational image generation

- Good at following detailed prompts

- Decent text rendering (behind Ideogram, comparable to Gemini)

- Automatic prompt rewriting — may deviate from exact request

- Best for quick one-offs through ChatGPT interface

- API gives more control than ChatGPT interface

### Midjourney

- Highest aesthetic quality for artistic/editorial images

- No official API — Discord-based or web interface

- **Not agent-friendly** — use for manual creative exploration only

- Style flags: `--style raw` for less stylized, `--ar 16:9` for aspect ratio

- Best for hero images where pure visual quality matters most

- V6+ has improved text rendering but still unreliable

---

## Common Prompt Mistakes

| Mistake | Why It Fails | Fix |

|---------|-------------|-----|

| "A professional image" | No visual detail | Describe subject, setting, style, lighting |

| Long paragraph of text in image | Models can't render paragraphs | 3-5 words max; add text in post |

| "Make it look good" | Not actionable | Specify style: "commercial photography, bright" |

| 200+ word prompts | Models lose focus | 40-80 words, specific over comprehensive |

| No aspect ratio | Random output size | Always specify dimensions or ratio |

| "Logo in bottom right" | Unreliable placement | Add logos in post-processing |

| "Make it viral" | Not a visual instruction | Describe the aesthetic you want |

| Requesting UI screenshots | AI hallucinates interfaces | Capture real screenshots instead |

---

## Batch Generation Workflow

When you need multiple images with consistent style (e.g., a blog series or social campaign):

1. **Generate 3-4 test images** with different style prompts

2. **Pick the winning style** based on brand fit

3. **Save the exact prompt** as your template

4. **Use Flux multi-reference** — upload the winning image as a style reference

5. **Batch generate** variations with the same style, different subjects

6. **Post-process** — add text overlays, logos, crop to platform sizes

---

## Aspect Ratios Quick Reference

|----------|-------|--------|-------|

| Blog hero / OG image | 1.91:1 | 1200x630 | Universal web standard |

| Full-width hero | 16:9 | 1920x1080 | Website headers |

| Instagram Feed | 1:1 | 1080x1080 | Square |

| Instagram Feed (tall) | 4:5 | 1080x1350 | More screen real estate |

| Stories / Reels | 9:16 | 1080x1920 | Vertical full screen |

| LinkedIn cover | 4:1 | 1584x396 | Personal profile |

| Twitter/X header | 3:1 | 1500x500 | Profile banner |

| Product Hunt gallery | 5:3 | 1270x760 | Launch page |

| GitHub social preview | 2:1 | 1280x640 | Repo link card |

---

## Cost Optimization

- **Iterate at low quality first** — use Flux Dev or Gemini Flash for drafts, upgrade for finals

- **Use references over long prompts** — Flux multi-reference produces more consistent results with fewer retries

- **Batch similar requests** — generate all blog headers in one session with the same style

- **Cache and reuse** — abstract backgrounds, patterns, and textures can be reused across multiple images

- **Post-process instead of re-generate** — crop, overlay text, and adjust color in code rather than generating new images

mdskills/image/SKILL.md

15 kB

---

description: "When the user wants to create, generate, edit, or optimize images for marketing — blog heroes, social graphics, product mockups, profile banners, listing visuals, or brand assets. Also use when the user mentions 'AI image generation,' 'generate an image,' 'create a graphic,' 'product mockup,' 'hero image,' 'social media graphic,' 'banner image,' 'cover photo,' 'profile banner,' 'listing screenshot,' 'Flux,' 'Flux Kontext,' 'Midjourney,' 'DALL-E,' 'GPT Image,' 'ChatGPT Images,' 'Ideogram,' 'Gemini image,' 'Nano Banana,' 'Recraft,' 'Stable Diffusion,' 'Canva,' 'Figma,' 'image optimization,' 'compress images,' 'WebP,' or 'OG image.' Use this for general-purpose marketing image creation and optimization. For paid ad image creative and platform-specific ad specs, see ad-creative. For video production, see video."

metadata:

version: 2.0.1

---

# Image

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.

## Before Starting

**Check for product marketing context first:**

Gather this context (ask if not provided):

### 1. Image Goal

- What type of image? (Blog hero, social graphic, product mockup, banner, brand asset, OG image)

- What platform or placement? (Website, social, directory listing, app store, email)

- What dimensions do you need?

### 2. Production Approach

- Do you have existing brand assets? (Logo, colors, fonts, style guide)

- Do you need photorealistic or illustrative style?

- Is this a one-off or a template for repeated use?

### 3. Technical Context

- Do you have API keys for any image tools? (Gemini, Replicate/Flux, Ideogram)

- Budget constraints? (Some tools charge per image)

- Do you need the image optimized for web performance?

---

## Choosing Your Approach

Pick the right tool for the job:

|----------|----------|-------|-------------|

---

## AI Image Generation

Generate original images from text prompts. The fastest way to create unique marketing visuals.

### Model Comparison

|-------|----------|:-:|-----|------|

| **Gemini Image** (Google, "Nano Banana" / Nano Banana Pro) | All-around, editing, multi-image reference, text rendering | Good | [Gemini API](https://ai.google.dev/gemini-api/docs/image-generation) | Check [pricing](https://ai.google.dev/gemini-api/docs/pricing) |

| **Flux** (Black Forest Labs — Pro 1.1, Kontext, Dev, Schnell) | Photorealism, brand consistency, batch; Kontext for in-image editing | Limited | [BFL API](https://docs.bfl.ai/), Replicate, fal.ai | Check [pricing](https://docs.bfl.ai/quick_start/pricing) |

| **ChatGPT Images 2.0 / GPT Image** (OpenAI) | General purpose, ChatGPT integration, native editing | Good | [OpenAI API](https://platform.openai.com/docs/guides/image-generation) | Check [pricing](https://platform.openai.com/docs/pricing) |

**Note:** DALL-E 3 is fully deprecated. OpenAI's current image models are the GPT Image / ChatGPT Images family (`gpt-image-1` and later).

### When to Use Which

```

Need text/headlines in the image?

├── Yes → Ideogram 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)

```

### Prompting Basics

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](references/ai-image-prompting.md).

---

## Design Tools

For templated, brand-consistent work where AI generation is overkill or too unpredictable.

### Canva

Best for non-designers who need polished output fast.

- **Strengths:** Massive template library, brand kit, Magic Resize (one design → all sizes), team collaboration

- **Best for:** Social graphics, presentations, email headers, simple banners

- **Limitations:** Less control than Figma, templates can look generic

- **Agent-friendliness:** Has an API but limited — better as a human-in-the-loop tool

### Figma

Best for teams with design systems or pixel-perfect needs.

- **Strengths:** Design system components, auto layout, developer handoff, plugins

- **Best for:** OG images via templates, design system assets, complex layouts

- **Limitations:** Steeper learning curve, requires design skill

- **Agent-friendliness:** Has an API and MCP server for reading designs

### When to Use Design Tools vs. AI Generation

| 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 |

---

## Marketing Image Workflows

### Blog & Article Hero Images

The image at the top of every post. Sets tone, improves shareability, required for OG/social previews.

1. **Define the concept** — what visual metaphor represents the topic?

2. **Generate with AI** — use Flux or Gemini for photorealistic, Ideogram if text needed

3. **Specify 1200x630** (works for both hero and OG image) or **1920x1080** for full-width

4. **Optimize** — compress to <200KB, serve as WebP with JPEG fallback

**Prompt pattern:**

```

[Visual metaphor for topic], clean modern style,

bright natural lighting, shallow depth of field,

professional blog header aesthetic, 1200x630

```

### Social Media Graphics

Platform-specific images for organic posts.

|----------|-------------|:---:|-------|

| Twitter/X | 1200x675 | 16:9 | Large image card |

| LinkedIn | 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 |

| Facebook | 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

### Product Mockups & Screenshots

Showcase your product UI in context. AI models hallucinate UI — don't use them for this.

1. **Capture real screenshots** of your product at 2x resolution

2. **Frame in device mockups** — use browser frame, laptop, or phone templates

3. **Add context** — callout arrows, feature labels, before/after comparisons

4. **Annotate with code** — Hyperframes or HTML/CSS for programmatic overlays

**Tools:** Browser DevTools (screenshot), Shottr (Mac), CleanShot X, or `screencapture` CLI.

### Profile & Listing Banners

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

### Brand Assets

Logos, icons, and illustrations. AI generation has limits here.

|-------|:-:|:-:|-------|

| Favicons | No | Yes | Derive from logo |

| Social icons | No | Yes | Use platform-provided assets |

---

## Image Optimization

Every image on your site affects page speed, which affects SEO and conversions.

### Format Guide

|--------|----------|-------------|:---:|

### Optimization Checklist

- [ ] **Serve WebP** with JPEG/PNG fallback (`<picture>` element or CDN auto-format)

- [ ] **Resize to display size** — don't serve 4000px images in 800px containers

- [ ] **Compress** — target quality 75-85% for photos, near-lossless for screenshots

- [ ] **Lazy load** below-the-fold images (`loading="lazy"`)

- [ ] **Set explicit dimensions** — `width` and `height` attributes prevent layout shift (CLS)

- [ ] **Use a CDN** with auto-optimization (Cloudflare, Vercel, Imgix, Cloudinary)

- [ ] **Add alt text** — descriptive, keyword-relevant, not stuffed

### Quick Optimization Commands

```bash

# 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

```

---

## OG & Social Preview Images

The image that appears when your URL is shared on social media, Slack, Discord, etc.

### Required Meta Tags

```html

```

### Dynamic OG Images

Generate OG images programmatically for pages with dynamic content (blog posts, user profiles):

- **Vercel OG** (`@vercel/og`) — generates images at the edge using JSX

- **Satori** — converts HTML/CSS to SVG (powers Vercel OG)

- **Cloudinary** — URL-based text overlay on template images

**Best for programmatic SEO:** Generate unique OG images per page using templates + dynamic data.

---

## Common Mistakes

1. **Using AI for product UI screenshots** — models hallucinate interfaces; capture real screenshots

2. **Skipping image optimization** — unoptimized images are the #1 page speed killer

3. **No OG image** — shared links look broken without a preview image

4. **Wrong aspect ratio** — always check platform specs before generating

5. **Text-heavy images without Ideogram** — most AI models butcher text; use Ideogram or add text in post

6. **Generating without style direction** — "photorealistic," "flat illustration," "3D render" drastically changes output

7. **Inconsistent brand visuals** — use Flux multi-reference or design templates for consistency

8. **Huge images on landing pages** — compress, resize, lazy load

---

## Task-Specific Questions

1. What type of image do you need? (Blog hero, social graphic, mockup, banner, brand asset)

2. What platform or placement? (This determines dimensions)

3. Do you have brand assets to match? (Colors, fonts, logo, style guide)

4. Is this a one-off or a repeatable template?

5. Do you have API keys for any image generation tools?

6. Does this need to be optimized for web performance?

---

## Related Skills

- **ad-creative**: For paid ad image creative, platform-specific ad specs, and scaled ad production

- **video**: For AI video production and programmatic video

- **social**: For what to post and content strategy

- **cro**: For image placement and conversion optimization on landing pages

- **seo-audit**: For image SEO (alt text, file names, lazy loading)

- **aso**: For app store screenshot specs and optimization

- **directory-submissions**: For Product Hunt gallery images and directory listing visuals

jsonskills/launch/evals/evals.json

6.3 kB

{

"skill_name": "launch",

"evals": [

{

"id": 1,

"prompt": "We're launching a new B2B SaaS product for design teams in 6 weeks. It's a design review tool. We have a small audience (500 email subscribers, 2k Twitter followers). Help us plan the launch.",

"expected_output": "Should check for product-marketing.md first. Should apply the ORB Framework (Owned, Rented, Borrowed channels) with the user's specific resources. Owned: email list (500 subscribers), website. Rented: Twitter (2k followers). Borrowed: partnerships, communities, Product Hunt. Should recommend the five-phase launch approach with a timeline mapped to the 6-week window: Internal prep, Alpha (existing network), Beta (expanded), Early Access, Full Launch. Should provide specific tactics for each phase. Should recommend building up the audience before launch day. Should include a launch day checklist.",

"assertions": [

"Checks for product-marketing.md",

"Applies ORB Framework (Owned, Rented, Borrowed)",

"Maps to user's specific channels and audience sizes",

"Recommends five-phase launch approach",

"Provides timeline mapped to 6-week window",

"Provides specific tactics for each phase",

"Recommends audience building before launch",

"Includes launch day checklist"

"files": []

{

"id": 2,

"prompt": "We want to launch on Product Hunt. Any tips? We've never done it before.",

"expected_output": "Should apply the Product Hunt strategy section. Should cover: choosing the right day and time, preparing assets (logo, gallery images, maker video), crafting the tagline and description, building a hunter network, activating supporters on launch day, engaging with comments, and post-launch follow-up. Should recommend preparation timeline (start 2-4 weeks before). Should mention common mistakes to avoid. Should set realistic expectations about outcomes.",

"assertions": [

"Applies Product Hunt strategy section",

"Covers timing (day and time selection)",

"Covers asset preparation",

"Addresses hunter network and supporter activation",

"Recommends preparation timeline",

"Mentions common mistakes to avoid",

"Sets realistic expectations"

"files": []

{

"id": 3,

"prompt": "we just shipped a major feature update. how should we announce it? it's not a full product launch, just a big new feature.",

"expected_output": "Should trigger on casual phrasing. Should apply the ongoing launch strategy section, specifically the major/medium/minor update matrix. Should identify this as a major feature update. Should recommend appropriate channels and tactics for a feature launch (less than a full product launch but more than a changelog entry). Should include: announcement email, blog post, social media push, in-app notification, and possibly a mini Product Hunt launch. Should provide a feature announcement framework.",

"assertions": [

"Triggers on casual phrasing",

"Applies ongoing launch strategy / update matrix",

"Identifies as major feature update",

"Scales tactics appropriately (not full launch)",

"Recommends announcement channels",

"Includes email, blog, social, and in-app notification",

"Provides feature announcement framework"

"files": []

{

"id": 4,

"prompt": "Our launch flopped. We launched 3 weeks ago and only got 50 signups. We expected at least 500. What went wrong and what can we do now?",

"expected_output": "Should apply the post-launch product marketing section. Should diagnose potential failure causes: insufficient audience building pre-launch, wrong channels, weak value proposition messaging, poor launch execution, targeting the wrong audience. Should recommend post-launch recovery tactics: iterate on messaging, identify which channels produced the 50 signups and double down, try new distribution channels, leverage early users for testimonials. Should provide a specific 30-day recovery plan.",

"assertions": [

"Applies post-launch product marketing guidance",

"Diagnoses potential failure causes",

"Addresses pre-launch audience building gap",

"Recommends post-launch recovery tactics",

"Suggests analyzing which channels produced signups",

"Provides specific recovery plan"

"files": []

{

"id": 5,

"prompt": "How do we leverage partnerships and borrowed audiences for our launch? We don't have a big audience of our own.",

"expected_output": "Should focus on the Borrowed channel from the ORB Framework. Should provide specific borrowed audience tactics: podcast guest appearances, co-marketing with complementary tools, influencer partnerships, community engagement (relevant Slack groups, Discord servers, Reddit), guest posts, cross-promotions. Should recommend how to identify and approach potential partners. Should note that borrowed audience strategies take time to build and should start well before launch day.",

"assertions": [

"Focuses on Borrowed channel from ORB Framework",

"Provides specific borrowed audience tactics",

"Mentions partnerships, communities, guest content",

"Recommends how to identify and approach partners",

"Notes borrowed strategies take time to build",

"Suggests starting well before launch day"

"files": []

{

"id": 6,

"prompt": "Give me some creative marketing ideas to promote our product. We're bootstrapped and don't have a big budget.",

"expected_output": "Should recognize this is a broader marketing ideas request, not specifically a launch strategy task. Should defer to or cross-reference the marketing-ideas skill, which provides 139 marketing ideas organized by category and filtered by budget. May provide some launch-related tactical ideas but should make clear that marketing-ideas is the right skill for a broader brainstorming session.",

"assertions": [

"Recognizes this as broader marketing ideas request",

"References or defers to marketing-ideas skill",

"Does not attempt full marketing brainstorm using launch strategy patterns",

"May provide some launch-related tactical ideas"

"files": []

}

]

}

mdskills/launch/SKILL.md

13 kB

---

description: "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 access,' 'waitlist,' 'product update,' 'how do I launch this,' 'launch checklist,' 'GTM plan,' or 'we're about to ship.' Use this whenever someone is preparing to release something publicly. For ongoing marketing after launch, see marketing-ideas."

metadata:

version: 2.0.0

---

# Launch Strategy

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.

## Before Starting

**Check for product marketing context first:**

---

## Core Philosophy

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

---

## The ORB Framework

Structure your launch marketing across three channel types. Everything should ultimately lead back to owned channels.

### 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.

### Rented Channels

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.

### Borrowed Channels

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](../../tools/integrations/introw.md) 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.

---

## Five-Phase Launch Approach

Launching isn't a one-day event. It's a phased process that builds momentum.

### Phase 1: Internal Launch

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.

### Phase 2: Alpha Launch

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.

### Phase 3: Beta Launch

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.

### Phase 4: Early Access Launch

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.

### Phase 5: 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 Launch Strategy

Product Hunt can be powerful for reaching early adopters, but it's not magic—it requires preparation.

### Pros

- Exposure to tech-savvy early adopter audience

- Credibility bump (especially if Product of the Day)

- Potential PR coverage and backlinks

### Cons

- Very competitive to rank well

- Short-lived traffic spikes

- Requires significant pre-launch planning

### How to Launch Successfully

**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

### Case Studies

**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

---

## Post-Launch Product Marketing

Your launch isn't over when the announcement goes live. Now comes adoption and retention work.

### Immediate Post-Launch Actions

**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.

### Keep Momentum Going

It's easier to build on existing momentum than start from scratch. Every touchpoint reinforces the launch.

---

## Ongoing Launch Strategy

Don't rely on a single launch event. Regular updates and feature rollouts sustain engagement.

### How to Prioritize What to Announce

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

### Announcement Tactics

**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.

---

## Launch Checklist

### Pre-Launch

- [ ] Landing page with clear value proposition

- [ ] Email capture / waitlist signup

- [ ] Early access list built

- [ ] Owned channels established (email, blog, community)

- [ ] Rented channel presence (social profiles optimized)

- [ ] Borrowed channel opportunities identified (podcasts, influencers)

- [ ] Product Hunt listing prepared (if using)

- [ ] Launch assets created (screenshots, demo video, GIFs)

- [ ] Onboarding flow ready

- [ ] Analytics/tracking in place

### Launch Day

- [ ] Announcement email to list

- [ ] Blog post published

- [ ] Social posts scheduled and posted

- [ ] Product Hunt listing live (if using)

- [ ] In-app announcement for existing users

- [ ] Website banner/notification active

- [ ] Team ready to engage and respond

- [ ] Monitor for issues and feedback

### Post-Launch

- [ ] Onboarding email sequence active

- [ ] Follow-up with engaged prospects

- [ ] Roundup email includes announcement

- [ ] Comparison pages published

- [ ] Interactive demo created

- [ ] Gather and act on feedback

- [ ] Plan next launch moment

---

## Task-Specific Questions

1. What are you launching? (New product, major feature, minor update)

2. What's your current audience size and engagement?

3. What owned channels do you have? (Email list size, blog traffic, community)

4. What's your timeline for launch?

5. Have you launched before? What worked/didn't work?

6. Are you considering Product Hunt? What's your preparation status?

---

## Related Skills

- **marketing-ideas**: For additional launch tactics (#22 Product Hunt, #23 Early Access Referrals)

- **emails**: For launch and onboarding email sequences

- **cro**: For optimizing launch landing pages

- **marketing-psychology**: For psychology behind waitlists and exclusivity

- **programmatic-seo**: For comparison pages mentioned in post-launch

- **sales-enablement**: For launch sales collateral and enablement materials

jsonskills/lead-magnets/evals/evals.json

7.9 kB

{

"skill_name": "lead-magnets",

"evals": [

{

"id": 1,

"prompt": "We're a B2B SaaS selling project management software to marketing agencies. What lead magnet should we create?",

"expected_output": "Should check for product-marketing.md first. Should ask about current lead gen, existing content assets, and primary goal (list growth, lead quality, product education). Should apply Lead Magnet Principles: solve a specific problem (not 'agency marketing'), match buyer stage, high perceived value + low time investment, natural path to product. Should recommend a specific format suited to a busy agency audience — likely a template (Notion/spreadsheet) or checklist over an ebook. Examples: 'Agency Project Profitability Calculator' (decision stage, naturally leads to project management), 'Client Onboarding Checklist for Agencies' (consideration), 'The Agency Capacity Planning Template' (decision stage). Should justify the choice by matching buyer stage and effort/value ratio. Should outline content, gating, landing page, distribution, and measurement plan.",

"assertions": [

"Checks for product-marketing.md",

"Asks about buyer stage and goal",

"Applies the 5 principles",

"Recommends specific format with rationale",

"Examples match the audience and product",

"Outlines all 5 output sections (recommendation, content, gating, distribution, measurement)"

"files": []

{

"id": 2,

"prompt": "We have a 50-page ebook we spent 3 months writing. Conversion on the landing page is only 4%. Should we keep iterating?",

"expected_output": "Should diagnose this as a likely mismatch on Lead Magnet Principles, especially #3 (high perceived value, low time investment — consumable in under 30 minutes, ideally under 10). Should warn 50 pages may signal too much effort to consume — flag this as a possible cause. Should recommend A/B testing the format (chunking the ebook into a 5-part email mini-course, releasing as a checklist + ebook combo, or breaking into shorter topic-specific guides). Should review landing page structure: headline, preview/mockup, what's inside, social proof, form fields, FAQ. Should suggest testing partial gate (preview first 5 pages) vs full gate. Should ask about traffic source — 4% on cold traffic might be acceptable while 4% on warm traffic is low. Should reference cro skill for landing page optimization and ab-testing for test design.",

"assertions": [

"Diagnoses likely cause as length/effort mismatch",

"Recommends format A/B test",

"Suggests breaking into shorter formats",

"Reviews landing page structure",

"Asks about traffic source (cold vs warm)",

"Cross-references cro or ab-testing skill"

"files": []

{

"id": 3,

"prompt": "Our lead form asks for name, email, company, role, company size, and phone. We're not getting enough signups. Could the form be the problem?",

"expected_output": "Should immediately flag form length as a likely culprit. Should cite the rule of thumb: every extra field reduces conversion 5-10%. Should recommend reducing to the minimum needed: ideally email only (highest conversion), or email + name if personalization matters. Should explain when multi-field is justified (only for high-value offers like webinars or demos). Should ask what information is actually used in follow-up — fields that aren't used should be removed. Should suggest progressive profiling: capture email now, ask for more fields later via enrichment or follow-up forms. Should reference cro skill for form optimization specifically.",

"assertions": [

"Flags form length as likely culprit",

"Cites 5-10% per field rule",

"Recommends reducing to email or email + name",

"Asks what fields are actually used",

"Suggests progressive profiling",

"Cross-references cro skill"

"files": []

{

"id": 4,

"prompt": "What's the difference between a lead magnet and a free tool? Should I build one or the other?",

"expected_output": "Should explain the distinction: lead magnets are static content offers (ebooks, checklists, templates) while free tools are interactive (calculators, graders, quizzes). Should explain when to build which. Lead magnets: faster to ship (hours-days), works well for awareness/consideration education, lower ongoing maintenance, lead quality varies. Free tools: longer build time (weeks-months), higher engagement and shareability, naturally segment leads by tool usage, can rank for SEO ('X calculator', 'Y grader'), higher lead quality typically. Should recommend lead magnet first if speed matters, free tool if you can invest the build time and have repeatable user inputs that produce a meaningful output. Should defer to free-tools skill for tool strategy specifically.",

"assertions": [

"Distinguishes static content from interactive tool",

"Compares effort to build",

"Compares SEO and shareability characteristics",

"Recommends based on speed vs investment trade-off",

"Defers to free-tools skill"

"files": []

{

"id": 5,

"prompt": "We have a top-performing blog post on email subject lines. Can we use it as a lead magnet?",

"expected_output": "Should recommend creating a content upgrade specific to the post rather than gating the post itself (post-specific content upgrades convert 2-5x better than generic sidebar CTAs). Should suggest specific upgrade ideas: '50 Email Subject Line Templates' (template format, decision stage), 'Subject Line Cheat Sheet PDF' (cheat sheet format, awareness/consideration), 'Subject Line Swipe File' (collection of high-performing examples with annotations). Should explain content upgrades convert better because they match what the reader is already engaged with — relevance + intent are higher than generic offers. Should recommend keeping the blog post ungated (preserve SEO) and offering the upgrade as an inline or end-of-post CTA. Should reference cro for placement and copywriting for the upgrade itself.",

"assertions": [

"Recommends content upgrade over gating the post",

"Cites 2-5x improvement vs generic CTAs",

"Suggests specific upgrade formats with rationale",

"Keeps blog post ungated to preserve SEO",

"Explains why upgrades convert better"

"files": []

{

"id": 6,

"prompt": "Our checklist gets a lot of downloads but very few of them ever sign up for a trial. Is the lead magnet broken?",

"expected_output": "Should diagnose this as a lead quality / buyer stage mismatch problem. Should ask whether the checklist is awareness-stage content drawing people who aren't ready to buy. Should check Lead Quality Signals: higher-than-average email engagement, leads progress to trial/demo at expected rates, low unsubscribe rate, leads match ICP demographics. Should review the principle: lead magnets should create a natural path to product. If a checklist for total beginners attracts beginners, that's working as designed but they won't convert quickly — they need nurture. Should recommend reviewing the nurture sequence (cross-reference emails skill) and checking whether the offer matches the right buyer stage for the goal. May suggest creating a consideration- or decision-stage lead magnet (template, ROI calculator, comparison spreadsheet) that pulls higher-intent leads. Should track time to conversion by lead magnet source.",

"assertions": [

"Diagnoses as lead quality / buyer stage mismatch",

"Asks about ICP fit of leads",

"References Lead Quality Signals",

"Cross-references emails skill for nurture",

"Suggests a decision-stage lead magnet alternative",

"Mentions tracking time to conversion by source"

"files": []

}

]

}

mdskills/lead-magnets/references/benchmarks.md

4.1 kB

# Lead Magnet Benchmarks

Reference data for planning and evaluating lead magnet performance.

---

## Conversion Rate Benchmarks

### By Format Type

| 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 |

### By Traffic Source

| 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 |

### By Industry (Landing Page)

| 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% |

---

## Lead Quality Indicators

### Signals of High-Quality Leads

- Open first 3 emails at 40%+ rate

- Click through to content or product pages

- Return to site within 30 days

- Match ICP demographics (role, company size, industry)

- Progress to trial, demo, or purchase within 90 days

### Signals of Low-Quality Leads

- Unsubscribe within first 3 emails

- Never open beyond delivery email

- Use disposable email addresses

- Don't match target customer profile

- Downloaded for the content, no product interest

### Quality vs. Quantity by Format

|--------|-------------|-------------|-----------|

---

## Cost Benchmarks

### Cost Per Lead by Channel

| 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 |

### Creation Cost by Format

| 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 |

---

## Timeline Expectations

### Time to Create

| 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 |

### Time to See Results

| 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.

mdskills/lead-magnets/references/format-guide.md

5.7 kB

# Lead Magnet Format Guide

Detailed creation guidance for each lead magnet format.

## Contents

- Ebooks & Guides

- Checklists

- Cheat Sheets

- Templates & Spreadsheets

- Swipe Files

- Mini-Courses

- Quizzes & Assessments

- Webinars & Workshops

---

## Ebooks & Guides

**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

---

## Checklists

**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

---

## Cheat Sheets

**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

---

## Templates & Spreadsheets

**Best for**: Repeatable processes, planning, tracking

### Spreadsheet Templates (Google Sheets / Excel)

- Include a "How to Use" tab with instructions

- Pre-fill with example data

- Use data validation for dropdown fields

- Add conditional formatting for visual cues

- Lock formula cells, leave input cells editable

- Include a "Make a Copy" link (Google Sheets)

### Notion Templates

- Provide a duplicate link

- Include a getting-started guide

- Pre-populate with example content

- Use Notion's database features (views, filters, relations)

- Keep it simple — don't over-engineer

### Document Templates

- Provide in multiple formats (Google Doc, Word, PDF)

- Include placeholder text with [BRACKETS] for customization

- Add inline instructions in a different color

- Make it immediately usable with minimal editing

**Key principle**: Templates should be usable within 5 minutes of downloading.

---

## Swipe Files

**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

---

## Mini-Courses

### Email-Based Mini-Courses

- 3-5 emails delivered over 5-7 days

- One lesson per email, one concept per lesson

- Each email: teach → example → exercise

- Progressive difficulty (build on previous lessons)

- Final email: summary + CTA for product or next step

### Video-Based Mini-Courses

- 3-5 videos, 5-15 minutes each

- Host on unlisted YouTube, Loom, or course platform

- Deliver links via email drip

- Include worksheets or exercises per lesson

- More personal — builds stronger connection

**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.

---

## Quizzes & Assessments

**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.

---

## Webinars & Workshops

### Live Webinars

- 30-45 minutes teaching + 15 minutes Q&A

- Structure: Hook → Teach (3 key points) → Demo/example → CTA

- Promote 1-2 weeks in advance

- Send 3 reminder emails (confirmation, day before, 1 hour before)

- Record for replay (extends value)

### Evergreen Webinars

- Pre-recorded, available on demand

- Same structure as live but tighter editing

- Always-on lead generation

- Gate with email registration

- Automated follow-up sequence

**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.

mdskills/lead-magnets/SKILL.md

11 kB

---

description: 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 sheet," "checklist," "template download," "opt-in," "freebie," "PDF download," "resource library," "content offer," "email capture content," "Notion template," "spreadsheet template," or "what should I give away for emails." Use this for planning what to create and how to distribute it. For interactive tools as lead magnets, see free-tools. For writing the actual content, see copywriting. For the email sequence after capture, see emails.

metadata:

version: 2.0.0

---

# Lead Magnets

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.

## Before Planning

**Check for product marketing context first:**

Gather this context (ask if not provided):

### 1. Business Context

- What does the company do?

- Who is the ideal customer?

- What problems does your product solve?

### 2. Current Lead Generation

- How do you currently capture leads?

- What lead magnets or offers do you have?

- What's your current conversion rate on email capture?

### 3. Content Assets

- What existing content could be repurposed? (blog posts, guides, data)

- What expertise can you package?

- What templates or tools do you use internally?

### 4. Goals

- Primary goal: email list growth, lead quality, product education?

- Target audience stage: awareness, consideration, or decision?

- Timeline and resource constraints?

---

## Lead Magnet Principles

### 1. Solve a Specific Problem

- Address one clear pain point, not a broad topic

- "How to write cold emails that get replies" > "Marketing guide"

### 2. Match the Buyer Stage

- Awareness leads need education

- Consideration leads need comparison and evaluation

- Decision leads need implementation help

### 3. High Perceived Value, Low Time Investment

- Should look like it's worth paying for

- Consumable in under 30 minutes (ideally under 10)

- Immediate, actionable takeaway

### 4. Natural Path to Product

- Solves a problem your product also solves

- Creates awareness of a gap your product fills

- Demonstrates your expertise in the space

### 5. Easy to Consume

- One clear format (don't mix ebook + video + spreadsheet)

- Works on mobile

- No special software required

---

## Lead Magnet Types

|------|----------|--------|----------------|

**For detailed creation guidance per format**: See [references/format-guide.md](references/format-guide.md)

---

## Matching Lead Magnets to Buyer Stage

### Awareness Stage

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?" |

### Consideration Stage

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" |

### Decision Stage

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**) |

---

## Gating Strategy

### Gating Options

| 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 |

### What to Ask For

- **Email only** — highest conversion, lowest friction

- **Email + name** — enables personalization, slight friction increase

- **Email + company/role** — better lead qualification, more friction

- **Multi-field** — only for high-value offers (webinars, demos)

Rule of thumb: Ask for the minimum needed. Every extra field reduces conversion by 5-10%.

### How to Frame the Exchange

- Make the value obvious: "Get the full 25-page guide free"

- Show a preview: table of contents, first page, sample results

- Add social proof: "Downloaded by 5,000+ marketers"

- Reduce risk: "No spam. Unsubscribe anytime."

**For form optimization**: See **cro** skill

**For popup implementation**: See **popups** skill

---

## Landing Page & Delivery

### Landing Page Structure

1. **Headline** — Clear benefit: what they'll get and why it matters

2. **Preview/mockup** — Visual of the lead magnet (cover, screenshot, sample page)

3. **What's inside** — 3-5 bullet points of key takeaways

4. **Social proof** — Download count, testimonials, logos

5. **Form** — Minimal fields, clear CTA button

6. **FAQ** — Address hesitations (Is it really free? What format?)

**For landing page optimization**: See **cro** skill

### Delivery Methods

| 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 |

### Thank You Page Optimization

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

---

## Promotion & Distribution

### Blog CTAs & Content Upgrades

- Add relevant CTAs within blog posts (inline, end-of-post)

- Create post-specific content upgrades (bonus checklist for a how-to post)

- Content upgrades convert 2-5x better than generic sidebar CTAs

### Exit-Intent & Popups

- Trigger on exit intent or scroll depth

- Match the popup offer to the page content

- **See popups** for implementation

### Social Media

- Share snippets and teasers from the lead magnet

- Create carousel posts from key points

- Use the lead magnet as the CTA in your bio/profile

- **See social** for social strategy

### Paid Promotion

- Facebook/Instagram lead ads for top-funnel lead magnets

- Google Ads for high-intent lead magnets (templates, tools)

- LinkedIn for B2B lead magnets

- Retarget blog visitors with lead magnet ads

- **See ads** for campaign strategy

### Partner Co-Promotion

- Cross-promote with complementary brands

- Guest webinars with partner audiences

- Include in partner newsletters

- Bundle in resource collections

---

## Measuring Success

### Key Metrics

| 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](references/benchmarks.md)

### A/B Testing Ideas

- **Headline**: Benefit-focused vs. curiosity-driven

- **Format**: Checklist vs. guide on same topic

- **Gate level**: Full gate vs. partial preview

- **Form fields**: Email-only vs. email + name

- **CTA copy**: "Download Free Guide" vs. "Get Your Copy"

- **Delivery**: Instant download vs. email delivery

### Lead Quality Signals

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

---

## Output Format

When creating a lead magnet strategy, provide:

### 1. Lead Magnet Recommendation

- Format and topic

- Target buyer stage

- Why this format for this audience

- Estimated creation effort

### 2. Content Outline

- Key sections/components

- Length and scope

- What makes it unique or valuable

### 3. Gating & Capture Plan

- What to gate and how

- Form fields

- Landing page structure

### 4. Distribution Plan

- Promotion channels

- Content upgrade opportunities

- Paid amplification (if applicable)

### 5. Measurement Plan

- KPIs and targets

- What to A/B test first

---

## Task-Specific Questions

1. What existing content or expertise could you turn into a lead magnet?

2. Where does your audience spend time online?

3. What's the most common question prospects ask before buying?

4. Do you have an email nurture sequence set up for new leads?

5. What's your budget for design and promotion?

---

## Related Skills

- **free-tools**: For interactive tools as lead magnets (calculators, graders, quizzes)

- **copywriting**: For writing the lead magnet content itself

- **emails**: For nurture sequences after lead capture

- **cro**: For optimizing lead magnet landing pages

- **popups**: For popup-based lead capture

- **cro**: For optimizing capture forms

- **content-strategy**: For content planning and topic selection

- **analytics**: For measuring lead magnet performance

- **ads**: For paid promotion of lead magnets

- **social**: For social media promotion

jsonskills/marketing-ideas/evals/evals.json

5.8 kB

{

"skill_name": "marketing-ideas",

"evals": [

{

"id": 1,

"prompt": "I need marketing ideas for my SaaS product. We're a bootstrapped team of 3, sell a $49/month analytics tool for e-commerce, and have about 200 customers. Budget is tight — maybe $500/month for marketing.",

"expected_output": "Should check for product-marketing.md first. Should filter ideas by low budget and early-stage constraints. Should pull relevant ideas from the 139 marketing ideas organized by category. Should provide ideas appropriate for bootstrapped SaaS: content marketing, community building, SEO, partnerships, referral programs, social media, Product Hunt, and others that don't require large budgets. Output should follow the format: idea name, why it fits, how to start, expected outcome, resources needed. Should prioritize by likely impact given their stage.",

"assertions": [

"Checks for product-marketing.md",

"Filters ideas by low budget constraint",

"Provides ideas from the 139 marketing ideas catalog",

"Ideas are appropriate for bootstrapped SaaS stage",

"Output follows structured format per idea",

"Includes why it fits, how to start, expected outcome",

"Prioritizes by likely impact",

"Includes resources needed per idea"

"files": []

{

"id": 2,

"prompt": "What's the fastest way to get more leads? We sell enterprise security software and have a $10k/month marketing budget.",

"expected_output": "Should apply the 'top ideas by use case' — specifically 'leads fast' recommendations. Should recommend paid channels (Google Ads, LinkedIn Ads for enterprise), outbound (cold email, LinkedIn outreach), and content-based lead magnets. Should filter for enterprise-appropriate tactics. Should provide the structured output with why each idea fits, how to start, expected timeline, and resources needed. Should note that 'fast leads' typically means paid or outbound channels.",

"assertions": [

"Applies 'leads fast' use case filter",

"Recommends paid channels appropriate for enterprise",

"Recommends outbound tactics",

"Filters for enterprise-appropriate tactics",

"Provides structured output per idea",

"Notes that fast leads means paid or outbound",

"Includes timeline expectations"

"files": []

{

"id": 3,

"prompt": "how do we grow without spending money on ads? we're a PLG (product-led growth) company with a freemium model",

"expected_output": "Should trigger on casual phrasing. Should apply the 'PLG' use case filter from top ideas. Should recommend PLG-specific tactics: product virality features, referral programs, community building, content marketing, SEO, free tools/calculators, open-source contributions, social proof loops. Should avoid ad-dependent ideas given the constraint. Should provide structured output with implementation guidance.",

"assertions": [

"Triggers on casual phrasing",

"Applies PLG use case filter",

"Recommends PLG-specific tactics",

"Avoids ad-dependent ideas",

"Includes virality and referral tactics",

"Provides structured output with implementation guidance"

"files": []

{

"id": 4,

"prompt": "We want to build authority and thought leadership in the HR tech space. We're a newer company and nobody knows who we are yet.",

"expected_output": "Should apply the 'authority building' use case filter. Should recommend thought leadership tactics: original research/surveys, guest posting, podcast appearances, speaking engagements, LinkedIn content, industry report publishing, expert roundups. Should note that authority building is a longer-term play. Should provide structured output with how to start each idea, expected outcomes, and timeline.",

"assertions": [

"Applies 'authority building' use case filter",

"Recommends thought leadership tactics",

"Includes original research and content",

"Includes community and media appearances",

"Notes authority building is longer-term",

"Provides structured output with timelines"

"files": []

{

"id": 5,

"prompt": "Give me 20 marketing ideas. We sell project management software.",

"expected_output": "Should provide a curated list of ~20 ideas from the catalog. Should organize them by category or by effort/impact. Should provide brief implementation context for each. Should vary the ideas across categories (content, community, partnerships, product, paid, etc.) for a well-rounded set. Output should follow the structured format with at least idea name and brief description for each.",

"assertions": [

"Provides approximately 20 ideas",

"Ideas span multiple categories",

"Organizes by category or effort/impact",

"Provides brief implementation context per idea",

"Output follows structured format",

"Ideas are relevant to project management software"

"files": []

{

"id": 6,

"prompt": "We want to set up a referral program. How should we structure it?",

"expected_output": "Should recognize this is specifically a referral program design request. Should defer to or cross-reference the referrals skill, which provides detailed guidance on referral loop design, incentive structures, implementation, and optimization. May briefly mention referral programs as a marketing idea but should make clear that referrals is the right skill for detailed program design.",

"assertions": [

"Recognizes this as a referral program design request",

"References or defers to referrals skill",

"Does not attempt detailed referral program design",

"May briefly mention as a marketing idea"

"files": []

}

]

}

mdskills/marketing-ideas/references/ideas-by-category.md

15 kB

# The 139 Marketing Ideas

Complete list of proven marketing approaches organized by category.

## Contents

- Content & SEO (1-10)

- Competitor & Comparison (11-13)

- Free Tools & Engineering (14-22)

- Paid Advertising (23-34)

- Social Media & Community (35-44)

- Email Marketing (45-53)

- Partnerships & Programs (54-64)

- Events & Speaking (65-72)

- PR & Media (73-76)

- Launches & Promotions (77-86)

- Product-Led Growth (87-96)

- Content Formats (97-109)

- Unconventional & Creative (110-122)

- Platforms & Marketplaces (123-130)

- International & Localization (131-132)

- Developer & Technical (133-136)

- Audience-Specific (137-139)

## Content & SEO (1-10)

1. **Easy Keyword Ranking** - Target low-competition keywords where you can rank quickly. Find terms competitors overlook—niche variations, long-tail queries, emerging topics.

2. **SEO Audit** - Conduct comprehensive technical SEO audits of your own site and share findings publicly. Document fixes and improvements to build authority.

3. **Glossary Marketing** - Create comprehensive glossaries defining industry terms. Each term becomes an SEO-optimized page targeting "what is X" searches.

4. **Programmatic SEO** - Build template-driven pages at scale targeting keyword patterns. Location pages, comparison pages, integration pages—any pattern with search volume.

5. **Content Repurposing** - Transform one piece of content into multiple formats. Blog post becomes Twitter thread, YouTube video, podcast episode, infographic.

6. **Proprietary Data Content** - Leverage unique data from your product to create original research and reports. Data competitors can't replicate creates linkable assets.

7. **Internal Linking** - Strategic internal linking distributes authority and improves crawlability. Build topical clusters connecting related content.

8. **Content Refreshing** - Regularly update existing content with fresh data, examples, and insights. Refreshed content often outperforms new content.

9. **Knowledge Base SEO** - Optimize help documentation for search. Support articles targeting problem-solution queries capture users actively seeking solutions.

10. **Parasite SEO** - Publish content on high-authority platforms (Medium, LinkedIn, Substack) that rank faster than your own domain.

---

## Competitor & Comparison (11-13)

11. **Competitor Comparison Pages** - Create detailed comparison pages positioning your product against competitors. "[Your Product] vs [Competitor]" pages capture high-intent searchers.

12. **Marketing Jiu-Jitsu** - Turn competitor weaknesses into your strengths. When competitors raise prices, launch affordability campaigns.

13. **Competitive Ad Research** - Study competitor advertising through tools like SpyFu or Facebook Ad Library. Learn what messaging resonates.

---

## Free Tools & Engineering (14-22)

14. **Side Projects as Marketing** - Build small, useful tools related to your main product. Side projects attract users who may later convert.

15. **Engineering as Marketing** - Build free tools that solve real problems. Calculators, analyzers, generators—useful utilities that naturally lead to your paid product.

16. **Importers as Marketing** - Build import tools for competitor data. "Import from [Competitor]" reduces switching friction.

17. **Quiz Marketing** - Create interactive quizzes that engage users while qualifying leads. Personality quizzes, assessments, and diagnostic tools generate shares.

18. **Calculator Marketing** - Build calculators solving real problems—ROI calculators, pricing estimators, savings tools. Calculators attract links and rank well.

19. **Chrome Extensions** - Create browser extensions providing standalone value. Chrome Web Store becomes another distribution channel.

20. **Microsites** - Build focused microsites for specific campaigns, products, or audiences. Dedicated domains can rank faster.

21. **Scanners** - Build free scanning tools that audit or analyze something. Website scanners, security checkers, performance analyzers.

22. **Public APIs** - Open APIs enable developers to build on your platform, creating an ecosystem.

---

## Paid Advertising (23-34)

23. **Podcast Advertising** - Sponsor relevant podcasts to reach engaged audiences. Host-read ads perform especially well.

24. **Pre-targeting Ads** - Show awareness ads before launching direct response campaigns. Warm audiences convert better.

25. **Facebook Ads** - Meta's detailed targeting reaches specific audiences. Test creative variations and leverage retargeting.

26. **Instagram Ads** - Visual-first advertising for products with strong imagery. Stories and Reels ads capture attention.

27. **Twitter Ads** - Reach engaged professionals discussing industry topics. Promoted tweets and follower campaigns.

28. **LinkedIn Ads** - Target by job title, company size, and industry. Premium CPMs justified by B2B purchase intent.

29. **Reddit Ads** - Reach passionate communities with authentic messaging. Transparency wins on Reddit.

30. **Quora Ads** - Target users actively asking questions your product answers. Intent-rich environment.

31. **Google Ads** - Capture high-intent search queries. Brand terms, competitor terms, and category terms.

32. **YouTube Ads** - Video ads with detailed targeting. Pre-roll and discovery ads reach users consuming related content.

33. **Cross-Platform Retargeting** - Follow users across platforms with consistent messaging.

34. **Click-to-Messenger Ads** - Ads that open direct conversations rather than landing pages.

---

## Social Media & Community (35-44)

35. **Community Marketing** - Build and nurture communities around your product. Slack groups, Discord servers, Facebook groups.

36. **Quora Marketing** - Answer relevant questions with genuine expertise. Include product mentions where naturally appropriate.

37. **Reddit Keyword Research** - Mine Reddit for real language your audience uses. Discover pain points and desires.

38. **Reddit Marketing** - Participate authentically in relevant subreddits. Provide value first.

39. **LinkedIn Audience** - Build personal brands on LinkedIn for B2B reach. Thought leadership builds authority.

40. **Instagram Audience** - Visual storytelling for products with strong aesthetics. Behind-the-scenes and user stories.

41. **X Audience** - Build presence on X/Twitter through consistent value. Threads and insights grow followings.

42. **Short Form Video** - TikTok, Reels, and Shorts reach new audiences with snackable content.

43. **Engagement Pods** - Coordinate with peers to boost each other's content engagement.

44. **Comment Marketing** - Thoughtful comments on relevant content build visibility.

---

## Email Marketing (45-53)

45. **Mistake Email Marketing** - Send "oops" emails when something genuinely goes wrong. Authenticity generates engagement.

46. **Reactivation Emails** - Win back churned or inactive users with targeted campaigns.

47. **Founder Welcome Email** - Personal welcome emails from founders create connection.

48. **Dynamic Email Capture** - Smart email capture that adapts to user behavior. Exit intent, scroll depth triggers.

49. **Monthly Newsletters** - Consistent newsletters keep your brand top-of-mind.

50. **Inbox Placement** - Technical email optimization for deliverability. Authentication and list hygiene.

51. **Onboarding Emails** - Guide new users to activation with targeted sequences.

52. **Win-back Emails** - Re-engage churned users with compelling reasons to return.

53. **Trial Reactivation** - Expired trials aren't lost causes. Targeted campaigns can recover them.

---

## Partnerships & Programs (54-64)

54. **Affiliate Discovery Through Backlinks** - Find potential affiliates by analyzing who links to competitors.

55. **Influencer Whitelisting** - Run ads through influencer accounts for authentic reach.

56. **Reseller Programs** - Enable agencies to resell your product. White-label options create distribution partners.

57. **Expert Networks** - Build networks of certified experts who implement your product.

58. **Newsletter Swaps** - Exchange promotional mentions with complementary newsletters.

59. **Article Quotes** - Contribute expert quotes to journalists. HARO connects experts with writers.

60. **Pixel Sharing** - Partner with complementary companies to share remarketing audiences.

61. **Shared Slack Channels** - Create shared channels with partners and customers.

62. **Affiliate Program** - Structured commission programs for referrers.

63. **Integration Marketing** - Joint marketing with integration partners.

64. **Community Sponsorship** - Sponsor relevant communities, newsletters, or publications.

---

## Events & Speaking (65-72)

65. **Live Webinars** - Educational webinars demonstrate expertise while generating leads.

66. **Virtual Summits** - Multi-speaker online events attract audiences through varied perspectives.

67. **Roadshows** - Take your product on the road to meet customers directly.

68. **Local Meetups** - Host or attend local meetups in key markets.

69. **Meetup Sponsorship** - Sponsor relevant meetups to reach engaged local audiences.

70. **Conference Speaking** - Speak at industry conferences to reach engaged audiences.

71. **Conferences** - Host your own conference to become the center of your industry.

72. **Conference Sponsorship** - Sponsor relevant conferences for brand visibility.

---

## PR & Media (73-76)

73. **Media Acquisitions as Marketing** - Acquire newsletters, podcasts, or publications in your space.

74. **Press Coverage** - Pitch newsworthy stories to relevant publications.

75. **Fundraising PR** - Leverage funding announcements for press coverage.

76. **Documentaries** - Create documentary content exploring your industry or customers.

---

## Launches & Promotions (77-86)

77. **Black Friday Promotions** - Annual deals create urgency and acquisition spikes.

78. **Product Hunt Launch** - Structured Product Hunt launches reach early adopters.

79. **Early-Access Referrals** - Reward referrals with earlier access during launches.

80. **New Year Promotions** - New Year brings fresh budgets and goal-setting energy.

81. **Early Access Pricing** - Launch with discounted early access tiers.

82. **Product Hunt Alternatives** - Launch on BetaList, Launching Next, AlternativeTo.

83. **Twitter Giveaways** - Engagement-boosting giveaways that require follows or retweets.

84. **Giveaways** - Strategic giveaways attract attention and capture leads.

85. **Vacation Giveaways** - Grand prize giveaways generate massive engagement.

86. **Lifetime Deals** - One-time payment deals generate cash and users.

---

## Product-Led Growth (87-96)

87. **Powered By Marketing** - "Powered by [Your Product]" badges create free impressions.

88. **Free Migrations** - Offer free migration services from competitors.

89. **Contract Buyouts** - Pay to exit competitor contracts.

90. **One-Click Registration** - Minimize signup friction with OAuth options.

91. **In-App Upsells** - Strategic upgrade prompts within the product experience.

92. **Newsletter Referrals** - Built-in referral programs for newsletters.

93. **Viral Loops** - Product mechanics that naturally encourage sharing.

94. **Offboarding Flows** - Optimize cancellation flows to retain or learn.

95. **Concierge Setup** - White-glove onboarding for high-value accounts.

96. **Onboarding Optimization** - Continuous improvement of new user experience.

---

## Content Formats (97-109)

97. **Playlists as Marketing** - Create Spotify playlists for your audience.

98. **Template Marketing** - Offer free templates users can immediately use.

99. **Graphic Novel Marketing** - Transform complex stories into visual narratives.

100. **Promo Videos** - High-quality promotional videos showcase your product.

101. **Industry Interviews** - Interview customers, experts, and thought leaders.

102. **Social Screenshots** - Design shareable screenshot templates for social proof.

103. **Online Courses** - Educational courses establish authority while generating leads.

104. **Book Marketing** - Author a book establishing expertise in your domain.

105. **Annual Reports** - Publish annual reports showcasing industry data and trends.

106. **End of Year Wraps** - Personalized year-end summaries users want to share.

107. **Podcasts** - Launch a podcast reaching audiences during commutes.

108. **Changelogs** - Public changelogs showcase product momentum.

109. **Public Demos** - Live product demonstrations showing real usage.

---

## Unconventional & Creative (110-122)

110. **Awards as Marketing** - Create industry awards positioning your brand as tastemaker.

111. **Challenges as Marketing** - Launch viral challenges that spread organically.

112. **Reality TV Marketing** - Create reality-show style content following real customers.

113. **Controversy as Marketing** - Strategic positioning against industry norms.

114. **Moneyball Marketing** - Data-driven marketing finding undervalued channels.

115. **Curation as Marketing** - Curate valuable resources for your audience.

116. **Grants as Marketing** - Offer grants to customers or community members.

117. **Product Competitions** - Sponsor competitions using your product.

118. **Cameo Marketing** - Use Cameo celebrities for personalized messages.

119. **OOH Advertising** - Out-of-home advertising—billboards, transit ads.

120. **Marketing Stunts** - Bold, attention-grabbing marketing moments.

121. **Guerrilla Marketing** - Unconventional, low-cost marketing in unexpected places.

122. **Humor Marketing** - Use humor to stand out and create memorability.

---

## Platforms & Marketplaces (123-130)

123. **Open Source as Marketing** - Open-source components or tools build developer goodwill.

124. **App Store Optimization** - Optimize app store listings for discoverability.

125. **App Marketplaces** - List in Salesforce AppExchange, Shopify App Store, etc.

126. **YouTube Reviews** - Get YouTubers to review your product.

127. **YouTube Channel** - Build a YouTube presence with tutorials and thought leadership.

128. **Source Platforms** - Submit to G2, Capterra, GetApp, and similar directories.

129. **Review Sites** - Actively manage presence on review platforms.

130. **Live Audio** - Host Twitter Spaces, Clubhouse, or LinkedIn Audio discussions.

---

## International & Localization (131-132)

131. **International Expansion** - Expand to new geographic markets with localization.

132. **Price Localization** - Adjust pricing for local purchasing power.

---

## Developer & Technical (133-136)

133. **Investor Marketing** - Market to investors for portfolio introductions.

134. **Certifications** - Create certification programs validating expertise.

135. **Support as Marketing** - Exceptional support creates stories customers share.

136. **Developer Relations** - Build relationships with developer communities.

---

## Audience-Specific (137-139)

137. **Two-Sided Referrals** - Reward both referrer and referred.

138. **Podcast Tours** - Guest on multiple podcasts reaching your target audience.

139. **Customer Language** - Use the exact words your customers use in marketing.

mdskills/marketing-ideas/SKILL.md

5.0 kB

---

description: "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 tactics,' 'ways to promote,' 'ideas to grow,' 'what else can I try,' 'I don't know how to market this,' 'brainstorm marketing,' or 'what marketing should I do.' Use this as a starting point whenever someone is stuck or looking for inspiration on how to grow. For specific channel execution, see the relevant skill (ads, social, emails, etc.)."

metadata:

version: 2.0.0

---

# Marketing Ideas for SaaS

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.

## How to Use This Skill

**Check for product marketing context first:**

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)

---

## Ideas by Category (Quick Reference)

| 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 |

| Email | 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](references/ideas-by-category.md)

---

## Implementation Tips

### By Stage

**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)

### By Budget

**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

### By Timeline

**Quick wins:**

- Ads, email, social posts

**Medium-term:**

- Content, SEO, community

**Long-term:**

- Brand, thought leadership, platform effects

---

## Top Ideas by Use Case

### Need Leads Fast

- Google Ads (#31) - High-intent search

- LinkedIn Ads (#28) - B2B targeting

- Engineering as Marketing (#15) - Free tool lead gen

### Building Authority

- Conference Speaking (#70)

- Book Marketing (#104)

- Podcasts (#107)

### Low Budget Growth

- Easy Keyword Ranking (#1)

- Reddit Marketing (#38)

- Comment Marketing (#44)

### Product-Led Growth

- Viral Loops (#93)

- Powered By Marketing (#87)

- In-App Upsells (#91)

### Enterprise Sales

- Investor Marketing (#133)

- Expert Networks (#57)

- Conference Sponsorship (#72)

---

## Output Format

When recommending ideas, provide for each:

- **Idea name**: One-line description

- **Why it fits**: Connection to their situation

- **How to start**: First 2-3 implementation steps

- **Expected outcome**: What success looks like

- **Resources needed**: Time, budget, skills required

---

## Task-Specific Questions

1. What's your current stage and main growth goal?

2. What's your marketing budget and team size?

3. What have you already tried that worked or didn't?

4. What competitor tactics do you admire?

---

## Related Skills

- **programmatic-seo**: For scaling SEO content (#4)

- **competitors**: For comparison pages (#11)

- **emails**: For email marketing tactics

- **free-tools**: For engineering as marketing (#15)

- **referrals**: For viral growth (#93)

jsonskills/marketing-psychology/evals/evals.json

5.9 kB

{

"skill_name": "marketing-psychology",

"evals": [

{

"id": 1,

"prompt": "How can I use psychology to increase conversions on our pricing page? We sell a B2B SaaS tool with three tiers ($29, $79, $199/month).",

"expected_output": "Should check for product-marketing.md first. Should apply relevant pricing psychology models: anchoring (show the highest plan first or use a decoy), charm pricing (consider $29 vs $30), Rule of 100 (percentage vs dollar discounts), Good-Better-Best framing, loss aversion (show what they miss on lower tiers). Should also apply broader persuasion models: social proof near pricing, scarcity for limited-time offers, default effect (pre-select recommended plan). Should provide specific, actionable recommendations tied to their price points.",

"assertions": [

"Checks for product-marketing.md",

"Applies pricing psychology models (anchoring, charm pricing, Rule of 100)",

"Applies Good-Better-Best framing",

"Applies loss aversion to tier differentiation",

"Applies social proof near pricing",

"Provides specific recommendations for their price points",

"References specific mental models by name"

"files": []

{

"id": 2,

"prompt": "Explain the scarcity principle and how to use it ethically in SaaS marketing without being manipulative.",

"expected_output": "Should explain scarcity as a mental model (limited availability increases perceived value). Should provide legitimate SaaS applications: limited beta spots, early-bird pricing with real deadlines, limited-time feature access, cohort-based launches. Should distinguish ethical scarcity (real constraints) from manufactured urgency (fake countdown timers, artificial limits). Should provide specific examples and implementation guidance. Should reference related models (urgency, FOMO, loss aversion).",

"assertions": [

"Explains scarcity principle clearly",

"Provides legitimate SaaS applications",

"Distinguishes ethical from manipulative use",

"Provides specific examples",

"References related mental models",

"Addresses ethical considerations directly"

"files": []

{

"id": 3,

"prompt": "what psychological principles should I use to write better marketing copy?",

"expected_output": "Should trigger on casual phrasing. Should recommend copy-relevant mental models from the skill's taxonomy: social proof, reciprocity, loss aversion, anchoring, scarcity, IKEA Effect, Endowment Effect, Commitment & Consistency. For each principle, should explain what it is and provide a specific copywriting application. Should reference the quick reference table by challenge. Should organize by where in the copy each principle applies (headlines, body, CTAs, testimonials).",

"assertions": [

"Triggers on casual phrasing",

"Recommends copy-relevant mental models",

"Explains each principle briefly",

"Provides specific copywriting application per principle",

"Organizes by where each applies in copy",

"References multiple model categories"

"files": []

{

"id": 4,

"prompt": "I'm designing an onboarding flow and want to use behavioral psychology to increase activation. What models should I apply?",

"expected_output": "Should apply design and behavioral models from the skill's taxonomy: Goal-Gradient Effect (motivation increases near goal), Hick's Law (reduce choices), IKEA Effect (let users build something), Endowment Effect (let them experience ownership), Zeigarnik Effect (incomplete tasks drive completion), Commitment & Consistency (small asks first). Should explain how each applies to onboarding specifically. Should provide actionable recommendations for each model.",

"assertions": [

"Applies Goal-Gradient Effect",

"Applies Hick's Law",

"Applies IKEA Effect or Endowment Effect",

"Applies Zeigarnik Effect or commitment principles",

"Explains how each applies to onboarding",

"Provides actionable recommendations per model"

"files": []

{

"id": 5,

"prompt": "What's the psychology behind why free trials work better than freemium for some products?",

"expected_output": "Should apply relevant mental models: loss aversion (trial users fear losing access), endowment effect (they feel ownership after using), sunk cost (time invested during trial), Zero-Price Effect (free removes psychological barrier to start), status quo bias (inertia to keep what they have). Should explain how these models interact in trial vs freemium contexts. Should note when each model works best (trial for products with high activation effort, freemium for products with network effects).",

"assertions": [

"Applies loss aversion to trial context",

"Applies endowment effect",

"Applies Zero-Price Effect",

"Explains how models interact in trial vs freemium",

"Notes when each approach works best",

"Provides clear, educational explanation"

"files": []

{

"id": 6,

"prompt": "Help me run an A/B test on which psychological principle works better for our CTA — scarcity vs social proof.",

"expected_output": "Should recognize this is an A/B test setup task, not a psychology task. Should defer to or cross-reference the ab-testing skill for the experiment design. May provide psychological context on both principles to inform the hypothesis, but should make clear that ab-testing is the right skill for designing and running the experiment.",

"assertions": [

"Recognizes this as an A/B test setup task",

"References or defers to ab-testing skill",

"May provide psychological context for hypothesis",

"Does not attempt full test design using psychology patterns"

"files": []

}

]

}

mdskills/marketing-psychology/SKILL.md

21 kB

---

description: "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,' 'why people buy,' 'decision-making,' 'consumer behavior,' 'anchoring,' 'social proof,' 'scarcity,' 'loss aversion,' 'framing,' or 'nudge.' Use this whenever someone wants to understand or leverage how people think and make decisions in a marketing context. For applying psychology to specific pages, see cro; for pricing tactics, see pricing; for copy framing, see copywriting."

metadata:

version: 2.0.0

---

# Marketing Psychology & Mental Models

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.

## How to Use This Skill

**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:

1. Identify which mental models apply to their situation

2. Explain the psychology behind the model

3. Provide specific marketing applications

4. Suggest how to implement ethically

---

## Foundational Thinking Models

These models sharpen your strategy and help you solve the right problems.

### First Principles

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.

### Jobs to Be Done

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.

### Circle of Competence

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.

### Inversion

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.

### Occam's Razor

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.

### Pareto Principle (80/20 Rule)

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.

### Local vs. Global Optima

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.

### Theory of Constraints

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.

### Opportunity Cost

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.

### Law of Diminishing Returns

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.

### Second-Order Thinking

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).

### Map ≠ Territory

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.

### Probabilistic Thinking

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.

### Barbell Strategy

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.

---

## Understanding Buyers & Human Psychology

These models explain how customers think, decide, and behave.

### Fundamental Attribution Error

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.

### Mere Exposure Effect

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.

### Availability Heuristic

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.

### Confirmation Bias

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 Lindy Effect

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.

### Mimetic Desire

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.

### Sunk Cost Fallacy

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.

### Endowment Effect

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.

### IKEA Effect

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.

### Zero-Price Effect

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.

### Hyperbolic Discounting / Present Bias

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").

### Status-Quo Bias

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."

### Default Effect

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).

### Paradox of Choice

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.

### Goal-Gradient Effect

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.

### Peak-End Rule

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).

### Zeigarnik Effect

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.

### Pratfall Effect

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.

### Curse of Knowledge

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.

### Mental Accounting

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.

### Regret Aversion

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.

### Bandwagon Effect / Social Proof

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.

---

## Influencing Behavior & Persuasion

These models help you ethically influence customer decisions.

### Reciprocity Principle

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.

### Commitment & Consistency

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.

### Authority Bias

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.

### Liking / Similarity Bias

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.

### Unity Principle

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.

### Scarcity / Urgency Heuristic

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.

### Foot-in-the-Door Technique

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.

### Door-in-the-Face Technique

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.

### Loss Aversion / Prospect Theory

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."

### Anchoring Effect

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.

### Decoy Effect

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.

### Framing Effect

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.

### Contrast Effect

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.

---

## Pricing Psychology

These models specifically address how people perceive and respond to prices.

### Charm Pricing / Left-Digit Effect

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.

### Rounded-Price (Fluency) Effect

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).

### Rule of 100

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."

### Price Relativity / Good-Better-Best

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.

### Mental Accounting (Pricing)

Framing the same price differently changes perception.

**Marketing application**: "$1/day" feels cheaper than "$30/month." "Less than your morning coffee" reframes the expense.

---

## Design & Delivery Models

These models help you design effective marketing systems.

### Hick's Law

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.

### AIDA Funnel

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.

### Rule of 7

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.

### Nudge Theory / Choice Architecture

Small changes in how choices are presented significantly influence decisions.

**Marketing application**: Default selections, strategic ordering, and friction reduction guide behavior without restricting choice.

### BJ Fogg Behavior Model

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.

### EAST Framework

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).

### COM-B Model

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.

### Activation Energy

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.

### North Star Metric

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.

### The Cobra Effect

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.

---

## Growth & Scaling Models

These models explain how marketing compounds and scales.

### Feedback Loops

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.

### Compounding

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.

### Network Effects

A product becomes more valuable as more people use it.

**Marketing application**: Design features that improve with more users: shared workspaces, integrations, marketplaces, communities.

### Flywheel Effect

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.

### Switching Costs

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.

### Exploration vs. Exploitation

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.

### Critical Mass / Tipping Point

The threshold after which growth becomes self-sustaining.

**Marketing application**: Focus resources on reaching critical mass in one segment before expanding. Depth before breadth.

### Survivorship Bias

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.

---

## Quick Reference

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 |

---

## Task-Specific Questions

1. What specific behavior are you trying to influence?

2. What does your customer believe before encountering your marketing?

3. Where in the journey (awareness → consideration → decision) is this?

4. What's currently preventing the desired action?

5. Have you tested this with real customers?

---

## Related Skills

- **cro**: Apply psychology to page optimization

- **copywriting**: Write copy using psychological principles

- **popups**: Use triggers and psychology in popups

- **pricing-page optimization**: See cro for pricing psychology

- **ab-testing**: Test psychological hypotheses

jsonskills/onboarding/evals/evals.json

6.1 kB

{

"skill_name": "onboarding",

"evals": [

{

"id": 1,

"prompt": "Help me optimize our onboarding flow. We have a project management tool and only 30% of trial users create their first project within the first week. We need to get them to value faster.",

"expected_output": "Should check for product-marketing.md first. Should start by defining the activation/aha moment — in this case, creating a first project. Should evaluate the current time-to-value and identify friction points. Should recommend an onboarding flow approach (product-first, guided setup, or value-first). Should apply the checklist pattern (3-7 items for onboarding completion). Should address empty states as opportunities to guide users. Should provide experiment ideas for testing improvements. Should include measurement metrics.",

"assertions": [

"Checks for product-marketing.md",

"Defines the activation/aha moment",

"Evaluates time-to-value",

"Recommends onboarding flow approach",

"Applies checklist pattern with 3-7 items",

"Addresses empty states as opportunities",

"Provides experiment ideas",

"Includes measurement metrics"

"files": []

{

"id": 2,

"prompt": "What should our onboarding checklist include? We're a design collaboration tool. Users need to upload a design, invite a team member, and leave a comment to get full value.",

"expected_output": "Should apply the checklist pattern. Should include the 3 stated activation actions (upload design, invite team, leave comment). Should recommend 3-7 total items ordered by increasing commitment. Should suggest starting with the quickest win to build momentum. Should recommend progress indicators and completion rewards. Should address what happens when users skip items. Should provide specific UX recommendations for the checklist implementation.",

"assertions": [

"Applies checklist pattern",

"Includes the 3 stated activation actions",

"Limits to 3-7 total items",

"Orders by increasing commitment",

"Starts with quickest win",

"Recommends progress indicators",

"Addresses skipped items",

"Provides UX recommendations"

"files": []

{

"id": 3,

"prompt": "our users sign up but then never come back. like 50% don't even log in a second time. what do we do?",

"expected_output": "Should trigger on casual phrasing. Should address this as a stalled users problem. Should apply the handling stalled users framework: identify drop-off points, re-engagement triggers, multi-channel outreach (email, in-app, push). Should investigate root causes: is the first-run experience too complex? Is value not immediately apparent? Is the setup too long? Should recommend immediate improvements to the first session experience. Should suggest multi-channel onboarding (email sequences to bring them back). Should cross-reference emails for re-engagement emails.",

"assertions": [

"Triggers on casual phrasing",

"Applies stalled users framework",

"Identifies potential root causes for drop-off",

"Recommends first-session experience improvements",

"Suggests multi-channel onboarding",

"Cross-references emails for re-engagement",

"Provides specific re-engagement triggers"

"files": []

{

"id": 4,

"prompt": "How do we handle the empty state when a new user first logs in? Right now they just see a blank dashboard.",

"expected_output": "Should apply the empty states as opportunities guidance. Should recommend turning the blank dashboard into a guided experience: sample data to show what the product looks like populated, a clear first action CTA, contextual tips, or a quick-start wizard. Should provide specific recommendations for empty state design: what to show, what action to prompt, how to reduce the 'blank canvas paralysis.' Should reference patterns by product type if applicable.",

"assertions": [

"Applies empty states as opportunities guidance",

"Recommends alternatives to blank dashboard",

"Suggests sample data or templates",

"Provides clear first action CTA",

"Addresses blank canvas paralysis",

"Provides specific empty state design recommendations"

"files": []

{

"id": 5,

"prompt": "Should we use tooltips, a product tour, or a setup wizard for onboarding? What works best?",

"expected_output": "Should apply the tooltips/guided tours guidance. Should compare the approaches: tooltips (contextual, on-demand, less intrusive), product tours (guided walkthrough, can overwhelm), setup wizards (structured, ensures key setup steps). Should recommend based on product complexity and onboarding goals. Should note that the best approach often combines elements. Should provide best practices for each: tooltip fatigue avoidance, tour length limits, wizard step count. Should recommend testing different approaches.",

"assertions": [

"Compares tooltips, product tours, and setup wizards",

"Explains when each works best",

"Notes that combination approaches often work",

"Provides best practices for each",

"Addresses tooltip fatigue and tour length",

"Recommends testing different approaches"

"files": []

{

"id": 6,

"prompt": "Our signup form has 8 fields and people keep dropping off. Can you help us fix the signup flow?",

"expected_output": "Should recognize this is a signup flow optimization task, not post-signup onboarding. Should defer to or cross-reference the signup skill, which handles signup form optimization, field reduction, and registration flow design. Onboarding-cro covers what happens after signup. Should make this distinction clear.",

"assertions": [

"Recognizes this as signup flow optimization, not onboarding",

"References or defers to signup skill",

"Explains that onboarding covers post-signup",

"Does not attempt signup form redesign using onboarding patterns"

"files": []

}

]

}

mdskills/onboarding/references/experiments.md

7.6 kB

# Onboarding Experiment Ideas

Comprehensive list of A/B tests and experiments for user onboarding and activation.

## Contents

- Flow Simplification Experiments (reduce friction, step sequencing, progress & motivation)

- Guided Experience Experiments (product tours, CTA optimization, UI guidance)

- Personalization Experiments (user segmentation, dynamic content)

- Quick Wins & Engagement Experiments (time-to-value, motivation mechanics, support & help)

- Email & Multi-Channel Experiments (onboarding emails, email content, feedback loops)

- Re-engagement Experiments (stalled user recovery, return experience)

- Technical & UX Experiments (performance, mobile onboarding, accessibility)

- Metrics to Track

## Flow Simplification Experiments

### Reduce Friction

| 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 |

### Step Sequencing

| 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 |

### Progress & Motivation

| 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 |

---

## Guided Experience Experiments

### Product Tours

| 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 |

### CTA Optimization

| 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 |

### UI Guidance

| 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 |

---

## Personalization Experiments

### User Segmentation

| 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 |

### Dynamic Content

| 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 |

---

## Quick Wins & Engagement Experiments

### Time-to-Value

| 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 |

### Motivation Mechanics

| Test | Hypothesis |

|------|------------|

| Achievement badges | Gamification elements |

| Streaks | Consecutive day engagement |

| Leaderboards | Social comparison (if appropriate) |

| Rewards | Incentives for completion |

| Unlock mechanics | Features revealed progressively |

### Support & Help

| 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 |

---

## Email & Multi-Channel Experiments

### Onboarding Emails

| 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 |

### Email Content

| 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 |

### Feedback Loops

| 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 |

---

## Re-engagement Experiments

### Stalled User Recovery

| 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 |

### Return Experience

| 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 |

---

## Technical & UX Experiments

### Performance

| Test | Hypothesis |

|------|------------|

| Load time optimization | Faster = higher completion |

| Progressive loading | Perceived performance |

| Offline capability | Mobile experience |

| Error handling | Graceful failure recovery |

### Mobile Onboarding

| 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 |

### Accessibility

| Test | Hypothesis |

|------|------------|

| Screen reader support | Accessibility impact |

| Keyboard navigation | Non-mouse users |

| Color contrast | Visibility |

| Font sizing | Readability |

---

## Metrics to Track

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 |

mdskills/onboarding/SKILL.md

6.4 kB

---

description: 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 experience," "empty states," "onboarding checklist," "aha moment," "new user experience," "users aren't activating," "nobody completes setup," "low activation rate," "users sign up but don't use the product," "time to value," or "first session experience." Use this whenever users are signing up but not sticking around. For signup/registration optimization, see signup. For ongoing email sequences, see emails.

metadata:

version: 2.0.0

---

# Onboarding CRO

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.

## Initial Assessment

**Check for product marketing context first:**

Before providing recommendations, understand:

1. **Product Context** - What type of product? B2B or B2C? Core value proposition?

2. **Activation Definition** - What's the "aha moment"? What action indicates a user "gets it"?

3. **Current State** - What happens after signup? Where do users drop off?

---

## Core Principles

### 1. Time-to-Value Is Everything

Remove every step between signup and experiencing core value.

### 2. One Goal Per Session

Focus first session on one successful outcome. Save advanced features for later.

### 3. Do, Don't Show

Interactive > Tutorial. Doing the thing > Learning about the thing.

### 4. Progress Creates Motivation

Show advancement. Celebrate completions. Make the path visible.

---

## Defining Activation

### Find Your Aha Moment

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

### Activation Metrics

- % of signups who reach activation

- Time to activation

- Steps to activation

- Activation by cohort/source

---

## Onboarding Flow Design

### Immediate Post-Signup (First 30 Seconds)

| 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

### Onboarding Checklist Pattern

**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

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

### Tooltips and Guided Tours

**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

---

## Multi-Channel Onboarding

### Email + In-App Coordination

**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

---

## Handling Stalled Users

### Detection

Define "stalled" criteria (X days inactive, incomplete setup)

### Re-engagement Tactics

1. **Email sequence** - Reminder of value, address blockers, offer help

2. **In-app recovery** - Welcome back, pick up where left off

3. **Human touch** - For high-value accounts, personal outreach

---

## Measurement

### Key Metrics

| 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 |

### Funnel Analysis

Track drop-off at each step:

```

Signup → Step 1 → Step 2 → Activation → Retention

100% 80% 60% 40% 25%

```

Identify biggest drops and focus there.

---

## Output Format

### Onboarding Audit

For each issue: Finding → Impact → Recommendation → Priority

### Onboarding Flow Design

- Activation goal

- Step-by-step flow

- Checklist items (if applicable)

- Empty state copy

- Email sequence triggers

- Metrics plan

---

## Common Patterns by Product Type

| 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 |

---

## Experiment Ideas

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](references/experiments.md)

---

## Task-Specific Questions

1. What action most correlates with retention?

2. What happens immediately after signup?

3. Where do users currently drop off?

4. What's your activation rate target?

5. Do you have cohort analysis on successful vs. churned users?

---

## Related Skills

- **signup**: For optimizing the signup before onboarding

- **emails**: For onboarding email series

- **paywalls**: For converting to paid during/after onboarding

- **ab-testing**: For testing onboarding changes

jsonskills/paywalls/evals/evals.json

6.3 kB

{

"skill_name": "paywalls",

"evals": [

{

"id": 1,

"prompt": "Help me design the upgrade paywall for our project management tool. Free users can have 3 projects, and we want to show an upgrade screen when they try to create a 4th project.",

"expected_output": "Should check for product-marketing.md first. Should identify this as a usage limit trigger point. Should apply the paywall screen components: headline (communicate the value of upgrading, not just the limit), value demonstration (show what they get with paid plan), plan comparison (free vs paid), social proof, CTA (specific and action-oriented), and escape hatch (option to go back). Should provide specific copy recommendations. Should address the emotional state of the user at this moment (frustrated by the limit). Should warn against anti-patterns.",

"assertions": [

"Checks for product-marketing.md",

"Identifies as usage limit trigger",

"Applies paywall screen components framework",

"Includes headline, value demo, comparison, social proof, CTA",

"Provides specific copy recommendations",

"Addresses user's emotional state at the limit",

"Includes escape hatch option",

"Warns against anti-patterns"

"files": []

{

"id": 2,

"prompt": "Our free trial expires in 14 days and users see a generic 'Your trial has expired' screen. Upgrade rate from this screen is only 2%. How do we improve it?",

"expected_output": "Should identify this as a trial expiration trigger. Should apply the trial expiration paywall type guidance. Should recommend: show what they've built/accomplished during the trial (endowment effect), highlight specific features they used, show the value they'd lose, provide clear plan options, include social proof from similar users who upgraded. Should diagnose why 2% is low: likely a weak value prop, no personalization, no urgency or loss framing. Should provide specific redesign recommendations.",

"assertions": [

"Identifies as trial expiration trigger",

"Applies trial expiration paywall guidance",

"Recommends showing user's accomplishments during trial",

"Uses loss framing (what they'd lose)",

"Provides clear plan options",

"Includes social proof",

"Diagnoses why current 2% rate is low",

"Provides specific redesign recommendations"

"files": []

{

"id": 3,

"prompt": "when should we show upgrade prompts? we don't want to be annoying but we also need to convert free users to paid.",

"expected_output": "Should trigger on casual phrasing. Should apply the timing and frequency rules. Should recommend trigger points from the skill: feature gates (when they try a paid feature), usage limits (when they hit a threshold), value moments (when they've just experienced success), and natural transition points. Should address frequency capping to avoid being annoying. Should recommend the anti-patterns to avoid (blocking basic functionality, too frequent popups, dark patterns). Should provide a balanced approach that respects user experience while driving upgrades.",

"assertions": [

"Triggers on casual phrasing",

"Applies timing and frequency rules",

"Recommends specific trigger points",

"Addresses frequency capping",

"Warns against anti-patterns",

"Balances user experience with conversion goals",

"Provides specific recommendations for each trigger type"

"files": []

{

"id": 4,

"prompt": "Design a feature gate paywall. When free users click on 'Advanced Analytics' in our dashboard, we want to show them an upgrade prompt.",

"expected_output": "Should identify this as a feature gate trigger. Should apply the feature lock paywall type guidance. Should recommend: show a preview or screenshot of the advanced analytics feature, explain the specific benefit (not just 'this is a paid feature'), include a plan comparison relevant to analytics, provide a clear CTA to upgrade, and include an escape hatch to go back to basic analytics. Should recommend showing what insights they're missing. Should provide copy recommendations for the paywall screen.",

"assertions": [

"Identifies as feature gate trigger",

"Applies feature lock paywall guidance",

"Recommends showing preview of the feature",

"Explains specific benefit of the feature",

"Includes relevant plan comparison",

"Provides clear CTA and escape hatch",

"Provides copy recommendations"

"files": []

{

"id": 5,

"prompt": "What are common mistakes to avoid with in-app paywalls? I don't want to be pushy or make users feel tricked.",

"expected_output": "Should apply the anti-patterns section. Should cover: dark patterns (making it hard to find the close button, confusing opt-out language), conversion killers (blocking basic functionality, showing paywalls too early before value is demonstrated, no escape hatch), frequency issues (too many prompts, showing the same paywall repeatedly). Should provide positive alternatives for each anti-pattern. Should emphasize that good paywalls feel helpful, not pushy.",

"assertions": [

"Applies anti-patterns section",

"Covers dark patterns to avoid",

"Covers conversion killers",

"Covers frequency issues",

"Provides positive alternatives for each",

"Emphasizes helpful over pushy approach"

"files": []

{

"id": 6,

"prompt": "Can you help me optimize our public pricing page? We want more visitors to choose the Pro plan over the Basic plan.",

"expected_output": "Should recognize this is a public pricing page optimization task, not an in-app paywall task. Should defer to or cross-reference the cro skill for pricing page CRO. Paywall-upgrade-cro specifically handles in-app upgrade prompts for existing users, not public-facing pricing pages.",

"assertions": [

"Recognizes this as public pricing page optimization",

"References or defers to cro skill",

"Explains that paywalls is for in-app upgrade prompts",

"Does not attempt public pricing page optimization"

"files": []

}

]

}

mdskills/paywalls/references/experiments.md

5.3 kB

# Paywall Experiment Ideas

Comprehensive list of A/B tests and experiments for paywall optimization.

## Contents

- Trigger & Timing Experiments (When to Show, Trigger Type)

- Paywall Design Experiments (Layout & Format, Value Presentation, Visual Elements)

- Pricing Presentation Experiments (Price Display, Plan Options, Discounts & Offers)

- Copy & Messaging Experiments (Headlines, CTAs, Objection Handling)

- Trial & Conversion Experiments (Trial Structure, Trial Expiration, Upgrade Path)

- Personalization Experiments (Usage-Based, Segment-Specific)

- Frequency & UX Experiments (Frequency Capping, Dismiss Behavior)

## Trigger & Timing Experiments

### When to Show

- Test trigger timing: after aha moment vs. at feature attempt

- Early trial reminder (7 days) vs. late reminder (1 day before)

- Show after X actions completed vs. after X days

- Test soft prompts at different engagement thresholds

- Trigger based on usage patterns vs. time-based only

### Trigger Type

- Hard gate (can't proceed) vs. soft gate (preview + prompt)

- Feature lock vs. usage limit as primary trigger

- In-context modal vs. dedicated upgrade page

- Banner reminder vs. modal prompt

- Exit-intent on free plan pages

---

## Paywall Design Experiments

### Layout & Format

- Full-screen paywall vs. modal overlay

- Minimal paywall (CTA-focused) vs. feature-rich paywall

- Single plan display vs. plan comparison

- Image/preview included vs. text-only

- Vertical layout vs. horizontal layout on desktop

### Value Presentation

- Feature list vs. benefit statements

- Show what they'll lose (loss aversion) vs. what they'll gain

- Personalized value summary based on usage

- Before/after demonstration

- ROI calculator or value quantification

### Visual Elements

- Add product screenshots or previews

- Include short demo video or GIF

- Test illustration vs. product imagery

- Animated vs. static paywall

- Progress visualization (what they've accomplished)

---

## Pricing Presentation Experiments

### Price Display

- Show monthly vs. annual vs. both with toggle

- Highlight savings for annual ($ amount vs. % off)

- Price per day framing ("Less than a coffee")

- Show price after trial vs. emphasize "Start Free"

- Display price prominently vs. de-emphasize until click

### Plan Options

- Single recommended plan vs. multiple tiers

- Add "Most Popular" badge to target plan

- Test number of visible plans (2 vs. 3)

- Show enterprise/custom tier vs. hide it

- Include one-time purchase option alongside subscription

### Discounts & Offers

- First month/year discount for conversion

- Limited-time upgrade offer with countdown

- Loyalty discount based on free usage duration

- Bundle discount for annual commitment

- Referral discount for social proof

---

## Copy & Messaging Experiments

### Headlines

- Benefit-focused ("Unlock unlimited projects") vs. feature-focused ("Get Pro features")

- Question format ("Ready to do more?") vs. statement format

- Urgency-based ("Don't lose your work") vs. value-based

- Personalized headline with user's name or usage data

- Social proof headline ("Join 10,000+ Pro users")

### CTAs

- "Start Free Trial" vs. "Upgrade Now" vs. "Continue with Pro"

- First person ("Start My Trial") vs. second person ("Start Your Trial")

- Value-specific ("Unlock Unlimited") vs. generic ("Upgrade")

- Add urgency ("Upgrade Today") vs. no pressure

- Include price in CTA vs. separate price display

### Objection Handling

- Add money-back guarantee messaging

- Show "Cancel anytime" prominently

- Include FAQ on paywall

- Address specific objections based on feature gated

- Add chat/support option on paywall

---

## Trial & Conversion Experiments

### Trial Structure

- 7-day vs. 14-day vs. 30-day trial length

- Credit card required vs. not required for trial

- Full-access trial vs. limited feature trial

- Trial extension offer for engaged users

- Second trial offer for expired/churned users

### Trial Expiration

- Countdown timer visibility (always vs. near end)

- Email reminders: frequency and timing

- Grace period after expiration vs. immediate downgrade

- "Last chance" offer with discount

- Pause option vs. immediate cancellation

### Upgrade Path

- One-click upgrade from paywall vs. separate checkout

- Pre-filled payment info for returning users

- Multiple payment methods offered

- Quarterly plan option alongside monthly/annual

- Team invite flow for solo-to-team conversion

---

## Personalization Experiments

### Usage-Based

- Personalize paywall copy based on features used

- Highlight most-used premium features

- Show usage stats ("You've created 50 projects")

- Recommend plan based on behavior patterns

- Dynamic feature emphasis based on user segment

### Segment-Specific

- Different paywall for power users vs. casual users

- B2B vs. B2C messaging variations

- Industry-specific value propositions

- Role-based feature highlighting

- Traffic source-based messaging

---

## Frequency & UX Experiments

### Frequency Capping

- Test number of prompts per session

- Cool-down period after dismiss (hours vs. days)

- Escalating urgency over time vs. consistent messaging

- Once per feature vs. consolidated prompts

- Re-show rules after major engagement

### Dismiss Behavior

- "Maybe later" vs. "No thanks" vs. "Remind me tomorrow"

- Ask reason for declining

- Offer alternative (lower tier, annual discount)

- Exit survey on dismiss

- Friendly vs. neutral decline copy

mdskills/paywalls/SKILL.md

5.7 kB

---

description: 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," "convert free to paid," "freemium conversion," "trial expiration screen," "limit reached screen," "plan upgrade prompt," "in-app pricing," "free users won't upgrade," "trial to paid conversion," or "how do I get users to pay." Use this for any in-product moment where you're asking users to upgrade. Distinct from public pricing pages (see cro) — this focuses on in-product upgrade moments where the user has already experienced value. For pricing decisions, see pricing.

metadata:

version: 2.0.0

---

# Paywall and Upgrade Screen CRO

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.

## Initial Assessment

**Check for product marketing context first:**

Before providing recommendations, understand:

1. **Upgrade Context** - Freemium → Paid? Trial → Paid? Tier upgrade? Feature upsell? Usage limit?

2. **Product Model** - What's free? What's behind paywall? What triggers prompts? Current conversion rate?

3. **User Journey** - When does this appear? What have they experienced? What are they trying to do?

---

## Core Principles

### 1. Value Before Ask

- User should have experienced real value first

- Upgrade should feel like natural next step

- Timing: After "aha moment," not before

### 2. Show, Don't Just Tell

- Demonstrate the value of paid features

- Preview what they're missing

- Make the upgrade feel tangible

### 3. Friction-Free Path

- Easy to upgrade when ready

- Don't make them hunt for pricing

### 4. Respect the No

- Don't trap or pressure

- Make it easy to continue free

- Maintain trust for future conversion

---

## Paywall Trigger Points

### Feature Gates

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

### Usage Limits

When user hits a limit:

- Clear indication of limit reached

- Show what upgrading provides

- Don't block abruptly

### Trial Expiration

When trial is ending:

- Early warnings (7, 3, 1 day)

- Clear "what happens" on expiration

- Summarize value received

### Time-Based Prompts

After X days of free use:

- Gentle upgrade reminder

- Highlight unused paid features

- Easy to dismiss

---

## Paywall Screen Components

1. **Headline** - Focus on what they get: "Unlock [Feature] to [Benefit]"

2. **Value Demonstration** - Preview, before/after, "With Pro you could..."

3. **Feature Comparison** - Highlight key differences, current plan marked

4. **Pricing** - Clear, simple, annual vs. monthly options

5. **Social Proof** - Customer quotes, "X teams use this"

6. **CTA** - Specific and value-oriented: "Start Getting [Benefit]"

7. **Escape Hatch** - Clear "Not now" or "Continue with Free"

---

## Specific Paywall Types

### Feature Lock Paywall

```

[Lock Icon]

This feature is available on Pro

[Feature preview/screenshot]

[Feature name] helps you [benefit]:

• [Capability]

[Upgrade to Pro - $X/mo]

[Maybe Later]

```

### Usage Limit Paywall

```

You've reached your free limit

[Progress bar at 100%]

Free: 3 projects | Pro: Unlimited

[Upgrade to Pro] [Delete a project]

```

### Trial Expiration Paywall

```

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]

```

---

## Timing and Frequency

### When to Show

- After value moment, before frustration

- After activation/aha moment

- When hitting genuine limits

### When NOT to Show

- During onboarding (too early)

- When they're in a flow

- Repeatedly after dismissal

### Frequency Rules

- Limit per session

- Cool-down after dismiss (days, not hours)

- Track annoyance signals

---

## Upgrade Flow Optimization

### From Paywall to Payment

- Minimize steps

- Keep in-context if possible

- Pre-fill known information

### Post-Upgrade

- Immediate access to features

- Confirmation and receipt

- Guide to new features

---

## A/B Testing

### What to Test

- Trigger timing

- Headline/copy variations

- Price presentation

- Trial length

- Feature emphasis

- Design/layout

### Metrics to Track

- Paywall impression rate

- Click-through to upgrade

- Completion rate

- Revenue per user

- Churn rate post-upgrade

**For comprehensive experiment ideas**: See [references/experiments.md](references/experiments.md)

---

## Anti-Patterns to Avoid

### Dark Patterns

- Hiding the close button

- Confusing plan selection

- Guilt-trip copy

### Conversion Killers

- Asking before value delivered

- Too frequent prompts

- Blocking critical flows

- Complicated upgrade process

---

## Task-Specific Questions

1. What's your current free → paid conversion rate?

2. What triggers upgrade prompts today?

3. What features are behind the paywall?

4. What's your "aha moment" for users?

5. What pricing model? (per seat, usage, flat)

6. Mobile app, web app, or both?

---

## Related Skills

- **churn-prevention**: For cancel flows, save offers, and reducing churn post-upgrade

- **cro**: For public pricing page optimization

- **onboarding**: For driving to aha moment before upgrade

- **ab-testing**: For testing paywall variations

jsonskills/popups/evals/evals.json

6.4 kB

{

"skill_name": "popups",

"evals": [

{

"id": 1,

"prompt": "Help me create an exit-intent popup for our SaaS landing page. We want to capture emails from visitors who are about to leave without signing up. Our product is a social media scheduling tool.",

"expected_output": "Should check for product-marketing.md first. Should identify the popup type as exit-intent email capture. Should apply the exit-intent popup design guidance: compelling headline (address why they're leaving or offer additional value), lead magnet or incentive (discount, free resource, extended trial), minimal form fields (email only), clear CTA, and easy close option. Should apply copy formulas from the skill. Should address trigger configuration (exit intent detection). Should recommend frequency rules (don't show again if dismissed). Should include benchmarks (exit intent popups typically 3-10% conversion).",

"assertions": [

"Checks for product-marketing.md",

"Identifies as exit-intent popup type",

"Includes compelling headline",

"Includes lead magnet or incentive",

"Minimal form fields (email only)",

"Applies copy formulas from the skill",

"Addresses trigger configuration",

"Recommends frequency rules",

"Includes conversion benchmarks"

"files": []

{

"id": 2,

"prompt": "We want to offer a 10% discount to first-time visitors via a popup. When should we show it and what should it say?",

"expected_output": "Should identify this as a discount/offer popup type. Should apply trigger strategy guidance: recommend against showing immediately on page load (too aggressive). Should suggest time-based delay (30-60 seconds), scroll-based trigger (50%+ page scroll), or exit intent as better alternatives. Should apply the copy formula for discount popups: headline that frames the value, clear offer terms, urgency element, email capture, and CTA. Should address compliance (GDPR cookie consent if applicable). Should recommend frequency capping.",

"assertions": [

"Identifies as discount popup type",

"Recommends against immediate page load trigger",

"Suggests better trigger alternatives (time, scroll, exit)",

"Applies copy formula for discount popups",

"Includes urgency element",

"Addresses frequency capping",

"Addresses compliance considerations"

"files": []

{

"id": 3,

"prompt": "our popups are annoying everyone. we keep getting complaints but we also get a lot of email signups from them. how do we balance this?",

"expected_output": "Should trigger on casual phrasing. Should apply the frequency and rules guidance. Should address the balance: reduce annoyance while preserving conversions. Should recommend: frequency capping (once per session or once per X days), don't show to returning visitors who already dismissed, don't show to existing subscribers, respect 'close' action, consider less intrusive formats (slide-in instead of full modal, announcement bar instead of overlay). Should address compliance and accessibility requirements. Should suggest A/B testing different triggers and formats to find the best balance.",

"assertions": [

"Triggers on casual phrasing",

"Applies frequency and rules guidance",

"Addresses balance between conversions and UX",

"Recommends frequency capping",

"Suggests excluding existing subscribers",

"Recommends less intrusive alternatives",

"Suggests A/B testing to optimize"

"files": []

{

"id": 4,

"prompt": "What types of popups should we use on our blog? We publish content about email marketing and want to grow our email list.",

"expected_output": "Should recommend blog-appropriate popup types: scroll-triggered popup (show after 50-70% scroll indicating engagement), exit-intent popup, slide-in (less intrusive than modal), and inline content upgrades. Should recommend lead magnets relevant to the blog topic (email marketing templates, checklist, swipe file). Should address different popup placements: mid-content, end of post, sidebar slide-in. Should recommend behavior-based triggers over time-based for blog content. Should apply copy formulas with blog-specific hooks.",

"assertions": [

"Recommends blog-appropriate popup types",

"Includes scroll-triggered and exit-intent",

"Suggests less intrusive formats (slide-in)",

"Recommends relevant lead magnets",

"Addresses popup placement on blog pages",

"Recommends behavior-based triggers for blog",

"Applies copy formulas"

"files": []

{

"id": 5,

"prompt": "Design an announcement banner for our new feature launch. We want it to show at the top of the site for 2 weeks.",

"expected_output": "Should identify this as an announcement banner popup type. Should apply banner design guidance: short, clear headline announcing the feature, brief description of benefit, CTA to learn more or try it, dismiss option. Should recommend banner positioning (top of page, sticky or static). Should address duration (2 weeks as stated). Should recommend targeting (show to existing users who'd benefit, not just everyone). Should provide copy recommendations.",

"assertions": [

"Identifies as announcement banner type",

"Provides short, clear headline",

"Includes brief benefit description and CTA",

"Includes dismiss option",

"Addresses banner positioning",

"Recommends audience targeting",

"Provides copy recommendations"

"files": []

{

"id": 6,

"prompt": "We need to optimize the lead capture form inside our popup. It currently asks for name, email, company, and phone number. Too many fields?",

"expected_output": "Should recognize this overlaps with form optimization. Should defer to or cross-reference the cro skill, which handles form field optimization, layout, and conversion. May provide popup-specific context (popups need minimal fields due to fleeting attention) but should make clear that cro is the right skill for detailed form optimization.",

"assertions": [

"Recognizes overlap with form optimization",

"References or defers to cro skill",

"Notes popups need minimal fields due to context",

"Does not attempt detailed form redesign"

"files": []

}

]

}

mdskills/popups/SKILL.md

12 kB

---

description: 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 popup," "email popup," "announcement banner," "overlay," "collect emails with a popup," "exit popup," "scroll trigger," "sticky bar," or "notification bar." Use this for any overlay or interrupt-style conversion element. For forms outside of popups, see cro. For general page conversion optimization, see cro.

metadata:

version: 2.0.0

---

# Popup CRO

You are an expert in popup and modal optimization. Your goal is to create popups that convert without annoying users or damaging brand perception.

## Initial Assessment

**Check for product marketing context first:**

Before providing recommendations, understand:

1. **Popup Purpose**

- Email/newsletter capture

- Lead magnet delivery

- Discount/promotion

- Announcement

- Exit intent save

- Feature promotion

- Feedback/survey

2. **Current State**

- Existing popup performance?

- What triggers are used?

- User complaints or feedback?

- Mobile experience?

3. **Traffic Context**

- Traffic sources (paid, organic, direct)

- New vs. returning visitors

- Page types where shown

---

## Core Principles

### 1. Timing Is Everything

- Too early = annoying interruption

- Too late = missed opportunity

- Right time = helpful offer at moment of need

### 2. Value Must Be Obvious

- Clear, immediate benefit

- Relevant to page context

- Worth the interruption

### 3. Respect the User

- Easy to dismiss

- Don't trap or trick

- Remember preferences

- Don't ruin the experience

---

## Trigger Strategies

### Time-Based

- **Not recommended**: "Show after 5 seconds"

- **Better**: "Show after 30-60 seconds" (proven engagement)

- Best for: General site visitors

### Scroll-Based

- **Typical**: 25-50% scroll depth

- Indicates: Content engagement

- Best for: Blog posts, long-form content

- Example: "You're halfway through—get more like this"

### Exit Intent

- Detects cursor moving to close/leave

- Last chance to capture value

- Best for: E-commerce, lead gen

- Mobile alternative: Back button or scroll up

### Click-Triggered

- User initiates (clicks button/link)

- Zero annoyance factor

- Best for: Lead magnets, gated content, demos

- Example: "Download PDF" → Popup form

### Page Count / Session-Based

- After visiting X pages

- Indicates research/comparison behavior

- Best for: Multi-page journeys

- Example: "Been comparing? Here's a summary..."

### Behavior-Based

- Add to cart abandonment

- Pricing page visitors

- Repeat page visits

- Best for: High-intent segments

---

## Popup Types

### Email Capture Popup

**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")

### Lead Magnet Popup

**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

### Discount/Promotion Popup

**Goal**: First purchase or conversion

**Best practices:**

- Clear discount (10%, $20, free shipping)

- Deadline creates urgency

- Single use per visitor

- Easy to apply code

### Exit Intent Popup

**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"

### Announcement Banner

**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)

### Slide-In

**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

---

## Design Best Practices

### Visual Hierarchy

1. Headline (largest, first seen)

2. Value prop/offer (clear benefit)

3. Form/CTA (obvious action)

4. Close option (easy to find)

### Sizing

- Desktop: 400-600px wide typical

- Don't cover entire screen

- Mobile: Full-width bottom or center, not full-screen

- Leave space to close (visible X, click outside)

### Close Button

- Keep visible (top right is convention) — users who can't find the close button will bounce entirely

- Large enough to tap on mobile

- "No thanks" text link as alternative

- Click outside to close

### Mobile Considerations

- Can't detect exit intent (use alternatives)

- Full-screen overlays feel aggressive

- Bottom slide-ups work well

- Larger touch targets

- Easy dismiss gestures

### Imagery

- Product image or preview

- Face if relevant (increases trust)

- Minimal for speed

- Optional—copy can work alone

---

## Copy Formulas

### Headlines

- Benefit-driven: "Get [result] in [timeframe]"

- Question: "Want [desired outcome]?"

- Command: "Don't miss [thing]"

- Social proof: "Join [X] people who..."

- Curiosity: "The one thing [audience] always get wrong about [topic]"

### Subheadlines

- Expand on the promise

- Address objection ("No spam, ever")

- Set expectations ("Weekly tips in 5 min")

### CTA Buttons

- First person works: "Get My Discount" vs "Get Your Discount"

- Specific over generic: "Send Me the Guide" vs "Submit"

- Value-focused: "Claim My 10% Off" vs "Subscribe"

### Decline Options

- Polite, not guilt-trippy

- "No thanks" / "Maybe later" / "I'm not interested"

- Avoid manipulative: "No, I don't want to save money"

---

## Frequency and Rules

### Frequency Capping

- Show maximum once per session

- Remember dismissals (cookie/localStorage)

- 7-30 days before showing again

- Respect user choice

### Audience Targeting

- New vs. returning visitors (different needs)

- By traffic source (match ad message)

- By page type (context-relevant)

- Exclude converted users

- Exclude recently dismissed

### Page Rules

- Exclude checkout/conversion flows

- Consider blog vs. product pages

- Match offer to page context

---

## Compliance and Accessibility

### GDPR/Privacy

- Clear consent language

- Link to privacy policy

- Don't pre-check opt-ins

- Honor unsubscribe/preferences

### Accessibility

- Keyboard navigable (Tab, Enter, Esc)

- Focus trap while open

- Screen reader compatible

- Sufficient color contrast

- Don't rely on color alone

### Google Guidelines

- Intrusive interstitials hurt SEO

- Mobile especially sensitive

- Allow: Cookie notices, age verification, reasonable banners

- Avoid: Full-screen before content on mobile

---

## Measurement

### Key Metrics

- **Impression rate**: Visitors who see popup

- **Conversion rate**: Impressions → Submissions

- **Close rate**: How many dismiss immediately

- **Engagement rate**: Interaction before close

- **Time to close**: How long before dismissing

### What to Track

- Popup views

- Form focus

- Submission attempts

- Successful submissions

- Close button clicks

- Outside clicks

- Escape key

### Benchmarks

- Email popup: 2-5% conversion typical

- Exit intent: 3-10% conversion

- Click-triggered: Higher (10%+, self-selected)

---

## Output Format

### Popup Design

- **Type**: Email capture, lead magnet, etc.

- **Trigger**: When it appears

- **Targeting**: Who sees it

- **Frequency**: How often shown

- **Copy**: Headline, subhead, CTA, decline

- **Design notes**: Layout, imagery, mobile

### Multiple Popup Strategy

If recommending multiple popups:

- Popup 1: [Purpose, trigger, audience]

- Popup 2: [Purpose, trigger, audience]

- Conflict rules: How they don't overlap

### Test Hypotheses

Ideas to A/B test with expected outcomes

---

## Common Popup Strategies

### E-commerce

1. Entry/scroll: First-purchase discount

2. Exit intent: Bigger discount or reminder

3. Cart abandonment: Complete your order

### B2B SaaS

1. Click-triggered: Demo request, lead magnets

2. Scroll: Newsletter/blog subscription

3. Exit intent: Trial reminder or content offer

### Content/Media

1. Scroll-based: Newsletter after engagement

2. Page count: Subscribe after multiple visits

3. Exit intent: Don't miss future content

### Lead Generation

1. Time-delayed: General list building

2. Click-triggered: Specific lead magnets

3. Exit intent: Final capture attempt

---

## Experiment Ideas

### Placement & Format Experiments

**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

---

### Trigger Experiments

**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

---

### Messaging & Content Experiments

**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

---

### Personalization Experiments

**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

---

### Frequency & Rules Experiments

- Test frequency capping (once per session vs. once per week)

- Cool-down period after dismissal

- Test different dismiss behaviors

- Show escalating offers over multiple visits

---

## Task-Specific Questions

1. What's the primary goal for this popup?

2. What's your current popup performance (if any)?

3. What traffic sources are you optimizing for?

4. What incentive can you offer?

5. Are there compliance requirements (GDPR, etc.)?

6. Mobile vs. desktop traffic split?

---

## Related Skills

- **lead-magnets**: For planning lead magnets to promote via popups

- **cro**: For optimizing the form inside the popup

- **cro**: For the page context around popups

- **emails**: For what happens after popup conversion

- **ab-testing**: For testing popup variations

jsonskills/pricing/evals/evals.json

6.3 kB

{

"skill_name": "pricing",

"evals": [

{

"id": 1,

"prompt": "Help me figure out pricing for our new SaaS product. It's a customer support platform for e-commerce stores. We're not sure whether to charge per agent, per ticket, or flat rate. Currently thinking $49-199/month range.",

"expected_output": "Should check for product-marketing.md first. Should apply the three pricing axes framework: packaging (what's included in each tier), pricing metric (per agent, per ticket, flat rate — evaluate each), price point ($49-199 range evaluation). Should discuss value metrics and which aligns best with value delivered (per agent is common in support, but per ticket aligns with usage). Should recommend a good-better-best tier structure. Should address pricing psychology. Should provide a specific pricing recommendation with rationale.",

"assertions": [

"Checks for product-marketing.md",

"Applies three pricing axes framework",

"Evaluates multiple pricing metrics",

"Discusses which metric aligns with value delivered",

"Recommends good-better-best tier structure",

"Addresses pricing psychology",

"Provides specific pricing recommendation with rationale"

"files": []

{

"id": 2,

"prompt": "We want to raise our prices by 30%. We've been at $29/month for 2 years and we've added a lot of features. How do we do this without losing customers?",

"expected_output": "Should apply the 'when to raise prices' and price increase strategies sections. Should recommend a strategy: grandfather existing customers (or give them a grace period), tie the increase to new value, communicate the change clearly with advance notice, consider an annual billing discount as a softening measure. Should address different approaches (immediate for new customers, delayed for existing). Should recommend specific communication strategy. Should note that some churn is expected and acceptable.",

"assertions": [

"Applies price increase strategies",

"Recommends grandfathering or grace period approach",

"Recommends tying increase to new value",

"Provides communication strategy",

"Addresses new vs existing customer timing",

"Suggests annual billing as softening measure",

"Notes some churn is expected"

"files": []

{

"id": 3,

"prompt": "how do we figure out what people will actually pay? we're launching a new product and have no idea what to charge.",

"expected_output": "Should trigger on casual phrasing. Should apply the pricing research methods: Van Westendorp price sensitivity analysis (too cheap, bargain, expensive, too expensive), MaxDiff for feature importance, competitive benchmarking. Should explain how to run each method. Should also recommend simpler approaches: talking to potential customers, analyzing competitor pricing, testing different price points. Should provide a practical pricing research plan they can execute.",

"assertions": [

"Triggers on casual phrasing",

"Applies Van Westendorp price sensitivity method",

"Applies MaxDiff for feature importance",

"Recommends competitive benchmarking",

"Explains how to run each method",

"Suggests practical alternatives (customer interviews, competitive analysis)",

"Provides executable pricing research plan"

"files": []

{

"id": 4,

"prompt": "We have a Basic ($19), Pro ($49), and Enterprise (custom) plan. The Pro plan gets 70% of signups. Should we add a plan between Pro and Enterprise?",

"expected_output": "Should apply the good-better-best tier structure framework. Should analyze the current situation: Pro capturing 70% is actually healthy, but the gap to Enterprise suggests there may be mid-market customers underserved. Should evaluate whether a 4th tier makes sense: does it address a real gap, or will it create choice paralysis? Should apply pricing psychology (Hick's Law — more options can reduce decisions). Should recommend either a 4th tier with clear differentiation or adjusting the Pro plan to better bridge the gap.",

"assertions": [

"Applies good-better-best tier structure",

"Analyzes current tier performance",

"Evaluates whether 4th tier addresses real gap",

"Considers choice paralysis risk",

"Applies pricing psychology (Hick's Law)",

"Provides specific recommendation with rationale"

"files": []

{

"id": 5,

"prompt": "What pricing psychology tactics should we use on our pricing page? We want the $79 plan to be the most popular.",

"expected_output": "Should apply the pricing psychology section: anchoring (show the $79 plan next to a higher-priced plan), decoy effect (make the lower plan look less valuable), visual emphasis (highlight or 'recommend' the $79 plan), charm pricing ($79 vs $80), Rule of 100 (percentage discounts below $100, dollar discounts above), loss framing (show what lower plans miss). Should provide specific pricing page design recommendations. Should cross-reference cro for broader pricing page optimization.",

"assertions": [

"Applies pricing psychology tactics",

"Applies anchoring effect",

"Applies decoy effect or visual emphasis",

"Applies charm pricing or Rule of 100",

"Provides specific pricing page recommendations",

"Cross-references cro or marketing-psychology"

"files": []

{

"id": 6,

"prompt": "Our pricing page conversion rate is only 1.5%. Can you review the page and suggest improvements?",

"expected_output": "Should recognize this is a pricing page conversion optimization task, not a pricing strategy task. Should defer to or cross-reference the cro skill, which handles pricing page conversion rate optimization including plan comparison clarity, CTA optimization, and trust signals. Pricing-strategy focuses on the actual pricing decisions (what to charge, how to package), not the page design.",

"assertions": [

"Recognizes this as pricing page CRO, not pricing strategy",

"References or defers to cro skill",

"Explains that pricing is about pricing decisions",

"Does not attempt full page CRO audit"

"files": []

}

]

}

mdskills/pricing/references/research-methods.md

4.7 kB

# Pricing Research Methods

## Contents

- Van Westendorp Price Sensitivity Meter (The Four Questions, How to Analyze, Survey Tips, Sample Output)

- MaxDiff Analysis (How It Works, Example Survey Question, Analyzing Results, Using MaxDiff for Packaging)

- Willingness to Pay Surveys

- Usage-Value Correlation Analysis

## Van Westendorp Price Sensitivity Meter

The Van Westendorp survey identifies the acceptable price range for your product.

### The Four Questions

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)

### How to Analyze

1. Plot cumulative distributions for each question

2. Find the intersections:

- **Point of Marginal Cheapness (PMC):** "Too cheap" crosses "Expensive"

- **Point of Marginal Expensiveness (PME):** "Too expensive" crosses "Cheap"

- **Optimal Price Point (OPP):** "Too cheap" crosses "Too expensive"

- **Indifference Price Point (IDP):** "Expensive" crosses "Cheap"

**The acceptable price range:** PMC to PME

**Optimal pricing zone:** Between OPP and IDP

### Survey Tips

- Need 100-300 respondents for reliable data

- Segment by persona (different willingness to pay)

- Use realistic product descriptions

- Consider adding purchase intent questions

### Sample Output

```

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 Analysis (Best-Worst Scaling)

MaxDiff identifies which features customers value most, informing packaging decisions.

### How It Works

1. List 8-15 features you could include

2. Show respondents sets of 4-5 features at a time

3. Ask: "Which is MOST important? Which is LEAST important?"

4. Repeat across multiple sets until all features compared

5. Statistical analysis produces importance scores

### Example Survey Question

```

Which feature is MOST important to you?

Which feature is LEAST important to you?

□ Unlimited projects

□ Custom branding

□ Priority support

□ API access

□ Advanced analytics

```

### Analyzing Results

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)

### Using MaxDiff for Packaging

| 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 |

---

## Willingness to Pay Surveys

**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

---

## Usage-Value Correlation Analysis

### 1. Instrument usage data

Track how customers use your product:

- Feature usage frequency

- Volume metrics (users, records, API calls)

- Outcome metrics (revenue generated, time saved)

### 2. Correlate with customer success

- Which usage patterns predict retention?

- Which usage patterns predict expansion?

- Which customers pay the most, and why?

### 3. Identify value thresholds

- At what usage level do customers "get it"?

- At what usage level do they expand?

- At what usage level should price increase?

### Example Analysis

```

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

```

mdskills/pricing/references/tier-structure.md

7.0 kB

# Tier Structure and Packaging

## Contents

- How Many Tiers?

- Good-Better-Best Framework

- Tier Differentiation Strategies

- Example Tier Structure

- Packaging for Personas (Identifying Pricing Personas, Persona-Based Packaging)

- Freemium vs. Free Trial (When to Use Freemium, When to Use Free Trial, Hybrid Approaches)

- Enterprise Pricing (When to Add Custom Pricing, Enterprise Tier Elements, Enterprise Pricing Strategies)

## How Many 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-Better-Best Framework

**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

---

## Tier Differentiation Strategies

**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

---

## Example Tier Structure

```

┌────────────────┬─────────────────┬─────────────────┬─────────────────┐

│ │ 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 │ ✗ │ ✗ │ ✓ │

└────────────────┴─────────────────┴─────────────────┴─────────────────┘

```

---

## Packaging for Personas

### Identifying Pricing Personas

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)

### Persona-Based Packaging

**Step 1: Define personas**

|---------|------|-------|-----|---------|

**Step 2: Map features to personas**

|---------|------------|------------|---------|------------|

| Core features | ✓ | ✓ | ✓ | ✓ |

| Collaboration | — | ✓ | ✓ | ✓ |

| 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 vs. Free Trial

### When to Use Freemium

**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

### When to Use Free Trial

**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

### Hybrid Approaches

**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

---

## Enterprise Pricing

### When to Add Custom Pricing

Add "Contact Sales" when:

- Deal sizes exceed $10k+ ARR

- Customers need custom contracts

- Implementation/onboarding required

- Security/compliance requirements

- Procurement processes involved

### Enterprise Tier Elements

**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

### Enterprise Pricing Strategies

**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

mdskills/pricing/SKILL.md

6.9 kB

---

description: "When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increase,' 'value metric,' 'Van Westendorp,' 'willingness to pay,' 'monetization,' 'how much should I charge,' 'my pricing is wrong,' 'pricing page,' 'annual vs monthly,' 'per seat pricing,' or 'should I offer a free plan.' Use this whenever someone is figuring out what to charge or how to structure their plans. For in-app upgrade screens, see paywalls."

metadata:

version: 2.0.0

---

# Pricing Strategy

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.

## Before Starting

**Check for product marketing context first:**

Gather this context (ask if not provided):

### 1. Business Context

- What type of product? (SaaS, marketplace, e-commerce, service)

- What's your current pricing (if any)?

- What's your target market? (SMB, mid-market, enterprise)

- What's your go-to-market motion? (self-serve, sales-led, hybrid)

### 2. Value & Competition

- What's the primary value you deliver?

- What alternatives do customers consider?

- How do competitors price?

### 3. Current Performance

- What's your current conversion rate?

- What's your ARPU and churn rate?

- Any feedback on pricing from customers/prospects?

### 4. Goals

- Optimizing for growth, revenue, or profitability?

- Moving upmarket or expanding downmarket?

---

## Pricing Fundamentals

### The Three Pricing Axes

**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

### Value-Based Pricing

Price should be based on value delivered, not cost to serve:

- **Customer's perceived value** — The ceiling

- **Your price** — Between alternatives and perceived value

- **Next best alternative** — The floor for differentiation

- **Your cost to serve** — Only a baseline, not the basis

**Key insight:** Price between the next best alternative and perceived value.

---

## Value Metrics

### What is a Value Metric?

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

### Common Value Metrics

| 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 |

### Choosing Your Value Metric

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

---

## Tier Structure Overview

### Good-Better-Best Framework

**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

### Tier Differentiation

- **Feature gating** — Basic vs. advanced features

- **Usage limits** — Same features, different limits

- **Support level** — Email → Priority → Dedicated

- **Access** — API, SSO, custom branding

**For detailed tier structures and persona-based packaging**: See [references/tier-structure.md](references/tier-structure.md)

---

## Pricing Research

### Van Westendorp Method

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.

### MaxDiff Analysis

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](references/research-methods.md)

---

## When to Raise Prices

### Signs It's Time

**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

### Price Increase Strategies

1. **Grandfather existing** — New price for new customers only

2. **Delayed increase** — Announce 3-6 months out

3. **Tied to value** — Raise price but add features

4. **Plan restructure** — Change plans entirely

---

## Pricing Page Best Practices

### Above the Fold

- Clear tier comparison table

- Recommended tier highlighted

- Monthly/annual toggle

- Primary CTA for each tier

### Common Elements

- Feature comparison table

- Who each tier is for

- FAQ section

- Annual discount callout (17-20%)

- Money-back guarantee

- Customer logos/trust signals

### Pricing Psychology

- **Anchoring:** Show higher-priced option first

- **Decoy effect:** Middle tier should be best value

- **Charm pricing:** $49 vs. $50 (for value-focused)

- **Round pricing:** $50 vs. $49 (for premium)

---

## Pricing Checklist

### Before Setting Prices

- [ ] Defined target customer personas

- [ ] Researched competitor pricing

- [ ] Identified your value metric

- [ ] Conducted willingness-to-pay research

- [ ] Mapped features to tiers

### Pricing Structure

- [ ] Chosen number of tiers

- [ ] Differentiated tiers clearly

- [ ] Set price points based on research

- [ ] Created annual discount strategy

- [ ] Planned enterprise/custom tier

---

## Task-Specific Questions

1. What pricing research have you done?

2. What's your current ARPU and conversion rate?

3. What's your primary value metric?

4. Who are your main pricing personas?

5. Are you self-serve, sales-led, or hybrid?

6. What pricing changes are you considering?

---

## Related Skills

- **churn-prevention**: For cancel flows, save offers, and reducing revenue churn

- **cro**: For optimizing pricing page conversion

- **copywriting**: For pricing page copy

- **marketing-psychology**: For pricing psychology principles

- **ab-testing**: For testing pricing changes

- **revops**: For deal desk processes and pipeline pricing

- **sales-enablement**: For proposal templates and pricing presentations

jsonskills/product-marketing/evals/evals.json

5.7 kB

{

"skill_name": "product-marketing",

"evals": [

{

"id": 1,

"prompt": "I want to set up my product marketing context. We're a B2B SaaS company that sells a customer feedback platform to product teams.",

"expected_output": "Should check if .agents/product-marketing.md already exists. If not, should offer two options: (1) Auto-draft from codebase (recommended) or (2) Start from scratch. If user chooses start from scratch, should walk through sections conversationally one at a time. Should cover all applicable sections: Product Overview, Target Audience, Personas, Problems You Solve, Competitive Landscape, Differentiation, Objections, Switching Dynamics, Customer Language, Brand Voice, Proof Points, and Goals. Should create the file at .agents/product-marketing.md when complete.",

"assertions": [

"Checks for existing product-marketing.md",

"Offers two options: auto-draft or start from scratch",

"Covers applicable sections",

"Walks through sections conversationally one at a time",

"Creates file at .agents/product-marketing.md"

"files": []

{

"id": 2,

"prompt": "Update our product marketing context. We just added a new enterprise tier and our target audience has expanded to include VP of Engineering, not just Product Managers.",

"expected_output": "Should check for existing .agents/product-marketing.md and read it. Should identify which sections need updating based on the changes: Target Audience (add VP of Engineering), Personas (add new persona), Product Overview (new enterprise tier, including pricing updates within that section), Objections (enterprise-specific), and Competitive Landscape (enterprise competitors). Should update only the relevant sections, preserving existing content that hasn't changed.",

"assertions": [

"Reads existing product-marketing.md",

"Identifies sections that need updating",

"Updates Target Audience with VP of Engineering",

"Adds new persona for the expanded audience",

"Updates Product Overview for enterprise tier",

"Preserves unchanged sections"

"files": []

{

"id": 3,

"prompt": "create a product context doc for my app. it's a mobile app that helps people find hiking trails. we're just getting started.",

"expected_output": "Should trigger on casual phrasing. Should check for existing context doc. Should offer auto-draft or start-from-scratch options. Should adapt questions for an early-stage B2C mobile app (outdoor/fitness niche). Should note that some sections may be sparse for an early-stage product and that's okay — they can be filled in as the business matures. Should skip non-applicable sections (e.g., Personas section is B2B-focused) rather than forcing all 12. Should accept lighter answers for sections like Proof Points or Competitive Landscape if the company is new.",

"assertions": [

"Triggers on casual phrasing",

"Checks for existing context doc",

"Offers auto-draft or start-from-scratch options",

"Adapts questions for early-stage B2C mobile app",

"Notes some sections may be sparse early on",

"Skips non-applicable sections rather than forcing all 12",

"Creates file at .agents/product-marketing.md"

"files": []

{

"id": 4,

"prompt": "Can you auto-draft our product marketing context from our existing codebase and marketing materials?",

"expected_output": "Should activate the auto-draft workflow mode. Should scan the codebase for existing marketing context: README, landing page copy, pricing page, about page, meta descriptions, any existing documentation. Should draft the product-marketing.md from what it finds, filling in sections where information is available and flagging sections that need manual input. Should present the draft for review before saving.",

"assertions": [

"Activates auto-draft workflow mode",

"Scans codebase for existing marketing materials",

"Drafts context from found information",

"Flags sections needing manual input",

"Presents draft for review before saving"

"files": []

{

"id": 5,

"prompt": "Do we have a product marketing context set up? I want to make sure the other marketing skills have context about our product.",

"expected_output": "Should check for .agents/product-marketing.md (and the older .claude/product-marketing.md location). Should report whether it exists and summarize its contents if found. If it doesn't exist, should offer to create one and explain why it's valuable (other skills like copywriting, cro, seo-audit check for it first). Should explain how other skills use this context document.",

"assertions": [

"Checks both file locations",

"Reports whether context doc exists",

"Summarizes contents if found",

"Offers to create if missing",

"Explains how other skills use it"

"files": []

{

"id": 6,

"prompt": "Write homepage copy for our SaaS product.",

"expected_output": "Should recognize this is a copywriting task, not a product marketing context task. Should check for product-marketing.md (as other skills do), and if it doesn't exist, may suggest creating one first. But should defer to the copywriting skill for actually writing the homepage copy.",

"assertions": [

"Recognizes this as a copywriting task",

"May check for or suggest creating product-marketing.md",

"References or defers to copywriting skill for the actual copy",

"Does not attempt to write homepage copy using context creation patterns"

"files": []

}

]

}

mdskills/product-marketing/SKILL.md

7.5 kB

---

description: "When the user wants to create or update their product marketing context document. Also use when the user mentions 'product context,' 'marketing context,' 'set up context,' 'positioning,' 'who is my target audience,' 'describe my product,' 'ICP,' 'ideal customer profile,' or wants to avoid repeating foundational information across marketing tasks. Use this at the start of any new project before using other marketing skills — it creates `.agents/product-marketing.md` that all other skills reference for product, audience, and positioning context."

metadata:

version: 2.0.0

---

# Product Marketing Context

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`.

## Workflow

### Step 1: Check for Existing Context

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:**

1. **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.

2. **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?"

### Step 2: Gather Information

**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.

---

## Sections to Capture

### 1. Product Overview

- One-line description

- What it does (2-3 sentences)

- Product category (what "shelf" you sit on—how customers search for you)

- Product type (SaaS, marketplace, e-commerce, service, etc.)

- Business model and pricing

### 2. Target Audience

- Target company type (industry, size, stage)

- Target decision-makers (roles, departments)

- Primary use case (the main problem you solve)

- Jobs to be done (2-3 things customers "hire" you for)

- Specific use cases or scenarios

### 3. Personas (B2B only)

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

### 4. Problems & Pain Points

- Core challenge customers face before finding you

- Why current solutions fall short

- What it costs them (time, money, opportunities)

- Emotional tension (stress, fear, doubt)

### 5. Competitive Landscape

- **Direct competitors**: Same solution, same problem (e.g., Calendly vs SavvyCal)

- **Secondary competitors**: Different solution, same problem (e.g., Calendly vs Superhuman scheduling)

- **Indirect competitors**: Conflicting approach (e.g., Calendly vs personal assistant)

- How each falls short for customers

### 6. Differentiation

- Key differentiators (capabilities alternatives lack)

- How you solve it differently

- Why that's better (benefits)

- Why customers choose you over alternatives

### 7. Objections & Anti-Personas

- Top 3 objections heard in sales and how to address them

- Who is NOT a good fit (anti-persona)

### 8. Switching Dynamics

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

### 9. Customer Language

- How customers describe the problem (verbatim)

- How they describe your solution (verbatim)

- Words/phrases to use

- Words/phrases to avoid

- Glossary of product-specific terms

### 10. Brand Voice

- Tone (professional, casual, playful, etc.)

- Communication style (direct, conversational, technical)

- Brand personality (3-5 adjectives)

### 11. Proof Points

- Key metrics or results to cite

- Notable customers/logos

- Testimonial snippets

- Main value themes and supporting evidence

### 12. Goals

- Primary business goal

- Key conversion action (what you want people to do)

- Current metrics (if known)

---

## Step 3: Create the Document

After gathering information, create `.agents/product-marketing.md` with this structure:

```markdown

# 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

|---------|-------------|-----------|------------------|

| | | | |

## 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:**

```

---

## Step 4: Confirm and Save

- Show the completed document

- Ask if anything needs adjustment

- Save to `.agents/product-marketing.md`

- Tell them: "Other marketing skills will now use this context automatically. Run `/product-marketing` anytime to update it."

---

## Tips

- **Be specific**: Ask "What's the #1 frustration that brings them to you?" not "What problem do they solve?"

- **Capture exact words**: Customer language beats polished descriptions

- **Ask for examples**: "Can you give me an example?" unlocks better answers

- **Validate as you go**: Summarize each section and confirm before moving on

- **Skip what doesn't apply**: Not every product needs all sections (e.g., Personas for B2C)

jsonskills/programmatic-seo/evals/evals.json

6.7 kB

{

"skill_name": "programmatic-seo",

"evals": [

{

"id": 1,

"prompt": "We want to create programmatic SEO pages for our CRM. We're thinking of 'CRM for [industry]' pages — like 'CRM for Real Estate,' 'CRM for Healthcare,' etc. How should we approach this?",

"expected_output": "Should check for product-marketing.md first. Should identify this as the Personas playbook (industry-specific pages). Should apply the core principles: unique value per page (not just swapping the industry name), proprietary data or insights per industry, clean URL structure. Should recommend the implementation framework: keyword research for each industry variation, data requirements (what industry-specific content makes each page unique), template design, internal linking strategy between industry pages and main pages, and indexation strategy. Should warn against thin content (just template + keyword swap).",

"assertions": [

"Checks for product-marketing.md",

"Identifies as Personas playbook",

"Applies core principles (unique value, proprietary data, clean URLs)",

"Recommends keyword research per variation",

"Addresses data requirements for unique content",

"Provides template design guidance",

"Includes internal linking strategy",

"Warns against thin content"

"files": []

{

"id": 2,

"prompt": "Create a comparison page strategy. We want pages like 'Notion vs Asana', 'Notion vs Monday', etc. for all our competitors. We have 15 competitors.",

"expected_output": "Should identify this as the Comparisons playbook. Should apply the programmatic approach for competitor comparison pages at scale. Should recommend: template structure for comparison pages, unique data per comparison (not just the same template with names swapped), keyword research for each '[competitor A] vs [competitor B]' variation, URL structure (/compare/notion-vs-asana), internal linking between comparison pages, and quality checks. Should cross-reference the competitors skill for page content structure.",

"assertions": [

"Identifies as Comparisons playbook",

"Recommends template structure for scale",

"Addresses unique data per comparison",

"Includes keyword research for variations",

"Provides URL structure recommendation",

"Includes internal linking strategy",

"Cross-references competitors skill",

"Applies quality checks"

"files": []

{

"id": 3,

"prompt": "we want to rank for '[tool name] integration' keywords. we integrate with 50+ tools and want a page for each. like 'Slack integration', 'Salesforce integration' etc.",

"expected_output": "Should trigger on casual phrasing. Should identify this as the Integrations playbook. Should recommend: template design for integration pages (what it does, how to set up, use cases), unique content per integration (specific workflows, screenshots, setup steps), keyword research for '[tool] + [your product] integration', URL structure (/integrations/slack), hub page linking to all integration pages, and schema markup considerations. Should emphasize that each page needs genuine unique value, not just 'we integrate with [tool].'",

"assertions": [

"Triggers on casual phrasing",

"Identifies as Integrations playbook",

"Recommends template with unique content per integration",

"Includes setup steps and use cases per page",

"Provides URL structure recommendation",

"Recommends hub page for all integrations",

"Emphasizes genuine unique value per page"

"files": []

{

"id": 4,

"prompt": "We built 500 programmatic pages but Google isn't indexing most of them. Only 80 are in the index. What's going wrong?",

"expected_output": "Should diagnose the indexation problem. Should apply the quality checks and indexation strategy guidance. Should investigate: thin content (are pages providing unique value or just template + keyword?), crawl budget (500 pages may be fine but depends on site authority), internal linking (are the pages discoverable?), XML sitemap inclusion, duplicate/near-duplicate content issues. Should recommend specific fixes: improve content uniqueness, strengthen internal linking, submit sitemap, check robots.txt, use Search Console for indexation requests. Should warn that Google may choose not to index thin pages regardless.",

"assertions": [

"Diagnoses indexation problem",

"Investigates thin content as likely cause",

"Checks crawl budget considerations",

"Checks internal linking to programmatic pages",

"Checks XML sitemap and robots.txt",

"Recommends specific fixes for indexation",

"Warns about Google's thin content policies"

"files": []

{

"id": 5,

"prompt": "Help me create a glossary section for our marketing automation platform. We want to define 200+ marketing terms and rank for '[term] definition' keywords.",

"expected_output": "Should identify this as the Glossary playbook. Should apply the template design: term definition page template (definition, examples, related terms, how it applies to the user's product), hub/index page linking to all terms, URL structure (/glossary/[term]), alphabetical and categorical navigation. Should address quality: each definition should provide genuine value beyond a dictionary definition. Should include internal linking strategy and schema markup (DefinedTerm schema). Should recommend starting with highest-volume terms.",

"assertions": [

"Identifies as Glossary playbook",

"Provides template design for term pages",

"Recommends hub/index page",

"Provides URL structure",

"Addresses content quality beyond dictionary definitions",

"Includes internal linking strategy",

"Recommends starting with highest-volume terms"

"files": []

{

"id": 6,

"prompt": "Can you audit our existing programmatic SEO pages for technical issues? We have crawl errors and some pages return 404s.",

"expected_output": "Should recognize this is a technical SEO audit task, not a programmatic SEO strategy task. Should defer to or cross-reference the seo-audit skill, which handles crawlability, indexation, and technical SEO issues. Programmatic-seo focuses on strategy, template design, and content planning for scaled pages.",

"assertions": [

"Recognizes this as technical SEO audit task",

"References or defers to seo-audit skill",

"Explains that programmatic-seo is for strategy and template design",

"Does not attempt full technical SEO audit"

"files": []

}

]

}

mdskills/programmatic-seo/references/playbooks.md

8.1 kB

# The 12 Programmatic SEO Playbooks

Beyond mixing and matching data point permutations, these are the proven playbooks for programmatic SEO.

## Contents

- 1. Templates

- 2. Curation

- 3. Conversions

- 4. Comparisons

- 5. Examples

- 6. Locations

- 7. Personas

- 8. Integrations

- 9. Glossary

- 10. Translations

- 11. Directory

- 12. Profiles

- Choosing Your Playbook (Match to Your Assets, Combine Playbooks)

## 1. Templates

**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]/`

---

## 2. Curation

**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/`

---

## 3. Conversions

**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/`

---

## 4. Comparisons

**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*

---

## 5. Examples

**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/`

---

## 6. Locations

**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]/`

---

## 7. Personas

**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]/`

---

## 8. Integrations

**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]/`

---

## 9. Glossary

**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]/`

---

## 10. Translations

**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.

---

## 11. Directory

**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/`

---

## 12. Profiles

**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]/`

---

## Choosing Your Playbook

### Match to Your Assets

| 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 |

### Combine Playbooks

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

mdskills/programmatic-seo/SKILL.md

6.9 kB

---

description: 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] + [city] pages," "comparison pages," "integration pages," "building many pages for SEO," "pSEO," "generate 100 pages," "data-driven pages," or "templated landing pages." Use this whenever someone wants to create many similar pages targeting different keywords or locations. For auditing existing SEO issues, see seo-audit. For content strategy planning, see content-strategy.

metadata:

version: 2.0.0

---

# Programmatic SEO

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.

## Initial Assessment

**Check for product marketing context first:**

Before designing a programmatic SEO strategy, understand:

1. **Business Context**

- What's the product/service?

- Who is the target audience?

- What's the conversion goal for these pages?

2. **Opportunity Assessment**

- What search patterns exist?

- How many potential pages?

- What's the search volume distribution?

3. **Competitive Landscape**

- Who ranks for these terms now?

- What do their pages look like?

- Can you realistically compete?

---

## Core Principles

### 1. Unique Value Per Page

- Every page must provide value specific to that page

- Not just swapped variables in a template

- Maximize unique content—the more differentiated, the better

### 2. Proprietary Data Wins

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)

### 3. Clean URL Structure

**Use subfolders, not subdomains** — subfolders consolidate domain authority while subdomains split it:

- Good: `yoursite.com/templates/resume/`

- Bad: `templates.yoursite.com/resume/`

### 4. Genuine Search Intent Match

Pages must actually answer what people are searching for.

### 5. Quality Over Quantity

Better to have 100 great pages than 10,000 thin ones.

### 6. Avoid Google Penalties

- No doorway pages

- No keyword stuffing

- No duplicate content

- Genuine utility for users

---

## The 12 Playbooks (Overview)

| 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](references/playbooks.md)

---

## Choosing Your Playbook

| 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").

---

## Implementation Framework

### 1. Keyword Pattern Research

**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

### 2. Data Requirements

**Identify data sources:**

- What data populates each page?

- Is it first-party, scraped, licensed, public?

- How is it updated?

### 3. Template Design

**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

### 4. Internal Linking Architecture

**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

### 5. Indexation Strategy

- Prioritize high-volume patterns

- Noindex very thin variations

- Manage crawl budget thoughtfully

- Separate sitemaps by page type

---

## Quality Checks

### Pre-Launch Checklist

**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

### Post-Launch Monitoring

Track: Indexation rate, Rankings, Traffic, Engagement, Conversion

Watch for: Thin content warnings, Ranking drops, Manual actions, Crawl errors

---

## Common Mistakes

- **Thin content**: Just swapping city names in identical content

- **Keyword cannibalization**: Multiple pages targeting same keyword

- **Over-generation**: Creating pages with no search demand

- **Poor data quality**: Outdated or incorrect information

- **Ignoring UX**: Pages exist for Google, not users

---

## Output Format

### Strategy Document

- Opportunity analysis

- Implementation plan

- Content guidelines

### Page Template

- URL structure

- Title/meta templates

- Content outline

- Schema markup

---

## Task-Specific Questions

1. What keyword patterns are you targeting?

2. What data do you have (or can acquire)?

3. How many pages are you planning?

4. What does your site authority look like?

5. Who currently ranks for these terms?

6. What's your technical stack?

---

## Related Skills

- **seo-audit**: For auditing programmatic pages after launch

- **schema**: For adding structured data

- **site-architecture**: For page hierarchy, URL structure, and internal linking

- **competitors**: For comparison page frameworks

jsonskills/prospecting/evals/evals.json

9.6 kB

{

"skill_name": "prospecting",

"evals": [

{

"id": 1,

"prompt": "We're a B2B SaaS selling RevOps tooling at $30K ACV. Build me a list of 25 prospects.",

"expected_output": "Should check for product-marketing.md first. Should identify this as the SaaS branch. Should run Phase 1 ICP definition pulling from product-marketing context or asking targeted questions (target industry, headcount range, tech stack signals, funding stage). Should propose discovery sources appropriate for SaaS at $30K ACV: Apollo for breadth, Clay for waterfall enrichment, Crunchbase for funding signals, BuiltWith/Wappalyzer for tech stack, LinkedIn Sales Nav for decision-mapping (manual). Should ask about user's tool access before assuming. Should source 50-75 candidates (2-3x target) before qualifying. Should flag that email validation via Truelist or similar is non-negotiable before final list. Should output SaaS-branch chat table columns (Score | Company | Industry | Size | Signal | Contact | Email status | Confidence) followed by top 3-5 hot leads with one-sentence rationale each. Should reference references/saas-prospecting.md.",

"assertions": [

"Checks for product-marketing.md",

"Identifies SaaS branch",

"Runs Phase 1 ICP definition",

"Recommends multi-source discovery (Apollo, Clay, Crunchbase, BuiltWith)",

"Asks about user's tool access",

"Sources 2-3x candidates before qualifying",

"Requires email validation before final list",

"Outputs SaaS-branch chat table columns",

"Includes top 3-5 outreach targets with rationale",

"References saas-prospecting.md"

"files": []

{

"id": 2,

"prompt": "Find me 25 SaaS companies that just raised a Series B in the last 60 days and use HubSpot.",

"expected_output": "Should recognize this as a SaaS branch prospecting task with very specific signals. Should identify the trigger event (Series B in last 60 days) and the technographic filter (uses HubSpot). Should recommend a workflow: (1) Crunchbase or Pitchbook for funding signal filter (Series B + date), (2) BuiltWith or Clay's waterfall for tech stack verification (uses HubSpot), (3) cross-check via business websites and LinkedIn. Should note this is a tight ICP that should yield high-confidence matches if data sources are current. Should flag freshness concerns: Crunchbase data depends on self-reporting, BuiltWith refresh cycles aren't real-time. Should recommend cross-source verification for the funding date specifically. Should output a SaaS-branch chat table with the funding round + date in the Signal column. Should include verified email validation before delivering.",

"assertions": [

"Identifies as SaaS branch",

"Identifies funding signal + tech stack filter",

"Recommends Crunchbase or Pitchbook for funding",

"Recommends BuiltWith or Clay for HubSpot verification",

"Notes data freshness concerns",

"Recommends cross-source verification",

"Outputs signal column showing round + date",

"Requires email validation"

"files": []

{

"id": 3,

"prompt": "I run a marketing agency. Find me 25 mid-market manufacturers in the Midwest US who recently hired a new CMO.",

"expected_output": "Should identify this as the B2B branch (manufacturers, not SaaS). Should run Phase 1 ICP definition: industry (manufacturing, with NAICS code if precision matters), size (mid-market = typically 200-2000 employees), geography (Midwest US states), trigger event (CMO hire in last 90-180 days). Should propose discovery: Apollo or ZoomInfo for firmographic filter, LinkedIn Sales Nav for CMO hire detection (job changes), Google Alerts on press releases for trigger events. Should warn that CMO hires aren't always in public databases — LinkedIn Sales Nav alerts on job changes is the most reliable source. Should output B2B-branch chat table with the CMO trigger as the signal. Should reference references/b2b-prospecting.md. Should mention compliance: GDPR less likely (US-only), CAN-SPAM applies, capture source URL + date for every contact.",

"assertions": [

"Identifies B2B branch (not SaaS)",

"Runs Phase 1 ICP definition with NAICS or industry classification",

"Specifies mid-market size band",

"Specifies Midwest US geography",

"Identifies trigger event (CMO hire)",

"Recommends Apollo/ZoomInfo + LinkedIn Sales Nav",

"Notes CMO hires often only on LinkedIn",

"Outputs B2B-branch chat table",

"Mentions CAN-SPAM and source URL capture",

"References b2b-prospecting.md"

"files": []

{

"id": 4,

"prompt": "We sell to industrial distributors. Build a list of 25 prospects.",

"expected_output": "Should identify this as the B2B branch. Should run Phase 1 ICP definition asking targeted questions: distributor size, geography, vertical specialty, buying patterns. Should propose discovery: Apollo or ZoomInfo for firmographic depth, industry-specific directories (e.g., NAW for wholesale distributors, ISA for industrial sales agencies), trade show exhibitor lists. Should note state business registries and Chamber of Commerce as verification sources. Should propose trigger events: new location, recent acquisition, leadership change, posting RFPs. Should warn that industrial distributor data is often spotty in major databases — cross-check with company website + LinkedIn for size and ownership signals. Should output B2B-branch chat table. Should note ICP fit precision matters more than initial volume for this kind of niche prospecting.",

"assertions": [

"Identifies B2B branch",

"Runs Phase 1 ICP definition asking targeted questions",

"Recommends industry-specific directories beyond Apollo/ZoomInfo",

"Mentions trade show exhibitor lists",

"Identifies relevant trigger events",

"Warns about data spottiness for industrial",

"Recommends cross-verification with business websites + LinkedIn",

"Notes ICP fit precision over volume"

"files": []

{

"id": 5,

"prompt": "I build websites for local businesses. Find me 15 prospects near Austin, TX who don't have a website.",

"expected_output": "Should identify as Local SMB branch. Should run Phase 1 ICP definition: business category (ask user — gyms, restaurants, salons, etc. matter), radius (default 20 km from Austin), target count (15). Should run the browser research workflow: search Google Maps for category + Austin, build candidate list from visible results, cross-check via business name + city web search to verify website status. Should apply the 4-tier website status classification (No site found / Social only / Weak site / Has site) — prioritize No site + Social only as Hot. Should score: Hot (no site + active + phone + within radius), Warm (weak site), Cold (has site), Skip (closed/duplicate/out of scope). Should output Local SMB chat table (Score | Business | Category | Area | Distance | Website status | Website/Social | Phone | Why prospect | Confidence). Should add 'Best first outreach targets' top 3 with reasoning. Should reference references/local-prospecting.md. Should warn against bulk-scraping Google Maps (ToS violation) — browser-assisted research only.",

"assertions": [

"Identifies Local SMB branch",

"Asks about business category if not specified",

"Defaults radius to 20km",

"Runs browser research workflow",

"Applies 4-tier website status classification",

"Uses Hot/Warm/Cold/Skip scoring",

"Outputs Local SMB chat table columns",

"Adds top 3 outreach targets",

"References local-prospecting.md",

"Warns against bulk-scraping Google Maps"

"files": []

{

"id": 6,

"prompt": "I have a list of 200 prospect emails from Apollo. How do I know which ones are deliverable before I start outreach?",

"expected_output": "Should explain the deliverability validation step in Phase 3. Should recommend Truelist (the integration in this pack) for bulk validation. Should explain the email_state classification output: ok (deliverable), email_invalid (bounces, exclude), risky (deliverable with risk like role or disposable, include cautiously), unknown (couldn't determine, skip or re-verify), accept_all (catch-all domain, include cautiously). Should warn that Apollo data accuracy is typically 60-80% — sending without validation will tank sender reputation (bounce rate >2% triggers ISP throttling and reputation damage). Should recommend the workflow: bulk POST to /api/v1/verify or CSV upload → keep ok, include risky/accept_all cautiously, exclude email_invalid, re-verify unknown → hand off to outreach. Should note Truelist also has an official MCP server for agent-driven validation. Should note cold email reputation is hard to recover once damaged — validation is non-negotiable, not optional. Should mention Hunter and Snov as alternatives with built-in verification. Should reference truelist.md integration guide.",

"assertions": [

"Recommends Truelist for bulk validation",

"Explains email_state values (ok, email_invalid, risky, unknown, accept_all)",

"Warns Apollo accuracy is 60-80%",

"Cites 2% bounce rate threshold for reputation damage",

"Recommends workflow: validate, keep ok, exclude email_invalid",

"Mentions Truelist MCP server for agent workflows",

"Mentions cold email reputation is hard to recover",

"References truelist.md or data-sources.md"

"files": []

}

]

}

mdskills/prospecting/references/b2b-prospecting.md

4.8 kB

# B2B Prospecting Reference

For when the user sells to non-SaaS B2B — services, agencies, manufacturers, mid-market and enterprise companies, professional services firms.

---

## ICP Signals That Matter (B2B branch)

### Firmographic signals

- **Industry / vertical** — NAICS or SIC codes if precision matters

- **Company size** — headcount band, revenue band, location count

- **Geography** — relevant for time zones, regulations, on-site requirements

- **Business model** — service vs product vs distribution; B2B vs B2B2C

- **Ownership** — independent, PE-backed, public, family-owned — affects buying motion

### Buying signals

- **Trigger events**: new C-level hire, recent acquisition or divestiture, IPO/funding, opening a new location, recent rebrand, expansion announcement

- **Vendor signals**: posting RFPs publicly, switching costs in last quarterly report, contract renewal windows

- **Operational signals**: recent layoffs (cost pressure) or rapid hiring (capacity pressure)

- **News mentions**: launching new initiative, entering new market, regulatory change forcing action

- **PR / press**: anything that signals "this company is changing right now"

### Decay signals

- Multiple bankruptcies or PE-stripped operations

- Negative growth + cost-cutting headlines

- Ownership stagnation (small family-owned, no growth incentive)

- Buyer turnover (3+ Marketing Directors in 2 years)

---

## Discovery Sources (B2B branch)

### Tier 1 — primary discovery

- **Apollo**: best general B2B firmographic + contact discovery

- **ZoomInfo**: enterprise B2B + intent signals (mid-market+)

- **LinkedIn Sales Navigator**: industry + role + signal search; the gold standard for decision-maker mapping (manual)

- **Clay**: when you need custom waterfall lookups (e.g., enrich Apollo records with Hunter + Clearbit)

### Tier 2 — industry-specific directories

- **Crunchbase / Pitchbook**: funded businesses

- **D&B Hoovers**: large traditional B2B firmographics

- **State / national business registries**: for verified incorporation data

- **Industry association membership rosters**: trade groups often publish member lists

- **Trade show exhibitor lists**: signals active participation in a vertical

- **Procurement databases** (Procore for construction, e.g.): vertical-specific signals

### Tier 3 — trigger event monitoring

- **Google Alerts / Feedly**: trigger keywords ("acquired," "hires," "expansion," "raises," "announces")

- **PR Newswire / Business Wire**: company-controlled announcements

- **SEC filings** (public companies): material change disclosures

- **State filings**: new entity formation, dissolution

---

## Qualification Checklist (B2B branch)

- [ ] Industry / vertical matches ICP (use a recognized classification if possible)

- [ ] Company size within range (employees or revenue)

- [ ] Geography fits

- [ ] At least one trigger event in last 90–180 days

- [ ] Decision-maker role exists (CEO, COO, VP Operations, Director of X — match buyer profile)

- [ ] Email contact verifiable (named role > info@ catchall)

- [ ] Source URLs captured for firmographic claims

- [ ] No disqualifiers (closed, acquired-paused, multi-bankrupt, off-ICP)

---

## Output Columns (B2B branch)

Recommended CSV columns:

```csv

score,company,domain,industry,naics_code,size_band,revenue_band,country,city,trigger_event,trigger_date,contact_name,contact_title,contact_email,email_status,linkedin_url,source_urls,why_prospect,confidence,verified_date,notes

```

---

## Top Outreach Targets Selection (B2B)

Prioritize for the top 3–5 hot leads:

1. **Trigger event recency** — 30 days beats 6 months

2. **Trigger event specificity** — new CMO hire in your buyer's role beats "company in the news"

3. **Decision-maker access** — named contact with verified email + LinkedIn beats role-only

4. **Vertical fit precision** — exact NAICS match beats "adjacent industry"

Each top target rationale names the trigger and decision-maker: "Hired new VP of Marketing 14 days ago; verified email; mid-market manufacturer matching ICP."

---

## Common Mistakes (B2B)

1. **Treating B2B like SaaS** — funding rounds matter less; PE ownership and acquisition activity matter more.

2. **Trying to verify private company revenue precisely** — most public databases approximate. Use size bands, not point estimates.

3. **Ignoring procurement complexity** at enterprise scale — your prospect contact list may not include the actual approver.

4. **Cold-emailing executive assistants** — they're not the buyer and they will flag your outreach as spam.

5. **Source URL hygiene** — without source lineage, you can't defend a contact under GDPR DSAR or CAN-SPAM challenge.

6. **Stopping at one source** — Apollo can be 60% accurate on small businesses. Cross-verify with LinkedIn or the business website.

mdskills/prospecting/references/compliance.md

6.1 kB

# Prospecting Compliance Reference

The legal and platform-ToS constraints that apply to prospect list building. Read first, every engagement.

> Operational guidance, not legal advice. For high-volume programs or programs touching EU/UK residents, run your setup past a privacy attorney.

---

## United States — CAN-SPAM (downstream)

CAN-SPAM regulates the cold email **send**, not the list build. But the list build matters because:

- You must be able to identify the source of every email address you contact (required if challenged)

- The "from" line and email content rules apply at send time — but you can't lie about how you got the contact

- Opt-out requests must be honored within 10 business days and tracked

**For prospecting specifically**: capture and retain the source URL + date for every contact you add to a list. CAN-SPAM doesn't require it explicitly, but defending your sender practices does.

---

## EU / UK — GDPR

The strictest applicable framework. Triggers when:

- Your prospect resides in EU/UK

- You're processing personal data (any identifiable info, including business emails tied to a named person)

### Lawful bases for cold B2B outreach

You have three credible options:

1. **Legitimate interest** (most common for B2B). Requires:

- The contact is in a business role likely to be interested in your offer

- The data was collected from a public, business-context source

- You provide a clear opt-out

- You can articulate the legitimate interest test in writing

2. **Consent** — typically not feasible for cold outreach (you don't have consent before first contact)

3. **Existing customer relationship** — only applies to current customers, not prospects

### What you must do

- Capture **source + date + lawful basis** for every contact

- Honor data subject access requests (DSARs) — you must be able to disclose, correct, or delete on request

- Include a privacy notice / opt-out in the first outreach

- Don't store personal data longer than necessary for the legitimate interest

### What disqualifies a list

- Bulk-scraped LinkedIn data — explicit ToS violation + GDPR risk

- Email addresses purchased from a list broker without source provenance

- "Anyone @ this domain" guessed emails sent without verification (multiplies risk + bounces)

---

## Canada — CASL

Stricter than CAN-SPAM. Cold B2B outreach requires:

- **Express consent** (explicit opt-in) — typically not present for cold prospecting

- **OR implied consent** — existing business relationship within 24 months, OR business address publicly published on the company's own site for the purpose of receiving such communications

**Practical implication for Canadian prospects**: relying on the publicly-published-address exception is the most defensible cold prospecting basis in Canada. You must include sender identification, mailing address, and an unsubscribe mechanism in every message.

---

## Platform Terms of Service

### LinkedIn

- **Sales Navigator** as a research tool: fine

- **Scraping LinkedIn at any scale**: explicit ToS violation. Banned accounts are permanent. Don't.

- **Apollo, Clay, and ZoomInfo** claim LinkedIn-overlap data through various legitimate channels — verify their data sources before assuming compliance

- **InMail and Connection Requests**: governed by LinkedIn's own messaging rules, not by CAN-SPAM/GDPR (because LinkedIn-internal)

### Google Maps

- ToS prohibits bulk extraction or productizing Maps data

- Browser-assisted research as a discovery aid: acceptable

- Storing Place IDs or large structured Maps data in your CRM: explicit ToS prohibition

- Use Maps to **find** local businesses, then cross-source from the business's own site for the data you retain

### Apollo / ZoomInfo / Clearbit

- All have their own ToS limiting reselling, downstream sharing, and use cases

- Read your contract — typically you can use the data for your own outreach but not productize it

- Don't share extracts publicly (e.g., on a leaderboard, in a public report)

### Crunchbase

- Free tier is read-only for personal use

- Paid tier permits broader use within contractual scope

- API access requires paid Pro+ tier

---

## Anti-Patterns (Don't Do These)

1. **Bulk-scraping LinkedIn / Google Maps / Yelp**. Browser-assisted research is OK; automated scrapers pointed at these platforms are not. **Firecrawl and Browserbase are fine for an individual prospect's own website** (the URL you found through manual discovery) — not for the platforms hosting prospects.

2. **Buying lists from random vendors** without source provenance. You inherit their legal exposure.

3. **Guessing emails and sending unverified**. Bounce rates over 2% destroy sender reputation; legally, you can't claim a "legitimate interest" basis for an email you fabricated.

4. **Harvesting personal email addresses** (Gmail, personal Outlook, etc.) from public profiles. Personal addresses raise GDPR risk significantly.

5. **Storing data you don't need**. Minimize retention. Don't keep prospect lists forever — GDPR right to deletion applies.

6. **Skipping the lawful basis documentation**. If challenged, you need to show your work. Capture source URL + collection date for every contact.

7. **Reselling prospect lists**. You may not have the right to share them downstream. Read your data provider contracts.

8. **CAPTCHA bypass / login wall bypass**. Even if technically possible, this signals bot behavior and violates virtually every ToS.

---

## Quick Audit Checklist

Before shipping a list to the user (or downstream to cold-email):

- [ ] Every contact has a source URL + collection date

- [ ] No contacts sourced from scraped LinkedIn data

- [ ] No Google Maps Place IDs or large Maps-structured data retained

- [ ] Lawful basis documented (legitimate interest test for B2B, or relevant alternative)

- [ ] Email addresses validated (deliverability check before outreach)

- [ ] Personal addresses (Gmail, etc.) flagged or excluded

- [ ] Source provider contracts permit the intended use case

- [ ] Retention plan documented (when to delete)

- [ ] First outreach will include unsubscribe + privacy notice (downstream concern for cold-email skill, but mention it now)

mdskills/prospecting/references/data-sources.md

11 kB

# Prospecting Data Sources

Tool selection guide for prospecting across all three branches.

---

## Tool selection by goal

| Goal | Primary tools | Notes |

|------|--------------|-------|

| **Build initial firmographic list (B2B / SaaS)** | Apollo, ZoomInfo, Clay | Apollo for breadth, ZoomInfo for enterprise + intent, Clay for custom workflows |

| **Decision-maker mapping** | LinkedIn Sales Navigator (manual), Apollo, ZoomInfo | Sales Nav is the gold standard. Never bulk scrape it. |

| **Tech stack qualification (SaaS)** | BuiltWith, Wappalyzer | BuiltWith has wider coverage + paid plans for bulk; Wappalyzer is lighter + free for small use |

| **Funding signals (SaaS)** | Crunchbase, Pitchbook | Crunchbase free tier sufficient for early signals; Pitchbook for deeper investor data |

| **Email pattern discovery** | Hunter, Snov, Apollo | Pattern guessing — followed by verification |

| **Email deliverability verification** | Truelist, Hunter, NeverBounce, ZeroBounce | Always verify before adding to outreach lists |

| **Visitor identification (warm intent)** | RB2B, Clearbit Reveal | Anonymous traffic → company identification |

| **Intent data** | ZoomInfo Intent, 6sense, Bombora | Pre-warmed signals; mid-market+ pricing |

| **Trigger event monitoring** | Google Alerts, Feedly, LinkedIn Sales Nav alerts | Free options are sufficient for most |

| **Local business discovery** | Google Maps (manual), Yelp, Facebook Pages | Browser-assisted, not bulk-extracted |

---

## Apollo

**Use for**: General B2B / SaaS firmographic + contact data. Best starting point if you don't already have a list.

**Strengths**:

- Large database (>200M contacts, >60M companies)

- Strong filtering UI (industry, size, technologies, signals)

- Integrated email + LinkedIn finder

- Pay-as-you-go and tiered plans

**Watch out for**:

- Data freshness varies — re-verify before scoring as "Hot"

- Email accuracy ~60–80% — always validate

- Bulk export limits apply

**Integration**: see [apollo.md](../../../tools/integrations/apollo.md)

---

## Clay

**Use for**: Multi-source enrichment, waterfall lookups, custom scoring logic. When list quality matters more than list size.

**Strengths**:

- Waterfall logic: try Apollo first → fallback to ZoomInfo → fallback to Clearbit

- 100+ data provider integrations

- AI-powered enrichment (LLM-driven extraction from URLs)

- Custom columns + scoring formulas

- Native MCP server

**Watch out for**:

- Per-credit pricing can spike on large lists

- Complexity overhead — easy to over-engineer workflows

**Integration**: see [clay.md](../../../tools/integrations/clay.md)

---

## ZoomInfo

**Use for**: Enterprise B2B + intent data. Mid-market+ buyer profiles.

**Strengths**:

- Enterprise-grade firmographic depth

- Intent signals (companies searching topics relevant to your offer)

- Best-in-class for >$50K ACV B2B sales

- Native MCP server

**Watch out for**:

- Expensive ($15K+/yr starter)

- Overkill for SMB prospecting

- Locked into multi-year contracts typically

**Integration**: see [zoominfo.md](../../../tools/integrations/zoominfo.md)

---

## Clearbit

**Use for**: Email → company enrichment, anonymous visitor identification (Clearbit Reveal).

**Strengths**:

- Strong company enrichment (industry, size, funding, tech stack)

- Email lookup by domain

- Reveal: identify anonymous site visitors at company level

- API-first

**Watch out for**:

- HubSpot acquisition (2023) — bundled into HubSpot Breeze Intelligence now

- Standalone API still available but pricing/access depends on tier

**Integration**: see [clearbit.md](../../../tools/integrations/clearbit.md)

---

## Hunter / Snov

**Use for**: Email pattern discovery + lightweight verification on small lists.

**Hunter strengths**:

- Domain-based email discovery

- Built-in deliverability verification

- Free tier reasonable for occasional use

**Snov strengths**:

- Email finder + drip campaigns (overlap with outreach tooling)

- Bulk verification

- Cheaper than Hunter at scale

**Watch out for**:

- Both are pattern-guessing tools — accuracy depends on the target company's email pattern being inferable

- Always run results through a dedicated validator (Truelist or similar) before outreach

**Integrations**: see [hunter.md](../../../tools/integrations/hunter.md), [snov.md](../../../tools/integrations/snov.md)

---

## Truelist

**Use for**: Email deliverability validation before adding contacts to outreach lists. Critical safety step.

**Strengths**:

- Single-email sync verification (`/api/v1/verify_inline`) + bulk async (`/api/v1/verify`)

- Returns `email_state` (ok / email_invalid / risky / unknown / accept_all) + `email_sub_state` (email_ok / is_disposable / is_role / unknown_error / failed_smtp_check) + did-you-mean typo suggestions

- Catches catch-all domains, role accounts, spam traps, disposable providers

- Official MCP server for agent-driven workflows (Claude, Cursor, VS Code)

- Official SDKs in 7 languages + framework integrations (Django, Laravel, Next.js, Rails, React, Svelte, Vue, WordPress)

- Native integrations with Mailchimp, Klaviyo, HubSpot, Zapier, Make, n8n, Clay, Salesforce, more

- Pay-per-email pricing

**Why this matters**: Cold email reputation craters when bounce rates exceed 2%. Validating before sending is non-negotiable. Apollo/ZoomInfo/Hunter data is often 60–80% accurate — Truelist catches the rest.

**Integration**: see [truelist.md](../../../tools/integrations/truelist.md)

---

## LinkedIn Sales Navigator

**Use for**: Manual decision-maker discovery. The gold standard for B2B / SaaS prospecting but only when used as a research tool.

**Strengths**:

- Most accurate decision-maker data in the industry

- Real-time job changes, posts, signals

- Lead lists, alerts, saved searches

- Inmail credits (separate channel from cold email)

**Hard rules**:

- **Never bulk scrape**. LinkedIn aggressively bans scrapers. Account ban risk is real and permanent.

- Use Sales Nav as a research interface — open profiles, read, take notes, capture key data manually.

- Apollo and other tools claim LinkedIn data via partnerships / public mirroring — verify the source legitimacy before assuming compliance.

**Integration**: no MCP or API access at consumer level. Manual research only.

---

## BuiltWith / Wappalyzer

**Use for**: Tech stack qualification (SaaS branch).

**BuiltWith**:

- ~50K+ technologies tracked

- API + bulk lookups (paid)

- Historical data (when stack changed)

**Wappalyzer**:

- Free browser extension; paid API

- Lighter coverage than BuiltWith

- Faster for one-off lookups

Cross-reference both for high-confidence tech stack signals.

---

## Crunchbase

**Use for**: Funding signals (SaaS branch).

**Strengths**:

- Free tier shows recent funding events

- Paid (Pro / Enterprise) unlocks alerts and deep history

- API access for paid users

**Watch out for**:

- Coverage is best for VC-backed companies; bootstrapped + small businesses underrepresented

- Self-reported data — verify funding amounts independently

---

## GitHub (stargazers / forks / watchers)

**Use for**: Developer-intent prospecting. Especially powerful for dev-tool SaaS — stargazers of competitor or category-defining repos are in-market signal.

**Strengths**:

- Public API, no scraping concerns

- High signal quality (a starred repo = explicit interest)

- Forks are an even stronger signal (intent to modify, not just bookmark)

- Bundled `github-prospects.js` CLI handles pagination + enrichment + CSV output

- Free with 5,000 req/hr authenticated rate limit

**Watch out for**:

- Only ~5–20% of users publish email — pair with Apollo/Clay/Hunter for enrichment

- Very-popular repos (100K+ stars) are mostly noise; smaller targeted repos (5K–25K) give better signal density

- Most prospects are individuals, not company contacts directly — need to figure out their company from `company` field or LinkedIn

**Integration**: see [github.md](../../../tools/integrations/github.md)

---

## Firecrawl / Browserbase (single-target site research)

**Use for**: Programmatically extracting content from a **prospect's own website** that you already found via discovery on platforms like Google Maps, Yelp, or LinkedIn. Not for scraping those platforms themselves.

### Firecrawl

- **Best for**: "Just give me the page as markdown" — Local SMB website status checks, B2B company about/team page extraction, structured field extraction

- **Strengths**: Low overhead, returns clean LLM-ready markdown, handles most JS-rendered sites, has an MCP server

- **API + MCP + SDKs**: Node, Python, Go, Rust

### Browserbase

- **Best for**: When you need real Chromium — JS-heavy pages, cookie consent dialogs, form submission to reach a contact page, session state

- **Strengths**: Full browser control via Playwright/Puppeteer; Stagehand provides AI-friendly natural-language extraction; session recordings for debugging

- **API + MCP (Stagehand) + SDKs**: Node, Python

### Critical compliance line

Both tools can technically point at any URL. The hard rule:

- ✓ **OK**: extracting content from a single business's own website (`joescoffeeshop.com`) that you found through manual discovery

- ✗ **NOT OK**: pointing them at `google.com/maps`, LinkedIn search results, Yelp listings, or any platform whose ToS prohibits bulk extraction

Discovery happens on platforms (manual browser-assisted research). Extraction happens on individual public business sites.

**Integrations**: see [firecrawl.md](../../../tools/integrations/firecrawl.md), [browserbase.md](../../../tools/integrations/browserbase.md)

---

## RB2B / Clearbit Reveal

**Use for**: Identifying anonymous site visitors as warm intent signals.

**Strengths**:

- Pixel-based visitor → company identification

- High-intent: they came to your site, they're already in research mode

- Slack / email alerts on key visits

**Watch out for**:

- Privacy/GDPR considerations — verify your privacy policy disclosures

- Person-level identification raises higher concerns than company-level

**Integration**: see [rb2b.md](../../../tools/integrations/rb2b.md)

---

## Free / browser-only fallbacks

When the user has no paid tools, lean on:

- **Google Search** — exact business name + city + role searches

- **LinkedIn** (manual, no scraping) — company pages, employee lookups

- **Crunchbase free tier** — funding events

- **Wappalyzer browser extension** — tech stack at a glance

- **Hunter.io free tier** — 25 lookups/month

- **Google Maps** — for Local SMB discovery

- **Business websites + About pages** — primary source for any claim

- **News sites + press releases** — trigger event monitoring via Google Alerts

Slower than tooled-up workflows, but produces high-quality smaller lists if the user is willing to do the work.

---

## Sequencing recommendations

A typical full-stack prospecting workflow:

1. **Define ICP** from product-marketing context (no tools needed)

2. **Initial list** from Apollo or ZoomInfo (firmographic filter)

3. **Enrich** with Clay (waterfall: tech stack, funding, trigger events)

4. **Decision-maker mapping** in LinkedIn Sales Nav (manual)

5. **Email pattern discovery** with Hunter or Apollo's built-in

6. **Email validation** with Truelist before final list

7. **Hand off** to cold-email skill for outreach copy

Adapt this sequence based on which tools the user actually has.

mdskills/prospecting/references/local-prospecting.md

8.0 kB

# Local SMB Prospecting Reference

For when the user sells to local small businesses — shops, gyms, restaurants, salons, clinics, professional services, contractors, real estate, fitness studios, dental practices.

Adapted from and generalized beyond the local-client-prospector pattern (browser-assisted discovery + website status classification + proximity scoring).

---

## ICP Signals That Matter (Local SMB branch)

### Operational signals

- **Active business** — Google Business Profile updated, recent reviews, recent hours updates

- **Recent activity** — open right now, regular hours posted, recent photos uploaded by owner

- **Customer engagement** — owner responding to reviews, posts on social, active calendar (for service businesses)

### Online presence signals (the core SMB qualification axis)

The reference local-client-prospector skill uses **website status** as the primary qualification — port this directly. Four classifications:

| Status | Definition | Typical outcome |

|--------|-----------|-----------------|

| **No site found** | No credible standalone website after cross-checked search | **Hot prospect** for web/marketing service |

| **Social only** | Facebook, Instagram, WhatsApp, Linktree, booking portal, marketplace page only — no standalone site | **Hot prospect** for web/marketing service |

| **Weak site** | Standalone site exists but outdated, broken, very thin, non-mobile-friendly, or missing clear contact/conversion flow | **Warm prospect** for refresh / rebuild service |

| **Has site** | Credible, modern standalone site exists | **Low prospect** unless other signals apply (e.g., poor SEO, weak conversion design) |

### Proximity signals

- **Distance** from the user's location or service area

- **Density** — clusters of similar businesses in one area = neighborhood targeting opportunity

- **Travel time** — useful when in-person discovery, install, or service delivery is required

### Decay signals

- Closed permanently (Google Maps banner)

- Reviews paused or business listing reported as closed

- Last activity (review, post) >12 months ago

---

## Discovery Sources (Local SMB branch)

### Primary

- **Google Maps** (browser, manual) — search "category near [location]" and walk the visible results. Cross-check details. Don't bulk-extract.

- **Yelp** — secondary verification; complementary categories

- **Bing Local / Apple Maps** — different coverage on smaller businesses

- **Facebook Pages search** — many SMBs are Facebook-only

### Cross-verification

- **Business's own website** (if any)

- **Industry directories** (e.g., Healthgrades for medical, OpenTable for restaurants, Avvo for legal)

- **Local Chamber of Commerce listings**

- **State business registries** for incorporation status

- **Search results for "[business name] [city]"** to discover non-Maps presence

---

## Browser Research Workflow

1. Open a browser and search Google Maps for the category near `base_location`

2. Build a candidate list from visible local results, search results, and public directories

3. For each candidate, inspect public sources to fill required fields

4. Search the exact business name plus city/town to check whether a standalone website exists

5. Classify website status per the table above

6. Mark confidence: High (2+ sources), Medium (1 source + consistent evidence), Low (incomplete/ambiguous)

When the user explicitly asks for subagents AND subagents are available, split candidates into non-overlapping batches and ask each subagent to verify only website/social/contact status. Don't use subagents for the primary search if it slows progress.

### Optional: programmatic verification with Firecrawl or Browserbase

Once you have a candidate's website URL (found via manual Maps/Yelp discovery), you can speed up website-status classification by hitting the URL programmatically:

- **Firecrawl** for simple "is this site live, modern, mobile-friendly, conversion-flow-equipped" reads — returns clean markdown you can inspect

- **Browserbase** when the candidate site requires JS rendering, has a cookie consent dialog, or you need session state

**Strict line**: use these on the individual business's URL. **Don't** point them at Google Maps, Yelp, or any platform whose ToS prohibits bulk extraction — discovery stays manual.

See [data-sources.md](data-sources.md) for setup details.

---

## Qualification Checklist (Local SMB branch)

- [ ] Business is active (recent reviews or activity in last 6 months)

- [ ] Category matches user's service offering

- [ ] Distance / proximity within target radius

- [ ] Website status classified

- [ ] Phone or contact channel verified

- [ ] At least one cross-source confirms business operates at the listed address

- [ ] Not a duplicate / chain location / out-of-scope category

- [ ] Not closed permanently

---

## Lead Scoring (Local SMB)

Use this simple rubric (matches local-client-prospector pattern):

| Score | Criteria |

|-------|----------|

| **Hot** | No site found OR social-only + phone present + active business + within target radius |

| **Warm** | Weak site, poor online presentation, or marketplace/booking-page only |

| **Cold** | Good website already present OR low confidence |

| **Skip** | Closed, duplicate, outside radius, irrelevant category, or not a business prospect |

---

## Output Columns (Local SMB branch)

Chat table (≤15 rows):

```

```

CSV:

```csv

score,business,category,area,distance_km,website_status,website_url,social_urls,phone,email,source_urls,why_prospect,confidence,verified_date,notes

```

Rules:

- Keep "Why it's a prospect" short and actionable

- Use `Not found` instead of leaving blank fields

- Include source links sparingly, not all of them

- After the table, add **Best first outreach targets** with the top 3 leads and one practical reason each

- If confidence is low, state exactly what remains uncertain

---

## Top Outreach Targets Selection (Local SMB)

Prioritize for the top 3 hot leads:

1. **No site / social only + phone present** = clearest service opportunity

2. **High review count** = active, established business with real customers

3. **Owner-responded reviews** = engaged owner = more likely to evaluate a vendor

4. **Industry alignment with your service specialty** beats generic category match

Each top target rationale should be one sentence naming the gap and the signal: "No standalone website (cross-checked); 80+ Google reviews with owner replies; 2 km from target area."

---

## Compliance Notes (Local SMB-specific)

The local branch is the most scraping-sensitive of the three motions. Specifically:

- **Google Maps Terms of Service** prohibit bulk extraction. Treat browser visits as research, not as data acquisition.

- **Don't store full Google Maps Place IDs in your CRM** — the ToS limits storage of Maps data.

- **Public business contact channels only**: published phone, contact form, info@ email. Don't reach individual employees through their personal channels.

- **Owner/operator name when published on the business's own site** is OK to use. If you only got it from LinkedIn, mark the source.

---

## Common Mistakes (Local SMB)

1. **Bulk-scraping Google Maps** — fastest way to violate ToS and lose the research channel.

2. **Treating Google Maps data as truth** — listings go stale. Cross-check hours, status, and reviews.

3. **Skipping the website status cross-check** — finding "no site" on Maps doesn't mean no site exists; do an exact-name web search before classifying.

4. **Targeting only the largest businesses** — they're already covered by other providers. The 2–5 employee SMBs are the under-served opportunity.

5. **Generic outreach to all hot leads** — local SMBs respond better to outreach that names their specific gap ("I noticed your menu isn't visible on mobile") than generic pitches.

6. **Ignoring chains and franchises** as Skip — sometimes the franchisee is the buyer and they have local marketing authority. Verify before skipping.

mdskills/prospecting/references/saas-prospecting.md

5.9 kB

# SaaS Prospecting Reference

For when the user sells SaaS or digital services to other SaaS companies / digital businesses.

---

## ICP Signals That Matter (SaaS branch)

Beyond standard firmographics (industry, size, geography), SaaS prospects are qualified by:

### Technographic signals

- **Tech stack** — do they use complementary tools (your integration target) or competing tools (a switch opportunity)?

- **Recent stack changes** — adding/removing tools signals active vendor evaluation

- **Custom-built vs off-the-shelf** — DIY tooling often means a buyer who'd benefit from your product

- **Free/freemium plan signals** — using a free competitor means they may be ready to upgrade

### Growth signals

- **Funding round** — Series A / B / C in last 6 months = budget + new hires + tool needs

- **Headcount growth** — 10%+ growth in last quarter signals scaling pressure

- **Hiring signals** — specific role openings (e.g., "Head of RevOps" → ICP for revops tooling)

- **Product velocity** — frequent shipping, new features, blog posts = healthy growth motion

- **Open positions for your buyer's role** — if you sell to Marketing Ops and they're hiring one, that's a signal

### Decay signals (downgrade scoring)

- Layoffs in target department

- Funding round >2 years ago with no follow-up

- Product hasn't shipped in 6+ months

- Team page shows founders only (very early — may not have budget)

---

## Discovery Sources (SaaS branch)

Combine 2+ sources for cross-verification.

### Tier 1 — primary discovery

- **Apollo**: firmographic + technographic + contact data. Good for building large initial lists.

- **Clay**: waterfall enrichment, custom scoring, multi-source merges. Best for high-quality smaller lists.

- **ZoomInfo**: enterprise-grade firmographic + intent signals. Expensive; mid-market+.

- **LinkedIn Sales Navigator**: decision-maker mapping. Use manually, never bulk scrape.

### Tier 2 — technographic / growth signals

- **BuiltWith**: tech stack lookups, find sites using specific tools

- **Wappalyzer**: free browser extension + API; lighter tech stack signal

- **Crunchbase**: funding rounds, headcount, founders

- **Pitchbook**: deeper investor data (enterprise/paid)

- **ProductHunt**: recent launches, builder audience

- **Hacker News / Show HN**: technical builders launching products

### Tier 3 — buying signals

- **Job boards** (LinkedIn Jobs, Indeed, AngelList): role openings as signals

- **RB2B / Clearbit Reveal**: visitor identification (warm anonymous traffic)

- **GitHub stars/forks of competitor or adjacent repos**: developer-level intent signal (see `tools/integrations/github.md` and the `github-prospects.js` CLI). Especially strong for dev-tool SaaS — a developer who starred `vercel/next.js` last week is in-market for adjacent Next.js infrastructure.

- **Recent blog posts / changelog**: product direction signals

- **G2 reviews mentioning competitor switches**: explicit dissatisfaction signal

#### GitHub prospecting pattern (when audience is developers)

For dev-tool SaaS, GitHub is one of the highest-quality discovery channels:

1. Identify 3–5 "anchor" repos: your direct competitors, your category leader, complementary tools your buyer uses

2. Pull stargazers (or forks for stronger intent) via `node tools/clis/github-prospects.js stargazers <owner/repo> --enrich --with-company --format csv`

3. Filter to users with `company` set — these are the easiest to enrich downstream

4. Pair with Apollo/Clay/Hunter to lookup email by name + company

5. Validate with Truelist before adding to outreach list

Tradeoffs: GitHub yields email for only ~5–20% of users directly. The strength is the signal quality — a stargazer of a niche dev tool is genuinely in-market in a way Apollo firmographics alone can't tell you.

---

## Qualification Checklist (SaaS branch)

For each candidate, verify:

- [ ] Industry vertical matches ICP

- [ ] Company size (headcount) within range

- [ ] Tech stack includes (or notably excludes) a target technology

- [ ] Funding stage matches buyer maturity

- [ ] At least one growth signal in last 90 days (funding, hiring, product velocity)

- [ ] Decision-maker role exists at the company (named or inferable from job listings)

- [ ] Email contact verifiable

- [ ] No disqualifiers (closed, acquired-and-paused, layoffs, ICP miss)

---

## Output Columns (SaaS branch)

Recommended CSV columns:

```csv

score,company,domain,industry,size_band,country,funding_stage,last_round_date,tech_stack_match,signal,signal_date,contact_name,contact_title,contact_email,email_status,linkedin_url,source_urls,why_prospect,confidence,verified_date,notes

```

---

## Top Outreach Targets Selection (SaaS)

Prioritize for the top 3–5 hot leads:

1. **Strongest signal recency** — funding 30 days ago beats funding 9 months ago

2. **Tech stack match strength** — known integration partner beats inferred fit

3. **Decision-maker named with verified email** — beats role-pattern-guessed email

4. **Multi-source confidence** — both Apollo + Crunchbase agree beats one source

Each top target gets a one-sentence outreach rationale that names the specific signal: "Raised Series B 30 days ago; hiring Head of RevOps; verified VP of Ops email."

---

## Common Mistakes (SaaS)

1. **Buying lists from Apollo wholesale** without re-verifying email and re-checking firmographics. Stale data is the norm.

2. **Treating tech stack data as 100% accurate**. BuiltWith and Wappalyzer miss things; Clay's waterfalls miss things. Cross-check.

3. **Targeting Series C+ for early-stage SaaS sellers**. The buyer profile is wrong — too many procurement hoops, too much red tape.

4. **Targeting Series Pre-Seed seed** for products requiring meaningful budget. They have neither budget nor evaluator bandwidth.

5. **Ignoring intent data when it exists** (ZoomInfo Intent, 6sense, etc.) — pre-warm signals beat cold every time.

mdskills/prospecting/SKILL.md

15 kB

---

description: When the user wants to find, qualify, and build a list of prospects to reach out to — across B2B SaaS, general B2B, or local small businesses. Also use when the user mentions "prospecting," "build a prospect list," "find prospects," "find leads," "lead gen list," "find SaaS companies that," "find B2B companies," "find local businesses," "ICP-fit accounts," "who should we go after," "outbound list," "target account list," "find clients near me," "businesses without websites," "prospect research," or "qualified leads." Use this for the list-building and qualification phase. For writing the outbound copy after the list is built, see cold-email. For deep competitive research on specific accounts, see competitor-profiling.

metadata:

version: 1.0.0

---

# Prospecting

You are an expert at building qualified prospect lists across three motions: B2B SaaS, general B2B, and local small businesses. Your goal is to turn an ICP definition into a verified, scored, ready-to-outreach lead sheet — using the right data sources, qualification signals, and compliance posture for each motion.

## Before Starting

**Check for product marketing context first:**

## Pick the Branch

Prospecting motions differ enough that the workflow forks at intake. Pick **one** branch based on who the user is selling to:

|--------|---------|----------------------------|----------------|

| **SaaS** | Other SaaS companies / digital businesses | ICP fit + tech stack match + growth signals (funding, hiring, product velocity) | LinkedIn, BuiltWith, Crunchbase, Apollo, Clay, Clearbit, ProductHunt |

| **B2B** | Non-SaaS B2B (services, manufacturers, enterprises, mid-market) | Industry + size + geographic fit + buying signals (trigger events, vendor changes) | Apollo, ZoomInfo, Clay, Clearbit, LinkedIn Sales Nav, industry directories |

| **Local SMB** | Local small businesses (shops, gyms, restaurants, clinics, salons, services) | Active business + website status + proximity + decision-maker access | Google Maps, Yelp, local directories, Facebook, business websites |

If the user describes a hybrid motion (e.g., "SMBs that are also SaaS"), pick the dominant branch and pull in qualification signals from the other.

For the branch-specific deep dives:

- **SaaS** → see [references/saas-prospecting.md](references/saas-prospecting.md)

- **B2B** → see [references/b2b-prospecting.md](references/b2b-prospecting.md)

- **Local SMB** → see [references/local-prospecting.md](references/local-prospecting.md)

---

## Shared Framework (all branches)

Every prospecting engagement follows the same five phases. Tools and qualification signals change per branch; the phases don't.

### Phase 1 — Define the ICP

Pull from `product-marketing.md` if available. Otherwise, gather:

1. **Firmographic fit** — industry, company size, revenue band, geography, business model

2. **Technographic fit** (SaaS branch) — what tools they already use, what they're missing

3. **Buying signal** — why now? (trigger event, funding, hiring, new initiative, dissatisfaction with current vendor, recent move/expansion)

4. **Decision-maker profile** — role, seniority, what they care about

5. **Disqualifiers** — what makes a prospect a clear "skip"

Output the ICP as a one-paragraph statement plus a checklist of pass/fail criteria. Don't move to discovery without this.

### Phase 2 — Build the candidate list (discovery)

Source 2–3× more candidates than the user wants in the final list — qualification will cull aggressively.

- **SaaS / B2B**: combine 2–3 sources for cross-verification. Apollo or ZoomInfo for firmographics; Clearbit or Clay for enrichment; LinkedIn Sales Nav for decision-maker mapping.

- **Local SMB**: browser-assisted research starting with Google Maps for the target category in the target area; cross-check with Yelp, the business website, social pages, and public directories.

If the user's list quality bar is high, smaller is better. 25 verified leads beats 250 mostly-junk ones.

### Phase 3 — Qualify each candidate

Score every candidate against the ICP checklist. Add **evidence** (a source URL or two) for each qualification — never assert without backing.

**Confidence levels** (used across all branches):

- **High**: confirmed by at least two independent sources or official business page

- **Medium**: one credible source plus consistent search evidence

- **Low**: incomplete or ambiguous evidence — flag what remains uncertain

For email contacts (B2B / SaaS branches), **always verify deliverability before adding to the final list** — see Truelist integration in [references/data-sources.md](references/data-sources.md). Don't ship leads with invalid or risky emails.

### Phase 4 — Score and prioritize

Apply this rubric across all branches:

| Score | Definition |

|-------|------------|

| **Hot** | Strong ICP fit + clear buying signal + decision-maker accessible + verified contact |

| **Warm** | ICP fit + softer or older signal + contact verifiable |

| **Cold** | Loose ICP fit OR no clear signal OR contact unverified |

| **Skip** | Disqualifier hit (out of ICP, closed business, duplicate, irrelevant, low confidence) |

Branch-specific signals refine the scoring — see each reference file. Default ratio target: ~20% Hot, ~30% Warm, rest Cold/Skip.

### Phase 5 — Output the lead sheet

Default to a markdown table in chat. Switch to CSV when the list is >25 rows or the user explicitly asks for a file.

After the table, always add **"Top outreach targets"** — the top 3–5 hot leads with one sentence each on why this lead should be reached out to first.

Columns vary by branch (see reference files), but every lead sheet includes:

- score, business/company name, contact (where applicable), why-it's-a-prospect, source(s), confidence, last verified date

---

## Compliance Guardrails

These apply to every branch. **Read first, every engagement.**

1. **No bulk scraping** of LinkedIn, Google Maps, paywalled sites, or rate-limited APIs. Browser is an assisted research tool, not a scraper.

2. **No CAPTCHA, login wall, or bot protection bypass.** If a site requires it, work with what's publicly visible.

3. **Public business contact channels only.** Use info@, hello@, contact@, and named-role emails (founder, owner) where they're published on the business's own site. Personal/private emails require a lawful basis (existing relationship, opt-in, etc.).

4. **GDPR / CAN-SPAM / CASL aware.** Capture and retain the source URL and date for every contact you add to a list — required for downstream outreach compliance.

5. **No reselling extracted data** from Google Maps, LinkedIn, or any platform whose terms prohibit it. List building for the user's own outreach is fine; productizing the list to sell is not.

6. **Rate limit yourself.** Even on public sources, space requests. Don't fingerprint as a bot.

For the full compliance reference (GDPR, CAN-SPAM, CASL, LinkedIn ToS, Google Maps ToS, Clay/Apollo/ZoomInfo use restrictions): see [references/compliance.md](references/compliance.md).

---

## Inputs to Collect

If missing, ask once, then infer reasonable defaults and continue:

- **Branch** (SaaS / B2B / Local SMB) — usually inferable from context

- **ICP description** — pull from `product-marketing.md` if present

- **Target count** — default 25 for SaaS / B2B, 15 for Local SMB

- **Geography** (essential for Local SMB; useful for B2B; less critical for SaaS)

- **Tools the user has access to** — Apollo? Clay? ZoomInfo? Hunter? Truelist? Defaults to what's free + browser

- **Output format** — chat table (default) or CSV

- **Buying signal preference** — what triggers should they prioritize? (funding rounds, hiring, recent move, etc.)

---

## Tool Selection Quick Picks

Full breakdown in [references/data-sources.md](references/data-sources.md). Quick picks:

| If the user has access to... | Use it for |

|------------------------------|------------|

| **Apollo** | B2B / SaaS firmographic + contact discovery |

| **Clay** | Multi-source enrichment, waterfall lookups, custom scoring |

| **Clearbit** | Email-to-company and company enrichment |

| **ZoomInfo** | Enterprise B2B contact + intent data |

| **Hunter or Snov** | Email pattern guessing and verification |

| **Truelist** | Email deliverability validation (before adding to outreach list) |

| **LinkedIn Sales Navigator** | Decision-maker mapping (manual, no scraping) |

| **BuiltWith / Wappalyzer** | Tech stack qualification (SaaS branch) |

| **Crunchbase** | Funding signals (SaaS branch) |

| **GitHub** | Stargazers / forks of competitor or adjacent repos (dev-tool SaaS branch) |

| **Google Maps + browser** | Local SMB discovery |

| **Firecrawl / Browserbase** | Programmatic extraction from individual prospect websites — never from platforms |

**If the user has no enrichment tools**: lean on browser-assisted research with public sources — company website, About page, LinkedIn company page, news mentions. Slower but works.

---

## Output Formats

### Default — chat table

For SaaS / B2B (≤25 rows):

```

| --- | --- | --- | --- | --- | --- | --- | --- | --- |

```

For Local SMB (≤15 rows) — port from the local-prospector reference:

```

| --- | --- | --- | --- | --- | --- | --- | --- | --- |

```

### CSV — when >25 rows or user requests a file

SaaS / B2B columns:

```csv

score,company,domain,industry,size_band,country,signal,contact_name,contact_title,contact_email,email_status,linkedin,source_urls,why_prospect,confidence,verified_date,notes

```

Local SMB columns:

```csv

score,business,category,area,distance_km,website_status,website_url,social_urls,phone,email,source_urls,why_prospect,confidence,verified_date,notes

```

### Always include after the table

- **Top outreach targets**: top 3–5 hot leads with one-sentence outreach rationale each

- **Search parameters**: branch, ICP, location/radius, target count, date generated

- **Open questions**: anything you couldn't verify and the user should look at

---

## Quality Checks (before finalizing)

- [ ] Remove duplicates (by domain for SaaS/B2B, by business + address for Local SMB)

- [ ] Every "Hot" lead has a verified contact + at least one source URL

- [ ] No lead has an email that failed Truelist (or your validator) verification — move to a separate "invalid" bucket and flag for the user

- [ ] No lead labeled "Hot" lacks a clear buying signal

- [ ] Confidence levels honest — "High" requires 2 independent sources, not just two of your own searches

- [ ] No leads sourced from prohibited scraping (LinkedIn at scale, Google Maps bulk extract, etc.)

- [ ] Source URL + date captured for every contact (GDPR / CAN-SPAM lineage)

- [ ] Final count matches user's request, or you've explained why it's smaller (quality bar)

---

## Common Mistakes

1. **Starting discovery without an ICP**. Build candidates against vague criteria and you'll qualify the wrong things.

2. **Treating data sources as authoritative without cross-checks**. Apollo and ZoomInfo are out of date often; verify before scoring as "Hot."

3. **Adding contacts without email verification**. Cold email reputation tanks fast with bounces — always validate.

4. **Bulk scraping LinkedIn or Google Maps**. Real risk: account suspension + ToS violation. Browser as an assisted tool only.

5. **Mixing branches**. Don't apply Local SMB scoring (website status) to a B2B SaaS prospect, or vice versa.

6. **"Hot" labels without buying signals**. ICP fit alone is not enough — the signal is what makes the timing right.

7. **No source URLs**. Every claim should be traceable to a public source. Future outreach depends on this lineage.

8. **Ignoring quiet hours / time zone** when scheduling the downstream outreach (handoff to cold-email).

9. **Forgetting to retain consent / lineage records**. Required for GDPR DSARs and CAN-SPAM audits.

---

## Task-Specific Questions

1. Which branch — SaaS, B2B, or Local SMB?

2. What's your ICP? (Or: should I pull from your product-marketing context?)

3. How many qualified leads do you want?

4. What tools do you have access to (Apollo / Clay / ZoomInfo / Hunter / Truelist / browser only)?

5. What's the triggering buying signal you care most about?

6. Geography or radius (Local SMB / B2B)?

7. Chat table or CSV?

---

## Tool Integrations

For implementation, see the [tools registry](../../tools/REGISTRY.md). Key prospecting tools:

|------|----------|:---:|-------|

| **RB2B** | Visitor identification (warm intent) | - | [rb2b.md](../../tools/integrations/rb2b.md) |

---

## Related Skills

- **cold-email**: For writing outbound sequences against the qualified list (the natural next step after prospecting)

- **customer-research**: For understanding why current customers buy — informs the ICP definition

- **competitor-profiling**: For deeper research on individual accounts (different from list-building qualification)

- **revops**: For lead routing, lifecycle, and CRM handoff after prospecting

- **sales-enablement**: For battle cards and one-pagers used in the outreach

- **directory-submissions**: For inbound discovery surfaces (the prospects might find you back)

- **product-marketing**: For the ICP definition that anchors every prospecting engagement

jsonskills/referrals/evals/evals.json

6.3 kB

{

"skill_name": "referrals",

"evals": [

{

"id": 1,

"prompt": "Help me design a referral program for our SaaS product. We're a $49/month project management tool with about 1,000 customers. We want to encourage word-of-mouth growth.",

"expected_output": "Should check for product-marketing.md first. Should distinguish between referral and affiliate programs (this is referral — existing customers referring peers). Should design the referral loop: trigger point (when to ask for referral), share mechanism (unique link, email invite, social share), conversion flow (what the referred person experiences), and reward structure. Should recommend incentive type: double-sided recommended (both referrer and referred get value). Should suggest specific incentives appropriate for $49/month SaaS (e.g., free month for both). Should include the launch checklist. Should recommend tool integrations (Rewardful, Tolt, etc.).",

"assertions": [

"Checks for product-marketing.md",

"Distinguishes referral from affiliate",

"Designs the referral loop (trigger, share, convert, reward)",

"Recommends double-sided incentive structure",

"Suggests specific incentives for the price point",

"Includes launch checklist",

"Recommends tool integrations"

"files": []

{

"id": 2,

"prompt": "We have a referral program but only 5% of customers have ever referred someone. How do we increase participation?",

"expected_output": "Should apply the program optimization guidance. Should diagnose low participation: are customers aware of the program? Is the trigger point well-timed? Is the incentive compelling enough? Is sharing easy? Should recommend optimization tactics: better placement/visibility, timing referral asks at peak satisfaction moments, improving the incentive, simplifying the share mechanism, adding referral reminders in email and in-app. Should provide specific experiment ideas to test improvements.",

"assertions": [

"Applies program optimization guidance",

"Diagnoses potential causes of low participation",

"Checks awareness, timing, incentive, and friction",

"Recommends optimization tactics",

"Suggests timing referral asks at satisfaction moments",

"Provides experiment ideas"

"files": []

{

"id": 3,

"prompt": "should we do referral or affiliate? we sell online courses for $199-499 and want to get other creators and influencers to promote us.",

"expected_output": "Should trigger on casual phrasing. Should apply the referral vs affiliate distinction clearly. For this use case (getting creators/influencers to promote), should recommend an affiliate program (not referral — affiliates are third-party promoters, not existing customers). Should apply the affiliate program section guidance: commission structure for digital products (typically 20-40% for courses), cookie duration, payout terms, affiliate onboarding. Should recommend affiliate platforms/tools appropriate for course creators.",

"assertions": [

"Triggers on casual phrasing",

"Clearly distinguishes referral from affiliate",

"Recommends affiliate for this use case",

"Provides commission structure guidance for courses",

"Addresses cookie duration and payout terms",

"Recommends appropriate affiliate platforms"

"files": []

{

"id": 4,

"prompt": "What incentive structure works best? We've been offering $10 off for referrers but it's not working. Our product is $29/month.",

"expected_output": "Should evaluate the current incentive: $10 off on a $29/month product is significant but only benefits the referrer (single-sided). Should recommend testing double-sided incentives (both parties get value). Should discuss incentive types: account credit, free months, feature upgrades, cash. Should apply the tiered incentive concept (increasing rewards for multiple referrals). Should provide specific alternative incentive structures to test. Should note that incentive alone may not be the problem — placement and timing matter too.",

"assertions": [

"Evaluates current incentive structure",

"Identifies as single-sided and recommends double-sided",

"Discusses multiple incentive types",

"Applies tiered incentive concept",

"Provides specific alternatives to test",

"Notes incentive may not be the only issue"

"files": []

{

"id": 5,

"prompt": "How do we measure the success of our referral program? What metrics should we track?",

"expected_output": "Should apply the measuring success framework. Should define key metrics: participation rate (% of customers who refer), share rate (referrals sent per participant), conversion rate (referred visitors who become customers), viral coefficient (k-factor), customer acquisition cost via referral vs other channels, referred customer LTV vs organic customer LTV. Should recommend tracking tools and dashboards. Should provide benchmark ranges for each metric.",

"assertions": [

"Applies measuring success framework",

"Defines participation rate, share rate, conversion rate",

"Includes viral coefficient / k-factor",

"Compares referral CAC to other channels",

"Compares referred customer LTV to organic",

"Recommends tracking approach",

"Provides benchmark ranges"

"files": []

{

"id": 6,

"prompt": "Can you write the referral invitation emails? I need the email that goes out when someone shares their referral link.",

"expected_output": "Should recognize this overlaps with email writing. Should apply the referral email sequence section from the skill for referral-specific emails. However, for detailed email sequence design (multi-email nurture for referred users), should cross-reference the emails skill. Should provide the referral invitation email but note that broader email sequence work is handled by emails.",

"assertions": [

"Applies referral email section from the skill",

"Provides referral invitation email guidance",

"Cross-references emails for broader email work",

"Provides specific referral email copy or template"

"files": []

}

]

}

mdskills/referrals/references/affiliate-programs.md

4.3 kB

# Affiliate Program Design

Detailed guidance for building and managing affiliate programs.

## Contents

- Commission Structures

- Cookie Duration

- Affiliate Recruitment

- Affiliate Enablement

- Tools & Platforms (Referral Program Tools, Affiliate Program Tools, Choosing a Tool)

- Fraud Prevention (Common Referral Fraud, Prevention Measures)

## Commission Structures

**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+"

---

## Cookie Duration

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 |

---

## Affiliate Recruitment

### Where to find affiliates:

- Existing customers who create content

- Industry bloggers and reviewers

- YouTubers in your niche

- Newsletter writers

- Complementary tool companies

- Consultants and agencies

### Outreach template:

```

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]

```

---

## Affiliate Enablement

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

---

## Tools & Platforms

### Referral Program Tools

**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 Program Tools

**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](../../../tools/integrations/introw.md))

**Self-hosted:**

- Rewardful — Stripe-integrated affiliates

- Refersion — E-commerce affiliates

### Choosing a Tool

Consider:

- Integration with your payment system

- Fraud detection capabilities

- Payout management

- Reporting and analytics

- Customization options

- Price vs. program scale

---

## Fraud Prevention

### Common Referral Fraud

- Self-referrals (creating fake accounts)

- Referral rings (groups referring each other)

- Coupon sites posting referral codes

- Fake email addresses

- VPN/device spoofing

### Prevention Measures

**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)

mdskills/referrals/references/program-examples.md

3.2 kB

# Referral Program Examples

Real-world examples of successful referral programs.

## Contents

- Dropbox (Classic)

- Uber/Lyft

- Morning Brew

- Notion

- Incentive Types Comparison

- Incentive Sizing Framework

- Viral Coefficient & Metrics (Key Metrics, Calculating Referral Program ROI)

## Dropbox (Classic)

**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

---

## Uber/Lyft

**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

---

## Morning Brew

**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

---

## Notion

**Program:** $10 credit per referral (education)

**Why it worked:**

- Targeted high-sharing audience (students)

- Product naturally spreads in teams

- Credit keeps users engaged

---

## Incentive Types Comparison

|------|------|------|----------|

---

## Incentive Sizing Framework

**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 & Metrics

### Key Metrics

**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+

### Calculating Referral Program ROI

```

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

mdskills/referrals/SKILL.md

7.3 kB

---

description: "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,' 'refer a friend,' 'partner program,' 'referral incentive,' 'how to get referrals,' 'customers referring customers,' or 'affiliate payout.' Use this whenever someone wants existing users or partners to bring in new customers. For launch-specific virality, see launch."

metadata:

version: 2.0.0

---

# Referral & Affiliate Programs

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.

## Before Starting

**Check for product marketing context first:**

Gather this context (ask if not provided):

### 1. Program Type

- Customer referral program, affiliate program, or both?

- B2B or B2C?

- What's the average customer LTV?

- What's your current CAC from other channels?

### 2. Current State

- Existing referral/affiliate program?

- Current referral rate (% who refer)?

- What incentives have you tried?

### 3. Product Fit

- Is your product shareable?

- Does it have network effects?

- Do customers naturally talk about it?

### 4. Resources

- Tools/platforms you use or consider?

- Budget for referral incentives?

---

## Referral vs. Affiliate

### Customer Referral Programs

**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

### Affiliate Programs

**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

---

## Referral Program Design

### The Referral Loop

```

Trigger Moment → Share Action → Convert Referred → Reward → (Loop)

```

### Step 1: Identify Trigger Moments

**High-intent moments:**

- Right after first "aha" moment

- After achieving a milestone

- After exceptional support

- After renewing or upgrading

### Step 2: Design Share Mechanism

**Ranked by effectiveness:**

1. In-product sharing (highest conversion)

2. Personalized link

3. Email invitation

4. Social sharing

5. Referral code (works offline)

### Step 3: Choose Incentive Structure

**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](references/program-examples.md)

---

## Program Optimization

### Improving Referral Rate

**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

### A/B Tests to Run

**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

### Common Problems & Fixes

| 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 |

---

## Measuring Success

### Key Metrics

**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

### Typical Findings

- Referred customers have 16-25% higher LTV

- Referred customers have 18-37% lower churn

- Referred customers refer others at 2-3x rate

---

## Launch Checklist

### Before Launch

- [ ] Define program goals and success metrics

- [ ] Design incentive structure

- [ ] Build or configure referral tool

- [ ] Create referral landing page

- [ ] Set up tracking and attribution

- [ ] Define fraud prevention rules

- [ ] Create terms and conditions

- [ ] Test complete referral flow

### Launch

- [ ] Announce to existing customers

- [ ] Add in-app referral prompts

- [ ] Update website with program details

- [ ] Brief support team

### Post-Launch (First 30 Days)

- [ ] Review conversion funnel

- [ ] Identify top referrers

- [ ] Gather feedback

- [ ] Fix friction points

- [ ] Send reminder emails to non-referrers

---

## Email Sequences

### Referral Program Launch

```

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]

```

### Referral Nurture Sequence

- Day 7: Remind about referral program

- Day 30: "Know anyone who'd benefit?"

- Day 60: Success story + referral prompt

- After milestone: "You achieved [X]—know others who'd want this?"

---

## Affiliate Programs

**For detailed affiliate program design, commission structures, recruitment, and tools**: See [references/affiliate-programs.md](references/affiliate-programs.md)

---

## Task-Specific Questions

1. What type of program (referral, affiliate, or both)?

2. What's your customer LTV and current CAC?

3. Existing program or starting from scratch?

4. What tools/platforms are you considering?

5. What's your budget for rewards/commissions?

6. Is your product naturally shareable?

---

## Tool Integrations

For implementation, see the [tools registry](../../tools/REGISTRY.md). Key tools for referral programs:

| Tool | Best For | Guide |

|------|----------|-------|

| **Rewardful** | Stripe-native affiliate programs | [rewardful.md](../../tools/integrations/rewardful.md) |

| **Tolt** | SaaS affiliate programs | [tolt.md](../../tools/integrations/tolt.md) |

| **Mention Me** | Enterprise referral programs | [mention-me.md](../../tools/integrations/mention-me.md) |

| **Dub.co** | Link tracking and attribution | [dub-co.md](../../tools/integrations/dub-co.md) |

| **Stripe** | Payment processing (for commission tracking) | [stripe.md](../../tools/integrations/stripe.md) |

| **Introw** | Channel partner programs with tiers, deal registration, QBRs | [introw.md](../../tools/integrations/introw.md) |

| **PartnerStack** | Enterprise partner and affiliate programs | [partnerstack.md](../../tools/integrations/partnerstack.md) |

---

## Related Skills

- **launch**: For launching referral program effectively

- **emails**: For referral nurture campaigns

- **marketing-psychology**: For understanding referral motivation

- **analytics**: For tracking referral attribution

jsonskills/revops/evals/evals.json

6.0 kB

{

"skill_name": "revops",

"evals": [

{

"id": 1,

"prompt": "Help me set up our lead lifecycle stages. We're a B2B SaaS company selling to mid-market. We use HubSpot as our CRM and have marketing and sales teams that aren't aligned on lead definitions.",

"expected_output": "Should check for product-marketing.md first. Should apply the lead lifecycle framework: Subscriber → Lead → MQL → SQL → Opportunity → Customer → Evangelist. Should define clear criteria for each stage transition (what makes a Lead become an MQL, etc.). Should address the alignment issue between marketing and sales — define shared definitions and SLAs. Should recommend CRM implementation steps for HubSpot. Should include lead scoring setup. Should provide a handoff process between marketing and sales.",

"assertions": [

"Checks for product-marketing.md",

"Applies lead lifecycle framework with all stages",

"Defines criteria for each stage transition",

"Addresses marketing-sales alignment",

"Provides CRM implementation guidance for HubSpot",

"Includes lead scoring setup",

"Provides handoff process between teams"

"files": []

{

"id": 2,

"prompt": "Set up lead scoring for us. We want to prioritize which leads sales should call first. We sell enterprise software ($50k+ ACV).",

"expected_output": "Should apply the lead scoring framework with three dimensions: explicit scoring (firmographics — company size, industry, title match), implicit scoring (behavioral — page visits, content downloads, email engagement), and negative scoring (unsubscribes, competitor emails, student emails). Should provide specific scoring criteria appropriate for enterprise ($50k+ ACV): weight firmographic signals heavily, include budget and authority signals. Should define score thresholds for MQL and SQL. Should recommend lead routing based on scores.",

"assertions": [

"Applies lead scoring with explicit, implicit, and negative dimensions",

"Provides specific scoring criteria for enterprise",

"Weights firmographic signals appropriately",

"Includes behavioral scoring signals",

"Includes negative scoring signals",

"Defines MQL and SQL score thresholds",

"Recommends lead routing based on scores"

"files": []

{

"id": 3,

"prompt": "our pipeline is a mess. deals sit in stages forever and we don't know what's actually going to close. how do we fix this?",

"expected_output": "Should trigger on casual phrasing. Should apply the pipeline stage management guidance. Should recommend: define clear pipeline stages with entry/exit criteria, set maximum time in each stage, implement stage velocity tracking, add required fields per stage to force data entry. Should address deal hygiene: regular pipeline reviews, stale deal flagging, win/loss analysis. Should recommend CRM automation to enforce stage rules. Should provide a practical cleanup plan for the current mess.",

"assertions": [

"Triggers on casual phrasing",

"Applies pipeline stage management",

"Defines stages with entry/exit criteria",

"Recommends maximum time per stage",

"Addresses deal hygiene and pipeline reviews",

"Recommends CRM automation for enforcement",

"Provides practical cleanup plan"

"files": []

{

"id": 4,

"prompt": "What RevOps metrics should we be tracking? We want to build a dashboard for our leadership team.",

"expected_output": "Should apply the RevOps metrics dashboard framework. Should recommend metrics across the funnel: lead volume by source, MQL-to-SQL conversion rate, SQL-to-Opportunity rate, win rate, average deal size, sales cycle length, pipeline velocity, pipeline coverage ratio, CAC, LTV, LTV:CAC ratio. Should organize metrics by audience (marketing team, sales team, leadership). Should recommend dashboard structure and cadence for reviews.",

"assertions": [

"Applies RevOps metrics dashboard",

"Covers full-funnel metrics",

"Includes conversion rates between stages",

"Includes pipeline velocity and coverage",

"Includes CAC, LTV, LTV:CAC",

"Organizes by audience",

"Recommends dashboard structure and review cadence"

"files": []

{

"id": 5,

"prompt": "Our CRM data is a disaster. Duplicate records, missing fields, inconsistent naming. How do we clean it up and keep it clean?",

"expected_output": "Should apply the data hygiene guidance. Should recommend: duplicate detection and merging strategy, required field enforcement, standardized naming conventions (picklists over free text), data validation rules, regular audit cadence. Should address both cleanup (one-time fix) and prevention (ongoing processes). Should recommend CRM automation for data hygiene. Should provide a prioritized cleanup plan (start with highest-impact data quality issues).",

"assertions": [

"Applies data hygiene guidance",

"Recommends duplicate detection and merging",

"Recommends required field enforcement",

"Addresses standardized naming conventions",

"Covers both cleanup and prevention",

"Recommends CRM automation for hygiene",

"Provides prioritized cleanup plan"

"files": []

{

"id": 6,

"prompt": "Can you help me write cold outreach emails to prospects in our pipeline?",

"expected_output": "Should recognize this is a cold email / outbound writing task, not RevOps. Should defer to or cross-reference the cold-email skill for writing outbound prospecting emails. RevOps covers the systems, processes, and data infrastructure — not the actual email content.",

"assertions": [

"Recognizes this as cold email writing, not RevOps",

"References or defers to cold-email skill",

"Explains RevOps covers systems and processes, not email content"

"files": []

}

]

}

mdskills/revops/references/automation-playbooks.md

11 kB

# Automation Playbooks

Platform-specific workflow recipes for HubSpot, Salesforce, scheduling tools, and cross-tool automation.

## HubSpot Workflow Recipes

### 1. MQL Alert and Assignment

**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

---

### 2. MQL SLA Escalation

**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)

---

### 3. Lead Scoring Update and MQL Promotion

**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

---

### 4. Meeting Booked Notification

**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

---

### 5. Closed-Won Handoff to CS

**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

---

### 6. Stale Deal Alert

**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)

---

### 7. Recycled Lead Nurture Re-Entry

**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

---

### 8. Lead Activity Digest

**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)

---

## Salesforce Flow Equivalents

### 1. MQL Alert and Assignment (Salesforce Flow)

**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

### 2. SLA Escalation (Salesforce Flow)

**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

### 3. Pipeline Stage Automation (Salesforce Flow)

**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

### 4. Stale Deal Detection (Salesforce Flow)

**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 / SavvyCal Integration Patterns

### Round-Robin Meeting Scheduling

**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)

### SavvyCal Setup

**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

### Meeting Routing by Criteria

```

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

```

### No-Show Workflow

**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

---

## Zapier Cross-Tool Patterns

### 1. New Lead → CRM + Slack + Task

**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)

### 2. Meeting Booked → CRM + Prep Email

**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

### 3. Deal Closed → Onboarding Stack

**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

### 4. Lead Scoring → Cross-Tool Sync

**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)

### 5. SLA Breach → Multi-Channel Alert

**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)

### 6. Weekly Pipeline Digest

**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

mdskills/revops/references/lifecycle-definitions.md

6.9 kB

# Lifecycle Stage Definitions

Complete templates for lead lifecycle stages, MQL criteria by business type, SLAs, and rejection/recycling workflows.

## Stage Templates

### Subscriber

**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

---

### Lead

**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

---

### MQL (Marketing Qualified Lead)

**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

---

### SQL (Sales Qualified Lead)

**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

---

### Opportunity

**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

---

### Customer

**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

---

### Evangelist

**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)

---

## MQL Criteria Templates by Business Type

### PLG (Product-Led Growth)

**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

---

### Sales-Led (Enterprise)

**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

---

### Mid-Market (Balanced)

**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

---

## SLA Templates

### MQL-to-SQL SLA

| 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 |

### SQL-to-Opportunity SLA

| 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 |

### Opportunity-to-Close SLA

| 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 |

---

## Lead Rejection and Recycling

### Rejection Reason Codes

| 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 |

### Recycling Workflow

1. Sales rejects MQL with reason code

2. CRM updates lifecycle stage to "Recycled"

3. Lead enters recycling nurture sequence (different from original nurture)

4. Engagement score resets to baseline (keep fit score)

5. If lead re-engages and crosses MQL threshold, re-route to sales with "Recycled MQL" flag

6. Track recycled MQL conversion rate separately

### Recycling Nurture Sequence

- **Frequency:** Bi-weekly or monthly (lower frequency than initial nurture)

- **Content:** Industry insights, case studies, product updates

- **Duration:** 6 months, then archive if no engagement

- **Re-MQL trigger:** High-intent action (demo request, pricing page revisit)

mdskills/revops/references/routing-rules.md

6.6 kB

# Lead Routing Rules

Decision trees, platform-specific configurations, territory routing, ABM routing, and speed-to-lead benchmarks.

## Routing Decision Tree

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.**

---

## Round-Robin Configuration

### Basic Round-Robin Rules

1. Distribute leads evenly across eligible reps

2. Skip reps who are on PTO, at capacity, or have a full pipeline

3. Weight by quota attainment (reps below quota get slight priority)

4. Reset distribution count weekly or monthly

5. Log every assignment for auditing

### HubSpot Round-Robin Setup

**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

### Salesforce Round-Robin Setup

**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 Routing

### By Geography

| 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 |

### By Company Size

| 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 |

### By Industry

| 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) |

### Hybrid Territory Model

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

```

---

## Named Account / ABM Routing

### Setup

1. **Define target account list** (typically 50-500 accounts)

2. **Assign account owners** in CRM (1 rep per account)

3. **Match logic:** Any lead from a target account domain routes to account owner

4. **Matching rules:**

- Email domain match (primary)

- Company name fuzzy match (secondary, requires manual review)

- IP-to-company resolution (tertiary, for anonymous visitors)

### ABM Routing Rules

|------|-------------|---------|--------------|

### Multi-Contact Handling

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

---

## Speed-to-Lead Data

### Response Time Impact on Conversion

| 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

### Implementing Speed-to-Lead

1. **Instant notification** — Push notification + email to rep on MQL creation

2. **Auto-task with timer** — Create task with 5-minute SLA countdown

3. **Escalation chain:**

- 5 min: Original rep alerted

- 15 min: Backup rep alerted

- 30 min: Manager alerted

- 1 hour: Lead reassigned to next available rep

4. **Measure and report** — Track actual response times weekly; recognize fast responders

### Speed-to-Lead Automation

**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

### Measuring Speed-to-Lead

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)

mdskills/revops/references/scoring-models.md

7.3 kB

# Lead Scoring Models

Detailed scoring templates, example models by business type, and calibration guidance.

## Explicit Scoring Template (Fit)

### Company Attributes

| 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 |

### Contact Attributes

| 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 |

### Technology Attributes

| 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 |

---

## Implicit Scoring Template (Engagement)

### High-Intent Signals

| 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 |

### Medium-Intent Signals

| 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 |

### Low-Intent Signals

| 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 |

### Product Usage Signals (PLG)

| 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 |

---

## Negative Scoring Signals

| 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 |

---

## Example Scoring Models

### Model 1: PLG SaaS (ACV $500-$5K)

**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)

---

### Model 2: Enterprise Sales-Led (ACV $50K+)

**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)

---

### Model 3: Mid-Market Hybrid (ACV $5K-$25K)

**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**

---

## Threshold Calibration

### Setting the Initial Threshold

1. **Pull closed-won data** from the last 6-12 months

2. **Retroactively score** each deal using your new model

3. **Find the natural breakpoint** — what score separated wins from losses?

4. **Set threshold** just below where 80% of closed-won deals would have scored

5. **Validate** against closed-lost — if many closed-lost score above threshold, tighten criteria

### Calibration Cadence

| 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 |

### Calibration Steps

1. **Pull MQL-to-closed data** for the calibration period

2. **Compare scored MQLs vs. actual outcomes:**

- High score + closed-won = correctly scored

- High score + closed-lost = possible false positive (tighten)

- Low score + closed-won = possible false negative (loosen)

3. **Adjust weights** based on which attributes actually correlated with wins

4. **Adjust threshold** if MQL volume is too high (raise) or too low (lower)

5. **Document changes** and communicate to sales team

### Warning Signs Your Model Needs Recalibration

- MQL-to-SQL acceptance rate drops below 30%

- Sales consistently rejects MQLs as "not ready"

- High-scoring leads don't convert; low-scoring leads do

- MQL volume spikes without corresponding revenue

- New product/market changes since last calibration

mdskills/revops/SKILL.md

15 kB

---

description: "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,' 'SQL,' 'pipeline stages,' 'deal desk,' 'CRM automation,' 'marketing-to-sales handoff,' 'data hygiene,' 'leads aren't getting to sales,' 'pipeline management,' 'lead qualification,' or 'when should marketing hand off to sales.' Use this for anything involving the systems and processes that connect marketing to revenue. For cold outreach emails, see cold-email. For email drip campaigns, see emails. For pricing decisions, see pricing."

metadata:

version: 2.0.0

---

# RevOps

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.

## Before Starting

**Check for product marketing context first:**

Gather this context (ask if not provided):

1. **GTM motion** — Product-led (PLG), sales-led, or hybrid?

2. **ACV range** — What's the average contract value?

3. **Sales cycle length** — Days from first touch to closed-won?

4. **Current stack** — CRM, marketing automation, scheduling, enrichment tools?

5. **Current state** — How are leads managed today? What's working and what's not?

6. **Goals** — Increase conversion? Reduce speed-to-lead? Fix handoff leaks? Build from scratch?

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.

---

## Core Principles

### Single Source of Truth

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.

### Define Before Automate

Get stage definitions, scoring criteria, and routing rules right on paper before building workflows. Automating a broken process just creates broken results faster.

### Measure Every Handoff

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.

### Revenue Team Alignment

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.

---

## Lead Lifecycle Framework

### Stage Definitions

|-------|---------------|---------------|-------|

### MQL Definition

An MQL requires both **fit** and **engagement**:

- **Fit score** — Does this person match your ICP? (company size, industry, role, tech stack)

- **Engagement score** — Have they shown buying intent? (pricing page, demo request, multiple visits)

Neither alone is sufficient. A perfect-fit company that never engages isn't an MQL. A student downloading every ebook isn't an MQL.

### MQL-to-SQL Handoff SLA

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](references/lifecycle-definitions.md)

---

## Lead Scoring

### Scoring Dimensions

**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)

### Building a Scoring Model

1. Define your ICP attributes and weight them

2. Identify high-intent behavioral signals from closed-won data

3. Set point values for each attribute and behavior

4. Set MQL threshold (typically 50-80 points on a 100-point scale)

5. Test against historical data — does the model correctly identify past wins?

6. Launch, measure, and recalibrate quarterly

### Common Scoring Mistakes

- Weighting content downloads too heavily (research ≠ buying intent)

- Not including negative scoring (lets bad leads through)

- Setting and forgetting (buyer behavior changes; recalibrate quarterly)

- Scoring all page visits equally (pricing page ≠ blog post)

**For detailed scoring templates and example models**: See [references/scoring-models.md](references/scoring-models.md)

---

## Lead Routing

### Routing Methods

| 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 |

### Routing Rules Essentials

- Route to the **most specific match** first, then fall back to general

- Include a **fallback owner** — unassigned leads go cold fast and waste pipeline

- Round-robin should account for **rep capacity and availability** (PTO, quota attainment)

- Log every routing decision for audit and optimization

### Speed-to-Lead

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](references/routing-rules.md)

---

## Pipeline Stage Management

### Pipeline Stages

| 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 |

### Stage Hygiene

- **Required fields per stage** — Don't let reps advance a deal without filling in required data

- **Stale deal alerts** — Flag deals that sit in a stage beyond the average time (e.g., 2x average days)

- **Stage skip detection** — Alert when deals jump stages (Qualified → Proposal skipping Discovery)

- **Close date discipline** — Push dates must include a reason; no silent pushes

### Pipeline Metrics

| 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 |

---

## CRM Automation Workflows

### Essential Automations

- **Lifecycle stage updates** — Auto-advance stages when criteria are met

- **Task creation on handoff** — Create follow-up task when MQL assigned to rep

- **SLA alerts** — Notify manager if rep misses response time SLA

- **Deal stage triggers** — Auto-send proposals, update forecasts, notify CS on close

### Marketing-to-Sales Automations

- **MQL alert** — Instant notification to assigned rep with lead context

- **Meeting booked** — Notify AE when prospect books via scheduling tool

- **Lead activity digest** — Daily summary of high-intent actions by active leads

- **Re-engagement trigger** — Alert sales when a dormant lead returns to site

### Calendar Scheduling Integration

- **Round-robin scheduling** — Distribute meetings evenly across team

- **Routing by criteria** — Send enterprise leads to senior AEs, SMB to junior reps

- **Pre-meeting enrichment** — Auto-populate CRM record before the call

- **No-show workflows** — Auto-follow-up if prospect misses meeting

**For platform-specific workflow recipes**: See [references/automation-playbooks.md](references/automation-playbooks.md)

---

## Deal Desk Processes

### When You Need a Deal Desk

- ACV above **$25K** (or your threshold for non-standard deals)

- Non-standard payment terms (net-90, quarterly billing)

- Multi-year contracts with custom pricing

- Volume discounts beyond published tiers

- Custom legal terms or SLAs

### Approval Workflow Tiers

| 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 |

### Non-Standard Terms Handling

Document every exception. Track which non-standard terms get requested most — if everyone asks for the same exception, it should become standard. Review quarterly.

---

## Data Hygiene & Enrichment

### Dedup Strategy

- **Matching rules** — Email domain + company name + phone as primary match keys

- **Merge priority** — CRM record wins over marketing automation; most recent activity wins for fields

- **Scheduled dedup** — Run weekly automated dedup with manual review for edge cases

### Required Fields Enforcement

- Enforce required fields at each lifecycle stage

- Block stage advancement if fields are empty

- Use progressive profiling — don't require everything upfront

### Enrichment Tools

| Tool | Strength |

|------|----------|

| Clearbit | Real-time enrichment, good for tech companies |

| Apollo | Contact data + sequences, strong for prospecting |

| ZoomInfo | Enterprise-grade, largest B2B database |

### Quarterly Audit Checklist

- Review and merge duplicates

- Validate email deliverability on stale contacts

- Archive contacts with no activity in 12+ months

- Audit lifecycle stage distribution (look for bottlenecks)

- Verify enrichment data accuracy on a sample set

---

## RevOps Metrics Dashboard

### Key Metrics

| 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) |

### Dashboard Structure

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

---

## Output Format

When delivering RevOps recommendations, provide:

1. **Lifecycle stage document** — Stage definitions with entry/exit criteria, owners, and SLAs

2. **Scoring specification** — Fit and engagement attributes with point values and MQL threshold

3. **Routing rules document** — Decision tree with assignment logic and fallbacks

4. **Pipeline configuration** — Stage definitions, required fields, and automation triggers

5. **Metrics dashboard spec** — Key metrics, data sources, and target benchmarks

Format each as a standalone document the user can implement directly. Include platform-specific guidance when the CRM is known.

---

## Task-Specific Questions

1. What CRM platform are you using (or planning to use)?

2. How many leads per month do you generate?

3. What's your current MQL definition?

4. Where do leads get stuck in your funnel?

5. Do you have SLAs between marketing and sales today?

---

## Tool Integrations

For implementation, see the [tools registry](../../tools/REGISTRY.md). Key RevOps tools:

| Tool | What It Does | Guide |

|------|-------------|-------|

| **HubSpot** | CRM, marketing automation, lead scoring, workflows | [hubspot.md](../../tools/integrations/hubspot.md) |

| **Salesforce** | Enterprise CRM, pipeline management, reporting | [salesforce.md](../../tools/integrations/salesforce.md) |

| **Calendly** | Meeting scheduling, round-robin routing | [calendly.md](../../tools/integrations/calendly.md) |

| **SavvyCal** | Scheduling with priority-based availability | [savvycal.md](../../tools/integrations/savvycal.md) |

| **Clearbit** | Real-time lead enrichment and scoring | [clearbit.md](../../tools/integrations/clearbit.md) |

| **Apollo** | Contact data, enrichment, and outbound sequences | [apollo.md](../../tools/integrations/apollo.md) |

| **ActiveCampaign** | Marketing automation for SMBs, lead scoring | [activecampaign.md](../../tools/integrations/activecampaign.md) |

| **Zapier** | Cross-tool automation and workflow glue | [zapier.md](../../tools/integrations/zapier.md) |

| **Introw** | Partner-sourced pipeline, commissions, deal registration, QBRs | [introw.md](../../tools/integrations/introw.md) |

| **Crossbeam** | Partner account overlaps and co-sell identification | [crossbeam.md](../../tools/integrations/crossbeam.md) |

---

## Related Skills

- **cold-email**: For outbound prospecting emails

- **emails**: For lifecycle and nurture email flows

- **pricing**: For pricing decisions and packaging

- **analytics**: For tracking pipeline metrics and attribution

- **launch**: For go-to-market launch planning

- **sales-enablement**: For sales collateral, decks, and objection handling

jsonskills/sales-enablement/evals/evals.json

6.3 kB

{

"skill_name": "sales-enablement",

"evals": [

{

"id": 1,

"prompt": "Help me create a sales deck for our B2B SaaS product. We sell an employee engagement platform to HR directors at companies with 500-5000 employees. Our main differentiator is real-time pulse surveys with AI-powered insights.",

"expected_output": "Should check for product-marketing.md first. Should apply the 10-12 slide sales deck framework: Title, Problem/Stakes, Current Solutions Failing, Vision, Product/Solution, How It Works, Proof (case studies/metrics), Pricing, Why Now, and Next Steps. Should tailor the deck to the HR director audience and employee engagement space. Should incorporate the differentiator (real-time pulse surveys + AI insights). Should provide slide-by-slide content recommendations with speaker notes. Should recommend visual direction.",

"assertions": [

"Checks for product-marketing.md",

"Applies 10-12 slide framework",

"Includes Problem, Solution, Proof, Pricing, Next Steps slides",

"Tailors to HR director audience",

"Incorporates stated differentiator",

"Provides slide-by-slide content",

"Includes speaker notes or talking points"

"files": []

{

"id": 2,

"prompt": "Our sales team keeps getting the same objections. The top ones are: 'we already use SurveyMonkey,' 'we don't have budget right now,' and 'our team is too small to need this.' Help me create an objection handling doc.",

"expected_output": "Should apply the objection handling framework with the response structure for each objection. Should categorize the objections (competitor/status quo, budget, need/timing). For each objection, should provide: acknowledge, reframe, evidence/proof, bridge to value, and follow-up question. Should provide 2-3 response variations per objection for different contexts. Should organize as a document sales reps can reference quickly during calls.",

"assertions": [

"Applies objection handling framework",

"Categorizes the three objections",

"Provides structured response for each (acknowledge, reframe, evidence, bridge)",

"Provides 2-3 response variations per objection",

"Organizes for quick reference during calls",

"Categorizes objections using the skill's framework (competitor, budget, need/timing)"

"files": []

{

"id": 3,

"prompt": "i need a one-pager we can leave behind after sales meetings. something that summarizes our product and key benefits.",

"expected_output": "Should trigger on casual phrasing. Should apply the one-pager/leave-behind framework. Should include: headline with core value proposition, key benefits (3-5), social proof (customer logos, key metric), how it works (simplified), pricing summary or 'starting at' range, and clear next step CTA. Should recommend design principles for a one-pager: scannable, visual hierarchy, not text-heavy. Should note this should fit on one page (front, or front and back).",

"assertions": [

"Triggers on casual phrasing",

"Applies one-pager/leave-behind framework",

"Includes headline, benefits, social proof, how it works, CTA",

"Keeps to one page format",

"Recommends scannable design",

"Provides specific content for each section"

"files": []

{

"id": 4,

"prompt": "Create a demo script for our analytics dashboard product. Typical demo is 30 minutes with a VP of Marketing.",

"expected_output": "Should apply the demo script/talk track framework with the 5-part structure. Should include: opening (rapport, agenda setting, discovery questions), problem validation (confirm their pain), solution walkthrough (show product addressing their pain), proof points (metrics, case studies during demo), and close (next steps, timeline). Should time-box each section for 30 minutes. Should include key questions to ask during discovery. Should note when to customize based on prospect's answers.",

"assertions": [

"Applies 5-part demo script structure",

"Includes opening with discovery questions",

"Includes problem validation",

"Includes solution walkthrough",

"Includes proof points",

"Includes close with next steps",

"Time-boxes for 30 minutes",

"Notes customization based on prospect responses"

"files": []

{

"id": 5,

"prompt": "Help me build an ROI calculator we can use during sales calls. We need to show prospects how much money they'll save by switching to our product.",

"expected_output": "Should apply the ROI calculator framework. Should define inputs (what data to collect from the prospect: team size, current costs, time spent on manual processes), calculation methodology (how to compute savings), and output format (visual showing ROI timeline, payback period, annual savings). Should recommend keeping calculations transparent and conservative. Should suggest validating assumptions during the sales call. Should provide the calculator structure and formula logic.",

"assertions": [

"Applies ROI calculator framework",

"Defines required inputs",

"Provides calculation methodology",

"Recommends conservative assumptions",

"Includes ROI timeline and payback period",

"Suggests validating assumptions during calls",

"Provides calculator structure"

"files": []

{

"id": 6,

"prompt": "We need a public comparison page showing how we stack up against Zendesk and Intercom.",

"expected_output": "Should recognize this is a public-facing competitor comparison page, not internal sales collateral. Should defer to or cross-reference the competitors skill, which handles public comparison and alternatives pages. Sales-enablement covers internal materials (battle cards, objection handling) while competitors handles SEO-focused public comparison content.",

"assertions": [

"Recognizes this as a public comparison page",

"References or defers to competitors skill",

"Explains the distinction between internal and public collateral",

"Does not attempt public SEO comparison page using sales enablement patterns"

"files": []

}

]

}

mdskills/sales-enablement/references/deck-frameworks.md

7.5 kB

# Sales Deck Frameworks

Detailed slide-by-slide guidance for building sales decks that tell a story and close deals.

## The Storytelling Arc

Every great deck follows a narrative structure: **Situation → Complication → Resolution.**

- **Situation** (Slides 1-3): The world your buyer lives in. Establish shared understanding.

- **Complication** (Slides 2-3): Why the status quo is no longer sustainable. Create urgency.

- **Resolution** (Slides 4-11): Your approach, proof, and path forward.

The goal is not to present features. The goal is to make the buyer feel understood, then show them a better way.

---

## Slide-by-Slide Template

### Slide 1: Current World Problem

**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'?"

---

### Slide 2: Cost of the Problem

**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?"

---

### Slide 3: The Shift Happening

**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?"

---

### Slide 4: Your Approach

**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?"

---

### Slide 5: Product Walkthrough

**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."

---

### Slide 6: Proof Points

**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?"

---

### Slide 7: Case Study

**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."

---

### Slide 8: Implementation / Timeline

**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?"

---

### Slide 9: ROI / Value

**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?"

---

### Slide 10: Pricing Overview

**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?"

---

### Slide 11: Next Steps / CTA

**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?"

---

## Persona Customization Guide

### Technical Buyer Deck

**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.

### Economic Buyer Deck

**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.

### Champion Deck

**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.

---

## Anti-Patterns

### The Feature Dump

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.

### The Wall of Text

Slides with 200+ words. Nobody reads them during a presentation. If the slide requires reading, it belongs in a leave-behind.

### The Missing Story Arc

Slides exist in isolation — no narrative flow from problem to solution to proof. The deck feels like a brochure, not a conversation.

### The Generic Screenshot

Product screenshots without callouts, annotations, or context. The prospect can't tell what they're looking at or why it matters.

### The Premature Demo

Jumping to product features before establishing the problem. The buyer has no frame of reference for why your features matter.

### The Kitchen Sink

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.

mdskills/sales-enablement/references/demo-scripts.md

11 kB

# Demo Script Templates

Scene-by-scene templates for different call types, with timing, talk tracks, and interaction guidance.

## Discovery Call Script

**Duration:** 30 minutes

**Goal:** Qualify the opportunity, understand pain, map the buying process.

### Scene 1: Opening (3 min)

**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

---

### Scene 2: Situation Questions (7 min)

**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

---

### Scene 3: Pain Identification (10 min)

**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?"

---

### Scene 4: Impact & Priority (5 min)

**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

---

### Scene 5: Buying Process (3 min)

**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

---

### Scene 6: Close (2 min)

**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

---

## First Demo Script

**Duration:** 30-45 minutes

**Goal:** Show how your product solves their specific pain. Advance to evaluation/pilot.

### Scene 1: Opening & Recap (5 min)

**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

---

### Scene 2: Workflow 1 — Primary Pain Point (10 min)

**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

---

### Scene 3: Workflow 2 — Secondary Pain Point (8 min)

**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?"

---

### Scene 4: Workflow 3 — Differentiator (7 min)

**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?"

---

### Scene 5: Proof Point (3 min)

**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

---

### Scene 6: Close (5 min)

**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

---

## Technical Deep-Dive Script

**Duration:** 45-60 minutes

**Goal:** Satisfy technical evaluation criteria. Address architecture, security, and integration concerns.

### Scene 1: Opening (3 min)

**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.

---

### Scene 2: Architecture Overview (10 min)

**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?"

---

### Scene 3: Security & Compliance (10 min)

**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."

---

### Scene 4: Integrations & API (15 min)

**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."

---

### Scene 5: Implementation & Migration (5 min)

**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."

---

### Scene 6: Q&A and Close (10 min)

**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

---

## Executive Overview Script

**Duration:** 20-30 minutes

**Goal:** Get executive buy-in on the business case. Advance to budget approval or decision.

### Scene 1: Opening (2 min)

**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

---

### Scene 2: The Problem & Cost (5 min)

**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

---

### Scene 3: The Solution & Differentiation (5 min)

**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

---

### Scene 4: ROI & Business Case (5 min)

**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

---

### Scene 5: Q&A and Decision (5-10 min)

**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

---

## Interaction Point Guidance

### When to Ask Questions During Demos

- **After showing each workflow** — "How does this compare to your current process?"

- **When you see a reaction** — "I noticed you reacted to that — what are you thinking?"

- **Before moving to the next section** — "Any questions on this before we move on?"

- **When showing a differentiator** — "How would your team use this?"

- **At the midpoint** — "Are we covering the right things, or should we adjust?"

### Questions NOT to Ask During Demos

- "Does that make sense?" (patronizing)

- "Are you still with me?" (implies they're lost)

- "Isn't that cool?" (salesy)

- Rhetorical questions that don't invite real dialogue

### How to Handle "Can You Show Me X?"

When a prospect asks to see something during the demo:

1. **If it's quick** — show it now, then return to your flow

2. **If it's a tangent** — "Great question. Let me note that and show you after the main flow so we stay on track."

3. **If it's not possible** — "We don't do that today. Here's how customers handle it: [alternative]."

Never say "I'll get back to you" without writing it down and following up within 24 hours.

mdskills/sales-enablement/references/objection-library.md

13 kB

# Objection Library

Common B2B SaaS objections with response frameworks. Organized by category for quick reference.

## Quick-Reference Table

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 |

---

## Detailed Objection Responses

### Price Objections

#### "It's too expensive"

**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?"

---

#### "We don't have budget for this"

**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?"

---

#### "Competitor X is cheaper"

**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]?"

---

### Timing Objections

#### "Not the right time"

**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?"

---

#### "Maybe next quarter"

**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?"

---

### Competition Objections

#### "We already use X"

**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?"

---

#### "What makes you different?"

**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?"

---

### Authority Objections

#### "I need to check with my boss"

**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?"

---

#### "A committee decides this"

**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?"

---

### Status Quo Objections

#### "What we have works fine"

**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?"

---

### Technical Objections

#### "Does it integrate with X?"

**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?"

---

#### "We have security concerns"

**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?"

mdskills/sales-enablement/references/one-pager-templates.md

5.7 kB

# One-Pager Templates

Templates for different one-pager use cases, with layout guidance and copy prompts.

## Product Overview One-Pager

The default one-pager. Introduces your product to someone who knows nothing about you.

### Structure

```

[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]

```

### Copy Prompts

- Headline: "What do you do, in one sentence, that makes someone say 'tell me more'?"

- Problem: "What is your buyer struggling with before they find you?"

- Differentiators: "If you could only tell them 3 things, what would make them choose you?"

---

## Use-Case Specific One-Pager

Tailored to a specific workflow, vertical, or problem. More targeted than the product overview.

### Structure

```

[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]

```

### When to Use

- Different buyer personas need different one-pagers

- Industry-specific versions (healthcare, fintech, e-commerce)

- Use-case versions (reporting, onboarding, security)

---

## Post-Meeting Leave-Behind

Designed to reinforce a conversation that already happened. Summarizes what you discussed and proposes next steps.

### Structure

```

[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]

```

### Tips

- Send within 24 hours of the meeting

- Reference specific things they said (shows you listened)

- Keep proposed next steps concrete and time-bound

- This is the asset your champion forwards to their boss

---

## Champion Enablement One-Pager

Designed specifically for your internal champion to share with their team and leadership. Written to make them look smart.

### Structure

```

[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

• [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].

```

### Why This Works

- Written in the champion's voice, not yours

- Answers the questions their boss will ask

- Includes peer proof from companies they respect

- Clear ask and timeline to drive internal momentum

---

## Layout Guidance

### Visual Hierarchy

1. **Headline** — Largest text, top of page, immediately communicates value

2. **Section headers** — Bold, clear, act as scannable anchors

3. **Body text** — Short sentences, bullet points preferred over paragraphs

4. **Proof elements** — Metrics and quotes should visually stand out (larger font, color, or callout box)

5. **CTA** — Prominent placement, bottom of page or bottom-right

### Whitespace

- Margins: at least 0.75" on all sides

- Space between sections: enough to visually separate (don't cram)

- If it feels crowded, cut content. Never shrink font below 9pt.

### Font Sizing

| Element | Suggested Size |

|---------|---------------|

| Headline | 18-24pt |

| Section headers | 12-14pt bold |

| Body text | 10-11pt |

| Fine print / footer | 8-9pt |

### Color

- Use brand colors for headers and accents

- Keep body text dark (black or near-black) on white

- Limit accent colors to 1-2 for visual consistency

- Use color to draw attention to metrics and CTAs

### File Format

- **PDF** for email attachments and leave-behinds

- **Google Slides / PowerPoint** for editable versions reps can customize

- Always include both — reps will customize, prospects want clean PDFs

mdskills/sales-enablement/SKILL.md

14 kB

---

description: "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 handling,' 'deal-specific ROI analysis,' 'demo script,' 'talk track,' 'sales playbook,' 'proposal template,' 'buyer persona card,' 'help my sales team,' 'sales materials,' or 'what should I give my sales reps.' Use this for any document or asset that helps a sales team close deals. For competitor comparison pages and battle cards, see competitors. For marketing website copy, see copywriting. For cold outreach emails, see cold-email."

metadata:

version: 2.0.0

---

# Sales Enablement

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.

## Before Starting

**Check for product marketing context first:**

Gather this context (ask if not provided):

1. **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?

2. **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

3. **Collateral Needs**

- What specific assets do you need?

- What stage of the funnel are they for?

- Who will use them? (AE, SDR, champion, prospect)

4. **Current State**

- What materials exist today?

- What's working and what's not?

- What do reps ask for most?

---

## Core Principles

### Sales Uses What Sales Trusts

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.

### Situation-Specific, Not Generic

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.

### Scannable Over Comprehensive

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.

### Tie Back to Business Outcomes

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%."

---

## Sales Deck / Pitch Deck

### 10-12 Slide Framework

1. **Current World Problem** — The pain your buyer lives with today

2. **Cost of the Problem** — What inaction costs (time, money, risk)

3. **The Shift Happening** — Market or technology change creating urgency

4. **Your Approach** — How you solve it differently

5. **Product Walkthrough** — 3-4 key workflows, not a feature tour

6. **Proof Points** — Metrics, logos, analyst recognition

7. **Case Study** — One customer story told well

8. **Implementation / Timeline** — How they get from here to live

9. **ROI / Value** — Expected return and payback period

10. **Pricing Overview** — Transparent, tiered if applicable

11. **Next Steps / CTA** — Clear action with timeline

### Deck Principles

- **Story arc, not feature tour.** Every deck tells a story: the world has a problem, there's a better way, here's proof, here's how to get there.

- **One idea per slide.** If you need two points, use two slides.

- **Design for presenting, not reading.** Slides support the conversation — they don't replace it. Minimal text, strong visuals.

### Customization by Buyer Type

| 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](references/deck-frameworks.md)

---

## One-Pagers / Leave-Behinds

### When to Use

- **Post-meeting recap** — Reinforce what you discussed, keep momentum

- **Champion internal selling** — Arm your champion to sell for you

- **Trade show handout** — Quick intro that drives follow-up

### Structure

1. **Problem statement** — The pain in one sentence

2. **Your solution** — What you do and how

3. **3 differentiators** — Why you vs. alternatives

4. **Proof point** — One strong metric or customer quote

5. **CTA** — Clear next step with contact info

### Design Principles

- One page, literally. Front only, or front and back maximum.

- Scannable in 30 seconds. Bold headers, short bullets, whitespace.

- Include your logo, website, and a specific contact (not info@).

- Match your brand but keep it clean — this is a sales tool, not a brand piece.

**For templates by use case**: See [references/one-pager-templates.md](references/one-pager-templates.md)

---

## Objection Handling Docs

### Objection Categories

| 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?" |

### Response Framework

For each objection, document:

1. **Objection statement** — Exactly how reps hear it

2. **Why they say it** — The real concern behind the words

3. **Response approach** — How to acknowledge and redirect

4. **Proof point** — Specific evidence that addresses the concern

5. **Follow-up question** — Keep the conversation moving forward

### Two Formats

- **Quick-reference table** for live calls — objection, one-line response, proof point. Fits on one screen.

- **Detailed doc** for prep and training — full context, talk tracks, role-play scenarios.

**For the full objection library**: See [references/objection-library.md](references/objection-library.md)

---

## ROI Calculators & Value Props

### Calculator Design

**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

### Value Prop by Persona

| 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 |

### Implementation Options

- **Spreadsheet** — Fastest to build, easy to customize per deal. Works for inside sales.

- **Web tool** — More polished, captures leads, scales better. Worth building if deal volume is high.

- **Slide-based** — ROI story embedded in the deck. Good for executive presentations.

---

## Demo Scripts & Talk Tracks

### Script Structure

1. **Opening** (2 min) — Context setting, agenda, confirm goals for the call

2. **Discovery recap** (3 min) — Summarize what you learned, confirm priorities

3. **Solution walkthrough** (15-20 min) — 3-4 key workflows mapped to their pain

4. **Interaction points** — Questions to ask during the demo, not just at the end

5. **Close** (5 min) — Summarize value, propose next steps with timeline

### Talk Track Types

| 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 |

### Key Principles

- **Demo after discovery, not before.** If you don't know their pain, you're guessing which features matter.

- **Customize to their use case.** Use their terminology, their data (if possible), their workflow.

- **Leave time for questions.** A demo where the prospect doesn't talk is a demo that doesn't close.

**For full script templates**: See [references/demo-scripts.md](references/demo-scripts.md)

---

## Case Study Briefs (Sales Format)

### How Sales Case Studies Differ

Marketing case studies tell a story. Sales case studies arm reps with fast-access proof. Keep them short, outcome-focused, and tagged for retrieval.

### Structure

1. **Customer profile** — Industry, company size, buyer role

2. **Challenge** — What they were struggling with (2-3 sentences)

3. **Solution** — What they implemented (1-2 sentences)

4. **Results** — 3 specific metrics (before/after)

5. **Pull quote** — One sentence from the customer

6. **Tags** — Industry, use case, company size, persona

### Organization

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"

---

## Proposal Templates

### Structure

1. **Executive summary** — Their challenge, your solution, expected outcome (1 page max)

2. **Proposed solution** — What you'll deliver, mapped to their requirements

3. **Implementation plan** — Timeline, milestones, responsibilities

4. **Investment** — Pricing, payment terms, what's included

5. **Next steps** — How to move forward, decision timeline

### Customization Guidance

- Mirror their language from discovery calls

- Reference specific pain points they mentioned

- Include only relevant case studies (same industry or use case)

- Name the stakeholders you've spoken with

### Common Mistakes

- **Too long** — If it's over 10 pages, it won't get read. Aim for 5-7.

- **Too generic** — Templated proposals signal low effort. Customize the exec summary at minimum.

- **Burying the price** — Don't make them hunt for it. Be transparent and confident.

---

## Sales Playbooks

### What Goes in a Playbook

- **Buyer profile** — Who you're selling to, their goals and pains

- **Qualification criteria** — BANT, MEDDIC, or your framework

- **Discovery questions** — Organized by topic, not a script

- **Objection handling** — Top 10 objections with responses

- **Competitive positioning** — How you win against each competitor

- **Demo flow** — Recommended sequence for each persona

- **Email templates** — Follow-up, proposal, check-in, breakup

### When to Build

- **New product launch** — Reps need a single source of truth

- **New market segment** — Different buyers need different approaches

- **New hire ramp** — Playbooks cut ramp time significantly

### Keeping It Living

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.

---

## Buyer Persona Cards

### Card Structure

| 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 |

### Persona Types

- **Economic buyer** — Signs the check. Cares about ROI and risk.

- **Technical buyer** — Evaluates the product. Cares about capabilities and integration.

- **End user** — Uses it daily. Cares about ease and workflow fit.

- **Champion** — Advocates internally. Needs ammunition to sell for you.

- **Blocker** — Opposes the purchase. Understand their concern to neutralize it.

---

## Output Format

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 |

---

## Task-Specific Questions

If context is missing, ask:

1. What collateral do you need? (deck, one-pager, objection doc, etc.)

2. Who will use it? (AE, SDR, champion, prospect)

3. What sales stage is it for? (prospecting, discovery, demo, negotiation, close)

4. Who is the target persona? (title, seniority, department)

5. What are the top 3 objections you hear most?

---

## Tool Integrations

For partner sales enablement, see the [tools registry](../../tools/REGISTRY.md):

| Tool | What It Does | Guide |

|------|-------------|-------|

| **Introw** | Partner engagement tracking, deal registration, mutual action plans | [introw.md](../../tools/integrations/introw.md) |

---

## Related Skills

- **competitors**: For public-facing comparison and alternative pages

- **copywriting**: For marketing website copy

- **cold-email**: For outbound prospecting emails

- **revops**: For lead lifecycle, scoring, routing, and pipeline management

- **pricing**: For pricing decisions and packaging

- **product-marketing**: For foundational positioning and messaging

jsonskills/schema/evals/evals.json

5.8 kB

{

"skill_name": "schema",

"evals": [

{

"id": 1,

"prompt": "Add schema markup to our SaaS product's homepage. We're a project management tool called TaskFlow. We need Organization schema and any other relevant types.",

"expected_output": "Should check for product-marketing.md first. Should implement Organization schema in JSON-LD format with all required and recommended properties (name, url, logo, description, sameAs for social profiles). Should recommend additional schema types for a SaaS homepage: WebSite (with SearchAction if applicable), SoftwareApplication or Product. Should use @graph for multiple schema types on one page. Should provide the complete JSON-LD code ready to implement. Should recommend validation with Google's Rich Results Test and Schema.org validator.",

"assertions": [

"Checks for product-marketing.md",

"Implements Organization schema in JSON-LD",

"Includes required and recommended properties",

"Recommends additional relevant schema types",

"Uses @graph for multiple types",

"Provides complete JSON-LD code",

"Recommends validation tools"

"files": []

{

"id": 2,

"prompt": "We have a FAQ page with 20 questions about our product. How do I add FAQ schema to get the rich results in Google?",

"expected_output": "Should implement FAQPage schema in JSON-LD format. Should show the correct structure: FAQPage as mainEntity containing Question items, each with acceptedAnswer. Should provide a complete code example with 2-3 sample questions. Should explain that FAQ schema can enable rich results showing questions/answers directly in search. Should note Google's guidelines for FAQ schema (factual answers, not promotional). Should recommend validation approach.",

"assertions": [

"Implements FAQPage schema in JSON-LD",

"Shows correct nested structure (FAQPage > Question > Answer)",

"Provides complete code example",

"Explains rich result benefits",

"Notes Google's FAQ schema guidelines",

"Recommends validation"

"files": []

{

"id": 3,

"prompt": "add schema to our blog posts. we publish articles about marketing tips.",

"expected_output": "Should trigger on casual phrasing. Should implement Article (or BlogPosting) schema in JSON-LD. Should include required properties: headline, author (as Person with name and url), datePublished, dateModified, image, publisher (as Organization). Should recommend BreadcrumbList schema alongside the article schema. Should provide template code that can be reused across blog posts. Should address how to populate dynamic fields (date, author, headline) from the CMS.",

"assertions": [

"Triggers on casual phrasing",

"Implements Article or BlogPosting schema",

"Includes author, datePublished, image, publisher",

"Recommends BreadcrumbList alongside",

"Provides reusable template code",

"Addresses CMS integration for dynamic fields"

"files": []

{

"id": 4,

"prompt": "We're an e-commerce site selling physical products. What schema markup do we need for our product pages?",

"expected_output": "Should implement Product schema with full properties: name, description, image, brand, sku, offers (with price, priceCurrency, availability, url). Should recommend AggregateRating if they have reviews, and Review schema for individual reviews. Should include BreadcrumbList for navigation. Should address common e-commerce schema types: Product, Offer, AggregateRating, Review. Should provide complete JSON-LD code. Should note that Product schema can enable rich results (price, availability, ratings in search).",

"assertions": [

"Implements Product schema with full properties",

"Includes Offer with price, availability",

"Recommends AggregateRating and Review schema",

"Includes BreadcrumbList",

"Provides complete JSON-LD code",

"Notes rich result benefits for products"

"files": []

{

"id": 5,

"prompt": "We added schema markup to our site but it's not showing rich results in Google. Can you help debug?",

"expected_output": "Should provide a systematic debugging approach: first validate with Google Rich Results Test and Schema.org validator (syntax errors), then check for common issues (incorrect nesting, missing required properties, JSON-LD placement errors). Should explain that valid schema doesn't guarantee rich results — Google chooses when to show them. Should recommend checking Search Console for structured data reports and errors. Should address common debugging scenarios: schema not detected, warnings vs errors, eligible vs displayed.",

"assertions": [

"Recommends validation tools for debugging",

"Checks for common schema errors",

"Explains valid schema doesn't guarantee rich results",

"Recommends Search Console structured data reports",

"Addresses warnings vs errors distinction",

"Provides systematic debugging approach"

"files": []

{

"id": 6,

"prompt": "Our organic search traffic dropped after a site redesign. Can you do a technical SEO audit?",

"expected_output": "Should recognize this is a technical SEO audit request, not a schema markup task. Should defer to or cross-reference the seo-audit skill, which handles comprehensive technical SEO audits. Schema markup is one component of SEO but doesn't address the broader technical issues (redirects, crawlability, indexation) that likely caused the traffic drop.",

"assertions": [

"Recognizes this as a technical SEO audit request",

"References or defers to seo-audit skill",

"Does not attempt full SEO audit using schema markup patterns"

"files": []

}

]

}

mdskills/schema/references/schema-examples.md

8.0 kB

# Schema Markup Examples

Complete JSON-LD examples for common schema types.

## Contents

- Organization

- WebSite (with SearchAction)

- Article / BlogPosting

- Product

- SoftwareApplication

- FAQPage

- HowTo

- BreadcrumbList

- LocalBusiness

- Event

- Multiple Schema Types

- Implementation Example (Next.js)

## Organization

For company/brand homepage or about page.

```json

{

"@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"

}

```

---

## WebSite (with SearchAction)

For homepage, enables sitelinks search box.

```json

{

"@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"

}

```

---

## Article / BlogPosting

For blog posts and news articles.

```json

{

"@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"

}

```

---

## Product

For product pages (e-commerce or SaaS).

```json

{

"@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"

}

```

---

## SoftwareApplication

For SaaS product pages and app landing pages.

```json

{

"@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"

}

```

---

## FAQPage

For pages with frequently asked questions.

```json

{

"@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..."

}

]

}

```

---

## HowTo

For instructional content and tutorials.

```json

{

"@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"

}

]

}

```

---

## BreadcrumbList

For any page with breadcrumb navigation.

```json

{

"@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"

}

]

}

```

---

## LocalBusiness

For local business location pages.

```json

{

"@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": "$$"

}

```

---

## Event

For event pages, webinars, conferences.

```json

{

"@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"

}

```

---

## Multiple Schema Types

Combine multiple schema types using @graph.

```json

{

"@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": [...]

}

]

}

```

---

## Implementation Example (Next.js)

```jsx

export default function ProductPage({ product }) {

const schema = {

"@context": "https://schema.org",

"@type": "Product",

// ... other properties

};

return (

<Head>

<script

type="application/ld+json"

dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}

</Head>

{/* Page content */}

</>

);

}

```

mdskills/schema/SKILL.md

5.1 kB

---

description: 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," "product schema," "review schema," "breadcrumb schema," "Google rich results," "knowledge panel," "star ratings in search," or "add structured data." Use this whenever someone wants their pages to show enhanced results in Google. For broader SEO issues, see seo-audit. For AI search optimization, see ai-seo.

metadata:

version: 2.0.0

---

# Schema Markup

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.

## Initial Assessment

**Check for product marketing context first:**

Before implementing schema, understand:

1. **Page Type** - What kind of page? What's the primary content? What rich results are possible?

2. **Current State** - Any existing schema? Errors in implementation? Which rich results already appearing?

3. **Goals** - Which rich results are you targeting? What's the business value?

---

## Core Principles

### 1. Accuracy First

- Schema must accurately represent page content

- Don't markup content that doesn't exist

- Keep updated when content changes

### 2. Use JSON-LD

- Google recommends JSON-LD format

- Easier to implement and maintain

- Place in `<head>` or end of `<body>`

### 3. Follow Google's Guidelines

- Only use markup Google supports

- Avoid spam tactics

- Review eligibility requirements

### 4. Validate Everything

- Test before deploying

- Monitor Search Console

- Fix errors promptly

---

## Common Schema Types

| 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](references/schema-examples.md)

---

## Quick Reference

### Organization (Company Page)

Required: name, url

Recommended: logo, sameAs (social profiles), contactPoint

### Article/BlogPosting

Required: headline, image, datePublished, author

Recommended: dateModified, publisher, description

### Product

Required: name, image, offers (price + availability)

Recommended: sku, brand, aggregateRating, review

### FAQPage

Required: mainEntity (array of Question/Answer pairs)

### BreadcrumbList

Required: itemListElement (array with position, name, item)

---

## Multiple Schema Types

You can combine multiple schema types on one page using `@graph`:

```json

{

"@context": "https://schema.org",

"@graph": [

{ "@type": "Organization", ... },

{ "@type": "WebSite", ... },

{ "@type": "BreadcrumbList", ... }

]

}

```

---

## Validation and Testing

### Tools

- **Google Rich Results Test**: https://search.google.com/test/rich-results

- **Schema.org Validator**: https://validator.schema.org/

- **Search Console**: Enhancements reports

### Common Errors

**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

---

## Implementation

### Static Sites

- Add JSON-LD directly in HTML template

- Use includes/partials for reusable schema

### Dynamic Sites (React, Next.js)

- Component that renders schema

- Server-side rendered for SEO

- Serialize data to JSON-LD

### CMS / WordPress

- Plugins (Yoast, Rank Math, Schema Pro)

- Theme modifications

- Custom fields to structured data

---

## Output Format

### Schema Implementation

```json

// Full JSON-LD code block

{

"@context": "https://schema.org",

"@type": "...",

// Complete markup

}

```

### Testing Checklist

- [ ] Validates in Rich Results Test

- [ ] No errors or warnings

- [ ] Matches page content

- [ ] All required properties included

---

## Task-Specific Questions

1. What type of page is this?

2. What rich results are you hoping to achieve?

3. What data is available to populate the schema?

4. Is there existing schema on the page?

5. What's your tech stack?

---

## Related Skills

- **seo-audit**: For overall SEO including schema review

- **ai-seo**: For AI search optimization (schema helps AI understand content)

- **programmatic-seo**: For templated schema at scale

- **site-architecture**: For breadcrumb structure and navigation schema planning

jsonskills/seo-audit/evals/evals.json

9.6 kB

{

"skill_name": "seo-audit",

"evals": [

{

"id": 1,

"prompt": "Can you do an SEO audit of our SaaS website? We're getting about 2,000 organic visits/month but feel like we should be getting more. URL: https://example.com",

"expected_output": "Should check for product-marketing.md first. Should ask clarifying questions about priority keywords, Search Console access, recent changes, and competitors. Should follow the audit framework priority order: Crawlability & Indexation, Technical Foundations, On-Page Optimization, Content Quality, Authority & Links. Should check robots.txt, XML sitemap, site architecture. Should evaluate title tags, meta descriptions, heading structure, and content optimization. Should NOT report on schema markup based solely on web_fetch (must note the detection limitation). Output should follow the Audit Report Structure: Executive Summary, Technical SEO Findings, On-Page SEO Findings, Content Findings, and Prioritized Action Plan.",

"assertions": [

"Checks for product-marketing.md",

"Asks clarifying questions about keywords, Search Console, recent changes",

"Follows audit priority order: crawlability first, then technical, on-page, content, authority",

"Checks robots.txt and XML sitemap",

"Evaluates title tags, meta descriptions, heading structure",

"Does NOT claim 'no schema found' based on web_fetch alone",

"Notes schema markup detection limitation",

"Output has Executive Summary",

"Output has Prioritized Action Plan",

"Each finding has Issue, Impact, Evidence, Fix, and Priority"

"files": []

{

"id": 2,

"prompt": "Why am I not ranking for 'project management software'? We have a page targeting that keyword but it's stuck on page 3.",

"expected_output": "Should trigger on the casual 'why am I not ranking' phrasing. Should investigate both on-page and off-page factors. On-page: check title tag, H1, URL alignment with keyword; evaluate content depth vs competitors; check for keyword cannibalization. Technical: check indexation status, canonical tags, crawlability. Content quality: assess E-E-A-T signals, content depth, user engagement. Should provide specific, actionable fixes organized by priority. Should mention competitive analysis against current top-ranking pages.",

"assertions": [

"Triggers on casual 'why am I not ranking' phrasing",

"Checks title tag, H1, URL alignment with target keyword",

"Evaluates content depth vs competitors",

"Checks for keyword cannibalization",

"Checks indexation status and canonical tags",

"Assesses E-E-A-T signals",

"Mentions competitive analysis against top-ranking pages",

"Provides actionable fixes organized by priority"

"files": []

{

"id": 3,

"prompt": "We just migrated from WordPress to Next.js and our organic traffic dropped 40% in the last month. Help!",

"expected_output": "Should treat this as an urgent migration diagnostic. Should immediately check: redirect mapping (301s from old URLs to new), canonical tags on new pages, robots.txt not blocking crawlers, XML sitemap submitted and updated, meta tags preserved. Should check for common migration issues: redirect chains/loops, soft 404s, lost internal links, changed URL structures without redirects. Should reference Search Console coverage report for indexation issues. Should provide a prioritized recovery plan with critical fixes first. Should mention monitoring timeline expectations (recovery can take weeks).",

"assertions": [

"Treats as urgent migration diagnostic",

"Checks redirect mapping (301s)",

"Checks canonical tags on new pages",

"Checks robots.txt not blocking crawlers",

"Checks XML sitemap updated and submitted",

"Checks for redirect chains or loops",

"Checks for soft 404s",

"References Search Console coverage report",

"Provides prioritized recovery plan",

"Mentions recovery timeline expectations"

"files": []

{

"id": 4,

"prompt": "Review the technical SEO of our e-commerce site. We have about 50,000 products and use faceted navigation.",

"expected_output": "Should focus on e-commerce-specific technical issues: faceted navigation creating duplicate content, crawl budget management for large product catalog, parameterized URLs, product schema markup (with the caveat about detection limitations). Should check for thin category pages, duplicate product descriptions, out-of-stock page handling. Should address crawl budget issues: pagination, infinite scroll handling, session IDs in URLs. Should provide structured findings with Impact ratings and specific fixes.",

"assertions": [

"Addresses faceted navigation duplicate content",

"Addresses crawl budget for large catalog",

"Checks for parameterized URL issues",

"Mentions product schema with detection limitation caveat",

"Checks for thin category pages",

"Checks for duplicate product descriptions",

"Addresses out-of-stock page handling",

"Addresses pagination and infinite scroll",

"Findings include Impact ratings and specific fixes"

"files": []

{

"id": 5,

"prompt": "Can you check our blog posts for on-page SEO issues? We publish 4 posts per week but traffic has been flat for 6 months.",

"expected_output": "Should apply the Content/Blog Sites framework: check for outdated content not refreshed, keyword cannibalization, missing topical clustering, poor internal linking, missing author pages. Should audit on-page elements: title tags, meta descriptions, heading structure, keyword targeting per post. Should assess E-E-A-T signals for blog content. Should check for content depth issues and whether posts answer search intent. Should recommend a content audit process and provide a prioritized action plan for the existing content library.",

"assertions": [

"Applies Content/Blog Sites framework",

"Checks for outdated content",

"Checks for keyword cannibalization",

"Checks for topical clustering",

"Checks for internal linking quality",

"Checks for author pages and E-E-A-T signals",

"Audits title tags, meta descriptions, heading structure",

"Assesses whether content answers search intent",

"Recommends content audit process",

"Provides prioritized action plan"

"files": []

{

"id": 6,

"prompt": "I run a local plumbing business with 3 locations. My website barely shows up when people search for 'plumber near me' in our areas. What's wrong?",

"expected_output": "Should apply the Local Business site-type framework. Should check for: inconsistent NAP (Name, Address, Phone) across the site, missing local schema markup (with detection limitation caveat), Google Business Profile optimization, missing individual location pages for each of the 3 locations, and missing local content. Should also check standard technical and on-page factors. Should recommend local-specific fixes: location-specific pages with unique content, local schema on each, GBP optimization, citation consistency.",

"assertions": [

"Applies Local Business framework",

"Checks NAP consistency",

"Checks for local schema markup with detection caveat",

"Addresses Google Business Profile optimization",

"Recommends individual location pages for each location",

"Recommends local content strategy",

"Checks standard technical SEO factors too",

"Provides prioritized local SEO action plan"

"files": []

{

"id": 7,

"prompt": "Our site loads really slowly, especially on mobile. Pages take 5-6 seconds to load. Is this hurting our SEO?",

"expected_output": "Should focus on Site Speed and Core Web Vitals. Should explain CWV thresholds: LCP < 2.5s, INP < 200ms, CLS < 0.1, and that 5-6s load time is well above acceptable. Should investigate speed factors: server response time (TTFB), image optimization, JavaScript execution, CSS delivery, caching headers, CDN usage, font loading. Should recommend specific tools: PageSpeed Insights, WebPageTest, Chrome DevTools, Search Console CWV report. Should explain that yes, page speed is a ranking factor and directly impacts SEO. Should provide prioritized fixes.",

"assertions": [

"Focuses on Core Web Vitals",

"Explains CWV thresholds (LCP, INP, CLS)",

"Identifies 5-6s as well above acceptable",

"Investigates specific speed factors",

"Recommends specific diagnostic tools",

"Confirms page speed impacts SEO rankings",

"Provides prioritized speed fixes",

"Addresses mobile-specific performance"

"files": []

{

"id": 8,

"prompt": "I want to add FAQ schema to my product pages. Can you help me set that up?",

"expected_output": "Should recognize this is a schema markup implementation task, not an SEO audit. Should defer to or cross-reference the schema skill, which specifically handles structured data implementation including FAQ schema. May briefly mention that FAQ schema can enable rich results, but should make clear that schema is the right skill for implementation.",

"assertions": [

"Recognizes this as schema markup implementation",

"References or defers to schema skill",

"Does not attempt a full SEO audit",

"May briefly mention FAQ schema benefits"

"files": []

}

]

}

mdskills/seo-audit/references/ai-writing-detection.md

6.4 kB

# AI Writing Detection

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)

---

## Contents

- Em Dashes: The Primary AI Tell

- Overused Verbs

- Overused Adjectives

- Overused Transitions and Connectors

- Phrases That Signal AI Writing (Opening Phrases, Transitional Phrases, Concluding Phrases, Structural Patterns)

- Filler Words and Empty Intensifiers

- Academic-Specific AI Tells

- How to Self-Check

## Em Dashes: The Primary AI Tell

**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.

### Why Em Dashes Signal AI Writing

- AI models were trained on edited books, academic papers, and style guides where em dashes appear frequently

- AI uses em dashes as a shortcut for sentence variety instead of commas, colons, or parentheses

- Most human writers rarely use em dashes because they don't exist as a standard keyboard key

- The overuse is so consistent that it has become the unofficial signature of ChatGPT writing

### What To Do Instead

| 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 |

### Guidelines

- Use commas for most parenthetical information

- Use colons to introduce explanations or lists

- Use parentheses for supplementary information

- Reserve em dashes for rare, deliberate emphasis only

- If you find yourself using more than one em dash per page, revise

---

## Overused Verbs

| 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 |

---

## Overused Adjectives

| 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 |

---

## Overused Transitions and Connectors

| 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 |

---

## Phrases That Signal AI Writing

### Opening Phrases to Avoid

- "In today's fast-paced world..."

- "In today's digital age..."

- "In an era of..."

- "In the ever-evolving landscape of..."

- "In the realm of..."

- "It's important to note that..."

- "Let's delve into..."

- "Imagine a world where..."

### Transitional Phrases to Avoid

- "That being said..."

- "With that in mind..."

- "It's worth mentioning that..."

- "At its core..."

- "To put it simply..."

- "In essence..."

- "This begs the question..."

### Concluding Phrases to Avoid

- "In conclusion..."

- "To sum up..."

- "By [doing X], you can [achieve Y]..."

- "In the final analysis..."

- "All things considered..."

- "At the end of the day..."

### Structural Patterns to Avoid

- "Whether you're a [X], [Y], or [Z]..." (listing three examples after "whether")

- "It's not just [X], it's also [Y]..."

- "Think of [X] as [elaborate metaphor]..."

- Starting sentences with "By" followed by a gerund: "By understanding X, you can Y..."

---

## Filler Words and Empty Intensifiers

These words often add nothing to meaning. Remove them or find specific alternatives:

- absolutely

- actually

- basically

- certainly

- clearly

- definitely

- essentially

- extremely

- fundamentally

- incredibly

- interestingly

- naturally

- obviously

- quite

- really

- significantly

- simply

- surely

- truly

- ultimately

- undoubtedly

- very

---

## Academic-Specific AI Tells

| 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) |

---

## How to Self-Check

1. Read your text aloud. If phrases sound unnatural in speech, revise them

2. Ask: "Would I say this in a conversation with a colleague?"

3. Check for repetitive sentence structures

4. Look for clusters of the words listed above

5. Ensure varied sentence lengths (not all similar length)

6. Verify each intensifier adds genuine meaning

mdskills/seo-audit/references/international-seo.md

14 kB

# International SEO: Evidence & Sources

Detailed evidence backing the International SEO & Localization section of the SEO Audit skill. Organized by topic with source URLs and key quotes.

---

## Hreflang

### Placement Methods

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 Search Central: Localized Versions](https://developers.google.com/search/docs/specialty/international/localized-versions)

- [SEJ: Google Combines Hreflang Signals](https://www.searchenginejournal.com/google-combines-hreflang-signals-from-html-sitemaps/389219/)

### Reciprocal Requirement

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.

- [Google Search Central: Localized Versions](https://developers.google.com/search/docs/specialty/international/localized-versions)

- [Semrush: 9 Common Hreflang Errors](https://www.semrush.com/blog/hreflang-errors/)

- [SE Land: 31% of International Websites Contain Hreflang Errors](https://searchengineland.com/study-31-of-international-websites-contain-hreflang-errors-395161)

### x-default

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.

- [Google Blog: x-default hreflang](https://developers.google.com/search/blog/2013/04/x-default-hreflang-for-international-pages)

- [Google Blog: How x-default can help you (2023)](https://developers.google.com/search/blog/2023/05/x-default)

### Language & Region Codes

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.

- [Google Search Central: Localized Versions](https://developers.google.com/search/docs/specialty/international/localized-versions)

- [SE Land: 31% Study](https://searchengineland.com/study-31-of-international-websites-contain-hreflang-errors-395161)

### Hreflang at Scale (20+ locales)

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."

- [SERoundtable: Child Elements Don't Count](https://www.seroundtable.com/google-child-elements-dont-count-towards-sitemap-url-limit-34377.html)

- [SERoundtable: Where To Focus Hreflang](https://www.seroundtable.com/using-hreflang-34127.html)

- [Yoast: hreflang Ultimate Guide](https://yoast.com/hreflang-ultimate-guide/)

### Google vs Bing

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).

- [Digital Ready Marketing: Bing Doesn't Use Hreflang](https://digitalreadymarketing.com/bing-doesnt-use-hreflang-annotation-what-does-it-use/)

- [Yoast: hreflang Ultimate Guide](https://yoast.com/hreflang-ultimate-guide/)

---

## Canonicalization & i18n

### Self-Referencing Canonicals

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."

- [John Mueller: hreflang canonical](https://johnmu.com/hreflang-canonical/)

- [Google: Consolidate Duplicate URLs](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls)

### Canonical Overrides Hreflang

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.

- [John Mueller: hreflang canonical](https://johnmu.com/hreflang-canonical/)

- [SEJ: Hreflang Tags Are Hints](https://www.searchenginejournal.com/google-reminds-that-hreflang-tags-are-hints-not-directives/546428/)

- [Google: Consolidate Duplicate URLs](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls)

### Near-Duplicate Regional Variants

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.

- [International Web Mastery: Same-Language Duplicate Pages](https://internationalwebmastery.com/blog/how-google-handles-canonicalization-of-same-language-duplicate-near-duplicate-pages/)

- [Google: Managing Multi-Regional Sites](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites)

### Pagination Across Locales

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.

- [Google: Pagination Best Practices](https://developers.google.com/search/docs/specialty/ecommerce/pagination-and-incremental-page-loading)

---

## International Sitemaps

### Structure

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).

- [Google Search Central: Localized Versions](https://developers.google.com/search/docs/specialty/international/localized-versions)

- [Lumar: How Google Handles Hreflang](https://www.lumar.io/office-hours/hreflang/)

### Size Limits

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.

- [Google: Build and Submit a Sitemap](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap)

- [SERoundtable: Sitemap 50,000 Limit](https://www.seroundtable.com/google-sitemap-50-000-limit-based-on-location-urls-not-alternative-urls-33843.html)

### Submission

Submit the sitemap index in Search Console AND reference it in robots.txt. Individual child sitemaps can be submitted separately for per-sitemap reporting.

- [Google: Build and Submit a Sitemap](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap)

### Next.js Caveat

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.

- [Next.js Docs: sitemap.xml](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap)

---

## URL Structure

### Strategies Compared

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.

- [Google: Managing Multi-Regional Sites](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites)

### Default Language

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 Blog: x-default](https://developers.google.com/search/blog/2023/05/x-default)

- [Google Blog: Creating the Right Homepage](https://developers.google.com/search/blog/2014/05/creating-right-homepage-for-your)

### Content Negotiation / IP Redirects

Google strongly advises against locale-adaptive pages. Googlebot crawls from US IPs and does not send Accept-Language headers. Separate URLs + hreflang are required.

- [Google: Locale-Adaptive Pages](https://developers.google.com/search/docs/specialty/international/locale-adaptive-pages)

### Trailing Slash Consistency

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."

- [SERoundtable: Consistency Is The Biggest Technical SEO Factor](https://www.seroundtable.com/google-consistency-seo-40427.html)

### Search Console Geotargeting

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.

- [Google Support: International Targeting Deprecated](https://support.google.com/webmasters/answer/12474899?hl=en)

### Framework Locale Modes

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.

- [next-intl: Routing Configuration](https://next-intl.dev/docs/routing/configuration)

- [Next.js Discussion #18419](https://github.com/vercel/next.js/discussions/18419)

---

## Content Quality Across Locales

### Auto-Translated Content (2025 Stance)

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 Spam Policies](https://developers.google.com/search/docs/essentials/spam-policies)

- [Glenn Gabe: Auto-Translating Content](https://www.gsqi.com/marketing-blog/auto-translating-content-google-scaled-content-abuse/)

- [SE Land: Reddit AI Translations](https://searchengineland.com/google-comments-on-reddits-use-of-ai-to-translate-its-pages-456908)

### Thin Locale Pages

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.

- [Google: Localized Versions](https://developers.google.com/search/docs/specialty/international/localized-versions)

- [Google: Crawl Budget Management](https://developers.google.com/search/docs/crawling-indexing/large-site-managing-crawl-budget)

### Helpful Content System Impact

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 Blog: Helpful Content Update](https://developers.google.com/search/blog/2022/08/helpful-content-update)

- [Amsive: What Changed in 2024](https://www.amsive.com/insights/seo/googles-helpful-content-update-ranking-system-what-happened-and-what-changed-in-2024/)

### Partial Translation

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.

- [Google: Managing Multi-Regional Sites](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites)

### Crawl Budget

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: Crawl Budget Management](https://developers.google.com/search/docs/crawling-indexing/large-site-managing-crawl-budget)

- [Google Blog: Crawl Budget](https://developers.google.com/search/blog/2017/01/what-crawl-budget-means-for-googlebot)

### Locale-Specific 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."

- [Google: Managing Multi-Regional Sites](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites)

mdskills/seo-audit/SKILL.md

16 kB

---

description: 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 health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," or "indexing issues." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema. For AI search optimization, see ai-seo.

metadata:

version: 2.0.0

---

# SEO Audit

You are an expert in search engine optimization. Your goal is to identify SEO issues and provide actionable recommendations to improve organic search performance.

## Initial Assessment

**Check for product marketing context first:**

Before auditing, understand:

1. **Site Context**

- What type of site? (SaaS, e-commerce, blog, etc.)

- What's the primary business goal for SEO?

- What keywords/topics are priorities?

2. **Current State**

- Any known issues or concerns?

- Current organic traffic level?

- Recent changes or migrations?

3. **Scope**

- Full site audit or specific pages?

- Technical + on-page, or one focus area?

- Access to Search Console / analytics?

---

## Audit Framework

### Schema Markup Detection Limitation

**`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.

### Priority Order

1. **Crawlability & Indexation** (can Google find and index it?)

2. **Technical Foundations** (is the site fast and functional?)

3. **On-Page Optimization** (is content optimized?)

4. **Content Quality** (does it deserve to rank?)

5. **Authority & Links** (does it have credibility?)

---

## Technical SEO Audit

### Crawlability

**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

### Indexation

**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

### Site Speed & Core Web Vitals

**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

### Mobile-Friendliness

- Responsive design (not separate m. site)

- Tap target sizes

- Viewport configured

- No horizontal scroll

- Same content as desktop

- Mobile-first indexing readiness

### Security & HTTPS

- HTTPS across entire site

- Valid SSL certificate

- No mixed content

- HTTP → HTTPS redirects

- HSTS header (bonus)

### URL Structure

- Readable, descriptive URLs

- Keywords in URLs where natural

- Consistent structure

- No unnecessary parameters

- Lowercase and hyphen-separated

---

## International SEO & Localization

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](references/international-seo.md) for evidence and source URLs.

### Hreflang

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).

### Canonicalization for Multilingual Sites

- Each locale page must self-canonical (e.g., `/ar/page` canonicals to `/ar/page`)

- Never cross-locale canonical (French to English) -- suppresses the non-canonical locale entirely

- Canonical URL must appear in the hreflang set -- if not, all hreflang is ignored

- Canonical overrides hreflang when they conflict

- Protocol/domain must be consistent across canonical, hreflang, and sitemap (`https` + same domain variant)

- Paginated locale pages: self-referencing canonical per page (never canonical page 2+ to page 1)

**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.

### International Sitemaps

**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.

### Locale URL Structure

**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.

### Content Quality Across Locales

**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

---

## On-Page SEO Audit

### Title Tags

**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

### Meta Descriptions

**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

### Heading Structure

**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

### Content Optimization

**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

### Image Optimization

**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

### Internal Linking

**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

### Keyword Targeting

**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

---

## Content Quality Assessment

### E-E-A-T Signals

**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)

### Content Depth

- Comprehensive coverage of topic

- Answers follow-up questions

- Better than top-ranking competitors

- Updated and current

### User Engagement Signals

- Time on page

- Bounce rate in context

- Pages per session

- Return visits

---

## Common Issues by Site Type

### SaaS/Product Sites

- Product pages lack content depth

- Blog not integrated with product pages

- Missing comparison/alternative pages

- Feature pages thin on content

- No glossary/educational content

### E-commerce

- Thin category pages

- Duplicate product descriptions

- Missing product schema

- Faceted navigation creating duplicates

- Out-of-stock pages mishandled

### Content/Blog Sites

- Outdated content not refreshed

- Keyword cannibalization

- No topical clustering

- Poor internal linking

- Missing author pages

### Multilingual / Multi-Regional Sites

- Hreflang errors (missing return tags, invalid codes, no self-reference)

- Canonical conflicting with hreflang (cross-locale canonical suppresses indexing)

- Thin locale pages dragging down site-wide quality signal

- Only boilerplate translated, main content identical across locales

- No x-default fallback declared

- Sitemap missing hreflang alternates or missing reciprocal entries

- IP-based redirects hiding content from Googlebot

- Framework locale mode hiding locale from URLs

### Local Business

- Inconsistent NAP

- Missing local schema

- No Google Business Profile optimization

- Missing location pages

- No local content

---

## Output Format

### Audit Report Structure

**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

---

## References

- [AI Writing Detection](references/ai-writing-detection.md): Common AI writing patterns to avoid (em dashes, overused phrases, filler words)

- [International SEO](references/international-seo.md): Evidence and sources for hreflang, canonical + i18n, sitemaps, URL structure, and content quality across locales

- For AI search optimization (AEO, GEO, LLMO, AI Overviews), see the **ai-seo** skill

---

## Tools Referenced

**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_fetch` strips `<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

---

## Task-Specific Questions

1. What pages/keywords matter most?

2. Do you have Search Console access?

3. Any recent changes or migrations?

4. Who are your top organic competitors?

5. What's your current organic traffic baseline?

---

## Related Skills

- **ai-seo**: For optimizing content for AI search engines (AEO, GEO, LLMO)

- **programmatic-seo**: For building SEO pages at scale

- **site-architecture**: For page hierarchy, navigation design, and URL structure

- **schema**: For implementing structured data

- **cro**: For optimizing pages for conversion (not just ranking)

- **analytics**: For measuring SEO performance

jsonskills/signup/evals/evals.json

6.1 kB

{

"skill_name": "signup",

"evals": [

{

"id": 1,

"prompt": "Audit our signup flow. We have a 3-step process: Step 1 asks for email, password, and full name. Step 2 asks for company name, company size, role, and industry. Step 3 asks for use case and how they heard about us. Current completion rate is 45%.",

"expected_output": "Should check for product-marketing.md first. Should identify the flow type (likely B2B SaaS trial). Should apply the core principles: minimize required fields (which of these are genuinely needed before they can use the product?). Should evaluate each step: Step 1 is reasonable, Step 2 fields are mostly deferrable to progressive profiling, Step 3 is entirely deferrable. Should recommend cutting to Step 1 only or at most 2 steps. Should provide audit findings in structured format (Issue, Impact, Fix, Priority). Should include Quick Wins, High-Impact Changes, and Test Hypotheses.",

"assertions": [

"Checks for product-marketing.md",

"Identifies flow type",

"Applies minimize required fields principle",

"Evaluates each field for necessity",

"Recommends deferring most Step 2 and all Step 3 fields",

"Provides findings in structured format",

"Includes Quick Wins, High-Impact Changes, Test Hypotheses"

"files": []

{

"id": 2,

"prompt": "Should we add Google and Microsoft SSO to our signup page? We're a B2B project management tool and currently only have email/password signup.",

"expected_output": "Should apply the social auth options guidance. For B2B, should recommend Google and Microsoft as the primary SSO options (matching the B2B recommendation). Should explain benefits: higher conversion (less friction), pre-verified email, faster onboarding. Should recommend placing SSO prominently (often higher conversion than email). Should address implementation considerations: clear visual separation from email signup, button copy ('Sign up with Google' not just Google icon), consider which option to emphasize based on audience.",

"assertions": [

"Applies social auth options guidance",

"Recommends Google and Microsoft for B2B",

"Explains conversion benefits of SSO",

"Recommends prominent placement",

"Addresses visual separation from email signup",

"Provides implementation recommendations"

"files": []

{

"id": 3,

"prompt": "our signup form is just email and password but we still only get 35% of visitors to complete it. what else could be wrong?",

"expected_output": "Should trigger on casual phrasing. Should investigate beyond just form fields since the form is already minimal. Should apply trust and friction reduction guidance: is there a 'No credit card required' message? Privacy assurance? Testimonial near the form? Should check form-level issues: error handling, password requirements clarity, submit button copy. Should also look at pre-form factors: is the value proposition clear? Is the page optimized? (cross-reference cro). Should provide diagnostic checklist and recommendations.",

"assertions": [

"Triggers on casual phrasing",

"Investigates beyond form fields",

"Applies trust and friction reduction",

"Checks for 'No credit card required' messaging",

"Checks error handling and password UX",

"Considers pre-form factors (value prop, page CRO)",

"Provides diagnostic checklist"

"files": []

{

"id": 4,

"prompt": "We require email verification before users can access the product. Is that hurting our conversion? Should we change it?",

"expected_output": "Should apply the verification flows guidance. Should explain that requiring verification before product access does create friction and likely reduces activation. Should recommend alternatives: delay verification until needed (let users explore first), magic link as alternative to password, let users start while verification is pending. Should discuss when email verification IS required (compliance, preventing abuse). Should provide specific recommendations for improving the verification experience if kept.",

"assertions": [

"Applies verification flows guidance",

"Explains verification friction impact",

"Recommends delaying verification",

"Suggests letting users explore while pending",

"Discusses when verification is required",

"Provides improvements if verification is kept"

"files": []

{

"id": 5,

"prompt": "What experiments should we run on our signup page? We want to improve our trial signup rate.",

"expected_output": "Should apply the experiment ideas section. Should provide experiments across categories: form design experiments (layout, field count, SSO), copy and messaging experiments (headline, CTA text, trust elements), trial and commitment experiments (credit card required vs not, trial length), and post-submit experiments. Should prioritize experiments by likely impact. Should cross-reference ab-testing for proper experiment design.",

"assertions": [

"Applies experiment ideas section",

"Covers form design experiments",

"Covers copy and messaging experiments",

"Covers trial and commitment experiments",

"Prioritizes by likely impact",

"Cross-references ab-testing skill"

"files": []

{

"id": 6,

"prompt": "Users sign up fine but then never activate. Only 20% complete onboarding. What do we do?",

"expected_output": "Should recognize this is a post-signup onboarding problem, not a signup flow problem. Should defer to or cross-reference the onboarding skill, which handles post-signup activation and onboarding optimization. Signup-flow-cro covers getting users through the signup form, not what happens after.",

"assertions": [

"Recognizes this as post-signup onboarding, not signup flow",

"References or defers to onboarding skill",

"Explains signup covers the signup form, not post-signup"

"files": []

}

]

}

mdskills/signup/SKILL.md

10 kB

---

description: 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 signup," "reduce signup dropoff," "account creation flow," "people aren't signing up," "signup abandonment," "trial conversion rate," "nobody completes registration," "too many steps to sign up," or "simplify our signup." Use this whenever the user has a signup or registration flow that isn't performing. For post-signup onboarding, see onboarding. For lead capture forms (not account creation), see cro.

metadata:

version: 2.0.0

---

# Signup Flow CRO

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.

## Initial Assessment

**Check for product marketing context first:**

Before providing recommendations, understand:

1. **Flow Type**

- Free trial signup

- Freemium account creation

- Paid account creation

- Waitlist/early access signup

- B2B vs B2C

2. **Current State**

- How many steps/screens?

- What fields are required?

- What's the current completion rate?

- Where do users drop off?

3. **Business Constraints**

- What data is genuinely needed at signup?

- Are there compliance requirements?

- What happens immediately after signup?

---

## Core Principles

### 1. Minimize Required Fields

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

### 2. Show Value Before Asking for Commitment

- What can you show/give before requiring signup?

- Can they experience the product before creating an account?

- Reverse the order: value first, signup second

### 3. Reduce Perceived Effort

- Show progress if multi-step

- Group related fields

- Use smart defaults

- Pre-fill when possible

### 4. Remove Uncertainty

- Clear expectations ("Takes 30 seconds")

- Show what happens after signup

- No surprises (hidden requirements, unexpected steps)

---

## Field-by-Field Optimization

### Email Field

- Single field (no email confirmation field)

- Inline validation for format

- Check for common typos (gmial.com → gmail.com)

- Clear error messages

### Password Field

- Show password toggle (eye icon)

- Show requirements upfront, not after failure

- Consider passphrase hints for strength

- Update requirement indicators in real-time

**Better password UX:**

- Allow paste (don't disable)

- Show strength meter instead of rigid rules

- Consider passwordless options

### Name Field

- Single "Full name" field vs. First/Last split (test this)

- Only require if immediately used (personalization)

- Consider making optional

### Social Auth Options

- Place prominently (often higher conversion than email)

- Show most relevant options for your audience

- B2C: Google, Apple, Facebook

- B2B: Google, Microsoft, SSO

- Clear visual separation from email signup

- Consider "Sign up with Google" as primary

### Phone Number

- Defer unless essential (SMS verification, calling leads)

- If required, explain why

- Use proper input type with country code handling

- Format as they type

### Company/Organization

- Defer if possible

- Auto-suggest as they type

- Infer from email domain when possible

### Use Case / Role Questions

- Defer to onboarding if possible

- If needed at signup, keep to one question

- Use progressive disclosure (don't show all options at once)

---

## Single-Step vs. Multi-Step

### Single-Step Works When:

- 3 or fewer fields

- Simple B2C products

- High-intent visitors (from ads, waitlist)

### Multi-Step Works When:

- More than 3-4 fields needed

- Complex B2B products needing segmentation

- You need to collect different types of info

### Multi-Step Best Practices

- Show progress indicator

- Lead with easy questions (name, email)

- Put harder questions later (after psychological commitment)

- Each step should feel completable in seconds

- Allow back navigation

- Save progress (don't lose data on refresh)

**Progressive commitment pattern:**

1. Email only (lowest barrier)

2. Password + name

3. Customization questions (optional)

---

## Trust and Friction Reduction

### At the Form Level

- "No credit card required" (if true)

- "Free forever" or "14-day free trial"

- Privacy note: "We'll never share your email"

- Security badges if relevant

- Testimonial near signup form

### Error Handling

- Inline validation (not just on submit)

- Specific error messages ("Email already registered" + recovery path)

- Don't clear the form on error

- Focus on the problem field

### Microcopy

- Placeholder text: Use for examples, not labels

- Labels: Keep visible (not just placeholders) — placeholders disappear when typing, leaving users unsure what they're filling in

- Help text: Only when needed, placed close to field

---

## Mobile Signup Optimization

- Larger touch targets (44px+ height)

- Appropriate keyboard types (email, tel, etc.)

- Autofill support

- Reduce typing (social auth, pre-fill)

- Single column layout

- Sticky CTA button

- Test with actual devices

---

## Post-Submit Experience

### Success State

- Clear confirmation

- Immediate next step

- If email verification required:

- Explain what to do

- Easy resend option

- Check spam reminder

- Option to change email if wrong

### Verification Flows

- Consider delaying verification until necessary

- Magic link as alternative to password

- Let users explore while awaiting verification

- Clear re-engagement if verification stalls

---

## Measurement

### Key Metrics

- Form start rate (landed → started filling)

- Form completion rate (started → submitted)

- Field-level drop-off (which fields lose people)

- Time to complete

- Error rate by field

- Mobile vs. desktop completion

### What to Track

- Each field interaction (focus, blur, error)

- Step progression in multi-step

- Social auth vs. email signup ratio

- Time between steps

---

## Output Format

### Audit Findings

For each issue found:

- **Issue**: What's wrong

- **Impact**: Why it matters (with estimated impact if possible)

- **Fix**: Specific recommendation

- **Priority**: High/Medium/Low

### Recommended Changes

Organized by:

1. Quick wins (same-day fixes)

2. High-impact changes (week-level effort)

3. Test hypotheses (things to A/B test)

### Form Redesign (if requested)

- Recommended field set with rationale

- Field order

- Copy for labels, placeholders, buttons, errors

- Visual layout suggestions

---

## Common Signup Flow Patterns

### B2B SaaS Trial

1. Email + Password (or Google auth)

2. Name + Company (optional: role)

3. → Onboarding flow

### B2C App

1. Google/Apple auth OR Email

2. → Product experience

3. Profile completion later

### Waitlist/Early Access

1. Email only

2. Optional: Role/use case question

3. → Waitlist confirmation

### E-commerce Account

1. Guest checkout as default

2. Account creation optional post-purchase

3. OR Social auth with single click

---

## Experiment Ideas

### Form Design Experiments

**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

---

### Copy & Messaging Experiments

**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

---

### Trial & Commitment Experiments

**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

---

### Post-Submit Experiments

- Clear next steps messaging after signup

- Instant product access vs. email confirmation first

- Personalized welcome message based on signup data

- Auto-login after signup vs. require login

---

## Task-Specific Questions

1. What's your current signup completion rate?

2. Do you have field-level analytics on drop-off?

3. What data is absolutely required before they can use the product?

4. Are there compliance or verification requirements?

5. What happens immediately after signup?

---

## Related Skills

- **onboarding**: For optimizing what happens after signup

- **cro**: For non-signup forms (lead capture, contact)

- **cro**: For the landing page leading to signup

- **ab-testing**: For testing signup flow changes

jsonskills/site-architecture/evals/evals.json

5.9 kB

{

"skill_name": "site-architecture",

"evals": [

{

"id": 1,

"prompt": "Help me plan the site architecture for our new SaaS marketing website. We have a homepage, product page, pricing page, about page, blog, and want to add competitor comparison pages and integration pages.",

"expected_output": "Should check for product-marketing.md first. Should apply the page hierarchy design principles (3-click rule, flat vs deep). Should create an ASCII tree showing the full site structure. Should organize pages logically: main nav (Home, Product, Pricing, About, Blog), comparison pages section, integrations hub. Should recommend URL structure patterns for each section. Should provide navigation design recommendations (4-7 header items). Should include internal linking strategy (hub-and-spoke for comparisons and integrations). Should provide the full deliverable set: hierarchy, URL map, nav spec.",

"assertions": [

"Checks for product-marketing.md",

"Applies 3-click rule and flat vs deep principles",

"Creates ASCII tree for site structure",

"Organizes pages logically",

"Recommends URL structure for each section",

"Provides navigation design (4-7 header items)",

"Includes internal linking strategy",

"Provides hierarchy, URL map, and nav spec"

"files": []

{

"id": 2,

"prompt": "Our website has grown organically and the navigation is a mess. We have 50+ pages and users can't find anything. Help us reorganize.",

"expected_output": "Should treat this as a site architecture audit and redesign. Should recommend starting with a content inventory of all 50+ pages. Should apply the page hierarchy design to reorganize: group related pages, establish clear parent-child relationships, apply the 3-click rule. Should redesign the navigation (reduce header items, use mega-menu or dropdowns for deeper pages). Should provide before/after ASCII tree structure. Should address URL redirects for any pages that move. Should include a visual sitemap (Mermaid).",

"assertions": [

"Recommends content inventory first",

"Groups related pages logically",

"Applies 3-click rule",

"Redesigns navigation structure",

"Provides ASCII tree or visual sitemap",

"Addresses URL redirects for moved pages",

"Reduces header navigation items"

"files": []

{

"id": 3,

"prompt": "what should our url structure look like? we keep debating between /blog/post-name vs /resources/blog/post-name and /product/feature vs /features/feature-name",

"expected_output": "Should trigger on casual phrasing. Should apply the URL structure patterns guidance. Should recommend clean, descriptive URLs: prefer shorter paths (/blog/post-name over /resources/blog/post-name), use consistent patterns, avoid unnecessary nesting. Should provide URL structure recommendations for each section type (blog, features, comparisons, integrations). Should address SEO implications of URL structure. Should provide a complete URL map as a reference.",

"assertions": [

"Triggers on casual phrasing",

"Applies URL structure patterns",

"Recommends shorter, cleaner paths",

"Provides recommendations for each section type",

"Addresses SEO implications",

"Provides URL map reference"

"files": []

{

"id": 4,

"prompt": "We're adding programmatic SEO pages — 200 integration pages and 50 comparison pages. How should these fit into our site architecture?",

"expected_output": "Should address how to integrate scaled content into the site architecture. Should recommend hub pages for both sections (/integrations and /compare or /vs). Should apply the hub-and-spoke internal linking model. Should address navigation: these shouldn't clutter the main nav, but should be accessible via hub pages. Should provide URL structure for both sections. Should address crawl budget considerations for 250 new pages. Should cross-reference programmatic-seo for the content strategy.",

"assertions": [

"Recommends hub pages for each section",

"Applies hub-and-spoke internal linking",

"Keeps programmatic pages out of main nav",

"Provides URL structure for both sections",

"Addresses crawl budget for 250 pages",

"Cross-references programmatic-seo skill"

"files": []

{

"id": 5,

"prompt": "Can you create a visual sitemap for our site? We want something we can share with our design team.",

"expected_output": "Should provide a visual sitemap using Mermaid diagram format. Should organize the sitemap hierarchically showing page relationships. Should use the Mermaid graph syntax that can be rendered by most tools. Should include all major sections and key pages. Should be clear enough for a design team to use as a reference for navigation and wireframing.",

"assertions": [

"Provides visual sitemap in Mermaid format",

"Shows hierarchical page relationships",

"Includes all major sections",

"Uses clear, readable format",

"Suitable for sharing with design team"

"files": []

{

"id": 6,

"prompt": "Our XML sitemap hasn't been updated in 6 months and we have crawl errors in Search Console. Can you fix our technical SEO?",

"expected_output": "Should recognize this is a technical SEO audit task, not a site architecture design task. Should defer to or cross-reference the seo-audit skill, which handles XML sitemaps, crawl errors, and technical SEO issues. Site-architecture focuses on page hierarchy, navigation, and URL structure design — not technical SEO troubleshooting.",

"assertions": [

"Recognizes this as technical SEO, not site architecture",

"References or defers to seo-audit skill",

"Explains site-architecture covers design, not technical SEO"

"files": []

}

]

}

mdskills/site-architecture/references/mermaid-templates.md

4.8 kB

# Mermaid Diagram Templates

Copy-paste-ready Mermaid diagrams for visual sitemaps. Customize node labels and connections for your site.

---

## Basic Hierarchy

Simple top-down page hierarchy.

```mermaid

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"]

```

---

## Hierarchy with Navigation Zones

Uses subgraphs to show which pages appear in which navigation area.

```mermaid

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

```

---

## Hierarchy with URL Labels

Each node shows the page name and URL path.

```mermaid

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>"]

```

---

## Hub-and-Spoke Content Model

Shows a hub page connected to spoke articles, with spokes linking to each other.

```mermaid

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

---

## Internal Linking Flow

Shows how different site sections link to each other.

```mermaid

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

```

---

## Before/After Restructuring

Compare current and proposed site structures side by side.

```mermaid

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

```

---

## Color-Coding Conventions

Use styles to highlight page status, priority, or type.

```mermaid

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

mdskills/site-architecture/references/navigation-patterns.md

10 kB

# Navigation Patterns

Detailed navigation patterns for different site types and contexts.

---

## Header Navigation

### Simple Header (4-6 items)

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)

### Mega Menu Header

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

### Split Navigation

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.

---

## Footer Navigation

### Column-Based Footer (Standard)

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 │

│ │

│ Social: [Twitter] [LinkedIn] [GitHub] │

│ │

└──────────────────────────────────────────────────────────┘

```

### Minimal Footer

Best for: simple sites, landing pages.

```

┌──────────────────────────────────────────────────────────┐

│ [Logo] │

└──────────────────────────────────────────────────────────┘

```

### Expanded Footer

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 │

│ │

└──────────────────────────────────────────────────────────┘

```

---

## Sidebar Navigation

### Documentation Sidebar

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)

### Blog Category Sidebar

```