Mario Karras

@clawhub-mariokarras-f59a320bef

49prompts

0upvotes received

0contributions

Joined about 1 month ago

49 contributions in the last year

Jun

Jul

Aug

Sep

Oct

Nov

Dec

Jan

Feb

Mar

Apr

May

Less

Industry Research

Skill

When the user wants to conduct industry research, keyword research for a campaign, search demand analysis, intent mapping, audience research, or understand w...

---
name: industry-research
description: "When the user wants to conduct industry research, keyword research for a campaign, search demand analysis, intent mapping, audience research, or understand what people are searching for. Also use when the user mentions 'industry research,' 'keyword clusters,' 'search intent,' 'what are people looking for,' 'audience questions,' 'content gaps,' 'competitor keywords,' 'SERP analysis,' or 'research before campaign.' This skill orchestrates multi-tool deep research using Ahrefs, Firecrawl, and Exa to produce a comprehensive intelligence brief. For raw web scraping, see firecrawl-cli; for competitor analysis, see competitive-intelligence; for market sizing, see market-research."
metadata:
  version: 1.0.0
---

# Industry Research

You conduct deep, intent-driven industry research. The core question is "what are people looking for?" -- not "what are competitors doing?" Keyword intent, search demand, and real audience language are the primary signals. Competitor analysis serves the intent research by finding gaps in what's being served.

## Before Starting

**Check for product marketing context first:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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.

Then determine:

1. **Client name** -- Which client to research for
2. **Industry/market** -- The market category and key services/products
3. **Seed keywords** -- 5-8 starting keyword phrases reflecting core services
4. **Competitor URLs** -- 3-5 known competitor websites to analyze
5. **Geographic focus** -- Target region for keyword data (default: US)

If dispatched via cron or orchestrator with a specific client name, use the product-marketing-context for that client to derive seed keywords and competitors automatically.

---

## Workflow

### Step 1: Keyword Research (Ahrefs)

Use Ahrefs to gather keyword data. Try the Ahrefs MCP server first (if available via mcporter or MCP tools list). If MCP is not available, fall back to the Ahrefs REST API at `https://api.ahrefs.com/v3` with `Authorization: Bearer $AHREFS_API_KEY`.

Regardless of access method, gather data from these endpoints/capabilities:

**Keywords Explorer overview** -- seed keywords (batch up to 10 per request) for volume, difficulty, traffic potential:
```
POST /keywords-explorer/overview
Body: { "keywords": ["seed1", "seed2", ...], "country": "us" }
```

**Keywords Explorer matching terms** -- for each seed keyword, find related keywords (limit: 100 results per seed):
```
POST /keywords-explorer/matching-terms
Body: { "keyword": "seed keyword", "country": "us", "limit": 100 }
```

**Keywords Explorer related terms** -- semantically similar keywords:
```
POST /keywords-explorer/related-terms
Body: { "keyword": "seed keyword", "country": "us", "limit": 100 }
```

Cluster results by topic (group keywords sharing the same parent topic or SERP overlap).

Classify each keyword's intent:
- **Informational** -- how/what/why questions, guides, educational content
- **Transactional** -- near me, cost, buy, hire, service, pricing queries

**Rate limit:** Max 60 requests/min. **Budget cap:** 15 API calls per research run.

**If neither Ahrefs MCP nor AHREFS_API_KEY is available**, skip this step and note "Ahrefs data unavailable -- no MCP server or API key configured" in the artifact. Continue with Firecrawl+Exa only.

### Step 2: Audience Research (Firecrawl + Exa)

Use `exa.js search` to find Reddit threads, forum posts, Quora answers about the industry/problem space:

```bash
exa.js search "[industry] questions problems reddit" --num-results 10
```

```bash
exa.js search "[industry] advice forum" --num-results 10
```

```bash
exa.js search "site:reddit.com [service] experience" --num-results 10
```

Use `firecrawl.js scrape` to extract content from top 5 most relevant results:

```bash
firecrawl.js scrape --url "https://reddit.com/r/relevant-thread"
```

Extract:
- Exact questions people ask
- Pain points in their own words
- Emotional language
- Common objections

Cross-reference with Google's People Also Ask (search for each seed keyword via Exa and extract PAA-style questions):

```bash
exa.js search "[seed keyword] questions people also ask" --num-results 5
```

### Step 3: Content Gap Analysis

For each top keyword cluster, use `exa.js search` to find what currently ranks:

```bash
exa.js search "[keyword]" --num-results 10
```

Use `firecrawl.js scrape` on top 3 ranking pages per cluster to analyze content depth:

```bash
firecrawl.js scrape --url "https://top-ranking-page.com/article"
```

Identify gaps:
- Topics with search demand but weak/missing/outdated content from competitors
- Flag underserved angles -- queries where top results are generic directories (Yelp, WebMD) rather than authoritative guides
- Note city-specific opportunities if geographic focus applies

### Step 4: Competitor Landscape

Use `firecrawl.js map` on each competitor URL to discover their site structure:

```bash
firecrawl.js map --url "https://competitor.com"
```

Use `firecrawl.js scrape` on their key pages (homepage, services, blog, pricing) -- max 5 pages per competitor:

```bash
firecrawl.js scrape --url "https://competitor.com/services"
```

Analyze:
- Positioning/messaging
- Content strategy (blog frequency, topics)
- SEO approach (city pages, programmatic content)

If Ahrefs is available (MCP or API), use Site Explorer organic-keywords to see what keywords competitors rank for:
```
GET /site-explorer/organic-keywords?target=competitor.com&limit=50
```

Identify messaging patterns and gaps -- what positioning angles are unclaimed.

### Step 5: Compile Artifact

Write the output to `.agents/industry-research-{client}.md` where `{client}` is the lowercase client name (e.g., `allcare`).

Use this artifact template:

```markdown
# Industry Research: {Client Name}

*Client: {Client Full Name}*
*Last full refresh: YYYY-MM-DD*

## 1. Keyword Clusters & Intent Map

*Last researched: YYYY-MM-DD*

### Cluster: {Topic Name}
| Keyword | Monthly Volume | Difficulty | Intent | Traffic Potential |
|---------|---------------|------------|--------|-------------------|
| keyword phrase | X,XXX | XX | Informational/Transactional | X,XXX |

**Intent distribution:** X% informational, X% transactional
**Primary opportunities:** Summary of top keyword opportunities

## 2. Questions & Pain Points

*Last researched: YYYY-MM-DD*

### What people ask (from PAA, Reddit, forums)
- "Exact question from audience?" (volume: X,XXX)

### Pain points (exact audience language)
- "Verbatim quote from real person" -- Source (Reddit, forum, etc.)

## 3. Content Gaps & Opportunities

*Last researched: YYYY-MM-DD*

### Underserved angles
- **Gap description:** Why it matters and the opportunity

### What's ranking (and what's weak)
| Query | Top Result | Gap/Opportunity |
|-------|-----------|-----------------|
| search query | Current top result | What's missing or weak |

## 4. Competitor Landscape

*Last researched: YYYY-MM-DD*

### Who ranks for our keywords
| Competitor | Ranks For | Positioning | Content Strategy |
|-----------|-----------|-------------|------------------|
| Competitor name | Key keywords | How they position | Blog, city pages, etc. |

### Messaging patterns
- Competitor: "Their messaging angle" -- framing type
- **Gap:** Unclaimed positioning angle
```

**Target artifact size:** 3,000-5,000 words. Synthesize and distill -- do not dump raw scraped content.

Each section has its own `Last researched:` timestamp so consuming skills can verify recency.

---

## Tips

- Focus on intent, not just volume -- a 500-volume transactional keyword outperforms a 5,000-volume informational one for conversions
- Capture exact audience language -- "my mom can barely get to the doctor" is more valuable than "transportation barriers to healthcare access"
- Budget API calls carefully -- 15 Ahrefs calls per run, scrape selectively (use `firecrawl.js map` before `scrape`)
- Keep the artifact scannable -- downstream skills read specific sections, not the whole document

---

## Related Skills

- **competitive-intelligence** -- For detailed competitor analysis (company-level deep dives)
- **market-research** -- For market sizing, TAM/SAM/SOM, and industry trends
- **firecrawl-cli** -- For raw Firecrawl scraping (detailed tool documentation)
- **exa-company-research** -- For raw Exa web search on specific companies
- **product-marketing-context** -- For foundational product/service context that feeds into research

ClawHub Writing Marketing+2

M@clawhub-mariokarras-f59a320bef

Industry Research

Skill

When the user wants to conduct industry research, keyword research for a campaign, search demand analysis, intent mapping, audience research, or understand w...

---
name: industry-research
description: "When the user wants to conduct industry research, keyword research for a campaign, search demand analysis, intent mapping, audience research, or understand what people are searching for. Also use when the user mentions 'industry research,' 'keyword clusters,' 'search intent,' 'what are people looking for,' 'audience questions,' 'content gaps,' 'competitor keywords,' 'SERP analysis,' or 'research before campaign.' This skill orchestrates multi-tool deep research using Ahrefs, Firecrawl, and Exa to produce a comprehensive intelligence brief. For raw web scraping, see firecrawl-cli; for competitor analysis, see competitive-intelligence; for market sizing, see market-research."
metadata:
  version: 1.0.0
---

# Industry Research

You conduct deep, intent-driven industry research. The core question is "what are people looking for?" -- not "what are competitors doing?" Keyword intent, search demand, and real audience language are the primary signals. Competitor analysis serves the intent research by finding gaps in what's being served.

## Before Starting

**Check for product marketing context first:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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.

Then determine:

1. **Client name** -- Which client to research for
2. **Industry/market** -- The market category and key services/products
3. **Seed keywords** -- 5-8 starting keyword phrases reflecting core services
4. **Competitor URLs** -- 3-5 known competitor websites to analyze
5. **Geographic focus** -- Target region for keyword data (default: US)

If dispatched via cron or orchestrator with a specific client name, use the product-marketing-context for that client to derive seed keywords and competitors automatically.

---

## Workflow

### Step 1: Keyword Research (Ahrefs)

Use Ahrefs to gather keyword data. Try the Ahrefs MCP server first (if available via mcporter or MCP tools list). If MCP is not available, fall back to the Ahrefs REST API at `https://api.ahrefs.com/v3` with `Authorization: Bearer $AHREFS_API_KEY`.

Regardless of access method, gather data from these endpoints/capabilities:

**Keywords Explorer overview** -- seed keywords (batch up to 10 per request) for volume, difficulty, traffic potential:
```
POST /keywords-explorer/overview
Body: { "keywords": ["seed1", "seed2", ...], "country": "us" }
```

**Keywords Explorer matching terms** -- for each seed keyword, find related keywords (limit: 100 results per seed):
```
POST /keywords-explorer/matching-terms
Body: { "keyword": "seed keyword", "country": "us", "limit": 100 }
```

**Keywords Explorer related terms** -- semantically similar keywords:
```
POST /keywords-explorer/related-terms
Body: { "keyword": "seed keyword", "country": "us", "limit": 100 }
```

Cluster results by topic (group keywords sharing the same parent topic or SERP overlap).

Classify each keyword's intent:
- **Informational** -- how/what/why questions, guides, educational content
- **Transactional** -- near me, cost, buy, hire, service, pricing queries

**Rate limit:** Max 60 requests/min. **Budget cap:** 15 API calls per research run.

**If neither Ahrefs MCP nor AHREFS_API_KEY is available**, skip this step and note "Ahrefs data unavailable -- no MCP server or API key configured" in the artifact. Continue with Firecrawl+Exa only.

### Step 2: Audience Research (Firecrawl + Exa)

Use `exa.js search` to find Reddit threads, forum posts, Quora answers about the industry/problem space:

```bash
exa.js search "[industry] questions problems reddit" --num-results 10
```

```bash
exa.js search "[industry] advice forum" --num-results 10
```

```bash
exa.js search "site:reddit.com [service] experience" --num-results 10
```

Use `firecrawl.js scrape` to extract content from top 5 most relevant results:

```bash
firecrawl.js scrape --url "https://reddit.com/r/relevant-thread"
```

Extract:
- Exact questions people ask
- Pain points in their own words
- Emotional language
- Common objections

Cross-reference with Google's People Also Ask (search for each seed keyword via Exa and extract PAA-style questions):

```bash
exa.js search "[seed keyword] questions people also ask" --num-results 5
```

### Step 3: Content Gap Analysis

For each top keyword cluster, use `exa.js search` to find what currently ranks:

```bash
exa.js search "[keyword]" --num-results 10
```

Use `firecrawl.js scrape` on top 3 ranking pages per cluster to analyze content depth:

```bash
firecrawl.js scrape --url "https://top-ranking-page.com/article"
```

Identify gaps:
- Topics with search demand but weak/missing/outdated content from competitors
- Flag underserved angles -- queries where top results are generic directories (Yelp, WebMD) rather than authoritative guides
- Note city-specific opportunities if geographic focus applies

### Step 4: Competitor Landscape

Use `firecrawl.js map` on each competitor URL to discover their site structure:

```bash
firecrawl.js map --url "https://competitor.com"
```

Use `firecrawl.js scrape` on their key pages (homepage, services, blog, pricing) -- max 5 pages per competitor:

```bash
firecrawl.js scrape --url "https://competitor.com/services"
```

Analyze:
- Positioning/messaging
- Content strategy (blog frequency, topics)
- SEO approach (city pages, programmatic content)

If Ahrefs is available (MCP or API), use Site Explorer organic-keywords to see what keywords competitors rank for:
```
GET /site-explorer/organic-keywords?target=competitor.com&limit=50
```

Identify messaging patterns and gaps -- what positioning angles are unclaimed.

### Step 5: Compile Artifact

Write the output to `.agents/industry-research-{client}.md` where `{client}` is the lowercase client name (e.g., `allcare`).

Use this artifact template:

```markdown
# Industry Research: {Client Name}

*Client: {Client Full Name}*
*Last full refresh: YYYY-MM-DD*

## 1. Keyword Clusters & Intent Map

*Last researched: YYYY-MM-DD*

### Cluster: {Topic Name}
| Keyword | Monthly Volume | Difficulty | Intent | Traffic Potential |
|---------|---------------|------------|--------|-------------------|
| keyword phrase | X,XXX | XX | Informational/Transactional | X,XXX |

**Intent distribution:** X% informational, X% transactional
**Primary opportunities:** Summary of top keyword opportunities

## 2. Questions & Pain Points

*Last researched: YYYY-MM-DD*

### What people ask (from PAA, Reddit, forums)
- "Exact question from audience?" (volume: X,XXX)

### Pain points (exact audience language)
- "Verbatim quote from real person" -- Source (Reddit, forum, etc.)

## 3. Content Gaps & Opportunities

*Last researched: YYYY-MM-DD*

### Underserved angles
- **Gap description:** Why it matters and the opportunity

### What's ranking (and what's weak)
| Query | Top Result | Gap/Opportunity |
|-------|-----------|-----------------|
| search query | Current top result | What's missing or weak |

## 4. Competitor Landscape

*Last researched: YYYY-MM-DD*

### Who ranks for our keywords
| Competitor | Ranks For | Positioning | Content Strategy |
|-----------|-----------|-------------|------------------|
| Competitor name | Key keywords | How they position | Blog, city pages, etc. |

### Messaging patterns
- Competitor: "Their messaging angle" -- framing type
- **Gap:** Unclaimed positioning angle
```

**Target artifact size:** 3,000-5,000 words. Synthesize and distill -- do not dump raw scraped content.

Each section has its own `Last researched:` timestamp so consuming skills can verify recency.

---

## Tips

- Focus on intent, not just volume -- a 500-volume transactional keyword outperforms a 5,000-volume informational one for conversions
- Capture exact audience language -- "my mom can barely get to the doctor" is more valuable than "transportation barriers to healthcare access"
- Budget API calls carefully -- 15 Ahrefs calls per run, scrape selectively (use `firecrawl.js map` before `scrape`)
- Keep the artifact scannable -- downstream skills read specific sections, not the whole document

---

## Related Skills

- **competitive-intelligence** -- For detailed competitor analysis (company-level deep dives)
- **market-research** -- For market sizing, TAM/SAM/SOM, and industry trends
- **firecrawl-cli** -- For raw Firecrawl scraping (detailed tool documentation)
- **exa-company-research** -- For raw Exa web search on specific companies
- **product-marketing-context** -- For foundational product/service context that feeds into research

ClawHub Writing Marketing+2

M@clawhub-mariokarras-f59a320bef

Video Ad Creation

Skill

When the user wants to create video advertisements using Remotion. Also use when the user mentions 'video ad,' 'create ad video,' 'ad creative video,' 'promo...

---
name: video-ad-creation
description: "When the user wants to create video advertisements using Remotion. Also use when the user mentions 'video ad,' 'create ad video,' 'ad creative video,' 'promotional video,' 'product video ad,' or 'marketing video.' Guides creation of standard ad format compositions (15s, 30s, 60s) with scene-based storytelling structure. For project setup and core Remotion APIs, see remotion-best-practices. For social media video formats, see social-video-content."
metadata:
  version: 1.0.0
---

# Video Ad Creation

You help users create video advertisements using React and Remotion. Your goal is to produce ad compositions in standard durations (15s, 30s, 60s) with compelling scene-based storytelling -- hook, value proposition, and call-to-action -- optimized for digital advertising platforms.

## Before Starting

**Check for product marketing context first:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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.

Understand what the user needs (ask if not provided):

1. **Ad duration** -- 15s, 30s, or 60s
2. **Product or service** -- what is being advertised
3. **Key message and CTA** -- the main value proposition and desired action
4. **Brand assets** -- logo, colors, fonts
5. **Target platform** -- web, social, TV, or pre-roll

## Workflow

### Step 1: Choose Ad Format

Present the three standard ad durations:

| Duration | Frames (60fps) | Scenes | Best For |
|----------|----------------|--------|----------|
| 15s | 900 | 3 | Social ads, bumper ads, retargeting |
| 30s | 1800 | 4 | Standard digital ads, pre-roll |
| 60s | 3600 | 5 | Brand storytelling, product demos, explainers |

Default resolution: **1920x1080** (landscape). Default FPS: **60**.

For detailed format specifications and scene timing breakdowns, read `references/formats.md`.

### Step 2: Plan Scene Structure

Each ad duration has a recommended scene structure:

**15s ad** (3 scenes):
- **Hook** (3s / 180 frames): Grab attention immediately
- **Value Prop** (9s / 540 frames): Showcase the product or key benefit
- **CTA** (3s / 180 frames): Clear call-to-action with brand

**30s ad** (4 scenes):
- **Hook** (5s / 300 frames): Attention-grabbing opener
- **Problem** (7s / 420 frames): Present the pain point
- **Solution** (13s / 780 frames): Show how the product solves it
- **CTA** (5s / 300 frames): Call-to-action with brand reinforcement

**60s ad** (5 scenes):
- **Hook** (5s / 300 frames): Bold opener to stop the scroll
- **Problem** (10s / 600 frames): Deep dive into the pain point
- **Solution** (20s / 1200 frames): Product demonstration and benefits
- **Social Proof** (15s / 900 frames): Testimonials, stats, trust signals
- **CTA** (10s / 600 frames): Strong call-to-action with brand outro

### Step 3: Register Composition

Register the ad as a Composition in `src/Root.tsx`:

```tsx
import { Composition } from "remotion";
import { AdVideo } from "./AdVideo";

export const RemotionRoot: React.FC = () => {
  return (
    <Composition
      id="VideoAd15s"
      component={AdVideo}
      durationInFrames={900}
      fps={60}
      width={1920}
      height={1080}
      defaultProps={{
        headline: "Your Product",
        cta: "Learn More",
        brandColor: "#0066FF",
      }}
    />
  );
};
```

For 30s ads, use `durationInFrames={1800}`. For 60s ads, use `durationInFrames={3600}`.

### Step 4: Build Scene Components

Each scene is a separate React component composed with `<Sequence>` for timeline positioning:

```tsx
import { useCurrentFrame, useVideoConfig, interpolate, spring, AbsoluteFill, Sequence } from "remotion";

const HookScene: React.FC<{ headline: string }> = ({ headline }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  const scale = spring({ frame, fps, config: { damping: 12, stiffness: 100 } });
  const opacity = interpolate(frame, [0, 20], [0, 1], { extrapolateRight: "clamp" });

  return (
    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center", backgroundColor: "#0066FF" }}>
      <h1 style={{ opacity, transform: `scale(scale)`, fontSize: 72, color: "white" }}>
        {headline}
      </h1>
    </AbsoluteFill>
  );
};
```

Compose scenes on the ad timeline:

```tsx
export const AdVideo: React.FC<{ headline: string; cta: string; brandColor: string }> = (props) => {
  return (
    <AbsoluteFill>
      <Sequence durationInFrames={180}>
        <HookScene headline={props.headline} />
      </Sequence>
      <Sequence from={180} durationInFrames={540}>
        <ValuePropScene />
      </Sequence>
      <Sequence from={720} durationInFrames={180}>
        <CTAScene cta={props.cta} brandColor={props.brandColor} />
      </Sequence>
    </AbsoluteFill>
  );
};
```

Each `<Sequence>` resets `useCurrentFrame()` to 0 for its children, so each scene animates independently.

### Step 5: Render

Render the ad locally:

```bash
npx remotion render src/index.ts VideoAd15s out/ad-15s.mp4
```

For different durations, register additional compositions and render each:

```bash
npx remotion render src/index.ts VideoAd30s out/ad-30s.mp4
npx remotion render src/index.ts VideoAd60s out/ad-60s.mp4
```

Preview in browser before rendering:

```bash
npx remotion preview src/index.ts
```

See `tools/integrations/remotion.md` for the full CLI command reference.

## Output Format

Deliver a working ad composition with:

