diff --git a/.agents/skills/ab-test-setup/SKILL.md b/.agents/skills/ab-test-setup/SKILL.md new file mode 100644 index 00000000..2da0d1e5 --- /dev/null +++ b/.agents/skills/ab-test-setup/SKILL.md @@ -0,0 +1,266 @@ +--- +name: ab-test-setup +description: When the user wants to plan, design, or implement an A/B test or experiment. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant copy," "multivariate test," or "hypothesis." For tracking implementation, see analytics-tracking. +metadata: + version: 1.1.0 +--- + +# A/B Test Setup + +You are an expert in experimentation and A/B testing. Your goal is to help design tests that produce statistically valid, actionable results. + +## Initial Assessment + +**Check for product marketing context first:** +If `.agents/product-marketing-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 test, understand: + +1. **Test Context** - What are you trying to improve? What change are you considering? +2. **Current State** - Baseline conversion rate? Current traffic volume? +3. **Constraints** - Technical complexity? Timeline? Tools available? + +--- + +## Core Principles + +### 1. Start with a Hypothesis +- Not just "let's see what happens" +- Specific prediction of outcome +- Based on reasoning or data + +### 2. Test One Thing +- Single variable per test +- Otherwise you don't know what worked + +### 3. Statistical Rigor +- Pre-determine sample size +- Don't peek and stop early +- Commit to the methodology + +### 4. Measure What Matters +- Primary metric tied to business value +- Secondary metrics for context +- Guardrail metrics to prevent harm + +--- + +## Hypothesis Framework + +### Structure + +``` +Because [observation/data], +we believe [change] +will cause [expected outcome] +for [audience]. +We'll know this is true when [metrics]. +``` + +### Example + +**Weak**: "Changing the button color might increase clicks." + +**Strong**: "Because users report difficulty finding the CTA (per heatmaps and feedback), we believe making the button larger and using contrasting color will increase CTA clicks by 15%+ for new visitors. We'll measure click-through rate from page view to signup start." + +--- + +## Test Types + +| Type | Description | Traffic Needed | +|------|-------------|----------------| +| A/B | Two versions, single change | Moderate | +| A/B/n | Multiple variants | Higher | +| MVT | Multiple changes in combinations | Very high | +| Split URL | Different URLs for variants | Moderate | + +--- + +## Sample Size + +### Quick Reference + +| Baseline | 10% Lift | 20% Lift | 50% Lift | +|----------|----------|----------|----------| +| 1% | 150k/variant | 39k/variant | 6k/variant | +| 3% | 47k/variant | 12k/variant | 2k/variant | +| 5% | 27k/variant | 7k/variant | 1.2k/variant | +| 10% | 12k/variant | 3k/variant | 550/variant | + +**Calculators:** +- [Evan Miller's](https://www.evanmiller.org/ab-testing/sample-size.html) +- [Optimizely's](https://www.optimizely.com/sample-size-calculator/) + +**For detailed sample size tables and duration calculations**: See [references/sample-size-guide.md](references/sample-size-guide.md) + +--- + +## Metrics Selection + +### Primary Metric +- Single metric that matters most +- Directly tied to hypothesis +- What you'll use to call the test + +### Secondary Metrics +- Support primary metric interpretation +- Explain why/how the change worked + +### Guardrail Metrics +- Things that shouldn't get worse +- Stop test if significantly negative + +### Example: Pricing Page Test +- **Primary**: Plan selection rate +- **Secondary**: Time on page, plan distribution +- **Guardrail**: Support tickets, refund rate + +--- + +## Designing Variants + +### What to Vary + +| Category | Examples | +|----------|----------| +| Headlines/Copy | Message angle, value prop, specificity, tone | +| Visual Design | Layout, color, images, hierarchy | +| CTA | Button copy, size, placement, number | +| Content | Information included, order, amount, social proof | + +### Best Practices +- Single, meaningful change +- Bold enough to make a difference +- True to the hypothesis + +--- + +## Traffic Allocation + +| Approach | Split | When to Use | +|----------|-------|-------------| +| Standard | 50/50 | Default for A/B | +| Conservative | 90/10, 80/20 | Limit risk of bad variant | +| Ramping | Start small, increase | Technical risk mitigation | + +**Considerations:** +- Consistency: Users see same variant on return +- Balanced exposure across time of day/week + +--- + +## Implementation + +### Client-Side +- JavaScript modifies page after load +- Quick to implement, can cause flicker +- Tools: PostHog, Optimizely, VWO + +### Server-Side +- Variant determined before render +- No flicker, requires dev work +- Tools: PostHog, LaunchDarkly, Split + +--- + +## Running the Test + +### Pre-Launch Checklist +- [ ] Hypothesis documented +- [ ] Primary metric defined +- [ ] Sample size calculated +- [ ] Variants implemented correctly +- [ ] Tracking verified +- [ ] QA completed on all variants + +### During the Test + +**DO:** +- Monitor for technical issues +- Check segment quality +- Document external factors + +**DON'T:** +- Peek at results and stop early +- Make changes to variants +- Add traffic from new sources + +### The Peeking Problem +Looking at results before reaching sample size and stopping early leads to false positives and wrong decisions. Pre-commit to sample size and trust the process. + +--- + +## Analyzing Results + +### Statistical Significance +- 95% confidence = p-value < 0.05 +- Means <5% chance result is random +- Not a guarantee—just a threshold + +### Analysis Checklist + +1. **Reach sample size?** If not, result is preliminary +2. **Statistically significant?** Check confidence intervals +3. **Effect size meaningful?** Compare to MDE, project impact +4. **Secondary metrics consistent?** Support the primary? +5. **Guardrail concerns?** Anything get worse? +6. **Segment differences?** Mobile vs. desktop? New vs. returning? + +### Interpreting Results + +| Result | Conclusion | +|--------|------------| +| Significant winner | Implement variant | +| Significant loser | Keep control, learn why | +| No significant difference | Need more traffic or bolder test | +| Mixed signals | Dig deeper, maybe segment | + +--- + +## Documentation + +Document every test with: +- Hypothesis +- Variants (with screenshots) +- Results (sample, metrics, significance) +- Decision and learnings + +**For templates**: See [references/test-templates.md](references/test-templates.md) + +--- + +## Common Mistakes + +### Test Design +- Testing too small a change (undetectable) +- Testing too many things (can't isolate) +- No clear hypothesis + +### Execution +- Stopping early +- Changing things mid-test +- Not checking implementation + +### Analysis +- Ignoring confidence intervals +- Cherry-picking segments +- Over-interpreting inconclusive results + +--- + +## Task-Specific Questions + +1. What's your current conversion rate? +2. How much traffic does this page get? +3. What change are you considering and why? +4. What's the smallest improvement worth detecting? +5. What tools do you have for testing? +6. Have you tested this area before? + +--- + +## Related Skills + +- **page-cro**: For generating test ideas based on CRO principles +- **analytics-tracking**: For setting up test measurement +- **copywriting**: For creating variant copy diff --git a/.agents/skills/ab-test-setup/references/sample-size-guide.md b/.agents/skills/ab-test-setup/references/sample-size-guide.md new file mode 100644 index 00000000..3e35e6c1 --- /dev/null +++ b/.agents/skills/ab-test-setup/references/sample-size-guide.md @@ -0,0 +1,263 @@ +# Sample Size Guide + +Reference for calculating sample sizes and test duration. + +## Contents +- Sample Size Fundamentals (required inputs, what these mean) +- Sample Size Quick Reference Tables +- Duration Calculator (formula, examples, minimum duration rules, maximum duration guidelines) +- Online Calculators +- Adjusting for Multiple Variants +- Common Sample Size Mistakes +- When Sample Size Requirements Are Too High +- Sequential Testing +- Quick Decision Framework + +## Sample Size Fundamentals + +### Required Inputs + +1. **Baseline conversion rate**: Your current rate +2. **Minimum detectable effect (MDE)**: Smallest change worth detecting +3. **Statistical significance level**: Usually 95% (α = 0.05) +4. **Statistical power**: Usually 80% (β = 0.20) + +### What These Mean + +**Baseline conversion rate**: If your page converts at 5%, that's your baseline. + +**MDE (Minimum Detectable Effect)**: The smallest improvement you care about detecting. Set this based on: +- Business impact (is a 5% lift meaningful?) +- Implementation cost (worth the effort?) +- Realistic expectations (what have past tests shown?) + +**Statistical significance (95%)**: Means there's less than 5% chance the observed difference is due to random chance. + +**Statistical power (80%)**: Means if there's a real effect of size MDE, you have 80% chance of detecting it. + +--- + +## Sample Size Quick Reference Tables + +### Conversion Rate: 1% + +| Lift to Detect | Sample per Variant | Total Sample | +|----------------|-------------------|--------------| +| 5% (1% → 1.05%) | 1,500,000 | 3,000,000 | +| 10% (1% → 1.1%) | 380,000 | 760,000 | +| 20% (1% → 1.2%) | 97,000 | 194,000 | +| 50% (1% → 1.5%) | 16,000 | 32,000 | +| 100% (1% → 2%) | 4,200 | 8,400 | + +### Conversion Rate: 3% + +| Lift to Detect | Sample per Variant | Total Sample | +|----------------|-------------------|--------------| +| 5% (3% → 3.15%) | 480,000 | 960,000 | +| 10% (3% → 3.3%) | 120,000 | 240,000 | +| 20% (3% → 3.6%) | 31,000 | 62,000 | +| 50% (3% → 4.5%) | 5,200 | 10,400 | +| 100% (3% → 6%) | 1,400 | 2,800 | + +### Conversion Rate: 5% + +| Lift to Detect | Sample per Variant | Total Sample | +|----------------|-------------------|--------------| +| 5% (5% → 5.25%) | 280,000 | 560,000 | +| 10% (5% → 5.5%) | 72,000 | 144,000 | +| 20% (5% → 6%) | 18,000 | 36,000 | +| 50% (5% → 7.5%) | 3,100 | 6,200 | +| 100% (5% → 10%) | 810 | 1,620 | + +### Conversion Rate: 10% + +| Lift to Detect | Sample per Variant | Total Sample | +|----------------|-------------------|--------------| +| 5% (10% → 10.5%) | 130,000 | 260,000 | +| 10% (10% → 11%) | 34,000 | 68,000 | +| 20% (10% → 12%) | 8,700 | 17,400 | +| 50% (10% → 15%) | 1,500 | 3,000 | +| 100% (10% → 20%) | 400 | 800 | + +### Conversion Rate: 20% + +| Lift to Detect | Sample per Variant | Total Sample | +|----------------|-------------------|--------------| +| 5% (20% → 21%) | 60,000 | 120,000 | +| 10% (20% → 22%) | 16,000 | 32,000 | +| 20% (20% → 24%) | 4,000 | 8,000 | +| 50% (20% → 30%) | 700 | 1,400 | +| 100% (20% → 40%) | 200 | 400 | + +--- + +## Duration Calculator + +### Formula + +``` +Duration (days) = (Sample per variant × Number of variants) / (Daily traffic × % exposed) +``` + +### Examples + +**Scenario 1: High-traffic page** +- Need: 10,000 per variant (2 variants = 20,000 total) +- Daily traffic: 5,000 visitors +- 100% exposed to test +- Duration: 20,000 / 5,000 = **4 days** + +**Scenario 2: Medium-traffic page** +- Need: 30,000 per variant (60,000 total) +- Daily traffic: 2,000 visitors +- 100% exposed +- Duration: 60,000 / 2,000 = **30 days** + +**Scenario 3: Low-traffic with partial exposure** +- Need: 15,000 per variant (30,000 total) +- Daily traffic: 500 visitors +- 50% exposed to test +- Effective daily: 250 +- Duration: 30,000 / 250 = **120 days** (too long!) + +### Minimum Duration Rules + +Even with sufficient sample size, run tests for at least: +- **1 full week**: To capture day-of-week variation +- **2 business cycles**: If B2B (weekday vs. weekend patterns) +- **Through paydays**: If e-commerce (beginning/end of month) + +### Maximum Duration Guidelines + +Avoid running tests longer than 4-8 weeks: +- Novelty effects wear off +- External factors intervene +- Opportunity cost of other tests + +--- + +## Online Calculators + +### Recommended Tools + +**Evan Miller's Calculator** +https://www.evanmiller.org/ab-testing/sample-size.html +- Simple interface +- Bookmark-worthy + +**Optimizely's Calculator** +https://www.optimizely.com/sample-size-calculator/ +- Business-friendly language +- Duration estimates + +**AB Test Guide Calculator** +https://www.abtestguide.com/calc/ +- Includes Bayesian option +- Multiple test types + +**VWO Duration Calculator** +https://vwo.com/tools/ab-test-duration-calculator/ +- Duration-focused +- Good for planning + +--- + +## Adjusting for Multiple Variants + +With more than 2 variants (A/B/n tests), you need more sample: + +| Variants | Multiplier | +|----------|------------| +| 2 (A/B) | 1x | +| 3 (A/B/C) | ~1.5x | +| 4 (A/B/C/D) | ~2x | +| 5+ | Consider reducing variants | + +**Why?** More comparisons increase chance of false positives. You're comparing: +- A vs B +- A vs C +- B vs C (sometimes) + +Apply Bonferroni correction or use tools that handle this automatically. + +--- + +## Common Sample Size Mistakes + +### 1. Underpowered tests +**Problem**: Not enough sample to detect realistic effects +**Fix**: Be realistic about MDE, get more traffic, or don't test + +### 2. Overpowered tests +**Problem**: Waiting for sample size when you already have significance +**Fix**: This is actually fine—you committed to sample size, honor it + +### 3. Wrong baseline rate +**Problem**: Using wrong conversion rate for calculation +**Fix**: Use the specific metric and page, not site-wide averages + +### 4. Ignoring segments +**Problem**: Calculating for full traffic, then analyzing segments +**Fix**: If you plan segment analysis, calculate sample for smallest segment + +### 5. Testing too many things +**Problem**: Dividing traffic too many ways +**Fix**: Prioritize ruthlessly, run fewer concurrent tests + +--- + +## When Sample Size Requirements Are Too High + +Options when you can't get enough traffic: + +1. **Increase MDE**: Accept only detecting larger effects (20%+ lift) +2. **Lower confidence**: Use 90% instead of 95% (risky, document it) +3. **Reduce variants**: Test only the most promising variant +4. **Combine traffic**: Test across multiple similar pages +5. **Test upstream**: Test earlier in funnel where traffic is higher +6. **Don't test**: Make decision based on qualitative data instead +7. **Longer test**: Accept longer duration (weeks/months) + +--- + +## Sequential Testing + +If you must check results before reaching sample size: + +### What is it? +Statistical method that adjusts for multiple looks at data. + +### When to use +- High-risk changes +- Need to stop bad variants early +- Time-sensitive decisions + +### Tools that support it +- Optimizely (Stats Accelerator) +- VWO (SmartStats) +- PostHog (Bayesian approach) + +### Tradeoff +- More flexibility to stop early +- Slightly larger sample size requirement +- More complex analysis + +--- + +## Quick Decision Framework + +### Can I run this test? + +``` +Daily traffic to page: _____ +Baseline conversion rate: _____ +MDE I care about: _____ + +Sample needed per variant: _____ (from tables above) +Days to run: Sample / Daily traffic = _____ + +If days > 60: Consider alternatives +If days > 30: Acceptable for high-impact tests +If days < 14: Likely feasible +If days < 7: Easy to run, consider running longer anyway +``` diff --git a/.agents/skills/ab-test-setup/references/test-templates.md b/.agents/skills/ab-test-setup/references/test-templates.md new file mode 100644 index 00000000..1c517d88 --- /dev/null +++ b/.agents/skills/ab-test-setup/references/test-templates.md @@ -0,0 +1,277 @@ +# A/B Test Templates Reference + +Templates for planning, documenting, and analyzing experiments. + +## Contents +- Test Plan Template +- Results Documentation Template +- Test Repository Entry Template +- Quick Test Brief Template +- Stakeholder Update Template +- Experiment Prioritization Scorecard +- Hypothesis Bank Template + +## Test Plan Template + +```markdown +# A/B Test: [Name] + +## Overview +- **Owner**: [Name] +- **Test ID**: [ID in testing tool] +- **Page/Feature**: [What's being tested] +- **Planned dates**: [Start] - [End] + +## Hypothesis + +Because [observation/data], +we believe [change] +will cause [expected outcome] +for [audience]. +We'll know this is true when [metrics]. + +## Test Design + +| Element | Details | +|---------|---------| +| Test type | A/B / A/B/n / MVT | +| Duration | X weeks | +| Sample size | X per variant | +| Traffic allocation | 50/50 | +| Tool | [Tool name] | +| Implementation | Client-side / Server-side | + +## Variants + +### Control (A) +[Screenshot] +- Current experience +- [Key details about current state] + +### Variant (B) +[Screenshot or mockup] +- [Specific change #1] +- [Specific change #2] +- Rationale: [Why we think this will win] + +## Metrics + +### Primary +- **Metric**: [metric name] +- **Definition**: [how it's calculated] +- **Current baseline**: [X%] +- **Minimum detectable effect**: [X%] + +### Secondary +- [Metric 1]: [what it tells us] +- [Metric 2]: [what it tells us] +- [Metric 3]: [what it tells us] + +### Guardrails +- [Metric that shouldn't get worse] +- [Another safety metric] + +## Segment Analysis Plan +- Mobile vs. desktop +- New vs. returning visitors +- Traffic source +- [Other relevant segments] + +## Success Criteria +- Winner: [Primary metric improves by X% with 95% confidence] +- Loser: [Primary metric decreases significantly] +- Inconclusive: [What we'll do if no significant result] + +## Pre-Launch Checklist +- [ ] Hypothesis documented and reviewed +- [ ] Primary metric defined and trackable +- [ ] Sample size calculated +- [ ] Test duration estimated +- [ ] Variants implemented correctly +- [ ] Tracking verified in all variants +- [ ] QA completed on all variants +- [ ] Stakeholders informed +- [ ] Calendar hold for analysis date +``` + +--- + +## Results Documentation Template + +```markdown +# A/B Test Results: [Name] + +## Summary +| Element | Value | +|---------|-------| +| Test ID | [ID] | +| Dates | [Start] - [End] | +| Duration | X days | +| Result | Winner / Loser / Inconclusive | +| Decision | [What we're doing] | + +## Hypothesis (Reminder) +[Copy from test plan] + +## Results + +### Sample Size +| Variant | Target | Actual | % of target | +|---------|--------|--------|-------------| +| Control | X | Y | Z% | +| Variant | X | Y | Z% | + +### Primary Metric: [Metric Name] +| Variant | Value | 95% CI | vs. Control | +|---------|-------|--------|-------------| +| Control | X% | [X%, Y%] | — | +| Variant | X% | [X%, Y%] | +X% | + +**Statistical significance**: p = X.XX (95% = sig / not sig) +**Practical significance**: [Is this lift meaningful for the business?] + +### Secondary Metrics + +| Metric | Control | Variant | Change | Significant? | +|--------|---------|---------|--------|--------------| +| [Metric 1] | X | Y | +Z% | Yes/No | +| [Metric 2] | X | Y | +Z% | Yes/No | + +### Guardrail Metrics + +| Metric | Control | Variant | Change | Concern? | +|--------|---------|---------|--------|----------| +| [Metric 1] | X | Y | +Z% | Yes/No | + +### Segment Analysis + +**Mobile vs. Desktop** +| Segment | Control | Variant | Lift | +|---------|---------|---------|------| +| Mobile | X% | Y% | +Z% | +| Desktop | X% | Y% | +Z% | + +**New vs. Returning** +| Segment | Control | Variant | Lift | +|---------|---------|---------|------| +| New | X% | Y% | +Z% | +| Returning | X% | Y% | +Z% | + +## Interpretation + +### What happened? +[Explanation of results in plain language] + +### Why do we think this happened? +[Analysis and reasoning] + +### Caveats +[Any limitations, external factors, or concerns] + +## Decision + +**Winner**: [Control / Variant] + +**Action**: [Implement variant / Keep control / Re-test] + +**Timeline**: [When changes will be implemented] + +## Learnings + +### What we learned +- [Key insight 1] +- [Key insight 2] + +### What to test next +- [Follow-up test idea 1] +- [Follow-up test idea 2] + +### Impact +- **Projected lift**: [X% improvement in Y metric] +- **Business impact**: [Revenue, conversions, etc.] +``` + +--- + +## Test Repository Entry Template + +For tracking all tests in a central location: + +```markdown +| Test ID | Name | Page | Dates | Primary Metric | Result | Lift | Link | +|---------|------|------|-------|----------------|--------|------|------| +| 001 | Hero headline test | Homepage | 1/1-1/15 | CTR | Winner | +12% | [Link] | +| 002 | Pricing table layout | Pricing | 1/10-1/31 | Plan selection | Loser | -5% | [Link] | +| 003 | Signup form fields | Signup | 2/1-2/14 | Completion | Inconclusive | +2% | [Link] | +``` + +--- + +## Quick Test Brief Template + +For simple tests that don't need full documentation: + +```markdown +## [Test Name] + +**What**: [One sentence description] +**Why**: [One sentence hypothesis] +**Metric**: [Primary metric] +**Duration**: [X weeks] +**Result**: [TBD / Winner / Loser / Inconclusive] +**Learnings**: [Key takeaway] +``` + +--- + +## Stakeholder Update Template + +```markdown +## A/B Test Update: [Name] + +**Status**: Running / Complete +**Days remaining**: X (or complete) +**Current sample**: X% of target + +### Preliminary observations +[What we're seeing - without making decisions yet] + +### Next steps +[What happens next] + +### Timeline +- [Date]: Analysis complete +- [Date]: Decision and recommendation +- [Date]: Implementation (if winner) +``` + +--- + +## Experiment Prioritization Scorecard + +For deciding which tests to run: + +| Factor | Weight | Test A | Test B | Test C | +|--------|--------|--------|--------|--------| +| Potential impact | 30% | | | | +| Confidence in hypothesis | 25% | | | | +| Ease of implementation | 20% | | | | +| Risk if wrong | 15% | | | | +| Strategic alignment | 10% | | | | +| **Total** | | | | | + +Scoring: 1-5 (5 = best) + +--- + +## Hypothesis Bank Template + +For collecting test ideas: + +```markdown +| ID | Page/Area | Observation | Hypothesis | Potential Impact | Status | +|----|-----------|-------------|------------|------------------|--------| +| H1 | Homepage | Low scroll depth | Shorter hero will increase scroll | High | Testing | +| H2 | Pricing | Users compare plans | Comparison table will help | Medium | Backlog | +| H3 | Signup | Drop-off at email | Social login will increase completion | Medium | Backlog | +``` diff --git a/.agents/skills/ad-creative/SKILL.md b/.agents/skills/ad-creative/SKILL.md new file mode 100644 index 00000000..7dd2709f --- /dev/null +++ b/.agents/skills/ad-creative/SKILL.md @@ -0,0 +1,362 @@ +--- +name: ad-creative +description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' or 'ad performance optimization.' This skill covers generating ad creative at scale, iterating based on performance data, and enforcing platform character limits. For campaign strategy and targeting, see paid-ads. For landing page copy, see copywriting." +metadata: + version: 1.1.0 +--- + +# Ad Creative + +You are an expert performance creative strategist. Your goal is to generate high-performing ad creative at scale — headlines, descriptions, and primary text that drive clicks and conversions — and iterate based on real performance data. + +## Before Starting + +**Check for product marketing context first:** +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. Platform & Format +- What platform? (Google Ads, Meta, LinkedIn, TikTok, Twitter/X) +- What ad format? (Search RSAs, display, social feed, stories, video) +- Are there existing ads to iterate on, or starting from scratch? + +### 2. Product & Offer +- What are you promoting? (Product, feature, free trial, demo, lead magnet) +- What's the core value proposition? +- What makes this different from competitors? + +### 3. Audience & Intent +- Who is the target audience? +- What stage of awareness? (Problem-aware, solution-aware, product-aware) +- What pain points or desires drive them? + +### 4. Performance Data (if iterating) +- What creative is currently running? +- Which headlines/descriptions are performing best? (CTR, conversion rate, ROAS) +- Which are underperforming? +- What angles or themes have been tested? + +### 5. Constraints +- Brand voice guidelines or words to avoid? +- Compliance requirements? (Industry regulations, platform policies) +- Any mandatory elements? (Brand name, trademark symbols, disclaimers) + +--- + +## How This Skill Works + +This skill supports two modes: + +### Mode 1: Generate from Scratch +When starting fresh, you generate a full set of ad creative based on product context, audience insights, and platform best practices. + +### Mode 2: Iterate from Performance Data +When the user provides performance data (CSV, paste, or API output), you analyze what's working, identify patterns in top performers, and generate new variations that build on winning themes while exploring new angles. + +The core loop: + +``` +Pull performance data → Identify winning patterns → Generate new variations → Validate specs → Deliver +``` + +--- + +## Platform Specs + +**Always enforce these limits.** Never deliver creative that exceeds platform character limits. + +### Google Ads (Responsive Search Ads) + +| Element | Limit | Quantity | +|---------|-------|----------| +| Headline | 30 characters | Up to 15 | +| Description | 90 characters | Up to 4 | +| Display URL path | 15 characters each | 2 paths | + +**RSA rules:** +- Headlines must make sense independently and in any combination +- Pin headlines to positions only when necessary (reduces optimization) +- Include at least one keyword-focused headline +- Include at least one benefit-focused headline +- Include at least one CTA headline + +### Meta Ads (Facebook/Instagram) + +| Element | Limit | Notes | +|---------|-------|-------| +| Primary text | 125 chars visible (up to 2,200) | Front-load the hook | +| Headline | 40 characters recommended | Below the image | +| Description | 30 characters recommended | Below headline | +| URL display link | 40 characters | Optional | + +### LinkedIn Ads + +| Element | Limit | Notes | +|---------|-------|-------| +| Intro text | 150 chars recommended (600 max) | Above the image | +| Headline | 70 chars recommended (200 max) | Below the image | +| Description | 100 chars recommended (300 max) | Appears in some placements | + +### TikTok Ads + +| Element | Limit | Notes | +|---------|-------|-------| +| Ad text | 80 chars recommended (100 max) | Above the video | +| Display name | 40 characters | Brand name | + +### Twitter/X Ads + +| Element | Limit | Notes | +|---------|-------|-------| +| Tweet text | 280 characters | The ad copy | +| Headline | 70 characters | Card headline | +| Description | 200 characters | Card description | + +For detailed specs and format variations, see [references/platform-specs.md](references/platform-specs.md). + +--- + +## Generating Ad Visuals + +For image and video ad creative, use generative AI tools and code-based video rendering. See [references/generative-tools.md](references/generative-tools.md) for the complete guide covering: + +- **Image generation** — Nano Banana Pro (Gemini), Flux, Ideogram for static ad images +- **Video generation** — Veo, Kling, Runway, Sora, Seedance, Higgsfield for video ads +- **Voice & audio** — ElevenLabs, OpenAI TTS, Cartesia for voiceovers, cloning, multilingual +- **Code-based video** — Remotion for templated, data-driven video at scale +- **Platform image specs** — Correct dimensions for every ad placement +- **Cost comparison** — Pricing for 100+ ad variations across tools + +**Recommended workflow for scaled production:** +1. Generate hero creative with AI tools (exploratory, high-quality) +2. Build Remotion templates based on winning patterns +3. Batch produce variations with Remotion using data feeds +4. Iterate — AI for new angles, Remotion for scale + +--- + +## Generating Ad Copy + +### Step 1: Define Your Angles + +Before writing individual headlines, establish 3-5 distinct **angles** — different reasons someone would click. Each angle should tap into a different motivation. + +**Common angle categories:** + +| Category | Example Angle | +|----------|---------------| +| Pain point | "Stop wasting time on X" | +| Outcome | "Achieve Y in Z days" | +| Social proof | "Join 10,000+ teams who..." | +| Curiosity | "The X secret top companies use" | +| Comparison | "Unlike X, we do Y" | +| Urgency | "Limited time: get X free" | +| Identity | "Built for [specific role/type]" | +| Contrarian | "Why [common practice] doesn't work" | + +### Step 2: Generate Variations per Angle + +For each angle, generate multiple variations. Vary: +- **Word choice** — synonyms, active vs. passive +- **Specificity** — numbers vs. general claims +- **Tone** — direct vs. question vs. command +- **Structure** — short punch vs. full benefit statement + +### Step 3: Validate Against Specs + +Before delivering, check every piece of creative against the platform's character limits. Flag anything that's over and provide a trimmed alternative. + +### Step 4: Organize for Upload + +Present creative in a structured format that maps to the ad platform's upload requirements. + +--- + +## Iterating from Performance Data + +When the user provides performance data, follow this process: + +### Step 1: Analyze Winners + +Look at the top-performing creative (by CTR, conversion rate, or ROAS — ask which metric matters most) and identify: + +- **Winning themes** — What topics or pain points appear in top performers? +- **Winning structures** — Questions? Statements? Commands? Numbers? +- **Winning word patterns** — Specific words or phrases that recur? +- **Character utilization** — Are top performers shorter or longer? + +### Step 2: Analyze Losers + +Look at the worst performers and identify: + +- **Themes that fall flat** — What angles aren't resonating? +- **Common patterns in low performers** — Too generic? Too long? Wrong tone? + +### Step 3: Generate New Variations + +Create new creative that: +- **Doubles down** on winning themes with fresh phrasing +- **Extends** winning angles into new variations +- **Tests** 1-2 new angles not yet explored +- **Avoids** patterns found in underperformers + +### Step 4: Document the Iteration + +Track what was learned and what's being tested: + +``` +## Iteration Log +- Round: [number] +- Date: [date] +- Top performers: [list with metrics] +- Winning patterns: [summary] +- New variations: [count] headlines, [count] descriptions +- New angles being tested: [list] +- Angles retired: [list] +``` + +--- + +## Writing Quality Standards + +### Headlines That Click + +**Strong headlines:** +- Specific ("Cut reporting time 75%") over vague ("Save time") +- Benefits ("Ship code faster") over features ("CI/CD pipeline") +- Active voice ("Automate your reports") over passive ("Reports are automated") +- Include numbers when possible ("3x faster," "in 5 minutes," "10,000+ teams") + +**Avoid:** +- Jargon the audience won't recognize +- Claims without specificity ("Best," "Leading," "Top") +- All caps or excessive punctuation +- Clickbait that the landing page can't deliver on + +### Descriptions That Convert + +Descriptions should complement headlines, not repeat them. Use descriptions to: +- Add proof points (numbers, testimonials, awards) +- Handle objections ("No credit card required," "Free forever for small teams") +- Reinforce CTAs ("Start your free trial today") +- Add urgency when genuine ("Limited to first 500 signups") + +--- + +## Output Formats + +### Standard Output + +Organize by angle, with character counts: + +``` +## Angle: [Pain Point — Manual Reporting] + +### Headlines (30 char max) +1. "Stop Building Reports by Hand" (29) +2. "Automate Your Weekly Reports" (28) +3. "Reports Done in 5 Min, Not 5 Hr" (31) <- OVER LIMIT, trimmed below + -> "Reports in 5 Min, Not 5 Hrs" (27) + +### Descriptions (90 char max) +1. "Marketing teams save 10+ hours/week with automated reporting. Start free." (73) +2. "Connect your data sources once. Get automated reports forever. No code required." (80) +``` + +### Bulk CSV Output + +When generating at scale (10+ variations), offer CSV format for direct upload: + +```csv +headline_1,headline_2,headline_3,description_1,description_2,platform +"Stop Manual Reporting","Automate in 5 Minutes","Join 10K+ Teams","Save 10+ hrs/week on reports. Start free.","Connect data sources once. Reports forever.","google_ads" +``` + +### Iteration Report + +When iterating, include a summary: + +``` +## Performance Summary +- Analyzed: [X] headlines, [Y] descriptions +- Top performer: "[headline]" — [metric]: [value] +- Worst performer: "[headline]" — [metric]: [value] +- Pattern: [observation] + +## New Creative +[organized variations] + +## Recommendations +- [What to pause, what to scale, what to test next] +``` + +--- + +## Batch Generation Workflow + +For large-scale creative production (Anthropic's growth team generates 100+ variations per cycle): + +### 1. Break into sub-tasks +- **Headline generation** — Focused on click-through +- **Description generation** — Focused on conversion +- **Primary text generation** — Focused on engagement (Meta/LinkedIn) + +### 2. Generate in waves +- Wave 1: Core angles (3-5 angles, 5 variations each) +- Wave 2: Extended variations on top 2 angles +- Wave 3: Wild card angles (contrarian, emotional, specific) + +### 3. Quality filter +- Remove anything over character limit +- Remove duplicates or near-duplicates +- Flag anything that might violate platform policies +- Ensure headline/description combinations make sense together + +--- + +## Common Mistakes + +- **Writing headlines that only work together** — RSA headlines get combined randomly +- **Ignoring character limits** — Platforms truncate without warning +- **All variations sound the same** — Vary angles, not just word choice +- **No CTA headlines** — Always include action-oriented headlines +- **Generic descriptions** — "Learn more about our solution" wastes the slot +- **Iterating without data** — Gut feelings are less reliable than metrics +- **Testing too many things at once** — Change one variable per test cycle +- **Retiring creative too early** — Allow 1,000+ impressions before judging + +--- + +## Tool Integrations + +For pulling performance data and managing campaigns, see the [tools registry](../../tools/REGISTRY.md). + +| Platform | Pull Performance Data | Manage Campaigns | Guide | +|----------|:---------------------:|:----------------:|-------| +| **Google Ads** | `google-ads campaigns list`, `google-ads reports get` | `google-ads campaigns create` | [google-ads.md](../../tools/integrations/google-ads.md) | +| **Meta Ads** | `meta-ads insights get` | `meta-ads campaigns list` | [meta-ads.md](../../tools/integrations/meta-ads.md) | +| **LinkedIn Ads** | `linkedin-ads analytics get` | `linkedin-ads campaigns list` | [linkedin-ads.md](../../tools/integrations/linkedin-ads.md) | +| **TikTok Ads** | `tiktok-ads reports get` | `tiktok-ads campaigns list` | [tiktok-ads.md](../../tools/integrations/tiktok-ads.md) | + +### Workflow: Pull Data, Analyze, Generate + +```bash +# 1. Pull recent ad performance +node tools/clis/google-ads.js reports get --type ad_performance --date-range last_30_days + +# 2. Analyze output (identify top/bottom performers) +# 3. Feed winning patterns into this skill +# 4. Generate new variations +# 5. Upload to platform +``` + +--- + +## Related Skills + +- **paid-ads**: For campaign strategy, targeting, budgets, and optimization +- **copywriting**: For landing page copy (where ad traffic lands) +- **ab-test-setup**: For structuring creative tests with statistical rigor +- **marketing-psychology**: For psychological principles behind high-performing creative +- **copy-editing**: For polishing ad copy before launch diff --git a/.agents/skills/ad-creative/references/generative-tools.md b/.agents/skills/ad-creative/references/generative-tools.md new file mode 100644 index 00000000..e22ebcee --- /dev/null +++ b/.agents/skills/ad-creative/references/generative-tools.md @@ -0,0 +1,637 @@ +# Generative AI Tools for Ad Creative + +Reference for using AI image generators, video generators, and code-based video tools to produce ad visuals at scale. + +--- + +## When to Use Generative Tools + +| Need | Tool Category | Best Fit | +|------|---------------|----------| +| Static ad images (banners, social) | Image generation | Nano Banana Pro, Flux, Ideogram | +| Ad images with text overlays | Image generation (text-capable) | Ideogram, Nano Banana Pro | +| Short video ads (6-30 sec) | Video generation | Veo, Kling, Runway, Sora, Seedance | +| Video ads with voiceover | Video gen + voice | Veo/Sora (native), or Runway + ElevenLabs | +| Voiceover tracks for ads | Voice generation | ElevenLabs, OpenAI TTS, Cartesia | +| Multi-language ad versions | Voice generation | ElevenLabs, PlayHT | +| Brand voice cloning | Voice generation | ElevenLabs, Resemble AI | +| Product mockups and variations | Image generation + references | Flux (multi-image reference) | +| Templated video ads at scale | Code-based video | Remotion | +| Personalized video (name, data) | Code-based video | Remotion | +| Brand-consistent variations | Image gen + style refs | Flux, Ideogram, Nano Banana Pro | + +--- + +## Image Generation + +### Nano Banana Pro (Gemini) + +Google DeepMind's image generation model, available through the Gemini API. + +**Best for:** High-quality ad images, product visuals, text rendering +**API:** Gemini API (Google AI Studio, Vertex AI) +**Pricing:** ~$0.04/image (Gemini 2.5 Flash Image), ~$0.24/4K image (Nano Banana Pro) + +**Strengths:** +- Strong text rendering in images (logos, headlines) +- Native image editing (modify existing images with prompts) +- Available through the same Gemini API used for text generation +- Supports both generation and editing in one model + +**Ad creative use cases:** +- Generate social media ad images from text descriptions +- Create product mockup variations +- Edit existing ad images (swap backgrounds, change colors) +- Generate images with headline text baked in + +**API example:** +```bash +# Using the Gemini API for image generation +curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent" \ + -H "Content-Type: application/json" \ + -H "x-goog-api-key: $GEMINI_API_KEY" \ + -d '{ + "contents": [{"parts": [{"text": "Create a clean, modern social media ad image for a project management tool. Show a laptop with a kanban board interface. Bright, professional, 16:9 ratio."}]}], + "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]} + }' +``` + +**Docs:** [Gemini Image Generation](https://ai.google.dev/gemini-api/docs/image-generation) + +--- + +### Flux (Black Forest Labs) + +Open-weight image generation models with API access through Replicate and BFL's native API. + +**Best for:** Photorealistic images, brand-consistent variations, multi-reference generation +**API:** Replicate, BFL API, fal.ai +**Pricing:** ~$0.01-0.06/image depending on model and resolution + +**Model variants:** +| Model | Speed | Quality | Cost | Best For | +|-------|-------|---------|------|----------| +| Flux 2 Pro | ~6 sec | Highest | $0.015/MP | Final production assets | +| Flux 2 Flex | ~22 sec | High + editing | $0.06/MP | Iterative editing | +| Flux 2 Dev | ~2.5 sec | Good | $0.012/MP | Rapid prototyping | +| Flux 2 Klein | Fastest | Good | Lowest | High-volume batch generation | + +**Strengths:** +- Multi-image reference (up to 8 images) for consistent identity across ads +- Product consistency — same product in different contexts +- Style transfer from reference images +- Open-weight Dev model for self-hosting + +**Ad creative use cases:** +- Generate 50+ ad variations with consistent product/person identity +- Create product-in-context images (your SaaS on different devices) +- Style-match to existing brand assets using reference images +- Rapid A/B test image variations + +**Docs:** [Replicate Flux](https://replicate.com/black-forest-labs/flux-2-pro), [BFL API](https://docs.bfl.ml/) + +--- + +### Ideogram + +Specialized in typography and text rendering within images. + +**Best for:** Ad banners with text, branded graphics, social ad images with headlines +**API:** Ideogram API, Runware +**Pricing:** ~$0.06/image (API), ~$0.009/image (subscription) + +**Strengths:** +- Best-in-class text rendering (~90% accuracy vs ~30% for most tools) +- Style reference system (upload up to 3 reference images) +- 4.3 billion style presets for consistent brand aesthetics +- Strong at logos and branded typography + +**Ad creative use cases:** +- Generate ad banners with headline text directly in the image +- Create social media graphics with branded text overlays +- Produce multiple design variations with consistent typography +- Generate promotional materials without needing a designer for each iteration + +**Docs:** [Ideogram API](https://developer.ideogram.ai/), [Ideogram](https://ideogram.ai/) + +--- + +### Other Image Tools + +| Tool | Best For | API Status | Notes | +|------|----------|------------|-------| +| **DALL-E 3** (OpenAI) | General image generation | Official API | Integrated with ChatGPT, good text rendering | +| **Midjourney** | Artistic, high-aesthetic images | No official public API | Discord-based; unofficial APIs exist but risk bans | +| **Stable Diffusion** | Self-hosted, customizable | Open source | Best for teams with GPU infrastructure | + +--- + +## Video Generation + +### Google Veo + +Google DeepMind's video generation model, available through the Gemini API and Vertex AI. + +**Best for:** High-quality video ads with native audio, vertical video for social +**API:** Gemini API, Vertex AI +**Pricing:** ~$0.15/sec (Veo 3.1 Fast), ~$0.40/sec (Veo 3.1 Standard) + +**Capabilities:** +- Up to 60 seconds at 1080p +- Native audio generation (dialogue, sound effects, ambient) +- Vertical 9:16 output for Stories/Reels/Shorts +- Upscale to 4K +- Text-to-video and image-to-video + +**Ad creative use cases:** +- Generate short video ads (15-30 sec) from text descriptions +- Create vertical video ads for TikTok, Reels, Shorts +- Produce product demos with voiceover +- Generate multiple video variations from the same prompt with different styles + +**Docs:** [Veo on Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/video/overview) + +--- + +### Kling (Kuaishou) + +Video generation with simultaneous audio-visual generation and camera controls. + +**Best for:** Cinematic video ads, longer-form content, audio-synced video +**API:** Kling API, PiAPI, fal.ai +**Pricing:** ~$0.09/sec (via fal.ai third-party) + +**Capabilities:** +- Up to 3 minutes at 1080p/30-48fps +- Simultaneous audio-visual generation (Kling 2.6) +- Text-to-video and image-to-video +- Motion and camera controls + +**Ad creative use cases:** +- Longer product explainer videos +- Cinematic brand videos with synchronized audio +- Animate product images into video ads + +**Docs:** [Kling AI Developer](https://klingai.com/global/dev/model/video) + +--- + +### Runway + +Video generation and editing platform with strong controllability. + +**Best for:** Controlled video generation, style-consistent content, editing existing footage +**API:** Runway Developer Portal + +**Capabilities:** +- Gen-4: Character/scene consistency across shots +- Motion brush and camera controls +- Image-to-video with reference images +- Video-to-video style transfer + +**Ad creative use cases:** +- Generate video ads with consistent characters/products across scenes +- Style-transfer existing footage to match brand aesthetics +- Extend or remix existing video content + +**Docs:** [Runway API](https://docs.dev.runwayml.com/) + +--- + +### Sora 2 (OpenAI) + +OpenAI's video generation model with synchronized audio. + +**Best for:** High-fidelity video with dialogue and sound +**API:** OpenAI API +**Pricing:** Free tier available; Pro from $0.10-0.50/sec depending on resolution + +**Capabilities:** +- Up to 60 seconds with synchronized audio +- Dialogue, sound effects, and ambient audio +- sora-2 (fast) and sora-2-pro (quality) variants +- Text-to-video and image-to-video + +**Ad creative use cases:** +- Video testimonials and talking-head style ads +- Product demo videos with narration +- Narrative brand videos + +**Docs:** [OpenAI Video Generation](https://platform.openai.com/docs/guides/video-generation) + +--- + +### Seedance 2.0 (ByteDance) + +ByteDance's video generation model with simultaneous audio-visual generation and multimodal inputs. + +**Best for:** Fast, affordable video ads with native audio, multimodal reference inputs +**API:** BytePlus (official), Replicate, WaveSpeedAI, fal.ai (third-party); OpenAI-compatible API format +**Pricing:** ~$0.10-0.80/min depending on resolution (estimated 10-100x cheaper than Sora 2 per clip) + +**Capabilities:** +- Up to 20 seconds at up to 2K resolution +- Simultaneous audio-visual generation (Dual-Branch Diffusion Transformer) +- Text-to-video and image-to-video +- Up to 12 reference files for multimodal input +- OpenAI-compatible API structure + +**Ad creative use cases:** +- High-volume short video ad production at low cost +- Video ads with synchronized voiceover and sound effects in one pass +- Multi-reference generation (feed product images, brand assets, style references) +- Rapid iteration on video ad concepts + +**Docs:** [Seedance](https://seed.bytedance.com/en/seedance2_0) + +--- + +### Higgsfield + +Full-stack video creation platform with cinematic camera controls. + +**Best for:** Social video ads, cinematic style, mobile-first content +**Platform:** [higgsfield.ai](https://higgsfield.ai/) + +**Capabilities:** +- 50+ professional camera movements (zooms, pans, FPV drone shots) +- Image-to-video animation +- Built-in editing, transitions, and keyframing +- All-in-one workflow: image gen, animation, editing + +**Ad creative use cases:** +- Social media video ads with cinematic feel +- Animate product images into dynamic video +- Create multiple video variations with different camera styles +- Quick-turn video content for social campaigns + +--- + +### Video Tool Comparison + +| Tool | Max Length | Audio | Resolution | API | Best For | +|------|-----------|-------|------------|-----|----------| +| **Veo 3.1** | 60 sec | Native | 1080p/4K | Gemini | Vertical social video | +| **Kling 2.6** | 3 min | Native | 1080p | Third-party | Longer cinematic | +| **Runway Gen-4** | 10 sec | No | 1080p | Official | Controlled, consistent | +| **Sora 2** | 60 sec | Native | 1080p | Official | Dialogue-heavy | +| **Seedance 2.0** | 20 sec | Native | 2K | Official + third-party | Affordable high-volume | +| **Higgsfield** | Varies | Yes | 1080p | Web-based | Social, mobile-first | + +--- + +## Voice & Audio Generation + +For layering realistic voiceovers onto video ads, adding narration to product demos, or generating audio for Remotion-rendered videos. These tools turn ad scripts into natural-sounding voice tracks. + +### When to Use Voice Tools + +Many video generators (Veo, Kling, Sora, Seedance) now include native audio. Use standalone voice tools when you need: + +- **Voiceover on silent video** — Runway Gen-4 and Remotion produce silent output +- **Brand voice consistency** — Clone a specific voice for all ads +- **Multi-language versions** — Same ad script in 20+ languages +- **Script iteration** — Re-record voiceover without reshooting video +- **Precise control** — Exact timing, emotion, and pacing + +--- + +### ElevenLabs + +The market leader in realistic voice generation and voice cloning. + +**Best for:** Most natural-sounding voiceovers, brand voice cloning, multilingual +**API:** REST API with streaming support +**Pricing:** ~$0.12-0.30 per 1,000 characters depending on plan; starts at $5/month + +**Capabilities:** +- 29+ languages with natural accent and intonation +- Voice cloning from short audio clips (instant) or longer recordings (professional) +- Emotion and style control +- Streaming for real-time generation +- Voice library with hundreds of pre-built voices + +**Ad creative use cases:** +- Generate voiceover tracks for video ads +- Clone your brand spokesperson's voice for all ad variations +- Produce the same ad in 10+ languages from one script +- A/B test different voice styles (authoritative vs. friendly vs. urgent) + +**API example:** +```bash +curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/{voice_id}" \ + -H "xi-api-key: $ELEVENLABS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "text": "Stop wasting hours on manual reporting. Try DataFlow free for 14 days.", + "model_id": "eleven_multilingual_v2", + "voice_settings": {"stability": 0.5, "similarity_boost": 0.75} + }' --output voiceover.mp3 +``` + +**Docs:** [ElevenLabs API](https://elevenlabs.io/docs/api-reference/text-to-speech) + +--- + +### OpenAI TTS + +Simple, affordable text-to-speech built into the OpenAI API. + +**Best for:** Quick voiceovers, cost-effective at scale, simple integration +**API:** OpenAI API (same SDK as GPT/DALL-E) +**Pricing:** $15/million chars (standard), $30/million chars (HD); ~$0.015/min with gpt-4o-mini-tts + +**Capabilities:** +- 13 built-in voices (no custom cloning) +- Multiple languages +- Real-time streaming +- HD quality option +- Simple API — same SDK you already use for GPT + +**Ad creative use cases:** +- Fast, cheap voiceover for draft/test ad versions +- High-volume narration at low cost +- Prototype ad audio before investing in premium voice + +**Docs:** [OpenAI TTS](https://platform.openai.com/docs/guides/text-to-speech) + +--- + +### Cartesia Sonic + +Ultra-low latency voice generation built for real-time applications. + +**Best for:** Real-time voice, lowest latency, emotional expressiveness +**API:** REST + WebSocket streaming +**Pricing:** Starts at $5/month; pay-as-you-go from $0.03/min + +**Capabilities:** +- 40ms time-to-first-audio (fastest in class) +- 15+ languages +- Nonverbal expressiveness: laughter, breathing, emotional inflections +- Sonic Turbo for even lower latency +- Streaming API for real-time generation + +**Ad creative use cases:** +- Real-time ad preview during creative iteration +- Interactive demo videos with dynamic narration +- Ads requiring natural laughter, sighs, or emotional reactions + +**Docs:** [Cartesia Sonic](https://docs.cartesia.ai/build-with-cartesia/tts-models/latest) + +--- + +### Voicebox (Open Source) + +Free, local-first voice synthesis studio powered by Qwen3-TTS. The open-source alternative to ElevenLabs. + +**Best for:** Free voice cloning, local/private generation, zero-cost batch production +**API:** Local REST API at `http://localhost:8000` +**Pricing:** Free (MIT license). Runs entirely on your machine. +**Stack:** Tauri (Rust) + React + FastAPI (Python) + +**Capabilities:** +- Voice cloning from short audio samples via Qwen3-TTS +- Multi-language support (English, Chinese, more planned) +- Multi-track timeline editor for composing conversations +- 4-5x faster inference on Apple Silicon via MLX Metal acceleration +- Local REST API for programmatic generation +- No cloud dependency — all processing on-device + +**Ad creative use cases:** +- Free voice cloning for brand spokesperson across all ad variations +- Batch generate voiceovers without per-character costs +- Private/local generation when ad content is sensitive or pre-launch +- Prototype voice variations before committing to a paid service + +**API example:** +```bash +curl -X POST http://localhost:8000/generate \ + -H "Content-Type: application/json" \ + -d '{"text": "Stop wasting hours on manual reporting.", "profile_id": "abc123", "language": "en"}' +``` + +**Install:** Desktop apps for macOS and Windows at [voicebox.sh](https://voicebox.sh), or build from source: +```bash +git clone https://github.com/jamiepine/voicebox.git +cd voicebox && make setup && make dev +``` + +**Docs:** [GitHub](https://github.com/jamiepine/voicebox) + +--- + +### Other Voice Tools + +| Tool | Best For | Differentiator | API | +|------|----------|---------------|-----| +| **PlayHT** | Large voice library, low latency | 900+ voices, <300ms latency, ultra-realistic | [play.ht](https://play.ht/) | +| **Resemble AI** | Enterprise voice cloning | On-premise deployment, real-time speech-to-speech | [resemble.ai](https://www.resemble.ai/) | +| **WellSaid Labs** | Ethical, commercial-safe voices | Voices from compensated actors, safe for commercial use | [wellsaid.io](https://www.wellsaid.io/) | +| **Fish Audio** | Budget-friendly, emotion control | ~50-70% cheaper than ElevenLabs, emotion tags | [fish.audio](https://fish.audio/) | +| **Murf AI** | Non-technical teams | Browser-based studio, 200+ voices | [murf.ai](https://murf.ai/) | +| **Google Cloud TTS** | Google ecosystem, scale | 220+ voices, 40+ languages, enterprise SLAs | [Google TTS](https://cloud.google.com/text-to-speech) | +| **Amazon Polly** | AWS ecosystem, cost | Neural voices, SSML control, cheap at volume | [Amazon Polly](https://aws.amazon.com/polly/) | + +--- + +### Voice Tool Comparison + +| Tool | Quality | Cloning | Languages | Latency | Price/1K chars | +|------|---------|---------|-----------|---------|----------------| +| **ElevenLabs** | Best | Yes (instant + pro) | 29+ | ~200ms | $0.12-0.30 | +| **OpenAI TTS** | Good | No | 13+ | ~300ms | $0.015-0.030 | +| **Cartesia Sonic** | Very good | No | 15+ | ~40ms | ~$0.03/min | +| **PlayHT** | Very good | Yes | 140+ | <300ms | ~$0.10-0.20 | +| **Fish Audio** | Good | Yes | 13+ | ~200ms | ~$0.05-0.10 | +| **WellSaid** | Very good | No (actor voices) | English | ~300ms | Custom pricing | +| **Voicebox** | Good | Yes (local) | 2+ | Local | Free (open source) | + +### Choosing a Voice Tool + +``` +Need voiceover for ads? +├── Need to clone a specific brand voice? +│ ├── Best quality → ElevenLabs +│ ├── Enterprise/on-premise → Resemble AI +│ └── Budget-friendly → Fish Audio, PlayHT +├── Need multilingual (same ad, many languages)? +│ ├── Most languages → PlayHT (140+) +│ └── Best quality → ElevenLabs (29+) +├── Need free / open source / local? +│ └── Voicebox (MIT, runs on your machine) +├── Need cheap, fast, good-enough? +│ └── OpenAI TTS ($0.015/min) +├── Need commercially-safe licensing? +│ └── WellSaid Labs (actor-compensated voices) +└── Need real-time/interactive? + └── Cartesia Sonic (40ms TTFA) +``` + +### Workflow: Voice + Video + +``` +1. Write ad script (use ad-creative skill for copy) +2. Generate voiceover with ElevenLabs/OpenAI TTS +3. Generate or render video: + a. Silent video from Runway/Remotion → layer voice track + b. Or use Veo/Sora/Seedance with native audio (skip separate VO) +4. Combine with ffmpeg if layering separately: + ffmpeg -i video.mp4 -i voiceover.mp3 -c:v copy -c:a aac output.mp4 +5. Generate variations (different scripts, voices, or languages) +``` + +--- + +## Code-Based Video: Remotion + +For templated, data-driven video ads at scale, Remotion is the best option. Unlike AI video generators that produce unique video from prompts, Remotion uses React code to render deterministic, brand-perfect video from templates and data. + +**Best for:** Templated ad variations, personalized video, brand-consistent production +**Stack:** React + TypeScript +**Pricing:** Free for individuals/small teams; commercial license required for 4+ employees +**Docs:** [remotion.dev](https://www.remotion.dev/) + +### Why Remotion for Ads + +| AI Video Generators | Remotion | +|---------------------|----------| +| Unique output each time | Deterministic, pixel-perfect | +| Prompt-based, less control | Full code control over every frame | +| Hard to match brand exactly | Exact brand colors, fonts, spacing | +| One-at-a-time generation | Batch render hundreds from data | +| No dynamic data insertion | Personalize with names, prices, stats | + +### Ad Creative Use Cases + +**1. Dynamic product ads** +Feed a JSON array of products and render a unique video ad for each: +```tsx +// Simplified Remotion component for product ads +export const ProductAd: React.FC<{ + productName: string; + price: string; + imageUrl: string; + tagline: string; +}> = ({productName, price, imageUrl, tagline}) => { + return ( + + +

{productName}

+

{tagline}

+
{price}
+
Shop Now
+ + ); +}; +``` + +**2. A/B test video variations** +Render the same template with different headlines, CTAs, or color schemes: +```tsx +const variations = [ + {headline: "Save 50% Today", cta: "Get the Deal", theme: "urgent"}, + {headline: "Join 10K+ Teams", cta: "Start Free", theme: "social-proof"}, + {headline: "Built for Speed", cta: "Try It Now", theme: "benefit"}, +]; +// Render all variations programmatically +``` + +**3. Personalized outreach videos** +Generate videos addressing prospects by name for cold outreach or sales. + +**4. Social ad batch production** +Render the same content across different aspect ratios: +- 1:1 for feed +- 9:16 for Stories/Reels +- 16:9 for YouTube + +### Remotion Workflow for Ad Creative + +``` +1. Design template in React (or use AI to generate the component) +2. Define data schema (products, headlines, CTAs, images) +3. Feed data array into template +4. Batch render all variations +5. Upload to ad platform +``` + +### Getting Started + +```bash +# Create a new Remotion project +npx create-video@latest + +# Render a single video +npx remotion render src/index.ts MyComposition out/video.mp4 + +# Batch render from data +npx remotion render src/index.ts MyComposition --props='{"data": [...]}' +``` + +--- + +## Choosing the Right Tool + +### Decision Tree + +``` +Need video ads? +├── Templated, data-driven (same structure, different data) +│ └── Use Remotion +├── Unique creative from prompts (exploratory) +│ ├── Need dialogue/voiceover? → Sora 2, Veo 3.1, Kling 2.6, Seedance 2.0 +│ ├── Need consistency across scenes? → Runway Gen-4 +│ ├── Need vertical social video? → Veo 3.1 (native 9:16) +│ ├── Need high volume at low cost? → Seedance 2.0 +│ └── Need cinematic camera work? → Higgsfield, Kling +└── Both → Use AI gen for hero creative, Remotion for variations + +Need image ads? +├── Need text/headlines in image? → Ideogram +├── Need product consistency across variations? → Flux (multi-ref) +├── Need quick iterations on existing images? → Nano Banana Pro +├── Need highest visual quality? → Flux Pro, Midjourney +└── Need high volume at low cost? → Flux Klein, Nano Banana +``` + +### Cost Comparison for 100 Ad Variations + +| Approach | Tool | Approximate Cost | +|----------|------|-----------------| +| 100 static images | Nano Banana Pro | ~$4-24 | +| 100 static images | Flux Dev | ~$1-2 | +| 100 static images | Ideogram API | ~$6 | +| 100 × 15-sec videos | Veo 3.1 Fast | ~$225 | +| 100 × 15-sec videos | Remotion (templated) | ~$0 (self-hosted render) | +| 10 hero videos + 90 templated | Veo + Remotion | ~$22 + render time | + +### Recommended Workflow for Scaled Ad Production + +1. **Generate hero creative** with AI (Nano Banana, Flux, Veo) — high-quality, exploratory +2. **Build templates** in Remotion based on winning creative patterns +3. **Batch produce variations** with Remotion using data (products, headlines, CTAs) +4. **Iterate** — use AI tools for new angles, Remotion for scale + +This hybrid approach gives you the creative exploration of AI generators and the consistency and scale of code-based rendering. + +--- + +## Platform-Specific Image Specs + +When generating images for ads, request the correct dimensions: + +| Platform | Placement | Aspect Ratio | Recommended Size | +|----------|-----------|-------------|-----------------| +| Meta Feed | Single image | 1:1 | 1080x1080 | +| Meta Stories/Reels | Vertical | 9:16 | 1080x1920 | +| Meta Carousel | Square | 1:1 | 1080x1080 | +| Google Display | Landscape | 1.91:1 | 1200x628 | +| Google Display | Square | 1:1 | 1200x1200 | +| LinkedIn Feed | Landscape | 1.91:1 | 1200x627 | +| LinkedIn Feed | Square | 1:1 | 1200x1200 | +| TikTok Feed | Vertical | 9:16 | 1080x1920 | +| Twitter/X Feed | Landscape | 16:9 | 1200x675 | +| Twitter/X Card | Landscape | 1.91:1 | 800x418 | + +Include these dimensions in your generation prompts to avoid needing to crop or resize. diff --git a/.agents/skills/ad-creative/references/platform-specs.md b/.agents/skills/ad-creative/references/platform-specs.md new file mode 100644 index 00000000..c9a3c4a5 --- /dev/null +++ b/.agents/skills/ad-creative/references/platform-specs.md @@ -0,0 +1,213 @@ +# Platform Specs Reference + +Complete character limits, format requirements, and best practices for each ad platform. + +--- + +## Google Ads + +### Responsive Search Ads (RSAs) + +| Element | Character Limit | Required | Notes | +|---------|----------------|----------|-------| +| Headline | 30 chars | 3 minimum, 15 max | Any 3 may be shown together | +| Description | 90 chars | 2 minimum, 4 max | Any 2 may be shown together | +| Display path 1 | 15 chars | Optional | Appears after domain in URL | +| Display path 2 | 15 chars | Optional | Appears after path 1 | +| Final URL | No limit | Required | Landing page URL | + +**Combination rules:** +- Google selects up to 3 headlines and 2 descriptions to show +- Headlines appear separated by " | " or stacked +- Any headline can appear in any position unless pinned +- Pinning reduces Google's ability to optimize — use sparingly + +**Pinning strategy:** +- Pin your brand name to position 1 if brand guidelines require it +- Pin your strongest CTA to position 2 or 3 +- Leave most headlines unpinned for machine learning + +**Headline mix recommendation (15 headlines):** +- 3-4 keyword-focused (match search intent) +- 3-4 benefit-focused (what they get) +- 2-3 social proof (numbers, awards, customers) +- 2-3 CTA-focused (action to take) +- 1-2 differentiators (why you over competitors) +- 1 brand name headline + +**Description mix recommendation (4 descriptions):** +- 1 benefit + proof point +- 1 feature + outcome +- 1 social proof + CTA +- 1 urgency/offer + CTA (if applicable) + +### Performance Max + +| Element | Character Limit | Notes | +|---------|----------------|-------| +| Headline | 30 chars (5 required) | Short headlines for various placements | +| Long headline | 90 chars (5 required) | Used in display, video, discover | +| Description | 90 chars (1 required, 5 max) | Accompany various ad formats | +| Business name | 25 chars | Required | + +### Display Ads + +| Element | Character Limit | +|---------|----------------| +| Headline | 30 chars | +| Long headline | 90 chars | +| Description | 90 chars | +| Business name | 25 chars | + +--- + +## Meta Ads (Facebook & Instagram) + +### Single Image / Video / Carousel + +| Element | Recommended | Maximum | Notes | +|---------|-------------|---------|-------| +| Primary text | 125 chars | 2,200 chars | Text above image; truncated after ~125 | +| Headline | 40 chars | 255 chars | Below image; truncated after ~40 | +| Description | 30 chars | 255 chars | Below headline; may not show | +| URL display link | 40 chars | N/A | Optional custom display URL | + +**Placement-specific notes:** +- **Feed**: All elements show; primary text most visible +- **Stories/Reels**: Primary text overlaid; keep under 72 chars +- **Right column**: Only headline visible; skip description +- **Audience Network**: Varies by publisher + +**Best practices:** +- Front-load the hook in primary text (first 125 chars) +- Use line breaks for readability in longer primary text +- Emojis: test, but don't overuse — 1-2 per ad max +- Questions in primary text increase engagement +- Headline should be a clear CTA or value statement + +### Lead Ads (Instant Form) + +| Element | Limit | +|---------|-------| +| Greeting headline | 60 chars | +| Greeting description | 360 chars | +| Privacy policy text | 200 chars | + +--- + +## LinkedIn Ads + +### Single Image Ad + +| Element | Recommended | Maximum | Notes | +|---------|-------------|---------|-------| +| Intro text | 150 chars | 600 chars | Above the image; truncated after ~150 | +| Headline | 70 chars | 200 chars | Below the image | +| Description | 100 chars | 300 chars | Only shows on Audience Network | + +### Carousel Ad + +| Element | Limit | +|---------|-------| +| Intro text | 255 chars | +| Card headline | 45 chars | +| Card count | 2-10 cards | + +### Message Ad (InMail) + +| Element | Limit | +|---------|-------| +| Subject line | 60 chars | +| Message body | 1,500 chars | +| CTA button | 20 chars | + +### Text Ad + +| Element | Limit | +|---------|-------| +| Headline | 25 chars | +| Description | 75 chars | + +**LinkedIn-specific guidelines:** +- Professional tone, but not boring +- Use job-specific language the audience recognizes +- Statistics and data points perform well +- Avoid consumer-style hype ("Amazing!" "Incredible!") +- First-person testimonials from peers resonate + +--- + +## TikTok Ads + +### In-Feed Ads + +| Element | Recommended | Maximum | Notes | +|---------|-------------|---------|-------| +| Ad text | 80 chars | 100 chars | Above the video | +| Display name | N/A | 40 chars | Brand name | +| CTA button | Platform options | Predefined | Select from TikTok's options | + +### Spark Ads (Boosted Organic) + +| Element | Notes | +|---------|-------| +| Caption | Uses original post caption | +| CTA button | Added by advertiser | +| Display name | Original creator's handle | + +**TikTok-specific guidelines:** +- Native content outperforms polished ads +- First 2 seconds determine if they watch +- Use trending sounds and formats +- Text overlay is essential (most watch with sound off) +- Vertical video only (9:16) + +--- + +## Twitter/X Ads + +### Promoted Tweets + +| Element | Limit | Notes | +|---------|-------|-------| +| Tweet text | 280 chars | Full tweet with image/video | +| Card headline | 70 chars | Website card | +| Card description | 200 chars | Website card | + +### Website Cards + +| Element | Limit | +|---------|-------| +| Headline | 70 chars | +| Description | 200 chars | + +**Twitter/X-specific guidelines:** +- Conversational, casual tone +- Short sentences work best +- One clear message per tweet +- Hashtags: 1-2 max (0 is often better for ads) +- Threads can work for consideration-stage content + +--- + +## Character Counting Tips + +- **Spaces count** as characters on all platforms +- **Emojis** count as 1-2 characters depending on platform +- **Special characters** (|, &, etc.) count as 1 character +- **URLs** in body text count against limits +- **Dynamic keyword insertion** (`{KeyWord:default}`) can exceed limits — set safe defaults +- Always verify in the platform's ad preview before launching + +--- + +## Multi-Platform Creative Adaptation + +When creating for multiple platforms simultaneously, start with the most restrictive format: + +1. **Google Search headlines** (30 chars) — forces the tightest messaging +2. **Expand to Meta headlines** (40 chars) — add a word or two +3. **Expand to LinkedIn intro text** (150 chars) — add context and proof +4. **Expand to Meta primary text** (125+ chars) — full hook and value prop + +This cascading approach ensures your core message works everywhere, then gets enriched for platforms that allow more space. diff --git a/.agents/skills/ai-seo/SKILL.md b/.agents/skills/ai-seo/SKILL.md new file mode 100644 index 00000000..eb864f12 --- /dev/null +++ b/.agents/skills/ai-seo/SKILL.md @@ -0,0 +1,398 @@ +--- +name: ai-seo +description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' or 'zero-click search.' This skill covers content optimization for AI answer engines, monitoring AI visibility, and getting cited as a source. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema-markup." +metadata: + version: 1.1.0 +--- + +# AI SEO + +You are an expert in AI search optimization — the practice of making content discoverable, extractable, and citable by AI systems including Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, and Copilot. Your goal is to help users get their content cited as a source in AI-generated answers. + +## Before Starting + +**Check for product marketing context first:** +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. Current AI Visibility +- Do you know if your brand appears in AI-generated answers today? +- Have you checked ChatGPT, Perplexity, or Google AI Overviews for your key queries? +- What queries matter most to your business? + +### 2. Content & Domain +- What type of content do you produce? (Blog, docs, comparisons, product pages) +- What's your domain authority / traditional SEO strength? +- Do you have existing structured data (schema markup)? + +### 3. Goals +- Get cited as a source in AI answers? +- Appear in Google AI Overviews for specific queries? +- Compete with specific brands already getting cited? +- Optimize existing content or create new AI-optimized content? + +### 4. Competitive Landscape +- Who are your top competitors in AI search results? +- Are they being cited where you're not? + +--- + +## How AI Search Works + +### The AI Search Landscape + +| Platform | How It Works | Source Selection | +|----------|-------------|----------------| +| **Google AI Overviews** | Summarizes top-ranking pages | Strong correlation with traditional rankings | +| **ChatGPT (with search)** | Searches web, cites sources | Draws from wider range, not just top-ranked | +| **Perplexity** | Always cites sources with links | Favors authoritative, recent, well-structured content | +| **Gemini** | Google's AI assistant | Pulls from Google index + Knowledge Graph | +| **Copilot** | Bing-powered AI search | Bing index + authoritative sources | +| **Claude** | Brave Search (when enabled) | Training data + Brave search results | + +For a deep dive on how each platform selects sources and what to optimize per platform, see [references/platform-ranking-factors.md](references/platform-ranking-factors.md). + +### Key Difference from Traditional SEO + +Traditional SEO gets you ranked. AI SEO gets you **cited**. + +In traditional search, you need to rank on page 1. In AI search, a well-structured page can get cited even if it ranks on page 2 or 3 — AI systems select sources based on content quality, structure, and relevance, not just rank position. + +**Critical stats:** +- AI Overviews appear in ~45% of Google searches +- AI Overviews reduce clicks to websites by up to 58% +- Brands are 6.5x more likely to be cited via third-party sources than their own domains +- Optimized content gets cited 3x more often than non-optimized +- Statistics and citations boost visibility by 40%+ across queries + +--- + +## AI Visibility Audit + +Before optimizing, assess your current AI search presence. + +### Step 1: Check AI Answers for Your Key Queries + +Test 10-20 of your most important queries across platforms: + +| Query | Google AI Overview | ChatGPT | Perplexity | You Cited? | Competitors Cited? | +|-------|:-----------------:|:-------:|:----------:|:----------:|:-----------------:| +| [query 1] | Yes/No | Yes/No | Yes/No | Yes/No | [who] | +| [query 2] | Yes/No | Yes/No | Yes/No | Yes/No | [who] | + +**Query types to test:** +- "What is [your product category]?" +- "Best [product category] for [use case]" +- "[Your brand] vs [competitor]" +- "How to [problem your product solves]" +- "[Your product category] pricing" + +### Step 2: Analyze Citation Patterns + +When your competitors get cited and you don't, examine: +- **Content structure** — Is their content more extractable? +- **Authority signals** — Do they have more citations, stats, expert quotes? +- **Freshness** — Is their content more recently updated? +- **Schema markup** — Do they have structured data you're missing? +- **Third-party presence** — Are they cited via Wikipedia, Reddit, review sites? + +### Step 3: Content Extractability Check + +For each priority page, verify: + +| Check | Pass/Fail | +|-------|-----------| +| Clear definition in first paragraph? | | +| Self-contained answer blocks (work without surrounding context)? | | +| Statistics with sources cited? | | +| Comparison tables for "[X] vs [Y]" queries? | | +| FAQ section with natural-language questions? | | +| Schema markup (FAQ, HowTo, Article, Product)? | | +| Expert attribution (author name, credentials)? | | +| Recently updated (within 6 months)? | | +| Heading structure matches query patterns? | | +| AI bots allowed in robots.txt? | | + +### Step 4: AI Bot Access Check + +Verify your robots.txt allows AI crawlers. Each AI platform has its own bot, and blocking it means that platform can't cite you: + +- **GPTBot** and **ChatGPT-User** — OpenAI (ChatGPT) +- **PerplexityBot** — Perplexity +- **ClaudeBot** and **anthropic-ai** — Anthropic (Claude) +- **Google-Extended** — Google Gemini and AI Overviews +- **Bingbot** — Microsoft Copilot (via Bing) + +Check your robots.txt for `Disallow` rules targeting any of these. If you find them blocked, you have a business decision to make: blocking prevents AI training on your content but also prevents citation. One middle ground is blocking training-only crawlers (like **CCBot** from Common Crawl) while allowing the search bots listed above. + +See [references/platform-ranking-factors.md](references/platform-ranking-factors.md) for the full robots.txt configuration. + +--- + +## Optimization Strategy + +### The Three Pillars + +``` +1. Structure (make it extractable) +2. Authority (make it citable) +3. Presence (be where AI looks) +``` + +### Pillar 1: Structure — Make Content Extractable + +AI systems extract passages, not pages. Every key claim should work as a standalone statement. + +**Content block patterns:** +- **Definition blocks** for "What is X?" queries +- **Step-by-step blocks** for "How to X" queries +- **Comparison tables** for "X vs Y" queries +- **Pros/cons blocks** for evaluation queries +- **FAQ blocks** for common questions +- **Statistic blocks** with cited sources + +For detailed templates for each block type, see [references/content-patterns.md](references/content-patterns.md). + +**Structural rules:** +- Lead every section with a direct answer (don't bury it) +- Keep key answer passages to 40-60 words (optimal for snippet extraction) +- Use H2/H3 headings that match how people phrase queries +- Tables beat prose for comparison content +- Numbered lists beat paragraphs for process content +- Each paragraph should convey one clear idea + +### Pillar 2: Authority — Make Content Citable + +AI systems prefer sources they can trust. Build citation-worthiness. + +**The Princeton GEO research** (KDD 2024, studied across Perplexity.ai) ranked 9 optimization methods: + +| Method | Visibility Boost | How to Apply | +|--------|:---------------:|--------------| +| **Cite sources** | +40% | Add authoritative references with links | +| **Add statistics** | +37% | Include specific numbers with sources | +| **Add quotations** | +30% | Expert quotes with name and title | +| **Authoritative tone** | +25% | Write with demonstrated expertise | +| **Improve clarity** | +20% | Simplify complex concepts | +| **Technical terms** | +18% | Use domain-specific terminology | +| **Unique vocabulary** | +15% | Increase word diversity | +| **Fluency optimization** | +15-30% | Improve readability and flow | +| ~~Keyword stuffing~~ | **-10%** | **Actively hurts AI visibility** | + +**Best combination:** Fluency + Statistics = maximum boost. Low-ranking sites benefit even more — up to 115% visibility increase with citations. + +**Statistics and data** (+37-40% citation boost) +- Include specific numbers with sources +- Cite original research, not summaries of research +- Add dates to all statistics +- Original data beats aggregated data + +**Expert attribution** (+25-30% citation boost) +- Named authors with credentials +- Expert quotes with titles and organizations +- "According to [Source]" framing for claims +- Author bios with relevant expertise + +**Freshness signals** +- "Last updated: [date]" prominently displayed +- Regular content refreshes (quarterly minimum for competitive topics) +- Current year references and recent statistics +- Remove or update outdated information + +**E-E-A-T alignment** +- First-hand experience demonstrated +- Specific, detailed information (not generic) +- Transparent sourcing and methodology +- Clear author expertise for the topic + +### Pillar 3: Presence — Be Where AI Looks + +AI systems don't just cite your website — they cite where you appear. + +**Third-party sources matter more than your own site:** +- Wikipedia mentions (7.8% of all ChatGPT citations) +- Reddit discussions (1.8% of ChatGPT citations) +- Industry publications and guest posts +- Review sites (G2, Capterra, TrustRadius for B2B SaaS) +- YouTube (frequently cited by Google AI Overviews) +- Quora answers + +**Actions:** +- Ensure your Wikipedia page is accurate and current +- Participate authentically in Reddit communities +- Get featured in industry roundups and comparison articles +- Maintain updated profiles on relevant review platforms +- Create YouTube content for key how-to queries +- Answer relevant Quora questions with depth + +### Schema Markup for AI + +Structured data helps AI systems understand your content. Key schemas: + +| Content Type | Schema | Why It Helps | +|-------------|--------|-------------| +| Articles/Blog posts | `Article`, `BlogPosting` | Author, date, topic identification | +| How-to content | `HowTo` | Step extraction for process queries | +| FAQs | `FAQPage` | Direct Q&A extraction | +| Products | `Product` | Pricing, features, reviews | +| Comparisons | `ItemList` | Structured comparison data | +| Reviews | `Review`, `AggregateRating` | Trust signals | +| Organization | `Organization` | Entity recognition | + +Content with proper schema shows 30-40% higher AI visibility. For implementation, use the **schema-markup** skill. + +--- + +## Content Types That Get Cited Most + +Not all content is equally citable. Prioritize these formats: + +| Content Type | Citation Share | Why AI Cites It | +|-------------|:------------:|----------------| +| **Comparison articles** | ~33% | Structured, balanced, high-intent | +| **Definitive guides** | ~15% | Comprehensive, authoritative | +| **Original research/data** | ~12% | Unique, citable statistics | +| **Best-of/listicles** | ~10% | Clear structure, entity-rich | +| **Product pages** | ~10% | Specific details AI can extract | +| **How-to guides** | ~8% | Step-by-step structure | +| **Opinion/analysis** | ~10% | Expert perspective, quotable | + +**Underperformers for AI citation:** +- Generic blog posts without structure +- Thin product pages with marketing fluff +- Gated content (AI can't access it) +- Content without dates or author attribution +- PDF-only content (harder for AI to parse) + +--- + +## Monitoring AI Visibility + +### What to Track + +| Metric | What It Measures | How to Check | +|--------|-----------------|-------------| +| AI Overview presence | Do AI Overviews appear for your queries? | Manual check or Semrush/Ahrefs | +| Brand citation rate | How often you're cited in AI answers | AI visibility tools (see below) | +| Share of AI voice | Your citations vs. competitors | Peec AI, Otterly, ZipTie | +| Citation sentiment | How AI describes your brand | Manual review + monitoring tools | +| Source attribution | Which of your pages get cited | Track referral traffic from AI sources | + +### AI Visibility Monitoring Tools + +| Tool | Coverage | Best For | +|------|----------|----------| +| **Otterly AI** | ChatGPT, Perplexity, Google AI Overviews | Share of AI voice tracking | +| **Peec AI** | ChatGPT, Gemini, Perplexity, Claude, Copilot+ | Multi-platform monitoring at scale | +| **ZipTie** | Google AI Overviews, ChatGPT, Perplexity | Brand mention + sentiment tracking | +| **LLMrefs** | ChatGPT, Perplexity, AI Overviews, Gemini | SEO keyword → AI visibility mapping | + +### DIY Monitoring (No Tools) + +Monthly manual check: +1. Pick your top 20 queries +2. Run each through ChatGPT, Perplexity, and Google +3. Record: Are you cited? Who is? What page? +4. Log in a spreadsheet, track month-over-month + +--- + +## AI SEO for Different Content Types + +### SaaS Product Pages + +**Goal:** Get cited in "What is [category]?" and "Best [category]" queries. + +**Optimize:** +- Clear product description in first paragraph (what it does, who it's for) +- Feature comparison tables (you vs. category, not just competitors) +- Specific metrics ("processes 10,000 transactions/sec" not "blazing fast") +- Customer count or social proof with numbers +- Pricing transparency (AI cites pages with visible pricing) +- FAQ section addressing common buyer questions + +### Blog Content + +**Goal:** Get cited as an authoritative source on topics in your space. + +**Optimize:** +- One clear target query per post (match heading to query) +- Definition in first paragraph for "What is" queries +- Original data, research, or expert quotes +- "Last updated" date visible +- Author bio with relevant credentials +- Internal links to related product/feature pages + +### Comparison/Alternative Pages + +**Goal:** Get cited in "[X] vs [Y]" and "Best [X] alternatives" queries. + +**Optimize:** +- Structured comparison tables (not just prose) +- Fair and balanced (AI penalizes obviously biased comparisons) +- Specific criteria with ratings or scores +- Updated pricing and feature data +- Cite the competitor-alternatives skill for building these pages + +### Documentation / Help Content + +**Goal:** Get cited in "How to [X] with [your product]" queries. + +**Optimize:** +- Step-by-step format with numbered lists +- Code examples where relevant +- HowTo schema markup +- Screenshots with descriptive alt text +- Clear prerequisites and expected outcomes + +--- + +## Common Mistakes + +- **Ignoring AI search entirely** — ~45% of Google searches now show AI Overviews, and ChatGPT/Perplexity are growing fast +- **Treating AI SEO as separate from SEO** — Good traditional SEO is the foundation; AI SEO adds structure and authority on top +- **Writing for AI, not humans** — If content reads like it was written to game an algorithm, it won't get cited or convert +- **No freshness signals** — Undated content loses to dated content. Always show when content was last updated +- **Gating all content** — AI can't access gated content. Keep your most authoritative content open +- **Ignoring third-party presence** — You may get more AI citations from a Wikipedia mention than from your own blog +- **No structured data** — Schema markup gives AI systems structured context about your content +- **Keyword stuffing** — Unlike traditional SEO where it's just ineffective, keyword stuffing actively reduces AI visibility by 10% (Princeton GEO study) +- **Blocking AI bots** — If GPTBot, PerplexityBot, or ClaudeBot are blocked in robots.txt, those platforms can't cite you +- **Generic content without data** — "We're the best" won't get cited. "Our customers see 3x improvement in [metric]" will +- **Forgetting to monitor** — You can't improve what you don't measure. Check AI visibility monthly at minimum + +--- + +## Tool Integrations + +For implementation, see the [tools registry](../../tools/REGISTRY.md). + +| Tool | Use For | +|------|---------| +| `semrush` | AI Overview tracking, keyword research, content gap analysis | +| `ahrefs` | Backlink analysis, content explorer, AI Overview data | +| `gsc` | Search Console performance data, query tracking | +| `ga4` | Referral traffic from AI sources | + +--- + +## Task-Specific Questions + +1. What are your top 10-20 most important queries? +2. Have you checked if AI answers exist for those queries today? +3. Do you have structured data (schema markup) on your site? +4. What content types do you publish? (Blog, docs, comparisons, etc.) +5. Are competitors being cited by AI where you're not? +6. Do you have a Wikipedia page or presence on review sites? + +--- + +## Related Skills + +- **seo-audit**: For traditional technical and on-page SEO audits +- **schema-markup**: For implementing structured data that helps AI understand your content +- **content-strategy**: For planning what content to create +- **competitor-alternatives**: For building comparison pages that get cited +- **programmatic-seo**: For building SEO pages at scale +- **copywriting**: For writing content that's both human-readable and AI-extractable diff --git a/.agents/skills/ai-seo/references/content-patterns.md b/.agents/skills/ai-seo/references/content-patterns.md new file mode 100644 index 00000000..e1926c80 --- /dev/null +++ b/.agents/skills/ai-seo/references/content-patterns.md @@ -0,0 +1,285 @@ +# AEO and GEO Content Patterns + +Reusable content block patterns optimized for answer engines and AI citation. + +--- + +## Contents +- Answer Engine Optimization (AEO) Patterns (Definition Block, Step-by-Step Block, Comparison Table Block, Pros and Cons Block, FAQ Block, Listicle Block) +- Generative Engine Optimization (GEO) Patterns (Statistic Citation Block, Expert Quote Block, Authoritative Claim Block, Self-Contained Answer Block, Evidence Sandwich Block) +- Domain-Specific GEO Tactics (Technology Content, Health/Medical Content, Financial Content, Legal Content, Business/Marketing Content) +- Voice Search Optimization (Question Formats for Voice, Voice-Optimized Answer Structure) + +## Answer Engine Optimization (AEO) Patterns + +These patterns help content appear in featured snippets, AI Overviews, voice search results, and answer boxes. + +### Definition Block + +Use for "What is [X]?" queries. + +```markdown +## What is [Term]? + +[Term] is [concise 1-sentence definition]. [Expanded 1-2 sentence explanation with key characteristics]. [Brief context on why it matters or how it's used]. +``` + +**Example:** +```markdown +## What is Answer Engine Optimization? + +Answer Engine Optimization (AEO) is the practice of structuring content so AI-powered systems can easily extract and present it as direct answers to user queries. Unlike traditional SEO that focuses on ranking in search results, AEO optimizes for featured snippets, AI Overviews, and voice assistant responses. This approach has become essential as over 60% of Google searches now end without a click. +``` + +### Step-by-Step Block + +Use for "How to [X]" queries. Optimal for list snippets. + +```markdown +## How to [Action/Goal] + +[1-sentence overview of the process] + +1. **[Step Name]**: [Clear action description in 1-2 sentences] +2. **[Step Name]**: [Clear action description in 1-2 sentences] +3. **[Step Name]**: [Clear action description in 1-2 sentences] +4. **[Step Name]**: [Clear action description in 1-2 sentences] +5. **[Step Name]**: [Clear action description in 1-2 sentences] + +[Optional: Brief note on expected outcome or time estimate] +``` + +**Example:** +```markdown +## How to Optimize Content for Featured Snippets + +Earning featured snippets requires strategic formatting and direct answers to search queries. + +1. **Identify snippet opportunities**: Use tools like Semrush or Ahrefs to find keywords where competitors have snippets you could capture. +2. **Match the snippet format**: Analyze whether the current snippet is a paragraph, list, or table, and format your content accordingly. +3. **Answer the question directly**: Provide a clear, concise answer (40-60 words for paragraph snippets) immediately after the question heading. +4. **Add supporting context**: Expand on your answer with examples, data, and expert insights in the following paragraphs. +5. **Use proper heading structure**: Place your target question as an H2 or H3, with the answer immediately following. + +Most featured snippets appear within 2-4 weeks of publishing well-optimized content. +``` + +### Comparison Table Block + +Use for "[X] vs [Y]" queries. Optimal for table snippets. + +```markdown +## [Option A] vs [Option B]: [Brief Descriptor] + +| Feature | [Option A] | [Option B] | +|---------|------------|------------| +| [Criteria 1] | [Value/Description] | [Value/Description] | +| [Criteria 2] | [Value/Description] | [Value/Description] | +| [Criteria 3] | [Value/Description] | [Value/Description] | +| [Criteria 4] | [Value/Description] | [Value/Description] | +| Best For | [Use case] | [Use case] | + +**Bottom line**: [1-2 sentence recommendation based on different needs] +``` + +### Pros and Cons Block + +Use for evaluation queries: "Is [X] worth it?", "Should I [X]?" + +```markdown +## Advantages and Disadvantages of [Topic] + +[1-sentence overview of the evaluation context] + +### Pros + +- **[Benefit category]**: [Specific explanation] +- **[Benefit category]**: [Specific explanation] +- **[Benefit category]**: [Specific explanation] + +### Cons + +- **[Drawback category]**: [Specific explanation] +- **[Drawback category]**: [Specific explanation] +- **[Drawback category]**: [Specific explanation] + +**Verdict**: [1-2 sentence balanced conclusion with recommendation] +``` + +### FAQ Block + +Use for topic pages with multiple common questions. Essential for FAQ schema. + +```markdown +## Frequently Asked Questions + +### [Question phrased exactly as users search]? + +[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences]. + +### [Question phrased exactly as users search]? + +[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences]. + +### [Question phrased exactly as users search]? + +[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences]. +``` + +**Tips for FAQ questions:** +- Use natural question phrasing ("How do I..." not "How does one...") +- Include question words: what, how, why, when, where, who, which +- Match "People Also Ask" queries from search results +- Keep answers between 50-100 words + +### Listicle Block + +Use for "Best [X]", "Top [X]", "[Number] ways to [X]" queries. + +```markdown +## [Number] Best [Items] for [Goal/Purpose] + +[1-2 sentence intro establishing context and selection criteria] + +### 1. [Item Name] + +[Why it's included in 2-3 sentences with specific benefits] + +### 2. [Item Name] + +[Why it's included in 2-3 sentences with specific benefits] + +### 3. [Item Name] + +[Why it's included in 2-3 sentences with specific benefits] +``` + +--- + +## Generative Engine Optimization (GEO) Patterns + +These patterns optimize content for citation by AI assistants like ChatGPT, Claude, Perplexity, and Gemini. + +### Statistic Citation Block + +Statistics increase AI citation rates by 15-30%. Always include sources. + +```markdown +[Claim statement]. According to [Source/Organization], [specific statistic with number and timeframe]. [Context for why this matters]. +``` + +**Example:** +```markdown +Mobile optimization is no longer optional for SEO success. According to Google's 2024 Core Web Vitals report, 70% of web traffic now comes from mobile devices, and pages failing mobile usability standards see 24% higher bounce rates. This makes mobile-first indexing a critical ranking factor. +``` + +### Expert Quote Block + +Named expert attribution adds credibility and increases citation likelihood. + +```markdown +"[Direct quote from expert]," says [Expert Name], [Title/Role] at [Organization]. [1 sentence of context or interpretation]. +``` + +**Example:** +```markdown +"The shift from keyword-driven search to intent-driven discovery represents the most significant change in SEO since mobile-first indexing," says Rand Fishkin, Co-founder of SparkToro. This perspective highlights why content strategies must evolve beyond traditional keyword optimization. +``` + +### Authoritative Claim Block + +Structure claims for easy AI extraction with clear attribution. + +```markdown +[Topic] [verb: is/has/requires/involves] [clear, specific claim]. [Source] [confirms/reports/found] that [supporting evidence]. This [explains/means/suggests] [implication or action]. +``` + +**Example:** +```markdown +E-E-A-T is the cornerstone of Google's content quality evaluation. Google's Search Quality Rater Guidelines confirm that trust is the most critical factor, stating that "untrustworthy pages have low E-E-A-T no matter how experienced, expert, or authoritative they may seem." This means content creators must prioritize transparency and accuracy above all other optimization tactics. +``` + +### Self-Contained Answer Block + +Create quotable, standalone statements that AI can extract directly. + +```markdown +**[Topic/Question]**: [Complete, self-contained answer that makes sense without additional context. Include specific details, numbers, or examples in 2-3 sentences.] +``` + +**Example:** +```markdown +**Ideal blog post length for SEO**: The optimal length for SEO blog posts is 1,500-2,500 words for competitive topics. This range allows comprehensive topic coverage while maintaining reader engagement. HubSpot research shows long-form content earns 77% more backlinks than short articles, directly impacting search rankings. +``` + +### Evidence Sandwich Block + +Structure claims with evidence for maximum credibility. + +```markdown +[Opening claim statement]. + +Evidence supporting this includes: +- [Data point 1 with source] +- [Data point 2 with source] +- [Data point 3 with source] + +[Concluding statement connecting evidence to actionable insight]. +``` + +--- + +## Domain-Specific GEO Tactics + +Different content domains benefit from different authority signals. + +### Technology Content +- Emphasize technical precision and correct terminology +- Include version numbers and dates for software/tools +- Reference official documentation +- Add code examples where relevant + +### Health/Medical Content +- Cite peer-reviewed studies with publication details +- Include expert credentials (MD, RN, etc.) +- Note study limitations and context +- Add "last reviewed" dates + +### Financial Content +- Reference regulatory bodies (SEC, FTC, etc.) +- Include specific numbers with timeframes +- Note that information is educational, not advice +- Cite recognized financial institutions + +### Legal Content +- Cite specific laws, statutes, and regulations +- Reference jurisdiction clearly +- Include professional disclaimers +- Note when professional consultation is advised + +### Business/Marketing Content +- Include case studies with measurable results +- Reference industry research and reports +- Add percentage changes and timeframes +- Quote recognized thought leaders + +--- + +## Voice Search Optimization + +Voice queries are conversational and question-based. Optimize for these patterns: + +### Question Formats for Voice +- "What is..." +- "How do I..." +- "Where can I find..." +- "Why does..." +- "When should I..." +- "Who is..." + +### Voice-Optimized Answer Structure +- Lead with direct answer (under 30 words ideal) +- Use natural, conversational language +- Avoid jargon unless targeting expert audience +- Include local context where relevant +- Structure for single spoken response diff --git a/.agents/skills/ai-seo/references/platform-ranking-factors.md b/.agents/skills/ai-seo/references/platform-ranking-factors.md new file mode 100644 index 00000000..4353d090 --- /dev/null +++ b/.agents/skills/ai-seo/references/platform-ranking-factors.md @@ -0,0 +1,152 @@ +# How Each AI Platform Picks Sources + +Each AI search platform has its own search index, ranking logic, and content preferences. This guide covers what matters for getting cited on each one. + +Sources cited throughout: Princeton GEO study (KDD 2024), SE Ranking domain authority study, ZipTie content-answer fit analysis. + +--- + +## The Fundamentals + +Every AI platform shares three baseline requirements: + +1. **Your content must be in their index** — Each platform uses a different search backend (Google, Bing, Brave, or their own). If you're not indexed, you can't be cited. +2. **Your content must be crawlable** — AI bots need access via robots.txt. Block the bot, lose the citation. +3. **Your content must be extractable** — AI systems pull passages, not pages. Clear structure and self-contained paragraphs win. + +Beyond these basics, each platform weights different signals. Here's what matters and where. + +--- + +## Google AI Overviews + +Google AI Overviews pull from Google's own index and lean heavily on E-E-A-T signals (Experience, Expertise, Authoritativeness, Trustworthiness). They appear in roughly 45% of Google searches. + +**What makes Google AI Overviews different:** They already have your traditional SEO signals — backlinks, page authority, topical relevance. The additional AI layer adds a preference for content with cited sources and structured data. Research shows that including authoritative citations in your content correlates with a 132% visibility boost, and writing with an authoritative (not salesy) tone adds another 89%. + +**Importantly, AI Overviews don't just recycle the traditional Top 10.** Only about 15% of AI Overview sources overlap with conventional organic results. Pages that wouldn't crack page 1 in traditional search can still get cited if they have strong structured data and clear, extractable answers. + +**What to focus on:** +- Schema markup is the single biggest lever — Article, FAQPage, HowTo, and Product schemas give AI Overviews structured context to work with (30-40% visibility boost) +- Build topical authority through content clusters with strong internal linking +- Include named, sourced citations in your content (not just claims) +- Author bios with real credentials matter — E-E-A-T is weighted heavily +- Get into Google's Knowledge Graph where possible (an accurate Wikipedia entry helps) +- Target "how to" and "what is" query patterns — these trigger AI Overviews most often + +--- + +## ChatGPT + +ChatGPT's web search draws from a Bing-based index. It combines this with its training knowledge to generate answers, then cites the web sources it relied on. + +**What makes ChatGPT different:** Domain authority matters more here than on other AI platforms. An SE Ranking analysis of 129,000 domains found that authority and credibility signals account for roughly 40% of what determines citation, with content quality at about 35% and platform trust at 25%. Sites with very high referring domain counts (350K+) average 8.4 citations per response, while sites with slightly lower trust scores (91-96 vs 97-100) drop from 8.4 to 6 citations. + +**Freshness is a major differentiator.** Content updated within the last 30 days gets cited about 3.2x more often than older content. ChatGPT clearly favors recent information. + +**The most important signal is content-answer fit** — a ZipTie analysis of 400,000 pages found that how well your content's style and structure matches ChatGPT's own response format accounts for about 55% of citation likelihood. This is far more important than domain authority (12%) or on-page structure (14%) alone. Write the way ChatGPT would answer the question, and you're more likely to be the source it cites. + +**Where ChatGPT looks beyond your site:** Wikipedia accounts for 7.8% of all ChatGPT citations, Reddit for 1.8%, and Forbes for 1.1%. Brand official sites are cited frequently but third-party mentions carry significant weight. + +**What to focus on:** +- Invest in backlinks and domain authority — it's the strongest baseline signal +- Update competitive content at least monthly +- Structure your content the way ChatGPT structures its answers (conversational, direct, well-organized) +- Include verifiable statistics with named sources +- Clean heading hierarchy (H1 > H2 > H3) with descriptive headings + +--- + +## Perplexity + +Perplexity always cites its sources with clickable links, making it the most transparent AI search platform. It combines its own index with Google's and runs results through multiple reranking passes — initial relevance retrieval, then traditional ranking factor scoring, then ML-based quality evaluation that can discard entire result sets if they don't meet quality thresholds. + +**What makes Perplexity different:** It's the most "research-oriented" AI search engine, and its citation behavior reflects that. Perplexity maintains curated lists of authoritative domains (Amazon, GitHub, major academic sites) that get inherent ranking boosts. It uses a time-decay algorithm that evaluates new content quickly, giving fresh publishers a real shot at citation. + +**Perplexity has unique content preferences:** +- **FAQ Schema (JSON-LD)** — Pages with FAQ structured data get cited noticeably more often +- **PDF documents** — Publicly accessible PDFs (whitepapers, research reports) are prioritized. If you have authoritative PDF content gated behind a form, consider making a version public. +- **Publishing velocity** — How frequently you publish matters more than keyword targeting +- **Self-contained paragraphs** — Perplexity prefers atomic, semantically complete paragraphs it can extract cleanly + +**What to focus on:** +- Allow PerplexityBot in robots.txt +- Implement FAQPage schema on any page with Q&A content +- Host PDF resources publicly (whitepapers, guides, reports) +- Add Article schema with publication and modification timestamps +- Write in clear, self-contained paragraphs that work as standalone answers +- Build deep topical authority in your specific niche + +--- + +## Microsoft Copilot + +Copilot is embedded across Microsoft's ecosystem — Edge, Windows, Microsoft 365, and Bing Search. It relies entirely on Bing's index, so if Bing hasn't indexed your content, Copilot can't cite it. + +**What makes Copilot different:** The Microsoft ecosystem connection creates unique optimization opportunities. Mentions and content on LinkedIn and GitHub provide ranking boosts that other platforms don't offer. Copilot also puts more weight on page speed — sub-2-second load times are a clear threshold. + +**What to focus on:** +- Submit your site to Bing Webmaster Tools (many sites only submit to Google Search Console) +- Use IndexNow protocol for faster indexing of new and updated content +- Optimize page speed to under 2 seconds +- Write clear entity definitions — when your content defines a term or concept, make the definition explicit and extractable +- Build presence on LinkedIn (publish articles, maintain company page) and GitHub if relevant +- Ensure Bingbot has full crawl access + +--- + +## Claude + +Claude uses Brave Search as its search backend when web search is enabled — not Google, not Bing. This is a completely different index, which means your Brave Search visibility directly determines whether Claude can find and cite you. + +**What makes Claude different:** Claude is extremely selective about what it cites. While it processes enormous amounts of content, its citation rate is very low — it's looking for the most factually accurate, well-sourced content on a given topic. Data-rich content with specific numbers and clear attribution performs significantly better than general-purpose content. + +**What to focus on:** +- Verify your content appears in Brave Search results (search for your brand and key terms at search.brave.com) +- Allow ClaudeBot and anthropic-ai user agents in robots.txt +- Maximize factual density — specific numbers, named sources, dated statistics +- Use clear, extractable structure with descriptive headings +- Cite authoritative sources within your content +- Aim to be the most factually accurate source on your topic — Claude rewards precision + +--- + +## Allowing AI Bots in robots.txt + +If your robots.txt blocks an AI bot, that platform can't cite your content. Here are the user agents to allow: + +``` +User-agent: GPTBot # OpenAI — powers ChatGPT search +User-agent: ChatGPT-User # ChatGPT browsing mode +User-agent: PerplexityBot # Perplexity AI search +User-agent: ClaudeBot # Anthropic Claude +User-agent: anthropic-ai # Anthropic Claude (alternate) +User-agent: Google-Extended # Google Gemini and AI Overviews +User-agent: Bingbot # Microsoft Copilot (via Bing) +Allow: / +``` + +**Training vs. search:** Some AI bots are used for both model training and search citation. If you want to be cited but don't want your content used for training, your options are limited — GPTBot handles both for OpenAI. However, you can safely block **CCBot** (Common Crawl) without affecting any AI search citations, since it's only used for training dataset collection. + +--- + +## Where to Start + +If you're optimizing for AI search for the first time, focus your effort where your audience actually is: + +**Start with Google AI Overviews** — They reach the most users (45%+ of Google searches) and you likely already have Google SEO foundations in place. Add schema markup, include cited sources in your content, and strengthen E-E-A-T signals. + +**Then address ChatGPT** — It's the most-used standalone AI search tool for tech and business audiences. Focus on freshness (update content monthly), domain authority, and matching your content structure to how ChatGPT formats its responses. + +**Then expand to Perplexity** — Especially valuable if your audience includes researchers, early adopters, or tech professionals. Add FAQ schema, publish PDF resources, and write in clear, self-contained paragraphs. + +**Copilot and Claude are lower priority** unless your audience skews enterprise/Microsoft (Copilot) or developer/analyst (Claude). But the fundamentals — structured content, cited sources, schema markup — help across all platforms. + +**Actions that help everywhere:** +1. Allow all AI bots in robots.txt +2. Implement schema markup (FAQPage, Article, Organization at minimum) +3. Include statistics with named sources in your content +4. Update content regularly — monthly for competitive topics +5. Use clear heading structure (H1 > H2 > H3) +6. Keep page load time under 2 seconds +7. Add author bios with credentials diff --git a/.agents/skills/analytics-tracking/SKILL.md b/.agents/skills/analytics-tracking/SKILL.md new file mode 100644 index 00000000..ae9769e4 --- /dev/null +++ b/.agents/skills/analytics-tracking/SKILL.md @@ -0,0 +1,309 @@ +--- +name: analytics-tracking +description: When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions "set up tracking," "GA4," "Google Analytics," "conversion tracking," "event tracking," "UTM parameters," "tag manager," "GTM," "analytics implementation," or "tracking plan." For A/B test measurement, see ab-test-setup. +metadata: + version: 1.1.0 +--- + +# Analytics Tracking + +You are an expert in analytics implementation and measurement. Your goal is to help set up tracking that provides actionable insights for marketing and product decisions. + +## Initial Assessment + +**Check for product marketing context first:** +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 tracking, understand: + +1. **Business Context** - What decisions will this data inform? What are key conversions? +2. **Current State** - What tracking exists? What tools are in use? +3. **Technical Context** - What's the tech stack? Any privacy/compliance requirements? + +--- + +## Core Principles + +### 1. Track for Decisions, Not Data +- Every event should inform a decision +- Avoid vanity metrics +- Quality > quantity of events + +### 2. Start with the Questions +- What do you need to know? +- What actions will you take based on this data? +- Work backwards to what you need to track + +### 3. Name Things Consistently +- Naming conventions matter +- Establish patterns before implementing +- Document everything + +### 4. Maintain Data Quality +- Validate implementation +- Monitor for issues +- Clean data > more data + +--- + +## Tracking Plan Framework + +### Structure + +``` +Event Name | Category | Properties | Trigger | Notes +---------- | -------- | ---------- | ------- | ----- +``` + +### Event Types + +| Type | Examples | +|------|----------| +| Pageviews | Automatic, enhanced with metadata | +| User Actions | Button clicks, form submissions, feature usage | +| System Events | Signup completed, purchase, subscription changed | +| Custom Conversions | Goal completions, funnel stages | + +**For comprehensive event lists**: See [references/event-library.md](references/event-library.md) + +--- + +## Event Naming Conventions + +### Recommended Format: Object-Action + +``` +signup_completed +button_clicked +form_submitted +article_read +checkout_payment_completed +``` + +### Best Practices +- Lowercase with underscores +- Be specific: `cta_hero_clicked` vs. `button_clicked` +- Include context in properties, not event name +- Avoid spaces and special characters +- Document decisions + +--- + +## Essential Events + +### Marketing Site + +| Event | Properties | +|-------|------------| +| cta_clicked | button_text, location | +| form_submitted | form_type | +| signup_completed | method, source | +| demo_requested | - | + +### Product/App + +| Event | Properties | +|-------|------------| +| onboarding_step_completed | step_number, step_name | +| feature_used | feature_name | +| purchase_completed | plan, value | +| subscription_cancelled | reason | + +**For full event library by business type**: See [references/event-library.md](references/event-library.md) + +--- + +## Event Properties + +### Standard Properties + +| Category | Properties | +|----------|------------| +| Page | page_title, page_location, page_referrer | +| User | user_id, user_type, account_id, plan_type | +| Campaign | source, medium, campaign, content, term | +| Product | product_id, product_name, category, price | + +### Best Practices +- Use consistent property names +- Include relevant context +- Don't duplicate automatic properties +- Avoid PII in properties + +--- + +## GA4 Implementation + +### Quick Setup + +1. Create GA4 property and data stream +2. Install gtag.js or GTM +3. Enable enhanced measurement +4. Configure custom events +5. Mark conversions in Admin + +### Custom Event Example + +```javascript +gtag('event', 'signup_completed', { + 'method': 'email', + 'plan': 'free' +}); +``` + +**For detailed GA4 implementation**: See [references/ga4-implementation.md](references/ga4-implementation.md) + +--- + +## Google Tag Manager + +### Container Structure + +| Component | Purpose | +|-----------|---------| +| Tags | Code that executes (GA4, pixels) | +| Triggers | When tags fire (page view, click) | +| Variables | Dynamic values (click text, data layer) | + +### Data Layer Pattern + +```javascript +dataLayer.push({ + 'event': 'form_submitted', + 'form_name': 'contact', + 'form_location': 'footer' +}); +``` + +**For detailed GTM implementation**: See [references/gtm-implementation.md](references/gtm-implementation.md) + +--- + +## UTM Parameter Strategy + +### Standard Parameters + +| Parameter | Purpose | Example | +|-----------|---------|---------| +| utm_source | Traffic source | google, newsletter | +| utm_medium | Marketing medium | cpc, email, social | +| utm_campaign | Campaign name | spring_sale | +| utm_content | Differentiate versions | hero_cta | +| utm_term | Paid search keywords | running+shoes | + +### Naming Conventions +- Lowercase everything +- Use underscores or hyphens consistently +- Be specific but concise: `blog_footer_cta`, not `cta1` +- Document all UTMs in a spreadsheet + +--- + +## Debugging and Validation + +### Testing Tools + +| Tool | Use For | +|------|---------| +| GA4 DebugView | Real-time event monitoring | +| GTM Preview Mode | Test triggers before publish | +| Browser Extensions | Tag Assistant, dataLayer Inspector | + +### Validation Checklist + +- [ ] Events firing on correct triggers +- [ ] Property values populating correctly +- [ ] No duplicate events +- [ ] Works across browsers and mobile +- [ ] Conversions recorded correctly +- [ ] No PII leaking + +### Common Issues + +| Issue | Check | +|-------|-------| +| Events not firing | Trigger config, GTM loaded | +| Wrong values | Variable path, data layer structure | +| Duplicate events | Multiple containers, trigger firing twice | + +--- + +## Privacy and Compliance + +### Considerations +- Cookie consent required in EU/UK/CA +- No PII in analytics properties +- Data retention settings +- User deletion capabilities + +### Implementation +- Use consent mode (wait for consent) +- IP anonymization +- Only collect what you need +- Integrate with consent management platform + +--- + +## Output Format + +### Tracking Plan Document + +```markdown +# [Site/Product] Tracking Plan + +## Overview +- Tools: GA4, GTM +- Last updated: [Date] + +## Events + +| Event Name | Description | Properties | Trigger | +|------------|-------------|------------|---------| +| signup_completed | User completes signup | method, plan | Success page | + +## Custom Dimensions + +| Name | Scope | Parameter | +|------|-------|-----------| +| user_type | User | user_type | + +## Conversions + +| Conversion | Event | Counting | +|------------|-------|----------| +| Signup | signup_completed | Once per session | +``` + +--- + +## Task-Specific Questions + +1. What tools are you using (GA4, Mixpanel, etc.)? +2. What key actions do you want to track? +3. What decisions will this data inform? +4. Who implements - dev team or marketing? +5. Are there privacy/consent requirements? +6. What's already tracked? + +--- + +## Tool Integrations + +For implementation, see the [tools registry](../../tools/REGISTRY.md). Key analytics tools: + +| Tool | Best For | MCP | Guide | +|------|----------|:---:|-------| +| **GA4** | Web analytics, Google ecosystem | ✓ | [ga4.md](../../tools/integrations/ga4.md) | +| **Mixpanel** | Product analytics, event tracking | - | [mixpanel.md](../../tools/integrations/mixpanel.md) | +| **Amplitude** | Product analytics, cohort analysis | - | [amplitude.md](../../tools/integrations/amplitude.md) | +| **PostHog** | Open-source analytics, session replay | - | [posthog.md](../../tools/integrations/posthog.md) | +| **Segment** | Customer data platform, routing | - | [segment.md](../../tools/integrations/segment.md) | + +--- + +## Related Skills + +- **ab-test-setup**: For experiment tracking +- **seo-audit**: For organic traffic analysis +- **page-cro**: For conversion optimization (uses this data) +- **revops**: For pipeline metrics, CRM tracking, and revenue attribution diff --git a/.agents/skills/analytics-tracking/references/event-library.md b/.agents/skills/analytics-tracking/references/event-library.md new file mode 100644 index 00000000..c381b56c --- /dev/null +++ b/.agents/skills/analytics-tracking/references/event-library.md @@ -0,0 +1,260 @@ +# Event Library Reference + +Comprehensive list of events to track by business type and context. + +## Contents +- Marketing Site Events (navigation & engagement, CTA & form interactions, conversion events) +- Product/App Events (onboarding, core usage, errors & support) +- Monetization Events (pricing & checkout, subscription management) +- E-commerce Events (browsing, cart, checkout, post-purchase) +- B2B / SaaS Specific Events (team & collaboration, integration events, account events) +- Event Properties (Parameters) +- Funnel Event Sequences + +## Marketing Site Events + +### Navigation & Engagement + +| Event Name | Description | Properties | +|------------|-------------|------------| +| page_view | Page loaded (enhanced) | page_title, page_location, content_group | +| scroll_depth | User scrolled to threshold | depth (25, 50, 75, 100) | +| outbound_link_clicked | Click to external site | link_url, link_text | +| internal_link_clicked | Click within site | link_url, link_text, location | +| video_played | Video started | video_id, video_title, duration | +| video_completed | Video finished | video_id, video_title, duration | + +### CTA & Form Interactions + +| Event Name | Description | Properties | +|------------|-------------|------------| +| cta_clicked | Call to action clicked | button_text, cta_location, page | +| form_started | User began form | form_name, form_location | +| form_field_completed | Field filled | form_name, field_name | +| form_submitted | Form successfully sent | form_name, form_location | +| form_error | Form validation failed | form_name, error_type | +| resource_downloaded | Asset downloaded | resource_name, resource_type | + +### Conversion Events + +| Event Name | Description | Properties | +|------------|-------------|------------| +| signup_started | Initiated signup | source, page | +| signup_completed | Finished signup | method, plan, source | +| demo_requested | Demo form submitted | company_size, industry | +| contact_submitted | Contact form sent | inquiry_type | +| newsletter_subscribed | Email list signup | source, list_name | +| trial_started | Free trial began | plan, source | + +--- + +## Product/App Events + +### Onboarding + +| Event Name | Description | Properties | +|------------|-------------|------------| +| signup_completed | Account created | method, referral_source | +| onboarding_started | Began onboarding | - | +| onboarding_step_completed | Step finished | step_number, step_name | +| onboarding_completed | All steps done | steps_completed, time_to_complete | +| onboarding_skipped | User skipped onboarding | step_skipped_at | +| first_key_action_completed | Aha moment reached | action_type | + +### Core Usage + +| Event Name | Description | Properties | +|------------|-------------|------------| +| session_started | App session began | session_number | +| feature_used | Feature interaction | feature_name, feature_category | +| action_completed | Core action done | action_type, count | +| content_created | User created content | content_type | +| content_edited | User modified content | content_type | +| content_deleted | User removed content | content_type | +| search_performed | In-app search | query, results_count | +| settings_changed | Settings modified | setting_name, new_value | +| invite_sent | User invited others | invite_type, count | + +### Errors & Support + +| Event Name | Description | Properties | +|------------|-------------|------------| +| error_occurred | Error experienced | error_type, error_message, page | +| help_opened | Help accessed | help_type, page | +| support_contacted | Support request made | contact_method, issue_type | +| feedback_submitted | User feedback given | feedback_type, rating | + +--- + +## Monetization Events + +### Pricing & Checkout + +| Event Name | Description | Properties | +|------------|-------------|------------| +| pricing_viewed | Pricing page seen | source | +| plan_selected | Plan chosen | plan_name, billing_cycle | +| checkout_started | Began checkout | plan, value | +| payment_info_entered | Payment submitted | payment_method | +| purchase_completed | Purchase successful | plan, value, currency, transaction_id | +| purchase_failed | Purchase failed | error_reason, plan | + +### Subscription Management + +| Event Name | Description | Properties | +|------------|-------------|------------| +| trial_started | Trial began | plan, trial_length | +| trial_ended | Trial expired | plan, converted (bool) | +| subscription_upgraded | Plan upgraded | from_plan, to_plan, value | +| subscription_downgraded | Plan downgraded | from_plan, to_plan | +| subscription_cancelled | Cancelled | plan, reason, tenure | +| subscription_renewed | Renewed | plan, value | +| billing_updated | Payment method changed | - | + +--- + +## E-commerce Events + +### Browsing + +| Event Name | Description | Properties | +|------------|-------------|------------| +| product_viewed | Product page viewed | product_id, product_name, category, price | +| product_list_viewed | Category/list viewed | list_name, products[] | +| product_searched | Search performed | query, results_count | +| product_filtered | Filters applied | filter_type, filter_value | +| product_sorted | Sort applied | sort_by, sort_order | + +### Cart + +| Event Name | Description | Properties | +|------------|-------------|------------| +| product_added_to_cart | Item added | product_id, product_name, price, quantity | +| product_removed_from_cart | Item removed | product_id, product_name, price, quantity | +| cart_viewed | Cart page viewed | cart_value, items_count | + +### Checkout + +| Event Name | Description | Properties | +|------------|-------------|------------| +| checkout_started | Checkout began | cart_value, items_count | +| checkout_step_completed | Step finished | step_number, step_name | +| shipping_info_entered | Address entered | shipping_method | +| payment_info_entered | Payment entered | payment_method | +| coupon_applied | Coupon used | coupon_code, discount_value | +| purchase_completed | Order placed | transaction_id, value, currency, items[] | + +### Post-Purchase + +| Event Name | Description | Properties | +|------------|-------------|------------| +| order_confirmed | Confirmation viewed | transaction_id | +| refund_requested | Refund initiated | transaction_id, reason | +| refund_completed | Refund processed | transaction_id, value | +| review_submitted | Product reviewed | product_id, rating | + +--- + +## B2B / SaaS Specific Events + +### Team & Collaboration + +| Event Name | Description | Properties | +|------------|-------------|------------| +| team_created | New team/org made | team_size, plan | +| team_member_invited | Invite sent | role, invite_method | +| team_member_joined | Member accepted | role | +| team_member_removed | Member removed | role | +| role_changed | Permissions updated | user_id, old_role, new_role | + +### Integration Events + +| Event Name | Description | Properties | +|------------|-------------|------------| +| integration_viewed | Integration page seen | integration_name | +| integration_started | Setup began | integration_name | +| integration_connected | Successfully connected | integration_name | +| integration_disconnected | Removed integration | integration_name, reason | + +### Account Events + +| Event Name | Description | Properties | +|------------|-------------|------------| +| account_created | New account | source, plan | +| account_upgraded | Plan upgrade | from_plan, to_plan | +| account_churned | Account closed | reason, tenure, mrr_lost | +| account_reactivated | Returned customer | previous_tenure, new_plan | + +--- + +## Event Properties (Parameters) + +### Standard Properties to Include + +**User Context:** +``` +user_id: "12345" +user_type: "free" | "trial" | "paid" +account_id: "acct_123" +plan_type: "starter" | "pro" | "enterprise" +``` + +**Session Context:** +``` +session_id: "sess_abc" +session_number: 5 +page: "/pricing" +referrer: "https://google.com" +``` + +**Campaign Context:** +``` +source: "google" +medium: "cpc" +campaign: "spring_sale" +content: "hero_cta" +``` + +**Product Context (E-commerce):** +``` +product_id: "SKU123" +product_name: "Product Name" +category: "Category" +price: 99.99 +quantity: 1 +currency: "USD" +``` + +**Timing:** +``` +timestamp: "2024-01-15T10:30:00Z" +time_on_page: 45 +session_duration: 300 +``` + +--- + +## Funnel Event Sequences + +### Signup Funnel +1. signup_started +2. signup_step_completed (email) +3. signup_step_completed (password) +4. signup_completed +5. onboarding_started + +### Purchase Funnel +1. pricing_viewed +2. plan_selected +3. checkout_started +4. payment_info_entered +5. purchase_completed + +### E-commerce Funnel +1. product_viewed +2. product_added_to_cart +3. cart_viewed +4. checkout_started +5. shipping_info_entered +6. payment_info_entered +7. purchase_completed diff --git a/.agents/skills/analytics-tracking/references/ga4-implementation.md b/.agents/skills/analytics-tracking/references/ga4-implementation.md new file mode 100644 index 00000000..f2656dcb --- /dev/null +++ b/.agents/skills/analytics-tracking/references/ga4-implementation.md @@ -0,0 +1,300 @@ +# GA4 Implementation Reference + +Detailed implementation guide for Google Analytics 4. + +## Contents +- Configuration (data streams, enhanced measurement events, recommended events) +- Custom Events (gtag.js implementation, Google Tag Manager) +- Conversions Setup (creating conversions, conversion values) +- Custom Dimensions and Metrics (when to use, setup steps, examples) +- Audiences (creating audiences, audience examples) +- Debugging (DebugView, real-time reports, common issues) +- Data Quality (filters, cross-domain tracking, session settings) +- Integration with Google Ads (linking, audience export) + +## Configuration + +### Data Streams + +- One stream per platform (web, iOS, Android) +- Enable enhanced measurement for automatic tracking +- Configure data retention (2 months default, 14 months max) +- Enable Google Signals (for cross-device, if consented) + +### Enhanced Measurement Events (Automatic) + +| Event | Description | Configuration | +|-------|-------------|---------------| +| page_view | Page loads | Automatic | +| scroll | 90% scroll depth | Toggle on/off | +| outbound_click | Click to external domain | Automatic | +| site_search | Search query used | Configure parameter | +| video_engagement | YouTube video plays | Toggle on/off | +| file_download | PDF, docs, etc. | Configurable extensions | + +### Recommended Events + +Use Google's predefined events when possible for enhanced reporting: + +**All properties:** +- login, sign_up +- share +- search + +**E-commerce:** +- view_item, view_item_list +- add_to_cart, remove_from_cart +- begin_checkout +- add_payment_info +- purchase, refund + +**Games:** +- level_up, unlock_achievement +- post_score, spend_virtual_currency + +Reference: https://support.google.com/analytics/answer/9267735 + +--- + +## Custom Events + +### gtag.js Implementation + +```javascript +// Basic event +gtag('event', 'signup_completed', { + 'method': 'email', + 'plan': 'free' +}); + +// Event with value +gtag('event', 'purchase', { + 'transaction_id': 'T12345', + 'value': 99.99, + 'currency': 'USD', + 'items': [{ + 'item_id': 'SKU123', + 'item_name': 'Product Name', + 'price': 99.99 + }] +}); + +// User properties +gtag('set', 'user_properties', { + 'user_type': 'premium', + 'plan_name': 'pro' +}); + +// User ID (for logged-in users) +gtag('config', 'GA_MEASUREMENT_ID', { + 'user_id': 'USER_ID' +}); +``` + +### Google Tag Manager (dataLayer) + +```javascript +// Custom event +dataLayer.push({ + 'event': 'signup_completed', + 'method': 'email', + 'plan': 'free' +}); + +// Set user properties +dataLayer.push({ + 'user_id': '12345', + 'user_type': 'premium' +}); + +// E-commerce purchase +dataLayer.push({ + 'event': 'purchase', + 'ecommerce': { + 'transaction_id': 'T12345', + 'value': 99.99, + 'currency': 'USD', + 'items': [{ + 'item_id': 'SKU123', + 'item_name': 'Product Name', + 'price': 99.99, + 'quantity': 1 + }] + } +}); + +// Clear ecommerce before sending (best practice) +dataLayer.push({ ecommerce: null }); +dataLayer.push({ + 'event': 'view_item', + 'ecommerce': { + // ... + } +}); +``` + +--- + +## Conversions Setup + +### Creating Conversions + +1. **Collect the event** - Ensure event is firing in GA4 +2. **Mark as conversion** - Admin > Events > Mark as conversion +3. **Set counting method**: + - Once per session (leads, signups) + - Every event (purchases) +4. **Import to Google Ads** - For conversion-optimized bidding + +### Conversion Values + +```javascript +// Event with conversion value +gtag('event', 'purchase', { + 'value': 99.99, + 'currency': 'USD' +}); +``` + +Or set default value in GA4 Admin when marking conversion. + +--- + +## Custom Dimensions and Metrics + +### When to Use + +**Custom dimensions:** +- Properties you want to segment/filter by +- User attributes (plan type, industry) +- Content attributes (author, category) + +**Custom metrics:** +- Numeric values to aggregate +- Scores, counts, durations + +### Setup Steps + +1. Admin > Data display > Custom definitions +2. Create dimension or metric +3. Choose scope: + - **Event**: Per event (content_type) + - **User**: Per user (account_type) + - **Item**: Per product (product_category) +4. Enter parameter name (must match event parameter) + +### Examples + +| Dimension | Scope | Parameter | Description | +|-----------|-------|-----------|-------------| +| User Type | User | user_type | Free, trial, paid | +| Content Author | Event | author | Blog post author | +| Product Category | Item | item_category | E-commerce category | + +--- + +## Audiences + +### Creating Audiences + +Admin > Data display > Audiences + +**Use cases:** +- Remarketing audiences (export to Ads) +- Segment analysis +- Trigger-based events + +### Audience Examples + +**High-intent visitors:** +- Viewed pricing page +- Did not convert +- In last 7 days + +**Engaged users:** +- 3+ sessions +- Or 5+ minutes total engagement + +**Purchasers:** +- Purchase event +- For exclusion or lookalike + +--- + +## Debugging + +### DebugView + +Enable with: +- URL parameter: `?debug_mode=true` +- Chrome extension: GA Debugger +- gtag: `'debug_mode': true` in config + +View at: Reports > Configure > DebugView + +### Real-Time Reports + +Check events within 30 minutes: +Reports > Real-time + +### Common Issues + +**Events not appearing:** +- Check DebugView first +- Verify gtag/GTM firing +- Check filter exclusions + +**Parameter values missing:** +- Custom dimension not created +- Parameter name mismatch +- Data still processing (24-48 hrs) + +**Conversions not recording:** +- Event not marked as conversion +- Event name doesn't match +- Counting method (once vs. every) + +--- + +## Data Quality + +### Filters + +Admin > Data streams > [Stream] > Configure tag settings > Define internal traffic + +**Exclude:** +- Internal IP addresses +- Developer traffic +- Testing environments + +### Cross-Domain Tracking + +For multiple domains sharing analytics: + +1. Admin > Data streams > [Stream] > Configure tag settings +2. Configure your domains +3. List all domains that should share sessions + +### Session Settings + +Admin > Data streams > [Stream] > Configure tag settings + +- Session timeout (default 30 min) +- Engaged session duration (10 sec default) + +--- + +## Integration with Google Ads + +### Linking + +1. Admin > Product links > Google Ads links +2. Enable auto-tagging in Google Ads +3. Import conversions in Google Ads + +### Audience Export + +Audiences created in GA4 can be used in Google Ads for: +- Remarketing campaigns +- Customer match +- Similar audiences diff --git a/.agents/skills/analytics-tracking/references/gtm-implementation.md b/.agents/skills/analytics-tracking/references/gtm-implementation.md new file mode 100644 index 00000000..956e6384 --- /dev/null +++ b/.agents/skills/analytics-tracking/references/gtm-implementation.md @@ -0,0 +1,390 @@ +# Google Tag Manager Implementation Reference + +Detailed guide for implementing tracking via Google Tag Manager. + +## Contents +- Container Structure (tags, triggers, variables) +- Naming Conventions +- Data Layer Patterns +- Common Tag Configurations (GA4 configuration tag, GA4 event tag, Facebook pixel) +- Preview and Debug +- Workspaces and Versioning +- Consent Management +- Advanced Patterns (tag sequencing, exception handling, custom JavaScript variables) + +## Container Structure + +### Tags + +Tags are code snippets that execute when triggered. + +**Common tag types:** +- GA4 Configuration (base setup) +- GA4 Event (custom events) +- Google Ads Conversion +- Facebook Pixel +- LinkedIn Insight Tag +- Custom HTML (for other pixels) + +### Triggers + +Triggers define when tags fire. + +**Built-in triggers:** +- Page View: All Pages, DOM Ready, Window Loaded +- Click: All Elements, Just Links +- Form Submission +- Scroll Depth +- Timer +- Element Visibility + +**Custom triggers:** +- Custom Event (from dataLayer) +- Trigger Groups (multiple conditions) + +### Variables + +Variables capture dynamic values. + +**Built-in (enable as needed):** +- Click Text, Click URL, Click ID, Click Classes +- Page Path, Page URL, Page Hostname +- Referrer +- Form Element, Form ID + +**User-defined:** +- Data Layer variables +- JavaScript variables +- Lookup tables +- RegEx tables +- Constants + +--- + +## Naming Conventions + +### Recommended Format + +``` +[Type] - [Description] - [Detail] + +Tags: +GA4 - Event - Signup Completed +GA4 - Config - Base Configuration +FB - Pixel - Page View +HTML - LiveChat Widget + +Triggers: +Click - CTA Button +Submit - Contact Form +View - Pricing Page +Custom - signup_completed + +Variables: +DL - user_id +JS - Current Timestamp +LT - Campaign Source Map +``` + +--- + +## Data Layer Patterns + +### Basic Structure + +```javascript +// Initialize (in before GTM) +window.dataLayer = window.dataLayer || []; + +// Push event +dataLayer.push({ + 'event': 'event_name', + 'property1': 'value1', + 'property2': 'value2' +}); +``` + +### Page Load Data + +```javascript +// Set on page load (before GTM container) +window.dataLayer = window.dataLayer || []; +dataLayer.push({ + 'pageType': 'product', + 'contentGroup': 'products', + 'user': { + 'loggedIn': true, + 'userId': '12345', + 'userType': 'premium' + } +}); +``` + +### Form Submission + +```javascript +document.querySelector('#contact-form').addEventListener('submit', function() { + dataLayer.push({ + 'event': 'form_submitted', + 'formName': 'contact', + 'formLocation': 'footer' + }); +}); +``` + +### Button Click + +```javascript +document.querySelector('.cta-button').addEventListener('click', function() { + dataLayer.push({ + 'event': 'cta_clicked', + 'ctaText': this.innerText, + 'ctaLocation': 'hero' + }); +}); +``` + +### E-commerce Events + +```javascript +// Product view +dataLayer.push({ ecommerce: null }); // Clear previous +dataLayer.push({ + 'event': 'view_item', + 'ecommerce': { + 'items': [{ + 'item_id': 'SKU123', + 'item_name': 'Product Name', + 'price': 99.99, + 'item_category': 'Category', + 'quantity': 1 + }] + } +}); + +// Add to cart +dataLayer.push({ ecommerce: null }); +dataLayer.push({ + 'event': 'add_to_cart', + 'ecommerce': { + 'items': [{ + 'item_id': 'SKU123', + 'item_name': 'Product Name', + 'price': 99.99, + 'quantity': 1 + }] + } +}); + +// Purchase +dataLayer.push({ ecommerce: null }); +dataLayer.push({ + 'event': 'purchase', + 'ecommerce': { + 'transaction_id': 'T12345', + 'value': 99.99, + 'currency': 'USD', + 'tax': 5.00, + 'shipping': 10.00, + 'items': [{ + 'item_id': 'SKU123', + 'item_name': 'Product Name', + 'price': 99.99, + 'quantity': 1 + }] + } +}); +``` + +--- + +## Common Tag Configurations + +### GA4 Configuration Tag + +**Tag Type:** Google Analytics: GA4 Configuration + +**Settings:** +- Measurement ID: G-XXXXXXXX +- Send page view: Checked (for pageviews) +- User Properties: Add any user-level dimensions + +**Trigger:** All Pages + +### GA4 Event Tag + +**Tag Type:** Google Analytics: GA4 Event + +**Settings:** +- Configuration Tag: Select your config tag +- Event Name: {{DL - event_name}} or hardcode +- Event Parameters: Add parameters from dataLayer + +**Trigger:** Custom Event with event name match + +### Facebook Pixel - Base + +**Tag Type:** Custom HTML + +```html + +``` + +**Trigger:** All Pages + +### Facebook Pixel - Event + +**Tag Type:** Custom HTML + +```html + +``` + +**Trigger:** Custom Event - form_submitted + +--- + +## Preview and Debug + +### Preview Mode + +1. Click "Preview" in GTM +2. Enter site URL +3. GTM debug panel opens at bottom + +**What to check:** +- Tags fired on this event +- Tags not fired (and why) +- Variables and their values +- Data layer contents + +### Debug Tips + +**Tag not firing:** +- Check trigger conditions +- Verify data layer push +- Check tag sequencing + +**Wrong variable value:** +- Check data layer structure +- Verify variable path (nested objects) +- Check timing (data may not exist yet) + +**Multiple firings:** +- Check trigger uniqueness +- Look for duplicate tags +- Check tag firing options + +--- + +## Workspaces and Versioning + +### Workspaces + +Use workspaces for team collaboration: +- Default workspace for production +- Separate workspaces for large changes +- Merge when ready + +### Version Management + +**Best practices:** +- Name every version descriptively +- Add notes explaining changes +- Review changes before publish +- Keep production version noted + +**Version notes example:** +``` +v15: Added purchase conversion tracking +- New tag: GA4 - Event - Purchase +- New trigger: Custom Event - purchase +- New variables: DL - transaction_id, DL - value +- Tested: Chrome, Safari, Mobile +``` + +--- + +## Consent Management + +### Consent Mode Integration + +```javascript +// Default state (before consent) +gtag('consent', 'default', { + 'analytics_storage': 'denied', + 'ad_storage': 'denied' +}); + +// Update on consent +function grantConsent() { + gtag('consent', 'update', { + 'analytics_storage': 'granted', + 'ad_storage': 'granted' + }); +} +``` + +### GTM Consent Overview + +1. Enable Consent Overview in Admin +2. Configure consent for each tag +3. Tags respect consent state automatically + +--- + +## Advanced Patterns + +### Tag Sequencing + +**Setup tags to fire in order:** +Tag Configuration > Advanced Settings > Tag Sequencing + +**Use cases:** +- Config tag before event tags +- Pixel initialization before tracking +- Cleanup after conversion + +### Exception Handling + +**Trigger exceptions** - Prevent tag from firing: +- Exclude certain pages +- Exclude internal traffic +- Exclude during testing + +### Custom JavaScript Variables + +```javascript +// Get URL parameter +function() { + var params = new URLSearchParams(window.location.search); + return params.get('campaign') || '(not set)'; +} + +// Get cookie value +function() { + var match = document.cookie.match('(^|;) ?user_id=([^;]*)(;|$)'); + return match ? match[2] : null; +} + +// Get data from page +function() { + var el = document.querySelector('.product-price'); + return el ? parseFloat(el.textContent.replace('$', '')) : 0; +} +``` diff --git a/.agents/skills/cold-email/SKILL.md b/.agents/skills/cold-email/SKILL.md new file mode 100644 index 00000000..eddc6d3c --- /dev/null +++ b/.agents/skills/cold-email/SKILL.md @@ -0,0 +1,158 @@ +--- +name: cold-email +description: Write B2B cold emails and follow-up sequences that get replies. Use when the user wants to write cold outreach emails, prospecting emails, cold email campaigns, sales development emails, or SDR emails. Covers subject lines, opening lines, body copy, CTAs, personalization, and multi-touch follow-up sequences. +metadata: + version: 1.1.0 +--- + +# Cold Email Writing + +You are an expert cold email writer. Your goal is to write emails that sound like they came from a sharp, thoughtful human — not a sales machine following a template. + +## Before Writing + +**Check for product marketing context first:** +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. **Who are you writing to?** — Role, company, why them specifically +2. **What do you want?** — The outcome (meeting, reply, intro, demo) +3. **What's the value?** — The specific problem you solve for people like them +4. **What's your proof?** — A result, case study, or credibility signal +5. **Any research signals?** — Funding, hiring, LinkedIn posts, company news, tech stack changes + +Work with whatever the user gives you. If they have a strong signal and a clear value prop, that's enough to write. Don't block on missing inputs — use what you have and note what would make it stronger. + +--- + +## Writing Principles + +### Write like a peer, not a vendor + +The email should read like it came from someone who understands their world — not someone trying to sell them something. Use contractions. Read it aloud. If it sounds like marketing copy, rewrite it. + +### Every sentence must earn its place + +Cold email is ruthlessly short. If a sentence doesn't move the reader toward replying, cut it. The best cold emails feel like they could have been shorter, not longer. + +### Personalization must connect to the problem + +If you remove the personalized opening and the email still makes sense, the personalization isn't working. The observation should naturally lead into why you're reaching out. + +See [personalization.md](references/personalization.md) for the 4-level system and research signals. + +### Lead with their world, not yours + +The reader should see their own situation reflected back. "You/your" should dominate over "I/we." Don't open with who you are or what your company does. + +### One ask, low friction + +Interest-based CTAs ("Worth exploring?" / "Would this be useful?") beat meeting requests. One CTA per email. Make it easy to say yes with a one-line reply. + +--- + +## Voice & Tone + +**The target voice:** A smart colleague who noticed something relevant and is sharing it. Conversational but not sloppy. Confident but not pushy. + +**Calibrate to the audience:** + +- C-suite: ultra-brief, peer-level, understated +- Mid-level: more specific value, slightly more detail +- Technical: precise, no fluff, respect their intelligence + +**What it should NOT sound like:** + +- A template with fields swapped in +- A pitch deck compressed into paragraph form +- A LinkedIn DM from someone you've never met +- An AI-generated email (avoid the telltale patterns: "I hope this email finds you well," "I came across your profile," "leverage," "synergy," "best-in-class") + +--- + +## Structure + +There's no single right structure. Choose a framework that fits the situation, or write freeform if the email flows naturally without one. + +**Common shapes that work:** + +- **Observation → Problem → Proof → Ask** — You noticed X, which usually means Y challenge. We helped Z with that. Interested? +- **Question → Value → Ask** — Struggling with X? We do Y. Company Z saw [result]. Worth a look? +- **Trigger → Insight → Ask** — Congrats on X. That usually creates Y challenge. We've helped similar companies with that. Curious? +- **Story → Bridge → Ask** — [Similar company] had [problem]. They [solved it this way]. Relevant to you? + +For the full catalog of frameworks with examples, see [frameworks.md](references/frameworks.md). + +--- + +## Subject Lines + +Short, boring, internal-looking. The subject line's only job is to get the email opened — not to sell. + +- 2-4 words, lowercase, no punctuation tricks +- Should look like it came from a colleague ("reply rates," "hiring ops," "Q2 forecast") +- No product pitches, no urgency, no emojis, no prospect's first name + +See [subject-lines.md](references/subject-lines.md) for the full data. + +--- + +## Follow-Up Sequences + +Each follow-up must add something new — a different angle, fresh proof, a useful resource. Never "just checking in." + +- 3-5 total emails, increasing gaps between them +- Each email should stand alone (they may not have read the previous ones) +- The breakup email is your last touch — honor it + +See [follow-up-sequences.md](references/follow-up-sequences.md) for cadence, angle rotation, and breakup email templates. + +--- + +## Quality Check + +Before presenting, gut-check: + +- Does it sound like a human wrote it? (Read it aloud) +- Would YOU reply to this if you received it? +- Does every sentence serve the reader, not the sender? +- Is the personalization connected to the problem? +- Is there one clear, low-friction ask? + +--- + +## What to Avoid + +- Opening with "I hope this email finds you well" or "My name is X and I work at Y" +- Jargon: "synergy," "leverage," "circle back," "best-in-class," "leading provider" +- Feature dumps — one proof point beats ten features +- HTML, images, or multiple links +- Fake "Re:" or "Fwd:" subject lines +- Identical templates with only {{FirstName}} swapped +- Asking for 30-minute calls in first touch +- "Just checking in" follow-ups + +--- + +## Data & Benchmarks + +The references contain performance data if you need to make informed choices: + +- [benchmarks.md](references/benchmarks.md) — Reply rates, conversion funnels, expert methods, common mistakes +- [personalization.md](references/personalization.md) — 4-level personalization system, research signals +- [subject-lines.md](references/subject-lines.md) — Subject line data and optimization +- [follow-up-sequences.md](references/follow-up-sequences.md) — Cadence, angles, breakup emails +- [frameworks.md](references/frameworks.md) — All copywriting frameworks with examples + +Use this data to inform your writing — not as a checklist to satisfy. + +--- + +## Related Skills + +- **copywriting**: For landing pages and web copy +- **email-sequence**: For lifecycle/nurture email sequences (not cold outreach) +- **social-content**: For LinkedIn and social posts +- **product-marketing-context**: For establishing foundational positioning +- **revops**: For lead scoring, routing, and pipeline management diff --git a/.agents/skills/cold-email/references/benchmarks.md b/.agents/skills/cold-email/references/benchmarks.md new file mode 100644 index 00000000..bc6e44d8 --- /dev/null +++ b/.agents/skills/cold-email/references/benchmarks.md @@ -0,0 +1,83 @@ +# Benchmarks, Data & Expert Methods + +## Core Performance Metrics (2024–2025) + +| Metric | Average | Good | Excellent | Source | +| -------------------------- | ------- | ------ | --------- | ------------------------ | +| Open rate | 27.7% | 40–45% | 50%+ | Belkins, Snov.io | +| Reply rate | 4–5.8% | 5–10% | 10–15% | Belkins, Reachoutly | +| Reply rate (best-in-class) | — | — | 15–25%+ | Digital Bloom, Instantly | +| Positive reply % | ~48% | 55–60% | 62–65% | Digital Bloom | +| Meeting booking rate | 0.5–1% | 1–2% | 2.3%+ | Reachoutly | +| Bounce rate | 7.5% | <4% | <2% | Belkins | + +## Realistic Funnel Model + +500 emails → 100 opens (20%) → 25 replies (5%) → 8 positive replies (30%) → 4 meetings (50%) → 1 client (25% close). ~**0.2% end-to-end conversion** for average performers. + +## Performance Levers (ranked by impact) + +1. **Hook type** — Timeline hooks outperform problem hooks by 3.4x in meetings +2. **Personalization depth** — Up to 250% more replies +3. **Brevity** — 25–75 words optimal, 83% more replies under 75 words +4. **Targeting precision** — ≤50 contacts per campaign = 2.76x higher reply rates +5. **Follow-up strategy** — First follow-up adds 49% more replies +6. **Reading level** — 3rd–5th grade = 67% more replies +7. **Send timing** — Thursday peaks at 6.87% reply rate + +## Declining Effectiveness Trend + +Reply rates dropped from 7–8% (2020–2022) to 4–5.8% (2024–2025), ~15% YoY decline. Drivers: inbox saturation (10+ cold emails/week, 20% say none relevant), stricter anti-spam (Google's threshold: 0.1% complaints), AI email flood (more volume, less quality signal). Writing craft matters more, not less — gap between average and excellent is widening. + +## Response Rates by Seniority + +- **Entry-level:** Highest engagement at 8% reply, 50% open +- **C-level:** 23% more likely to respond than non-C-suite when they engage (6.4% vs 5.2%) +- **CTOs/VP Tech:** 7.68% reply +- **CEOs/Founders:** 7.63% reply +- **Heads of Sales:** 6.60% (most targeted role, highest saturation) + +## Industry Variation + +**Highest responding:** Nonprofits (16.5%+), legal (10%), EdTech (7.8%), chemical (7.3%), manufacturing (6.1%). +**Lowest responding:** SaaS (3.5%), financial services (3.4%), IT services (3.5%). + +## Top 15 Mistakes (ranked by impact) + +1. **Too long** — 70% of emails above 10th-grade level. Under 75 words = 83% more replies +2. **Too self-focused** — "We are a leading..." signals sales pitch. Count I/We sentences +3. **No clear value prop** — 71% of decision-makers ignore irrelevant emails +4. **Generic templates** — {{FirstName}} isn't personalization. Recipients detect instantly +5. **Feature dumping** — "Great reps lead with problems" (Lavender). One proof point beats ten features +6. **False personalization** — "Loved your post!" without specifics is transparent +7. **Asking too much too soon** — 30-min call in first email = "proposing on first date" +8. **Pushy language** — "Act Now" stacking increases spam flagging by 67% +9. **No CTA** — Without a clear next step, momentum dies +10. **"Just checking in" follow-ups** — "I never heard back" = 12% drop in bookings +11. **Wrong tone for audience** — Founder ≠ RevOps lead ≠ sales leader +12. **Jargon/buzzwords** — "Leverage synergistic platform" → "We help you book more meetings" +13. **Unsubstantiated claims** — "300% more leads" without proof triggers skepticism +14. **Too many contacts per company** — 1–2 people = 7.8% reply; 10+ = 3.8% +15. **Fake urgency** — Fake "Re:" / "Fwd:" / countdown timers destroy trust + +## Cultural Calibration + +| Factor | US | UK | Germany/DACH | Scandinavia | +| ------------ | --------------- | ------------------------ | -------------------- | ----------------------- | +| Tone | Direct, casual | Polite, professional | Precise, data-driven | Fact-based, egalitarian | +| Length | Shorter, blunt | Longer, insight-led | Detail-oriented | Concise but substantive | +| Social proof | Outcome numbers | Research-led credibility | Technical precision | Shared values | + +North America: 4.1% response. Europe: 3.1%. Asia-Pacific: 2.8%. Shorter, more direct sequences work better in US. UK needs more insight/personality. GDPR affects European tone. + +## Expert Quick Reference + +| Expert | Core Method | Best For | +| -------------- | --------------------------------------------------------------- | ----------------------------------------------- | +| Alex Berman | 3C's: Compliment → Case Study → CTA | High-ticket B2B services, agencies | +| Josh Braun | "Poke the Bear" — neutral questions exposing invisible problems | Empathy-driven consultative selling | +| Kyle Coleman | Systematic research + AI personalization at scale | Bridging mass outreach and deep personalization | +| Becc Holland | Psychographic personalization, Premise Buckets | Combining personalization with relevance | +| Will Allred | Data-driven coaching, Mouse Trap, Vanilla Ice Cream | Any context; universal frameworks | +| Justin Michael | 1–3 sentence hyper-brevity, quote their own words | High-velocity SDR teams at scale | +| Sam Nelson | Agoge Sequence — Triple on Day 1 (email + LinkedIn + call) | Multi-channel, tiered personalization | diff --git a/.agents/skills/cold-email/references/follow-up-sequences.md b/.agents/skills/cold-email/references/follow-up-sequences.md new file mode 100644 index 00000000..f32d6d79 --- /dev/null +++ b/.agents/skills/cold-email/references/follow-up-sequences.md @@ -0,0 +1,81 @@ +# Follow-Up Sequences + +55% of replies come from follow-ups, not the initial email. Yet 48% of salespeople never follow up even once. + +## How Many: 3–5 Total Emails + +- Highest single-email reply rate: **8.4%** (Belkins). +- 4–7 email campaigns achieve **27% reply rates** vs 9% for 1–3 emails (Woodpecker, 20M emails). +- By 4th follow-up, response rates drop **55%** and spam complaints **triple**. +- Resolution: longer sequences catch different timing windows. Cap at 4 follow-ups (5 total emails). Each must add genuinely new value. + +## Optimal Cadence + +Increase the gap between each touch: + +| Touch | Day | Notes | +| ------------- | ----- | ---------------------------------------------- | +| Initial email | 0 | Maximum personalization investment | +| Follow-up 1 | 3 | Waiting 3 days increases response by up to 31% | +| Follow-up 2 | 7–8 | Different angle | +| Follow-up 3 | 14 | New value piece | +| Follow-up 4 | 21–28 | Breakup email | + +**Best days:** Tuesday–Thursday (Thursday peaks at 6.87% reply rate). +**Best times:** 9–11 AM or 1–3 PM in prospect's local time. +**Avoid:** Monday mornings (inbox overload), Friday afternoons (checked out). + +## Angle Rotation + +Each follow-up must stand alone while building toward the goal. Never just "bump this up." + +| Email | Angle | Purpose | +| ----------- | ---------------------------------------------------------- | -------------------------- | +| Initial | Personalized hook + core value prop + soft CTA | Introduce problem/solution | +| Follow-up 1 | Different angle, new value piece (stat, insight, resource) | Show additional benefit | +| Follow-up 2 | Social proof / case study from similar company | Build credibility | +| Follow-up 3 | New insight, industry trend, or relevant resource | Demonstrate expertise | +| Follow-up 4 | Breakup — acknowledge silence, leave door open | Trigger loss aversion | + +Add only **one new value proposition per email** (SalesBread). This naturally forces different angles. + +## The Breakup Email + +Leverages loss aversion — removing pressure while creating scarcity through withdrawal. Close.com reports **10–15% response rates** from breakup emails with cold prospects. + +**Structure:** + +1. Acknowledge you've reached out multiple times +2. Validate their potential lack of interest +3. State this is your final email for now +4. Leave the door open + +**Example:** + +> I haven't heard back, so I'll assume now isn't the right time. Before I close the loop: [1-sentence insight or resource]. If that changes things, feel free to reply. Otherwise, no hard feelings — good luck with [their goal]. + +**1-2-3 Format** (reduces friction to near zero): + +> Since I haven't heard back, I'll keep it simple. Reply with a number: +> +> 1 — Interested, let's talk +> 2 — Not now, check back in 3 months +> 3 — Not interested, please stop + +**Critical rule:** If you send a breakup email, honor it. Do not contact the prospect again. + +## Phrases That Kill Response Rates + +- "I never heard back" → **12% drop** in meeting booking rate (Gong) +- "Just checking in" → Zero value, signals laziness +- "Bumping this to the top of your inbox" → Presumptuous +- "Did you see my last email?" → Guilt-tripping +- "Following up on my previous message" → Generic, adds nothing + +## CTA Adjustment by Seniority + +**Executives/founders:** Ultra-low-effort, curiosity-driven. "Curious?" or "Worth 2 min?" + +**Mid-level managers:** More specific value. "Want me to walk through how [Company] saved 15 hours/week?" + +Higher in the org chart = less friction you can ask for. diff --git a/.agents/skills/cold-email/references/frameworks.md b/.agents/skills/cold-email/references/frameworks.md new file mode 100644 index 00000000..871e0f33 --- /dev/null +++ b/.agents/skills/cold-email/references/frameworks.md @@ -0,0 +1,90 @@ +# Cold Email Copywriting Frameworks + +Frameworks beat templates — they teach thinking patterns, not copy-paste shortcuts. + +## PAS — Problem, Agitate, Solution (default) + +**Structure:** Identify pain → Amplify consequences → Present solution + soft CTA. +**Best for:** Problem-aware but not solution-aware prospects. The workhorse framework. + +> Most VP Sales at companies your size spend 5+ hours/week on manual CRM reporting. That's 250+ hours/year not spent coaching reps — and often means inaccurate forecasts reaching leadership. We built a tool that auto-generates CRM reports in real time. Teams like Datadog reduced reporting time by 80%. Would it make sense to see how? + +## BAB — Before, After, Bridge + +**Structure:** Current painful situation → Ideal future → Your product as the bridge. +**Best for:** Transformation-driven offers with clear before/after. Emotional decision-makers. + +> Right now, your team is likely spending hours manually sourcing leads — feast or famine each quarter. Imagine qualified leads arriving daily on autopilot, reps spending 100% of their time selling. That's what our platform does. Companies like HubSpot saw a 40% pipeline increase within 90 days. Can I show you how? + +## QVC — Question, Value, CTA + +**Structure:** Targeted pain question → Brief value → Direct next step. +**Best for:** C-suite prospects who prefer brevity. Qualify interest immediately. + +> Are your SDRs spending more time researching than selling? We help sales teams automate prospect research so reps focus on conversations. Clients see 3x more meetings per rep per week. Worth a 10-minute demo? + +## AIDA — Attention, Interest, Desire, Action + +**Structure:** Hook/stat → Address specific challenge → Social proof/outcome → Clear CTA. +**Best for:** Data-driven prospects, high-ticket pitches with strong stats. + +> Companies in pharma lose 30% of leads due to manual outreach. Given {{Company}}'s growth this quarter, pipeline velocity is likely top of mind. Customers like Pfizer use our platform to automate lead qualification — cutting time-to-contact by 60%. Worth a 15-minute call? + +## PPP — Praise, Picture, Push + +**Structure:** Genuine compliment → How things could be better → Gentle push to action. +**Best for:** Senior prospects who respond to relationship-building. Requires genuine trigger. + +> Your keynote on scaling SDR teams was spot-on — especially on ramp time as the hidden cost. What if you could cut that in half? Our in-inbox coach helps new reps write effective emails from day one with real-time scoring. Open to a quick chat about how this could support your growth? + +## Star-Story-Solution + +**Structure:** Introduce character (customer) → Tell challenge narrative → Reveal results. +**Best for:** Strong customer success stories. Humanizes the pitch. + +> Last year, Sarah — VP Sales at a Series B startup — had 5 SDRs competing against a rival with 20. Her team was getting crushed on volume. They adopted our AI prospecting tool and sent hyper-personalized emails at 3x pace without losing quality. Within 90 days, they booked more meetings than their competitor's entire team. Happy to share how this could work for {{Company}}. + +## SCQ — Situation, Complication, Question + +**Structure:** Current reality → Complicating challenge → Question that speaks to need → Optional answer. +**Best for:** Consultative selling. Mirrors how professionals present to leadership. + +> Your team doubled this year. That usually means onboarding is eating into selling time. How are you handling ramp for new hires? + +## ACCA — Awareness, Comprehension, Conviction, Action + +**Structure:** Contrarian hook → Explain benefit simply → Provide proof → Strong CTA. +**Best for:** Analytical buyers who need evidence (engineers, CFOs, ops leaders). + +> Most sales teams measure rep activity. The top 5% measure rep efficiency instead. When Acme switched, they booked 40% more meetings with fewer emails. Worth seeing how? + +## 3C's (Alex Berman) + +**Structure:** Compliment → Case Study → CTA. +**Best for:** Agency/services cold outreach. Case study does the heavy lifting. + +> Big fan of [Company]. We just built an app for [Competitor] that does XYZ. I have a few more ideas. Interested? + +## Mouse Trap (Lavender/Will Allred) + +**Structure:** Observation + Binary value-prop question. 1–2 sentences total. +**Best for:** Maximum brevity. Impulsive reply based on curiosity. + +> Looks like you're hiring reps. Would it be helpful to get a more granular look at how they're ramping on email? + +## Justin Michael Method + +**Structure:** Trigger/Pain → Solution hint → Binary CTA. 1–3 sentences, no intro. +**Best for:** High-velocity SDR teams. Mobile-optimized. Deliberately polarizing. + +Spend max 1 minute on personalization. Use industry/persona-level signals. For top-tier prospects, quote their own words from interviews — they almost always respond. + +## Vanilla Ice Cream (Lavender) + +**Structure:** Observation → Problem/Insight → Credibility → Solution → Call-to-Conversation. +**Best for:** Universal "base" framework that works everywhere. Five parts. + +## PASTOR (Ray Edwards) + +**Structure:** Problem → Amplify → Story → Testimony → Offer → Response. +**Best for:** Longer-form or multi-email sequences. Consulting, education, complex B2B services. Each element can be developed across separate touches. diff --git a/.agents/skills/cold-email/references/personalization.md b/.agents/skills/cold-email/references/personalization.md new file mode 100644 index 00000000..c3f98d35 --- /dev/null +++ b/.agents/skills/cold-email/references/personalization.md @@ -0,0 +1,79 @@ +# Personalization at Scale + +Personalization drives **50–250% more replies** (Lavender). The key insight: **if your personalization has nothing to do with the problem you solve, it's just an attention hack** (Clay). + +## Four Levels of Personalization + +### Level 1 — Basic (merge tags) + +First name, company name, job title. Table stakes, no longer differentiating. ~5% lift. + +### Level 2 — Industry/segment + +Industry-specific pain points, trends, regulatory challenges. Scalable via micro-segmentation. + +> Most {{industry}} teams struggle with {{lead gen problem}}, which often leads to wasted effort. + +### Level 3 — Role-level + +Challenges specific to their role and seniority. + +> As Head of Sales, keeping pipeline steady is probably your biggest headache. Your RevOps team is small, so you're likely wearing multiple hats during scaling. + +### Level 4 — Individual (gold standard) + +Specific, timely observations about that person connected to the problem you solve. + +> Noticed you're hiring 3 SDRs — sounds like you're scaling outbound fast. Most teams hit follow-up fatigue during onboarding. + +## Research Signal Stack + +| Signal | Where to find it | How to use it | +| ----------------- | ---------------------------------- | ---------------------------------------------------------------------------- | +| Recent funding | Crunchbase, LinkedIn, press | "Congrats on Series B — scaling teams fast usually creates X challenge" | +| Job postings | LinkedIn Jobs, careers page | "Noticed you're hiring 3 SDRs — sounds like you're scaling outbound" | +| Tech stack | BuiltWith, Wappalyzer, HG Insights | "I see you're using HubSpot — most teams at your stage hit a ceiling with X" | +| LinkedIn activity | Posts, comments, job changes | "Really enjoyed your post about X" | +| Company news | Google News, press releases | "Congrats on acquiring X — integrating teams usually creates Y challenge" | +| Podcast/talks | Google, YouTube, podcasts | "Caught your talk at SaaStr on X — really insightful" | +| Website changes | Manual review | "Your new pricing page caught my eye — curious how it's converting" | + +## The 3-Minute Personalization System + +From "30 Minutes to President's Club": + +**Step 1:** Build a research stack of top 10 buying signals — 5 company triggers, 5 person triggers. Stack-rank by relevance. + +**Step 2:** Build a 3x3 template: (1) personalization attached to a problem, (2) problem you solve, (3) one-sentence solution + low-friction CTA. + +**Step 3:** Create 5 "trigger templates" — pre-written personalization paragraphs for each trigger, with a smooth segue into the problem. + +The personalization must logically connect to the problem. This creates 5 reusable triggers with the rest of the email constant. A top SDR writes a personalized email in **under 3 minutes**. + +## The Four -Graphic Principles (Becc Holland) + +- **Demographic** — Age, profession, background +- **Technographic** — Tech stack, tools used +- **Firmographic** — Company size, funding, industry, growth stage +- **Psychographic** — Values, passions, beliefs (highest-impact dimension) + +Tapping into what prospects are passionate about drives significantly higher response rates. + +## Observation-Based Openers (highest performing) + +**Trigger-event:** "Congrats on the recent funding round — scaling the team from here is exciting, and I imagine [challenge] is top of mind." + +**Observation:** "Your recent post about [topic] resonated — especially the part about [detail]. Got me thinking about how that applies to [challenge]." + +**Industry insight:** "Most [role titles] I talk to spend [X hours/week] on [problem] — curious if that matches your experience at [Company]." + +## What Feels Fake (avoid) + +- AI-generated emails with similar phrasing ("I hope this email finds you well") +- Generic attention hacks disconnected from problem ("Cool that you went to UCLA!" → pitch) +- Over-personalizing to creepiness +- "I saw your LinkedIn profile and wanted to reach out" — signals mass automation + +## The "So What?" Test + +After writing any opening line, read from prospect's perspective: "So what? Why would I care?" If the answer is nothing, rewrite. diff --git a/.agents/skills/cold-email/references/subject-lines.md b/.agents/skills/cold-email/references/subject-lines.md new file mode 100644 index 00000000..3a2cc592 --- /dev/null +++ b/.agents/skills/cold-email/references/subject-lines.md @@ -0,0 +1,53 @@ +# Subject Line Optimization + +The subject line determines whether the email gets read. The data is counterintuitive: **short, boring, internal-looking subject lines win decisively.** + +## Length: 2–4 words + +- 2-word subject lines get **60% more opens** than 5-word (Lavender). +- Going from 2 to 4 words reduces replies by **17.5%**. +- 2–4 words yield **46% open rates** vs 34% for 10 words (Belkins, 5.5M emails). +- Mobile truncates at 30–35 characters — brevity is practical necessity. + +## Internal Camouflage Principle + +Subject lines that look like they came from a colleague, not a vendor, double open rates (Gong). Buyers mentally categorize before opening — if it looks like sales, it's filtered. + +**High-performing examples:** "reply rates" · "trial delays" · "hiring ops" · "employee turnover" · "Q2 forecast" · "new patients" · "personalization issue" · "second page" + +## Capitalization: lowercase wins + +All-lowercase has highest open rates (Gong, 85M+ emails). Lowercase looks more personal/internal. For cold outreach specifically, lowercase beats title case. + +## Personalization: context over name + +Personalized subject lines boost opens **26–50%**, but type matters: + +- **First name in subject line → 12% fewer replies.** Signals automation. +- **Contextual personalization works:** pain points, competitors, trigger events, industry challenges. +- Use {{painPoint}}, {{competitor}}, {{commonGround}} — not {{firstName}}. + +## Questions: only when highly specific + +Data conflicts: Belkins says questions perform well (46% open rate). Lavender says questions lower opens by **56%**. Resolution: **specific pain questions work** ("Need help with {{challenge}}?"), **generic questions fail** ("Quick question?" / "Have 15 minutes?"). Default to statements. + +## What to Avoid + +| Anti-pattern | Impact | +| ---------------------------------------------- | --------------------------- | +| Salesy language ("increase," "boost," "ROI") | -17.9% opens | +| Urgency words ("ASAP," "urgent") | Below 36% opens | +| Excessive punctuation ("!!!" or "??") | -36% opens | +| Numbers and percentages | -46% opens | +| Emojis | Hurt B2B professionalism | +| Pitching product in subject | -57% replies | +| Empty/no subject line | +30% opens but -12% replies | +| Spam triggers ("free," "guarantee," "act now") | Deliverability risk | + +## C-Suite Subject Lines + +Executives receive 300–400 emails daily, decide in seconds. They respond **23% more often** than non-C-suite when emails pass their filter (6.4% reply rate). + +What works: ultra-concise, human, understated. "{{companyInitiative}}" · "thank you" · "an update" · "a question" · reference to a specific project or trigger event. + +Anything "salesy" is immediately rejected. diff --git a/.agents/skills/competitor-alternatives/SKILL.md b/.agents/skills/competitor-alternatives/SKILL.md new file mode 100644 index 00000000..e9802a7c --- /dev/null +++ b/.agents/skills/competitor-alternatives/SKILL.md @@ -0,0 +1,256 @@ +--- +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,' or 'competitive landing pages.' Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. Emphasizes deep research, modular content architecture, and varied section types beyond feature tables." +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 + +### 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 diff --git a/.agents/skills/competitor-alternatives/references/content-architecture.md b/.agents/skills/competitor-alternatives/references/content-architecture.md new file mode 100644 index 00000000..74b9ead2 --- /dev/null +++ b/.agents/skills/competitor-alternatives/references/content-architecture.md @@ -0,0 +1,271 @@ +# 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 diff --git a/.agents/skills/competitor-alternatives/references/templates.md b/.agents/skills/competitor-alternatives/references/templates.md new file mode 100644 index 00000000..74375051 --- /dev/null +++ b/.agents/skills/competitor-alternatives/references/templates.md @@ -0,0 +1,223 @@ +# 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] | diff --git a/.agents/skills/content-strategy/SKILL.md b/.agents/skills/content-strategy/SKILL.md index fc64f068..fe0ac747 100644 --- a/.agents/skills/content-strategy/SKILL.md +++ b/.agents/skills/content-strategy/SKILL.md @@ -1,7 +1,8 @@ --- name: content-strategy -version: 1.0.0 description: When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also use when the user mentions "content strategy," "what should I write about," "content ideas," "blog strategy," "topic clusters," or "content planning." For writing individual pieces, see copywriting. For SEO-specific audits, see seo-audit. +metadata: + version: 1.1.0 --- # Content Strategy @@ -11,7 +12,7 @@ You are a content strategist. Your goal is to help plan content that drives traf ## Before Planning **Check for product marketing context first:** -If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task. +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): @@ -351,6 +352,8 @@ Visual or structured representation of how content interconnects. - **copywriting**: For writing individual content pieces - **seo-audit**: For technical SEO and on-page optimization +- **ai-seo**: For optimizing content for AI search engines and getting cited by LLMs - **programmatic-seo**: For scaled content generation +- **site-architecture**: For page hierarchy, navigation design, and URL structure - **email-sequence**: For email-based content - **social-content**: For social media content diff --git a/.agents/skills/copy-editing/SKILL.md b/.agents/skills/copy-editing/SKILL.md new file mode 100644 index 00000000..57bd17b5 --- /dev/null +++ b/.agents/skills/copy-editing/SKILL.md @@ -0,0 +1,447 @@ +--- +name: copy-editing +description: "When the user wants to edit, review, or improve existing marketing copy. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' or 'copy sweep.' This skill provides a systematic approach to editing marketing copy through multiple focused passes." +metadata: + version: 1.1.0 +--- + +# Copy Editing + +You are an expert copy editor specializing in marketing and conversion copy. Your goal is to systematically improve existing copy through focused editing passes while preserving the core message. + +## Core Philosophy + +**Check for product marketing context first:** +If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before editing. Use brand voice and customer language from that context to guide your edits. + +Good copy editing isn't about rewriting—it's about enhancing. Each pass focuses on one dimension, catching issues that get missed when you try to fix everything at once. + +**Key principles:** +- Don't change the core message; focus on enhancing it +- Multiple focused passes beat one unfocused review +- Each edit should have a clear reason +- Preserve the author's voice while improving clarity + +--- + +## The Seven Sweeps Framework + +Edit copy through seven sequential passes, each focusing on one dimension. After each sweep, loop back to check previous sweeps aren't compromised. + +### Sweep 1: Clarity + +**Focus:** Can the reader understand what you're saying? + +**What to check:** +- Confusing sentence structures +- Unclear pronoun references +- Jargon or insider language +- Ambiguous statements +- Missing context + +**Common clarity killers:** +- Sentences trying to say too much +- Abstract language instead of concrete +- Assuming reader knowledge they don't have +- Burying the point in qualifications + +**Process:** +1. Read through quickly, highlighting unclear parts +2. Don't correct yet—just note problem areas +3. After marking issues, recommend specific edits +4. Verify edits maintain the original intent + +**After this sweep:** Confirm the "Rule of One" (one main idea per section) and "You Rule" (copy speaks to the reader) are intact. + +--- + +### Sweep 2: Voice and Tone + +**Focus:** Is the copy consistent in how it sounds? + +**What to check:** +- Shifts between formal and casual +- Inconsistent brand personality +- Mood changes that feel jarring +- Word choices that don't match the brand + +**Common voice issues:** +- Starting casual, becoming corporate +- Mixing "we" and "the company" references +- Humor in some places, serious in others (unintentionally) +- Technical language appearing randomly + +**Process:** +1. Read aloud to hear inconsistencies +2. Mark where tone shifts unexpectedly +3. Recommend edits that smooth transitions +4. Ensure personality remains throughout + +**After this sweep:** Return to Clarity Sweep to ensure voice edits didn't introduce confusion. + +--- + +### Sweep 3: So What + +**Focus:** Does every claim answer "why should I care?" + +**What to check:** +- Features without benefits +- Claims without consequences +- Statements that don't connect to reader's life +- Missing "which means..." bridges + +**The So What test:** +For every statement, ask "Okay, so what?" If the copy doesn't answer that question with a deeper benefit, it needs work. + +❌ "Our platform uses AI-powered analytics" +*So what?* +✅ "Our AI-powered analytics surface insights you'd miss manually—so you can make better decisions in half the time" + +**Common So What failures:** +- Feature lists without benefit connections +- Impressive-sounding claims that don't land +- Technical capabilities without outcomes +- Company achievements that don't help the reader + +**Process:** +1. Read each claim and literally ask "so what?" +2. Highlight claims missing the answer +3. Add the benefit bridge or deeper meaning +4. Ensure benefits connect to real reader desires + +**After this sweep:** Return to Voice and Tone, then Clarity. + +--- + +### Sweep 4: Prove It + +**Focus:** Is every claim supported with evidence? + +**What to check:** +- Unsubstantiated claims +- Missing social proof +- Assertions without backup +- "Best" or "leading" without evidence + +**Types of proof to look for:** +- Testimonials with names and specifics +- Case study references +- Statistics and data +- Third-party validation +- Guarantees and risk reversals +- Customer logos +- Review scores + +**Common proof gaps:** +- "Trusted by thousands" (which thousands?) +- "Industry-leading" (according to whom?) +- "Customers love us" (show them saying it) +- Results claims without specifics + +**Process:** +1. Identify every claim that needs proof +2. Check if proof exists nearby +3. Flag unsupported assertions +4. Recommend adding proof or softening claims + +**After this sweep:** Return to So What, Voice and Tone, then Clarity. + +--- + +### Sweep 5: Specificity + +**Focus:** Is the copy concrete enough to be compelling? + +**What to check:** +- Vague language ("improve," "enhance," "optimize") +- Generic statements that could apply to anyone +- Round numbers that feel made up +- Missing details that would make it real + +**Specificity upgrades:** + +| Vague | Specific | +|-------|----------| +| Save time | Save 4 hours every week | +| Many customers | 2,847 teams | +| Fast results | Results in 14 days | +| Improve your workflow | Cut your reporting time in half | +| Great support | Response within 2 hours | + +**Common specificity issues:** +- Adjectives doing the work nouns should do +- Benefits without quantification +- Outcomes without timeframes +- Claims without concrete examples + +**Process:** +1. Highlight vague words and phrases +2. Ask "Can this be more specific?" +3. Add numbers, timeframes, or examples +4. Remove content that can't be made specific (it's probably filler) + +**After this sweep:** Return to Prove It, So What, Voice and Tone, then Clarity. + +--- + +### Sweep 6: Heightened Emotion + +**Focus:** Does the copy make the reader feel something? + +**What to check:** +- Flat, informational language +- Missing emotional triggers +- Pain points mentioned but not felt +- Aspirations stated but not evoked + +**Emotional dimensions to consider:** +- Pain of the current state +- Frustration with alternatives +- Fear of missing out +- Desire for transformation +- Pride in making smart choices +- Relief from solving the problem + +**Techniques for heightening emotion:** +- Paint the "before" state vividly +- Use sensory language +- Tell micro-stories +- Reference shared experiences +- Ask questions that prompt reflection + +**Process:** +1. Read for emotional impact—does it move you? +2. Identify flat sections that should resonate +3. Add emotional texture while staying authentic +4. Ensure emotion serves the message (not manipulation) + +**After this sweep:** Return to Specificity, Prove It, So What, Voice and Tone, then Clarity. + +--- + +### Sweep 7: Zero Risk + +**Focus:** Have we removed every barrier to action? + +**What to check:** +- Friction near CTAs +- Unanswered objections +- Missing trust signals +- Unclear next steps +- Hidden costs or surprises + +**Risk reducers to look for:** +- Money-back guarantees +- Free trials +- "No credit card required" +- "Cancel anytime" +- Social proof near CTA +- Clear expectations of what happens next +- Privacy assurances + +**Common risk issues:** +- CTA asks for commitment without earning trust +- Objections raised but not addressed +- Fine print that creates doubt +- Vague "Contact us" instead of clear next step + +**Process:** +1. Focus on sections near CTAs +2. List every reason someone might hesitate +3. Check if the copy addresses each concern +4. Add risk reversals or trust signals as needed + +**After this sweep:** Return through all previous sweeps one final time: Heightened Emotion, Specificity, Prove It, So What, Voice and Tone, Clarity. + +--- + +## Quick-Pass Editing Checks + +Use these for faster reviews when a full seven-sweep process isn't needed. + +### Word-Level Checks + +**Cut these words:** +- Very, really, extremely, incredibly (weak intensifiers) +- Just, actually, basically (filler) +- In order to (use "to") +- That (often unnecessary) +- Things, stuff (vague) + +**Replace these:** + +| Weak | Strong | +|------|--------| +| Utilize | Use | +| Implement | Set up | +| Leverage | Use | +| Facilitate | Help | +| Innovative | New | +| Robust | Strong | +| Seamless | Smooth | +| Cutting-edge | New/Modern | + +**Watch for:** +- Adverbs (usually unnecessary) +- Passive voice (switch to active) +- Nominalizations (verb → noun: "make a decision" → "decide") + +### Sentence-Level Checks + +- One idea per sentence +- Vary sentence length (mix short and long) +- Front-load important information +- Max 3 conjunctions per sentence +- No more than 25 words (usually) + +### Paragraph-Level Checks + +- One topic per paragraph +- Short paragraphs (2-4 sentences for web) +- Strong opening sentences +- Logical flow between paragraphs +- White space for scannability + +--- + +## Copy Editing Checklist + +### Before You Start +- [ ] Understand the goal of this copy +- [ ] Know the target audience +- [ ] Identify the desired action +- [ ] Read through once without editing + +### Clarity (Sweep 1) +- [ ] Every sentence is immediately understandable +- [ ] No jargon without explanation +- [ ] Pronouns have clear references +- [ ] No sentences trying to do too much + +### Voice & Tone (Sweep 2) +- [ ] Consistent formality level throughout +- [ ] Brand personality maintained +- [ ] No jarring shifts in mood +- [ ] Reads well aloud + +### So What (Sweep 3) +- [ ] Every feature connects to a benefit +- [ ] Claims answer "why should I care?" +- [ ] Benefits connect to real desires +- [ ] No impressive-but-empty statements + +### Prove It (Sweep 4) +- [ ] Claims are substantiated +- [ ] Social proof is specific and attributed +- [ ] Numbers and stats have sources +- [ ] No unearned superlatives + +### Specificity (Sweep 5) +- [ ] Vague words replaced with concrete ones +- [ ] Numbers and timeframes included +- [ ] Generic statements made specific +- [ ] Filler content removed + +### Heightened Emotion (Sweep 6) +- [ ] Copy evokes feeling, not just information +- [ ] Pain points feel real +- [ ] Aspirations feel achievable +- [ ] Emotion serves the message authentically + +### Zero Risk (Sweep 7) +- [ ] Objections addressed near CTA +- [ ] Trust signals present +- [ ] Next steps are crystal clear +- [ ] Risk reversals stated (guarantee, trial, etc.) + +### Final Checks +- [ ] No typos or grammatical errors +- [ ] Consistent formatting +- [ ] Links work (if applicable) +- [ ] Core message preserved through all edits + +--- + +## Common Copy Problems & Fixes + +### Problem: Wall of Features +**Symptom:** List of what the product does without why it matters +**Fix:** Add "which means..." after each feature to bridge to benefits + +### Problem: Corporate Speak +**Symptom:** "Leverage synergies to optimize outcomes" +**Fix:** Ask "How would a human say this?" and use those words + +### Problem: Weak Opening +**Symptom:** Starting with company history or vague statements +**Fix:** Lead with the reader's problem or desired outcome + +### Problem: Buried CTA +**Symptom:** The ask comes after too much buildup, or isn't clear +**Fix:** Make the CTA obvious, early, and repeated + +### Problem: No Proof +**Symptom:** "Customers love us" with no evidence +**Fix:** Add specific testimonials, numbers, or case references + +### Problem: Generic Claims +**Symptom:** "We help businesses grow" +**Fix:** Specify who, how, and by how much + +### Problem: Mixed Audiences +**Symptom:** Copy tries to speak to everyone, resonates with no one +**Fix:** Pick one audience and write directly to them + +### Problem: Feature Overload +**Symptom:** Listing every capability, overwhelming the reader +**Fix:** Focus on 3-5 key benefits that matter most to the audience + +--- + +## Working with Copy Sweeps + +When editing collaboratively: + +1. **Run a sweep and present findings** - Show what you found, why it's an issue +2. **Recommend specific edits** - Don't just identify problems; propose solutions +3. **Request the updated copy** - Let the author make final decisions +4. **Verify previous sweeps** - After each round of edits, re-check earlier sweeps +5. **Repeat until clean** - Continue until a full sweep finds no new issues + +This iterative process ensures each edit doesn't create new problems while respecting the author's ownership of the copy. + +--- + +## References + +- [Plain English Alternatives](references/plain-english-alternatives.md): Replace complex words with simpler alternatives + +--- + +## Task-Specific Questions + +1. What's the goal of this copy? (Awareness, conversion, retention) +2. What action should readers take? +3. Are there specific concerns or known issues? +4. What proof/evidence do you have available? + +--- + +## Related Skills + +- **copywriting**: For writing new copy from scratch (use this skill to edit after your first draft is complete) +- **page-cro**: For broader page optimization beyond copy +- **marketing-psychology**: For understanding why certain edits improve conversion +- **ab-test-setup**: For testing copy variations + +--- + +## When to Use Each Skill + +| Task | Skill to Use | +|------|--------------| +| Writing new page copy from scratch | copywriting | +| Reviewing and improving existing copy | copy-editing (this skill) | +| Editing copy you just wrote | copy-editing (this skill) | +| Structural or strategic page changes | page-cro | diff --git a/.agents/skills/copy-editing/references/plain-english-alternatives.md b/.agents/skills/copy-editing/references/plain-english-alternatives.md new file mode 100644 index 00000000..2fc32355 --- /dev/null +++ b/.agents/skills/copy-editing/references/plain-english-alternatives.md @@ -0,0 +1,394 @@ +# Plain English Alternatives + +Replace complex or pompous words with plain English alternatives. + +Source: Plain English Campaign A-Z of Alternative Words (2001), Australian Government Style Manual (2024), plainlanguage.gov + +--- + +## Contents +- A +- B +- C +- D +- E +- F +- G-H +- I +- L-M +- N-O +- P +- R +- S +- T-U +- V-Z +- Phrases to Remove Entirely + +## A + +| Complex | Plain Alternative | +|---------|-------------------| +| (an) absence of | no, none | +| abundance | enough, plenty, many | +| accede to | allow, agree to | +| accelerate | speed up | +| accommodate | meet, hold, house | +| accomplish | do, finish, complete | +| accordingly | so, therefore | +| acknowledge | thank you for, confirm | +| acquire | get, buy, obtain | +| additional | extra, more | +| adjacent | next to | +| advantageous | useful, helpful | +| advise | tell, say, inform | +| aforesaid | this, earlier | +| aggregate | total | +| alleviate | ease, reduce | +| allocate | give, share, assign | +| alternative | other, choice | +| ameliorate | improve | +| anticipate | expect | +| apparent | clear, obvious | +| appreciable | large, noticeable | +| appropriate | proper, right, suitable | +| approximately | about, roughly | +| ascertain | find out | +| assistance | help | +| at the present time | now | +| attempt | try | +| authorise | allow, let | + +--- + +## B + +| Complex | Plain Alternative | +|---------|-------------------| +| belated | late | +| beneficial | helpful, useful | +| bestow | give | +| by means of | by | + +--- + +## C + +| Complex | Plain Alternative | +|---------|-------------------| +| calculate | work out | +| cease | stop, end | +| circumvent | avoid, get around | +| clarification | explanation | +| commence | start, begin | +| communicate | tell, talk, write | +| competent | able | +| compile | collect, make | +| complete | fill in, finish | +| component | part | +| comprise | include, make up | +| (it is) compulsory | (you) must | +| conceal | hide | +| concerning | about | +| consequently | so | +| considerable | large, great, much | +| constitute | make up, form | +| consult | ask, talk to | +| consumption | use | +| currently | now | + +--- + +## D + +| Complex | Plain Alternative | +|---------|-------------------| +| deduct | take off | +| deem | treat as, consider | +| defer | delay, put off | +| deficiency | lack | +| delete | remove, cross out | +| demonstrate | show, prove | +| denote | show, mean | +| designate | name, appoint | +| despatch/dispatch | send | +| determine | decide, find out | +| detrimental | harmful | +| diminish | reduce, lessen | +| discontinue | stop | +| disseminate | spread, distribute | +| documentation | papers, documents | +| due to the fact that | because | +| duration | time, length | +| dwelling | home | + +--- + +## E + +| Complex | Plain Alternative | +|---------|-------------------| +| economical | cheap, good value | +| eligible | allowed, qualified | +| elucidate | explain | +| enable | allow | +| encounter | meet | +| endeavour | try | +| enquire | ask | +| ensure | make sure | +| entitlement | right | +| envisage | expect | +| equivalent | equal, the same | +| erroneous | wrong | +| establish | set up, show | +| evaluate | assess, test | +| excessive | too much | +| exclusively | only | +| exempt | free from | +| expedite | speed up | +| expenditure | spending | +| expire | run out | + +--- + +## F + +| Complex | Plain Alternative | +|---------|-------------------| +| fabricate | make | +| facilitate | help, make possible | +| finalise | finish, complete | +| following | after | +| for the purpose of | to, for | +| for the reason that | because | +| forthwith | now, at once | +| forward | send | +| frequently | often | +| furnish | give, provide | +| furthermore | also, and | + +--- + +## G-H + +| Complex | Plain Alternative | +|---------|-------------------| +| generate | produce, create | +| henceforth | from now on | +| hitherto | until now | + +--- + +## I + +| Complex | Plain Alternative | +|---------|-------------------| +| if and when | if, when | +| illustrate | show | +| immediately | at once, now | +| implement | carry out, do | +| imply | suggest | +| in accordance with | under, following | +| in addition to | and, also | +| in conjunction with | with | +| in excess of | more than | +| in lieu of | instead of | +| in order to | to | +| in receipt of | receive | +| in relation to | about | +| in respect of | about, for | +| in the event of | if | +| in the majority of instances | most, usually | +| in the near future | soon | +| in view of the fact that | because | +| inception | start | +| indicate | show, suggest | +| inform | tell | +| initiate | start, begin | +| insert | put in | +| instances | cases | +| irrespective of | despite | +| issue | give, send | + +--- + +## L-M + +| Complex | Plain Alternative | +|---------|-------------------| +| (a) large number of | many | +| liaise with | work with, talk to | +| locality | place, area | +| locate | find | +| magnitude | size | +| (it is) mandatory | (you) must | +| manner | way | +| modification | change | +| moreover | also, and | + +--- + +## N-O + +| Complex | Plain Alternative | +|---------|-------------------| +| negligible | small | +| nevertheless | but, however | +| notify | tell | +| notwithstanding | despite, even if | +| numerous | many | +| objective | aim, goal | +| (it is) obligatory | (you) must | +| obtain | get | +| occasioned by | caused by | +| on behalf of | for | +| on numerous occasions | often | +| on receipt of | when you get | +| on the grounds that | because | +| operate | work, run | +| optimum | best | +| option | choice | +| otherwise | or | +| outstanding | unpaid | +| owing to | because | + +--- + +## P + +| Complex | Plain Alternative | +|---------|-------------------| +| partially | partly | +| participate | take part | +| particulars | details | +| per annum | a year | +| perform | do | +| permit | let, allow | +| personnel | staff, people | +| peruse | read | +| possess | have, own | +| practically | almost | +| predominant | main | +| prescribe | set | +| preserve | keep | +| previous | earlier, before | +| principal | main | +| prior to | before | +| proceed | go ahead | +| procure | get | +| prohibit | ban, stop | +| promptly | quickly | +| provide | give | +| provided that | if | +| provisions | rules, terms | +| proximity | nearness | +| purchase | buy | +| pursuant to | under | + +--- + +## R + +| Complex | Plain Alternative | +|---------|-------------------| +| reconsider | think again | +| reduction | cut | +| referred to as | called | +| regarding | about | +| reimburse | repay | +| reiterate | repeat | +| relating to | about | +| remain | stay | +| remainder | rest | +| remuneration | pay | +| render | make, give | +| represent | stand for | +| request | ask | +| require | need | +| residence | home | +| retain | keep | +| revised | changed, new | + +--- + +## S + +| Complex | Plain Alternative | +|---------|-------------------| +| scrutinise | examine, check | +| select | choose | +| solely | only | +| specified | given, stated | +| state | say | +| statutory | legal, by law | +| subject to | depending on | +| submit | send, give | +| subsequent to | after | +| subsequently | later | +| substantial | large, much | +| sufficient | enough | +| supplement | add to | +| supplementary | extra | + +--- + +## T-U + +| Complex | Plain Alternative | +|---------|-------------------| +| terminate | end, stop | +| thereafter | then | +| thereby | by this | +| thus | so | +| to date | so far | +| transfer | move | +| transmit | send | +| ultimately | in the end | +| undertake | agree, do | +| uniform | same | +| utilise | use | + +--- + +## V-Z + +| Complex | Plain Alternative | +|---------|-------------------| +| variation | change | +| virtually | almost | +| visualise | imagine, see | +| ways and means | ways | +| whatsoever | any | +| with a view to | to | +| with effect from | from | +| with reference to | about | +| with regard to | about | +| with respect to | about | +| zone | area | + +--- + +## Phrases to Remove Entirely + +These phrases often add nothing. Delete them: + +- a total of +- absolutely +- actually +- all things being equal +- as a matter of fact +- at the end of the day +- at this moment in time +- basically +- currently (when "now" or nothing works) +- I am of the opinion that (use: I think) +- in due course (use: soon, or say when) +- in the final analysis +- it should be understood +- last but not least +- obviously +- of course +- quite +- really +- the fact of the matter is +- to all intents and purposes +- very diff --git a/.agents/skills/copywriting/SKILL.md b/.agents/skills/copywriting/SKILL.md new file mode 100644 index 00000000..f578d280 --- /dev/null +++ b/.agents/skills/copywriting/SKILL.md @@ -0,0 +1,252 @@ +--- +name: copywriting +description: When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says "write copy for," "improve this copy," "rewrite this page," "marketing copy," "headline help," or "CTA copy." For email copy, see email-sequence. For popup copy, see popup-cro. +metadata: + version: 1.1.0 +--- + +# Copywriting + +You are an expert conversion copywriter. Your goal is to write marketing copy that is clear, compelling, and drives action. + +## Before Writing + +**Check for product marketing context first:** +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. Page Purpose +- What type of page? (homepage, landing page, pricing, feature, about) +- What is the ONE primary action you want visitors to take? + +### 2. Audience +- Who is the ideal customer? +- What problem are they trying to solve? +- What objections or hesitations do they have? +- What language do they use to describe their problem? + +### 3. Product/Offer +- What are you selling or offering? +- What makes it different from alternatives? +- What's the key transformation or outcome? +- Any proof points (numbers, testimonials, case studies)? + +### 4. Context +- Where is traffic coming from? (ads, organic, email) +- What do visitors already know before arriving? + +--- + +## Copywriting Principles + +### Clarity Over Cleverness +If you have to choose between clear and creative, choose clear. + +### Benefits Over Features +Features: What it does. Benefits: What that means for the customer. + +### Specificity Over Vagueness +- Vague: "Save time on your workflow" +- Specific: "Cut your weekly reporting from 4 hours to 15 minutes" + +### Customer Language Over Company Language +Use words your customers use. Mirror voice-of-customer from reviews, interviews, support tickets. + +### One Idea Per Section +Each section should advance one argument. Build a logical flow down the page. + +--- + +## Writing Style Rules + +### Core Principles + +1. **Simple over complex** — "Use" not "utilize," "help" not "facilitate" +2. **Specific over vague** — Avoid "streamline," "optimize," "innovative" +3. **Active over passive** — "We generate reports" not "Reports are generated" +4. **Confident over qualified** — Remove "almost," "very," "really" +5. **Show over tell** — Describe the outcome instead of using adverbs +6. **Honest over sensational** — Never fabricate statistics or testimonials + +### Quick Quality Check + +- Jargon that could confuse outsiders? +- Sentences trying to do too much? +- Passive voice constructions? +- Exclamation points? (remove them) +- Marketing buzzwords without substance? + +For thorough line-by-line review, use the **copy-editing** skill after your draft. + +--- + +## Best Practices + +### Be Direct +Get to the point. Don't bury the value in qualifications. + +❌ Slack lets you share files instantly, from documents to images, directly in your conversations + +✅ Need to share a screenshot? Send as many documents, images, and audio files as your heart desires. + +### Use Rhetorical Questions +Questions engage readers and make them think about their own situation. +- "Hate returning stuff to Amazon?" +- "Tired of chasing approvals?" + +### Use Analogies When Helpful +Analogies make abstract concepts concrete and memorable. + +### Pepper in Humor (When Appropriate) +Puns and wit make copy memorable—but only if it fits the brand and doesn't undermine clarity. + +--- + +## Page Structure Framework + +### Above the Fold + +**Headline** +- Your single most important message +- Communicate core value proposition +- Specific > generic + +**Example formulas:** +- "{Achieve outcome} without {pain point}" +- "The {category} for {audience}" +- "Never {unpleasant event} again" +- "{Question highlighting main pain point}" + +**For comprehensive headline formulas**: See [references/copy-frameworks.md](references/copy-frameworks.md) + +**For natural transition phrases**: See [references/natural-transitions.md](references/natural-transitions.md) + +**Subheadline** +- Expands on headline +- Adds specificity +- 1-2 sentences max + +**Primary CTA** +- Action-oriented button text +- Communicate what they get: "Start Free Trial" > "Sign Up" + +### Core Sections + +| Section | Purpose | +|---------|---------| +| Social Proof | Build credibility (logos, stats, testimonials) | +| Problem/Pain | Show you understand their situation | +| Solution/Benefits | Connect to outcomes (3-5 key benefits) | +| How It Works | Reduce perceived complexity (3-4 steps) | +| Objection Handling | FAQ, comparisons, guarantees | +| Final CTA | Recap value, repeat CTA, risk reversal | + +**For detailed section types and page templates**: See [references/copy-frameworks.md](references/copy-frameworks.md) + +--- + +## CTA Copy Guidelines + +**Weak CTAs (avoid):** +- Submit, Sign Up, Learn More, Click Here, Get Started + +**Strong CTAs (use):** +- Start Free Trial +- Get [Specific Thing] +- See [Product] in Action +- Create Your First [Thing] +- Download the Guide + +**Formula:** [Action Verb] + [What They Get] + [Qualifier if needed] + +Examples: +- "Start My Free Trial" +- "Get the Complete Checklist" +- "See Pricing for My Team" + +--- + +## Page-Specific Guidance + +### Homepage +- Serve multiple audiences without being generic +- Lead with broadest value proposition +- Provide clear paths for different visitor intents + +### Landing Page +- Single message, single CTA +- Match headline to ad/traffic source +- Complete argument on one page + +### Pricing Page +- Help visitors choose the right plan +- Address "which is right for me?" anxiety +- Make recommended plan obvious + +### Feature Page +- Connect feature → benefit → outcome +- Show use cases and examples +- Clear path to try or buy + +### About Page +- Tell the story of why you exist +- Connect mission to customer benefit +- Still include a CTA + +--- + +## Voice and Tone + +Before writing, establish: + +**Formality level:** +- Casual/conversational +- Professional but friendly +- Formal/enterprise + +**Brand personality:** +- Playful or serious? +- Bold or understated? +- Technical or accessible? + +Maintain consistency, but adjust intensity: +- Headlines can be bolder +- Body copy should be clearer +- CTAs should be action-oriented + +--- + +## Output Format + +When writing copy, provide: + +### Page Copy +Organized by section: +- Headline, Subheadline, CTA +- Section headers and body copy +- Secondary CTAs + +### Annotations +For key elements, explain: +- Why you made this choice +- What principle it applies + +### Alternatives +For headlines and CTAs, provide 2-3 options: +- Option A: [copy] — [rationale] +- Option B: [copy] — [rationale] + +### Meta Content (if relevant) +- Page title (for SEO) +- Meta description + +--- + +## Related Skills + +- **copy-editing**: For polishing existing copy (use after your draft) +- **page-cro**: If page structure/strategy needs work, not just copy +- **email-sequence**: For email copywriting +- **popup-cro**: For popup and modal copy +- **ab-test-setup**: To test copy variations diff --git a/.agents/skills/copywriting/references/copy-frameworks.md b/.agents/skills/copywriting/references/copy-frameworks.md new file mode 100644 index 00000000..0abc8123 --- /dev/null +++ b/.agents/skills/copywriting/references/copy-frameworks.md @@ -0,0 +1,344 @@ +# Copy Frameworks Reference + +Headline formulas, page section types, and structural templates. + +## Contents +- Headline Formulas (outcome-focused, problem-focused, audience-focused, differentiation-focused, proof-focused, additional formulas) +- Landing Page Section Types (core sections, supporting sections) +- Page Structure Templates (feature-heavy page, varied engaging page, compact landing page, enterprise/B2B landing page, product launch page) +- Section Writing Tips (problem section, benefits section, how it works section, testimonial selection) + +## Headline Formulas + +### Outcome-Focused + +**{Achieve desirable outcome} without {pain point}** +> Understand how users are really experiencing your site without drowning in numbers + +**{Achieve desirable outcome} by {how product makes it possible}** +> Generate more leads by seeing which companies visit your site + +**Turn {input} into {outcome}** +> Turn your hard-earned sales into repeat customers + +**[Achieve outcome] in [timeframe]** +> Get your tax refund in 10 days + +--- + +### Problem-Focused + +**Never {unpleasant event} again** +> Never miss a sales opportunity again + +**{Question highlighting the main pain point}** +> Hate returning stuff to Amazon? + +**Stop [pain]. Start [pleasure].** +> Stop chasing invoices. Start getting paid on time. + +--- + +### Audience-Focused + +**{Key feature/product type} for {target audience}** +> Advanced analytics for Shopify e-commerce + +**{Key feature/product type} for {target audience} to {what it's used for}** +> An online whiteboard for teams to ideate and brainstorm together + +**You don't have to {skills or resources} to {achieve desirable outcome}** +> With Ahrefs, you don't have to be an SEO pro to rank higher and get more traffic + +--- + +### Differentiation-Focused + +**The {opposite of usual process} way to {achieve desirable outcome}** +> The easiest way to turn your passion into income + +**The [category] that [key differentiator]** +> The CRM that updates itself + +--- + +### Proof-Focused + +**[Number] [people] use [product] to [outcome]** +> 50,000 marketers use Drip to send better emails + +**{Key benefit of your product}** +> Sound clear in online meetings + +--- + +### Additional Formulas + +**The simple way to {outcome}** +> The simple way to track your time + +**Finally, {category} that {benefit}** +> Finally, accounting software that doesn't suck + +**{Outcome} without {common pain}** +> Build your website without writing code + +**Get {benefit} from your {thing}** +> Get more revenue from your existing traffic + +**{Action verb} your {thing} like {admirable example}** +> Market your SaaS like a Fortune 500 + +**What if you could {desirable outcome}?** +> What if you could close deals 30% faster? + +**Everything you need to {outcome}** +> Everything you need to launch your course + +**The {adjective} {category} built for {audience}** +> The lightweight CRM built for startups + +--- + +## Landing Page Section Types + +### Core Sections + +**Hero (Above the Fold)** +- Headline + subheadline +- Primary CTA +- Supporting visual (product screenshot, hero image) +- Optional: Social proof bar + +**Social Proof Bar** +- Customer logos (recognizable > many) +- Key metric ("10,000+ teams") +- Star rating with review count +- Short testimonial snippet + +**Problem/Pain Section** +- Articulate their problem better than they can +- Create recognition ("that's exactly my situation") +- Hint at cost of not solving it + +**Solution/Benefits Section** +- Bridge from problem to your solution +- 3-5 key benefits (not 10) +- Each: headline + explanation + proof if available + +**How It Works** +- 3-4 numbered steps +- Reduces perceived complexity +- Each step: action + outcome + +**Final CTA Section** +- Recap value proposition +- Repeat primary CTA +- Risk reversal (guarantee, free trial) + +--- + +### Supporting Sections + +**Testimonials** +- Full quotes with names, roles, companies +- Photos when possible +- Specific results over vague praise +- Formats: quote cards, video, tweet embeds + +**Case Studies** +- Problem → Solution → Results +- Specific metrics and outcomes +- Customer name and context +- Can be snippets with "Read more" links + +**Use Cases** +- Different ways product is used +- Helps visitors self-identify +- "For marketers who need X" format + +**Personas / "Built For" Sections** +- Explicitly call out target audience +- "Perfect for [role]" blocks +- Addresses "Is this for me?" question + +**FAQ Section** +- Address common objections +- Good for SEO +- Reduces support burden +- 5-10 most common questions + +**Comparison Section** +- vs. competitors (name them or don't) +- vs. status quo (spreadsheets, manual processes) +- Tables or side-by-side format + +**Integrations / Partners** +- Logos of tools you connect with +- "Works with your stack" messaging +- Builds credibility + +**Founder Story / Manifesto** +- Why you built this +- What you believe +- Emotional connection +- Differentiates from faceless competitors + +**Demo / Product Tour** +- Interactive demos +- Video walkthroughs +- GIF previews +- Shows product in action + +**Pricing Preview** +- Teaser even on non-pricing pages +- Starting price or "from $X/mo" +- Moves decision-makers forward + +**Guarantee / Risk Reversal** +- Money-back guarantee +- Free trial terms +- "Cancel anytime" +- Reduces friction + +**Stats Section** +- Key metrics that build credibility +- "10,000+ customers" +- "4.9/5 rating" +- "$2M saved for customers" + +--- + +## Page Structure Templates + +### Feature-Heavy Page (Weak) + +``` +1. Hero +2. Feature 1 +3. Feature 2 +4. Feature 3 +5. Feature 4 +6. CTA +``` + +This is a list, not a persuasive narrative. + +--- + +### Varied, Engaging Page (Strong) + +``` +1. Hero with clear value prop +2. Social proof bar (logos or stats) +3. Problem/pain section +4. How it works (3 steps) +5. Key benefits (2-3, not 10) +6. Testimonial +7. Use cases or personas +8. Comparison to alternatives +9. Case study snippet +10. FAQ +11. Final CTA with guarantee +``` + +This tells a story and addresses objections. + +--- + +### Compact Landing Page + +``` +1. Hero (headline, subhead, CTA, image) +2. Social proof bar +3. 3 key benefits with icons +4. Testimonial +5. How it works (3 steps) +6. Final CTA with guarantee +``` + +Good for ad landing pages where brevity matters. + +--- + +### Enterprise/B2B Landing Page + +``` +1. Hero (outcome-focused headline) +2. Logo bar (recognizable companies) +3. Problem section (business pain) +4. Solution overview +5. Use cases by role/department +6. Security/compliance section +7. Integration logos +8. Case study with metrics +9. ROI/value section +10. Contact/demo CTA +``` + +Addresses enterprise buyer concerns. + +--- + +### Product Launch Page + +``` +1. Hero with launch announcement +2. Video demo or walkthrough +3. Feature highlights (3-5) +4. Before/after comparison +5. Early testimonials +6. Launch pricing or early access offer +7. CTA with urgency +``` + +Good for ProductHunt, launches, or announcements. + +--- + +## Section Writing Tips + +### Problem Section + +Start with phrases like: +- "You know the feeling..." +- "If you're like most [role]..." +- "Every day, [audience] struggles with..." +- "We've all been there..." + +Then describe: +- The specific frustration +- The time/money wasted +- The impact on their work/life + +### Benefits Section + +For each benefit, include: +- **Headline**: The outcome they get +- **Body**: How it works (1-2 sentences) +- **Proof**: Number, testimonial, or example (optional) + +### How It Works Section + +Each step should be: +- **Numbered**: Creates sense of progress +- **Simple verb**: "Connect," "Set up," "Get" +- **Outcome-oriented**: What they get from this step + +Example: +1. Connect your tools (takes 2 minutes) +2. Set your preferences +3. Get automated reports every Monday + +### Testimonial Selection + +Best testimonials include: +- Specific results ("increased conversions by 32%") +- Before/after context ("We used to spend hours...") +- Role + company for credibility +- Something quotable and specific + +Avoid testimonials that just say: +- "Great product!" +- "Love it!" +- "Easy to use!" diff --git a/.agents/skills/copywriting/references/natural-transitions.md b/.agents/skills/copywriting/references/natural-transitions.md new file mode 100644 index 00000000..ee72faa5 --- /dev/null +++ b/.agents/skills/copywriting/references/natural-transitions.md @@ -0,0 +1,272 @@ +# Natural Transitions + +Transitional phrases to guide readers through your content. Good signposting improves readability, user engagement, and helps search engines understand content structure. + +Adapted from: University of Manchester Academic Phrasebank (2023), Plain English Campaign, web content best practices + +--- + +## Contents +- Previewing Content Structure +- Introducing a New Topic +- Referring Back +- Moving Between Sections +- Indicating Addition +- Indicating Contrast +- Indicating Similarity +- Indicating Cause and Effect +- Giving Examples +- Emphasising Key Points +- Providing Evidence (neutral attribution, expert quotes, supporting claims) +- Summarising Sections +- Concluding Content +- Question-Based Transitions +- List Introductions +- Hedging Language +- Best Practice Guidelines +- Transitions to Avoid (AI Tells) + +## Previewing Content Structure + +Use to orient readers and set expectations: + +- Here's what we'll cover... +- This guide walks you through... +- Below, you'll find... +- We'll start with X, then move to Y... +- First, let's look at... +- Let's break this down step by step. +- The sections below explain... + +--- + +## Introducing a New Topic + +- When it comes to X,... +- Regarding X,... +- Speaking of X,... +- Now let's talk about X. +- Another key factor is... +- X is worth exploring because... + +--- + +## Referring Back + +Use to connect ideas and reinforce key points: + +- As mentioned earlier,... +- As we covered above,... +- Remember when we discussed X? +- Building on that point,... +- Going back to X,... +- Earlier, we explained that... + +--- + +## Moving Between Sections + +- Now let's look at... +- Next up:... +- Moving on to... +- With that covered, let's turn to... +- Now that you understand X, here's Y. +- That brings us to... + +--- + +## Indicating Addition + +- Also,... +- Plus,... +- On top of that,... +- What's more,... +- Another benefit is... +- Beyond that,... +- In addition,... +- There's also... + +**Note:** Use "moreover" and "furthermore" sparingly. They can sound AI-generated when overused. + +--- + +## Indicating Contrast + +- However,... +- But,... +- That said,... +- On the flip side,... +- In contrast,... +- Unlike X, Y... +- While X is true, Y... +- Despite this,... + +--- + +## Indicating Similarity + +- Similarly,... +- Likewise,... +- In the same way,... +- Just like X, Y also... +- This mirrors... +- The same applies to... + +--- + +## Indicating Cause and Effect + +- So,... +- This means... +- As a result,... +- That's why... +- Because of this,... +- This leads to... +- The outcome?... +- Here's what happens:... + +--- + +## Giving Examples + +- For example,... +- For instance,... +- Here's an example:... +- Take X, for instance. +- Consider this:... +- A good example is... +- To illustrate,... +- Like when... +- Say you want to... + +--- + +## Emphasising Key Points + +- Here's the key takeaway:... +- The important thing is... +- What matters most is... +- Don't miss this:... +- Pay attention to... +- This is critical:... +- The bottom line?... + +--- + +## Providing Evidence + +Use when citing sources, data, or expert opinions: + +### Neutral attribution +- According to [Source],... +- [Source] reports that... +- Research shows that... +- Data from [Source] indicates... +- A study by [Source] found... + +### Expert quotes +- As [Expert] puts it,... +- [Expert] explains,... +- In the words of [Expert],... +- [Expert] notes that... + +### Supporting claims +- This is backed by... +- Evidence suggests... +- The numbers confirm... +- This aligns with findings from... + +--- + +## Summarising Sections + +- To recap,... +- Here's the short version:... +- In short,... +- The takeaway?... +- So what does this mean?... +- Let's pull this together:... +- Quick summary:... + +--- + +## Concluding Content + +- Wrapping up,... +- The bottom line is... +- Here's what to do next:... +- To sum up,... +- Final thoughts:... +- Ready to get started?... +- Now it's your turn. + +**Note:** Avoid "In conclusion" at the start of a paragraph. It's overused and signals AI writing. + +--- + +## Question-Based Transitions + +Useful for conversational tone and featured snippet optimization: + +- So what does this mean for you? +- But why does this matter? +- How do you actually do this? +- What's the catch? +- Sound complicated? It's not. +- Wondering where to start? +- Still not sure? Here's the breakdown. + +--- + +## List Introductions + +For numbered lists and step-by-step content: + +- Here's how to do it: +- Follow these steps: +- The process is straightforward: +- Here's what you need to know: +- Key things to consider: +- The main factors are: + +--- + +## Hedging Language + +For claims that need qualification or aren't absolute: + +- may, might, could +- tends to, generally +- often, usually, typically +- in most cases +- it appears that +- evidence suggests +- this can help +- many experts believe + +--- + +## Best Practice Guidelines + +1. **Match tone to audience**: B2B content can be slightly more formal; B2C often benefits from conversational transitions +2. **Vary your transitions**: Repeating the same phrase gets noticed (and not in a good way) +3. **Don't over-signpost**: Trust your reader; every sentence doesn't need a transition +4. **Use for scannability**: Transitions at paragraph starts help skimmers navigate +5. **Keep it natural**: Read aloud; if it sounds forced, simplify +6. **Front-load key info**: Put the important word or phrase early in the transition + +--- + +## Transitions to Avoid (AI Tells) + +These phrases are overused in AI-generated content: + +- "That being said,..." +- "It's worth noting that..." +- "At its core,..." +- "In today's digital landscape,..." +- "When it comes to the realm of..." +- "This begs the question..." +- "Let's delve into..." + +See the seo-audit skill's `references/ai-writing-detection.md` for a complete list of AI writing tells. diff --git a/.agents/skills/email-sequence/SKILL.md b/.agents/skills/email-sequence/SKILL.md new file mode 100644 index 00000000..9fd021cf --- /dev/null +++ b/.agents/skills/email-sequence/SKILL.md @@ -0,0 +1,309 @@ +--- +name: email-sequence +description: When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions "email sequence," "drip campaign," "nurture sequence," "onboarding emails," "welcome sequence," "re-engagement emails," "email automation," or "lifecycle emails." For in-app onboarding, see onboarding-cro. +metadata: + version: 1.1.0 +--- + +# Email Sequence Design + +You are an expert in email marketing and automation. Your goal is to create email sequences that nurture relationships, drive action, and move people toward conversion. + +## Initial Assessment + +**Check for product marketing context first:** +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 a sequence, understand: + +1. **Sequence Type** + - Welcome/onboarding sequence + - Lead nurture sequence + - Re-engagement sequence + - Post-purchase sequence + - Event-based sequence + - Educational sequence + - Sales sequence + +2. **Audience Context** + - Who are they? + - What triggered them into this sequence? + - What do they already know/believe? + - What's their current relationship with you? + +3. **Goals** + - Primary conversion goal + - Relationship-building goals + - Segmentation goals + - What defines success? + +--- + +## Core Principles + +### 1. One Email, One Job +- Each email has one primary purpose +- One main CTA per email +- Don't try to do everything + +### 2. Value Before Ask +- Lead with usefulness +- Build trust through content +- Earn the right to sell + +### 3. Relevance Over Volume +- Fewer, better emails win +- Segment for relevance +- Quality > frequency + +### 4. Clear Path Forward +- Every email moves them somewhere +- Links should do something useful +- Make next steps obvious + +--- + +## Email Sequence Strategy + +### Sequence Length +- Welcome: 3-7 emails +- Lead nurture: 5-10 emails +- Onboarding: 5-10 emails +- Re-engagement: 3-5 emails + +Depends on: +- Sales cycle length +- Product complexity +- Relationship stage + +### Timing/Delays +- Welcome email: Immediately +- Early sequence: 1-2 days apart +- Nurture: 2-4 days apart +- Long-term: Weekly or bi-weekly + +Consider: +- B2B: Avoid weekends +- B2C: Test weekends +- Time zones: Send at local time + +### Subject Line Strategy +- Clear > Clever +- Specific > Vague +- Benefit or curiosity-driven +- 40-60 characters ideal +- Test emoji (they're polarizing) + +**Patterns that work:** +- Question: "Still struggling with X?" +- How-to: "How to [achieve outcome] in [timeframe]" +- Number: "3 ways to [benefit]" +- Direct: "[First name], your [thing] is ready" +- Story tease: "The mistake I made with [topic]" + +### Preview Text +- Extends the subject line +- ~90-140 characters +- Don't repeat subject line +- Complete the thought or add intrigue + +--- + +## Sequence Types Overview + +### Welcome Sequence (Post-Signup) +**Length**: 5-7 emails over 12-14 days +**Goal**: Activate, build trust, convert + +Key emails: +1. Welcome + deliver promised value (immediate) +2. Quick win (day 1-2) +3. Story/Why (day 3-4) +4. Social proof (day 5-6) +5. Overcome objection (day 7-8) +6. Core feature highlight (day 9-11) +7. Conversion (day 12-14) + +### Lead Nurture Sequence (Pre-Sale) +**Length**: 6-8 emails over 2-3 weeks +**Goal**: Build trust, demonstrate expertise, convert + +Key emails: +1. Deliver lead magnet + intro (immediate) +2. Expand on topic (day 2-3) +3. Problem deep-dive (day 4-5) +4. Solution framework (day 6-8) +5. Case study (day 9-11) +6. Differentiation (day 12-14) +7. Objection handler (day 15-18) +8. Direct offer (day 19-21) + +### Re-Engagement Sequence +**Length**: 3-4 emails over 2 weeks +**Trigger**: 30-60 days of inactivity +**Goal**: Win back or clean list + +Key emails: +1. Check-in (genuine concern) +2. Value reminder (what's new) +3. Incentive (special offer) +4. Last chance (stay or unsubscribe) + +### Onboarding Sequence (Product Users) +**Length**: 5-7 emails over 14 days +**Goal**: Activate, drive to aha moment, upgrade +**Note**: Coordinate with in-app onboarding—email supports, doesn't duplicate + +Key emails: +1. Welcome + first step (immediate) +2. Getting started help (day 1) +3. Feature highlight (day 2-3) +4. Success story (day 4-5) +5. Check-in (day 7) +6. Advanced tip (day 10-12) +7. Upgrade/expand (day 14+) + +**For detailed templates**: See [references/sequence-templates.md](references/sequence-templates.md) + +--- + +## Email Types by Category + +### Onboarding Emails +- New users series +- New customers series +- Key onboarding step reminders +- New user invites + +### Retention Emails +- Upgrade to paid +- Upgrade to higher plan +- Ask for review +- Proactive support offers +- Product usage reports +- NPS survey +- Referral program + +### Billing Emails +- Switch to annual +- Failed payment recovery +- Cancellation survey +- Upcoming renewal reminders + +### Usage Emails +- Daily/weekly/monthly summaries +- Key event notifications +- Milestone celebrations + +### Win-Back Emails +- Expired trials +- Cancelled customers + +### Campaign Emails +- Monthly roundup / newsletter +- Seasonal promotions +- Product updates +- Industry news roundup +- Pricing updates + +**For detailed email type reference**: See [references/email-types.md](references/email-types.md) + +--- + +## Email Copy Guidelines + +### Structure +1. **Hook**: First line grabs attention +2. **Context**: Why this matters to them +3. **Value**: The useful content +4. **CTA**: What to do next +5. **Sign-off**: Human, warm close + +### Formatting +- Short paragraphs (1-3 sentences) +- White space between sections +- Bullet points for scanability +- Bold for emphasis (sparingly) +- Mobile-first (most read on phone) + +### Tone +- Conversational, not formal +- First-person (I/we) and second-person (you) +- Active voice +- Read it out loud—does it sound human? + +### Length +- 50-125 words for transactional +- 150-300 words for educational +- 300-500 words for story-driven + +### CTA Guidelines +- Buttons for primary actions +- Links for secondary actions +- One clear primary CTA per email +- Button text: Action + outcome + +**For detailed copy, personalization, and testing guidelines**: See [references/copy-guidelines.md](references/copy-guidelines.md) + +--- + +## Output Format + +### Sequence Overview +``` +Sequence Name: [Name] +Trigger: [What starts the sequence] +Goal: [Primary conversion goal] +Length: [Number of emails] +Timing: [Delay between emails] +Exit Conditions: [When they leave the sequence] +``` + +### For Each Email +``` +Email [#]: [Name/Purpose] +Send: [Timing] +Subject: [Subject line] +Preview: [Preview text] +Body: [Full copy] +CTA: [Button text] → [Link destination] +Segment/Conditions: [If applicable] +``` + +### Metrics Plan +What to measure and benchmarks + +--- + +## Task-Specific Questions + +1. What triggers entry to this sequence? +2. What's the primary goal/conversion action? +3. What do they already know about you? +4. What other emails are they receiving? +5. What's your current email performance? + +--- + +## Tool Integrations + +For implementation, see the [tools registry](../../tools/REGISTRY.md). Key email tools: + +| Tool | Best For | MCP | Guide | +|------|----------|:---:|-------| +| **Customer.io** | Behavior-based automation | - | [customer-io.md](../../tools/integrations/customer-io.md) | +| **Mailchimp** | SMB email marketing | ✓ | [mailchimp.md](../../tools/integrations/mailchimp.md) | +| **Resend** | Developer-friendly transactional | ✓ | [resend.md](../../tools/integrations/resend.md) | +| **SendGrid** | Transactional email at scale | - | [sendgrid.md](../../tools/integrations/sendgrid.md) | +| **Kit** | Creator/newsletter focused | - | [kit.md](../../tools/integrations/kit.md) | + +--- + +## Related Skills + +- **churn-prevention**: For cancel flows, save offers, and dunning strategy (email supports this) +- **onboarding-cro**: For in-app onboarding (email supports this) +- **copywriting**: For landing pages emails link to +- **ab-test-setup**: For testing email elements +- **popup-cro**: For email capture popups +- **revops**: For lifecycle stages that trigger email sequences diff --git a/.agents/skills/email-sequence/references/copy-guidelines.md b/.agents/skills/email-sequence/references/copy-guidelines.md new file mode 100644 index 00000000..6e31f2b5 --- /dev/null +++ b/.agents/skills/email-sequence/references/copy-guidelines.md @@ -0,0 +1,113 @@ +# Email Copy Guidelines + +## Contents +- Structure +- Formatting +- Tone +- Length +- CTA Buttons vs. Links +- Personalization (merge fields, dynamic content, triggered emails) +- Segmentation Strategies (by behavior, by stage, by profile) +- Testing and Optimization (what to test, how to test, metrics to track) + +## Structure + +1. **Hook**: First line grabs attention +2. **Context**: Why this matters to them +3. **Value**: The useful content +4. **CTA**: What to do next +5. **Sign-off**: Human, warm close + +## Formatting + +- Short paragraphs (1-3 sentences) +- White space between sections +- Bullet points for scanability +- Bold for emphasis (sparingly) +- Mobile-first (most read on phone) + +## Tone + +- Conversational, not formal +- First-person (I/we) and second-person (you) +- Active voice +- Match your brand but lean friendly +- Read it out loud—does it sound human? + +## Length + +- Shorter is usually better +- 50-125 words for transactional +- 150-300 words for educational +- 300-500 words for story-driven +- If it's long, it better be good + +## CTA Buttons vs. Links + +- Buttons: Primary actions, high-visibility +- Links: Secondary actions, in-text +- One clear primary CTA per email +- Button text: Action + outcome + +--- + +## Personalization + +### Merge Fields +- First name (fallback to "there" or "friend") +- Company name (B2B) +- Relevant data (usage, plan, etc.) + +### Dynamic Content +- Based on segment +- Based on behavior +- Based on stage + +### Triggered Emails +- Action-based sends +- More relevant than time-based +- Examples: Feature used, milestone hit, inactivity + +--- + +## Segmentation Strategies + +### By Behavior +- Openers vs. non-openers +- Clickers vs. non-clickers +- Active vs. inactive + +### By Stage +- Trial vs. paid +- New vs. long-term +- Engaged vs. at-risk + +### By Profile +- Industry/role (B2B) +- Use case / goal +- Company size + +--- + +## Testing and Optimization + +### What to Test +- Subject lines (highest impact) +- Send times +- Email length +- CTA placement and copy +- Personalization level +- Sequence timing + +### How to Test +- A/B test one variable at a time +- Sufficient sample size +- Statistical significance +- Document learnings + +### Metrics to Track +- Open rate (benchmark: 20-40%) +- Click rate (benchmark: 2-5%) +- Unsubscribe rate (keep under 0.5%) +- Conversion rate (specific to sequence goal) +- Revenue per email (if applicable) diff --git a/.agents/skills/email-sequence/references/email-types.md b/.agents/skills/email-sequence/references/email-types.md new file mode 100644 index 00000000..dd612405 --- /dev/null +++ b/.agents/skills/email-sequence/references/email-types.md @@ -0,0 +1,515 @@ +# Email Types Reference + +A comprehensive guide to lifecycle and campaign emails. Use this as an audit checklist and implementation reference. + +## Contents +- Onboarding Emails (new users series, new customers series, key onboarding step reminder, new user invite) +- Retention Emails (upgrade to paid, upgrade to higher plan, ask for review, offer support proactively, product usage report, NPS survey, referral program) +- Billing Emails (switch to annual, failed payment recovery, cancellation survey, upcoming renewal reminder) +- Usage Emails (daily/weekly/monthly summary, key event or milestone notifications) +- Win-Back Emails (expired trials, cancelled customers) +- Campaign Emails (monthly roundup/newsletter, seasonal promotions, product updates, industry news roundup, pricing update) +- Email Audit Checklist (onboarding, retention, billing, usage, win-back, campaigns) + +## Onboarding Emails + +### New Users Series +**Trigger**: User signs up (free or trial) +**Goal**: Activate user, drive to aha moment +**Typical sequence**: 5-7 emails over 14 days + +- Email 1: Welcome + single next step (immediate) +- Email 2: Quick win / getting started (day 1) +- Email 3: Key feature highlight (day 3) +- Email 4: Success story / social proof (day 5) +- Email 5: Check-in + offer help (day 7) +- Email 6: Advanced tip (day 10) +- Email 7: Upgrade prompt or next milestone (day 14) + +**Key metrics**: Activation rate, feature adoption + +--- + +### New Customers Series +**Trigger**: User converts to paid +**Goal**: Reinforce purchase decision, drive adoption, reduce early churn +**Typical sequence**: 3-5 emails over 14 days + +- Email 1: Thank you + what's next (immediate) +- Email 2: Getting full value — setup checklist (day 2) +- Email 3: Pro tips for paid features (day 5) +- Email 4: Success story from similar customer (day 7) +- Email 5: Check-in + introduce support resources (day 14) + +**Key point**: Different from new user series—they've committed. Focus on reinforcement and expansion, not conversion. + +--- + +### Key Onboarding Step Reminder +**Trigger**: User hasn't completed critical setup step after X time +**Goal**: Nudge completion of high-value action +**Format**: Single email or 2-3 email mini-sequence + +**Example triggers**: +- Hasn't connected integration after 48 hours +- Hasn't invited team member after 3 days +- Hasn't completed profile after 24 hours + +**Copy approach**: +- Remind them what they started +- Explain why this step matters +- Make it easy (direct link to complete) +- Offer help if stuck + +--- + +### New User Invite +**Trigger**: Existing user invites teammate +**Goal**: Activate the invited user +**Recipient**: The person being invited + +- Email 1: You've been invited (immediate) +- Email 2: Reminder if not accepted (day 2) +- Email 3: Final reminder (day 5) + +**Copy approach**: +- Personalize with inviter's name +- Explain what they're joining +- Single CTA to accept invite +- Social proof optional + +--- + +## Retention Emails + +### Upgrade to Paid +**Trigger**: Free user shows engagement, or trial ending +**Goal**: Convert free to paid +**Typical sequence**: 3-5 emails + +**Trigger options**: +- Time-based (trial day 10, 12, 14) +- Behavior-based (hit usage limit, used premium feature) +- Engagement-based (highly active free user) + +**Sequence structure**: +- Value summary: What they've accomplished +- Feature comparison: What they're missing +- Social proof: Who else upgraded +- Urgency: Trial ending, limited offer +- Final: Last chance + easy path + +--- + +### Upgrade to Higher Plan +**Trigger**: User approaching plan limits or using features available on higher tier +**Goal**: Upsell to next tier +**Format**: Single email or 2-3 email sequence + +**Trigger examples**: +- 80% of seat limit reached +- 90% of storage/usage limit +- Tried to use higher-tier feature +- Power user behavior patterns + +**Copy approach**: +- Acknowledge their growth (positive framing) +- Show what next tier unlocks +- Quantify value vs. cost +- Easy upgrade path + +--- + +### Ask for Review +**Trigger**: Customer milestone (30/60/90 days, key achievement, support resolution) +**Goal**: Generate social proof on G2, Capterra, app stores +**Format**: Single email + +**Best timing**: +- After positive support interaction +- After achieving measurable result +- After renewal +- NOT after billing issues or bugs + +**Copy approach**: +- Thank them for being a customer +- Mention specific value/milestone if possible +- Explain why reviews matter (help others decide) +- Direct link to review platform +- Keep it short—this is an ask + +--- + +### Offer Support Proactively +**Trigger**: Signs of struggle (drop in usage, failed actions, error encounters) +**Goal**: Save at-risk user, improve experience +**Format**: Single email + +**Trigger examples**: +- Usage dropped significantly week-over-week +- Multiple failed attempts at action +- Viewed help docs repeatedly +- Stuck at same onboarding step + +**Copy approach**: +- Genuine concern tone +- Specific: "I noticed you..." (if data allows) +- Offer direct help (not just link to docs) +- Personal from support or CSM +- No sales pitch—pure help + +--- + +### Product Usage Report +**Trigger**: Time-based (weekly, monthly, quarterly) +**Goal**: Demonstrate value, drive engagement, reduce churn +**Format**: Single email, recurring + +**What to include**: +- Key metrics/activity summary +- Comparison to previous period +- Achievements/milestones +- Suggestions for improvement +- Light CTA to explore more + +**Examples**: +- "You saved X hours this month" +- "Your team completed X projects" +- "You're in the top X% of users" + +**Key point**: Make them feel good and remind them of value delivered. + +--- + +### NPS Survey +**Trigger**: Time-based (quarterly) or event-based (post-milestone) +**Goal**: Measure satisfaction, identify promoters and detractors +**Format**: Single email + +**Best practices**: +- Keep it simple: Just the NPS question initially +- Follow-up form for "why" based on score +- Personal sender (CEO, founder, CSM) +- Tell them how you'll use feedback + +**Follow-up based on score**: +- Promoters (9-10): Thank + ask for review/referral +- Passives (7-8): Ask what would make it a 10 +- Detractors (0-6): Personal outreach to understand issues + +--- + +### Referral Program +**Trigger**: Customer milestone, promoter NPS score, or campaign +**Goal**: Generate referrals +**Format**: Single email or periodic reminders + +**Good timing**: +- After positive NPS response +- After customer achieves result +- After renewal +- Seasonal campaigns + +**Copy approach**: +- Remind them of their success +- Explain the referral offer clearly +- Make sharing easy (unique link) +- Show what's in it for them AND referee + +--- + +## Billing Emails + +### Switch to Annual +**Trigger**: Monthly subscriber at renewal time or campaign +**Goal**: Convert monthly to annual (improve LTV, reduce churn) +**Format**: Single email or 2-email sequence + +**Value proposition**: +- Calculate exact savings +- Additional benefits (if any) +- Lock in current price messaging +- Easy one-click switch + +**Best timing**: +- Around monthly renewal date +- End of year / new year +- After 3-6 months of loyalty +- Price increase announcement (lock in old rate) + +--- + +### Failed Payment Recovery +**Trigger**: Payment fails +**Goal**: Recover revenue, retain customer +**Typical sequence**: 3-4 emails over 7-14 days + +**Sequence structure**: +- Email 1 (Day 0): Friendly notice, update payment link +- Email 2 (Day 3): Reminder, service may be interrupted +- Email 3 (Day 7): Urgent, account will be suspended +- Email 4 (Day 10-14): Final notice, what they'll lose + +**Copy approach**: +- Assume it's an accident (card expired, etc.) +- Clear, direct, no guilt +- Single CTA to update payment +- Explain what happens if not resolved + +**Key metrics**: Recovery rate, time to recovery + +--- + +### Cancellation Survey +**Trigger**: User cancels subscription +**Goal**: Learn why, opportunity to save +**Format**: Single email (immediate) + +**Options**: +- In-app survey at cancellation (better completion) +- Follow-up email if they skip in-app +- Personal outreach for high-value accounts + +**Questions to ask**: +- Primary reason for cancelling +- What could we have done better +- Would anything change your mind +- Can we help with transition + +**Winback opportunity**: Based on reason, offer targeted save (discount, pause, downgrade, training). + +--- + +### Upcoming Renewal Reminder +**Trigger**: X days before renewal (14 or 30 days typical) +**Goal**: No surprise charges, opportunity to expand +**Format**: Single email + +**What to include**: +- Renewal date and amount +- What's included in renewal +- How to update payment/plan +- Changes to pricing/features (if any) +- Optional: Upsell opportunity + +**Required for**: Annual subscriptions, high-value contracts + +--- + +## Usage Emails + +### Daily/Weekly/Monthly Summary +**Trigger**: Time-based +**Goal**: Drive engagement, demonstrate value +**Format**: Single email, recurring + +**Content by frequency**: +- **Daily**: Notifications, quick stats (for high-engagement products) +- **Weekly**: Activity summary, highlights, suggestions +- **Monthly**: Comprehensive report, achievements, ROI if calculable + +**Structure**: +- Key metrics at a glance +- Notable achievements +- Activity breakdown +- Suggestions / what to try next +- CTA to dive deeper + +**Personalization**: Must be relevant to their actual usage. Empty reports are worse than no report. + +--- + +### Key Event or Milestone Notifications +**Trigger**: Specific achievement or event +**Goal**: Celebrate, drive continued engagement +**Format**: Single email per event + +**Milestone examples**: +- First [action] completed +- 10th/100th [thing] created +- Goal achieved +- Team collaboration milestone +- Usage streak + +**Copy approach**: +- Celebration tone +- Specific achievement +- Context (compared to others, compared to before) +- What's next / next milestone + +--- + +## Win-Back Emails + +### Expired Trials +**Trigger**: Trial ended without conversion +**Goal**: Convert or re-engage +**Typical sequence**: 3-4 emails over 30 days + +**Sequence structure**: +- Email 1 (Day 1 post-expiry): Trial ended, here's what you're missing +- Email 2 (Day 7): What held you back? (gather feedback) +- Email 3 (Day 14): Incentive offer (discount, extended trial) +- Email 4 (Day 30): Final reach-out, door is open + +**Segmentation**: Different approach based on trial engagement level: +- High engagement: Focus on removing friction to convert +- Low engagement: Offer fresh start, more onboarding help +- No engagement: Ask what happened, offer demo/call + +--- + +### Cancelled Customers +**Trigger**: Time after cancellation (30, 60, 90 days) +**Goal**: Win back churned customers +**Typical sequence**: 2-3 emails spread over 90 days + +**Sequence structure**: +- Email 1 (Day 30): What's new since you left +- Email 2 (Day 60): We've addressed [common reason] +- Email 3 (Day 90): Special offer to return + +**Copy approach**: +- No guilt, no desperation +- Genuine updates and improvements +- Personalize based on cancellation reason if known +- Make return easy + +**Key point**: They're more likely to return if their reason was addressed. + +--- + +## Campaign Emails + +### Monthly Roundup / Newsletter +**Trigger**: Time-based (monthly) +**Goal**: Engagement, brand presence, content distribution +**Format**: Single email, recurring + +**Content mix**: +- Product updates and tips +- Customer stories +- Educational content +- Company news +- Industry insights + +**Best practices**: +- Consistent send day/time +- Scannable format +- Mix of content types +- One primary CTA focus +- Unsubscribe is okay—keeps list healthy + +--- + +### Seasonal Promotions +**Trigger**: Calendar events (Black Friday, New Year, etc.) +**Goal**: Drive conversions with timely offer +**Format**: Campaign burst (2-4 emails) + +**Common opportunities**: +- New Year (fresh start, annual planning) +- End of fiscal year (budget spending) +- Black Friday / Cyber Monday +- Industry-specific seasons +- Back to school / work + +**Sequence structure**: +- Announcement: Offer reveal +- Reminder: Midway through promotion +- Last chance: Final hours + +--- + +### Product Updates +**Trigger**: New feature release +**Goal**: Adoption, engagement, demonstrate momentum +**Format**: Single email per major release + +**What to include**: +- What's new (clear and simple) +- Why it matters (benefit, not just feature) +- How to use it (direct link) +- Who asked for it (community acknowledgment) + +**Segmentation**: Consider targeting based on relevance: +- Users who would benefit most +- Users who requested feature +- Power users first (for beta feel) + +--- + +### Industry News Roundup +**Trigger**: Time-based (weekly or monthly) +**Goal**: Thought leadership, engagement, brand value +**Format**: Curated newsletter + +**Content**: +- Curated news and links +- Your take / commentary +- What it means for readers +- How your product helps + +**Best for**: B2B products where customers care about industry trends. + +--- + +### Pricing Update +**Trigger**: Price change announcement +**Goal**: Transparent communication, minimize churn +**Format**: Single email (or sequence for major changes) + +**Timeline**: +- Announce 30-60 days before change +- Reminder 14 days before +- Final notice 7 days before + +**Copy approach**: +- Clear, direct, transparent +- Explain the why (value delivered, costs increased) +- Grandfather if possible (lock in old rate) +- Give options (annual lock-in, downgrade) + +**Important**: Honesty and advance notice build trust even when price increases. + +--- + +## Email Audit Checklist + +Use this to audit your current email program: + +### Onboarding +- [ ] New users series +- [ ] New customers series +- [ ] Key onboarding step reminders +- [ ] New user invite sequence + +### Retention +- [ ] Upgrade to paid sequence +- [ ] Upgrade to higher plan triggers +- [ ] Ask for review (timed properly) +- [ ] Proactive support outreach +- [ ] Product usage reports +- [ ] NPS survey +- [ ] Referral program emails + +### Billing +- [ ] Switch to annual campaign +- [ ] Failed payment recovery sequence +- [ ] Cancellation survey +- [ ] Upcoming renewal reminders + +### Usage +- [ ] Daily/weekly/monthly summaries +- [ ] Key event notifications +- [ ] Milestone celebrations + +### Win-Back +- [ ] Expired trial sequence +- [ ] Cancelled customer sequence + +### Campaigns +- [ ] Monthly roundup / newsletter +- [ ] Seasonal promotion calendar +- [ ] Product update announcements +- [ ] Pricing update communications diff --git a/.agents/skills/email-sequence/references/sequence-templates.md b/.agents/skills/email-sequence/references/sequence-templates.md new file mode 100644 index 00000000..791c7ecb --- /dev/null +++ b/.agents/skills/email-sequence/references/sequence-templates.md @@ -0,0 +1,168 @@ +# Email Sequence Templates + +Detailed templates for common email sequences. + +## Contents +- Welcome Sequence (Post-Signup) +- Lead Nurture Sequence (Pre-Sale) +- Re-Engagement Sequence +- Onboarding Sequence (Product Users) + +## Welcome Sequence (Post-Signup) + +**Email 1: Welcome (Immediate)** +- Subject: Welcome to [Product] — here's your first step +- Deliver what was promised (lead magnet, access, etc.) +- Single next action +- Set expectations for future emails + +**Email 2: Quick Win (Day 1-2)** +- Subject: Get your first [result] in 10 minutes +- Enable small success +- Build confidence +- Link to helpful resource + +**Email 3: Story/Why (Day 3-4)** +- Subject: Why we built [Product] +- Origin story or mission +- Connect emotionally +- Show you understand their problem + +**Email 4: Social Proof (Day 5-6)** +- Subject: How [Customer] achieved [Result] +- Case study or testimonial +- Relatable to their situation +- Soft CTA to explore + +**Email 5: Overcome Objection (Day 7-8)** +- Subject: "I don't have time for X" — sound familiar? +- Address common hesitation +- Reframe the obstacle +- Show easy path forward + +**Email 6: Core Feature (Day 9-11)** +- Subject: Have you tried [Feature] yet? +- Highlight underused capability +- Show clear benefit +- Direct CTA to try it + +**Email 7: Conversion (Day 12-14)** +- Subject: Ready to [upgrade/buy/commit]? +- Summarize value +- Clear offer +- Urgency if appropriate +- Risk reversal (guarantee, trial) + +--- + +## Lead Nurture Sequence (Pre-Sale) + +**Email 1: Deliver + Introduce (Immediate)** +- Deliver the lead magnet +- Brief intro to who you are +- Preview what's coming + +**Email 2: Expand on Topic (Day 2-3)** +- Related insight to lead magnet +- Establish expertise +- Light CTA to content + +**Email 3: Problem Deep-Dive (Day 4-5)** +- Articulate their problem deeply +- Show you understand +- Hint at solution + +**Email 4: Solution Framework (Day 6-8)** +- Your approach/methodology +- Educational, not salesy +- Builds toward your product + +**Email 5: Case Study (Day 9-11)** +- Real results from real customer +- Specific and relatable +- Soft CTA + +**Email 6: Differentiation (Day 12-14)** +- Why your approach is different +- Address alternatives +- Build preference + +**Email 7: Objection Handler (Day 15-18)** +- Common concern addressed +- FAQ or myth-busting +- Reduce friction + +**Email 8: Direct Offer (Day 19-21)** +- Clear pitch +- Strong value proposition +- Specific CTA +- Urgency if available + +--- + +## Re-Engagement Sequence + +**Email 1: Check-In (Day 30-60 of inactivity)** +- Subject: Is everything okay, [Name]? +- Genuine concern +- Ask what happened +- Easy win to re-engage + +**Email 2: Value Reminder (Day 2-3 after)** +- Subject: Remember when you [achieved X]? +- Remind of past value +- What's new since they left +- Quick CTA + +**Email 3: Incentive (Day 5-7 after)** +- Subject: We miss you — here's something special +- Offer if appropriate +- Limited time +- Clear CTA + +**Email 4: Last Chance (Day 10-14 after)** +- Subject: Should we stop emailing you? +- Honest and direct +- One-click to stay or go +- Clean the list if no response + +--- + +## Onboarding Sequence (Product Users) + +Coordinate with in-app onboarding. Email supports, doesn't duplicate. + +**Email 1: Welcome + First Step (Immediate)** +- Confirm signup +- One critical action +- Link directly to that action + +**Email 2: Getting Started Help (Day 1)** +- If they haven't completed step 1 +- Quick tip or video +- Support option + +**Email 3: Feature Highlight (Day 2-3)** +- Key feature they should know +- Specific use case +- In-app link + +**Email 4: Success Story (Day 4-5)** +- Customer who succeeded +- Relatable journey +- Motivational + +**Email 5: Check-In (Day 7)** +- How's it going? +- Ask for feedback +- Offer help + +**Email 6: Advanced Tip (Day 10-12)** +- Power feature +- For engaged users +- Level-up content + +**Email 7: Upgrade/Expand (Day 14+)** +- For trial users: conversion push +- For free users: upgrade prompt +- For paid: expansion opportunity diff --git a/.agents/skills/form-cro/SKILL.md b/.agents/skills/form-cro/SKILL.md new file mode 100644 index 00000000..81047f14 --- /dev/null +++ b/.agents/skills/form-cro/SKILL.md @@ -0,0 +1,429 @@ +--- +name: form-cro +description: When the user wants to optimize any form that is NOT signup/registration — including lead capture forms, contact forms, demo request forms, application forms, survey forms, or checkout forms. Also use when the user mentions "form optimization," "lead form conversions," "form friction," "form fields," "form completion rate," or "contact form." For signup/registration forms, see signup-flow-cro. For popups containing forms, see popup-cro. +metadata: + version: 1.1.0 +--- + +# Form CRO + +You are an expert in form optimization. Your goal is to maximize form completion rates while capturing the data that matters. + +## Initial Assessment + +**Check for product marketing context first:** +If `.agents/product-marketing-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, identify: + +1. **Form Type** + - Lead capture (gated content, newsletter) + - Contact form + - Demo/sales request + - Application form + - Survey/feedback + - Checkout form + - Quote request + +2. **Current State** + - How many fields? + - What's the current completion rate? + - Mobile vs. desktop split? + - Where do users abandon? + +3. **Business Context** + - What happens with form submissions? + - Which fields are actually used in follow-up? + - Are there compliance/legal requirements? + +--- + +## Core Principles + +### 1. Every Field Has a Cost +Each field reduces completion rate. Rule of thumb: +- 3 fields: Baseline +- 4-6 fields: 10-25% reduction +- 7+ fields: 25-50%+ reduction + +For each field, ask: +- Is this absolutely necessary before we can help them? +- Can we get this information another way? +- Can we ask this later? + +### 2. Value Must Exceed Effort +- Clear value proposition above form +- Make what they get obvious +- Reduce perceived effort (field count, labels) + +### 3. Reduce Cognitive Load +- One question per field +- Clear, conversational labels +- Logical grouping and order +- Smart defaults where possible + +--- + +## Field-by-Field Optimization + +### Email Field +- Single field, no confirmation +- Inline validation +- Typo detection (did you mean gmail.com?) +- Proper mobile keyboard + +### Name Fields +- Single "Name" vs. First/Last — test this +- Single field reduces friction +- Split needed only if personalization requires it + +### Phone Number +- Make optional if possible +- If required, explain why +- Auto-format as they type +- Country code handling + +### Company/Organization +- Auto-suggest for faster entry +- Enrichment after submission (Clearbit, etc.) +- Consider inferring from email domain + +### Job Title/Role +- Dropdown if categories matter +- Free text if wide variation +- Consider making optional + +### Message/Comments (Free Text) +- Make optional +- Reasonable character guidance +- Expand on focus + +### Dropdown Selects +- "Select one..." placeholder +- Searchable if many options +- Consider radio buttons if < 5 options +- "Other" option with text field + +### Checkboxes (Multi-select) +- Clear, parallel labels +- Reasonable number of options +- Consider "Select all that apply" instruction + +--- + +## Form Layout Optimization + +### Field Order +1. Start with easiest fields (name, email) +2. Build commitment before asking more +3. Sensitive fields last (phone, company size) +4. Logical grouping if many fields + +### Labels and Placeholders +- Labels: Always visible (not just placeholder) +- Placeholders: Examples, not labels +- Help text: Only when genuinely helpful + +**Good:** +``` +Email +[name@company.com] +``` + +**Bad:** +``` +[Enter your email address] ← Disappears on focus +``` + +### Visual Design +- Sufficient spacing between fields +- Clear visual hierarchy +- CTA button stands out +- Mobile-friendly tap targets (44px+) + +### Single Column vs. Multi-Column +- Single column: Higher completion, mobile-friendly +- Multi-column: Only for short related fields (First/Last name) +- When in doubt, single column + +--- + +## Multi-Step Forms + +### When to Use Multi-Step +- More than 5-6 fields +- Logically distinct sections +- Conditional paths based on answers +- Complex forms (applications, quotes) + +### Multi-Step Best Practices +- Progress indicator (step X of Y) +- Start with easy, end with sensitive +- One topic per step +- Allow back navigation +- Save progress (don't lose data on refresh) +- Clear indication of required vs. optional + +### Progressive Commitment Pattern +1. Low-friction start (just email) +2. More detail (name, company) +3. Qualifying questions +4. Contact preferences + +--- + +## Error Handling + +### Inline Validation +- Validate as they move to next field +- Don't validate too aggressively while typing +- Clear visual indicators (green check, red border) + +### Error Messages +- Specific to the problem +- Suggest how to fix +- Positioned near the field +- Don't clear their input + +**Good:** "Please enter a valid email address (e.g., name@company.com)" +**Bad:** "Invalid input" + +### On Submit +- Focus on first error field +- Summarize errors if multiple +- Preserve all entered data +- Don't clear form on error + +--- + +## Submit Button Optimization + +### Button Copy +Weak: "Submit" | "Send" +Strong: "[Action] + [What they get]" + +Examples: +- "Get My Free Quote" +- "Download the Guide" +- "Request Demo" +- "Send Message" +- "Start Free Trial" + +### Button Placement +- Immediately after last field +- Left-aligned with fields +- Sufficient size and contrast +- Mobile: Sticky or clearly visible + +### Post-Submit States +- Loading state (disable button, show spinner) +- Success confirmation (clear next steps) +- Error handling (clear message, focus on issue) + +--- + +## Trust and Friction Reduction + +### Near the Form +- Privacy statement: "We'll never share your info" +- Security badges if collecting sensitive data +- Testimonial or social proof +- Expected response time + +### Reducing Perceived Effort +- "Takes 30 seconds" +- Field count indicator +- Remove visual clutter +- Generous white space + +### Addressing Objections +- "No spam, unsubscribe anytime" +- "We won't share your number" +- "No credit card required" + +--- + +## Form Types: Specific Guidance + +### Lead Capture (Gated Content) +- Minimum viable fields (often just email) +- Clear value proposition for what they get +- Consider asking enrichment questions post-download +- Test email-only vs. email + name + +### Contact Form +- Essential: Email/Name + Message +- Phone optional +- Set response time expectations +- Offer alternatives (chat, phone) + +### Demo Request +- Name, Email, Company required +- Phone: Optional with "preferred contact" choice +- Use case/goal question helps personalize +- Calendar embed can increase show rate + +### Quote/Estimate Request +- Multi-step often works well +- Start with easy questions +- Technical details later +- Save progress for complex forms + +### Survey Forms +- Progress bar essential +- One question per screen for engagement +- Skip logic for relevance +- Consider incentive for completion + +--- + +## Mobile Optimization + +- Larger touch targets (44px minimum height) +- Appropriate keyboard types (email, tel, number) +- Autofill support +- Single column only +- Sticky submit button +- Minimal typing (dropdowns, buttons) + +--- + +## Measurement + +### Key Metrics +- **Form start rate**: Page views → Started form +- **Completion rate**: Started → Submitted +- **Field drop-off**: Which fields lose people +- **Error rate**: By field +- **Time to complete**: Total and by field +- **Mobile vs. desktop**: Completion by device + +### What to Track +- Form views +- First field focus +- Each field completion +- Errors by field +- Submit attempts +- Successful submissions + +--- + +## Output Format + +### Form Audit +For each issue: +- **Issue**: What's wrong +- **Impact**: Estimated effect on conversions +- **Fix**: Specific recommendation +- **Priority**: High/Medium/Low + +### Recommended Form Design +- **Required fields**: Justified list +- **Optional fields**: With rationale +- **Field order**: Recommended sequence +- **Copy**: Labels, placeholders, button +- **Error messages**: For each field +- **Layout**: Visual guidance + +### Test Hypotheses +Ideas to A/B test with expected outcomes + +--- + +## Experiment Ideas + +### Form Structure Experiments + +**Layout & Flow** +- Single-step form vs. multi-step with progress bar +- 1-column vs. 2-column field layout +- Form embedded on page vs. separate page +- Vertical vs. horizontal field alignment +- Form above fold vs. after content + +**Field Optimization** +- Reduce to minimum viable fields +- Add or remove phone number field +- Add or remove company/organization field +- Test required vs. optional field balance +- Use field enrichment to auto-fill known data +- Hide fields for returning/known visitors + +**Smart Forms** +- Add real-time validation for emails and phone numbers +- Progressive profiling (ask more over time) +- Conditional fields based on earlier answers +- Auto-suggest for company names + +--- + +### Copy & Design Experiments + +**Labels & Microcopy** +- Test field label clarity and length +- Placeholder text optimization +- Help text: show vs. hide vs. on-hover +- Error message tone (friendly vs. direct) + +**CTAs & Buttons** +- Button text variations ("Submit" vs. "Get My Quote" vs. specific action) +- Button color and size testing +- Button placement relative to fields + +**Trust Elements** +- Add privacy assurance near form +- Show trust badges next to submit +- Add testimonial near form +- Display expected response time + +--- + +### Form Type-Specific Experiments + +**Demo Request Forms** +- Test with/without phone number requirement +- Add "preferred contact method" choice +- Include "What's your biggest challenge?" question +- Test calendar embed vs. form submission + +**Lead Capture Forms** +- Email-only vs. email + name +- Test value proposition messaging above form +- Gated vs. ungated content strategies +- Post-submission enrichment questions + +**Contact Forms** +- Add department/topic routing dropdown +- Test with/without message field requirement +- Show alternative contact methods (chat, phone) +- Expected response time messaging + +--- + +### Mobile & UX Experiments + +- Larger touch targets for mobile +- Test appropriate keyboard types by field +- Sticky submit button on mobile +- Auto-focus first field on page load +- Test form container styling (card vs. minimal) + +--- + +## Task-Specific Questions + +1. What's your current form completion rate? +2. Do you have field-level analytics? +3. What happens with the data after submission? +4. Which fields are actually used in follow-up? +5. Are there compliance/legal requirements? +6. What's the mobile vs. desktop split? + +--- + +## Related Skills + +- **signup-flow-cro**: For account creation forms +- **popup-cro**: For forms inside popups/modals +- **page-cro**: For the page containing the form +- **ab-test-setup**: For testing form changes diff --git a/.agents/skills/free-tool-strategy/SKILL.md b/.agents/skills/free-tool-strategy/SKILL.md new file mode 100644 index 00000000..b143eac2 --- /dev/null +++ b/.agents/skills/free-tool-strategy/SKILL.md @@ -0,0 +1,178 @@ +--- +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," or "free resource." This skill bridges engineering and marketing — useful for founders and technical marketers. +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 diff --git a/.agents/skills/free-tool-strategy/references/tool-types.md b/.agents/skills/free-tool-strategy/references/tool-types.md new file mode 100644 index 00000000..65104ffb --- /dev/null +++ b/.agents/skills/free-tool-strategy/references/tool-types.md @@ -0,0 +1,217 @@ +# 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 diff --git a/.agents/skills/launch-strategy/SKILL.md b/.agents/skills/launch-strategy/SKILL.md new file mode 100644 index 00000000..38490b45 --- /dev/null +++ b/.agents/skills/launch-strategy/SKILL.md @@ -0,0 +1,353 @@ +--- +name: launch-strategy +description: "When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user mentions 'launch,' 'Product Hunt,' 'feature release,' 'announcement,' 'go-to-market,' 'beta launch,' 'early access,' 'waitlist,' or 'product update.' This skill covers phased launches, channel strategy, and ongoing launch momentum." +metadata: + version: 1.1.0 +--- + +# Launch Strategy + +You are an expert in SaaS product launches and feature announcements. Your goal is to help users plan launches that build momentum, capture attention, and convert interest into users. + +## Before Starting + +**Check for product marketing context first:** +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. + +--- + +## Core Philosophy + +The best companies don't just launch once—they launch again and again. Every new feature, improvement, and update is an opportunity to capture attention and engage your audience. + +A strong launch isn't about a single moment. It's about: +- Getting your product into users' hands early +- Learning from real feedback +- Making a splash at every stage +- Building momentum that compounds over time + +--- + +## The ORB Framework + +Structure your launch marketing across three channel types. Everything should ultimately lead back to owned channels. + +### Owned Channels +You own the channel (though not the audience). Direct access without algorithms or platform rules. + +**Examples:** +- Email list +- Blog +- Podcast +- Branded community (Slack, Discord) +- Website/product + +**Why they matter:** +- Get more effective over time +- No algorithm changes or pay-to-play +- Direct relationship with audience +- Compound value from content + +**Start with 1-2 based on audience:** +- Industry lacks quality content → Start a blog +- People want direct updates → Focus on email +- Engagement matters → Build a community + +**Example - Superhuman:** +Built demand through an invite-only waitlist and one-on-one onboarding sessions. Every new user got a 30-minute live demo. This created exclusivity, FOMO, and word-of-mouth—all through owned relationships. Years later, their original onboarding materials still drive engagement. + +### Rented Channels +Platforms that provide visibility but you don't control. Algorithms shift, rules change, pay-to-play increases. + +**Examples:** +- Social media (Twitter/X, LinkedIn, Instagram) +- App stores and marketplaces +- YouTube +- Reddit + +**How to use correctly:** +- Pick 1-2 platforms where your audience is active +- Use them to drive traffic to owned channels +- Don't rely on them as your only strategy + +**Example - Notion:** +Hacked virality through Twitter, YouTube, and Reddit where productivity enthusiasts were active. Encouraged community to share templates and workflows. But they funneled all visibility into owned assets—every viral post led to signups, then targeted email onboarding. + +**Platform-specific tactics:** +- Twitter/X: Threads that spark conversation → link to newsletter +- LinkedIn: High-value posts → lead to gated content or email signup +- Marketplaces (Shopify, Slack): Optimize listing → drive to site for more + +Rented channels give speed, not stability. Capture momentum by bringing users into your owned ecosystem. + +### Borrowed Channels +Tap into someone else's audience to shortcut the hardest part—getting noticed. + +**Examples:** +- Guest content (blog posts, podcast interviews, newsletter features) +- Collaborations (webinars, co-marketing, social takeovers) +- Speaking engagements (conferences, panels, virtual summits) +- Influencer partnerships + +**Be proactive, not passive:** +1. List industry leaders your audience follows +2. Pitch win-win collaborations +3. Use tools like SparkToro or Listen Notes to find audience overlap +4. Set up affiliate/referral incentives + +**Example - TRMNL:** +Sent a free e-ink display to YouTuber Snazzy Labs—not a paid sponsorship, just hoping he'd like it. He created an in-depth review that racked up 500K+ views and drove $500K+ in sales. They also set up an affiliate program for ongoing promotion. + +Borrowed channels give instant credibility, but only work if you convert borrowed attention into owned relationships. + +--- + +## Five-Phase Launch Approach + +Launching isn't a one-day event. It's a phased process that builds momentum. + +### Phase 1: Internal Launch +Gather initial feedback and iron out major issues before going public. + +**Actions:** +- Recruit early users one-on-one to test for free +- Collect feedback on usability gaps and missing features +- Ensure prototype is functional enough to demo (doesn't need to be production-ready) + +**Goal:** Validate core functionality with friendly users. + +### Phase 2: Alpha Launch +Put the product in front of external users in a controlled way. + +**Actions:** +- Create landing page with early access signup form +- Announce the product exists +- Invite users individually to start testing +- MVP should be working in production (even if still evolving) + +**Goal:** First external validation and initial waitlist building. + +### Phase 3: Beta Launch +Scale up early access while generating external buzz. + +**Actions:** +- Work through early access list (some free, some paid) +- Start marketing with teasers about problems you solve +- Recruit friends, investors, and influencers to test and share + +**Consider adding:** +- Coming soon landing page or waitlist +- "Beta" sticker in dashboard navigation +- Email invites to early access list +- Early access toggle in settings for experimental features + +**Goal:** Build buzz and refine product with broader feedback. + +### Phase 4: Early Access Launch +Shift from small-scale testing to controlled expansion. + +**Actions:** +- Leak product details: screenshots, feature GIFs, demos +- Gather quantitative usage data and qualitative feedback +- Run user research with engaged users (incentivize with credits) +- Optionally run product/market fit survey to refine messaging + +**Expansion options:** +- Option A: Throttle invites in batches (5-10% at a time) +- Option B: Invite all users at once under "early access" framing + +**Goal:** Validate at scale and prepare for full launch. + +### Phase 5: Full Launch +Open the floodgates. + +**Actions:** +- Open self-serve signups +- Start charging (if not already) +- Announce general availability across all channels + +**Launch touchpoints:** +- Customer emails +- In-app popups and product tours +- Website banner linking to launch assets +- "New" sticker in dashboard navigation +- Blog post announcement +- Social posts across platforms +- Product Hunt, BetaList, Hacker News, etc. + +**Goal:** Maximum visibility and conversion to paying users. + +--- + +## Product Hunt Launch Strategy + +Product Hunt can be powerful for reaching early adopters, but it's not magic—it requires preparation. + +### Pros +- Exposure to tech-savvy early adopter audience +- Credibility bump (especially if Product of the Day) +- Potential PR coverage and backlinks + +### Cons +- Very competitive to rank well +- Short-lived traffic spikes +- Requires significant pre-launch planning + +### How to Launch Successfully + +**Before launch day:** +1. Build relationships with influential supporters, content hubs, and communities +2. Optimize your listing: compelling tagline, polished visuals, short demo video +3. Study successful launches to identify what worked +4. Engage in relevant communities—provide value before pitching +5. Prepare your team for all-day engagement + +**On launch day:** +1. Treat it as an all-day event +2. Respond to every comment in real-time +3. Answer questions and spark discussions +4. Encourage your existing audience to engage +5. Direct traffic back to your site to capture signups + +**After launch day:** +1. Follow up with everyone who engaged +2. Convert Product Hunt traffic into owned relationships (email signups) +3. Continue momentum with post-launch content + +### Case Studies + +**SavvyCal** (Scheduling tool): +- Optimized landing page and onboarding before launch +- Built relationships with productivity/SaaS influencers in advance +- Responded to every comment on launch day +- Result: #2 Product of the Month + +**Reform** (Form builder): +- Studied successful launches and applied insights +- Crafted clear tagline, polished visuals, demo video +- Engaged in communities before launch (provided value first) +- Treated launch as all-day engagement event +- Directed traffic to capture signups +- Result: #1 Product of the Day + +--- + +## Post-Launch Product Marketing + +Your launch isn't over when the announcement goes live. Now comes adoption and retention work. + +### Immediate Post-Launch Actions + +**Educate new users:** +Set up automated onboarding email sequence introducing key features and use cases. + +**Reinforce the launch:** +Include announcement in your weekly/biweekly/monthly roundup email to catch people who missed it. + +**Differentiate against competitors:** +Publish comparison pages highlighting why you're the obvious choice. + +**Update web pages:** +Add dedicated sections about the new feature/product across your site. + +**Offer hands-on preview:** +Create no-code interactive demo (using tools like Navattic) so visitors can explore before signing up. + +### Keep Momentum Going +It's easier to build on existing momentum than start from scratch. Every touchpoint reinforces the launch. + +--- + +## Ongoing Launch Strategy + +Don't rely on a single launch event. Regular updates and feature rollouts sustain engagement. + +### How to Prioritize What to Announce + +Use this matrix to decide how much marketing each update deserves: + +**Major updates** (new features, product overhauls): +- Full campaign across multiple channels +- Blog post, email campaign, in-app messages, social media +- Maximize exposure + +**Medium updates** (new integrations, UI enhancements): +- Targeted announcement +- Email to relevant segments, in-app banner +- Don't need full fanfare + +**Minor updates** (bug fixes, small tweaks): +- Changelog and release notes +- Signal that product is improving +- Don't dominate marketing + +### Announcement Tactics + +**Space out releases:** +Instead of shipping everything at once, stagger announcements to maintain momentum. + +**Reuse high-performing tactics:** +If a previous announcement resonated, apply those insights to future updates. + +**Keep engaging:** +Continue using email, social, and in-app messaging to highlight improvements. + +**Signal active development:** +Even small changelog updates remind customers your product is evolving. This builds retention and word-of-mouth—customers feel confident you'll be around. + +--- + +## Launch Checklist + +### Pre-Launch +- [ ] Landing page with clear value proposition +- [ ] Email capture / waitlist signup +- [ ] Early access list built +- [ ] Owned channels established (email, blog, community) +- [ ] Rented channel presence (social profiles optimized) +- [ ] Borrowed channel opportunities identified (podcasts, influencers) +- [ ] Product Hunt listing prepared (if using) +- [ ] Launch assets created (screenshots, demo video, GIFs) +- [ ] Onboarding flow ready +- [ ] Analytics/tracking in place + +### Launch Day +- [ ] Announcement email to list +- [ ] Blog post published +- [ ] Social posts scheduled and posted +- [ ] Product Hunt listing live (if using) +- [ ] In-app announcement for existing users +- [ ] Website banner/notification active +- [ ] Team ready to engage and respond +- [ ] Monitor for issues and feedback + +### Post-Launch +- [ ] Onboarding email sequence active +- [ ] Follow-up with engaged prospects +- [ ] Roundup email includes announcement +- [ ] Comparison pages published +- [ ] Interactive demo created +- [ ] Gather and act on feedback +- [ ] Plan next launch moment + +--- + +## Task-Specific Questions + +1. What are you launching? (New product, major feature, minor update) +2. What's your current audience size and engagement? +3. What owned channels do you have? (Email list size, blog traffic, community) +4. What's your timeline for launch? +5. Have you launched before? What worked/didn't work? +6. Are you considering Product Hunt? What's your preparation status? + +--- + +## Related Skills + +- **marketing-ideas**: For additional launch tactics (#22 Product Hunt, #23 Early Access Referrals) +- **email-sequence**: For launch and onboarding email sequences +- **page-cro**: For optimizing launch landing pages +- **marketing-psychology**: For psychology behind waitlists and exclusivity +- **programmatic-seo**: For comparison pages mentioned in post-launch +- **sales-enablement**: For launch sales collateral and enablement materials diff --git a/.agents/skills/marketing-ideas/SKILL.md b/.agents/skills/marketing-ideas/SKILL.md new file mode 100644 index 00000000..00e98ce8 --- /dev/null +++ b/.agents/skills/marketing-ideas/SKILL.md @@ -0,0 +1,167 @@ +--- +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,' or 'ideas to grow.' This skill provides 139 proven marketing approaches organized by category." +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) diff --git a/.agents/skills/marketing-ideas/references/ideas-by-category.md b/.agents/skills/marketing-ideas/references/ideas-by-category.md new file mode 100644 index 00000000..3819a9c4 --- /dev/null +++ b/.agents/skills/marketing-ideas/references/ideas-by-category.md @@ -0,0 +1,366 @@ +# 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. diff --git a/.agents/skills/marketing-psychology/SKILL.md b/.agents/skills/marketing-psychology/SKILL.md new file mode 100644 index 00000000..c0890240 --- /dev/null +++ b/.agents/skills/marketing-psychology/SKILL.md @@ -0,0 +1,455 @@ +--- +name: marketing-psychology +description: "When the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when the user mentions 'psychology,' 'mental models,' 'cognitive bias,' 'persuasion,' 'behavioral science,' 'why people buy,' 'decision-making,' or 'consumer behavior.' This skill provides 70+ mental models organized for marketing application." +metadata: + version: 1.1.0 +--- + +# Marketing Psychology & Mental Models + +You are an expert in applying psychological principles and mental models to marketing. Your goal is to help users understand why people buy, how to influence behavior ethically, and how to make better marketing decisions. + +## How to Use This Skill + +**Check for product marketing context first:** +If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before applying mental models. Use that context to tailor recommendations to the specific product and audience. + +Mental models are thinking tools that help you make better decisions, understand customer behavior, and create more effective marketing. When helping users: + +1. Identify which mental models apply to their situation +2. Explain the psychology behind the model +3. Provide specific marketing applications +4. Suggest how to implement ethically + +--- + +## Foundational Thinking Models + +These models sharpen your strategy and help you solve the right problems. + +### First Principles +Break problems down to basic truths and build solutions from there. Instead of copying competitors, ask "why" repeatedly to find root causes. Use the 5 Whys technique to tunnel down to what really matters. + +**Marketing application**: Don't assume you need content marketing because competitors do. Ask why you need it, what problem it solves, and whether there's a better solution. + +### Jobs to Be Done +People don't buy products—they "hire" them to get a job done. Focus on the outcome customers want, not features. + +**Marketing application**: A drill buyer doesn't want a drill—they want a hole. Frame your product around the job it accomplishes, not its specifications. + +### Circle of Competence +Know what you're good at and stay within it. Venture outside only with proper learning or expert help. + +**Marketing application**: Don't chase every channel. Double down where you have genuine expertise and competitive advantage. + +### Inversion +Instead of asking "How do I succeed?", ask "What would guarantee failure?" Then avoid those things. + +**Marketing application**: List everything that would make your campaign fail—confusing messaging, wrong audience, slow landing page—then systematically prevent each. + +### Occam's Razor +The simplest explanation is usually correct. Avoid overcomplicating strategies or attributing results to complex causes when simple ones suffice. + +**Marketing application**: If conversions dropped, check the obvious first (broken form, page speed) before assuming complex attribution issues. + +### Pareto Principle (80/20 Rule) +Roughly 80% of results come from 20% of efforts. Identify and focus on the vital few. + +**Marketing application**: Find the 20% of channels, customers, or content driving 80% of results. Cut or reduce the rest. + +### Local vs. Global Optima +A local optimum is the best solution nearby, but a global optimum is the best overall. Don't get stuck optimizing the wrong thing. + +**Marketing application**: Optimizing email subject lines (local) won't help if email isn't the right channel (global). Zoom out before zooming in. + +### Theory of Constraints +Every system has one bottleneck limiting throughput. Find and fix that constraint before optimizing elsewhere. + +**Marketing application**: If your funnel converts well but traffic is low, more conversion optimization won't help. Fix the traffic bottleneck first. + +### Opportunity Cost +Every choice has a cost—what you give up by not choosing alternatives. Consider what you're saying no to. + +**Marketing application**: Time spent on a low-ROI channel is time not spent on high-ROI activities. Always compare against alternatives. + +### Law of Diminishing Returns +After a point, additional investment yields progressively smaller gains. + +**Marketing application**: The 10th blog post won't have the same impact as the first. Know when to diversify rather than double down. + +### Second-Order Thinking +Consider not just immediate effects, but the effects of those effects. + +**Marketing application**: A flash sale boosts revenue (first order) but may train customers to wait for discounts (second order). + +### Map ≠ Territory +Models and data represent reality but aren't reality itself. Don't confuse your analytics dashboard with actual customer experience. + +**Marketing application**: Your customer persona is a useful model, but real customers are more complex. Stay in touch with actual users. + +### Probabilistic Thinking +Think in probabilities, not certainties. Estimate likelihoods and plan for multiple outcomes. + +**Marketing application**: Don't bet everything on one campaign. Spread risk and plan for scenarios where your primary strategy underperforms. + +### Barbell Strategy +Combine extreme safety with small high-risk/high-reward bets. Avoid the mediocre middle. + +**Marketing application**: Put 80% of budget into proven channels, 20% into experimental bets. Avoid moderate-risk, moderate-reward middle. + +--- + +## Understanding Buyers & Human Psychology + +These models explain how customers think, decide, and behave. + +### Fundamental Attribution Error +People attribute others' behavior to character, not circumstances. "They didn't buy because they're not serious" vs. "The checkout was confusing." + +**Marketing application**: When customers don't convert, examine your process before blaming them. The problem is usually situational, not personal. + +### Mere Exposure Effect +People prefer things they've seen before. Familiarity breeds liking. + +**Marketing application**: Consistent brand presence builds preference over time. Repetition across channels creates comfort and trust. + +### Availability Heuristic +People judge likelihood by how easily examples come to mind. Recent or vivid events seem more common. + +**Marketing application**: Case studies and testimonials make success feel more achievable. Make positive outcomes easy to imagine. + +### Confirmation Bias +People seek information confirming existing beliefs and ignore contradictory evidence. + +**Marketing application**: Understand what your audience already believes and align messaging accordingly. Fighting beliefs head-on rarely works. + +### The Lindy Effect +The longer something has survived, the longer it's likely to continue. Old ideas often outlast new ones. + +**Marketing application**: Proven marketing principles (clear value props, social proof) outlast trendy tactics. Don't abandon fundamentals for fads. + +### Mimetic Desire +People want things because others want them. Desire is socially contagious. + +**Marketing application**: Show that desirable people want your product. Waitlists, exclusivity, and social proof trigger mimetic desire. + +### Sunk Cost Fallacy +People continue investing in something because of past investment, even when it's no longer rational. + +**Marketing application**: Know when to kill underperforming campaigns. Past spend shouldn't justify future spend if results aren't there. + +### Endowment Effect +People value things more once they own them. + +**Marketing application**: Free trials, samples, and freemium models let customers "own" the product, making them reluctant to give it up. + +### IKEA Effect +People value things more when they've put effort into creating them. + +**Marketing application**: Let customers customize, configure, or build something. Their investment increases perceived value and commitment. + +### Zero-Price Effect +Free isn't just a low price—it's psychologically different. "Free" triggers irrational preference. + +**Marketing application**: Free tiers, free trials, and free shipping have disproportionate appeal. The jump from $1 to $0 is bigger than $2 to $1. + +### Hyperbolic Discounting / Present Bias +People strongly prefer immediate rewards over future ones, even when waiting is more rational. + +**Marketing application**: Emphasize immediate benefits ("Start saving time today") over future ones ("You'll see ROI in 6 months"). + +### Status-Quo Bias +People prefer the current state of affairs. Change requires effort and feels risky. + +**Marketing application**: Reduce friction to switch. Make the transition feel safe and easy. "Import your data in one click." + +### Default Effect +People tend to accept pre-selected options. Defaults are powerful. + +**Marketing application**: Pre-select the plan you want customers to choose. Opt-out beats opt-in for subscriptions (ethically applied). + +### Paradox of Choice +Too many options overwhelm and paralyze. Fewer choices often lead to more decisions. + +**Marketing application**: Limit options. Three pricing tiers beat seven. Recommend a single "best for most" option. + +### Goal-Gradient Effect +People accelerate effort as they approach a goal. Progress visualization motivates action. + +**Marketing application**: Show progress bars, completion percentages, and "almost there" messaging to drive completion. + +### Peak-End Rule +People judge experiences by the peak (best or worst moment) and the end, not the average. + +**Marketing application**: Design memorable peaks (surprise upgrades, delightful moments) and strong endings (thank you pages, follow-up emails). + +### Zeigarnik Effect +Unfinished tasks occupy the mind more than completed ones. Open loops create tension. + +**Marketing application**: "You're 80% done" creates pull to finish. Incomplete profiles, abandoned carts, and cliffhangers leverage this. + +### Pratfall Effect +Competent people become more likable when they show a small flaw. Perfection is less relatable. + +**Marketing application**: Admitting a weakness ("We're not the cheapest, but...") can increase trust and differentiation. + +### Curse of Knowledge +Once you know something, you can't imagine not knowing it. Experts struggle to explain simply. + +**Marketing application**: Your product seems obvious to you but confusing to newcomers. Test copy with people unfamiliar with your space. + +### Mental Accounting +People treat money differently based on its source or intended use, even though money is fungible. + +**Marketing application**: Frame costs in favorable mental accounts. "$3/day" feels different than "$90/month" even though it's the same. + +### Regret Aversion +People avoid actions that might cause regret, even if the expected outcome is positive. + +**Marketing application**: Address regret directly. Money-back guarantees, free trials, and "no commitment" messaging reduce regret fear. + +### Bandwagon Effect / Social Proof +People follow what others are doing. Popularity signals quality and safety. + +**Marketing application**: Show customer counts, testimonials, logos, reviews, and "trending" indicators. Numbers create confidence. + +--- + +## Influencing Behavior & Persuasion + +These models help you ethically influence customer decisions. + +### Reciprocity Principle +People feel obligated to return favors. Give first, and people want to give back. + +**Marketing application**: Free content, free tools, and generous free tiers create reciprocal obligation. Give value before asking for anything. + +### Commitment & Consistency +Once people commit to something, they want to stay consistent with that commitment. + +**Marketing application**: Get small commitments first (email signup, free trial). People who've taken one step are more likely to take the next. + +### Authority Bias +People defer to experts and authority figures. Credentials and expertise create trust. + +**Marketing application**: Feature expert endorsements, certifications, "featured in" logos, and thought leadership content. + +### Liking / Similarity Bias +People say yes to those they like and those similar to themselves. + +**Marketing application**: Use relatable spokespeople, founder stories, and community language. "Built by marketers for marketers" signals similarity. + +### Unity Principle +Shared identity drives influence. "One of us" is powerful. + +**Marketing application**: Position your brand as part of the customer's tribe. Use insider language and shared values. + +### Scarcity / Urgency Heuristic +Limited availability increases perceived value. Scarcity signals desirability. + +**Marketing application**: Limited-time offers, low-stock warnings, and exclusive access create urgency. Only use when genuine. + +### Foot-in-the-Door Technique +Start with a small request, then escalate. Compliance with small requests leads to compliance with larger ones. + +**Marketing application**: Free trial → paid plan → annual plan → enterprise. Each step builds on the last. + +### Door-in-the-Face Technique +Start with an unreasonably large request, then retreat to what you actually want. The contrast makes the second request seem reasonable. + +**Marketing application**: Show enterprise pricing first, then reveal the affordable starter plan. The contrast makes it feel like a deal. + +### Loss Aversion / Prospect Theory +Losses feel roughly twice as painful as equivalent gains feel good. People will work harder to avoid losing than to gain. + +**Marketing application**: Frame in terms of what they'll lose by not acting. "Don't miss out" beats "You could gain." + +### Anchoring Effect +The first number people see heavily influences subsequent judgments. + +**Marketing application**: Show the higher price first (original price, competitor price, enterprise tier) to anchor expectations. + +### Decoy Effect +Adding a third, inferior option makes one of the original two look better. + +**Marketing application**: A "decoy" pricing tier that's clearly worse value makes your preferred tier look like the obvious choice. + +### Framing Effect +How something is presented changes how it's perceived. Same facts, different frames. + +**Marketing application**: "90% success rate" vs. "10% failure rate" are identical but feel different. Frame positively. + +### Contrast Effect +Things seem different depending on what they're compared to. + +**Marketing application**: Show the "before" state clearly. The contrast with your "after" makes improvements vivid. + +--- + +## Pricing Psychology + +These models specifically address how people perceive and respond to prices. + +### Charm Pricing / Left-Digit Effect +Prices ending in 9 seem significantly lower than the next round number. $99 feels much cheaper than $100. + +**Marketing application**: Use .99 or .95 endings for value-focused products. The left digit dominates perception. + +### Rounded-Price (Fluency) Effect +Round numbers feel premium and are easier to process. $100 signals quality; $99 signals value. + +**Marketing application**: Use round prices for premium products ($500/month), charm prices for value products ($497/month). + +### Rule of 100 +For prices under $100, percentage discounts seem larger ("20% off"). For prices over $100, absolute discounts seem larger ("$50 off"). + +**Marketing application**: $80 product: "20% off" beats "$16 off." $500 product: "$100 off" beats "20% off." + +### Price Relativity / Good-Better-Best +People judge prices relative to options presented. A middle tier seems reasonable between cheap and expensive. + +**Marketing application**: Three tiers where the middle is your target. The expensive tier makes it look reasonable; the cheap tier provides an anchor. + +### Mental Accounting (Pricing) +Framing the same price differently changes perception. + +**Marketing application**: "$1/day" feels cheaper than "$30/month." "Less than your morning coffee" reframes the expense. + +--- + +## Design & Delivery Models + +These models help you design effective marketing systems. + +### Hick's Law +Decision time increases with the number and complexity of choices. More options = slower decisions = more abandonment. + +**Marketing application**: Simplify choices. One clear CTA beats three. Fewer form fields beat more. + +### AIDA Funnel +Attention → Interest → Desire → Action. The classic customer journey model. + +**Marketing application**: Structure pages and campaigns to move through each stage. Capture attention before building desire. + +### Rule of 7 +Prospects need roughly 7 touchpoints before converting. One ad rarely converts; sustained presence does. + +**Marketing application**: Build multi-touch campaigns across channels. Retargeting, email sequences, and consistent presence compound. + +### Nudge Theory / Choice Architecture +Small changes in how choices are presented significantly influence decisions. + +**Marketing application**: Default selections, strategic ordering, and friction reduction guide behavior without restricting choice. + +### BJ Fogg Behavior Model +Behavior = Motivation × Ability × Prompt. All three must be present for action. + +**Marketing application**: High motivation but hard to do = won't happen. Easy to do but no prompt = won't happen. Design for all three. + +### EAST Framework +Make desired behaviors: Easy, Attractive, Social, Timely. + +**Marketing application**: Reduce friction (easy), make it appealing (attractive), show others doing it (social), ask at the right moment (timely). + +### COM-B Model +Behavior requires: Capability, Opportunity, Motivation. + +**Marketing application**: Can they do it (capability)? Is the path clear (opportunity)? Do they want to (motivation)? Address all three. + +### Activation Energy +The initial energy required to start something. High activation energy prevents action even if the task is easy overall. + +**Marketing application**: Reduce starting friction. Pre-fill forms, offer templates, show quick wins. Make the first step trivially easy. + +### North Star Metric +One metric that best captures the value you deliver to customers. Focus creates alignment. + +**Marketing application**: Identify your North Star (active users, completed projects, revenue per customer) and align all efforts toward it. + +### The Cobra Effect +When incentives backfire and produce the opposite of intended results. + +**Marketing application**: Test incentive structures. A referral bonus might attract low-quality referrals gaming the system. + +--- + +## Growth & Scaling Models + +These models explain how marketing compounds and scales. + +### Feedback Loops +Output becomes input, creating cycles. Positive loops accelerate growth; negative loops create decline. + +**Marketing application**: Build virtuous cycles: more users → more content → better SEO → more users. Identify and strengthen positive loops. + +### Compounding +Small, consistent gains accumulate into large results over time. Early gains matter most. + +**Marketing application**: Consistent content, SEO, and brand building compound. Start early; benefits accumulate exponentially. + +### Network Effects +A product becomes more valuable as more people use it. + +**Marketing application**: Design features that improve with more users: shared workspaces, integrations, marketplaces, communities. + +### Flywheel Effect +Sustained effort creates momentum that eventually maintains itself. Hard to start, easy to maintain. + +**Marketing application**: Content → traffic → leads → customers → case studies → more content. Each element powers the next. + +### Switching Costs +The price (time, money, effort, data) of changing to a competitor. High switching costs create retention. + +**Marketing application**: Increase switching costs ethically: integrations, data accumulation, workflow customization, team adoption. + +### Exploration vs. Exploitation +Balance trying new things (exploration) with optimizing what works (exploitation). + +**Marketing application**: Don't abandon working channels for shiny new ones, but allocate some budget to experiments. + +### Critical Mass / Tipping Point +The threshold after which growth becomes self-sustaining. + +**Marketing application**: Focus resources on reaching critical mass in one segment before expanding. Depth before breadth. + +### Survivorship Bias +Focusing on successes while ignoring failures that aren't visible. + +**Marketing application**: Study failed campaigns, not just successful ones. The viral hit you're copying had 99 failures you didn't see. + +--- + +## Quick Reference + +When facing a marketing challenge, consider: + +| Challenge | Relevant Models | +|-----------|-----------------| +| Low conversions | Hick's Law, Activation Energy, BJ Fogg, Friction | +| Price objections | Anchoring, Framing, Mental Accounting, Loss Aversion | +| Building trust | Authority, Social Proof, Reciprocity, Pratfall Effect | +| Increasing urgency | Scarcity, Loss Aversion, Zeigarnik Effect | +| Retention/churn | Endowment Effect, Switching Costs, Status-Quo Bias | +| Growth stalling | Theory of Constraints, Local vs Global Optima, Compounding | +| Decision paralysis | Paradox of Choice, Default Effect, Nudge Theory | +| Onboarding | Goal-Gradient, IKEA Effect, Commitment & Consistency | + +--- + +## Task-Specific Questions + +1. What specific behavior are you trying to influence? +2. What does your customer believe before encountering your marketing? +3. Where in the journey (awareness → consideration → decision) is this? +4. What's currently preventing the desired action? +5. Have you tested this with real customers? + +--- + +## Related Skills + +- **page-cro**: Apply psychology to page optimization +- **copywriting**: Write copy using psychological principles +- **popup-cro**: Use triggers and psychology in popups +- **pricing-page optimization**: See page-cro for pricing psychology +- **ab-test-setup**: Test psychological hypotheses diff --git a/.agents/skills/page-cro/SKILL.md b/.agents/skills/page-cro/SKILL.md new file mode 100644 index 00000000..fe29e199 --- /dev/null +++ b/.agents/skills/page-cro/SKILL.md @@ -0,0 +1,182 @@ +--- +name: page-cro +description: When the user wants to optimize, improve, or increase conversions on any marketing page — including homepage, landing pages, pricing pages, feature pages, or blog posts. Also use when the user says "CRO," "conversion rate optimization," "this page isn't converting," "improve conversions," or "why isn't this page working." For signup/registration flows, see signup-flow-cro. For post-signup activation, see onboarding-cro. For forms outside of signup, see form-cro. For popups/modals, see popup-cro. +metadata: + version: 1.1.0 +--- + +# Page Conversion Rate Optimization (CRO) + +You are a conversion rate optimization expert. Your goal is to analyze marketing pages and provide actionable recommendations to improve conversion rates. + +## Initial Assessment + +**Check for product marketing context first:** +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, identify: + +1. **Page Type**: Homepage, landing page, pricing, feature, blog, about, other +2. **Primary Conversion Goal**: Sign up, request demo, purchase, subscribe, download, contact sales +3. **Traffic Context**: Where are visitors coming from? (organic, paid, email, social) + +--- + +## CRO Analysis Framework + +Analyze the page across these dimensions, in order of impact: + +### 1. Value Proposition Clarity (Highest Impact) + +**Check for:** +- Can a visitor understand what this is and why they should care within 5 seconds? +- Is the primary benefit clear, specific, and differentiated? +- Is it written in the customer's language (not company jargon)? + +**Common issues:** +- Feature-focused instead of benefit-focused +- Too vague or too clever (sacrificing clarity) +- Trying to say everything instead of the most important thing + +### 2. Headline Effectiveness + +**Evaluate:** +- Does it communicate the core value proposition? +- Is it specific enough to be meaningful? +- Does it match the traffic source's messaging? + +**Strong headline patterns:** +- Outcome-focused: "Get [desired outcome] without [pain point]" +- Specificity: Include numbers, timeframes, or concrete details +- Social proof: "Join 10,000+ teams who..." + +### 3. CTA Placement, Copy, and Hierarchy + +**Primary CTA assessment:** +- Is there one clear primary action? +- Is it visible without scrolling? +- Does the button copy communicate value, not just action? + - Weak: "Submit," "Sign Up," "Learn More" + - Strong: "Start Free Trial," "Get My Report," "See Pricing" + +**CTA hierarchy:** +- Is there a logical primary vs. secondary CTA structure? +- Are CTAs repeated at key decision points? + +### 4. Visual Hierarchy and Scannability + +**Check:** +- Can someone scanning get the main message? +- Are the most important elements visually prominent? +- Is there enough white space? +- Do images support or distract from the message? + +### 5. Trust Signals and Social Proof + +**Types to look for:** +- Customer logos (especially recognizable ones) +- Testimonials (specific, attributed, with photos) +- Case study snippets with real numbers +- Review scores and counts +- Security badges (where relevant) + +**Placement:** Near CTAs and after benefit claims + +### 6. Objection Handling + +**Common objections to address:** +- Price/value concerns +- "Will this work for my situation?" +- Implementation difficulty +- "What if it doesn't work?" + +**Address through:** FAQ sections, guarantees, comparison content, process transparency + +### 7. Friction Points + +**Look for:** +- Too many form fields +- Unclear next steps +- Confusing navigation +- Required information that shouldn't be required +- Mobile experience issues +- Long load times + +--- + +## Output Format + +Structure your recommendations as: + +### Quick Wins (Implement Now) +Easy changes with likely immediate impact. + +### High-Impact Changes (Prioritize) +Bigger changes that require more effort but will significantly improve conversions. + +### Test Ideas +Hypotheses worth A/B testing rather than assuming. + +### Copy Alternatives +For key elements (headlines, CTAs), provide 2-3 alternatives with rationale. + +--- + +## Page-Specific Frameworks + +### Homepage CRO +- Clear positioning for cold visitors +- Quick path to most common conversion +- Handle both "ready to buy" and "still researching" + +### Landing Page CRO +- Message match with traffic source +- Single CTA (remove navigation if possible) +- Complete argument on one page + +### Pricing Page CRO +- Clear plan comparison +- Recommended plan indication +- Address "which plan is right for me?" anxiety + +### Feature Page CRO +- Connect feature to benefit +- Use cases and examples +- Clear path to try/buy + +### Blog Post CRO +- Contextual CTAs matching content topic +- Inline CTAs at natural stopping points + +--- + +## Experiment Ideas + +When recommending experiments, consider tests for: +- Hero section (headline, visual, CTA) +- Trust signals and social proof placement +- Pricing presentation +- Form optimization +- Navigation and UX + +**For comprehensive experiment ideas by page type**: See [references/experiments.md](references/experiments.md) + +--- + +## Task-Specific Questions + +1. What's your current conversion rate and goal? +2. Where is traffic coming from? +3. What does your signup/purchase flow look like after this page? +4. Do you have user research, heatmaps, or session recordings? +5. What have you already tried? + +--- + +## Related Skills + +- **signup-flow-cro**: If the issue is in the signup process itself +- **form-cro**: If forms on the page need optimization +- **popup-cro**: If considering popups as part of the strategy +- **copywriting**: If the page needs a complete copy rewrite +- **ab-test-setup**: To properly test recommended changes diff --git a/.agents/skills/page-cro/references/experiments.md b/.agents/skills/page-cro/references/experiments.md new file mode 100644 index 00000000..abc31c71 --- /dev/null +++ b/.agents/skills/page-cro/references/experiments.md @@ -0,0 +1,248 @@ +# Page CRO Experiment Ideas + +Comprehensive list of A/B tests and experiments organized by page type. + +## Contents +- Homepage Experiments (Hero Section, Trust & Social Proof, Features & Content, Navigation & UX) +- Pricing Page Experiments (Price Presentation, Pricing UX, Objection Handling, Trust Signals) +- Demo Request Page Experiments (Form Optimization, Page Content, CTA & Routing) +- Resource/Blog Page Experiments (Content CTAs, Resource Section) +- Landing Page Experiments (Message Match, Conversion Focus, Page Length) +- Feature Page Experiments (Feature Presentation, Conversion Path) +- Cross-Page Experiments (Site-Wide Tests, Navigation Tests) + +## Homepage Experiments + +### Hero Section + +| Test | Hypothesis | +|------|------------| +| Headline variations | Specific vs. abstract messaging | +| Subheadline clarity | Add/refine to support headline | +| CTA above fold | Include or exclude prominent CTA | +| Hero visual format | Screenshot vs. GIF vs. illustration vs. video | +| CTA button color | Test contrast and visibility | +| CTA button text | "Start Free Trial" vs. "Get Started" vs. "See Demo" | +| Interactive demo | Engage visitors immediately with product | + +### Trust & Social Proof + +| Test | Hypothesis | +|------|------------| +| Logo placement | Hero section vs. below fold | +| Case study in hero | Show results immediately | +| Trust badges | Add security, compliance, awards | +| Social proof in headline | "Join 10,000+ teams" messaging | +| Testimonial placement | Above fold vs. dedicated section | +| Video testimonials | More engaging than text quotes | + +### Features & Content + +| Test | Hypothesis | +|------|------------| +| Feature presentation | Icons + descriptions vs. detailed sections | +| Section ordering | Move high-value features up | +| Secondary CTAs | Add/remove throughout page | +| Benefit vs. feature focus | Lead with outcomes | +| Comparison section | Show vs. competitors or status quo | + +### Navigation & UX + +| Test | Hypothesis | +|------|------------| +| Sticky navigation | Persistent nav with CTA | +| Nav menu order | High-priority items at edges | +| Nav CTA button | Add prominent button in nav | +| Support widget | Live chat vs. AI chatbot | +| Footer optimization | Clearer secondary conversions | +| Exit intent popup | Capture abandoning visitors | + +--- + +## Pricing Page Experiments + +### Price Presentation + +| Test | Hypothesis | +|------|------------| +| Annual vs. monthly display | Highlight savings or simplify | +| Price points | $99 vs. $100 vs. $97 psychology | +| "Most Popular" badge | Highlight target plan | +| Number of tiers | 3 vs. 4 vs. 2 visible options | +| Price anchoring | Order plans to anchor expectations | +| Custom enterprise tier | Show vs. "Contact Sales" | + +### Pricing UX + +| Test | Hypothesis | +|------|------------| +| Pricing calculator | For usage-based pricing clarity | +| Guided pricing flow | Multistep wizard vs. comparison table | +| Feature comparison format | Table vs. expandable sections | +| Monthly/annual toggle | With savings highlighted | +| Plan recommendation quiz | Help visitors choose | +| Checkout flow length | Steps required after plan selection | + +### Objection Handling + +| Test | Hypothesis | +|------|------------| +| FAQ section | Address pricing objections | +| ROI calculator | Demonstrate value vs. cost | +| Money-back guarantee | Prominent placement | +| Per-user breakdowns | Clarity for team plans | +| Feature inclusion clarity | What's in each tier | +| Competitor comparison | Side-by-side value comparison | + +### Trust Signals + +| Test | Hypothesis | +|------|------------| +| Value testimonials | Quotes about ROI specifically | +| Customer logos | Near pricing section | +| Review scores | G2/Capterra ratings | +| Case study snippet | Specific pricing/value results | + +--- + +## Demo Request Page Experiments + +### Form Optimization + +| Test | Hypothesis | +|------|------------| +| Field count | Fewer fields, higher completion | +| Multi-step vs. single | Progress bar encouragement | +| Form placement | Above fold vs. after content | +| Phone field | Include vs. exclude | +| Field enrichment | Hide fields you can auto-fill | +| Form labels | Inside field vs. above | + +### Page Content + +| Test | Hypothesis | +|------|------------| +| Benefits above form | Reinforce value before ask | +| Demo preview | Video/GIF showing demo experience | +| "What You'll Learn" | Set expectations clearly | +| Testimonials near form | Reduce friction at decision point | +| FAQ below form | Address common objections | +| Video vs. text | Format for explaining value | + +### CTA & Routing + +| Test | Hypothesis | +|------|------------| +| CTA text | "Book Your Demo" vs. "Schedule 15-Min Call" | +| On-demand option | Instant demo alongside live option | +| Personalized messaging | Based on visitor data/source | +| Navigation removal | Reduce page distractions | +| Calendar integration | Inline booking vs. external link | +| Qualification routing | Self-serve for some, sales for others | + +--- + +## Resource/Blog Page Experiments + +### Content CTAs + +| Test | Hypothesis | +|------|------------| +| Floating CTAs | Sticky CTA on blog posts | +| CTA placement | Inline vs. end-of-post only | +| Reading time display | Estimated reading time | +| Related resources | End-of-article recommendations | +| Gated vs. free | Content access strategy | +| Content upgrades | Specific to article topic | + +### Resource Section + +| Test | Hypothesis | +|------|------------| +| Navigation/filtering | Easier to find relevant content | +| Search functionality | Find specific resources | +| Featured resources | Highlight best content | +| Layout format | Grid vs. list view | +| Topic bundles | Grouped resources by theme | +| Download tracking | Gate some, track engagement | + +--- + +## Landing Page Experiments + +### Message Match + +| Test | Hypothesis | +|------|------------| +| Headline matching | Match ad copy exactly | +| Visual matching | Match ad creative | +| Offer alignment | Same offer as ad promised | +| Audience-specific pages | Different pages per segment | + +### Conversion Focus + +| Test | Hypothesis | +|------|------------| +| Navigation removal | Single-focus page | +| CTA repetition | Multiple CTAs throughout | +| Form vs. button | Direct capture vs. click-through | +| Urgency/scarcity | If genuine, test messaging | +| Social proof density | Amount and placement | +| Video inclusion | Explain offer with video | + +### Page Length + +| Test | Hypothesis | +|------|------------| +| Short vs. long | Quick conversion vs. complete argument | +| Above-fold only | Minimal scroll required | +| Section ordering | Most important content first | +| Footer removal | Eliminate navigation | + +--- + +## Feature Page Experiments + +### Feature Presentation + +| Test | Hypothesis | +|------|------------| +| Demo/screenshot | Show feature in action | +| Use case examples | How customers use it | +| Before/after | Impact visualization | +| Video walkthrough | Feature tour | +| Interactive demo | Try feature without signup | + +### Conversion Path + +| Test | Hypothesis | +|------|------------| +| Trial CTA | Feature-specific trial offer | +| Related features | Cross-link to other features | +| Comparison | vs. competitors' version | +| Pricing mention | Connect to relevant plan | +| Case study link | Feature-specific success story | + +--- + +## Cross-Page Experiments + +### Site-Wide Tests + +| Test | Hypothesis | +|------|------------| +| Chat widget | Impact on conversions | +| Cookie consent UX | Minimize friction | +| Page load speed | Performance vs. features | +| Mobile experience | Responsive optimization | +| Accessibility | Impact on conversion | +| Personalization | Dynamic content by segment | + +### Navigation Tests + +| Test | Hypothesis | +|------|------------| +| Menu structure | Information architecture | +| Search placement | Help visitors find content | +| CTA in nav | Always-visible conversion path | +| Breadcrumbs | Navigation clarity | diff --git a/.agents/skills/paid-ads/SKILL.md b/.agents/skills/paid-ads/SKILL.md new file mode 100644 index 00000000..64620c46 --- /dev/null +++ b/.agents/skills/paid-ads/SKILL.md @@ -0,0 +1,315 @@ +--- +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,' or 'audience targeting.' This skill covers campaign strategy, audience targeting, and optimization. For bulk ad creative generation and iteration, see ad-creative." +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**: Always exclude existing customers and recent converters + +**For detailed targeting strategies by platform**: See [references/audience-targeting.md](references/audience-targeting.md) + +--- + +## Creative Best Practices + +### Image Ads +- Clear product screenshots showing UI +- Before/after comparisons +- Stats and numbers as focal point +- Human faces (real, not stock) +- Bold, readable text overlay (keep under 20%) + +### Video Ads Structure (15-30 sec) +1. Hook (0-3 sec): Pattern interrupt, question, or bold statement +2. Problem (3-8 sec): Relatable pain point +3. Solution (8-20 sec): Show product/benefit +4. CTA (20-30 sec): Clear next step + +**Production tips:** +- Captions always (85% watch without sound) +- Vertical for Stories/Reels, square for feed +- Native feel outperforms polished +- First 3 seconds determine if they watch + +### Creative Testing Hierarchy +1. Concept/angle (biggest impact) +2. Hook/headline +3. Visual style +4. Body copy +5. CTA + +--- + +## Campaign Optimization + +### Key Metrics by Objective + +| Objective | Primary Metrics | +|-----------|-----------------| +| Awareness | CPM, Reach, Video view rate | +| Consideration | CTR, CPC, Time on site | +| Conversion | CPA, ROAS, Conversion rate | + +### Optimization Levers + +**If CPA is too high:** +1. Check landing page (is the problem post-click?) +2. Tighten audience targeting +3. Test new creative angles +4. Improve ad relevance/quality score +5. Adjust bid strategy + +**If CTR is low:** +- Creative isn't resonating → test new hooks/angles +- Audience mismatch → refine targeting +- Ad fatigue → refresh creative + +**If CPM is high:** +- Audience too narrow → expand targeting +- High competition → try different placements +- Low relevance score → improve creative fit + +### Bid Strategy Progression +1. Start with manual or cost caps +2. Gather conversion data (50+ conversions) +3. Switch to automated with targets based on historical data +4. Monitor and adjust targets based on results + +--- + +## Retargeting Strategies + +### Funnel-Based Approach + +| 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 diff --git a/.agents/skills/paid-ads/references/ad-copy-templates.md b/.agents/skills/paid-ads/references/ad-copy-templates.md new file mode 100644 index 00000000..04818406 --- /dev/null +++ b/.agents/skills/paid-ads/references/ad-copy-templates.md @@ -0,0 +1,207 @@ +# Ad Copy Templates Reference + +Detailed formulas and templates for writing high-converting ad copy. + +## Contents +- Primary Text Formulas (Problem-Agitate-Solve, Before-After-Bridge, Social Proof Lead, Feature-Benefit Bridge, Direct Response) +- Headline Formulas (For Search Ads, For Social Ads) +- CTA Variations (Soft CTAs, Hard CTAs, Urgency CTAs, Action-Oriented CTAs) +- Platform-Specific Copy Guidelines (Google Search Ads, Meta Ads, LinkedIn Ads) +- Copy Testing Priority + +## Primary Text Formulas + +### Problem-Agitate-Solve (PAS) + +``` +[Problem statement] +[Agitate the pain] +[Introduce solution] +[CTA] +``` + +**Example:** +> Spending hours on manual reporting every week? +> While you're buried in spreadsheets, your competitors are making decisions. +> [Product] automates your reports in minutes. +> Start your free trial → + +--- + +### Before-After-Bridge (BAB) + +``` +[Current painful state] +[Desired future state] +[Your product as the bridge] +``` + +**Example:** +> Before: Chasing down approvals across email, Slack, and spreadsheets. +> After: Every approval tracked, automated, and on time. +> [Product] connects your tools and keeps projects moving. + +--- + +### Social Proof Lead + +``` +[Impressive stat or testimonial] +[What you do] +[CTA] +``` + +**Example:** +> "We cut our reporting time by 75%." — Sarah K., Marketing Director +> [Product] automates the reports you hate building. +> See how it works → + +--- + +### Feature-Benefit Bridge + +``` +[Feature] +[So that...] +[Which means...] +``` + +**Example:** +> Real-time collaboration on documents +> So your team always works from the latest version +> Which means no more version confusion or lost work + +--- + +### Direct Response + +``` +[Bold claim/outcome] +[Proof point] +[CTA with urgency if genuine] +``` + +**Example:** +> Cut your reporting time by 80% +> Join 5,000+ marketing teams already using [Product] +> Start free → First month 50% off + +--- + +## Headline Formulas + +### For Search Ads + +| Formula | Example | +|---------|---------| +| [Keyword] + [Benefit] | "Project Management That Teams Actually Use" | +| [Action] + [Outcome] | "Automate Reports \| Save 10 Hours Weekly" | +| [Question] | "Tired of Manual Data Entry?" | +| [Number] + [Benefit] | "500+ Teams Trust [Product] for [Outcome]" | +| [Keyword] + [Differentiator] | "CRM Built for Small Teams" | +| [Price/Offer] + [Keyword] | "Free Project Management \| No Credit Card" | + +### For Social Ads + +| Type | Example | +|------|---------| +| Outcome hook | "How we 3x'd our conversion rate" | +| Curiosity hook | "The reporting hack no one talks about" | +| Contrarian hook | "Why we stopped using [common tool]" | +| Specificity hook | "The exact template we use for..." | +| Question hook | "What if you could cut your admin time in half?" | +| Number hook | "7 ways to improve your workflow today" | +| Story hook | "We almost gave up. Then we found..." | + +--- + +## CTA Variations + +### Soft CTAs (awareness/consideration) + +Best for: Top of funnel, cold audiences, complex products + +- Learn More +- See How It Works +- Watch Demo +- Get the Guide +- Explore Features +- See Examples +- Read the Case Study + +### Hard CTAs (conversion) + +Best for: Bottom of funnel, warm audiences, clear offers + +- Start Free Trial +- Get Started Free +- Book a Demo +- Claim Your Discount +- Buy Now +- Sign Up Free +- Get Instant Access + +### Urgency CTAs (use when genuine) + +Best for: Limited-time offers, scarcity situations + +- Limited Time: 30% Off +- Offer Ends [Date] +- Only X Spots Left +- Last Chance +- Early Bird Pricing Ends Soon + +### Action-Oriented CTAs + +Best for: Active voice, clear next step + +- Start Saving Time Today +- Get Your Free Report +- See Your Score +- Calculate Your ROI +- Build Your First Project + +--- + +## Platform-Specific Copy Guidelines + +### Google Search Ads + +- **Headline limits:** 30 characters each (up to 15 headlines) +- **Description limits:** 90 characters each (up to 4 descriptions) +- Include keywords naturally +- Use all available headline slots +- Include numbers and stats when possible +- Test dynamic keyword insertion + +### Meta Ads (Facebook/Instagram) + +- **Primary text:** 125 characters visible (can be longer, gets truncated) +- **Headline:** 40 characters recommended +- Front-load the hook (first line matters most) +- Emojis can work but test +- Questions perform well +- Keep image text under 20% + +### LinkedIn Ads + +- **Intro text:** 600 characters max (150 recommended) +- **Headline:** 200 characters max (70 recommended) +- Professional tone (but not boring) +- Specific job outcomes resonate +- Stats and social proof important +- Avoid consumer-style hype + +--- + +## Copy Testing Priority + +When testing ad copy, focus on these elements in order of impact: + +1. **Hook/angle** (biggest impact on performance) +2. **Headline** +3. **Primary benefit** +4. **CTA** +5. **Supporting proof points** + +Test one element at a time for clean data. diff --git a/.agents/skills/paid-ads/references/audience-targeting.md b/.agents/skills/paid-ads/references/audience-targeting.md new file mode 100644 index 00000000..00dc42bb --- /dev/null +++ b/.agents/skills/paid-ads/references/audience-targeting.md @@ -0,0 +1,243 @@ +# Audience Targeting Reference + +Detailed targeting strategies for each major ad platform. + +## Contents +- Google Ads Audiences (Search Campaign Targeting, Display/YouTube Targeting) +- Meta Audiences (Core Audiences, Custom Audiences, Lookalike Audiences) +- LinkedIn Audiences (Job-Based Targeting, Company-Based Targeting, High-Performing Combinations) +- Twitter/X Audiences +- TikTok Audiences +- Audience Size Guidelines +- Exclusion Strategy + +## Google Ads Audiences + +### Search Campaign Targeting + +**Keywords:** +- Exact match: [keyword] — most precise, lower volume +- Phrase match: "keyword" — moderate precision and volume +- Broad match: keyword — highest volume, use with smart bidding + +**Audience layering:** +- Add audiences in "observation" mode first +- Analyze performance by audience +- Switch to "targeting" mode for high performers + +**RLSA (Remarketing Lists for Search Ads):** +- Bid higher on past visitors searching your terms +- Show different ads to returning searchers +- Exclude converters from prospecting campaigns + +### Display/YouTube Targeting + +**Custom intent audiences:** +- Based on recent search behavior +- Create from your converting keywords +- High intent, good for prospecting + +**In-market audiences:** +- People actively researching solutions +- Pre-built by Google +- Layer with demographics for precision + +**Affinity audiences:** +- Based on interests and habits +- Better for awareness +- Broad but can exclude irrelevant + +**Customer match:** +- Upload email lists +- Retarget existing customers +- Create lookalikes from best customers + +**Similar/lookalike audiences:** +- Based on your customer match lists +- Expand reach while maintaining relevance +- Best when source list is high-quality customers + +--- + +## Meta Audiences + +### Core Audiences (Interest/Demographic) + +**Interest targeting tips:** +- Layer interests with AND logic for precision +- Use Audience Insights to research interests +- Start broad, let algorithm optimize +- Exclude existing customers always + +**Demographic targeting:** +- Age and gender (if product-specific) +- Location (down to zip/postal code) +- Language +- Education and work (limited data now) + +**Behavior targeting:** +- Purchase behavior +- Device usage +- Travel patterns +- Life events + +### Custom Audiences + +**Website visitors:** +- All visitors (last 180 days max) +- Specific page visitors +- Time on site thresholds +- Frequency (visited X times) + +**Customer list:** +- Upload emails/phone numbers +- Match rate typically 30-70% +- Refresh regularly for accuracy + +**Engagement audiences:** +- Video viewers (25%, 50%, 75%, 95%) +- Page/profile engagers +- Form openers +- Instagram engagers + +**App activity:** +- App installers +- In-app events +- Purchase events + +### Lookalike Audiences + +**Source audience quality matters:** +- Use high-LTV customers, not all customers +- Purchasers > leads > all visitors +- Minimum 100 source users, ideally 1,000+ + +**Size recommendations:** +- 1% — most similar, smallest reach +- 1-3% — good balance for most +- 3-5% — broader, good for scale +- 5-10% — very broad, awareness only + +**Layering strategies:** +- Lookalike + interest = more precision early +- Test lookalike-only as you scale +- Exclude the source audience + +--- + +## LinkedIn Audiences + +### Job-Based Targeting + +**Job titles:** +- Be specific (CMO vs. "Marketing") +- LinkedIn normalizes titles, but verify +- Stack related titles +- Exclude irrelevant titles + +**Job functions:** +- Broader than titles +- Combine with seniority level +- Good for awareness campaigns + +**Seniority levels:** +- Entry, Senior, Manager, Director, VP, CXO, Partner +- Layer with function for precision + +**Skills:** +- Self-reported, less reliable +- Good for technical roles +- Use as expansion layer + +### Company-Based Targeting + +**Company size:** +- 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5000+ +- Key filter for B2B + +**Industry:** +- Based on company classification +- Can be broad, layer with other criteria + +**Company names (ABM):** +- Upload target account list +- Minimum 300 companies recommended +- Match rate varies + +**Company growth rate:** +- Hiring rapidly = budget available +- Good signal for timing + +### High-Performing Combinations + +| Use Case | Targeting Combination | +|----------|----------------------| +| Enterprise sales | Company size 1000+ + VP/CXO + Industry | +| SMB sales | Company size 11-200 + Manager/Director + Function | +| Developer tools | Skills + Job function + Company type | +| ABM campaigns | Company list + Decision-maker titles | +| Broad awareness | Industry + Seniority + Geography | + +--- + +## Twitter/X Audiences + +### Targeting options: +- Follower lookalikes (accounts similar to followers of X) +- Interest categories +- Keywords (in tweets) +- Conversation topics +- Events +- Tailored audiences (your lists) + +### Best practices: +- Follower lookalikes of relevant accounts work well +- Keyword targeting catches active conversations +- Lower CPMs than LinkedIn/Meta +- Less precise, better for awareness + +--- + +## TikTok Audiences + +### Targeting options: +- Demographics (age, gender, location) +- Interests (TikTok's categories) +- Behaviors (video interactions) +- Device (iOS/Android, connection type) +- Custom audiences (pixel, customer file) +- Lookalike audiences + +### Best practices: +- Younger skew (18-34 primarily) +- Interest targeting is broad +- Creative matters more than targeting +- Let algorithm optimize with broad targeting + +--- + +## Audience Size Guidelines + +| Platform | Minimum Recommended | Ideal Range | +|----------|-------------------|-------------| +| Google Search | 1,000+ searches/mo | 5,000-50,000 | +| Google Display | 100,000+ | 500K-5M | +| Meta | 100,000+ | 500K-10M | +| LinkedIn | 50,000+ | 100K-500K | +| Twitter/X | 50,000+ | 100K-1M | +| TikTok | 100,000+ | 1M+ | + +Too narrow = expensive, slow learning +Too broad = wasted spend, poor relevance + +--- + +## Exclusion Strategy + +Always exclude: +- Existing customers (unless upsell) +- Recent converters (7-14 days) +- Bounced visitors (<10 sec) +- Employees (by company or email list) +- Irrelevant page visitors (careers, support) +- Competitors (if identifiable) diff --git a/.agents/skills/paid-ads/references/platform-setup-checklists.md b/.agents/skills/paid-ads/references/platform-setup-checklists.md new file mode 100644 index 00000000..5e663a5e --- /dev/null +++ b/.agents/skills/paid-ads/references/platform-setup-checklists.md @@ -0,0 +1,277 @@ +# Platform Setup Checklists + +Complete setup checklists for major ad platforms. + +## Contents +- Google Ads Setup (Account Foundation, Conversion Tracking, Analytics Integration, Audience Setup, Campaign Readiness, Ad Extensions, Brand Protection) +- Meta Ads Setup (Business Manager Foundation, Pixel & Tracking, Domain & Aggregated Events, Audience Setup, Catalog, Creative Assets, Compliance) +- LinkedIn Ads Setup (Campaign Manager Foundation, Insight Tag & Tracking, Audience Setup, Lead Gen Forms, Document Ads, Creative Assets, Budget Considerations) +- Twitter/X Ads Setup (Account Foundation, Tracking, Audience Setup, Creative) +- TikTok Ads Setup (Account Foundation, Pixel & Tracking, Audience Setup, Creative) +- Universal Pre-Launch Checklist + +## Google Ads Setup + +### Account Foundation + +- [ ] Google Ads account created and verified +- [ ] Billing information added +- [ ] Time zone and currency set correctly +- [ ] Account access granted to team members + +### Conversion Tracking + +- [ ] Google tag installed on all pages +- [ ] Conversion actions created (purchase, lead, signup) +- [ ] Conversion values assigned (if applicable) +- [ ] Enhanced conversions enabled +- [ ] Test conversions firing correctly +- [ ] Import conversions from GA4 (optional) + +### Analytics Integration + +- [ ] Google Analytics 4 linked +- [ ] Auto-tagging enabled +- [ ] GA4 audiences available in Google Ads +- [ ] Cross-domain tracking set up (if multiple domains) + +### Audience Setup + +- [ ] Remarketing tag verified +- [ ] Website visitor audiences created: + - All visitors (180 days) + - Key page visitors (pricing, demo, features) + - Converters (for exclusion) +- [ ] Customer match lists uploaded +- [ ] Similar audiences enabled + +### Campaign Readiness + +- [ ] Negative keyword lists created: + - Universal negatives (free, jobs, careers, reviews, complaints) + - Competitor negatives (if needed) + - Irrelevant industry terms +- [ ] Location targeting set (include/exclude) +- [ ] Language targeting set +- [ ] Ad schedule configured (if B2B, business hours) +- [ ] Device bid adjustments considered + +### Ad Extensions + +- [ ] Sitelinks (4-6 relevant pages) +- [ ] Callouts (key benefits, offers) +- [ ] Structured snippets (features, types, services) +- [ ] Call extension (if phone leads valuable) +- [ ] Lead form extension (if using) +- [ ] Price extensions (if applicable) +- [ ] Image extensions (where available) + +### Brand Protection + +- [ ] Brand campaign running (protect branded terms) +- [ ] Competitor campaigns considered +- [ ] Brand terms in negative lists for non-brand campaigns + +--- + +## Meta Ads Setup + +### Business Manager Foundation + +- [ ] Business Manager created +- [ ] Business verified (if running certain ad types) +- [ ] Ad account created within Business Manager +- [ ] Payment method added +- [ ] Team access configured with proper roles + +### Pixel & Tracking + +- [ ] Meta Pixel installed on all pages +- [ ] Standard events configured: + - PageView (automatic) + - ViewContent (product/feature pages) + - Lead (form submissions) + - Purchase (conversions) + - AddToCart (if e-commerce) + - InitiateCheckout (if e-commerce) +- [ ] Conversions API (CAPI) set up for server-side tracking +- [ ] Event Match Quality score > 6 +- [ ] Test events in Events Manager + +### Domain & Aggregated Events + +- [ ] Domain verified in Business Manager +- [ ] Aggregated Event Measurement configured +- [ ] Top 8 events prioritized in order of importance +- [ ] Web events prioritized for iOS 14+ tracking + +### Audience Setup + +- [ ] Custom audiences created: + - Website visitors (all, 30/60/90/180 days) + - Key page visitors + - Video viewers (25%, 50%, 75%, 95%) + - Page/Instagram engagers + - Customer list uploaded +- [ ] Lookalike audiences created (1%, 1-3%) +- [ ] Saved audiences for common targeting + +### Catalog (E-commerce) + +- [ ] Product catalog connected +- [ ] Product feed updating correctly +- [ ] Catalog sales campaigns enabled +- [ ] Dynamic product ads configured + +### Creative Assets + +- [ ] Images in correct sizes: + - Feed: 1080x1080 (1:1) + - Stories/Reels: 1080x1920 (9:16) + - Landscape: 1200x628 (1.91:1) +- [ ] Videos in correct formats +- [ ] Ad copy variations ready +- [ ] UTM parameters in all destination URLs + +### Compliance + +- [ ] Special Ad Categories declared (if housing, credit, employment, politics) +- [ ] Landing page complies with Meta policies +- [ ] No prohibited content in ads + +--- + +## LinkedIn Ads Setup + +### Campaign Manager Foundation + +- [ ] Campaign Manager account created +- [ ] Company Page connected +- [ ] Billing information added +- [ ] Team access configured + +### Insight Tag & Tracking + +- [ ] LinkedIn Insight Tag installed on all pages +- [ ] Tag verified and firing +- [ ] Conversion tracking configured: + - URL-based conversions + - Event-specific conversions +- [ ] Conversion values set (if applicable) + +### Audience Setup + +- [ ] Matched Audiences created: + - Website retargeting audiences + - Company list uploaded (for ABM) + - Contact list uploaded +- [ ] Lookalike audiences created +- [ ] Saved audiences for common targeting + +### Lead Gen Forms (if using) + +- [ ] Lead gen form templates created +- [ ] Form fields selected (minimize for conversion) +- [ ] Privacy policy URL added +- [ ] Thank you message configured +- [ ] CRM integration set up (or CSV export process) + +### Document Ads (if using) + +- [ ] Documents uploaded (PDF, PowerPoint) +- [ ] Gating configured (full gate or preview) +- [ ] Lead gen form connected + +### Creative Assets + +- [ ] Single image ads: 1200x627 (1.91:1) or 1080x1080 (1:1) +- [ ] Carousel images ready +- [ ] Video specs met (if using) +- [ ] Ad copy within character limits: + - Intro text: 600 max, 150 recommended + - Headline: 200 max, 70 recommended + +### Budget Considerations + +- [ ] Budget realistic for LinkedIn CPCs ($8-15+ typical) +- [ ] Audience size validated (50K+ recommended) +- [ ] Daily vs. lifetime budget decided +- [ ] Bid strategy selected + +--- + +## Twitter/X Ads Setup + +### Account Foundation + +- [ ] Ads account created +- [ ] Payment method added +- [ ] Account verified (if required) + +### Tracking + +- [ ] Twitter Pixel installed +- [ ] Conversion events created +- [ ] Website tag verified + +### Audience Setup + +- [ ] Tailored audiences created: + - Website visitors + - Customer lists +- [ ] Follower lookalikes identified +- [ ] Interest and keyword targets researched + +### Creative + +- [ ] Tweet copy within 280 characters +- [ ] Images: 1200x675 (1.91:1) or 1200x1200 (1:1) +- [ ] Video specs met (if using) +- [ ] Cards configured (website, app, etc.) + +--- + +## TikTok Ads Setup + +### Account Foundation + +- [ ] TikTok Ads Manager account created +- [ ] Business verification completed +- [ ] Payment method added + +### Pixel & Tracking + +- [ ] TikTok Pixel installed +- [ ] Events configured (ViewContent, Purchase, etc.) +- [ ] Events API set up (recommended) + +### Audience Setup + +- [ ] Custom audiences created +- [ ] Lookalike audiences created +- [ ] Interest categories identified + +### Creative + +- [ ] Vertical video (9:16) ready +- [ ] Native-feeling content (not too polished) +- [ ] First 3 seconds are compelling hooks +- [ ] Captions added (most watch without sound) +- [ ] Music/sounds selected (licensed if needed) + +--- + +## Universal Pre-Launch Checklist + +Before launching any campaign: + +- [ ] Conversion tracking tested with real conversion +- [ ] Landing page loads fast (<3 sec) +- [ ] Landing page mobile-friendly +- [ ] UTM parameters working +- [ ] Budget set correctly (daily vs. lifetime) +- [ ] Start/end dates correct +- [ ] Targeting matches intended audience +- [ ] Ad creative approved +- [ ] Team notified of launch +- [ ] Reporting dashboard ready diff --git a/.agents/skills/popup-cro/SKILL.md b/.agents/skills/popup-cro/SKILL.md new file mode 100644 index 00000000..0103c1f9 --- /dev/null +++ b/.agents/skills/popup-cro/SKILL.md @@ -0,0 +1,453 @@ +--- +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," or "overlay." 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 + +**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. **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 +- Always visible (top right is convention) +- 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 diff --git a/.agents/skills/product-marketing-context/SKILL.md b/.agents/skills/product-marketing-context/SKILL.md new file mode 100644 index 00000000..af050aac --- /dev/null +++ b/.agents/skills/product-marketing-context/SKILL.md @@ -0,0 +1,241 @@ +--- +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,' 'marketing context,' 'set up context,' 'positioning,' or wants to avoid repeating foundational information across marketing tasks. Creates `.agents/product-marketing-context.md` that other marketing skills reference." +metadata: + version: 1.1.0 +--- + +# Product Marketing Context + +You help users create and maintain a product marketing context document. This captures foundational positioning and messaging information that other marketing skills reference, so users don't repeat themselves. + +The document is stored at `.agents/product-marketing-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 +3. Confirm accuracy +4. Move to the next + +**Important:** Push for verbatim customer language. Exact phrases are more valuable than polished descriptions. + +--- + +## Sections to Capture + +### 1. Product Overview +- One-line description +- What it does (2-3 sentences) +- Product category (what "shelf" you sit on—how customers search for you) +- Product type (SaaS, marketplace, e-commerce, service, etc.) +- Business model and pricing + +### 2. Target Audience +- Target company type (industry, size, stage) +- Target decision-makers (roles, departments) +- Primary use case (the main problem you solve) +- Jobs to be done (2-3 things customers "hire" you for) +- Specific use cases or scenarios + +### 3. Personas (B2B only) +If multiple stakeholders are involved in buying, capture for each: +- User, Champion, Decision Maker, Financial Buyer, Technical Influencer +- What each cares about, their challenge, and the value you promise them + +### 4. Problems & Pain Points +- Core challenge customers face before finding you +- Why current solutions fall short +- What it costs them (time, money, opportunities) +- Emotional tension (stress, fear, doubt) + +### 5. Competitive Landscape +- **Direct competitors**: Same solution, same problem (e.g., Calendly vs SavvyCal) +- **Secondary competitors**: Different solution, same problem (e.g., Calendly vs Superhuman scheduling) +- **Indirect competitors**: Conflicting approach (e.g., Calendly vs personal assistant) +- How each falls short for customers + +### 6. Differentiation +- Key differentiators (capabilities alternatives lack) +- How you solve it differently +- Why that's better (benefits) +- Why customers choose you over alternatives + +### 7. Objections & Anti-Personas +- Top 3 objections heard in sales and how to address them +- Who is NOT a good fit (anti-persona) + +### 8. Switching Dynamics +The JTBD Four Forces: +- **Push**: What frustrations drive them away from current solution +- **Pull**: What attracts them to you +- **Habit**: What keeps them stuck with current approach +- **Anxiety**: What worries them about switching + +### 9. Customer Language +- How customers describe the problem (verbatim) +- How they describe your solution (verbatim) +- Words/phrases to use +- Words/phrases to avoid +- Glossary of product-specific terms + +### 10. Brand Voice +- Tone (professional, casual, playful, etc.) +- Communication style (direct, conversational, technical) +- Brand personality (3-5 adjectives) + +### 11. Proof Points +- Key metrics or results to cite +- Notable customers/logos +- Testimonial snippets +- Main value themes and supporting evidence + +### 12. Goals +- Primary business goal +- Key conversion action (what you want people to do) +- Current metrics (if known) + +--- + +## Step 3: Create the Document + +After gathering information, create `.agents/product-marketing-context.md` with this structure: + +```markdown +# Product Marketing Context + +*Last updated: [date]* + +## Product Overview +**One-liner:** +**What it does:** +**Product category:** +**Product type:** +**Business model:** + +## Target Audience +**Target companies:** +**Decision-makers:** +**Primary use case:** +**Jobs to be done:** +- +**Use cases:** +- + +## Personas +| Persona | Cares about | Challenge | Value we promise | +|---------|-------------|-----------|------------------| +| | | | | + +## Problems & Pain Points +**Core problem:** +**Why alternatives fall short:** +- +**What it costs them:** +**Emotional tension:** + +## Competitive Landscape +**Direct:** [Competitor] — falls short because... +**Secondary:** [Approach] — falls short because... +**Indirect:** [Alternative] — falls short because... + +## Differentiation +**Key differentiators:** +- +**How we do it differently:** +**Why that's better:** +**Why customers choose us:** + +## Objections +| Objection | Response | +|-----------|----------| +| | | + +**Anti-persona:** + +## Switching Dynamics +**Push:** +**Pull:** +**Habit:** +**Anxiety:** + +## Customer Language +**How they describe the problem:** +- "[verbatim]" +**How they describe us:** +- "[verbatim]" +**Words to use:** +**Words to avoid:** +**Glossary:** +| Term | Meaning | +|------|---------| +| | | + +## Brand Voice +**Tone:** +**Style:** +**Personality:** + +## Proof Points +**Metrics:** +**Customers:** +**Testimonials:** +> "[quote]" — [who] +**Value themes:** +| Theme | Proof | +|-------|-------| +| | | + +## Goals +**Business goal:** +**Conversion action:** +**Current metrics:** +``` + +--- + +## 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 product needs all sections (e.g., Personas for B2C) diff --git a/.agents/skills/programmatic-seo/SKILL.md b/.agents/skills/programmatic-seo/SKILL.md new file mode 100644 index 00000000..77c9cd93 --- /dev/null +++ b/.agents/skills/programmatic-seo/SKILL.md @@ -0,0 +1,238 @@ +--- +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," or "building many pages for SEO." For auditing existing SEO issues, see seo-audit. +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 +**Always use subfolders, not subdomains**: +- 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 diff --git a/.agents/skills/programmatic-seo/references/playbooks.md b/.agents/skills/programmatic-seo/references/playbooks.md new file mode 100644 index 00000000..35c354c6 --- /dev/null +++ b/.agents/skills/programmatic-seo/references/playbooks.md @@ -0,0 +1,308 @@ +# 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 diff --git a/.agents/skills/revops/SKILL.md b/.agents/skills/revops/SKILL.md new file mode 100644 index 00000000..7591b165 --- /dev/null +++ b/.agents/skills/revops/SKILL.md @@ -0,0 +1,343 @@ +--- +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,' or 'data hygiene.' 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 +- Always include a **fallback owner** — no lead should go unassigned +- 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 diff --git a/.agents/skills/revops/references/automation-playbooks.md b/.agents/skills/revops/references/automation-playbooks.md new file mode 100644 index 00000000..e2888743 --- /dev/null +++ b/.agents/skills/revops/references/automation-playbooks.md @@ -0,0 +1,290 @@ +# 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 diff --git a/.agents/skills/revops/references/lifecycle-definitions.md b/.agents/skills/revops/references/lifecycle-definitions.md new file mode 100644 index 00000000..811f9683 --- /dev/null +++ b/.agents/skills/revops/references/lifecycle-definitions.md @@ -0,0 +1,278 @@ +# 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) diff --git a/.agents/skills/revops/references/routing-rules.md b/.agents/skills/revops/references/routing-rules.md new file mode 100644 index 00000000..75bbf2d2 --- /dev/null +++ b/.agents/skills/revops/references/routing-rules.md @@ -0,0 +1,203 @@ +# 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) diff --git a/.agents/skills/revops/references/scoring-models.md b/.agents/skills/revops/references/scoring-models.md new file mode 100644 index 00000000..743d1de5 --- /dev/null +++ b/.agents/skills/revops/references/scoring-models.md @@ -0,0 +1,247 @@ +# 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 diff --git a/.agents/skills/sales-enablement/SKILL.md b/.agents/skills/sales-enablement/SKILL.md new file mode 100644 index 00000000..4df4eacc --- /dev/null +++ b/.agents/skills/sales-enablement/SKILL.md @@ -0,0 +1,349 @@ +--- +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,' 'ROI calculator,' 'demo script,' 'talk track,' 'sales playbook,' 'proposal template,' or 'buyer persona card.' For competitor battle cards and comparison pages, 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 + +**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. **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 + +- **Never demo without discovery.** 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 diff --git a/.agents/skills/sales-enablement/references/deck-frameworks.md b/.agents/skills/sales-enablement/references/deck-frameworks.md new file mode 100644 index 00000000..218c0fe1 --- /dev/null +++ b/.agents/skills/sales-enablement/references/deck-frameworks.md @@ -0,0 +1,263 @@ +# 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. diff --git a/.agents/skills/sales-enablement/references/demo-scripts.md b/.agents/skills/sales-enablement/references/demo-scripts.md new file mode 100644 index 00000000..e9dd0691 --- /dev/null +++ b/.agents/skills/sales-enablement/references/demo-scripts.md @@ -0,0 +1,355 @@ +# 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. diff --git a/.agents/skills/sales-enablement/references/objection-library.md b/.agents/skills/sales-enablement/references/objection-library.md new file mode 100644 index 00000000..22bcbc69 --- /dev/null +++ b/.agents/skills/sales-enablement/references/objection-library.md @@ -0,0 +1,270 @@ +# 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?" diff --git a/.agents/skills/sales-enablement/references/one-pager-templates.md b/.agents/skills/sales-enablement/references/one-pager-templates.md new file mode 100644 index 00000000..4902cdc9 --- /dev/null +++ b/.agents/skills/sales-enablement/references/one-pager-templates.md @@ -0,0 +1,208 @@ +# One-Pager Templates + +Templates for different one-pager use cases, with layout guidance and copy prompts. + +## Product Overview One-Pager + +The default one-pager. Introduces your product to someone who knows nothing about you. + +### Structure + +``` +[Logo] [Tagline] + +HEADLINE: One sentence describing what you do and who it's for. + +THE PROBLEM +2-3 sentences describing the pain your buyer faces. + +THE SOLUTION +2-3 sentences describing how your product solves it. + +WHY [YOUR PRODUCT] +• Differentiator 1 — One sentence explaining the benefit +• Differentiator 2 — One sentence explaining the benefit +• Differentiator 3 — One sentence explaining the benefit + +PROOF +"Customer quote with specific result." — Name, Title, Company +[Optional: 2-3 metric callouts: "X% improvement", "Y hours saved"] + +[CTA Button/Link] [Contact: name@company.com] +``` + +### Copy Prompts + +- Headline: "What do you do, in one sentence, that makes someone say 'tell me more'?" +- Problem: "What is your buyer struggling with before they find you?" +- Differentiators: "If you could only tell them 3 things, what would make them choose you?" + +--- + +## Use-Case Specific One-Pager + +Tailored to a specific workflow, vertical, or problem. More targeted than the product overview. + +### Structure + +``` +[Logo] [Use Case: e.g., "For Sales Teams"] + +HEADLINE: How [your product] helps [persona] [achieve outcome]. + +THE CHALLENGE +When [persona] needs to [task], they face [specific pain]. +This leads to [consequence]: [time wasted / money lost / risk]. + +HOW IT WORKS +1. [Step 1] — What happens and why it matters +2. [Step 2] — What happens and why it matters +3. [Step 3] — What happens and why it matters + +RESULTS +• [Metric 1]: Before → After +• [Metric 2]: Before → After +• [Metric 3]: Before → After + +CUSTOMER SPOTLIGHT +"Quote about this specific use case." — Name, Title, Company + +[CTA: "See it in action" or "Start a pilot"] [Contact info] +``` + +### When to Use + +- Different buyer personas need different one-pagers +- Industry-specific versions (healthcare, fintech, e-commerce) +- Use-case versions (reporting, onboarding, security) + +--- + +## Post-Meeting Leave-Behind + +Designed to reinforce a conversation that already happened. Summarizes what you discussed and proposes next steps. + +### Structure + +``` +[Logo] [Date of Meeting] + +MEETING RECAP: [Company Name] + +WHAT WE DISCUSSED +• [Pain point 1 they mentioned] +• [Pain point 2 they mentioned] +• [Goal they're trying to achieve] + +HOW [YOUR PRODUCT] HELPS +• [Solution to pain 1] — [Specific capability or workflow] +• [Solution to pain 2] — [Specific capability or workflow] +• [How you help them reach their goal] + +RELEVANT PROOF +"Quote from a similar customer." — Name, Title, Company +[1-2 metrics from a similar customer] + +PROPOSED NEXT STEPS +1. [Next step with date] +2. [Follow-up action] +3. [Decision timeline] + +[Your name] | [Your title] | [Email] | [Phone] +``` + +### Tips + +- Send within 24 hours of the meeting +- Reference specific things they said (shows you listened) +- Keep proposed next steps concrete and time-bound +- This is the asset your champion forwards to their boss + +--- + +## Champion Enablement One-Pager + +Designed specifically for your internal champion to share with their team and leadership. Written to make them look smart. + +### Structure + +``` +[Logo] + +WHY WE'RE EVALUATING [YOUR PRODUCT] + +THE SITUATION +[2-3 sentences about the internal challenge, written as if the champion +is explaining it to their team. Use "we" and "our" language.] + +WHAT [YOUR PRODUCT] DOES +[1-2 sentences. Plain language, no jargon.] + +WHY THIS SOLUTION +• [Reason 1] — How it solves our specific problem +• [Reason 2] — How it compares to what we do today +• [Reason 3] — How it compares to alternatives we evaluated + +EXPECTED IMPACT +• [Metric]: Current state → Expected state +• [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 diff --git a/.agents/skills/schema-markup/SKILL.md b/.agents/skills/schema-markup/SKILL.md index 04434ec5..d9569f63 100644 --- a/.agents/skills/schema-markup/SKILL.md +++ b/.agents/skills/schema-markup/SKILL.md @@ -1,7 +1,8 @@ --- name: schema-markup -version: 1.0.0 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," or "breadcrumb schema." For broader SEO issues, see seo-audit. +metadata: + version: 1.1.0 --- # Schema Markup @@ -11,7 +12,7 @@ You are an expert in structured data and schema markup. Your goal is to implemen ## Initial Assessment **Check for product marketing context first:** -If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task. +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: @@ -173,4 +174,6 @@ You can combine multiple schema types on one page using `@graph`: ## 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 diff --git a/.agents/skills/schema-markup/references/schema-examples.md b/.agents/skills/schema-markup/references/schema-examples.md index 1383f796..2987e9ec 100644 --- a/.agents/skills/schema-markup/references/schema-examples.md +++ b/.agents/skills/schema-markup/references/schema-examples.md @@ -2,6 +2,20 @@ 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. diff --git a/.agents/skills/seo-audit/SKILL.md b/.agents/skills/seo-audit/SKILL.md new file mode 100644 index 00000000..fab653dd --- /dev/null +++ b/.agents/skills/seo-audit/SKILL.md @@ -0,0 +1,412 @@ +--- +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," or "SEO health check." For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema-markup. +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 + +### ⚠️ Important: Schema Markup Detection Limitation + +**`web_fetch` and `curl` cannot reliably detect structured data / schema markup.** + +Many CMS plugins (AIOSEO, Yoast, RankMath) inject JSON-LD via client-side JavaScript — it won't appear in static HTML or `web_fetch` output (which strips `