1. **`src/Root.tsx`** -- Composition registration with correct duration, fps, and dimensions
2. **Scene components** -- One `.tsx` file per scene (HookScene, ValuePropScene, CTAScene, etc.)
3. **Render command** -- The exact `npx remotion render` command for the chosen duration
4. **Preview command** -- `npx remotion preview src/index.ts` for browser preview

## Related Skills

- **remotion-best-practices**: Project setup, core APIs, animation patterns, rendering pipeline
- **social-video-content**: Social platform video formats (vertical, square, landscape)

FILE:references/formats.md
# Ad Format Specifications

Detailed format specs for video advertisements. All durations use **60fps** and **1920x1080** (landscape) as defaults.

## Quick Reference

| Duration | Frames | Scenes | Use Case |
|----------|--------|--------|----------|
| 15s | 900 | 3 | Social ads, bumper ads, retargeting |
| 30s | 1800 | 4 | Standard digital ads, pre-roll |
| 60s | 3600 | 5 | Brand storytelling, product demos, explainers |

**Frame calculation:** `duration_seconds * fps = frames` (e.g., 15 * 60 = 900)

## 15-Second Ad Template

Total: **900 frames** at 60fps

| Scene | Time | Frames | Purpose | Recommended Animations |
|-------|------|--------|---------|----------------------|
| Hook | 0-3s | 0-179 | Grab attention instantly | Bold text entrance with `spring()`, fast scale-up |
| Value Prop | 3-12s | 180-719 | Product showcase, key benefit | Image/text fade-in with `interpolate()`, slide transitions |
| CTA | 12-15s | 720-899 | Call-to-action, brand logo | Button bounce with `spring()`, logo fade-in |

**Best practices for 15s:**
- Front-load the hook -- viewers decide in the first second
- One message only -- no time for multiple value props
- Large text (64px+) -- many viewers watch on mobile
- Brand visible throughout (logo watermark or brand color)

### Composition Registration

```tsx
<Composition
  id="VideoAd15s"
  component={AdVideo}
  durationInFrames={900}
  fps={60}
  width={1920}
  height={1080}
  defaultProps={{ headline: "Your Product", cta: "Learn More", brandColor: "#0066FF" }}
/>
```

## 30-Second Ad Template

Total: **1800 frames** at 60fps

| Scene | Time | Frames | Purpose | Recommended Animations |
|-------|------|--------|---------|----------------------|
| Hook | 0-5s | 0-299 | Attention-grabbing opener | Bold text `spring()`, background movement |
| Problem | 5-12s | 300-719 | Present the pain point | Text fade-in, icon animations |
| Solution | 12-25s | 720-1499 | Product solves the problem | Product image scale, feature callouts |
| CTA | 25-30s | 1500-1799 | Call-to-action, brand outro | Button animation, logo + URL reveal |

**Best practices for 30s:**
- Problem-solution structure works best at this length
- Show the product in action during the Solution scene
- End card should include logo, CTA button, and website URL
- Pacing: quick hook, deliberate middle, punchy close

### Composition Registration

```tsx
<Composition
  id="VideoAd30s"
  component={AdVideo}
  durationInFrames={1800}
  fps={60}
  width={1920}
  height={1080}
  defaultProps={{ headline: "Solve Your Problem", cta: "Get Started", brandColor: "#0066FF" }}
/>
```

## 60-Second Ad Template

Total: **3600 frames** at 60fps

| Scene | Time | Frames | Purpose | Recommended Animations |
|-------|------|--------|---------|----------------------|
| Hook | 0-5s | 0-299 | Bold opener to stop the scroll | Large text `spring()`, dramatic reveal |
| Problem | 5-15s | 300-899 | Deep dive into pain point | Animated stats, icon sequences |
| Solution | 15-35s | 900-2099 | Product demo and benefits | Product walkthrough, feature highlights |
| Social Proof | 35-50s | 2100-2999 | Testimonials, stats, trust | Quote fade-ins, number counters |
| CTA | 50-60s | 3000-3599 | Strong call-to-action, brand outro | Button bounce, logo + URL + offer |

**Best practices for 60s:**
- Full storytelling arc -- enough time to build emotional connection
- Social proof scene builds credibility before the ask
- Can include multiple product features in the Solution scene
- End card can be more elaborate (offer details, multiple CTAs)

### Composition Registration

```tsx
<Composition
  id="VideoAd60s"
  component={AdVideo}
  durationInFrames={3600}
  fps={60}
  width={1920}
  height={1080}
  defaultProps={{ headline: "The Full Story", cta: "Start Free Trial", brandColor: "#0066FF" }}
/>
```

## Resolution Specs

| Format | Resolution | Aspect Ratio | Use Case |
|--------|-----------|--------------|----------|
| Standard landscape | 1920x1080 | 16:9 | Web ads, YouTube pre-roll, TV |
| Square variant | 1080x1080 | 1:1 | Social feed ads (Instagram, Facebook, LinkedIn) |
| Vertical variant | 1080x1920 | 9:16 | Story/reel ads (Instagram, TikTok, Snapchat) |

For social-specific format details, see the **social-video-content** skill.

## Common Ad Patterns

### Text Overlay on Background

Layer text over a full-bleed background using `AbsoluteFill`:

```tsx
<AbsoluteFill>
  <AbsoluteFill style={{ backgroundColor: brandColor }} />
  <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
    <h1 style={{ fontSize: 72, color: "white" }}>{headline}</h1>
  </AbsoluteFill>
</AbsoluteFill>
```

### Product Showcase

Animate a product image with scale and opacity:

```tsx
const scale = interpolate(frame, [0, 30], [0.8, 1], { extrapolateRight: "clamp" });
const opacity = interpolate(frame, [0, 20], [0, 1], { extrapolateRight: "clamp" });

<Img src={productImage} style={{ transform: `scale(scale)`, opacity }} />
```

### Price/Offer Callout

Use `spring()` for a bounce-in effect on price or discount text:

```tsx
const scale = spring({ frame, fps, config: { damping: 8, stiffness: 200 } });

<div style={{ transform: `scale(scale)`, fontSize: 64, fontWeight: "bold" }}>
  50% OFF
</div>
```

### End Card

Brand logo, CTA button, and website URL composed together:

```tsx
const logoOpacity = interpolate(frame, [0, 15], [0, 1], { extrapolateRight: "clamp" });
const buttonScale = spring({ frame: frame - 10, fps, config: { damping: 10 } });

<AbsoluteFill style={{ justifyContent: "center", alignItems: "center", gap: 40 }}>
  <Img src={logo} style={{ opacity: logoOpacity, width: 200 }} />
  <div style={{ transform: `scale(Math.max(0, buttonScale))`, padding: "20px 40px", backgroundColor: brandColor, borderRadius: 8 }}>
    <span style={{ fontSize: 36, color: "white" }}>{cta}</span>
  </div>
  <span style={{ opacity: logoOpacity, fontSize: 24, color: "#ccc" }}>www.example.com</span>
</AbsoluteFill>
```

ClawHub Marketing Product+2

M@clawhub-mariokarras-f59a320bef

Social Video Content

Skill

When the user wants to create video content for social media platforms using Remotion. Also use when the user mentions 'social video,' 'video for social,' 's...

---
name: social-video-content
description: "When the user wants to create video content for social media platforms using Remotion. Also use when the user mentions 'social video,' 'video for social,' 'short-form video,' 'reels,' 'TikTok video,' 'YouTube Shorts,' 'Instagram video,' or 'social media clip.' Guides creation of platform-specific compositions in vertical (9:16), square (1:1), and landscape (16:9) formats. For project setup and core Remotion APIs, see remotion-best-practices. For video advertisements, see video-ad-creation."
metadata:
  version: 1.0.0
---

# Social Video Content

You help users create video content optimized for social media platforms using React and Remotion. Your goal is to produce compositions in the right format for each platform -- vertical for Reels/TikTok/Shorts, square for feed posts, landscape for YouTube -- with scroll-stopping hooks and mobile-first design.

## Before Starting

**Check for product marketing context first:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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.

Understand what the user needs (ask if not provided):

1. **Target platform(s)** -- Reels, TikTok, YouTube Shorts, feed post, YouTube, LinkedIn, Twitter/X
2. **Content topic or message** -- what the video communicates
3. **Desired duration** -- typically 15-60s for short-form, up to 120s for landscape
4. **Brand assets** -- logo, colors, fonts
5. **Content style** -- educational, promotional, entertaining, behind-the-scenes

## Workflow

### Step 1: Select Platform Format

Choose the format based on the target platform:

| Format | Aspect Ratio | Resolution | Platforms | Duration Range |
|--------|-------------|------------|-----------|---------------|
| Vertical | 9:16 | 1080x1920 | Reels, TikTok, YouTube Shorts | 15-60s |
| Square | 1:1 | 1080x1080 | Instagram feed, Facebook feed, LinkedIn | 15-60s |
| Landscape | 16:9 | 1920x1080 | YouTube, LinkedIn, Twitter/X | 15-120s |

Default FPS: **60** for all formats.

For detailed platform requirements including max durations, file size limits, and codec recommendations, read `references/platforms.md`.

### Step 2: Plan Content Structure

Social video structure differs from ads -- the hook is everything:

- **Hook** (first 1-3s): Critical for scroll-stopping. Bold text, movement, contrast, or a provocative question. Viewers decide to stay or scroll in the first second.
- **Content** (middle): Key message, demonstrations, information, or entertainment. Keep pacing brisk -- cut or transition every 3-5 seconds.
- **CTA/Outro** (last 2-3s): Follow, subscribe, visit link, or share prompt.

**Vertical-specific considerations:**
- Content is consumed on mobile -- everything must be readable at phone size
- Top and bottom edges may be covered by platform UI (username, caption, buttons)
- Center-weight your composition for the safe zone

### Step 3: Register Composition

Register platform-specific compositions in `src/Root.tsx`:

```tsx
import { Composition } from "remotion";
import { SocialVideo } from "./SocialVideo";

export const RemotionRoot: React.FC = () => {
  return (
    <>
      {/* Vertical (Reels/TikTok/Shorts) */}
      <Composition
        id="ReelsVideo"
        component={SocialVideo}
        durationInFrames={1800}
        fps={60}
        width={1080}
        height={1920}
        defaultProps={{ text: "Hook text here" }}
      />

      {/* Square (Feed post) */}
      <Composition
        id="FeedPost"
        component={SocialVideo}
        durationInFrames={900}
        fps={60}
        width={1080}
        height={1080}
        defaultProps={{ text: "Feed content" }}
      />

      {/* Landscape (YouTube) */}
      <Composition
        id="YouTubeVideo"
        component={SocialVideo}
        durationInFrames={3600}
        fps={60}
        width={1920}
        height={1080}
        defaultProps={{ text: "YouTube content" }}
      />
    </>
  );
};
```

One project can have multiple compositions for multi-platform output. Share scene components but register each format as a separate composition.

### Step 4: Build for Vertical-First

Vertical (9:16) is the dominant social format. Key patterns for mobile-optimized layouts:

```tsx
import { useCurrentFrame, useVideoConfig, interpolate, spring, AbsoluteFill } from "remotion";

const VerticalScene: React.FC<{ text: string }> = ({ text }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  const textScale = spring({ frame, fps, config: { damping: 10, stiffness: 150 } });
  const opacity = interpolate(frame, [0, 15], [0, 1], { extrapolateRight: "clamp" });

  return (
    <AbsoluteFill style={{
      backgroundColor: "#1a1a2e",
      justifyContent: "center",
      alignItems: "center",
      padding: "0 60px",
    }}>
      <h1 style={{
        opacity,
        transform: `scale(textScale)`,
        fontSize: 64,
        color: "white",
        textAlign: "center",
        lineHeight: 1.2,
      }}>
        {text}
      </h1>
    </AbsoluteFill>
  );
};
```

**Vertical layout rules:**
- Stack content vertically in `AbsoluteFill`
- Minimum text size: **48px** for readability on mobile
- Center-weighted composition: keep content in the middle 80% of height
- Full-screen background images or solid colors (no letterboxing)
- Add horizontal padding (40-60px) to keep text off screen edges

### Step 5: Render

Render each platform format as a separate output:

```bash
npx remotion render src/index.ts ReelsVideo out/reels.mp4
npx remotion render src/index.ts FeedPost out/feed-post.mp4
npx remotion render src/index.ts YouTubeVideo out/youtube.mp4
```

Preview in browser:

```bash
npx remotion preview src/index.ts
```

See `tools/integrations/remotion.md` for the full CLI command reference.

## Output Format

Deliver a working social video project with:

1. **`src/Root.tsx`** -- Platform-specific Compositions with correct dimensions, fps, and duration
2. **Scene components** -- Reusable `.tsx` components that adapt to different aspect ratios
3. **Render commands** -- One `npx remotion render` command per platform variant
4. **Preview command** -- `npx remotion preview src/index.ts` for browser preview

## Related Skills

- **remotion-best-practices**: Project setup, core APIs, animation patterns, rendering pipeline
- **video-ad-creation**: Standard ad format compositions (15s/30s/60s) with product showcase templates

FILE:references/platforms.md
# Social Platform Specifications

Detailed platform requirements for social video content. Use this reference when choosing formats, resolutions, and duration limits for each platform.

> **Note:** Platform specs change frequently. Verify current limits on the platform's creator documentation before publishing.

## Platform Quick Reference

| Platform | Aspect Ratio | Resolution | Max Duration | Codec | Max File Size |
|----------|-------------|------------|--------------|-------|---------------|
| Instagram Reels | 9:16 | 1080x1920 | 90s | H.264 | 4GB |
| TikTok | 9:16 | 1080x1920 | 60s (default) | H.264 | 287MB |
| YouTube Shorts | 9:16 | 1080x1920 | 60s | H.264 | 256MB |
| Instagram Feed | 1:1 or 4:5 | 1080x1080 | 60s | H.264 | 4GB |
| YouTube | 16:9 | 1920x1080 | 12hr | H.264 | 256GB |
| LinkedIn | 1:1 or 16:9 | 1080x1080 | 10min | H.264 | 5GB |
| Twitter/X | 16:9 or 1:1 | 1920x1080 | 2min 20s | H.264 | 512MB |

All platforms support H.264 codec. Remotion renders H.264 by default -- no special configuration needed.

## Vertical (9:16) Design Guide

Vertical is the dominant format for short-form social content (Reels, TikTok, YouTube Shorts).

**Safe zone:**
- Top 180px may be covered by status bar, platform header, or notification bar
- Bottom 280px may be covered by caption text, username, like/share buttons
- **Effective content area:** 1080x1460 centered within 1080x1920
- Keep all critical text and visuals within the middle 76% of the height

**Text placement:**
- Center-weight all text (vertically and horizontally)
- Avoid placing text in the top 10% or bottom 15% of the frame
- Left-align body text with 40-60px horizontal padding

**Typography:**
- Minimum text size: **48px** for mobile readability
- Headlines: 56-72px
- Body text: 48-56px
- Use high-contrast colors (white on dark, or dark on light backgrounds)
- Bold weight for hook text -- thin fonts disappear on small screens

**Backgrounds:**
- Full-bleed images or solid colors (never letterbox)
- Dark backgrounds (#1a1a2e, #000000) work well for text-heavy content
- Gradient backgrounds add visual interest without distraction

**Composition example:**

```tsx
<Composition
  id="ReelsVideo"
  component={SocialVideo}
  durationInFrames={1800}  // 30s
  fps={60}
  width={1080}
  height={1920}
  defaultProps={{ text: "Hook text here", bgColor: "#1a1a2e" }}
/>
```

## Square (1:1) Design Guide

Square works universally across all platforms as feed content. It is the safest format for cross-platform distribution.

**Layout:**
- Balanced, centered compositions work best
- Equal visual weight on all sides
- No safe zone issues -- the full frame is visible on all platforms

**Typography:**
- Text can be slightly smaller than vertical: **40px** minimum
- Feed viewing distance is typically closer than full-screen vertical
- Center-align headlines, left-align body text

**Best for:**
- Instagram feed posts
- Facebook feed posts
- LinkedIn feed posts
- Cross-platform content (one render, multiple platforms)

**Composition example:**

```tsx
<Composition
  id="FeedPost"
  component={SocialVideo}
  durationInFrames={900}  // 15s
  fps={60}
  width={1080}
  height={1080}
  defaultProps={{ text: "Feed content", bgColor: "#0a0a1a" }}
/>
```

## Landscape (16:9) Design Guide

Landscape is the native YouTube format and works well on LinkedIn and Twitter/X.

**Layout:**
- Standard web video composition rules apply
- Wider canvas allows side-by-side layouts (text + image)
- Cinematic feel -- good for product demos and explainers

**Typography:**
- Minimum text size: **32px**
- More room for multi-line text and detailed information
- Subtitles: 28-36px at the bottom of the frame

**Best for:**
- YouTube (standard and long-form)
- LinkedIn native video
- Twitter/X timeline video
- Embedded web video

**Composition example:**

```tsx
<Composition
  id="YouTubeVideo"
  component={SocialVideo}
  durationInFrames={3600}  // 60s
  fps={60}
  width={1920}
  height={1080}
  defaultProps={{ text: "YouTube content", bgColor: "#0f0f1a" }}
/>
```

## Render Commands

Render each platform format as a separate file:

```bash
# Vertical (Reels, TikTok, YouTube Shorts)
npx remotion render src/index.ts ReelsVideo out/reels.mp4

# Square (Instagram feed, Facebook, LinkedIn)
npx remotion render src/index.ts FeedPost out/feed-post.mp4

# Landscape (YouTube, LinkedIn, Twitter/X)
npx remotion render src/index.ts YouTubeVideo out/youtube.mp4
```

## Multi-Platform Strategy

Create one Remotion project with multiple Compositions to target every platform from a single codebase:

1. **Shared scene components** -- Write content scenes (hook, main content, CTA) as reusable React components
2. **Layout wrappers** -- Create format-specific layout components that adapt padding, text size, and positioning
3. **Multiple Compositions** -- Register one Composition per platform format in Root.tsx, each using the same scene components but with different dimensions
4. **Batch render** -- Render all formats with separate commands:

```bash
npx remotion render src/index.ts ReelsVideo out/reels.mp4
npx remotion render src/index.ts FeedPost out/feed-post.mp4
npx remotion render src/index.ts YouTubeVideo out/youtube.mp4
```

**Adaptive text size pattern:**

```tsx
import { useVideoConfig } from "remotion";

const AdaptiveText: React.FC<{ children: string }> = ({ children }) => {
  const { width } = useVideoConfig();
  // Scale text based on composition width
  const fontSize = width <= 1080 ? 56 : 42;

  return <h1 style={{ fontSize, color: "white", textAlign: "center" }}>{children}</h1>;
};
```

This approach lets one team produce content for all platforms without duplicating creative work.

ClawHub Marketing Design+2

M@clawhub-mariokarras-f59a320bef

Remotion Best Practices

Skill

When the user wants to create videos programmatically with React using Remotion. Also use when the user mentions 'create video,' 'Remotion,' 'React video,' '...

---
name: remotion-best-practices
description: "When the user wants to create videos programmatically with React using Remotion. Also use when the user mentions 'create video,' 'Remotion,' 'React video,' 'video composition,' 'programmatic video,' or 'render video.' Covers project setup, composition structure, animation patterns, and rendering pipeline. Does not cover ad-specific formats (see video-ad-creation) or social media formats (see social-video-content)."
metadata:
  version: 1.0.0
---

# Remotion Best Practices

You help users create videos programmatically using React and Remotion. Your goal is to scaffold projects, write compositions, build animated scene components, and render final video output -- all following Remotion v4 conventions and best practices.

## Before Starting

**Check for product marketing context first:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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.

Understand what the user needs (ask if not provided):

1. **What video to create** -- subject, purpose, and visual style
2. **Target duration and dimensions** -- e.g., 15 seconds at 1920x1080
3. **New or existing project** -- whether to scaffold fresh or add to an existing Remotion project

## Workflow

### Step 1: Set Up Project

Check if a Remotion project already exists:
- Look for `package.json` with `@remotion/core` in `dependencies` or `devDependencies`
- If found: skip scaffolding and add a new composition to the existing `src/Root.tsx`
- If not found: scaffold a new project:

```bash
npx create-video@latest my-video
```

After scaffolding, verify all `@remotion/*` packages are on the same version:

```bash
npm ls | grep remotion
```

For detailed setup configuration, read `references/setup.md`.

### Step 2: Define Composition in Root.tsx

Register your video as a Composition in `src/Root.tsx`:

```tsx
import { Composition } from "remotion";
import { MyScene } from "./MyScene";

export const RemotionRoot: React.FC = () => {
  return (
    <Composition
      id="MyVideo"
      component={MyScene}
      durationInFrames={900}  // 15s at 60fps
      fps={60}
      width={1920}
      height={1080}
      defaultProps={{ title: "My Video" }}
    />
  );
};
```

Key points:
- Use `fps={60}` as the project default (60fps for smooth animation)
- Use PascalCase for composition IDs (e.g., `MyVideo`, `ProductDemo`)
- Calculate `durationInFrames` as `seconds * fps` (15s at 60fps = 900 frames)

### Step 3: Build Scene Components

Use `AbsoluteFill` as the root layout container. Use `useCurrentFrame()` and `useVideoConfig()` for animation state. Use `<Sequence>` for timeline positioning.

Minimal animated component:

```tsx
import { useCurrentFrame, useVideoConfig, interpolate, AbsoluteFill } from "remotion";

export const MyScene: React.FC<{ title: string }> = ({ title }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();
  const opacity = interpolate(frame, [0, 30], [0, 1], {
    extrapolateRight: "clamp",
  });

  return (
    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
      <h1 style={{ opacity, fontSize: 80, color: "white" }}>{title}</h1>
    </AbsoluteFill>
  );
};
```

For physics-based animation, use `spring()`:

```tsx
import { spring } from "remotion";

const scale = spring({
  frame,
  fps,
  config: { damping: 12, stiffness: 100 },
});
```

For detailed animation patterns including `spring()` configuration, multi-step interpolation, and easing functions, read `references/animations.md`.

### Step 4: Add Multi-Scene Timeline

Use `<Sequence>` to compose multiple scenes on a timeline:

```tsx
import { Sequence, AbsoluteFill } from "remotion";

export const MyVideo: React.FC = () => {
  return (
    <AbsoluteFill style={{ backgroundColor: "black" }}>
      <Sequence durationInFrames={180}>
        <IntroScene />
      </Sequence>
      <Sequence from={180} durationInFrames={600}>
        <MainContent />
      </Sequence>
      <Sequence from={780} durationInFrames={120}>
        <OutroScene />
      </Sequence>
    </AbsoluteFill>
  );
};
```

Each `<Sequence>` resets `useCurrentFrame()` to 0 for its children, so each scene animates independently. The `from` prop sets when the scene starts on the parent timeline.

### Step 5: Render Video

**Preview in browser:**

```bash
npx remotion preview src/index.ts
```

**Render locally:**

```bash
npx remotion render src/index.ts MyVideo out/video.mp4
```

**Render with custom props:**

```bash
npx remotion render src/index.ts MyVideo out/video.mp4 --props='{"title":"Hello"}'
```

For output formats, quality settings, and advanced render options, read `references/rendering.md`.

For AWS Lambda rendering at scale, read `references/lambda.md`.

See `tools/integrations/remotion.md` for the full CLI command reference.

## Key Rules

1. **Version pinning** -- All `@remotion/*` packages must be the same version. Never update one independently. See `tools/integrations/remotion.md` for details.
2. **Deterministic rendering** -- Never use `Math.random()`. Use `random('seed')` from the `remotion` package for deterministic random values.
3. **FPS from config** -- Always get fps from `useVideoConfig()`. Never hardcode fps values in animation calculations.
4. **Clamp interpolation** -- Use `interpolate()` with `extrapolateRight: "clamp"` to prevent values exceeding the target range.
5. **Default 60fps** -- All compositions use `fps={60}` unless the user specifies otherwise.

## Output Format

Deliver a working Remotion project with:

1. **`src/Root.tsx`** -- Composition registration with correct dimensions, fps, and duration
2. **Scene components** -- One `.tsx` file per scene with animations
3. **Render command** -- The exact `npx remotion render` command to produce the final video
4. **Preview command** -- `npx remotion preview src/index.ts` for browser preview

If adding to an existing project, deliver the new composition entry for Root.tsx and the new scene component files.

## Related Skills

- **video-ad-creation**: Standard ad format compositions (15s/30s/60s) with product showcase templates
- **social-video-content**: Social platform video formats (9:16 vertical, 1:1 square, 16:9 landscape)

FILE:references/animations.md
# Remotion Animation Patterns

Detailed animation reference covering interpolation, spring physics, easing, and transition effects.

## interpolate()

Maps a frame number to an animated value. The core animation primitive in Remotion.

### Basic Usage

```tsx
import { useCurrentFrame, interpolate } from "remotion";

const frame = useCurrentFrame();

// Fade in over frames 0-30
const opacity = interpolate(frame, [0, 30], [0, 1], {
  extrapolateRight: "clamp",
});
```

### Parameters

```tsx
interpolate(
  input,        // Current value (usually frame number)
  inputRange,   // Array of input breakpoints [0, 30, 60]
  outputRange,  // Array of output values [0, 1, 0]
  options       // Optional configuration
)
```

### Extrapolation Options

Control what happens when the input is outside the defined range:

| Option | Value | Behavior |
|--------|-------|----------|
| `extrapolateLeft` | `"clamp"` | Clamp to first output value |
| `extrapolateLeft` | `"extend"` | Continue the curve (default) |
| `extrapolateLeft` | `"identity"` | Return input as-is |
| `extrapolateLeft` | `"wrap"` | Wrap around the range |
| `extrapolateRight` | `"clamp"` | Clamp to last output value |
| `extrapolateRight` | `"extend"` | Continue the curve (default) |
| `extrapolateRight` | `"identity"` | Return input as-is |
| `extrapolateRight` | `"wrap"` | Wrap around the range |

**Best practice:** Always use `extrapolateRight: "clamp"` unless you specifically want values to exceed the output range.

### Multi-Step Interpolation

Use multiple breakpoints for complex animations:

```tsx
// Fade in, hold, then fade out
const opacity = interpolate(
  frame,
  [0, 30, 60, 90],   // Four breakpoints
  [0, 1, 1, 0],      // Corresponding values
  { extrapolateRight: "clamp" }
);

// Slide in from left, hold, slide out to right
const translateX = interpolate(
  frame,
  [0, 30, 120, 150],
  [-500, 0, 0, 500],
  { extrapolateRight: "clamp" }
);
```

### Using with Easing

Apply easing functions for non-linear motion:

```tsx
import { interpolate, Easing } from "remotion";

const opacity = interpolate(frame, [0, 30], [0, 1], {
  easing: Easing.bezier(0.25, 0.1, 0.25, 1),
  extrapolateRight: "clamp",
});
```

## spring()

Physics-based animation for natural motion. Ideal for scale, position, and bounce effects.

### Basic Usage

```tsx
import { spring, useCurrentFrame, useVideoConfig } from "remotion";

const frame = useCurrentFrame();
const { fps } = useVideoConfig();

const scale = spring({
  frame,
  fps,
  config: {
    damping: 12,
    stiffness: 100,
    mass: 1,
  },
});
```

**Always** get `fps` from `useVideoConfig()` -- never hardcode it.

### Configuration Options

| Option | Default | Effect |
|--------|---------|--------|
| `damping` | 10 | Higher = less oscillation. Range: 0-100 |
| `stiffness` | 100 | Higher = faster snap. Range: 0-500 |
| `mass` | 1 | Higher = heavier, slower. Range: 0.1-10 |
| `overshootClamping` | false | If true, stops at target without overshoot |

### Common Presets

```tsx
// Snappy entrance (no bounce)
spring({ frame, fps, config: { damping: 20, stiffness: 200, overshootClamping: true } });

// Bouncy entrance
spring({ frame, fps, config: { damping: 8, stiffness: 150, mass: 0.8 } });

// Slow, heavy entrance
spring({ frame, fps, config: { damping: 15, stiffness: 80, mass: 2 } });

// Gentle settle
spring({ frame, fps, config: { damping: 12, stiffness: 100, mass: 1 } });
```

### Delayed Spring

Use the `delay` parameter to start the spring at a specific frame:

```tsx
const scale = spring({
  frame,
  fps,
  delay: 30,  // Start spring at frame 30
  config: { damping: 12, stiffness: 100 },
});
```

### Duration Override

Override physics simulation with a fixed duration:

```tsx
const value = spring({
  frame,
  fps,
  durationInFrames: 60,  // Complete in exactly 60 frames
  config: { damping: 12, stiffness: 100 },
});
```

## Easing Functions

Import easing functions from `remotion` for use with `interpolate()`:

```tsx
import { Easing } from "remotion";
```

### Common Easing Presets

| Function | Effect |
|----------|--------|
| `Easing.linear` | No easing (default) |
| `Easing.ease` | Smooth ease-in-out |
| `Easing.in(Easing.ease)` | Ease in only |
| `Easing.out(Easing.ease)` | Ease out only |
| `Easing.inOut(Easing.ease)` | Ease in and out |
| `Easing.bezier(x1, y1, x2, y2)` | Custom cubic bezier |

### Custom Bezier Curves

```tsx
// CSS ease equivalent
const easeCSS = Easing.bezier(0.25, 0.1, 0.25, 1);

// Fast start, slow end
const easeOut = Easing.bezier(0, 0, 0.58, 1);

// Slow start, fast end
const easeIn = Easing.bezier(0.42, 0, 1, 1);

// Use with interpolate
const opacity = interpolate(frame, [0, 30], [0, 1], {
  easing: easeCSS,
  extrapolateRight: "clamp",
});
```

## Image Animation Patterns

### Scale + Fade Entrance

```tsx
const opacity = interpolate(frame, [0, 20], [0, 1], { extrapolateRight: "clamp" });
const scale = spring({ frame, fps, config: { damping: 12, stiffness: 100 } });

<img
  src={imageUrl}
  style={{
    opacity,
    transform: `scale(scale)`,
    width: 400,
    height: 300,
  }}
/>
```

### Slide In from Side

```tsx
const translateX = interpolate(frame, [0, 30], [-600, 0], {
  easing: Easing.out(Easing.ease),
  extrapolateRight: "clamp",
});

<div style={{ transform: `translateX(translateXpx)` }}>
  <img src={imageUrl} style={{ width: "100%" }} />
</div>
```

### Ken Burns Effect (Slow Zoom + Pan)

```tsx
const scale = interpolate(frame, [0, 300], [1, 1.3], { extrapolateRight: "clamp" });
const translateX = interpolate(frame, [0, 300], [0, -50], { extrapolateRight: "clamp" });

<div style={{ overflow: "hidden", width: 1920, height: 1080 }}>
  <img
    src={imageUrl}
    style={{
      transform: `scale(scale) translateX(translateXpx)`,
      width: "100%",
      height: "100%",
      objectFit: "cover",
    }}
  />
</div>
```

## Text Animation Patterns

### Character-by-Character Reveal

```tsx
const text = "Hello World";
const charsShown = interpolate(frame, [0, 60], [0, text.length], {
  extrapolateRight: "clamp",
});

<h1 style={{ fontSize: 80, color: "white" }}>
  {text.slice(0, Math.round(charsShown))}
</h1>
```

### Typewriter with Cursor

```tsx
const text = "Welcome to Remotion";
const charsShown = Math.round(
  interpolate(frame, [0, 90], [0, text.length], { extrapolateRight: "clamp" })
);
const cursorVisible = frame % 30 < 15; // Blink every 0.5s at 60fps

<h1 style={{ fontSize: 60, color: "white", fontFamily: "monospace" }}>
  {text.slice(0, charsShown)}
  <span style={{ opacity: cursorVisible ? 1 : 0 }}>|</span>
</h1>
```

Note: The cursor blink uses a frame-based modulo, which is deterministic (safe for Remotion rendering).

### Staggered Word Entrance

```tsx
const words = ["Build", "Ship", "Grow"];

{words.map((word, i) => {
  const delay = i * 15; // 15 frames between each word
  const wordOpacity = interpolate(frame, [delay, delay + 20], [0, 1], {
    extrapolateLeft: "clamp",
    extrapolateRight: "clamp",
  });
  const wordY = interpolate(frame, [delay, delay + 20], [30, 0], {
    extrapolateLeft: "clamp",
    extrapolateRight: "clamp",
  });

  return (
    <span
      key={word}
      style={{
        opacity: wordOpacity,
        transform: `translateY(wordYpx)`,
        display: "inline-block",
        marginRight: 20,
        fontSize: 80,
        color: "white",
      }}
    >
      {word}
    </span>
  );
})}
```

## Deterministic Randomness

**Never use `Math.random()` in Remotion.** It produces different values on each render, breaking deterministic output.

Use the `random()` function from the `remotion` package:

```tsx
import { random } from "remotion";

// Deterministic random value seeded by string
const rotation = random("particle-rotation") * 360;
const xOffset = random("particle-x") * 1920;

// Use index for unique per-item values
{items.map((item, i) => {
  const randomDelay = random(`delay-i`) * 30;
  const randomScale = 0.5 + random(`scale-i`) * 0.5;
  // ...
})}
```

`random('seed')` returns a number between 0 and 1, deterministic for the same seed string.

## Advanced: TransitionSeries

The `@remotion/transitions` package provides smooth transitions between scenes.

### Installation

```bash
npm install @remotion/transitions
```

Ensure the version matches your other `@remotion/*` packages.

### Fade Transition

```tsx
import { TransitionSeries } from "@remotion/transitions";
import { fade } from "@remotion/transitions/fade";
import { linearTiming } from "@remotion/transitions";

export const MyVideo: React.FC = () => {
  return (
    <TransitionSeries>
      <TransitionSeries.Sequence durationInFrames={300}>
        <SceneA />
      </TransitionSeries.Sequence>
      <TransitionSeries.Transition
        presentation={fade()}
        timing={linearTiming({ durationInFrames: 30 })}
      />
      <TransitionSeries.Sequence durationInFrames={300}>
        <SceneB />
      </TransitionSeries.Sequence>
    </TransitionSeries>
  );
};
```

### Available Transitions

| Transition | Import | Effect |
|-----------|--------|--------|
| `fade()` | `@remotion/transitions/fade` | Crossfade between scenes |
| `slide()` | `@remotion/transitions/slide` | Slide in from a direction |
| `wipe()` | `@remotion/transitions/wipe` | Wipe from one side |
| `flip()` | `@remotion/transitions/flip` | 3D flip effect |

### Timing Options

```tsx
import { linearTiming, springTiming } from "@remotion/transitions";

// Linear timing (fixed duration)
linearTiming({ durationInFrames: 30 })

// Spring-based timing (physics-based)
springTiming({ config: { damping: 12, stiffness: 100 } })
```

The transition duration overlaps the adjacent sequences -- it does not add extra frames to the total timeline.

FILE:references/lambda.md
# Remotion Lambda Rendering

Overview of serverless video rendering on AWS Lambda for scaling beyond local rendering.

## What is Remotion Lambda?

Remotion Lambda renders videos on AWS Lambda functions. Each Lambda invocation renders a chunk of frames in parallel, then stitches the result. This enables:

- **Faster renders** -- parallel frame rendering across multiple Lambda instances
- **Batch processing** -- render many videos without tying up a local machine
- **Scalability** -- render hundreds of videos concurrently

## When to Use

| Scenario | Local Render | Lambda |
|----------|-------------|--------|
| Single video, development | Best choice | Overkill |
| Single video, production | Good | Optional |
| Batch of 10+ videos | Slow | Best choice |
| CI/CD pipeline rendering | Limited | Best choice |
| Personalized videos at scale | Not feasible | Best choice |

**Default to local rendering.** Use Lambda when you need parallelism or batch processing.

## Setup Requirements

### AWS Credentials

Lambda rendering requires three environment variables:

```bash
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export REMOTION_AWS_REGION="us-east-1"
```

### Package Installation

```bash
npm install @remotion/lambda
```

Ensure the version matches your other `@remotion/*` packages.

## 3-Step Deploy Flow

### Step 1: Deploy Lambda Function

```bash
npx remotion lambda functions deploy
```

Creates the Lambda function in your AWS account. Run once per region.

### Step 2: Deploy Site (Upload Bundle)

```bash
npx remotion lambda sites create src/index.ts
```

Bundles your Remotion project and uploads it to S3. Returns a serve URL. Run after each code change.

### Step 3: Render

```bash
npx remotion lambda render --function-name <fn> --serve-url <url> CompositionId
```

Triggers a Lambda render. Returns a URL to the rendered video in S3.

### Check Render Status

```bash
npx remotion lambda renders list
```

Lists active and completed renders with status and output URLs.

## Cost Considerations

- **Lambda charges**: Per invocation + per millisecond of execution time
- **S3 charges**: Storage for bundled site + rendered output
- **Typical cost**: A 30-second 1080p video costs roughly $0.01-0.05 depending on complexity
- **Concurrency**: AWS Lambda default concurrency limit is 1000 per region

## Limitations

- Requires AWS account with appropriate IAM permissions
- Lambda has a 15-minute execution timeout per invocation
- Maximum output file size limited by Lambda's `/tmp` storage (10GB)
- Cold starts can add 5-10 seconds to the first render

## Further Reference

See `tools/integrations/remotion.md` for the full CLI command reference including all Lambda subcommands.

Note: AWS infrastructure setup (IAM roles, S3 bucket policies, VPC configuration) is out of scope for this skill. Refer to the [Remotion Lambda documentation](https://www.remotion.dev/docs/lambda) for detailed AWS setup instructions.

FILE:references/rendering.md
# Remotion Rendering Reference

Detailed rendering options, output formats, quality settings, and common render scenarios.

## Local Render

The basic render command:

```bash
npx remotion render src/index.ts CompositionId out/video.mp4
```

- `src/index.ts` -- the Remotion entry file
- `CompositionId` -- the `id` from your `<Composition>` registration (PascalCase)
- `out/video.mp4` -- output file path

## Preview Mode

Open an interactive preview in the browser:

```bash
npx remotion preview src/index.ts
```

Opens at `http://localhost:3000` with:
- Frame-by-frame scrubbing
- Real-time prop editing
- Composition selection (if multiple registered)
- Playback controls

## Output Formats

### Video Formats

| Format | Extension | Flag | Notes |
|--------|-----------|------|-------|
| H.264 (MP4) | `.mp4` | `--codec h264` | Default. Best compatibility. |
| H.265 (MP4) | `.mp4` | `--codec h265` | Smaller files, less compatible. |
| VP8 (WebM) | `.webm` | `--codec vp8` | Web-friendly, good quality. |
| VP9 (WebM) | `.webm` | `--codec vp9` | Better compression than VP8. |
| ProRes | `.mov` | `--codec prores` | Professional editing workflows. |

### Image Formats

| Format | Extension | Flag | Notes |
|--------|-----------|------|-------|
| PNG Sequence | `.png` | `--image-format png` | Lossless frames for post-processing |
| JPEG Sequence | `.jpg` | `--image-format jpeg` | Smaller frames, lossy |
| GIF | `.gif` | `--codec gif` | Animated GIF output |

## Quality Settings

### CRF (Constant Rate Factor)

Controls video quality for H.264 and H.265:

```bash
npx remotion render src/index.ts MyVideo out/video.mp4 --crf 18
```

| CRF | Quality | File Size | Use Case |
|-----|---------|-----------|----------|
| 0 | Lossless | Very large | Archival |
| 15 | Excellent | Large | Production master |
| 18 | Very good | Medium | **Recommended default** |
| 23 | Good | Smaller | Web delivery |
| 28 | Acceptable | Small | Fast previews |
| 51 | Worst | Tiny | Testing only |

Lower CRF = higher quality, larger files.

### JPEG Quality

Controls quality when using JPEG frame encoding:

```bash
npx remotion render src/index.ts MyVideo out/video.mp4 --jpeg-quality 90
```

Range: 0-100 (default: 80). Only affects JPEG-based encoding pipelines.

## Resolution Override

Override the composition dimensions at render time:

```bash
npx remotion render src/index.ts MyVideo out/video.mp4 --width 1280 --height 720
```

Useful for rendering lower-resolution previews quickly.

## Custom Props

Pass runtime props to the composition:

```bash
npx remotion render src/index.ts MyVideo out/video.mp4 --props='{"title":"Launch Day","color":"#ff0000"}'
```

Props must be valid JSON. They override the `defaultProps` in the `<Composition>` registration.

## Still Image Render

Render a single frame as an image:

```bash
npx remotion still src/index.ts CompositionId out/frame.png --frame=60
```

- `--frame=60` renders frame 60 (1 second into a 60fps video)
- Output format determined by file extension (`.png` or `.jpg`)
- Useful for thumbnails, social preview images, and debugging

## Codec Selection Guide

| Scenario | Codec | CRF | Command |
|----------|-------|-----|---------|
| Production delivery | H.264 | 18 | `--codec h264 --crf 18` |
| Fast preview | H.264 | 28 | `--codec h264 --crf 28` |
| Web embedding | VP9 | 23 | `--codec vp9 --crf 23` |
| Professional editing | ProRes | - | `--codec prores` |
| Social media upload | H.264 | 18 | `--codec h264 --crf 18` |
| Animated thumbnail | GIF | - | `--codec gif` |

## Common Render Scenarios

### Production Video (High Quality)

```bash
npx remotion render src/index.ts MyVideo out/video.mp4 --codec h264 --crf 18
```

### Fast Preview (Lower Quality)

```bash
npx remotion render src/index.ts MyVideo out/preview.mp4 --codec h264 --crf 28 --width 960 --height 540
```

### Social Media Upload

```bash
npx remotion render src/index.ts MyVideo out/social.mp4 --codec h264 --crf 18
```

H.264 is universally accepted by all social platforms (YouTube, TikTok, Instagram, LinkedIn).

### PNG Sequence for Post-Processing

```bash
npx remotion render src/index.ts MyVideo out/frames/ --image-format png
```

Renders each frame as a separate PNG file for use in external video editors.

### WebM for Web Embedding

```bash
npx remotion render src/index.ts MyVideo out/video.webm --codec vp9 --crf 23
```

Smaller files than H.264 with comparable quality, good for web delivery.

## Render Performance Tips

- **Reduce resolution** for previews (`--width 960 --height 540`)
- **Increase CRF** for faster renders during development (`--crf 28`)
- **Use `--frames=0-60`** to render only a portion for testing
- For parallel rendering at scale, see `references/lambda.md`

FILE:references/setup.md
# Remotion Project Setup

Detailed setup and configuration reference for Remotion projects.

## Scaffolding a New Project

Create a new Remotion project using the official scaffolding tool:

```bash
npx create-video@latest my-video
cd my-video
npm install
```

This creates the standard Remotion project structure with all required dependencies and configuration.

## Directory Structure

A scaffolded Remotion project has this structure:

```
my-video/
  src/
    Root.tsx           # Composition registration (entry point)
    index.ts           # Remotion entry file (registers Root)
    MyComposition.tsx   # Default scene component
  package.json          # Dependencies with @remotion/* packages
  tsconfig.json         # TypeScript configuration
  remotion.config.ts    # Remotion-specific bundler config (optional)
```

### Key Files

**`src/index.ts`** -- The Remotion entry point that registers the root component:

```tsx
import { registerRoot } from "remotion";
import { RemotionRoot } from "./Root";
registerRoot(RemotionRoot);
```

**`src/Root.tsx`** -- Where all compositions are registered:

```tsx
import { Composition } from "remotion";
import { MyScene } from "./MyScene";

export const RemotionRoot: React.FC = () => {
  return (
    <>
      <Composition
        id="MyVideo"
        component={MyScene}
        durationInFrames={900}
        fps={60}
        width={1920}
        height={1080}
        defaultProps={{ title: "My Video" }}
      />
    </>
  );
};
```

Multiple compositions can be registered in the same Root.tsx using a React fragment (`<>...</>`).

## Package Dependencies

### Required Packages

| Package | Purpose |
|---------|---------|
| `remotion` | Core framework (re-exports from @remotion/core) |
| `@remotion/cli` | CLI for rendering and preview |
| `@remotion/bundler` | Webpack bundler for Remotion projects |
| `react` | React (peer dependency) |
| `react-dom` | React DOM (peer dependency) |

### Optional Packages

| Package | Purpose | When to Add |
|---------|---------|-------------|
| `@remotion/player` | Embeddable video player for React apps | Web-based preview or embedding |
| `@remotion/lambda` | Serverless rendering on AWS | Cloud rendering at scale |
| `@remotion/media-utils` | Audio/video duration and metadata | Working with audio or video assets |
| `@remotion/transitions` | Scene transition effects | Smooth transitions between scenes |
| `@remotion/gif` | Animated GIF support | Using GIF assets in compositions |

## Version Pinning

**All `@remotion/*` packages MUST be pinned to the same version.** Mixing versions causes subtle rendering bugs and build failures.

Verify version alignment:

```bash
npm ls | grep remotion
```

If versions are mismatched, update all at once:

```bash
npm install remotion@latest @remotion/cli@latest @remotion/bundler@latest
```

If you use optional packages, include them in the update:

```bash
npm install remotion@latest @remotion/cli@latest @remotion/bundler@latest @remotion/player@latest @remotion/lambda@latest @remotion/media-utils@latest @remotion/transitions@latest
```

**Never** update a single `@remotion` package independently. Always update all of them together.

## TypeScript Configuration

The `tsconfig.json` must include:

```json
{
  "compilerOptions": {
    "target": "ES2018",
    "module": "commonjs",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"]
}
```

The critical setting is `"jsx": "react-jsx"` -- this enables the modern JSX transform that Remotion v4 requires.

## Adding to an Existing Project

If a Remotion project already exists (detected by `@remotion/core` in `package.json`):

1. **Add a new scene component** in `src/`:

```tsx
// src/NewScene.tsx
import { useCurrentFrame, AbsoluteFill } from "remotion";

export const NewScene: React.FC<{ text: string }> = ({ text }) => {
  const frame = useCurrentFrame();
  return (
    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
      <h1 style={{ fontSize: 60, color: "white" }}>{text}</h1>
    </AbsoluteFill>
  );
};
```

2. **Register it in `src/Root.tsx`** by adding a new `<Composition>`:

```tsx
import { Composition } from "remotion";
import { NewScene } from "./NewScene";
// ... existing imports

export const RemotionRoot: React.FC = () => {
  return (
    <>
      {/* Existing compositions... */}
      <Composition
        id="NewVideo"
        component={NewScene}
        durationInFrames={600}
        fps={60}
        width={1920}
        height={1080}
        defaultProps={{ text: "New Video" }}
      />
    </>
  );
};
```

3. **Render the new composition** by referencing its ID:

```bash
npx remotion render src/index.ts NewVideo out/new-video.mp4
```

## Common Resolutions

| Format | Width | Height | Aspect Ratio | Use Case |
|--------|-------|--------|--------------|----------|
| 1080p Landscape | 1920 | 1080 | 16:9 | Standard video, YouTube |
| 1080p Vertical | 1080 | 1920 | 9:16 | Reels, TikTok, Shorts |
| 1080p Square | 1080 | 1080 | 1:1 | Instagram feed, LinkedIn |
| 4K Landscape | 3840 | 2160 | 16:9 | High-res production |
| 720p Landscape | 1280 | 720 | 16:9 | Fast previews, low bandwidth |

ClawHub Frontend Cloud+2

M@clawhub-mariokarras-f59a320bef

Firecrawl Cli

Skill

When the user wants to scrape, crawl, or extract content from websites. Also use when the user mentions 'scrape site,' 'crawl website,' 'extract content,' 'w...

---
name: firecrawl-cli
description: "When the user wants to scrape, crawl, or extract content from websites. Also use when the user mentions 'scrape site,' 'crawl website,' 'extract content,' 'web scraping,' 'site map,' 'get page content,' 'extract data from website,' 'autonomous extraction,' or 'structured extraction.' Covers all Firecrawl CLI commands: scrape (single page), crawl (entire site), crawl-status (check job), map (sitemap/URL discovery), search (search + scrape), agent (autonomous data gathering), and extract (structured LLM extraction). For company research via web search, see exa-company-research."
metadata:
  version: 1.0.0
---

# Firecrawl CLI

You help users scrape, crawl, and extract content from websites using the Firecrawl CLI tool. You select the right subcommand for the task and handle async operations like crawling.

## Before Starting

**Check for product marketing context first:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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.

Then determine:

1. **Target URL(s)** — What site or page to extract content from
2. **What content to extract** — Full page, specific data, all pages on a site
3. **Single page vs full site** — One URL (scrape) or many pages (crawl)
4. **Search first?** — Does the user need to find pages before extracting content

---

## Command Reference

| Command | Purpose | When to Use |
|---------|---------|-------------|
| `scrape` | Extract content from a single page | Need content from one specific URL |
| `crawl` | Crawl an entire site (async) | Need content from multiple pages on a site |
| `crawl-status` | Check a crawl job's progress | After starting a crawl, to poll for results |
| `map` | Discover all URLs on a site | Need to see what pages exist before scraping |
| `search` | Search the web and scrape results | Need to find relevant pages AND extract content |
| `agent` | Autonomous web data gathering | Need AI to find and extract data across multiple sites |
| `extract` | Structured data extraction with LLMs | Need specific structured data from one or more URLs |

---

## Workflow by Use Case

### Scraping a Single Page

```bash
firecrawl.js scrape --url "https://example.com/page"
```

**When:** You need content from one specific page. Returns markdown by default.

**Options:**
- `--formats markdown,html` — Choose output format(s), comma-separated
- `--only-main-content false` — Include headers, footers, navs (default: main content only)
- `--dry-run` — Preview the API request without sending it

**Example — extract a blog post as markdown:**
```bash
firecrawl.js scrape --url "https://example.com/blog/post-title"
```

**Example — get full HTML including navigation:**
```bash
firecrawl.js scrape --url "https://example.com" --formats html --only-main-content false
```

### Crawling an Entire Site

```bash
firecrawl.js crawl --url "https://example.com" --limit 50
```

**When:** You need content from multiple pages across a site. This is an **async operation** — the CLI starts a crawl job and returns a job ID.

**Options:**
- `--limit N` — Maximum number of pages to crawl
- `--max-depth N` — Maximum link depth from the starting URL
- `--poll` — Automatically poll for completion instead of returning the job ID
- `--dry-run` — Preview the API request without sending it

**Workflow without --poll:**
1. Start the crawl: `firecrawl.js crawl --url "https://example.com" --limit 20`
2. Note the returned job ID
3. Check status: `firecrawl.js crawl-status --id "job-id-here"`
4. Repeat step 3 until complete

**Workflow with --poll (recommended):**
```bash
firecrawl.js crawl --url "https://example.com" --limit 20 --poll
```
The CLI handles polling automatically and returns all results when done.

### Checking Crawl Status

```bash
firecrawl.js crawl-status --id "job-id-here"
```

**When:** You started a crawl without `--poll` and need to check if it finished.

### Getting a Site Map

```bash
firecrawl.js map --url "https://example.com"
```

**When:** You need to discover all URLs on a site before deciding what to scrape. Good first step before targeted scraping.

**Options:**
- `--search "term"` — Filter URLs containing a search term
- `--limit N` — Maximum number of URLs to return
- `--dry-run` — Preview the API request without sending it

**Example — find all blog pages:**
```bash
firecrawl.js map --url "https://example.com" --search "blog"
```

### Searching and Scraping

```bash
firecrawl.js search --query "site:example.com pricing plans"
```

**When:** You need to find relevant pages AND extract their content in one step. Combines web search with content extraction.

**Options:**
- `--limit N` — Number of results to return
- `--country "us"` — Country code for localized results
- `--dry-run` — Preview the API request without sending it

**Example — find competitor pricing pages:**
```bash
firecrawl.js search --query "competitor.com pricing" --limit 5
```

### Autonomous Agent Extraction

```bash
firecrawl.js agent --prompt "Find pricing information for Acme Corp" --poll
```

**When:** You need the AI to autonomously search, navigate, and gather data. No URLs required -- just describe what you need.

**Options:**
- `--prompt "..."` -- Describe what data to find (required, max 10000 chars)
- `--url "..."` -- Optionally constrain to a specific URL
- `--urls "url1,url2"` -- Optionally constrain to multiple URLs
- `--max-credits N` -- Set spending limit (default: 2500)
- `--poll` -- Wait for results instead of returning job ID
- `--dry-run` -- Preview the API request without sending it

**Example -- find competitor pricing:**
```bash
firecrawl.js agent --prompt "Find pricing tiers and plans for competitor.com" --url "https://competitor.com" --poll
```

### Extracting Structured Data

```bash
firecrawl.js extract --urls "https://example.com/pricing" --prompt "Extract pricing tiers with plan names and prices" --poll
```

**When:** You need specific structured data extracted from URLs using LLMs. Supports wildcards for domain-wide extraction.

**Options:**
- `--urls "url1,url2"` -- URLs to extract from, comma-separated (required). Supports `/*` wildcards
- `--prompt "..."` -- Describe what data to extract
- `--schema '{"type":"object",...}'` -- JSON schema for structured output
- `--enable-web-search` -- Follow external links during extraction
- `--poll` -- Wait for results instead of returning job ID
- `--dry-run` -- Preview the API request without sending it

**Example -- extract product data from multiple pages:**
```bash
firecrawl.js extract --urls "https://example.com/products/*" --prompt "Extract product names, prices, and descriptions" --poll
```

---

## Choosing the Right Command

- **Need one page?** → `scrape`
- **Need the whole site?** → `crawl` with `--limit` and `--poll`
- **Need to discover URLs first?** → `map`, then `scrape` specific pages
- **Need search + content?** → `search`
- **Started a crawl and need results?** → `crawl-status`
- **Need AI to find data autonomously?** → `agent` with `--poll`
- **Need structured data from known URLs?** → `extract` with `--prompt` and `--poll`

**Common multi-step workflows:**

1. **Targeted extraction:** `map` → review URLs → `scrape` specific pages
2. **Full site dump:** `crawl --poll --limit 100`
3. **Research a topic:** `search` → review results → `scrape` for deeper content

---

## Output Format

Present extracted content with clear structure:

- **Source URL** — Always include the URL the content came from
- **Extraction method** — Note which command was used (scrape, crawl, search)
- **Content** — The extracted markdown/HTML content

For crawl results with multiple pages, organize by page with clear headers:

```
### Page 1: [title] (https://example.com/page-1)
[content]

### Page 2: [title] (https://example.com/page-2)
[content]
```

---

## Environment Setup

The Firecrawl CLI requires a `FIRECRAWL_API_KEY` environment variable. If the key is not set, the CLI will return an error. The user needs to:

1. Get an API key from [firecrawl.dev](https://firecrawl.dev)
2. Set it in their environment: `export FIRECRAWL_API_KEY="fc-..."`

Use `--dry-run` on any command to preview the API request without needing a key.

---

## Related Skills

- **exa-company-research** — For web search and company research (search-focused, not scraping)
- **seo-audit** — Uses Firecrawl for schema detection and technical SEO analysis
- **competitive-intelligence** — Combines Exa search + Firecrawl scraping for competitive analysis (Phase 4)

ClawHub Database Automation+2

M@clawhub-mariokarras-f59a320bef

Brand Voice

Skill

When the user wants to define, document, or enforce their brand voice and style guide. Use when the user mentions 'brand voice,' 'tone of voice,' 'style guid...

---
name: brand-voice
description: "When the user wants to define, document, or enforce their brand voice and style guide. Use when the user mentions 'brand voice,' 'tone of voice,' 'style guide,' 'voice and tone,' 'writing guidelines,' 'brand personality,' 'tone adaptation,' 'messaging pillars,' 'terminology guide,' 'how should we sound,' or wants consistency across content. Creates `.agents/brand-voice-guide.md` — a comprehensive style reference that downstream skills use alongside `product-marketing-context.md`. For foundational positioning context, see product-marketing-context."
metadata:
  version: 1.0.0
---

# Brand Voice

You help users define, document, and enforce a comprehensive brand voice and style guide. This goes deeper than the Brand Voice section in product-marketing-context — it covers voice attributes with examples, tone adaptation by channel and situation, style rules, and terminology governance.

The document is stored at `.agents/brand-voice-guide.md`.

## Workflow

### Step 1: Check for Existing Context

First, check if `.agents/brand-voice-guide.md` already exists.

**If it exists:**
- Read it and summarize what's captured
- Ask which sections they want to update or expand
- Only gather info for those sections

**If it doesn't exist:**

Check if `.agents/product-marketing-context.md` exists. If it does, read the Brand Voice, Customer Language, and Personas sections — use them as a starting point so the user doesn't repeat themselves.

Offer two options:
1. **Build from product-marketing-context** (recommended if it exists): Draft V1 from the existing context, then expand each area with the deeper frameworks below
2. **Start from scratch**: Walk through each section conversationally

### Step 2: Gather Information

Walk through sections conversationally. Don't dump all questions at once — one section at a time, confirm, move on.

**Question design — reduce friction, get better answers:**
- **Select one from spectrum**: For preference fields (formality, authority, emotion), present a scale: "Where do you fall? Formal ← → Casual." Let them pick a point.
- **Select all that apply**: For multi-value fields (channels, situations), present a checklist of common options plus "other."
- **Finish this sentence**: When users freeze, offer fill-in-the-blank: "Our brand sounds like ___ but never ___."
- **Examples as anchors**: Show a concrete example of a good answer before asking. E.g., show a completed voice attribute before asking them to define theirs.
- **Confirm by summarizing**: After each section, summarize in 2-3 sentences and ask: "Does this capture it? Anything to adjust?"
- **Stay conversational**: These patterns are tools to reach for when the user is stuck, not a rigid form. If the user gives a rich answer unprompted, capture it and move on. Use structured prompts to unblock, not to gate.
- Match pattern to question type — sections below use `→ *pattern*:` annotations as instructions for you, not text to show the user.

**Important:** Adapt to offering type and audience. A B2C healthcare service needs different tone guidance than a B2B developer tool. If product-marketing-context exists, use its offering type and audience to shape your questions.

---

## Sections to Capture

**Priority guide:** Sections 1-4 are the foundation — they give downstream skills enough to produce consistent content. Sections 5-7 add precision and are high-value for teams with multiple writers or agencies. Mark sections as "[to revisit]" if the user runs out of time.

### 1. Brand Personality

Define the brand as if it were a person.

- → *finish this sentence*: "If our brand were a person at a dinner party, other guests would describe them as ___."
- Capture the character sketch as a 2-3 sentence description → *constraining prompt*: "Describe them in 2-3 sentences."
- Extract 3-5 defining adjectives from the sketch
- → *finish this sentence*: "Our brand would NEVER be described as ___." — this prevents drift

**Output example:**
> "A knowledgeable colleague who explains complex things simply, celebrates your wins genuinely, and never talks down to you. Not a detached expert, not a hype-driven salesperson."

### 2. Voice Attributes

Select 3-5 attributes that define how the brand communicates. For each attribute, capture all four dimensions — the "is / is not" pairing prevents the most common brand voice failures.

For each attribute:
- **We are**: what this means in practice
- **We are not**: the common misinterpretation to avoid
- **This sounds like**: an example sentence demonstrating the attribute
- **This does NOT sound like**: an example sentence violating it

Ask the user to provide real examples from their existing content if possible. If they don't have content yet, co-write the examples together.

→ *spectrum selection*: Present these spectrums and ask them to pick where they fall on each. This helps them identify their 3-5 attributes:

| Spectrum | One End | Other End |
|----------|---------|-----------|
| Formality | Formal, institutional | Casual, conversational |
| Authority | Expert, authoritative | Peer-level, collaborative |
| Emotion | Warm, empathetic | Direct, matter-of-fact |
| Complexity | Technical, precise | Simple, accessible |
| Energy | Bold, energetic | Calm, measured |
| Humor | Playful, witty | Serious, earnest |

For each attribute they identify, walk through the four dimensions using the example as an anchor before asking.

### 3. Core Messaging Pillars

3-5 key themes the brand consistently communicates. These are the "big ideas" that should surface across all content.

For each pillar:
- The theme in one phrase
- Why it matters to the audience (connect to their pain points or aspirations)
- How it shows up in content (what kinds of claims, stories, or proof points support it)

→ *constraining prompt*: "If a customer could only remember three things about you, what should those be?"

Rank them by priority → ask: "Which one leads in a headline? Which supports in body copy?"

If product-marketing-context exists, draft pillars from the Differentiation and Proof Points sections and ask the user to validate and rank them.

### 4. Tone Spectrum

The voice stays consistent, but tone adapts by context. Tone is the emotional inflection applied to the voice.

**Key principle to convey:** Voice attributes remain fixed. Tone dials them up or down. For example, if a brand is "bold and warm" — in a product launch, dial up boldness; in an incident response, dial up warmth. Neither disappears.

**Capture tone by channel** → *select all that apply, then fill in tone for each*: "Which of these channels do you use?" Present the table and only fill rows for channels they select:

| Channel | Tone Adaptation | Example |
|---------|----------------|---------|
| Website/landing pages | [their guidance] | [their example] |
| Blog/articles | | |
| Social (specify platform) | | |
| Email marketing | | |
| Sales/proposals | | |
| Support/help docs | | |
| Ads | | |

**Capture tone by situation:**

| Situation | Tone Adaptation |
|-----------|----------------|
| Product launch / announcement | |
| Incident, outage, or bad news | |
| Customer success / case study | |
| Onboarding / welcome | |
| Price increase or breaking change | |

Only capture channels and situations that are relevant to the user's business. Don't force a SaaS startup to define press release tone if they've never written one.

### 5. Style Rules

Specific grammar, formatting, and language rules that ensure consistency across writers. These are the "house rules" — once decided, they shouldn't vary.

**Grammar and mechanics:**

| Rule | Options to present |
|------|--------------------|
| Oxford comma | Yes / No |
| Headings | Sentence case / Title case |
| Contractions | Use freely / Use sparingly / Avoid |
| Numbers | Spell out 1-9 / Always numerals |
| Percent | "%" / "percent" |
| Date format | Month DD, YYYY / DD/MM/YYYY / other |
| Lists | End with periods / No periods on fragments |

**Formatting conventions:**
- Bold and italic usage
- Link text policy (descriptive vs. "click here")
- Emoji policy by channel

**Punctuation and emphasis:**
- Exclamation mark policy (e.g., max one per paragraph, never in headlines)
- ALL CAPS policy
- Ellipsis usage

→ *select one per rule*: Present each grammar rule as a choice: "Oxford comma: (a) Yes (b) No." Help them decide quickly — these are decisions, not debates. If they don't have preferences, suggest sensible defaults and confirm.

### 6. Terminology

Preferred and avoided terms. This prevents inconsistency and protects positioning.

**Preferred terms:**
| Use This | Not This | Notes |
|----------|----------|-------|
| | | |

Ask for:
- Product and feature names (official capitalization, full name vs. shorthand)
- Whether to use "the" before product names
- Trademark/registration symbols (when required)

**Inclusive language guidance:**
- Gender-neutral defaults (they/them for unknown individuals)
- Person-first language preferences
- Terms to avoid and their replacements

**Jargon management:**
- Terms the audience understands without explanation
- Jargon that should always be replaced with plain language
- Acronyms that need spelling out on first use

**Competitor and category terms:**
- Preferred category framing (how you name what you do)
- How to refer to competitors (by name or generically)
- Terms competitors have coined that you should avoid

If product-marketing-context exists, pull the Glossary and Words to Use/Avoid into this section as a starting point.

### 7. Audience-Specific Voice Notes

If the brand speaks to multiple distinct audiences (captured in Personas from product-marketing-context), document how voice adapts for each.

For each audience:
- What they care about (pull from personas)
- Expertise level (what you can assume they know)
- How they expect to be addressed
- Key voice adjustments (more technical? more empathetic? more formal?)

Example: A home healthcare service might speak warmly and reassuringly to family decision-makers, clinically and efficiently to referring physicians, and clearly and patiently to elderly patients.

---

## Step 3: Create the Document

After gathering information, create `.agents/brand-voice-guide.md` with this structure:

```markdown
# Brand Voice Guide

*Last updated: [date]*

## Brand Personality
**Character sketch:**
> [2-3 sentence description]

**Defining traits:** [3-5 adjectives]
**We are NOT:** [what the brand is not]

## Voice Attributes

### [Attribute 1]
- **We are**: [what this means]
- **We are not**: [misinterpretation to avoid]
- **Sounds like**: "[example]"
- **Does NOT sound like**: "[counter-example]"

### [Attribute 2]
[same format]

### [Attribute 3]
[same format]

## Core Messaging Pillars

| Priority | Pillar | Why it matters | How it shows up |
|----------|--------|---------------|-----------------|
| 1 | | | |
| 2 | | | |
| 3 | | | |

## Tone Spectrum

**Principle:** Voice stays constant. Tone dials up or down by context.

### By Channel
| Channel | Tone | Example |
|---------|------|---------|
| | | |

### By Situation
| Situation | Tone |
|-----------|------|
| | |

## Style Rules

### Grammar & Mechanics
| Rule | Our choice |
|------|-----------|
| Oxford comma | |
| Headings | |
| Contractions | |
| Numbers | |
| Percent | |
| Date format | |
| Lists | |

### Formatting
- **Bold**: [when to use]
- **Italic**: [when to use]
- **Links**: [policy]
- **Emoji**: [policy by channel]

### Punctuation
- **Exclamation marks**: [policy]
- **ALL CAPS**: [policy]
- **Ellipsis**: [policy]

## Terminology

### Preferred Terms
| Use This | Not This | Notes |
|----------|----------|-------|
| | | |

### Product Names
| Name | Capitalization | Shorthand | Notes |
|------|---------------|-----------|-------|
| | | | |

### Inclusive Language
[guidelines]

### Jargon Guide
| Term | Audience knows it? | Action |
|------|-------------------|--------|
| | Yes / No | Use freely / Define / Replace with... |

### Competitor & Category Terms
**Our category:** [preferred framing]
**Refer to competitors:** [by name / generically]
**Terms to avoid:** [competitor-coined terms]

## Audience-Specific Notes

### [Audience 1]
- **Expertise**: [level]
- **Expects**: [how they want to be addressed]
- **Adjust**: [voice adjustments]

### [Audience 2]
[same format]
```

---

## Step 4: Confirm and Save

- Show the completed document
- Ask if anything needs adjustment
- Save to `.agents/brand-voice-guide.md`
- Tell them: "Content skills will now use this guide alongside your product marketing context. Run `/brand-voice` anytime to update it."

---

## Tips

- **Start with personality**: The character sketch anchors everything else. If the user can describe the brand as a person, the attributes and tone follow naturally.
- **Push for counter-examples**: "This does NOT sound like" is often more useful than "this sounds like" — it prevents the most common drift.
- **Don't over-specify early**: A startup with one writer doesn't need 30 style rules. Capture what matters now and mark the rest "[to revisit]."
- **Pull from existing content**: If they have content they're proud of, use it as voice examples. If they have content they hate, use it as counter-examples.
- **Respect product-marketing-context**: Don't re-ask what's already captured there. Build on it.
- **Style rules are decisions, not debates**: For grammar choices (Oxford comma, contractions, etc.), present options, help them choose, and move on. These aren't strategic — they just need to be consistent.

FILE:evals/evals.json
{
  "skill_name": "brand-voice",
  "evals": [
    {
      "id": 1,
      "prompt": "I want to define our brand voice. We're a B2B SaaS company that sells developer tools.",
      "expected_output": "Should check for existing brand-voice-guide.md. Should check for product-marketing-context.md to use as starting point. Should walk through sections conversationally: Brand Personality (character sketch), Voice Attributes (with is/is not/sounds like/doesn't sound like), Core Messaging Pillars, Tone Spectrum by channel and situation, Style Rules, Terminology, and Audience-Specific Notes. Should adapt for a technical B2B audience — e.g., suggest spectrums like 'technical vs accessible' and 'peer-level vs authoritative'. Should create .agents/brand-voice-guide.md when complete.",
      "assertions": [
        "Checks for existing brand-voice-guide.md",
        "Checks for product-marketing-context.md",
        "Asks for brand personality character sketch",
        "Captures voice attributes with is/is not format",
        "Captures messaging pillars with priority ranking",
        "Covers tone adaptation by channel and situation",
        "Adapts for technical B2B audience",
        "Creates file at .agents/brand-voice-guide.md"
      ],
      "files": []
    },
    {
      "id": 2,
      "prompt": "We already have a product marketing context set up. Can you build our brand voice guide from that?",
      "expected_output": "Should read .agents/product-marketing-context.md (or .claude/ location). Should pull Brand Voice, Customer Language, and Personas sections as starting points. Should draft voice attributes from the existing tone/personality fields. Should draft messaging pillars from Differentiation and Proof Points. Should draft audience-specific notes from Personas. Should present the draft and ask what needs expanding rather than starting from scratch.",
      "assertions": [
        "Reads existing product-marketing-context.md",
        "Pulls Brand Voice section as starting point",
        "Pulls Customer Language for terminology",
        "Pulls Personas for audience-specific notes",
        "Drafts pillars from Differentiation and Proof Points",
        "Presents draft before asking additional questions",
        "Does not re-ask information already captured"
      ],
      "files": []
    },
    {
      "id": 3,
      "prompt": "Our brand voice needs to work across very different audiences — we talk to anxious family members choosing home care and also to referring physicians. Help us define our voice.",
      "expected_output": "Should recognize multi-audience scenario. Should capture a unified brand personality that works across both audiences. Should document voice attributes that remain constant. Should capture audience-specific tone shifts — warmer and more reassuring for family members, clinical and efficient for physicians. Should ask about channels each audience uses and adapt tone-by-channel accordingly. Should handle the trust/empathy dimension that healthcare demands.",
      "assertions": [
        "Recognizes multi-audience scenario",
        "Captures unified brand personality",
        "Documents constant voice attributes",
        "Captures audience-specific tone shifts",
        "Adapts for family member audience (warm, reassuring)",
        "Adapts for physician audience (clinical, efficient)",
        "Addresses trust and empathy for healthcare context"
      ],
      "files": []
    },
    {
      "id": 4,
      "prompt": "We need a style guide for our content team. Things like Oxford comma, capitalization rules, how we refer to our product, inclusive language — that kind of thing.",
      "expected_output": "Should recognize this as primarily a style rules and terminology request. Should still capture minimal brand personality and voice attributes for context, but focus depth on Style Rules (grammar, mechanics, formatting, punctuation) and Terminology (preferred terms, product names, inclusive language, jargon management, competitor terms). Should present grammar choices as options to decide on rather than open-ended questions. Should help them make decisions efficiently.",
      "assertions": [
        "Focuses on style rules and terminology sections",
        "Presents grammar rules as choices not open-ended questions",
        "Covers product name capitalization and shorthand",
        "Covers inclusive language guidance",
        "Covers jargon management",
        "Covers competitor term handling",
        "Still captures minimal voice context"
      ],
      "files": []
    },
    {
      "id": 5,
      "prompt": "Update our brand voice guide — we just expanded to a new channel (TikTok) and need tone guidance for short-form video content.",
      "expected_output": "Should read existing .agents/brand-voice-guide.md. Should identify the Tone Spectrum section as the primary update target. Should add TikTok/short-form video to the channel tone table. Should ask about tone adjustments for the platform (likely more casual, energetic, visual-first). Should preserve all existing content. Should consider whether voice attributes need any adjustment for this more casual channel.",
      "assertions": [
        "Reads existing brand-voice-guide.md",
        "Updates Tone Spectrum section",
        "Adds TikTok to channel tone table",
        "Asks about platform-specific tone",
        "Preserves existing content",
        "Considers voice attribute implications"
      ],
      "files": []
    },
    {
      "id": 6,
      "prompt": "Write homepage copy for our product.",
      "expected_output": "Should recognize this is a copywriting task, not a brand voice task. Should check for brand-voice-guide.md and product-marketing-context.md (as other skills do for context). Should defer to the copywriting skill for actually writing the homepage copy.",
      "assertions": [
        "Recognizes this as a copywriting task",
        "May check for or suggest brand-voice-guide.md",
        "References or defers to copywriting skill",
        "Does not attempt to write homepage copy using brand voice patterns"
      ],
      "files": []
    },
    {
      "id": 7,
      "prompt": "We're an early-stage startup, just two founders. We haven't written much content yet but want to establish our voice before we start. Can you help?",
      "expected_output": "Should adapt for early-stage with minimal existing content. Should focus on Brand Personality and Voice Attributes (the foundation). Should not overwhelm with style rules or terminology at this stage — mark those as '[to revisit]'. Should offer to co-write example sentences for voice attributes since they don't have existing content to reference. Should suggest sensible defaults for basic style rules rather than presenting every option.",
      "assertions": [
        "Adapts for early-stage company",
        "Focuses on personality and voice attributes",
        "Offers to co-write example sentences",
        "Marks advanced sections as to-revisit",
        "Suggests sensible defaults for style rules",
        "Does not overwhelm with full framework"
      ],
      "files": []
    }
  ]
}

ClawHub Writing Marketing+2

M@clawhub-mariokarras-f59a320bef

Paywall Upgrade Cro

Skill

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

---
name: paywall-upgrade-cro
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 page-cro) — this focuses on in-product upgrade moments where the user has already experienced value. For pricing decisions, see pricing-strategy.
metadata:
version: 1.1.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:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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, 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]
• [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
- **page-cro**: For public pricing page optimization
- **onboarding-cro**: For driving to aha moment before upgrade
- **ab-test-setup**: For testing paywall variations

FILE:evals/evals.json
{
"skill_name": "paywall-upgrade-cro",
"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-context.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-context.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 page-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 page-cro skill",
"Explains that paywall-upgrade-cro is for in-app upgrade prompts",
"Does not attempt public pricing page optimization"
],
"files": []
}
]
}

FILE:references/experiments.md
# 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

ClawHub Frontend Testing+2

M@clawhub-mariokarras-f59a320bef

Popup Cro

Skill

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

---
name: popup-cro
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 form-cro. For general page conversion optimization, see page-cro.
metadata:
version: 1.1.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

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

- **form-cro**: For optimizing the form inside the popup
- **page-cro**: For the page context around popups
- **email-sequence**: For what happens after popup conversion
- **ab-test-setup**: For testing popup variations

FILE:evals/evals.json
{
"skill_name": "popup-cro",
"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-context.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-context.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 form-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 form-cro is the right skill for detailed form optimization.",
"assertions": [
"Recognizes overlap with form optimization",
"References or defers to form-cro skill",
"Notes popups need minimal fields due to context",
"Does not attempt detailed form redesign"
],
"files": []
}
]
}

ClawHub Research Writing+2

M@clawhub-mariokarras-f59a320bef

Schema Markup

Skill

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

---
name: schema-markup
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: 1.1.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:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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 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

FILE:evals/evals.json
{
  "skill_name": "schema-markup",
  "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-context.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-context.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": []
    }
  ]
}

FILE:references/schema-examples.md
# 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",
    name: product.name,
    // ... other properties
  };

  return (
    <>
      <Head>
        <script
          type="application/ld+json"
          dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
        />
      </Head>
      {/* Page content */}
    </>
  );
}
```

ClawHub Frontend Marketing+2

M@clawhub-mariokarras-f59a320bef

Programmatic Seo

Skill

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

---
name: programmatic-seo
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: 1.1.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:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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 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-markup**: For adding structured data
- **site-architecture**: For page hierarchy, URL structure, and internal linking
- **competitor-alternatives**: For comparison page frameworks

FILE:evals/evals.json
{
  "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-context.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-context.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 competitor-alternatives 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 competitor-alternatives 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": []
    }
  ]
}

FILE:references/playbooks.md
# 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: competitor-alternatives 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

ClawHub Data Analysis Marketing+2

M@clawhub-mariokarras-f59a320bef

Seo Audit

Skill

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

---
name: seo-audit
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-markup. For AI search optimization, see ai-seo.
metadata:
  version: 1.1.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:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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 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

To detect structured data / schema markup (including JSON-LD injected via JavaScript by CMS plugins like AIOSEO, Yoast, or RankMath), use Firecrawl to render the page:

1. **Firecrawl CLI** — renders JavaScript and returns full page content:
   ```bash
   firecrawl.js scrape <url>
   ```
   Search the output for `application/ld+json` blocks to find schema markup.

2. **Google Rich Results Test** — https://search.google.com/test/rich-results (secondary verification)

Do NOT rely on `web_fetch` or `curl` for schema detection — they cannot see JS-injected markup.

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

---

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

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

> **Schema detection:** Use Firecrawl CLI for JS-rendered schema — see "Schema Markup Detection" section above.

**Paid Tools** (if available)
- Screaming Frog
- Ahrefs / Semrush
- Sitebulb
- ContentKing

---

## 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-markup**: For implementing structured data
- **page-cro**: For optimizing pages for conversion (not just ranking)
- **analytics-tracking**: For measuring SEO performance

FILE:evals/evals.json
{
  "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-context.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-context.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-markup 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-markup is the right skill for implementation.",
      "assertions": [
        "Recognizes this as schema markup implementation",
        "References or defers to schema-markup skill",
        "Does not attempt a full SEO audit",
        "May briefly mention FAQ schema benefits"
      ],
      "files": []
    }
  ]
}

FILE:references/ai-writing-detection.md
# 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

ClawHub Marketing Browser Automation+2

M@clawhub-mariokarras-f59a320bef

Site Architecture

Skill

When the user wants to plan, map, or restructure their website's page hierarchy, navigation, URL structure, or internal linking. Also use when the user menti...

---
name: site-architecture
description: When the user wants to plan, map, or restructure their website's page hierarchy, navigation, URL structure, or internal linking. Also use when the user mentions "sitemap," "site map," "visual sitemap," "site structure," "page hierarchy," "information architecture," "IA," "navigation design," "URL structure," "breadcrumbs," "internal linking strategy," "website planning," "what pages do I need," "how should I organize my site," or "site navigation." Use this whenever someone is planning what pages a website should have and how they connect. NOT for XML sitemaps (that's technical SEO — see seo-audit). For SEO audits, see seo-audit. For structured data, see schema-markup.
metadata:
  version: 1.1.0
---

# Site Architecture

You are an information architecture expert. Your goal is to help plan website structure — page hierarchy, navigation, URL patterns, and internal linking — so the site is intuitive for users and optimized for search engines.

## Before Planning

**Check for product marketing context first:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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.

Gather this context (ask if not provided):

### 1. Business Context
- What does the company do?
- Who are the primary audiences?
- What are the top 3 goals for the site? (conversions, SEO traffic, education, support)

### 2. Current State
- New site or restructuring an existing one?
- If restructuring: what's broken? (high bounce, poor SEO, users can't find things)
- Existing URLs that must be preserved (for redirects)?

### 3. Site Type
- SaaS marketing site
- Content/blog site
- E-commerce
- Documentation
- Hybrid (SaaS + content)
- Small business / local

### 4. Content Inventory
- How many pages exist or are planned?
- What are the most important pages? (by traffic, conversions, or business value)
- Any planned sections or expansions?

---

## Site Types and Starting Points

| Site Type | Typical Depth | Key Sections | URL Pattern |
|-----------|--------------|--------------|-------------|
| SaaS marketing | 2-3 levels | Home, Features, Pricing, Blog, Docs | `/features/name`, `/blog/slug` |
| Content/blog | 2-3 levels | Home, Blog, Categories, About | `/blog/slug`, `/category/slug` |
| E-commerce | 3-4 levels | Home, Categories, Products, Cart | `/category/subcategory/product` |
| Documentation | 3-4 levels | Home, Guides, API Reference | `/docs/section/page` |
| Hybrid SaaS+content | 3-4 levels | Home, Product, Blog, Resources, Docs | `/product/feature`, `/blog/slug` |
| Small business | 1-2 levels | Home, Services, About, Contact | `/services/name` |

**For full page hierarchy templates**: See [references/site-type-templates.md](references/site-type-templates.md)

---

## Page Hierarchy Design

### The 3-Click Rule

Users should reach any important page within 3 clicks from the homepage. This isn't absolute, but if critical pages are buried 4+ levels deep, something is wrong.

### Flat vs Deep

| Approach | Best For | Tradeoff |
|----------|----------|----------|
| Flat (2 levels) | Small sites, portfolios | Simple but doesn't scale |
| Moderate (3 levels) | Most SaaS, content sites | Good balance of depth and findability |
| Deep (4+ levels) | E-commerce, large docs | Scales but risks burying content |

**Rule of thumb**: Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy.

### Hierarchy Levels

| Level | What It Is | Example |
|-------|-----------|---------|
| L0 | Homepage | `/` |
| L1 | Primary sections | `/features`, `/blog`, `/pricing` |
| L2 | Section pages | `/features/analytics`, `/blog/seo-guide` |
| L3+ | Detail pages | `/docs/api/authentication` |

### ASCII Tree Format

Use this format for page hierarchies:

```
Homepage (/)
├── Features (/features)
│   ├── Analytics (/features/analytics)
│   ├── Automation (/features/automation)
│   └── Integrations (/features/integrations)
├── Pricing (/pricing)
├── Blog (/blog)
│   ├── [Category: SEO] (/blog/category/seo)
│   └── [Category: CRO] (/blog/category/cro)
├── Resources (/resources)
│   ├── Case Studies (/resources/case-studies)
│   └── Templates (/resources/templates)
├── Docs (/docs)
│   ├── Getting Started (/docs/getting-started)
│   └── API Reference (/docs/api)
├── About (/about)
│   └── Careers (/about/careers)
└── Contact (/contact)
```

**When to use ASCII vs Mermaid**:
- ASCII: quick hierarchy drafts, text-only contexts, simple structures
- Mermaid: visual presentations, complex relationships, showing nav zones or linking patterns

---

## Navigation Design

### Navigation Types

| Nav Type | Purpose | Placement |
|----------|---------|-----------|
| Header nav | Primary navigation, always visible | Top of every page |
| Dropdown menus | Organize sub-pages under parent | Expands from header items |
| Footer nav | Secondary links, legal, sitemap | Bottom of every page |
| Sidebar nav | Section navigation (docs, blog) | Left side within a section |
| Breadcrumbs | Show current location in hierarchy | Below header, above content |
| Contextual links | Related content, next steps | Within page content |

### Header Navigation Rules

- **4-7 items max** in the primary nav (more causes decision paralysis)
- **CTA button** goes rightmost (e.g., "Start Free Trial," "Get Started")
- **Logo** links to homepage (left side)
- **Order by priority**: most important/visited pages first
- If you have a mega menu, limit to 3-4 columns

### Footer Organization

Group footer links into columns:
- **Product**: Features, Pricing, Integrations, Changelog
- **Resources**: Blog, Case Studies, Templates, Docs
- **Company**: About, Careers, Contact, Press
- **Legal**: Privacy, Terms, Security

### Breadcrumb Format

```
Home > Features > Analytics
Home > Blog > SEO Category > Post Title
```

Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be a clickable link except the current page.

**For detailed navigation patterns**: See [references/navigation-patterns.md](references/navigation-patterns.md)

---

## URL Structure

### Design Principles

1. **Readable by humans** — `/features/analytics` not `/f/a123`
2. **Hyphens, not underscores** — `/blog/seo-guide` not `/blog/seo_guide`
3. **Reflect the hierarchy** — URL path should match site structure
4. **Consistent trailing slash policy** — pick one (with or without) and enforce it
5. **Lowercase always** — `/About` should redirect to `/about`
6. **Short but descriptive** — `/blog/how-to-improve-landing-page-conversion-rates` is too long; `/blog/landing-page-conversions` is better

### URL Patterns by Page Type

| Page Type | Pattern | Example |
|-----------|---------|---------|
| Homepage | `/` | `example.com` |
| Feature page | `/features/{name}` | `/features/analytics` |
| Pricing | `/pricing` | `/pricing` |
| Blog post | `/blog/{slug}` | `/blog/seo-guide` |
| Blog category | `/blog/category/{slug}` | `/blog/category/seo` |
| Case study | `/customers/{slug}` | `/customers/acme-corp` |
| Documentation | `/docs/{section}/{page}` | `/docs/api/authentication` |
| Legal | `/{page}` | `/privacy`, `/terms` |
| Landing page | `/{slug}` or `/lp/{slug}` | `/free-trial`, `/lp/webinar` |
| Comparison | `/compare/{competitor}` or `/vs/{competitor}` | `/compare/competitor-name` |
| Integration | `/integrations/{name}` | `/integrations/slack` |
| Template | `/templates/{slug}` | `/templates/marketing-plan` |

### Common Mistakes

- **Dates in blog URLs** — `/blog/2024/01/15/post-title` adds no value and makes URLs long. Use `/blog/post-title`.
- **Over-nesting** — `/products/category/subcategory/item/detail` is too deep. Flatten where possible.
- **Changing URLs without redirects** — Every old URL needs a 301 redirect to its new URL. Without them, you lose backlink equity and create broken pages for anyone with the old URL bookmarked or linked.
- **IDs in URLs** — `/product/12345` is not human-readable. Use slugs.
- **Query parameters for content** — `/blog?id=123` should be `/blog/post-title`.
- **Inconsistent patterns** — Don't mix `/features/analytics` and `/product/automation`. Pick one parent.

### Breadcrumb-URL Alignment

The breadcrumb trail should mirror the URL path:

| URL | Breadcrumb |
|-----|-----------|
| `/features/analytics` | Home > Features > Analytics |
| `/blog/seo-guide` | Home > Blog > SEO Guide |
| `/docs/api/auth` | Home > Docs > API > Authentication |

---

## Visual Sitemap Output (Mermaid)

Use Mermaid `graph TD` for visual sitemaps. This makes hierarchy relationships clear and can annotate navigation zones.

### Basic Hierarchy

```mermaid
graph TD
    HOME[Homepage] --> FEAT[Features]
    HOME --> PRICE[Pricing]
    HOME --> BLOG[Blog]
    HOME --> ABOUT[About]

    FEAT --> F1[Analytics]
    FEAT --> F2[Automation]
    FEAT --> F3[Integrations]

    BLOG --> B1[Post 1]
    BLOG --> B2[Post 2]
```

### With Navigation Zones

```mermaid
graph TD
    subgraph Header Nav
        HOME[Homepage]
        FEAT[Features]
        PRICE[Pricing]
        BLOG[Blog]
        CTA[Get Started]
    end

    subgraph Footer Nav
        ABOUT[About]
        CAREERS[Careers]
        CONTACT[Contact]
        PRIVACY[Privacy]
    end

    HOME --> FEAT
    HOME --> PRICE
    HOME --> BLOG
    HOME --> ABOUT

    FEAT --> F1[Analytics]
    FEAT --> F2[Automation]
```

**For more Mermaid templates**: See [references/mermaid-templates.md](references/mermaid-templates.md)

---

## Internal Linking Strategy

### Link Types

| Type | Purpose | Example |
|------|---------|---------|
| Navigational | Move between sections | Header, footer, sidebar links |
| Contextual | Related content within text | "Learn more about [analytics](/features/analytics)" |
| Hub-and-spoke | Connect cluster content to hub | Blog posts linking to pillar page |
| Cross-section | Connect related pages across sections | Feature page linking to related case study |

### Internal Linking Rules

1. **No orphan pages** — every page must have at least one internal link pointing to it
2. **Descriptive anchor text** — "our analytics features" not "click here"
3. **5-10 internal links per 1000 words** of content (approximate guideline)
4. **Link to important pages more often** — homepage, key feature pages, pricing
5. **Use breadcrumbs** — free internal links on every page
6. **Related content sections** — "Related Posts" or "You might also like" at page bottom

### Hub-and-Spoke Model

For content-heavy sites, organize around hub pages:

```
Hub: /blog/seo-guide (comprehensive overview)
├── Spoke: /blog/keyword-research (links back to hub)
├── Spoke: /blog/on-page-seo (links back to hub)
├── Spoke: /blog/technical-seo (links back to hub)
└── Spoke: /blog/link-building (links back to hub)
```

Each spoke links back to the hub. The hub links to all spokes. Spokes link to each other where relevant.

### Link Audit Checklist

- [ ] Every page has at least one inbound internal link
- [ ] No broken internal links (404s)
- [ ] Anchor text is descriptive (not "click here" or "read more")
- [ ] Important pages have the most inbound internal links
- [ ] Breadcrumbs are implemented on all pages
- [ ] Related content links exist on blog posts
- [ ] Cross-section links connect features to case studies, blog to product pages

---

## Output Format

When creating a site architecture plan, provide these deliverables:

### 1. Page Hierarchy (ASCII Tree)
Full site structure with URLs at each node. Use the ASCII tree format from the Page Hierarchy Design section.

### 2. Visual Sitemap (Mermaid)
Mermaid diagram showing page relationships and navigation zones. Use `graph TD` with subgraphs for nav zones where helpful.

### 3. URL Map Table

| Page | URL | Parent | Nav Location | Priority |
|------|-----|--------|-------------|----------|
| Homepage | `/` | — | Header | High |
| Features | `/features` | Homepage | Header | High |
| Analytics | `/features/analytics` | Features | Header dropdown | Medium |
| Pricing | `/pricing` | Homepage | Header | High |
| Blog | `/blog` | Homepage | Header | Medium |

### 4. Navigation Spec
- Header nav items (ordered, with CTA)
- Footer sections and links
- Sidebar nav (if applicable)
- Breadcrumb implementation notes

### 5. Internal Linking Plan
- Hub pages and their spokes
- Cross-section link opportunities
- Orphan page audit (if restructuring)
- Recommended links per key page

---

## Task-Specific Questions

1. Is this a new site or are you restructuring an existing one?
2. What type of site is it? (SaaS, content, e-commerce, docs, hybrid, small business)
3. How many pages exist or are planned?
4. What are the 5 most important pages on the site?
5. Are there existing URLs that need to be preserved or redirected?
6. Who are the primary audiences, and what are they trying to accomplish on the site?

---

## Related Skills

- **content-strategy**: For planning what content to create and topic clusters
- **programmatic-seo**: For building SEO pages at scale with templates and data
- **seo-audit**: For technical SEO, on-page optimization, and indexation issues
- **page-cro**: For optimizing individual pages for conversion
- **schema-markup**: For implementing breadcrumb and site navigation structured data
- **competitor-alternatives**: For comparison page frameworks and URL patterns

FILE:evals/evals.json
{
  "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-context.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-context.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": []
    }
  ]
}

FILE:references/mermaid-templates.md
# 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

FILE:references/navigation-patterns.md
# 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              │
│                                                          │
│  [Logo]  © 2026 Company Name                             │
│  Social: [Twitter] [LinkedIn] [GitHub]                   │
│                                                          │
└──────────────────────────────────────────────────────────┘
```

### Minimal Footer

Best for: simple sites, landing pages.

```
┌──────────────────────────────────────────────────────────┐
│  [Logo]                                                  │
│  © 2026 Company  ·  Privacy  ·  Terms  ·  Contact        │
└──────────────────────────────────────────────────────────┘
```

### 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                    │
│                                                          │
│  [Logo]  © 2026  ·  Privacy  ·  Terms  ·  Security      │
└──────────────────────────────────────────────────────────┘
```

---

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

```
Categories
  ├── SEO (24)
  ├── CRO (18)
  ├── Content (15)
  ├── Paid Ads (12)
  └── Analytics (9)

Popular Posts
  ├── How to Improve SEO
  ├── Landing Page Guide
  └── Analytics Setup

Newsletter
  └── [Email signup form]
```

---

## Breadcrumbs

### Standard Format

```
Home > Features > Analytics
Home > Blog > SEO Category > How to Do Keyword Research
Home > Docs > API Reference > Authentication
```

Rules:
- Separator: `>` or `/` (be consistent)
- Every segment is a link except the current page
- Current page is plain text (not linked)
- Don't include the current page if the title is already visible as an H1

### With Schema Markup

```html
<nav aria-label="Breadcrumb">
  <ol itemscope itemtype="https://schema.org/BreadcrumbList">
    <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
      <a itemprop="item" href="/"><span itemprop="name">Home</span></a>
      <meta itemprop="position" content="1" />
    </li>
    <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
      <a itemprop="item" href="/features"><span itemprop="name">Features</span></a>
      <meta itemprop="position" content="2" />
    </li>
    <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
      <span itemprop="name">Analytics</span>
      <meta itemprop="position" content="3" />
    </li>
  </ol>
</nav>
```

Or use JSON-LD (recommended):

```json
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" },
    { "@type": "ListItem", "position": 2, "name": "Features", "item": "https://example.com/features" },
    { "@type": "ListItem", "position": 3, "name": "Analytics" }
  ]
}
```

---

## Mobile Navigation

### Hamburger Menu

Standard for mobile. All nav items collapse into a menu icon.

Rules:
- Hamburger icon (three lines) top-right or top-left
- Full-screen or slide-out panel
- CTA button visible without opening the menu (sticky header)
- Search accessible from mobile menu
- Accordion pattern for nested items

### Bottom Tab Bar

Best for: web apps, PWAs, mobile-first products.

```
┌──────────────────────────────────────┐
│                                      │
│           [Page Content]             │
│                                      │
├──────────────────────────────────────┤
│  Home    Search    Create    Profile │
│   🏠       🔍        ➕       👤    │
└──────────────────────────────────────┘
```

Rules:
- 3-5 items max
- Icons + labels (not just icons)
- Active state clearly indicated
- Most important action in the center

---

## Anti-Patterns

### Things to Avoid

- **Too many header items** (8+): causes decision paralysis, nav becomes unreadable on smaller screens
- **Dropdown inception**: dropdowns inside dropdowns inside dropdowns
- **Mystery icons**: icons without labels — users don't know what they mean
- **Hidden primary nav**: burying important pages in hamburger menus on desktop
- **Inconsistent nav between pages**: nav should be identical across the site (except app vs marketing)
- **No mobile consideration**: desktop nav that doesn't translate to mobile
- **Footer as sitemap dump**: 50+ links in the footer with no organization
- **Breadcrumbs that don't match URLs**: breadcrumb says "Products > Widget" but URL is `/shop/widget-pro`

### Common Fixes

| Problem | Fix |
|---------|-----|
| Too many nav items | Group into dropdowns or mega menus |
| Users can't find pages | Add search, improve labeling |
| High bounce from nav | Simplify choices, use clearer labels |
| SEO pages not linked | Add to footer or resource sections |
| Mobile nav is broken | Test on real devices, use hamburger pattern |

---

## Navigation for SEO

Internal links in navigation pass PageRank. Use this strategically:

- **Header nav links are strongest** — put your most important pages here
- **Footer links pass less value** but still matter — good for comparison pages, location pages
- **Sidebar links** help with section-level authority — good for blog categories, doc sections
- **Breadcrumbs** provide structural signals to search engines — implement with schema markup
- **Don't use JavaScript-only nav** — search engines need crawlable HTML links
- **Use descriptive anchor text** — "Analytics Features" not just "Features"

FILE:references/site-type-templates.md
# Site Type Templates

Full page hierarchy templates with ASCII trees, URL maps, and navigation recommendations for common site types.

---

## SaaS Marketing Site

### Page Hierarchy

```
Homepage (/)
├── Features (/features)
│   ├── Feature A (/features/feature-a)
│   ├── Feature B (/features/feature-b)
│   └── Feature C (/features/feature-c)
├── Pricing (/pricing)
├── Customers (/customers)
│   ├── Case Study 1 (/customers/company-name)
│   └── Case Study 2 (/customers/company-name-2)
├── Resources (/resources)
│   ├── Blog (/blog)
│   │   └── [Posts] (/blog/post-slug)
│   ├── Templates (/resources/templates)
│   │   └── [Template] (/resources/templates/template-slug)
│   └── Guides (/resources/guides)
│       └── [Guide] (/resources/guides/guide-slug)
├── Integrations (/integrations)
│   └── [Integration] (/integrations/integration-name)
├── Docs (/docs)
│   ├── Getting Started (/docs/getting-started)
│   ├── Guides (/docs/guides)
│   └── API Reference (/docs/api)
├── About (/about)
│   ├── Careers (/about/careers)
│   └── Contact (/contact)
├── Compare (/compare)
│   └── [Competitor] (/compare/competitor-name)
├── Privacy (/privacy)
└── Terms (/terms)
```

### URL Map

| Page | URL | Nav Location | Priority |
|------|-----|-------------|----------|
| Homepage | `/` | Header (logo) | Critical |
| Features | `/features` | Header | High |
| Feature pages | `/features/{slug}` | Header dropdown | Medium |
| Pricing | `/pricing` | Header | Critical |
| Customers | `/customers` | Header | Medium |
| Case studies | `/customers/{slug}` | Customers dropdown | Medium |
| Blog | `/blog` | Header (Resources) | High |
| Blog posts | `/blog/{slug}` | — | Medium |
| Integrations | `/integrations` | Header | Medium |
| Docs | `/docs` | Header | Medium |
| Compare | `/compare/{slug}` | Footer | High (SEO) |
| About | `/about` | Footer | Low |
| Pricing CTA | `/pricing` | Header (CTA button) | Critical |

### Navigation

**Header (6 items + CTA)**: Features | Pricing | Customers | Resources | Integrations | Docs | [Get Started]

**Footer columns**:
- Product: Features, Pricing, Integrations, Changelog, Security
- Resources: Blog, Templates, Guides, Case Studies
- Company: About, Careers, Contact, Press
- Legal: Privacy, Terms, Security

---

## Content / Blog Site

### Page Hierarchy

```
Homepage (/)
├── Blog (/blog)
│   ├── [Category: Topic A] (/blog/category/topic-a)
│   ├── [Category: Topic B] (/blog/category/topic-b)
│   ├── [Category: Topic C] (/blog/category/topic-c)
│   └── [Posts] (/blog/post-slug)
├── Newsletter (/newsletter)
├── Resources (/resources)
│   ├── Guides (/resources/guides)
│   │   └── [Guide] (/resources/guides/guide-slug)
│   └── Tools (/resources/tools)
│       └── [Tool] (/resources/tools/tool-slug)
├── About (/about)
├── Contact (/contact)
├── Privacy (/privacy)
└── Terms (/terms)
```

### URL Map

| Page | URL | Nav Location | Priority |
|------|-----|-------------|----------|
| Homepage | `/` | Header (logo) | Critical |
| Blog index | `/blog` | Header | High |
| Categories | `/blog/category/{slug}` | Header dropdown | Medium |
| Posts | `/blog/{slug}` | — | Medium |
| Newsletter | `/newsletter` | Header (CTA) | High |
| Guides | `/resources/guides` | Header | Medium |
| About | `/about` | Header | Low |

### Navigation

**Header (4 items + CTA)**: Blog | Resources | About | Contact | [Subscribe]

**Sidebar** (on blog): Categories, Popular Posts, Newsletter signup

---

## E-Commerce

### Page Hierarchy

```
Homepage (/)
├── Shop (/shop)
│   ├── Category A (/shop/category-a)
│   │   ├── Subcategory (/shop/category-a/subcategory)
│   │   │   └── [Product] (/shop/category-a/subcategory/product-slug)
│   │   └── [Product] (/shop/category-a/product-slug)
│   ├── Category B (/shop/category-b)
│   │   └── [Product] (/shop/category-b/product-slug)
│   └── Category C (/shop/category-c)
│       └── [Product] (/shop/category-c/product-slug)
├── Collections (/collections)
│   └── [Collection] (/collections/collection-slug)
├── Sale (/sale)
├── Blog (/blog)
│   └── [Posts] (/blog/post-slug)
├── About (/about)
│   └── Our Story (/about/our-story)
├── Help (/help)
│   ├── FAQ (/help/faq)
│   ├── Shipping (/help/shipping)
│   ├── Returns (/help/returns)
│   └── Contact (/contact)
├── Cart (/cart)
├── Account (/account)
├── Privacy (/privacy)
└── Terms (/terms)
```

### URL Map

| Page | URL | Nav Location | Priority |
|------|-----|-------------|----------|
| Homepage | `/` | Header (logo) | Critical |
| Shop | `/shop` | Header | Critical |
| Categories | `/shop/{category}` | Header mega menu | High |
| Products | `/shop/{category}/{product}` | — | High |
| Collections | `/collections/{slug}` | Header | Medium |
| Sale | `/sale` | Header (highlighted) | High |
| Cart | `/cart` | Header (icon) | Critical |
| Account | `/account` | Header (icon) | Medium |

### Navigation

**Header (5 items + cart/account)**: Shop (mega menu) | Collections | Sale | Blog | Help | [Cart icon] [Account icon]

**Mega menu under Shop**: Category columns with featured products/images

---

## Documentation Site

### Page Hierarchy

```
Docs Home (/docs)
├── Getting Started (/docs/getting-started)
│   ├── Installation (/docs/getting-started/installation)
│   ├── Quick Start (/docs/getting-started/quick-start)
│   └── Configuration (/docs/getting-started/configuration)
├── Guides (/docs/guides)
│   ├── Guide A (/docs/guides/guide-a)
│   ├── Guide B (/docs/guides/guide-b)
│   └── Guide C (/docs/guides/guide-c)
├── API Reference (/docs/api)
│   ├── Authentication (/docs/api/authentication)
│   ├── Endpoints (/docs/api/endpoints)
│   └── Webhooks (/docs/api/webhooks)
├── Examples (/docs/examples)
│   └── [Example] (/docs/examples/example-slug)
├── Changelog (/docs/changelog)
└── FAQ (/docs/faq)
```

### URL Map

| Page | URL | Nav Location | Priority |
|------|-----|-------------|----------|
| Docs home | `/docs` | Header | High |
| Getting Started | `/docs/getting-started` | Sidebar (top) | Critical |
| Guides | `/docs/guides` | Sidebar | High |
| API Reference | `/docs/api` | Sidebar | High |
| Changelog | `/docs/changelog` | Sidebar (bottom) | Low |

### Navigation

**Header**: Docs | API | Blog | Community | GitHub | [Dashboard]

**Sidebar** (persistent, left): Getting Started, Guides, API Reference, Examples, Changelog — with expandable subsections

**On-page**: Previous/Next navigation at bottom of each doc page

---

## Hybrid SaaS + Content

### Page Hierarchy

```
Homepage (/)
├── Product (/product)
│   ├── Feature A (/product/feature-a)
│   ├── Feature B (/product/feature-b)
│   └── Feature C (/product/feature-c)
├── Solutions (/solutions)
│   ├── By Use Case (/solutions/use-case-slug)
│   └── By Industry (/solutions/industry-slug)
├── Pricing (/pricing)
├── Blog (/blog)
│   ├── [Category] (/blog/category/slug)
│   └── [Posts] (/blog/post-slug)
├── Resources (/resources)
│   ├── Guides (/resources/guides)
│   ├── Templates (/resources/templates)
│   ├── Webinars (/resources/webinars)
│   └── Case Studies (/resources/case-studies)
├── Docs (/docs)
│   ├── Getting Started (/docs/getting-started)
│   └── API (/docs/api)
├── Integrations (/integrations)
│   └── [Integration] (/integrations/slug)
├── Compare (/compare)
│   └── [Competitor] (/compare/competitor-slug)
├── About (/about)
│   ├── Careers (/about/careers)
│   └── Contact (/contact)
├── Privacy (/privacy)
└── Terms (/terms)
```

### Navigation

**Header (7 items + CTA)**: Product | Solutions | Pricing | Resources | Blog | Docs | Integrations | [Start Free Trial]

Use mega menus for Product (features list), Solutions (use cases + industries), and Resources (blog, guides, templates, webinars, case studies).

---

## Small Business / Local

### Page Hierarchy

```
Homepage (/)
├── Services (/services)
│   ├── Service A (/services/service-a)
│   ├── Service B (/services/service-b)
│   └── Service C (/services/service-c)
├── About (/about)
├── Testimonials (/testimonials)
├── Blog (/blog)
│   └── [Posts] (/blog/post-slug)
├── Contact (/contact)
├── Privacy (/privacy)
└── Terms (/terms)
```

### URL Map

| Page | URL | Nav Location | Priority |
|------|-----|-------------|----------|
| Homepage | `/` | Header (logo) | Critical |
| Services | `/services` | Header | High |
| Service pages | `/services/{slug}` | Header dropdown | High |
| About | `/about` | Header | Medium |
| Testimonials | `/testimonials` | Header | Medium |
| Blog | `/blog` | Header | Medium |
| Contact | `/contact` | Header (CTA) | High |

### Navigation

**Header (5 items + CTA)**: Services | About | Testimonials | Blog | [Contact Us]

Keep it simple. Small business sites should be flat (1-2 levels max). Every page should be reachable from the header.

ClawHub Marketing Documentation+2

M@clawhub-mariokarras-f59a320bef

Competitor Alternatives

Skill

When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'v...

---
name: competitor-alternatives
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: 1.1.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:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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 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

### Automated Research with Exa

Use Exa to find competitor information, positioning, and market presence:

```bash
exa.js search "competitor name + product category"
exa.js search "competitor name alternatives"
exa.js search "competitor name reviews site:g2.com OR site:capterra.com"
```

Use this to quickly gather competitive intelligence before doing deeper manual research.

### 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-markup**: For FAQ and comparison schema
- **sales-enablement**: For internal sales collateral, decks, and objection docs

FILE:evals/evals.json
{
  "skill_name": "competitor-alternatives",
  "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-context.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-context.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": []
    }
  ]
}

FILE:references/content-architecture.md
# 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
name: Notion
website: notion.so
tagline: "The all-in-one workspace"
founded: 2016
headquarters: San Francisco

# Positioning
primary_use_case: "docs + light databases"
target_audience: "teams wanting flexible workspace"
market_position: "premium, feature-rich"

# Pricing
pricing_model: per-seat
free_tier: true
free_tier_limits: "limited blocks, 1 user"
starter_price: $8/user/month
business_price: $15/user/month
enterprise: custom

# Features (rate 1-5 or describe)
features:
  documents: 5
  databases: 4
  project_management: 3
  collaboration: 4
  integrations: 3
  mobile_app: 3
  offline_mode: 2
  api: 4

# Strengths (be honest)
strengths:
  - Extremely flexible and customizable
  - Beautiful, modern interface
  - Strong template ecosystem
  - Active community

# Weaknesses (be fair)
weaknesses:
  - Can be slow with large databases
  - Learning curve for advanced features
  - Limited automations compared to dedicated tools
  - Offline mode is limited

# Best for
best_for:
  - Teams wanting all-in-one workspace
  - Content-heavy workflows
  - Documentation-first teams
  - Startups and small teams

# Not ideal for
not_ideal_for:
  - Complex project management needs
  - Large databases (1000s of rows)
  - Teams needing robust offline
  - Enterprise with strict compliance

# Common complaints (from reviews)
common_complaints:
  - "Gets slow with lots of content"
  - "Hard to find things as workspace grows"
  - "Mobile app is clunky"

# Migration notes
migration_from:
  difficulty: medium
  data_export: "Markdown, CSV, HTML"
  what_transfers: "Pages, databases"
  what_doesnt: "Automations, integrations setup"
  time_estimate: "1-3 days for small team"
```

---

## Your Product Data

Same structure for yourself—be honest:

```yaml
name: [Your Product]
# ... same fields

strengths:
  - [Your real strengths]

weaknesses:
  - [Your honest weaknesses]

best_for:
  - [Your ideal customers]

not_ideal_for:
  - [Who should use something else]
```

---

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

FILE:references/templates.md
# 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]
- [Data type]: [How easily, any caveats]

### What needs reconfiguration
- [Thing]: [Why and effort level]
- [Thing]: [Why and effort level]

### Migration support

We offer [migration support details]:
- [Free data import tool / white-glove migration]
- [Documentation / migration guide]
- [Timeline expectation]
- [Support during transition]

### What customers say about switching

> "[Quote from customer who switched]"
> — [Name], [Role] at [Company]
```

---

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

| Category | You | Competitor | Notes |
|----------|-----|-----------|-------|
| Ease of use | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | [Brief note] |
| Feature depth | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | [Brief note] |

ClawHub Writing Marketing+2

M@clawhub-mariokarras-f59a320bef

Free Tool Strategy

Skill

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

---
name: free-tool-strategy
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 content-based lead generation, see content-strategy.
metadata:
  version: 1.1.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:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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 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

- **page-cro**: For optimizing the tool's landing page
- **seo-audit**: For SEO-optimizing the tool
- **analytics-tracking**: For measuring tool usage
- **email-sequence**: For nurturing leads from the tool

FILE:evals/evals.json
{
  "skill_name": "free-tool-strategy",
  "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-context.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-context.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 page-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 page-cro is the right skill for page conversion optimization.",
      "assertions": [
        "Recognizes this as page CRO, not free tool strategy",
        "References or defers to page-cro skill",
        "May provide free-tool-specific context",
        "Does not attempt full page CRO using free tool strategy patterns"
      ],
      "files": []
    }
  ]
}

FILE:references/tool-types.md
# 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

ClawHub Coding Marketing+2

M@clawhub-mariokarras-f59a320bef

Revops

Skill

When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes. Also use when the user mentions 'RevOps...

---
name: revops
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 email-sequence. For pricing decisions, see pricing-strategy."
metadata:
  version: 1.1.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:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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.

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

| Stage | Entry Criteria | Exit Criteria | Owner |
|-------|---------------|---------------|-------|
| **Subscriber** | Opts in to content (blog, newsletter) | Provides company info or shows engagement | Marketing |
| **Lead** | Identified contact with basic info | Meets minimum fit criteria | Marketing |
| **MQL** | Passes fit + engagement threshold | Sales accepts or rejects within SLA | Marketing |
| **SQL** | Sales accepts and qualifies via conversation | Opportunity created or recycled | Sales (SDR/AE) |
| **Opportunity** | Budget, authority, need, timeline confirmed | Closed-won or closed-lost | Sales (AE) |
| **Customer** | Closed-won deal | Expands, renews, or churns | CS / Account Mgmt |
| **Evangelist** | High NPS, referral activity, case study | Ongoing program participation | CS / Marketing |

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

---

## Related Skills

- **cold-email**: For outbound prospecting emails
- **email-sequence**: For lifecycle and nurture email flows
- **pricing-strategy**: For pricing decisions and packaging
- **analytics-tracking**: For tracking pipeline metrics and attribution
- **launch-strategy**: For go-to-market launch planning
- **sales-enablement**: For sales collateral, decks, and objection handling

FILE:evals/evals.json
{
  "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-context.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-context.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": []
    }
  ]
}

FILE:references/automation-playbooks.md
# 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

FILE:references/lifecycle-definitions.md
# 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)

FILE:references/routing-rules.md
# 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

| Tier | Account Type | Routing | Response SLA |
|------|-------------|---------|--------------|
| Tier 1 | Top 20 strategic accounts | Named owner, instant alert | 1 hour |
| Tier 2 | Top 100 target accounts | Named owner, standard alert | 4 hours |
| Tier 3 | Target industry / size match | Territory or round-robin | Same business day |

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

FILE:references/scoring-models.md
# 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

ClawHub Research Writing+2

M@clawhub-mariokarras-f59a320bef

Sales Enablement

Skill

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

---
name: sales-enablement
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 competitor-alternatives. For marketing website copy, see copywriting. For cold outreach emails, see cold-email."
metadata:
version: 1.1.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

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?

---

## Related Skills

- **competitor-alternatives**: 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-strategy**: For pricing decisions and packaging
- **product-marketing-context**: For foundational positioning and messaging

FILE:evals/evals.json
{
"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-context.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-context.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 competitor-alternatives skill, which handles public comparison and alternatives pages. Sales-enablement covers internal materials (battle cards, objection handling) while competitor-alternatives handles SEO-focused public comparison content.",
"assertions": [
"Recognizes this as a public comparison page",
"References or defers to competitor-alternatives skill",
"Explains the distinction between internal and public collateral",
"Does not attempt public SEO comparison page using sales enablement patterns"
],
"files": []
}
]
}

FILE:references/deck-frameworks.md
# 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.

FILE:references/demo-scripts.md
# 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.

FILE:references/objection-library.md
# 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?"

FILE:references/one-pager-templates.md
# 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: [email protected]]
```

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

ClawHub Research Writing+2

M@clawhub-mariokarras-f59a320bef

Product Marketing Context

Skill

When the user wants to create or update their product marketing context document. Also use when the user mentions 'product context,' 'service context,' 'mark...

---
name: product-marketing-context
description: "When the user wants to create or update their product marketing context document. Also use when the user mentions 'product context,' 'service context,' 'marketing context,' 'set up context,' 'positioning,' 'who is my target audience,' 'describe my product,' 'describe my service,' 'ICP,' 'ideal customer profile,' or wants to avoid repeating foundational information across marketing tasks. Works for products, services, or hybrid offerings — B2B and B2C. Use this at the start of any new project before using other marketing skills — it creates `.agents/product-marketing-context.md` that all other skills reference for offering, 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. Works for products, services, or hybrid offerings — B2B and B2C alike.

The document is stored at `.agents/product-marketing-context.md`.

## Workflow

### Step 1: Check for Existing Context

First, check if `.agents/product-marketing-context.md` already exists. Also check `.claude/product-marketing-context.md` for older setups — if found there but not in `.agents/`, offer to move it.

**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 using the right question format (see below)
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.

**Question design — reduce friction, get better answers:**
- **Select one**: When a field has known options (stage, offering type, business model), present them as a lettered list: "(a) ... (b) ... (c) ...". Faster than open-ended, and the user can still say something different.
- **Select all that apply**: When multiple values are valid (discovery channels, pain cost types), present common options as a numbered or bulleted list and ask the user to pick all that apply, plus "other." In the sections below, ☐ marks indicate the options to present — format them as a clean list for the user, not inline.
- **Finish this sentence**: When users freeze on open-ended questions, offer a fill-in-the-blank: "We help ___ do ___ so they can ___." This scaffolds without constraining.
- **Constraining prompts**: When answers tend to sprawl, add a length constraint: "In one sentence..." or "Pick your top 3."
- **Spectrum selection**: When capturing degree/preference, offer a scale: "Where do you fall? More formal ← → more casual."
- **Examples as anchors**: Show one concrete example of a good answer before asking, especially for open-ended fields. This sets the bar and unblocks the user.
- **Confirm by summarizing**: After each section, summarize what you captured in 2-3 sentences and ask: "Does this capture it? Anything to adjust?" Don't just say "confirm."
- **Stay conversational**: These patterns are tools to reach for, not a rigid form. If the user gives a rich, detailed answer unprompted, don't force them through a select-all list — capture what they said and move on. Use structured prompts when the user seems stuck, gives a vague answer, or needs help articulating what they mean.
- Don't use all patterns in every section — match the pattern to the question type. Sections below use `→ *pattern*:` annotations to indicate which pattern to use — these are instructions for you, not text to show the user.

**Important: Adapt to offering type.** Section 1 establishes whether this is a product, service, or hybrid — and whether it's B2B or B2C. Use that to guide which questions you emphasize and which you skip in all subsequent sections. Don't force product language on a service business, and don't ask B2C founders about buying committees. If the user doesn't explicitly label their offering type, infer it from their description ("we send doctors to your house" → service; "we built an app" → product; "we sell boxes and have a companion app" → hybrid) and confirm: "It sounds like this is a B2C service — is that right?"

**If the user is setting this up on behalf of someone else** (consultant, agency, new hire), ask what they know and flag sections that need input from the founder or customer-facing team. Mark those sections as "[needs founder input]" in the output.

---

## Sections to Capture

**Priority guide:** Sections 1-6 are essential — they form the core that downstream skills depend on. Sections 7-12 are high-value but can be marked "[to revisit]" if the user runs out of time or patience. Always capture 1-6 before moving to 7-12.

### 1. Offering Overview
- Company or brand name
- One-line description → *finish this sentence*: "We help ___ do ___ so they can ___."
- What it does (2-3 sentences) → *constraining prompt*: "Explain what you do as if you had 30 seconds with a stranger."
- Why it exists — the founding insight or personal experience that sparked this, and what makes the team uniquely qualified (this often becomes your most powerful marketing story)
- Category → *finish this sentence*: "When someone searches for what we do, they'd type ___." (This is the "shelf" you sit on.)
- Offering type → *select one*: (a) Product (b) Service (c) Hybrid — then give an example: "e.g., SaaS, home tutoring service, subscription box + companion app"
- Business model → *select one + details*: (a) Subscription/SaaS (b) One-time purchase (c) Freemium (d) Marketplace/commission (e) Retainer/hourly (f) Pay-per-use (g) Other — then ask for price points or tiers
- Stage → *select one*: (a) Pre-launch (b) Early traction (c) Growth (d) Established — this shapes what proof points and strategies are credible
- For services: delivery model → *select one*: (a) On-demand (b) Scheduled (c) Subscription (d) Retainer — and coverage area if relevant

### 2. Target Audience

Adapt these fields based on offering type:

**For B2B:**
- Target company type (industry, size, stage)
- Target decision-makers (roles, departments)

**For B2C:**
- Target customer segments (demographics, life stage, situation)
- Who makes the decision — often the user themselves, but not always (e.g., a family member choosing home care for a parent, a parent choosing a tutor for a child)

**For all:**
- Primary use case → *finish this sentence*: "Most customers come to us because they need to ___."
- Jobs to be done → *constraining prompt*: "Name 2-3 things customers 'hire' you to do for them."
- Specific use cases or scenarios
- How they find you → *select all that apply*:
  ☐ Google search ☐ Word-of-mouth ☐ Professional referral
  ☐ Social media ☐ Communities/forums ☐ Content/blog
  ☐ Paid ads ☐ Events/trade shows ☐ App store ☐ Other: ___
- Where they spend time → *select all + add your own* (online and offline):
  ☐ LinkedIn ☐ Facebook groups ☐ Reddit ☐ Twitter/X
  ☐ YouTube ☐ TikTok ☐ Industry forums
  ☐ Conferences/trade shows ☐ Professional associations
  ☐ Specific communities: ___ ☐ Offline locations: ___
- How they buy → *ask for a step-by-step journey*: "Walk me through how a customer goes from 'I have this problem' to choosing you. What are the steps?" Show an example: "e.g., Google search → read reviews → book a demo → free trial → purchase." Then ask: Is this typically a quick decision (minutes/hours) or a long consideration (days/weeks/months)?

### 3. Personas
Capture 2-4 distinct personas — the people who interact with your offering. Think about who uses it, who pays for it, and who influences the choice — these may be different people.

**For B2B** — organizational buying roles:
- User, Champion, Decision Maker, Financial Buyer, Technical Influencer

**For B2C** — user segments and decision stakeholders:
- e.g., Primary user, Family decision-maker, Referring professional, Gift buyer
- For services especially, the person receiving the service and the person choosing/paying may differ

For each persona, capture: what they care about, their challenge, and the value you promise them.

*Example*: "The Family Decision-Maker — cares about safety and trust, challenged by navigating confusing care options, we promise peace of mind and vetted professionals."

### 4. Problems & Pain Points
- Core challenge → *finish this sentence*: "Before finding us, customers were stuck because ___."
- Why current solutions or alternatives fall short
- What it costs them → *select all that apply, then ask "which is the biggest?"*:
  ☐ Time ☐ Money ☐ Health/wellbeing ☐ Peace of mind
  ☐ Missed opportunities ☐ Reputation ☐ Relationships ☐ Other: ___
- Emotional tension → *select all that apply*:
  ☐ Frustration ☐ Anxiety/worry ☐ Overwhelm ☐ Distrust
  ☐ Guilt ☐ Embarrassment ☐ Fear ☐ Helplessness ☐ Other: ___
- For services: what's broken about the current experience → *select all that apply*:
  ☐ Hard to access ☐ Long wait times ☐ Can't trust quality
  ☐ Inconvenient ☐ Impersonal ☐ Too expensive ☐ Poor communication ☐ Other: ___

### 5. Competitive Landscape

Help the user think in three tiers — show examples for each to unblock them:

- **Direct competitors**: Same solution, same problem (e.g., Calendly vs SavvyCal, or one dog-walking service vs another)
- **Secondary competitors**: Different solution, same problem (e.g., dog-walking service vs doggy daycare)
- **Indirect competitors**: Conflicting approach or inaction (e.g., dog-walking service vs "just let the dog out in the yard")
- For each: "How does this option fall short for your customers?"

*Prompt*: "Name 1-2 for each tier. If you're not sure, think about what your customers were doing before they found you — that's your indirect competitor."

### 6. Differentiation
- Key differentiators (capabilities or qualities alternatives lack) → *constraining prompt*: "Name your top 3 differentiators — things competitors can't or don't offer."
- How you solve it differently
- Why that's better (benefits)
- Why customers choose you over alternatives → *finish this sentence*: "Customers pick us over alternatives because ___."
- For services: what makes the experience different → *select all that apply*:
  ☐ More convenient ☐ More trustworthy ☐ Better credentials
  ☐ Higher quality ☐ Faster ☐ Easier access
  ☐ More personalized ☐ Better communication ☐ Other: ___

### 7. Objections & Anti-Personas
- Top 3 objections → *show common categories to jog memory*: "What pushback do you hear? Common ones include: price ('too expensive'), trust ('how do I know it works?'), switching cost ('too hard to change'), timing ('not now'), complexity ('seems complicated'), risk ('what if it doesn't work?'). What are your top 3?"
- For each objection, ask: "How do you respond to that?"
- Who is NOT a good fit (anti-persona) → *ask directly*: "Describe a customer you'd turn away. Who wastes your time or churns fast?"

### 8. Switching Dynamics
Compile the JTBD Four Forces from what you've already captured — do NOT re-ask questions the user already answered:
- **Push** ← pull from Section 4 (pain points, emotional tension, what it costs them)
- **Pull** ← pull from Section 6 (differentiators, why customers choose you)
- **Habit** ← what keeps them stuck (often not yet captured — ask if missing)
- **Anxiety** ← what worries them about switching (often not yet captured — ask if missing)

Present your compiled draft of all four forces and ask: "Does this capture the dynamics? What's missing?" Only probe for Habit and Anxiety directly — Push and Pull should already be covered.

### 9. Customer Language
- How customers describe the problem → *finish this sentence*: "A customer would tell a friend: 'I was struggling with ___ and then I found ___.'"
- How they describe your solution (verbatim) → ask: "When customers recommend you, what do they actually say? Not your marketing — their words."
- Words/phrases to use → ask: "What words does your audience use? What resonates?"
- Words/phrases to avoid → ask: "Any words that would make your audience cringe or tune out?"
- Glossary of key terms specific to your offering

For early-stage companies with few customers: "How would your ideal customer describe this problem to a friend? Just make it up — what would they say?"

### 10. Brand Voice
- Brand personality: "If your brand were a person, how would you describe them?" (3-5 adjectives, but push for a one-sentence character sketch too)
- Voice attributes (pick 2-3 core attributes — `/brand-voice` expands to 3-5 with full examples): for each, capture what it means and what it does NOT mean. E.g., "Approachable — friendly and jargon-free, but not dumbed-down or overly casual"
- Tone direction → *spectrum selection*: "Where do you fall on each? (a) Formal ← → Casual (b) Technical ← → Accessible (c) Bold ← → Measured (d) Warm ← → Direct"
- Voice do's and don'ts (1-2 each): e.g., "We explain, we don't lecture" or "We're confident, never arrogant"
- Sample sentence: ask for one sentence that sounds like the brand at its best — this is the most useful reference for downstream skills
- Tone shifts: does the voice change for different audiences or channels? (e.g., warmer with patients, more clinical with referring doctors; casual on social, professional in email)

**When is this section enough?** For most teams, these essentials are sufficient — downstream skills can produce consistent content from this. Run `/brand-voice` when you need grammar/style rules, detailed terminology governance, channel-by-channel tone tables, or have multiple writers who need a shared reference document.

### 11. Proof Points
- What proof do you have? → *select all that apply*:
  ☐ Metrics/results (revenue, users, growth) ☐ Customer logos ☐ Case studies
  ☐ Testimonials/quotes ☐ Ratings/reviews ☐ Certifications/credentials
  ☐ Awards ☐ Press/media mentions ☐ Research/data
  ☐ Founder expertise ☐ Pilot/beta results ☐ Waitlist size ☐ Other: ___
- For each type selected, ask for specifics
- Main value themes and supporting evidence

For early-stage: "What proof do you have so far, even if small? Anything counts — beta user feedback, waitlist numbers, founder credentials, a pilot result."

### 12. Goals
- Primary business goal → *select one or two*: (a) Grow revenue (b) Acquire customers/users (c) Increase retention (d) Build awareness/brand (e) Enter new market (f) Launch new offering (g) Raise funding (h) Other: ___
- Key conversion action → *select one*: What's the #1 thing you want someone to do? (a) Sign up / create account (b) Start free trial (c) Book a demo/call (d) Make a purchase (e) Request a quote (f) Download something (g) Join waitlist (h) Subscribe (i) Other: ___
- Current metrics (if known) — ask: "Any numbers you're tracking? Revenue, users, conversion rate, traffic — whatever you have."

---

## Step 3: Create the Document

After gathering information, create `.agents/product-marketing-context.md` with this structure:

```markdown
# Product Marketing Context

*Last updated: [date]*

## Offering Overview
**Company/brand:**
**One-liner:**
**What it does:**
**Why it exists:**
**Category:**
**Offering type:**
**Stage:**
**Business model & pricing:**
**Delivery model:** *(if service/hybrid)*
**Coverage area:** *(if service/hybrid)*

## Target Audience
**Target customers:**
**Who decides:**
**How they find us:**
**Where they spend time:**
**How they buy:**
**Primary use case:**
**Jobs to be done:**
-
**Use cases:**
-

## Personas
| Persona | Cares about | Challenge | Value we promise |
|---------|-------------|-----------|------------------|
| | | | |

## Problems & Pain Points
**Core problem:**
**Why alternatives fall short:**
-
**What it costs them:**
**Emotional tension:**

## Competitive Landscape
**Direct:** [Competitor] — falls short because...
**Secondary:** [Approach] — falls short because...
**Indirect:** [Alternative] — falls short because...

## Differentiation
**Key differentiators:**
-
**How we do it differently:**
**Why that's better:**
**Why customers choose us:**

## Objections
| Objection | Response |
|-----------|----------|
| | |

**Anti-persona:**

## Switching Dynamics
**Push:**
**Pull:**
**Habit:**
**Anxiety:**

## Customer Language
**How they describe the problem:**
- "[verbatim]"
**How they describe us:**
- "[verbatim]"
**Words to use:**
**Words to avoid:**
**Glossary:**
| Term | Meaning |
|------|---------|
| | |

## Brand Voice
**Personality:** [3-5 adjectives + one-sentence character sketch]
**Voice attributes:**
| Attribute | We are | We are not |
|-----------|--------|------------|
| | | |
**Tone direction:**
**Voice do's:**
**Voice don'ts:**
**Sample sentence:**
**Tone shifts:** [how voice adapts by audience or channel]

## Proof Points
**Metrics:**
**Customers/Credentials:**
**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-context.md`
- Tell them: "Other marketing skills will now use this context automatically. Run `/product-marketing-context` 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 offering needs all sections — adapt to the offering type
- **Adapt to the offering**: For services, lean into trust, access, experience, and relationship. For products, lean into features, capabilities, and integrations. Hybrid offerings need both. Let offering type (from Section 1) guide your emphasis throughout.
- **Match depth to stage**: Pre-launch companies will have sparse Proof Points and Customer Language — that's fine. Capture what exists and mark gaps to revisit later.

FILE:evals/evals.json
{
  "skill_name": "product-marketing-context",
  "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-context.md already exists. If not, should offer two options: (1) Auto-draft from codebase (recommended) or (2) Start from scratch. Should ask for the company/brand name early. If user chooses start from scratch, should walk through sections conversationally one at a time. Should cover all applicable sections: Offering Overview, Target Audience, Personas (B2B buying committee), Problems & Pain Points, Competitive Landscape, Differentiation, Objections, Switching Dynamics (compiled from earlier sections, not re-asked), Customer Language, Brand Voice, Proof Points, and Goals. Should create the file at .agents/product-marketing-context.md when complete.",
      "assertions": [
        "Checks for existing product-marketing-context.md",
        "Offers two options: auto-draft or start from scratch",
        "Asks for company/brand name",
        "Covers applicable sections",
        "Walks through sections conversationally one at a time",
        "Uses B2B persona roles (User, Champion, Decision Maker, etc.)",
        "Compiles Switching Dynamics from earlier sections rather than re-asking",
        "Uses structured prompts where indicated (select-one for stage/offering type/business model, finish-this-sentence for one-liner, select-all-that-apply for discovery channels)",
        "Creates file at .agents/product-marketing-context.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-context.md and read it. Should identify which sections need updating based on the changes: Target Audience (add VP of Engineering), Personas (add new persona), Offering 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-context.md",
        "Identifies sections that need updating",
        "Updates Target Audience with VP of Engineering",
        "Adds new persona for the expanded audience",
        "Updates Offering 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 adapt Personas for B2C user segments (e.g., casual hiker, serious hiker) rather than B2B buying committee. Should accept lighter answers for sections like Proof Points or Customer Language, offering the 'how would your ideal customer describe this to a friend?' prompt if verbatim quotes aren't available.",
      "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",
        "Adapts Personas for B2C user segments",
        "Uses early-stage fallback prompts for Customer Language and Proof Points",
        "Creates file at .agents/product-marketing-context.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-context.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-context.md (and the older .claude/product-marketing-context.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, page-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": "set up our marketing context. we're launching a home healthcare service — doctors come to your house. it's B2C but families often make the decision for elderly parents. it's a service, not a product.",
      "expected_output": "Should recognize this as a B2C service offering. Should ask for company/brand name. Should capture offering type as 'service' and ask about delivery model (on-demand, scheduled) and coverage area. Should ask about the founding insight — why does this service exist, what personal or professional experience sparked it, and what makes the team qualified. Should capture stage (launching = early/pre-launch). Should adapt Target Audience for consumer segments (patients, elderly, families) rather than companies/departments. Should ask about the buying journey (how does a family go from 'mom needs help' to booking the first visit). Should capture 2-4 personas even though it's B2C — the patient, the family decision-maker (e.g., adult child arranging care for parent), and possibly referring physicians. Should compile Switching Dynamics from earlier sections (trust/relationship framing from Problems and Objections), only asking follow-up about Habit and Anxiety if not already covered. Should ask about discovery channels relevant to healthcare (doctor referrals, insurance, word-of-mouth). Objections should reflect consumer concerns (trust, insurance coverage, quality, safety) not B2B sales objections. Proof Points should lean toward credentials, certifications, reviews, and patient outcomes rather than logos.",
      "assertions": [
        "Recognizes B2C service offering type",
        "Asks for company/brand name",
        "Captures delivery model and coverage area for the service",
        "Asks about founding insight and team qualification",
        "Captures company stage",
        "Adapts Target Audience for consumer segments, not companies",
        "Asks about the customer buying journey",
        "Captures 2-4 personas (patient, family decision-maker, referring professional)",
        "Compiles Switching Dynamics from earlier sections rather than re-asking everything",
        "Asks about service-relevant discovery channels using select-all-that-apply",
        "Objections reflect consumer concerns not B2B sales objections",
        "Proof Points emphasize credentials and reviews over logos",
        "Uses structured prompts (select-one for delivery model, select-all for broken experience, finish-this-sentence for core challenge)",
        "Does not force product-only language"
      ],
      "files": []
    },
    {
      "id": 7,
      "prompt": "help me set up context for our business. we sell curated subscription boxes of artisan coffee plus an app that tracks your taste profile and recommends roasts. it's both a product and a service.",
      "expected_output": "Should recognize this as a hybrid offering (physical product + digital service). Should capture both the product dimension (subscription box, pricing, what's in it) and the service dimension (app, personalization, taste profiling). Should ask about both product-style differentiation (quality, sourcing, variety) and service-style differentiation (personalization, convenience, discovery experience). Personas might include the coffee enthusiast, the gift buyer, and the casual explorer. Should handle this as a unified context document, not force a choice between product or service.",
      "assertions": [
        "Recognizes hybrid offering type",
        "Captures both product and service dimensions",
        "Asks about product-style and service-style differentiation",
        "Does not force a binary product-or-service choice",
        "Creates unified context document",
        "Creates file at .agents/product-marketing-context.md"
      ],
      "files": []
    },
    {
      "id": 8,
      "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-context.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-context.md",
        "References or defers to copywriting skill for the actual copy",
        "Does not attempt to write homepage copy using context creation patterns"
      ],
      "files": []
    },
    {
      "id": 9,
      "prompt": "I'm a marketing consultant. My client runs a fitness coaching business but I don't know all the details about their customers. Can you help me set up the context doc?",
      "expected_output": "Should recognize the user is a proxy, not the founder. Should capture what the consultant knows and flag sections that need founder or customer-facing team input. Should mark incomplete sections as '[needs founder input]' in the output rather than forcing the consultant to guess. Should still walk through all sections but accept 'I'd need to ask them' as a valid answer.",
      "assertions": [
        "Recognizes proxy scenario (consultant setting up for client)",
        "Captures what the proxy knows",
        "Flags sections needing founder input rather than forcing guesses",
        "Marks gaps as '[needs founder input]' in output",
        "Completes the document with available information"
      ],
      "files": []
    },
    {
      "id": 10,
      "prompt": "set up our marketing context. we're a B2B consulting firm that helps mid-market companies with digital transformation. we sell strategy engagements and implementation services.",
      "expected_output": "Should recognize this as a B2B service offering (not product). Should ask for company/brand name. Should capture offering type as 'service' and ask about delivery model (retainer, project-based) and any geographic or industry focus. Should use B2B persona roles (Champion, Decision Maker, etc.) but adapt questions for a service business — e.g., 'what does the engagement look like?' rather than 'what features do you have?'. Should ask about the B2B buying journey for services (RFP, referral, thought leadership → consultation → proposal → engagement). Discovery channels should reflect B2B services (referrals, thought leadership, conferences, LinkedIn, industry events). Differentiation should focus on expertise, methodology, team credentials, and client outcomes rather than product features. Proof Points should emphasize case studies, client logos, and measurable business outcomes.",
      "assertions": [
        "Recognizes B2B service offering type",
        "Asks for company/brand name",
        "Captures delivery model for services (retainer, project-based)",
        "Uses B2B persona roles but adapts for service context",
        "Asks about B2B service buying journey",
        "Discovery channels reflect B2B services (referrals, thought leadership, conferences)",
        "Differentiation focuses on expertise and methodology, not product features",
        "Proof Points emphasize case studies and business outcomes",
        "Does not force product-only language on a service business",
        "Creates file at .agents/product-marketing-context.md"
      ],
      "files": []
    }
  ]
}

ClawHub Writing Marketing+2

M@clawhub-mariokarras-f59a320bef

Marketing Ideas

Skill

When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growt...

---
name: marketing-ideas
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 (paid-ads, social-content, email-sequence, etc.)."
metadata:
  version: 1.1.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:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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.

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)
- **competitor-alternatives**: For comparison pages (#11)
- **email-sequence**: For email marketing tactics
- **free-tool-strategy**: For engineering as marketing (#15)
- **referral-program**: For viral growth (#93)

FILE:evals/evals.json
{
  "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-context.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-context.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 referral-program 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 referral-program is the right skill for detailed program design.",
      "assertions": [
        "Recognizes this as a referral program design request",
        "References or defers to referral-program skill",
        "Does not attempt detailed referral program design",
        "May briefly mention as a marketing idea"
      ],
      "files": []
    }
  ]
}

FILE:references/ideas-by-category.md
# 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.

ClawHub Research Marketing+2

M@clawhub-mariokarras-f59a320bef

Referral Program

Skill

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

---
name: referral-program
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-strategy."
metadata:
  version: 1.1.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:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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.

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

---

## Related Skills

- **launch-strategy**: For launching referral program effectively
- **email-sequence**: For referral nurture campaigns
- **marketing-psychology**: For understanding referral motivation
- **analytics-tracking**: For tracking referral attribution

FILE:evals/evals.json
{
  "skill_name": "referral-program",
  "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-context.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-context.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 email-sequence skill. Should provide the referral invitation email but note that broader email sequence work is handled by email-sequence.",
      "assertions": [
        "Applies referral email section from the skill",
        "Provides referral invitation email guidance",
        "Cross-references email-sequence for broader email work",
        "Provides specific referral email copy or template"
      ],
      "files": []
    }
  ]
}

FILE:references/affiliate-programs.md
# 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

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

FILE:references/program-examples.md
# 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

| Type | Pros | Cons | Best For |
|------|------|------|----------|
| Cash/credit | Universally valued | Feels transactional | Marketplaces, fintech |
| Product credit | Drives usage | Only valuable if they'll use it | SaaS, subscriptions |
| Free months | Clear value | May attract freebie-seekers | Subscription products |
| Feature unlock | Low cost to you | Only works for gated features | Freemium products |
| Swag/gifts | Memorable, shareable | Logistics complexity | Brand-focused companies |
| Charity donation | Feel-good | Lower personal motivation | Mission-driven brands |

---

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

ClawHub Writing Marketing+2

M@clawhub-mariokarras-f59a320bef

Social Listening

Skill

Monitors social conversations and sentiment around brands, topics, or industries by searching tweets and discussions to surface insights. Use when the user w...

---
name: social-listening
description: "Monitors social conversations and sentiment around brands, topics, or industries by searching tweets and discussions to surface insights. Use when the user wants social listening, brand mentions, sentiment analysis, social monitoring, or brand sentiment tracking. Also use when the user mentions 'what are people saying about,' 'Twitter mentions,' 'X mentions,' 'social buzz,' 'online conversations,' 'monitor brand,' or 'track sentiment.' This skill searches social platforms for conversation patterns and sentiment -- for raw Twitter/X search, see exa-x-search; for content creation based on social insights, see social-content. See exa-x-search for raw tweet searching, see social-content for creating social posts, see content-strategy for content planning from social insights."
metadata:
  version: 1.0.0
---

# Social Listening

You are an expert at monitoring and analyzing social conversations. Your goal is to search tweets, discussions, and online mentions to build a comprehensive picture of how people talk about a brand, topic, or industry -- surfacing sentiment, key voices, and actionable opportunities.

## Before Starting

**Check for product marketing context first:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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.

Understand the situation (ask if not provided):

1. **What are you monitoring?** -- Brand name, product name, topic, or keyword
2. **What timeframe?** -- Recent (last week), medium-term (last month), or broad trend
3. **What questions do you have?** -- Overall sentiment? Key voices? Trending themes? Specific complaints?
4. **Any competitors to include?** -- Compare your brand mentions against competitors for relative positioning
5. **Any known context?** -- Recent launch, controversy, campaign, or event that might shape the conversation

Work with whatever the user gives you. A brand name alone is enough to start. Default to broad monitoring if no specific questions are provided.

---

## Workflow

### Step 1: Gather Context

Review product-marketing-context if available. Clarify the brand/topic to monitor and any specific angles. Identify competitors for comparison if relevant.

### Step 2: Search Social Conversations with Exa

Start with direct social mentions using the tweet category filter. This is your primary data source for real-time sentiment.

**Core brand/topic search:**

```bash
exa.js search "[brand/topic]" --category tweet --num-results 20
```

**Opinion and review mentions:**

```bash
exa.js search "[brand/topic] review OR opinion OR thoughts" --category tweet --num-results 10
```

**Competitor comparison mentions:**

```bash
exa.js search "[competitor] vs [brand]" --category tweet --num-results 10
```

**Specific angle searches (based on monitoring goals):**

```bash
exa.js search "[brand/topic] love OR amazing OR best" --category tweet --num-results 10
exa.js search "[brand/topic] hate OR terrible OR worst OR broken" --category tweet --num-results 10
exa.js search "[brand/topic] switching OR alternative OR moved to" --category tweet --num-results 10
```

### Step 3: Search for Broader Discussions

Expand beyond tweets to forums, blogs, and discussion platforms for deeper context.

**Forum and community discussions:**

```bash
exa.js search "[brand/topic] discussion forum" --num-results 10
```

**Reviews and experience reports:**

```bash
exa.js search "[brand/topic] review experience" --num-results 10
```

**Industry context:**

```bash
exa.js search "[brand/topic] industry trend" --num-results 5
```

### Step 4: Analyze and Categorize

For each result, classify:

1. **Sentiment** -- Positive, negative, neutral, or mixed
2. **Theme** -- What topic or feature is being discussed
3. **Influence** -- Is this from an influential account or a regular user
4. **Actionability** -- Is this something the brand can respond to, fix, or leverage

Group results by theme first, then by sentiment within each theme. Look for patterns: recurring complaints, consistent praise, emerging trends.

### Step 5: Synthesize into Sentiment Report

Combine all findings into the output format below. Focus on patterns over individual mentions. Highlight actionable insights prominently.

---

## Output Format

### Social Listening Report: [Brand/Topic]

**Monitoring period:** [Timeframe of search results]
**Total mentions analyzed:** [Approximate count from search results]

#### Executive Summary

2-3 sentences capturing overall sentiment, the dominant narrative, and the single most important takeaway. This should be useful on its own for someone who reads nothing else.

#### Volume

| Metric | Value |
|--------|-------|
| **Approximate mentions found** | [Count from search results] |
| **Primary platforms** | [Twitter/X, forums, blogs, etc.] |
| **Timeframe covered** | [Date range of results] |
| **Trend** | [Increasing, stable, decreasing, or spike around event] |

Note: Volume is approximate based on search results, not total mentions across all platforms.

#### Sentiment Breakdown

| Sentiment | Approximate % | Count |
|-----------|--------------|-------|
| Positive | [X%] | [N] |
| Negative | [X%] | [N] |
| Neutral | [X%] | [N] |
| Mixed | [X%] | [N] |

**Representative positive quotes:**
> "[Quote]" -- @[handle/source]

> "[Quote]" -- @[handle/source]

**Representative negative quotes:**
> "[Quote]" -- @[handle/source]

> "[Quote]" -- @[handle/source]

#### Key Voices

| Account/Source | Reach | Sentiment | Context |
|---------------|-------|-----------|---------|
| @[handle] | [Followers/influence level] | [Pos/Neg/Neutral] | [What they said and why it matters] |

Focus on: thought leaders, industry analysts, power users, vocal critics, and brand advocates.

#### Trending Themes

1. **[Theme Name]** -- [Description of the pattern]
   - Sentiment: [Predominantly positive/negative/mixed]
   - Volume: [High/Medium/Low relative to other themes]
   - Example: "[Representative quote]"

2. **[Theme Name]** -- [Description]
   - Sentiment: [Pos/Neg/Mixed]
   - Volume: [High/Medium/Low]
   - Example: "[Representative quote]"

Common themes include: feature requests, complaints, praise, comparisons to competitors, use case discussions, pricing feedback, support experiences.

#### Opportunities

1. **[Opportunity Type: Content / Product / Engagement / Marketing]**
   - **What:** [Specific opportunity]
   - **Evidence:** [What conversations suggest this]
   - **Suggested action:** [Concrete next step]

2. **[Opportunity Type]**
   - **What:** [Specific opportunity]
   - **Evidence:** [What conversations suggest this]
   - **Suggested action:** [Concrete next step]

Types of opportunities to look for:
- **Content ideas** -- Topics people are asking about that you could address
- **Product improvements** -- Recurring feature requests or complaints
- **Engagement opportunities** -- Conversations where a brand response would be valuable
- **Marketing angles** -- Positive themes to amplify in campaigns
- **Competitive gaps** -- Competitor weaknesses mentioned by their users

---

## Tips

- **Run multiple search queries.** A single search rarely captures the full picture. Vary your keywords, include sentiment words, and search for competitor comparisons.
- **Categorize sentiment manually.** Read the actual tweet/post content to determine sentiment. Don't rely on keyword matching alone -- sarcasm, context, and nuance matter.
- **Compare against competitors.** Relative sentiment is more useful than absolute. "Negative mentions are up" means less than "negative mentions are up while competitor X is trending positive."
- **Note that volume is approximate.** Search results represent a sample, not total mentions. Frame volume findings as directional, not precise.
- **Look for spikes and triggers.** A sudden increase in mentions usually ties to an event (launch, outage, PR, viral post). Identify the trigger to contextualize sentiment.
- **Separate signal from noise.** Not all mentions are equal. One influential critic matters more than ten casual mentions. Weight your analysis accordingly.

---

## Related Skills

- **exa-x-search** -- Raw tweet searching when you need specific tweets, not analysis
- **social-content** -- Creating social media posts based on insights from listening
- **content-strategy** -- Planning content themes informed by social conversation data
- **competitive-intelligence** -- Broader competitive analysis beyond social mentions

ClawHub Data Analysis Research+2

M@clawhub-mariokarras-f59a320bef

Exa Personal Site Search

Skill

Find personal websites, blogs, and portfolios for specific people using Exa's personal site category search. Use when the user mentions 'find someone's site,...

---
name: exa-personal-site-search
description: "Find personal websites, blogs, and portfolios for specific people using Exa's personal site category search. Use when the user mentions 'find someone's site,' 'personal website,' 'portfolio search,' 'find [person]'s blog,' 'personal blog,' 'developer portfolio,' or 'find their website.' Searches for personal sites by name and affiliations. NOT for finding people at companies (see exa-people-search). For company research, see exa-company-research."
metadata:
  version: 1.0.0
---

# Exa Personal Site Search

You help users find personal websites, blogs, and portfolios for specific people using Exa's personal site category search.

## Before Starting

**Check for product marketing context first:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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.

Understand what the user needs (ask if not provided):

1. **Person's name** -- who are you looking for?
2. **Known affiliations** -- company, university, community, or role
3. **What they're looking for** -- blog, portfolio, personal site, speaking page, or any

## Workflow

### Step 1: Search by Person Name

Run via exec:
```bash
exa.js search --query "[person name] personal site" --category "personal site" --num-results 10
```

### Step 2: Narrow with Affiliations

If the initial results are too broad or return the wrong person, add context to the query:

```bash
exa.js search --query "[person name] [company/university/role]" --category "personal site" --num-results 10
```

### Step 3: Fetch Content from Best Matches

For the most relevant results, fetch full content to verify the site belongs to the right person:

```bash
exa.js contents --ids "[id1],[id2]" --text
```

Use the IDs returned from the search results.

### Step 4: Present Findings

Summarize what you found with context about the person and their site content.

---

## Dry Run

To preview the request without making an API call:
```bash
exa.js search --query "[person name]" --category "personal site" --dry-run
```

---

## Output Format

For each result, present:

- **Person's Name:** [name]
- **Site URL:** [url]
- **Site Type:** Blog / Portfolio / Personal site / Speaking page
- **Key Content Found:** [brief summary of what the site contains]
- **Last Updated:** [if visible from the content]

If multiple sites are found for the same person, list all with a note about which appears to be their primary site.

---

## Tips

- **Common names:** Add role, company, or location to disambiguate ("Jane Smith Stripe engineer" vs just "Jane Smith")
- **Academics:** Try including university name or research area
- **Developers:** Try including GitHub handle or programming language specialty
- **Multiple results:** Cross-reference with LinkedIn or company pages to confirm identity

---

## Related Skills

- **exa-people-search**: Find specific people at companies (who works at X, find the CTO of Y)
- **exa-company-research**: Research a company's overview, products, funding, and news

ClawHub Coding Research+2

M@clawhub-mariokarras-f59a320bef

Exa Research Papers

Skill

Find academic papers, studies, and research on any topic using Exa's research paper category search. Use when the user mentions 'find papers,' 'research pape...

---
name: exa-research-papers
description: "Find academic papers, studies, and research on any topic using Exa's research paper category search. Use when the user mentions 'find papers,' 'research papers,' 'academic search,' 'studies about,' 'scientific papers,' 'find research on,' or 'literature search.' Covers finding and synthesizing academic research. NOT for general web search or company research. For company research, see exa-company-research. For market/industry research, see market-research."
metadata:
  version: 1.0.0
---

# Exa Research Papers

You help users find academic papers and research studies using Exa's research paper category search. Your goal is to find relevant papers and synthesize key findings for the user's research question.

## Before Starting

**Check for product marketing context first:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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.

Understand what the user needs (ask if not provided):

1. **Research topic** -- what subject or question are they researching?
2. **Specific questions** -- what do they want to learn or prove?
3. **Field/discipline** -- if known (e.g., computer science, psychology, economics)
4. **Recency preference** -- recent papers only, foundational/seminal works, or both?

## Workflow

### Step 1: Search for Papers

Run via exec:
```bash
exa.js search --query "[research topic]" --category "research paper" --num-results 10
```

For recent papers only, add a date filter:
```bash
exa.js search --query "[topic]" --category "research paper" --num-results 10 --start-date [current-year]-01-01  # Use current year
```

### Step 2: Refine the Search

If results are too broad, narrow with specific terms:
```bash
exa.js search --query "[topic] [specific method or finding]" --category "research paper" --num-results 10
```

### Step 3: Fetch Paper Content

For the most relevant results, fetch content to read abstracts and key sections:
```bash
exa.js contents --ids "[id1],[id2]" --text --highlights
```

Use the IDs returned from the search results.

### Step 4: Synthesize Key Findings

Summarize the papers in the context of the user's research question. Highlight agreements and disagreements across papers.

---

## Dry Run

To preview the request without making an API call:
```bash
exa.js search --query "[topic]" --category "research paper" --dry-run
```

---

## Output Format

For each paper found:

- **Title:** [paper title]
- **Authors:** [author names]
- **Year:** [publication year]
- **Key Findings:** [2-3 sentence summary of main findings]
- **Relevance:** [how this paper relates to the user's question]
- **URL:** [link to paper]

After listing papers, provide a **Synthesis** section:
- Common themes across papers
- Areas of agreement and disagreement
- Gaps in the research
- Suggested next steps or follow-up searches

---

## Tips

- **Broad topics:** Start with a focused subtopic, then expand if needed
- **Technical terms:** Use field-specific terminology for better results
- **Foundational works:** Omit the date filter to find seminal papers
- **Cross-disciplinary:** Run separate searches for each discipline and compare

---

## Related Skills

- **exa-company-research**: Research companies, not academic topics
- **content-strategy**: Turn research findings into content plans

ClawHub Backend Research+2

M@clawhub-mariokarras-f59a320bef

Paid Ads

Skill

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

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

# 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:**
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.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.

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

### Competitor Ad Research

Use Exa to research competitor ad strategies and messaging:

```bash
exa.js search "competitor name ads"
exa.js search "competitor name landing page"
```

Analyze their positioning, offers, and CTAs to find differentiation opportunities for your own campaigns.

---

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

| Funnel Stage | Audience | Message | Goal |
|--------------|----------|---------|------|
| Top | Blog readers, video viewers | Educational, social proof | Move to consideration |
| Middle | Pricing/feature page visitors | Case studies, demos | Move to decision |
| Bottom | Cart abandoners, trial users | Urgency, objection handling | Convert |

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

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

---

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

| Platform | Best For | MCP | Guide |
|----------|----------|:---:|-------|
| **Google Ads** | Search intent, high-intent traffic | ✓ | [google-ads.md](../../tools/integrations/google-ads.md) |
| **Meta Ads** | Demand gen, visual products, B2C | - | [meta-ads.md](../../tools/integrations/meta-ads.md) |
| **LinkedIn Ads** | B2B, job title targeting | - | [linkedin-ads.md](../../tools/integrations/linkedin-ads.md) |
| **TikTok Ads** | Younger demographics, video | - | [tiktok-ads.md](../../tools/integrations/tiktok-ads.md) |

For tracking, see also: [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-tracking**: For proper conversion tracking setup
- **ab-test-setup**: For landing page testing to improve ROAS
- **page-cro**: For optimizing post-click conversion rates

FILE:evals/evals.json
{
  "skill_name": "paid-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-context.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-context.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": []
    }
  ]
}

FILE:references/ad-copy-templates.md
# 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.

FILE:references/audience-targeting.md
# 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)

FILE:references/platform-setup-checklists.md
# 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

ClawHub Marketing AI Agents+2

M@clawhub-mariokarras-f59a320bef

1 / 3Next