diff --git a/personas/_shared/community-skills/ab-test-setup/SKILL.md b/personas/_shared/community-skills/ab-test-setup/SKILL.md new file mode 100644 index 0000000..3730493 --- /dev/null +++ b/personas/_shared/community-skills/ab-test-setup/SKILL.md @@ -0,0 +1,353 @@ +--- +name: ab-test-setup +description: When the user wants to plan, design, or implement an A/B test or experiment, or build a growth experimentation program. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant copy," "multivariate test," "hypothesis," "should I test this," "which version is better," "test two versions," "statistical significance," "how long should I run this test," "growth experiments," "experiment velocity," "experiment backlog," "ICE score," "experimentation program," or "experiment playbook." Use this whenever someone is comparing two approaches and wants to measure which performs better, or when they want to build a systematic experimentation practice. For tracking implementation, see analytics-tracking. For page-level conversion optimization, see page-cro. +metadata: + version: 1.2.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 + +**Avoid:** +- Peek at results and stop early +- Make changes to variants +- Add traffic from new sources + +### The Peeking Problem +Looking at results before reaching sample size and stopping early leads to false positives and wrong decisions. Pre-commit to sample size and trust the process. + +--- + +## Analyzing Results + +### Statistical Significance +- 95% confidence = p-value < 0.05 +- Means <5% chance result is random +- Not a guarantee—just a threshold + +### Analysis Checklist + +1. **Reach sample size?** If not, result is preliminary +2. **Statistically significant?** Check confidence intervals +3. **Effect size meaningful?** Compare to MDE, project impact +4. **Secondary metrics consistent?** Support the primary? +5. **Guardrail concerns?** Anything get worse? +6. **Segment differences?** Mobile vs. desktop? New vs. returning? + +### Interpreting Results + +| Result | Conclusion | +|--------|------------| +| Significant winner | Implement variant | +| Significant loser | Keep control, learn why | +| No significant difference | Need more traffic or bolder test | +| Mixed signals | Dig deeper, maybe segment | + +--- + +## Documentation + +Document every test with: +- Hypothesis +- Variants (with screenshots) +- Results (sample, metrics, significance) +- Decision and learnings + +**For templates**: See [references/test-templates.md](references/test-templates.md) + +--- + +## Growth Experimentation Program + +Individual tests are valuable. A continuous experimentation program is a compounding asset. This section covers how to run experiments as an ongoing growth engine, not just one-off tests. + +### The Experiment Loop + +``` +1. Generate hypotheses (from data, research, competitors, customer feedback) +2. Prioritize with ICE scoring +3. Design and run the test +4. Analyze results with statistical rigor +5. Promote winners to a playbook +6. Generate new hypotheses from learnings +→ Repeat +``` + +### Hypothesis Generation + +Feed your experiment backlog from multiple sources: + +| Source | What to Look For | +|--------|-----------------| +| Analytics | Drop-off points, low-converting pages, underperforming segments | +| Customer research | Pain points, confusion, unmet expectations | +| Competitor analysis | Features, messaging, or UX patterns they use that you don't | +| Support tickets | Recurring questions or complaints about conversion flows | +| Heatmaps/recordings | Where users hesitate, rage-click, or abandon | +| Past experiments | "Significant loser" tests often reveal new angles to try | + +### ICE Prioritization + +Score each hypothesis 1-10 on three dimensions: + +| Dimension | Question | +|-----------|----------| +| **Impact** | If this works, how much will it move the primary metric? | +| **Confidence** | How sure are we this will work? (Based on data, not gut.) | +| **Ease** | How fast and cheap can we ship and measure this? | + +**ICE Score** = (Impact + Confidence + Ease) / 3 + +Run highest-scoring experiments first. Re-score monthly as context changes. + +### Experiment Velocity + +Track your experimentation rate as a leading indicator of growth: + +| Metric | Target | +|--------|--------| +| Experiments launched per month | 4-8 for most teams | +| Win rate | 20-30% is common for mature programs (sustained higher rates may indicate conservative hypotheses) | +| Average test duration | 2-4 weeks | +| Backlog depth | 20+ hypotheses queued | +| Cumulative lift | Compound gains from all winners | + +### The Experiment Playbook + +When a test wins, don't just implement it — document the pattern: + +``` +## [Experiment Name] +**Date**: [date] +**Hypothesis**: [the hypothesis] +**Sample size**: [n per variant] +**Result**: [winner/loser/inconclusive] — [primary metric] changed by [X%] (95% CI: [range], p=[value]) +**Guardrails**: [any guardrail metrics and their outcomes] +**Segment deltas**: [notable differences by device, segment, or cohort] +**Why it worked/failed**: [analysis] +**Pattern**: [the reusable insight — e.g., "social proof near pricing CTAs increases plan selection"] +**Apply to**: [other pages/flows where this pattern might work] +**Status**: [implemented / parked / needs follow-up test] +``` + +Over time, your playbook becomes a library of proven growth patterns specific to your product and audience. + +### Experiment Cadence + +**Weekly (30 min)**: Review running experiments for technical issues and guardrail metrics. Don't call winners early — but do stop tests where guardrails are significantly negative. + +**Bi-weekly**: Conclude completed experiments. Analyze results, update playbook, launch next experiment from backlog. + +**Monthly (1 hour)**: Review experiment velocity, win rate, cumulative lift. Replenish hypothesis backlog. Re-prioritize with ICE. + +**Quarterly**: Audit the playbook. Which patterns have been applied broadly? Which winning patterns haven't been scaled yet? What areas of the funnel are under-tested? + +--- + +## Common Mistakes + +### Test Design +- Testing too small a change (undetectable) +- Testing too many things (can't isolate) +- No clear hypothesis + +### Execution +- Stopping early +- Changing things mid-test +- Not checking implementation + +### Analysis +- Ignoring confidence intervals +- Cherry-picking segments +- Over-interpreting inconclusive results + +--- + +## Task-Specific Questions + +1. What's your current conversion rate? +2. How much traffic does this page get? +3. What change are you considering and why? +4. What's the smallest improvement worth detecting? +5. What tools do you have for testing? +6. Have you tested this area before? + +--- + +## Related Skills + +- **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/personas/_shared/community-skills/ab-test-setup/references/sample-size-guide.md b/personas/_shared/community-skills/ab-test-setup/references/sample-size-guide.md new file mode 100644 index 0000000..3e35e6c --- /dev/null +++ b/personas/_shared/community-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/personas/_shared/community-skills/ab-test-setup/references/test-templates.md b/personas/_shared/community-skills/ab-test-setup/references/test-templates.md new file mode 100644 index 0000000..1c517d8 --- /dev/null +++ b/personas/_shared/community-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/personas/_shared/community-skills/ad-creative/SKILL.md b/personas/_shared/community-skills/ad-creative/SKILL.md new file mode 100644 index 0000000..acf77e5 --- /dev/null +++ b/personas/_shared/community-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,' 'ad performance optimization,' 'write me some ads,' 'Facebook ad copy,' 'Google ad headlines,' 'LinkedIn ad text,' or 'I need more ad variations.' Use this whenever someone needs to produce ad copy at scale or iterate on existing ads. For campaign strategy and targeting, see 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 + +Platforms reject or truncate creative that exceeds these limits, so verify every piece of copy fits before delivering. + +### Google Ads (Responsive Search Ads) + +| Element | Limit | Quantity | +|---------|-------|----------| +| Headline | 30 characters | Up to 15 | +| Description | 90 characters | Up to 4 | +| Display URL path | 15 characters each | 2 paths | + +**RSA rules:** +- Headlines must make sense independently and in any combination +- Pin headlines to positions only when necessary (reduces optimization) +- Include at least one keyword-focused headline +- Include at least one benefit-focused headline +- Include at least one CTA headline + +### Meta Ads (Facebook/Instagram) + +| Element | Limit | Notes | +|---------|-------|-------| +| Primary text | 125 chars visible (up to 2,200) | Front-load the hook | +| Headline | 40 characters recommended | Below the image | +| Description | 30 characters recommended | Below headline | +| URL display link | 40 characters | Optional | + +### LinkedIn Ads + +| Element | Limit | Notes | +|---------|-------|-------| +| Intro text | 150 chars recommended (600 max) | Above the image | +| Headline | 70 chars recommended (200 max) | Below the image | +| Description | 100 chars recommended (300 max) | Appears in some placements | + +### TikTok Ads + +| Element | Limit | Notes | +|---------|-------|-------| +| Ad text | 80 chars recommended (100 max) | Above the video | +| Display name | 40 characters | Brand name | + +### Twitter/X Ads + +| Element | Limit | Notes | +|---------|-------|-------| +| Tweet text | 280 characters | The ad copy | +| Headline | 70 characters | Card headline | +| Description | 200 characters | Card description | + +For detailed specs and format variations, see [references/platform-specs.md](references/platform-specs.md). + +--- + +## Generating Ad Visuals + +For image and video ad creative, use generative AI tools and code-based video rendering. See [references/generative-tools.md](references/generative-tools.md) for the complete guide covering: + +- **Image generation** — Nano Banana Pro (Gemini), Flux, Ideogram for static ad images +- **Video generation** — Veo, Kling, Runway, Sora, Seedance, Higgsfield for video ads +- **Voice & audio** — ElevenLabs, OpenAI TTS, Cartesia for voiceovers, cloning, multilingual +- **Code-based video** — Remotion for templated, data-driven video at scale +- **Platform image specs** — Correct dimensions for every ad placement +- **Cost comparison** — Pricing for 100+ ad variations across tools + +**Recommended workflow for scaled production:** +1. Generate hero creative with AI tools (exploratory, high-quality) +2. Build Remotion templates based on winning patterns +3. Batch produce variations with Remotion using data feeds +4. Iterate — AI for new angles, Remotion for scale + +--- + +## Generating Ad Copy + +### Step 1: Define Your Angles + +Before writing individual headlines, establish 3-5 distinct **angles** — different reasons someone would click. Each angle should tap into a different motivation. + +**Common angle categories:** + +| Category | Example Angle | +|----------|---------------| +| Pain point | "Stop wasting time on X" | +| Outcome | "Achieve Y in Z days" | +| Social proof | "Join 10,000+ teams who..." | +| Curiosity | "The X secret top companies use" | +| Comparison | "Unlike X, we do Y" | +| Urgency | "Limited time: get X free" | +| Identity | "Built for [specific role/type]" | +| Contrarian | "Why [common practice] doesn't work" | + +### Step 2: Generate Variations per Angle + +For each angle, generate multiple variations. Vary: +- **Word choice** — synonyms, active vs. passive +- **Specificity** — numbers vs. general claims +- **Tone** — direct vs. question vs. command +- **Structure** — short punch vs. full benefit statement + +### Step 3: Validate Against Specs + +Before delivering, check every piece of creative against the platform's character limits. Flag anything that's over and provide a trimmed alternative. + +### Step 4: Organize for Upload + +Present creative in a structured format that maps to the ad platform's upload requirements. + +--- + +## Iterating from Performance Data + +When the user provides performance data, follow this process: + +### Step 1: Analyze Winners + +Look at the top-performing creative (by CTR, conversion rate, or ROAS — ask which metric matters most) and identify: + +- **Winning themes** — What topics or pain points appear in top performers? +- **Winning structures** — Questions? Statements? Commands? Numbers? +- **Winning word patterns** — Specific words or phrases that recur? +- **Character utilization** — Are top performers shorter or longer? + +### Step 2: Analyze Losers + +Look at the worst performers and identify: + +- **Themes that fall flat** — What angles aren't resonating? +- **Common patterns in low performers** — Too generic? Too long? Wrong tone? + +### Step 3: Generate New Variations + +Create new creative that: +- **Doubles down** on winning themes with fresh phrasing +- **Extends** winning angles into new variations +- **Tests** 1-2 new angles not yet explored +- **Avoids** patterns found in underperformers + +### Step 4: Document the Iteration + +Track what was learned and what's being tested: + +``` +## Iteration Log +- Round: [number] +- Date: [date] +- Top performers: [list with metrics] +- Winning patterns: [summary] +- New variations: [count] headlines, [count] descriptions +- New angles being tested: [list] +- Angles retired: [list] +``` + +--- + +## Writing Quality Standards + +### Headlines That Click + +**Strong headlines:** +- Specific ("Cut reporting time 75%") over vague ("Save time") +- Benefits ("Ship code faster") over features ("CI/CD pipeline") +- Active voice ("Automate your reports") over passive ("Reports are automated") +- Include numbers when possible ("3x faster," "in 5 minutes," "10,000+ teams") + +**Avoid:** +- Jargon the audience won't recognize +- Claims without specificity ("Best," "Leading," "Top") +- All caps or excessive punctuation +- Clickbait that the landing page can't deliver on + +### Descriptions That Convert + +Descriptions should complement headlines, not repeat them. Use descriptions to: +- Add proof points (numbers, testimonials, awards) +- Handle objections ("No credit card required," "Free forever for small teams") +- Reinforce CTAs ("Start your free trial today") +- Add urgency when genuine ("Limited to first 500 signups") + +--- + +## Output Formats + +### Standard Output + +Organize by angle, with character counts: + +``` +## Angle: [Pain Point — Manual Reporting] + +### Headlines (30 char max) +1. "Stop Building Reports by Hand" (29) +2. "Automate Your Weekly Reports" (28) +3. "Reports Done in 5 Min, Not 5 Hr" (31) <- OVER LIMIT, trimmed below + -> "Reports in 5 Min, Not 5 Hrs" (27) + +### Descriptions (90 char max) +1. "Marketing teams save 10+ hours/week with automated reporting. Start free." (73) +2. "Connect your data sources once. Get automated reports forever. No code required." (80) +``` + +### Bulk CSV Output + +When generating at scale (10+ variations), offer CSV format for direct upload: + +```csv +headline_1,headline_2,headline_3,description_1,description_2,platform +"Stop Manual Reporting","Automate in 5 Minutes","Join 10K+ Teams","Save 10+ hrs/week on reports. Start free.","Connect data sources once. Reports forever.","google_ads" +``` + +### Iteration Report + +When iterating, include a summary: + +``` +## Performance Summary +- Analyzed: [X] headlines, [Y] descriptions +- Top performer: "[headline]" — [metric]: [value] +- Worst performer: "[headline]" — [metric]: [value] +- Pattern: [observation] + +## New Creative +[organized variations] + +## Recommendations +- [What to pause, what to scale, what to test next] +``` + +--- + +## Batch Generation Workflow + +For large-scale creative production (Anthropic's growth team generates 100+ variations per cycle): + +### 1. Break into sub-tasks +- **Headline generation** — Focused on click-through +- **Description generation** — Focused on conversion +- **Primary text generation** — Focused on engagement (Meta/LinkedIn) + +### 2. Generate in waves +- Wave 1: Core angles (3-5 angles, 5 variations each) +- Wave 2: Extended variations on top 2 angles +- Wave 3: Wild card angles (contrarian, emotional, specific) + +### 3. Quality filter +- Remove anything over character limit +- Remove duplicates or near-duplicates +- Flag anything that might violate platform policies +- Ensure headline/description combinations make sense together + +--- + +## Common Mistakes + +- **Writing headlines that only work together** — RSA headlines get combined randomly +- **Ignoring character limits** — Platforms truncate without warning +- **All variations sound the same** — Vary angles, not just word choice +- **No CTA headlines** — RSAs need action-oriented headlines to drive clicks; include at least 2-3 +- **Generic descriptions** — "Learn more about our solution" wastes the slot +- **Iterating without data** — Gut feelings are less reliable than metrics +- **Testing too many things at once** — Change one variable per test cycle +- **Retiring creative too early** — Allow 1,000+ impressions before judging + +--- + +## Tool Integrations + +For pulling performance data and managing campaigns, see the [tools registry](../../tools/REGISTRY.md). + +| 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/personas/_shared/community-skills/ad-creative/references/generative-tools.md b/personas/_shared/community-skills/ad-creative/references/generative-tools.md new file mode 100644 index 0000000..e22ebce --- /dev/null +++ b/personas/_shared/community-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/personas/_shared/community-skills/ad-creative/references/platform-specs.md b/personas/_shared/community-skills/ad-creative/references/platform-specs.md new file mode 100644 index 0000000..c9a3c4a --- /dev/null +++ b/personas/_shared/community-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/personas/_shared/community-skills/ai-seo/SKILL.md b/personas/_shared/community-skills/ai-seo/SKILL.md new file mode 100644 index 0000000..8b18b5a --- /dev/null +++ b/personas/_shared/community-skills/ai-seo/SKILL.md @@ -0,0 +1,443 @@ +--- +name: ai-seo +description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' or 'optimize for Claude/Gemini.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema-markup." +metadata: + version: 1.2.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 + +### Machine-Readable Files for AI Agents + +AI agents aren't just answering questions — they're becoming buyers. When an AI agent evaluates tools on behalf of a user, it needs structured, parseable information. If your pricing is locked in a JavaScript-rendered page or a "contact sales" wall, agents will skip you and recommend competitors whose information they can actually read. + +Add these machine-readable files to your site root: + +**`/pricing.md` or `/pricing.txt`** — Structured pricing data for AI agents + +```markdown +# Pricing — [Your Product Name] + +## Free +- Price: $0/month +- Limits: 100 emails/month, 1 user +- Features: Basic templates, API access + +## Pro +- Price: $29/month (billed annually) | $35/month (billed monthly) +- Limits: 10,000 emails/month, 5 users +- Features: Custom domains, analytics, priority support + +## Enterprise +- Price: Custom — contact sales@example.com +- Limits: Unlimited emails, unlimited users +- Features: SSO, SLA, dedicated account manager +``` + +**Why this matters now:** +- AI agents increasingly compare products programmatically before a human ever visits your site +- Opaque pricing gets filtered out of AI-mediated buying journeys +- A simple markdown file is trivially parseable by any LLM — no rendering, no JavaScript, no login walls +- Same principle as `robots.txt` (for crawlers), `llms.txt` (for AI context), and `AGENTS.md` (for agent capabilities) + +**Best practices:** +- Use consistent units (monthly vs. annual, per-seat vs. flat) +- Include specific limits and thresholds, not just feature names +- List what's included at each tier, not just what's different +- Keep it updated — stale pricing is worse than no file +- Link to it from your sitemap and main pricing page + +**`/llms.txt`** — Context file for AI systems (see [llmstxt.org](https://llmstxt.org)) + +If you don't have one yet, add an `llms.txt` that gives AI systems a quick overview of what your product does, who it's for, and links to key pages (including your pricing). + +### Schema Markup for AI + +Structured data helps AI systems understand your content. Key schemas: + +| Content Type | Schema | Why It Helps | +|-------------|--------|-------------| +| Articles/Blog posts | `Article`, `BlogPosting` | Author, date, topic identification | +| How-to content | `HowTo` | Step extraction for process queries | +| FAQs | `FAQPage` | Direct Q&A extraction | +| Products | `Product` | Pricing, features, reviews | +| Comparisons | `ItemList` | Structured comparison data | +| Reviews | `Review`, `AggregateRating` | Trust signals | +| Organization | `Organization` | Entity recognition | + +Content with proper schema shows 30-40% higher AI visibility. 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) — add a `/pricing.md` file so AI agents can parse your plans without rendering your page (see "Machine-Readable Files" above) +- FAQ section addressing common buyer questions + +### 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 because AI systems weight recency heavily. Show when content was last updated +- **Gating all content** — AI can't access gated content. Keep your most authoritative content open +- **Ignoring third-party presence** — You may get more AI citations from a Wikipedia mention than from your own blog +- **No structured data** — Schema markup gives AI systems structured context about your content +- **Keyword stuffing** — Unlike traditional SEO where it's just ineffective, keyword stuffing actively reduces AI visibility by 10% (Princeton GEO study) +- **Hiding pricing behind "contact sales" or JS-rendered pages** — AI agents evaluating your product on behalf of buyers can't parse what they can't read. Add a `/pricing.md` file +- **Blocking AI bots** — If GPTBot, PerplexityBot, or ClaudeBot are blocked in robots.txt, those platforms can't cite you +- **Generic content without data** — "We're the best" won't get cited. "Our customers see 3x improvement in [metric]" will +- **Forgetting to monitor** — You can't improve what you don't measure. Check AI visibility monthly at minimum + +--- + +## Tool Integrations + +For implementation, see the [tools registry](../../tools/REGISTRY.md). + +| Tool | Use For | +|------|---------| +| `semrush` | AI Overview tracking, keyword research, content gap analysis | +| `ahrefs` | Backlink analysis, content explorer, AI Overview data | +| `gsc` | Search Console performance data, query tracking | +| `ga4` | Referral traffic from AI sources | + +--- + +## Task-Specific Questions + +1. What are your top 10-20 most important queries? +2. Have you checked if AI answers exist for those queries today? +3. Do you have structured data (schema markup) on your site? +4. What content types do you publish? (Blog, docs, comparisons, etc.) +5. Are competitors being cited by AI where you're not? +6. Do you have a Wikipedia page or presence on review sites? + +--- + +## Related Skills + +- **seo-audit**: For traditional technical and on-page SEO audits +- **schema-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/personas/_shared/community-skills/ai-seo/references/content-patterns.md b/personas/_shared/community-skills/ai-seo/references/content-patterns.md new file mode 100644 index 0000000..e1926c8 --- /dev/null +++ b/personas/_shared/community-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/personas/_shared/community-skills/ai-seo/references/platform-ranking-factors.md b/personas/_shared/community-skills/ai-seo/references/platform-ranking-factors.md new file mode 100644 index 0000000..4353d09 --- /dev/null +++ b/personas/_shared/community-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/personas/_shared/community-skills/analytics-tracking/SKILL.md b/personas/_shared/community-skills/analytics-tracking/SKILL.md new file mode 100644 index 0000000..de0159c --- /dev/null +++ b/personas/_shared/community-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," "tracking plan," "how do I measure this," "track conversions," "attribution," "Mixpanel," "Segment," "are my events firing," or "analytics isn't working." Use this whenever someone asks how to know if something is working or wants to measure marketing results. For A/B test measurement, see ab-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/personas/_shared/community-skills/analytics-tracking/references/event-library.md b/personas/_shared/community-skills/analytics-tracking/references/event-library.md new file mode 100644 index 0000000..c381b56 --- /dev/null +++ b/personas/_shared/community-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/personas/_shared/community-skills/analytics-tracking/references/ga4-implementation.md b/personas/_shared/community-skills/analytics-tracking/references/ga4-implementation.md new file mode 100644 index 0000000..f2656dc --- /dev/null +++ b/personas/_shared/community-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/personas/_shared/community-skills/analytics-tracking/references/gtm-implementation.md b/personas/_shared/community-skills/analytics-tracking/references/gtm-implementation.md new file mode 100644 index 0000000..956e638 --- /dev/null +++ b/personas/_shared/community-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/personas/_shared/community-skills/browser-use-browser-use/SKILL.md b/personas/_shared/community-skills/browser-use-browser-use/SKILL.md new file mode 100644 index 0000000..71beb9e --- /dev/null +++ b/personas/_shared/community-skills/browser-use-browser-use/SKILL.md @@ -0,0 +1,219 @@ +--- +name: browser-use +description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, or extract information from web pages. +allowed-tools: Bash(browser-use:*) +--- + +# Browser Automation with browser-use CLI + +The `browser-use` command provides fast, persistent browser automation. A background daemon keeps the browser open across commands, giving ~50ms latency per call. + +## Prerequisites + +```bash +browser-use doctor # Verify installation +``` + +For setup details, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md + +## Core Workflow + +1. **Navigate**: `browser-use open ` — launches headless browser and opens page +2. **Inspect**: `browser-use state` — returns clickable elements with indices +3. **Interact**: use indices from state (`browser-use click 5`, `browser-use input 3 "text"`) +4. **Verify**: `browser-use state` or `browser-use screenshot` to confirm +5. **Repeat**: browser stays open between commands + +If a command fails, run `browser-use close` first to clear any broken session, then retry. + +To use the user's existing Chrome (preserves logins/cookies): run `browser-use connect` first. +To use a cloud browser instead: run `browser-use cloud connect` first. +After either, commands work the same way. + +## Browser Modes + +```bash +browser-use open # Default: headless Chromium (no setup needed) +browser-use --headed open # Visible window (for debugging) +browser-use connect # Connect to user's Chrome (preserves logins/cookies) +browser-use cloud connect # Cloud browser (zero-config, requires API key) +browser-use --profile "Default" open # Real Chrome with specific profile +``` + +After `connect` or `cloud connect`, all subsequent commands go to that browser — no extra flags needed. + +## Commands + +```bash +# Navigation +browser-use open # Navigate to URL +browser-use back # Go back in history +browser-use scroll down # Scroll down (--amount N for pixels) +browser-use scroll up # Scroll up +browser-use tab list # List all tabs +browser-use tab new [url] # Open a new tab (blank or with URL) +browser-use tab switch # Switch to tab by index +browser-use tab close [index...] # Close one or more tabs + +# Page State — always run state first to get element indices +browser-use state # URL, title, clickable elements with indices +browser-use screenshot [path.png] # Screenshot (base64 if no path, --full for full page) + +# Interactions — use indices from state +browser-use click # Click element by index +browser-use click # Click at pixel coordinates +browser-use type "text" # Type into focused element +browser-use input "text" # Click element, then type +browser-use keys "Enter" # Send keyboard keys (also "Control+a", etc.) +browser-use select "option" # Select dropdown option +browser-use upload # Upload file to file input +browser-use hover # Hover over element +browser-use dblclick # Double-click element +browser-use rightclick # Right-click element + +# Data Extraction +browser-use eval "js code" # Execute JavaScript, return result +browser-use get title # Page title +browser-use get html [--selector "h1"] # Page HTML (or scoped to selector) +browser-use get text # Element text content +browser-use get value # Input/textarea value +browser-use get attributes # Element attributes +browser-use get bbox # Bounding box (x, y, width, height) + +# Wait +browser-use wait selector "css" # Wait for element (--state visible|hidden|attached|detached, --timeout ms) +browser-use wait text "text" # Wait for text to appear + +# Cookies +browser-use cookies get [--url ] # Get cookies (optionally filtered) +browser-use cookies set # Set cookie (--domain, --secure, --http-only, --same-site, --expires) +browser-use cookies clear [--url ] # Clear cookies +browser-use cookies export # Export to JSON +browser-use cookies import # Import from JSON + +# Session +browser-use close # Close browser and stop daemon +browser-use sessions # List active sessions +browser-use close --all # Close all sessions +``` + +For advanced browser control (CDP, device emulation, tab activation), see `references/cdp-python.md`. + +## Cloud API + +```bash +browser-use cloud connect # Provision cloud browser and connect (zero-config) +browser-use cloud login # Save API key (or set BROWSER_USE_API_KEY) +browser-use cloud logout # Remove API key +browser-use cloud v2 GET /browsers # REST passthrough (v2 or v3) +browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}' +browser-use cloud v2 poll # Poll task until done +browser-use cloud v2 --help # Show API endpoints +``` + +`cloud connect` provisions a cloud browser with a persistent profile (auto-created on first use), connects via CDP, and prints a live URL. `browser-use close` disconnects AND stops the cloud browser. For custom browser settings (proxy, timeout, specific profile), use `cloud v2 POST /browsers` directly with the desired parameters. + +### Agent Self-Registration + +Only use this if you don't already have an API key (check `browser-use doctor` to see if api_key is set). If already logged in, skip this entirely. + +1. `browser-use cloud signup` — get a challenge +2. Solve the challenge +3. `browser-use cloud signup --verify ` — verify and save API key +4. `browser-use cloud signup --claim` — generate URL for a human to claim the account + +## Tunnels + +```bash +browser-use tunnel # Start Cloudflare tunnel (idempotent) +browser-use tunnel list # Show active tunnels +browser-use tunnel stop # Stop tunnel +browser-use tunnel stop --all # Stop all tunnels +``` + +## Profile Management + +```bash +browser-use profile list # List detected browsers and profiles +browser-use profile sync --all # Sync profiles to cloud +browser-use profile update # Download/update profile-use binary +``` + +## Command Chaining + +Commands can be chained with `&&`. The browser persists via the daemon, so chaining is safe and efficient. + +```bash +browser-use open https://example.com && browser-use state +browser-use input 5 "user@example.com" && browser-use input 6 "password" && browser-use click 7 +``` + +Chain when you don't need intermediate output. Run separately when you need to parse `state` to discover indices first. + +## Common Workflows + +### Authenticated Browsing + +When a task requires an authenticated site (Gmail, GitHub, internal tools), use Chrome profiles: + +```bash +browser-use profile list # Check available profiles +# Ask the user which profile to use, then: +browser-use --profile "Default" open https://github.com # Already logged in +``` + +### Exposing Local Dev Servers + +```bash +browser-use tunnel 3000 # → https://abc.trycloudflare.com +browser-use open https://abc.trycloudflare.com # Browse the tunnel +``` + +## Multiple Browsers + +For subagent workflows or running multiple browsers in parallel, use `--session NAME`. Each session gets its own browser. See `references/multi-session.md`. + +## Configuration + +```bash +browser-use config list # Show all config values +browser-use config set cloud_connect_proxy jp # Set a value +browser-use config get cloud_connect_proxy # Get a value +browser-use config unset cloud_connect_timeout # Remove a value +browser-use doctor # Shows config + diagnostics +browser-use setup # Interactive post-install setup +``` + +Config stored in `~/.browser-use/config.json`. + +## Global Options + +| Option | Description | +|--------|-------------| +| `--headed` | Show browser window | +| `--profile [NAME]` | Use real Chrome (bare `--profile` uses "Default") | +| `--cdp-url ` | Connect via CDP URL (`http://` or `ws://`) | +| `--session NAME` | Target a named session (default: "default") | +| `--json` | Output as JSON | +| `--mcp` | Run as MCP server via stdin/stdout | + +## Tips + +1. **Always run `state` first** to see available elements and their indices +2. **Use `--headed` for debugging** to see what the browser is doing +3. **Sessions persist** — browser stays open between commands +4. **CLI aliases**: `bu`, `browser`, and `browseruse` all work +5. **If commands fail**, run `browser-use close` first, then retry + +## Troubleshooting + +- **Browser won't start?** `browser-use close` then `browser-use --headed open ` +- **Element not found?** `browser-use scroll down` then `browser-use state` +- **Run diagnostics:** `browser-use doctor` + +## Cleanup + +```bash +browser-use close # Close browser session +browser-use tunnel stop --all # Stop tunnels (if any) +``` diff --git a/personas/_shared/community-skills/browser-use-browser-use/references/cdp-python.md b/personas/_shared/community-skills/browser-use-browser-use/references/cdp-python.md new file mode 100644 index 0000000..4652264 --- /dev/null +++ b/personas/_shared/community-skills/browser-use-browser-use/references/cdp-python.md @@ -0,0 +1,76 @@ +# Raw CDP & Python Session Reference + +The CLI commands handle most browser interactions. Use `browser-use python` with raw CDP when you need browser-level control the CLI doesn't expose — activating a tab so the user sees it, intercepting network requests, emulating devices, or working with Chrome target IDs directly. + +## How the Python session works + +`browser-use python "statement"` executes one Python statement per call. Variables persist across calls — set a value in one call, use it in the next. + +A `browser` object is pre-injected with sync wrappers for common operations (`browser.goto()`, `browser.click()`, etc.). For anything beyond those, two internals give you full access: + +- `browser._run(coroutine)` — run any async coroutine synchronously (60s timeout) +- `browser._session` — the raw `BrowserSession` with full CDP client access + +## Getting a CDP client + +```bash +browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())" +``` + +After this, `cdp` persists across calls. Use `cdp.cdp_client.send..()` for any CDP command and `cdp.session_id` for the session parameter. + +## Recipes + +### Activate a tab (make it visible to the user) + +The CLI's `tab switch` only changes the agent's internal focus — Chrome's visible tab doesn't change. To actually show the user a specific tab: + +```bash +# Get all targets to find the target ID +browser-use python "targets = browser._session.session_manager.get_all_page_targets()" +browser-use python "print([(i, t.url) for i, t in enumerate(targets)])" + +# Activate target at index 1 so the user sees it +browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session(target_id=None, focus=False))" +browser-use python "browser._run(cdp.cdp_client.send.Target.activateTarget(params={'targetId': targets[1].target_id}))" +``` + +### List all tabs with target IDs + +```bash +browser-use python "targets = browser._session.session_manager.get_all_page_targets()" +browser-use python " +for i, t in enumerate(targets): + print(f'{i}: {t.target_id[:12]}... {t.url}') +" +``` + +### Run JavaScript and get the result + +```bash +browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())" +browser-use python "result = browser._run(cdp.cdp_client.send.Runtime.evaluate(params={'expression': 'document.title', 'returnByValue': True}, session_id=cdp.session_id))" +browser-use python "print(result['result']['value'])" +``` + +### Emulate a mobile device + +```bash +browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())" +browser-use python "browser._run(cdp.cdp_client.send.Emulation.setDeviceMetricsOverride(params={'width': 375, 'height': 812, 'deviceScaleFactor': 3, 'mobile': True}, session_id=cdp.session_id))" +``` + +### Get cookies via CDP + +```bash +browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())" +browser-use python "cookies = browser._run(cdp.cdp_client.send.Network.getCookies(params={}, session_id=cdp.session_id))" +browser-use python "print(cookies)" +``` + +## Tips + +- Each `browser-use python` call is one statement. Multi-line strings work for `for` loops and `if` blocks, but you can't mix statements and expressions. Use multiple calls. +- Variables persist: set `cdp = ...` in one call, use `cdp` in the next. +- The `browser._run()` bridge has a 60-second timeout. For long operations, increase it or use the async internals directly. +- All CDP domains are available via `cdp.cdp_client.send..()`. See the [Chrome DevTools Protocol docs](https://chromedevtools.github.io/devtools-protocol/) for the full API. diff --git a/personas/_shared/community-skills/browser-use-browser-use/references/multi-session.md b/personas/_shared/community-skills/browser-use-browser-use/references/multi-session.md new file mode 100644 index 0000000..1679b5b --- /dev/null +++ b/personas/_shared/community-skills/browser-use-browser-use/references/multi-session.md @@ -0,0 +1,92 @@ +# Multiple Browser Sessions + +## Why use multiple sessions + +When you need more than one browser at a time: +- Cloud browser for scraping + local Chrome for authenticated tasks +- Two different Chrome profiles simultaneously +- Isolated browser for testing that won't affect the user's browsing +- Running a headed browser for debugging while headless runs in background + +## How sessions are isolated + +Each `--session NAME` gets: +- Its own daemon process +- Its own Unix socket (`~/.browser-use/{name}.sock`) +- Its own PID file and state file +- Its own browser instance (completely independent) +- Its own tab ownership state (multi-agent locks don't cross sessions) + +## The `--session` flag + +Must be passed on every command targeting that session: + +```bash +browser-use --session work open # goes to 'work' daemon +browser-use --session work state # reads from 'work' daemon +browser-use state # goes to 'default' daemon (different browser) +``` + +If you forget `--session`, the command goes to the `default` session. This is the most common mistake — you'll interact with the wrong browser. + +## Combining sessions with browser modes + +```bash +# Session 1: cloud browser +browser-use --session cloud cloud connect + +# Session 2: connect to user's Chrome +browser-use --session chrome connect + +# Session 3: headed Chromium for debugging +browser-use --session debug --headed open +``` + +Each session is fully independent. The cloud session talks to a remote browser, the chrome session talks to the user's Chrome, and the debug session manages its own Chromium — all running simultaneously. + +## Listing and managing sessions + +```bash +browser-use sessions +``` + +Output: +``` +SESSION PHASE PID CONFIG +cloud running 12345 cloud +chrome running 12346 cdp +debug ready 12347 headed +``` + +PHASE shows the daemon lifecycle state: `initializing`, `ready`, `starting`, `running`, `shutting_down`, `stopped`, `failed`. + +```bash +browser-use --session cloud close # close one session +browser-use close --all # close every session +``` + +## Common patterns + +**Cloud + local authenticated:** +```bash +browser-use --session scraper cloud connect +browser-use --session scraper open https://example.com +# ... scrape data ... + +browser-use --session auth --profile "Default" open https://github.com +browser-use --session auth state +# ... interact with authenticated site ... +``` + +**Throwaway test browser:** +```bash +browser-use --session test --headed open https://localhost:3000 +# ... test, debug, inspect ... +browser-use --session test close # done, clean up +``` + +**Environment variable:** +```bash +export BROWSER_USE_SESSION=work +browser-use open # uses 'work' session without --session flag +``` diff --git a/personas/_shared/community-skills/browser-use-cloud/SKILL.md b/personas/_shared/community-skills/browser-use-cloud/SKILL.md new file mode 100644 index 0000000..d96b537 --- /dev/null +++ b/personas/_shared/community-skills/browser-use-cloud/SKILL.md @@ -0,0 +1,55 @@ +--- +name: cloud +description: > + Documentation reference for using Browser Use Cloud — the hosted API + and SDK for browser automation. Use this skill whenever the user needs + help with the Cloud REST API (v2 or v3), browser-use-sdk (Python or + TypeScript), X-Browser-Use-API-Key authentication, cloud sessions, + browser profiles, profile sync, CDP WebSocket connections, stealth + browsers, residential proxies, CAPTCHA handling, webhooks, workspaces, + skills marketplace, liveUrl streaming, pricing, or integration patterns + (chat UI, subagent, adding browser tools to existing agents). Also + trigger for questions about n8n/Make/Zapier integration, Playwright/ + Puppeteer/Selenium on cloud infrastructure, or 1Password vault + integration. Do NOT use this for the open-source Python library + (Agent, Browser, Tools config) — use the open-source skill instead. +allowed-tools: Read +--- + +# Browser Use Cloud Reference + +Reference docs for the Cloud REST API, SDKs, and integration patterns. +Read the relevant file based on what the user needs. + +## API & Platform + +| Topic | Read | +|-------|------| +| Setup, first task, pricing, FAQ | `references/quickstart.md` | +| v2 REST API: all 30 endpoints, cURL examples, schemas | `references/api-v2.md` | +| v3 BU Agent API: sessions, messages, files, workspaces | `references/api-v3.md` | +| Sessions, profiles, auth strategies, 1Password | `references/sessions.md` | +| CDP direct access, Playwright/Puppeteer/Selenium | `references/browser-api.md` | +| Proxies, webhooks, workspaces, skills, MCP, live view | `references/features.md` | +| Parallel, streaming, geo-scraping, tutorials | `references/patterns.md` | + +## Integration Guides + +| Topic | Read | +|-------|------| +| Building a chat interface with live browser view | `references/guides/chat-ui.md` | +| Using browser-use as a subagent (task in → result out) | `references/guides/subagent.md` | +| Adding browser-use tools to an existing agent | `references/guides/tools-integration.md` | + +## Critical Notes + +- Cloud API base URL: `https://api.browser-use.com/api/v2/` (v2) or `https://api.browser-use.com/api/v3` (v3) +- Auth header: `X-Browser-Use-API-Key: ` +- Get API key: https://cloud.browser-use.com/new-api-key +- Set env var: `BROWSER_USE_API_KEY=` +- Cloud SDK: `uv pip install browser-use-sdk` (Python) or `npm install browser-use-sdk` (TypeScript) +- Python v2: `from browser_use_sdk import AsyncBrowserUse` +- Python v3: `from browser_use_sdk.v3 import AsyncBrowserUse` +- TypeScript v2: `import { BrowserUse } from "browser-use-sdk"` +- TypeScript v3: `import { BrowserUse } from "browser-use-sdk/v3"` +- CDP WebSocket: `wss://connect.browser-use.com?apiKey=KEY&proxyCountryCode=us` diff --git a/personas/_shared/community-skills/browser-use-cloud/references/api-v2.md b/personas/_shared/community-skills/browser-use-cloud/references/api-v2.md new file mode 100644 index 0000000..5be9d2c --- /dev/null +++ b/personas/_shared/community-skills/browser-use-cloud/references/api-v2.md @@ -0,0 +1,328 @@ +# Cloud API v2 (Stable) + +Full-featured REST API for tasks, sessions, browsers, profiles, skills, and marketplace. + +## Table of Contents +- [Authentication](#authentication) +- [Common cURL Examples](#common-curl-examples) +- [Tasks](#tasks) +- [Sessions](#sessions) +- [Browsers (CDP)](#browsers-cdp) +- [Files](#files) +- [Profiles](#profiles) +- [Skills](#skills) +- [Marketplace](#marketplace) +- [Billing](#billing) +- [Pagination](#pagination) +- [Enums](#enums) +- [Response Schemas](#response-schemas) + +--- + +## Authentication + +- **Header:** `X-Browser-Use-API-Key: ` +- **Base URL:** `https://api.browser-use.com/api/v2` +- **Get key:** https://cloud.browser-use.com/new-api-key + +All endpoints require the `X-Browser-Use-API-Key` header. + +## Common cURL Examples + +### Create a task + +```bash +curl -X POST https://api.browser-use.com/api/v2/tasks \ + -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"task": "Find the top Hacker News post and return title and URL"}' +``` + +Response: `{"id": "", "sessionId": ""}` + +### Poll task status + +```bash +curl https://api.browser-use.com/api/v2/tasks//status \ + -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" +``` + +### Get session live URL + +```bash +curl https://api.browser-use.com/api/v2/sessions/ \ + -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" +``` + +Response includes `liveUrl` — open it to watch the agent work. + +### Create a CDP browser + +```bash +curl -X POST https://api.browser-use.com/api/v2/browsers \ + -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"proxyCountryCode": "us", "timeout": 30}' +``` + +Response includes `cdpUrl` (WebSocket) and `liveUrl`. + +### Stop a session + +```bash +curl -X PATCH https://api.browser-use.com/api/v2/sessions/ \ + -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"action": "stop"}' +``` + +### Upload a file to a session + +```bash +# 1. Get presigned URL +curl -X POST https://api.browser-use.com/api/v2/files/sessions//presigned-url \ + -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"fileName": "input.pdf", "contentType": "application/pdf", "sizeBytes": 102400}' + +# 2. Upload via multipart POST using the returned URL and ALL returned fields (S3-style presigned POST) +# Include every key-value pair from the response's `fields` object as form fields: +curl -X POST "" \ + -F "key=" \ + -F "policy=" \ + -F "x-amz-algorithm=" \ + -F "x-amz-credential=" \ + -F "x-amz-date=" \ + -F "x-amz-signature=" \ + -F "Content-Type=application/pdf" \ + -F "file=@input.pdf" +``` + +The v2 presigned URL response includes `fields` for a multipart POST form upload (S3-style). **Include all returned fields** as form fields — they contain the signing data. Presigned URLs expire after **120 seconds**. Max file size: **10 MB**. + +--- + +## Tasks + +**GET /tasks** — Paginated list with filtering. +Query: `pageSize?`, `pageNumber?`, `sessionId?` (uuid), `filterBy?` (TaskStatus), `after?` (datetime), `before?` (datetime) +Response: `{ items: TaskItemView[], totalItems, pageNumber, pageSize }` + +**POST /tasks** — Create and run a task. Auto-creates session or uses existing. + +| Param | Type | Required | Description | +|-------|------|----------|-------------| +| task | string | **yes** | Task prompt (1-50,000 chars) | +| llm | SupportedLLMs | no | Model (default: browser-use-llm) | +| startUrl | string | no | Initial URL (saves steps) | +| maxSteps | integer | no | Max agent steps (default: 100) | +| structuredOutput | string | no | JSON schema string | +| sessionId | uuid | no | Run in existing session | +| metadata | object | no | Key-value metadata (string values) | +| secrets | object | no | Domain-scoped credentials (string values) | +| allowedDomains | string[] | no | Restrict navigation | +| opVaultId | string | no | 1Password vault ID | +| highlightElements | boolean | no | Highlight interactive elements | +| flashMode | boolean | no | Fast mode (skip evaluation/thinking) | +| thinking | boolean | no | Extended reasoning | +| vision | boolean\|"auto" | no | Screenshot mode | +| systemPromptExtension | string | no | Append to system prompt | +| judge | boolean | no | Enable quality judge | +| skillIds | string[] | no | Skills to use during task | + +Response (202): `{ id: uuid, sessionId: uuid }` +Errors: 400 (session busy/stopped), 404 (session not found), 422 (validation), 429 (rate limit) + +**GET /tasks/{task_id}** — Detailed task info with steps and output files. +Response: TaskView + +**GET /tasks/{task_id}/status** — Poll task status (lighter than full GET). +Response: `{ status: TaskStatus }` + +**PATCH /tasks/{task_id}** — Control task execution. +Body: `{ action: TaskUpdateAction }` — `stop`, `pause`, `resume`, or `stop_task_and_session` +Response: TaskView. Errors: 404, 422. + +**GET /tasks/{task_id}/logs** — Download URL for execution logs. +Response: `{ downloadUrl: string }`. Errors: 404, 500. + +--- + +## Sessions + +**GET /sessions** — Paginated list. +Query: `pageSize?`, `pageNumber?`, `filterBy?` (SessionStatus) + +**POST /sessions** — Create a session. +Body: `{ profileId?: uuid, proxyCountryCode?: string, startUrl?: string }` +Response (201): SessionItemView. Errors: 404 (profile not found), 429 (too many concurrent). + +**GET /sessions/{id}** — Session details with tasks and share URL. +Response: SessionView + +**PATCH /sessions/{id}** — Stop session and all running tasks. +Body: `{ action: "stop" }`. Errors: 404, 422. + +**POST /sessions/{id}/purge** — Purge session data. +Response: 200. + +**GET /sessions/{id}/public-share** — Get share info. +Response: ShareView. Errors: 404. + +**POST /sessions/{id}/public-share** — Create or return existing share. +Response (201): ShareView. + +**DELETE /sessions/{id}/public-share** — Remove share. +Response: 204. + +--- + +## Browsers (CDP) + +**POST /browsers** — Create a CDP browser session. + +| Param | Type | Required | Description | +|-------|------|----------|-------------| +| profileId | uuid | no | Browser profile | +| proxyCountryCode | string | no | Residential proxy (195+ countries) | +| timeout | integer | no | Session timeout in minutes (max 240) | +| browserScreenWidth | integer | no | Browser width in pixels | +| browserScreenHeight | integer | no | Browser height in pixels | +| customProxy | object | no | `{ host, port, username?, password? }` (HTTP or SOCKS5) | + +**Pricing:** $0.05/hour. Billed upfront, proportional refund on stop. Ceil to nearest minute (min 1 min). Free: 15 min max. Paid: 4 hours max. + +Response (201): BrowserSessionItemView (includes `cdpUrl` and `liveUrl`). +Errors: 403 (timeout exceeded for free), 404 (profile not found), 429 (too many concurrent). + +**GET /browsers/{id}** — Browser session details. + +**PATCH /browsers/{id}** — Stop browser (unused time refunded). +Body: `{ action: "stop" }` + +--- + +## Files + +**POST /files/sessions/{id}/presigned-url** — Get upload URL for session files. +Body: `{ fileName: string, contentType: UploadContentType, sizeBytes: integer }` +Response: `{ url: string, method: "POST", fields: {}, fileName: string, expiresIn: integer }` +Errors: 400 (unsupported type), 404, 500. + +**POST /files/browsers/{id}/presigned-url** — Same for browser sessions. + +**GET /files/tasks/{task_id}/output-files/{file_id}** — Download URL for task output. +Response: `{ id: uuid, fileName: string, downloadUrl: string }` +Errors: 404, 500. + +**Upload flow:** Get presigned URL → POST multipart form with returned `fields` + file → URL expires in 120s → Max 10 MB. + +--- + +## Profiles + +**GET /profiles** — Paginated list. Query: `pageSize?`, `pageNumber?` + +**POST /profiles** — Create profile (persistent cookies/localStorage between tasks). +Body: `{ name?: string }`. Response (201): ProfileView. Error: 402 (subscription needed). + +**GET /profiles/{id}** — Profile details. + +**DELETE /profiles/{id}** — Permanently delete. Response: 204. + +**PATCH /profiles/{id}** — Update name. Body: `{ name?: string }` + +--- + +## Skills + +**POST /skills** — Create a skill (turn a website into an API endpoint). +Body: `{ goal: string, agent_prompt: string, ... }` +Response: SkillView. + +**GET /skills** — List all skills. + +**GET /skills/{id}** — Get skill details. + +**POST /skills/{id}/execute** — Execute a skill. +Body: `{ parameters: {} }` + +**POST /skills/{id}/refine** — Refine with feedback (free). +Body: `{ feedback: string }` + +**POST /skills/{id}/cancel** — Cancel skill training. + +**POST /skills/{id}/rollback** — Rollback to previous version. + +**GET /skills/{id}/executions** — List skill executions. + +**GET /skills/{id}/executions/{eid}/output** — Get execution output. + +--- + +## Marketplace + +**GET /marketplace/skills** — Browse community skills. + +**GET /marketplace/skills/{slug}** — Get marketplace skill details. + +**POST /marketplace/skills/{id}/clone** — Clone skill to your workspace. + +**POST /marketplace/skills/{id}/execute** — Execute a marketplace skill. +Body: `{ parameters: {} }` + +--- + +## Billing + +**GET /billing/account** — Account info and credits. +Response: `{ name?, monthlyCreditsBalanceUsd, additionalCreditsBalanceUsd, totalCreditsBalanceUsd, rateLimit, planInfo: { planName, subscriptionStatus?, subscriptionId?, subscriptionCurrentPeriodEnd?, subscriptionCanceledAt? }, projectId }` + +--- + +## Pagination + +All list endpoints use page-based pagination: + +| Param | Type | Description | +|-------|------|-------------| +| pageSize | integer | Items per page | +| pageNumber | integer | Page number (1-based) | + +Response includes: `{ items: [...], totalItems, pageNumber, pageSize }` + +--- + +## Enums + +| Enum | Values | +|------|--------| +| TaskStatus | `started`, `paused`, `finished`, `stopped` | +| TaskUpdateAction | `stop`, `pause`, `resume`, `stop_task_and_session` | +| SessionStatus | `active`, `stopped` | +| BrowserSessionStatus | `active`, `stopped` | +| ProxyCountryCode | `us`, `uk`, `fr`, `it`, `jp`, `au`, `de`, `fi`, `ca`, `in` (+185 more) | +| SupportedLLMs | `browser-use-llm`, `gpt-4.1`, `gpt-4.1-mini`, `o4-mini`, `o3`, `gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-flash-latest`, `gemini-flash-lite-latest`, `claude-sonnet-4-20250514`, `gpt-4o`, `gpt-4o-mini`, `llama-4-maverick-17b-128e-instruct`, `claude-3-7-sonnet-20250219` | +| UploadContentType | `image/jpg`, `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/svg+xml`, `application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `text/plain`, `text/csv`, `text/markdown` | + +## Response Schemas + +**TaskItemView:** id, sessionId, llm, task, status, startedAt, finishedAt?, metadata?, output?, browserUseVersion?, isSuccess? + +**TaskView:** extends TaskItemView + steps: TaskStepView[], outputFiles: FileView[] + +**TaskStepView:** number, memory, evaluationPreviousGoal, nextGoal, url, screenshotUrl?, actions: string[] + +**FileView:** id, fileName + +**SessionItemView:** id, status, liveUrl?, startedAt, finishedAt? + +**SessionView:** extends SessionItemView + tasks: TaskItemView[], publicShareUrl? + +**BrowserSessionItemView:** id, status, liveUrl?, cdpUrl?, timeoutAt, startedAt, finishedAt? + +**ProfileView:** id, name?, lastUsedAt?, createdAt, updatedAt, cookieDomains?: string[] + +**ShareView:** shareToken, shareUrl, viewCount, lastViewedAt? + +**AccountView:** name?, monthlyCreditsBalanceUsd, additionalCreditsBalanceUsd, totalCreditsBalanceUsd, rateLimit, planInfo, projectId diff --git a/personas/_shared/community-skills/browser-use-cloud/references/api-v3.md b/personas/_shared/community-skills/browser-use-cloud/references/api-v3.md new file mode 100644 index 0000000..f1f6ef0 --- /dev/null +++ b/personas/_shared/community-skills/browser-use-cloud/references/api-v3.md @@ -0,0 +1,257 @@ +# BU Agent API (v3 — Experimental) + +Next-generation agent API. Session-based, token-based billing, workspaces, message history. + +## Table of Contents +- [Authentication](#authentication) +- [SDK Setup](#sdk-setup) +- [run() — Execute a Task](#run--execute-a-task) +- [REST Endpoints](#rest-endpoints) +- [Sessions](#sessions) +- [Messages](#messages) +- [Files](#files) +- [Workspaces](#workspaces) +- [Polling & Terminal Statuses](#polling--terminal-statuses) +- [Error Handling](#error-handling) +- [Session Statuses & Enums](#session-statuses--enums) +- [Response Schemas](#response-schemas) + +--- + +## Authentication + +- **Header:** `X-Browser-Use-API-Key: ` +- **Base URL:** `https://api.browser-use.com/api/v3` +- **Get key:** https://cloud.browser-use.com/new-api-key + +Same package as v2, different import path: + +## SDK Setup + +```python +# Python (async — recommended) +from browser_use_sdk.v3 import AsyncBrowserUse +client = AsyncBrowserUse() # Uses BROWSER_USE_API_KEY env var + +# Python (sync) +from browser_use_sdk.v3 import BrowserUse +client = BrowserUse() +``` + +```typescript +// TypeScript +import { BrowserUse } from "browser-use-sdk/v3"; +const client = new BrowserUse(); +``` + +Constructor: `api_key`, `base_url`, `timeout` (HTTP request timeout, not polling). + +## run() — Execute a Task + +```python +result = await client.run("Find the top HN post") +print(result.output) # str +print(result.id) # session UUID +print(result.status) # e.g. "idle" +print(result.total_cost_usd) # cost breakdown +``` + +### Parameters + +| Param | Type | Description | +|-------|------|-------------| +| task | string | **Required.** What to do. | +| model | string | `"bu-mini"` (default, faster/cheaper) or `"bu-max"` (more capable) | +| output_schema | Pydantic/Zod | Structured output schema | +| session_id | string | Reuse existing session | +| keep_alive | boolean | Keep session idle after task (default: false) | +| max_cost_usd | float | Cost cap in USD; agent stops if exceeded | +| profile_id | string | Browser profile UUID | +| proxy_country_code | string | Residential proxy country (195+ countries) | +| workspace_id | string | Attach workspace for file I/O | + +### Structured Output + +```python +from pydantic import BaseModel + +class Product(BaseModel): + name: str + price: float + +result = await client.run("Get product info", output_schema=Product) +print(result.output) # Product instance +``` + +### SessionResult Fields + +| Field | Type | Description | +|-------|------|-------------| +| output | str / BaseModel | Task result (typed if schema provided) | +| id | uuid | Session ID | +| status | string | Session status | +| model | string | bu-mini or bu-max | +| title | string? | Auto-generated title | +| live_url | string | Real-time browser monitoring URL | +| profile_id | string? | Echo of request | +| proxy_country_code | string? | Echo of request | +| max_cost_usd | float? | Echo of request | +| total_input_tokens | int | Input tokens used | +| total_output_tokens | int | Output tokens used | +| llm_cost_usd | string | LLM cost | +| proxy_cost_usd | string | Proxy cost | +| proxy_used_mb | string | Proxy data used | +| total_cost_usd | string | Total cost | +| created_at | datetime | Session creation time | +| updated_at | datetime | Last update time | + +--- + +## REST Endpoints + +All 16 endpoints in the v3 API: + +### Sessions + +**POST /sessions** — Create session and/or dispatch task. +Body: `{ task?, model?, session_id?, keep_alive?, max_cost_usd?, profile_id?, proxy_country_code?, output_schema? (JSON Schema dict) }` +Response: SessionView + +**GET /sessions** — List sessions. +Query: `page?` (int), `page_size?` (int) +Response: `{ sessions: SessionView[], total, page, page_size }` + +**GET /sessions/{id}** — Get session details (includes cost breakdown). +Response: SessionView + +**DELETE /sessions/{id}** — Delete session. +Response: 204 + +**POST /sessions/{id}/stop** — Stop session or task. +Query: `strategy?` — `"session"` (default, destroy sandbox) or `"task"` (stop task only, keep session alive) +Response: 200 + +### Messages + +**GET /sessions/{id}/messages** — Cursor-paginated message history. + +| Param | Type | Description | +|-------|------|-------------| +| limit | int | Max messages per page (default 50, max 100) | +| after | string | Cursor for forward pagination | +| before | string | Cursor for backward pagination | + +Response: `{ messages: [{ id, role: "user"|"assistant", data: string, timestamp }], next_cursor?, has_more: boolean }` + +### Files + +**GET /sessions/{id}/files** — List files in session workspace. + +| Param | Type | Description | +|-------|------|-------------| +| include_urls | boolean | Include presigned download URLs (60s expiry) | +| prefix | string | Filter by path prefix (e.g. `"outputs/"`) | +| limit | int | Max per page (default 50, max 100) | +| cursor | string | Pagination cursor | + +Response: `{ files: [{ path, size, last_modified, url? }], next_cursor?, has_more }` + +**POST /sessions/{id}/files/upload** — Get presigned upload URLs. +Body: `{ files: [{ name: string, content_type: string }] }` +Response: `{ files: [{ name, upload_url, path }] }` + +Upload via **PUT** to `upload_url` with matching `Content-Type` header. Max **10 files** per batch. Presigned URLs expire in **120 seconds**. Max file size: **10 MB**. + +### Workspaces + +**POST /workspaces** — Create persistent workspace. +Body: `{ name?: string, metadata?: object }` +Response: WorkspaceView + +**GET /workspaces** — List workspaces. +Query: `page?`, `page_size?` +Response: `{ items: WorkspaceView[], total, page, page_size }` + +**GET /workspaces/{id}** — Get workspace details. + +**PATCH /workspaces/{id}** — Update workspace. +Body: `{ name?: string, metadata?: object }` + +**DELETE /workspaces/{id}** — Delete workspace and all files (irreversible). + +**GET /workspaces/{id}/files** — List workspace files. +Query: `include_urls?`, `prefix?`, `limit?`, `cursor?` +Response: same format as session files + +**GET /workspaces/{id}/size** — Storage usage. +Response: `{ size_bytes: int, quota_bytes: int }` + +**POST /workspaces/{id}/files/upload** — Upload files to workspace. +Same format as session file upload. + +--- + +## Polling & Terminal Statuses + +`run()` polls automatically: +- **Interval:** 2 seconds +- **Timeout:** 300 seconds (5 minutes) — raises `TimeoutError` if exceeded +- **Terminal statuses:** `idle`, `stopped`, `timed_out`, `error` + +### Stop Strategies + +| Strategy | Behavior | +|----------|----------| +| `"session"` (default) | Destroy sandbox completely | +| `"task"` | Stop current task, keep session alive for follow-ups | + +```python +await client.sessions.stop(session_id, strategy="task") # keep session +await client.sessions.stop(session_id, strategy="session") # destroy +``` + +--- + +## Error Handling + +```python +from browser_use_sdk.v3 import AsyncBrowserUse, BrowserUseError + +try: + result = await client.run("Do something") +except TimeoutError: + print("Polling timed out (5 min default)") +except BrowserUseError as e: + print(f"API error: {e}") +``` + +--- + +## Session Statuses & Enums + +| Status | Description | +|--------|-------------| +| `created` | Session created, not yet running | +| `idle` | Task completed, session still alive (keep_alive=True) | +| `running` | Task in progress | +| `stopped` | Manually stopped | +| `timed_out` | Session timed out | +| `error` | Session errored | + +**Models:** `bu-mini` (default, faster/cheaper), `bu-max` (more capable) + +## Response Schemas + +**SessionView (v3):** id, status, model, title?, live_url, output?, profile_id?, proxy_country_code?, max_cost_usd?, total_input_tokens, total_output_tokens, llm_cost_usd, proxy_cost_usd, proxy_used_mb, total_cost_usd, created_at, updated_at + +**MessageView:** id, role ("user"|"assistant"), data (string), timestamp + +**FileInfo:** path, size, last_modified, url? + +**WorkspaceView:** id, name?, metadata?, created_at, updated_at, size_bytes? + +**Key concepts:** +- **Autonomous execution** — agent decides how many steps (no max_steps param) +- **Cost control** — `max_cost_usd` caps spending; check `total_cost_usd` on result +- **Integrations** — agent auto-discovers third-party services (email, Slack, calendars) +- **File I/O** — upload before task, download from workspace after. Max 10 files per batch, download URLs expire in 60s diff --git a/personas/_shared/community-skills/browser-use-cloud/references/browser-api.md b/personas/_shared/community-skills/browser-use-cloud/references/browser-api.md new file mode 100644 index 0000000..c8ec6ac --- /dev/null +++ b/personas/_shared/community-skills/browser-use-cloud/references/browser-api.md @@ -0,0 +1,122 @@ +# Browser API (Direct CDP Access) + +Connect directly to Browser Use stealth browsers via Chrome DevTools Protocol. + +## Table of Contents +- [WebSocket Connection](#websocket-connection) +- [SDK Approach](#sdk-approach) +- [Playwright Integration](#playwright-integration) +- [Puppeteer Integration](#puppeteer-integration) +- [Selenium Integration](#selenium-integration) + +--- + +## WebSocket Connection + +Single URL with all config as query params. Browser **auto-starts on connect** and **auto-stops on disconnect** — no REST calls needed to start or stop. + +``` +wss://connect.browser-use.com?apiKey=YOUR_KEY&proxyCountryCode=us&timeout=30 +``` + +CDP discovery is also available over HTTPS (for tools that use HTTP auto-discovery): +``` +https://connect.browser-use.com/json/version?apiKey=YOUR_API_KEY +``` + +### Query Parameters + +| Param | Required | Description | +|-------|----------|-------------| +| `apiKey` | **yes** | API key | +| `proxyCountryCode` | no | Residential proxy country (195+ countries) | +| `profileId` | no | Browser profile UUID | +| `timeout` | no | Session timeout in minutes (max 240) | +| `browserScreenWidth` | no | Browser width in pixels | +| `browserScreenHeight` | no | Browser height in pixels | +| `customProxy.host` | no | Custom proxy host | +| `customProxy.port` | no | Custom proxy port | +| `customProxy.username` | no | Custom proxy username | +| `customProxy.password` | no | Custom proxy password | + +## SDK Approach + +```python +# Create browser +browser = await client.browsers.create( + profile_id="uuid", + proxy_country_code="us", + timeout=60, +) + +print(browser.cdp_url) # wss://... for CDP connection +print(browser.live_url) # View in browser + +# Stop (unused time refunded) +await client.browsers.stop(browser.id) +``` + +## Playwright Integration + +```python +from playwright.async_api import async_playwright + +# Create cloud browser +browser_session = await client.browsers.create(proxy_country_code="us") + +# Connect Playwright +pw = await async_playwright().start() +browser = await pw.chromium.connect_over_cdp(browser_session.cdp_url) +page = browser.contexts[0].pages[0] + +# Normal Playwright code +await page.goto("https://example.com") +await page.fill("#email", "user@example.com") +await page.click("button[type=submit]") +content = await page.content() + +# Cleanup +await pw.stop() +await client.browsers.stop(browser_session.id) +``` + +## Puppeteer Integration + +```javascript +const puppeteer = require('puppeteer-core'); + +const browser = await client.browsers.create({ proxyCountryCode: 'us' }); +const puppeteerBrowser = await puppeteer.connect({ browserWSEndpoint: browser.cdpUrl }); +const page = (await puppeteerBrowser.pages())[0]; + +await page.goto('https://example.com'); +// ... normal Puppeteer code + +await puppeteerBrowser.close(); +await client.browsers.stop(browser.id); +``` + +## Selenium Integration + +```python +from selenium import webdriver +from selenium.webdriver.chrome.options import Options + +browser_session = await client.browsers.create(proxy_country_code="us") + +options = Options() +options.debugger_address = browser_session.cdp_url.replace("wss://", "").replace("ws://", "").replace("/devtools/browser/", "") +driver = webdriver.Chrome(options=options) + +driver.get("https://example.com") +# ... normal Selenium code + +driver.quit() +await client.browsers.stop(browser_session.id) +``` + +### Session Limits + +- Free: 15 minutes max +- Paid: 4 hours max +- Pricing: $0.05/hour, billed upfront, proportional refund on early stop, min 1 minute diff --git a/personas/_shared/community-skills/browser-use-cloud/references/features.md b/personas/_shared/community-skills/browser-use-cloud/references/features.md new file mode 100644 index 0000000..55a1a4a --- /dev/null +++ b/personas/_shared/community-skills/browser-use-cloud/references/features.md @@ -0,0 +1,231 @@ +# Cloud Features + +## Table of Contents +- [Proxies & Stealth](#proxies--stealth) +- [Webhooks](#webhooks) +- [Workspaces](#workspaces) +- [Skills](#skills) +- [MCP Server](#mcp-server) +- [Live View](#live-view) + +--- + +## Proxies & Stealth + +Stealth is on by default — anti-fingerprinting, CAPTCHA solving, ad/cookie blocking, Cloudflare bypass. + +### Residential Proxies (195+ Countries) + +Default: US residential proxy always active. + +```python +# Common countries +session = await client.sessions.create(proxy_country_code="us") # or gb, de, fr, jp, au, br, in, kr, ca, es, it, nl, se, sg... +``` + +### Custom Proxy (HTTP or SOCKS5) + +```python +from browser_use_sdk import CustomProxy + +session = await client.sessions.create( + custom_proxy=CustomProxy( + url="http://proxy-host:8080", + username="user", + password="pass", + ) +) +``` + +### Disable Proxy (Not Recommended) + +```python +session = await client.sessions.create(proxy_country_code=None) +``` + +--- + +## Webhooks + +Real-time notifications when tasks complete. + +### Events + +| Event | Description | +|-------|-------------| +| `agent.task.status_update` | Task status changed (started/finished/stopped) | +| `test` | Test webhook delivery | + +### Payload + +```json +{ + "type": "agent.task.status_update", + "timestamp": "2025-01-15T10:30:00Z", + "payload": { + "task_id": "task_abc123", + "session_id": "session_xyz", + "status": "finished", + "metadata": {} + } +} +``` + +### Signature Verification (HMAC-SHA256) + +Headers: `X-Browser-Use-Signature`, `X-Browser-Use-Timestamp` + +The signature is computed over `{timestamp}.{body}` where body is JSON with sorted keys and no extra whitespace. Reject requests older than 5 minutes to prevent replay attacks. + +```python +import hmac, hashlib, json, time + +def verify_webhook(body: bytes, signature: str, timestamp: str, secret: str) -> bool: + # Reject requests older than 5 minutes + try: + ts = int(timestamp) + except (ValueError, TypeError): + return False + if abs(time.time() - ts) > 300: + return False + try: + payload = json.loads(body) + except (json.JSONDecodeError, ValueError): + return False + message = f"{timestamp}.{json.dumps(payload, separators=(',', ':'), sort_keys=True)}" + expected = hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest() + return hmac.compare_digest(expected, signature) +``` + +--- + +## Workspaces + +Persistent file storage across sessions (v3 API). Max 10 files per upload. + +```python +from browser_use_sdk.v3 import AsyncBrowserUse +client = AsyncBrowserUse() + +# Create workspace +workspace = await client.workspaces.create(name="my-data") + +# Create a session +session = await client.sessions.create() + +# Upload files before task +await client.sessions.upload_files( + session.id, + workspace_id=workspace.id, + files=[open("input.pdf", "rb")] +) + +# Download files after task +files = await client.sessions.files(session.id) +for f in files: + url = f.download_url # Presigned URL (60s expiry) + +# Manage workspaces +workspaces = await client.workspaces.list() +await client.workspaces.delete(workspace.id) +``` + +--- + +## Skills + +Turn website interactions into reusable, deterministic API endpoints. + +### Anatomy + +- **Goal**: Full spec with parameters and return data +- **Demonstration**: agent_prompt showing how to perform the task once + +### Create & Execute + +```python +# Create (~30s, $2 PAYG) +skill = await client.skills.create( + goal="Extract product price from Amazon", + demonstration="Navigate to product page, find price element..." +) + +# Execute ($0.02 PAYG) +result = await client.skills.execute(skill.id, params={"url": "https://amazon.com/dp/..."}) + +# Refine (free) +await client.skills.refine(skill.id, feedback="Also extract the rating") +``` + +### Marketplace + +```python +skills = await client.marketplace.list() +cloned = await client.marketplace.clone(skill_id) +result = await client.marketplace.execute(skill_id, params={}) +``` + +Browse at [cloud.browser-use.com/skills](https://cloud.browser-use.com/skills). + +### Load Skills in Local Agent + +```python +agent = Agent( + task="...", + skills=['skill-uuid-1', 'skill-uuid-2'], # or ['*'] for all + llm=ChatBrowserUse() +) +``` + +--- + +## MCP Server + +HTTP-based MCP at `https://api.browser-use.com/mcp` + +| Tool | Cost | Description | +|------|------|-------------| +| `browser_task` | $0.01 + per-step | Run automation task | +| `execute_skill` | $0.02 | Execute skill | +| `list_skills` | Free | List skills | +| `get_cookies` | Free | Get cookies | +| `list_browser_profiles` | Free | List profiles | +| `monitor_task` | Free | Check task progress | + +Setup: See `references/open-source/integrations.md` for Claude/Cursor/Windsurf config. + +--- + +## Live View + +### Human Takeover + +Pause agent, let human take over via `liveUrl`: + +```python +session = await client.sessions.create(keep_alive=True) # v3 +await client.run("Navigate to checkout", session_id=session.id) +# Agent pauses at checkout + +print(session.live_url) # Human opens this, enters payment details + +await client.run("Confirm the order", session_id=session.id) +await client.sessions.stop(session.id) +``` + +`liveUrl` gives full mouse/keyboard control. + +### Iframe Embed + +Embed live view in your app — no X-Frame-Options or CSP restrictions: + +```html + +``` + +No polling needed — updates in real-time. diff --git a/personas/_shared/community-skills/browser-use-cloud/references/guides/chat-ui.md b/personas/_shared/community-skills/browser-use-cloud/references/guides/chat-ui.md new file mode 100644 index 0000000..75b68d5 --- /dev/null +++ b/personas/_shared/community-skills/browser-use-cloud/references/guides/chat-ui.md @@ -0,0 +1,237 @@ +# Guide: Building a Chat Interface + +Build a conversational UI where users chat with a Browser Use agent and watch it work in real-time. + +## Table of Contents +- [Prerequisites](#prerequisites) +- [Architecture](#architecture) +- [SDK Setup](#sdk-setup) +- [Creating a Session](#creating-a-session) +- [Polling Messages](#polling-messages) +- [Sending Follow-ups](#sending-follow-ups) +- [Stopping Tasks](#stopping-tasks) +- [Live Browser View](#live-browser-view) +- [Python Equivalent](#python-equivalent) +- [SDK Methods Summary](#sdk-methods-summary) + +--- + +## Prerequisites + +- You have a web app (or are building one) — Next.js/React shown, but the SDK calls work from any backend +- You're using the **Cloud API** because you need `liveUrl` for real-time browser streaming +- `BROWSER_USE_API_KEY` from https://cloud.browser-use.com/new-api-key + +## Architecture + +Two pages: +1. **Home** — user types a task → app creates an idle session → navigates to session page → fires task +2. **Session** — polls for messages, shows live browser in iframe, lets user send follow-ups + +All SDK calls live in a single API file. The key pattern: create session first (instant), dispatch task second (fire-and-forget), navigate immediately so the user sees the browser while the task starts. + +## SDK Setup + +Uses both SDK versions — v3 for sessions/messages, v2 for profiles (not on v3 yet). + +```typescript +// api.ts +import { BrowserUse as BrowserUseV3 } from "browser-use-sdk/v3"; +import { BrowserUse as BrowserUseV2 } from "browser-use-sdk"; + +const apiKey = process.env.NEXT_PUBLIC_BROWSER_USE_API_KEY ?? ""; +const v3 = new BrowserUseV3({ apiKey }); +const v2 = new BrowserUseV2({ apiKey }); +``` + +> **Warning:** `NEXT_PUBLIC_` exposes the key to the browser. In production, move SDK calls to server actions or API routes. + +## Creating a Session + +Two functions: one creates an idle session, another dispatches a task into it. + +```typescript +// api.ts +export async function createSession(opts: { + model: string; + profileId?: string; + proxyCountryCode?: string; +}) { + return v3.sessions.create({ + model: opts.model as "bu-mini" | "bu-max", + keepAlive: true, // Keep session open for follow-ups + ...(opts.profileId && { profileId: opts.profileId }), + ...(opts.proxyCountryCode && { proxyCountryCode: opts.proxyCountryCode }), + }); +} + +export async function sendTask(sessionId: string, task: string) { + return v3.sessions.create({ sessionId, task, keepAlive: true }); +} +``` + +### Page flow — fire-and-forget for instant navigation + +```typescript +// page.tsx +async function handleSend(message: string) { + // 1. Create idle session + const session = await createSession({ model }); + + // 2. Navigate immediately (user sees browser while task dispatches) + router.push(`/session/${session.id}`); + + // 3. Fire-and-forget the task + sendTask(session.id, message).catch(console.error); +} +``` + +### Populate dropdowns + +```typescript +export async function listProfiles() { + return v2.profiles.list({ pageSize: 100 }); +} + +export async function listWorkspaces() { + return v3.workspaces.list({ pageSize: 100 }); +} +``` + +## Polling Messages + +Poll session status and messages at 1s intervals. Stop when terminal. + +```typescript +// api.ts +export async function getSession(id: string) { + return v3.sessions.get(id); +} + +export async function getMessages(id: string, limit = 100) { + return v3.sessions.messages(id, { limit }); +} +``` + +### React Query polling + +```typescript +// session-context.tsx +const TERMINAL = new Set(["stopped", "error", "timed_out"]); + +// Poll session status every 1s +const { data: session } = useQuery({ + queryKey: ["session", sessionId], + queryFn: () => api.getSession(sessionId), + refetchInterval: (query) => { + const s = query.state.data?.status; + return s && TERMINAL.has(s) ? false : 1000; + }, +}); + +const isTerminal = !!session && TERMINAL.has(session.status); +const isActive = !!session && !isTerminal; + +// Poll messages every 1s while active +const { data: rawResponse } = useQuery({ + queryKey: ["messages", sessionId], + queryFn: () => api.getMessages(sessionId), + refetchInterval: isActive ? 1000 : false, +}); +``` + +## Sending Follow-ups + +Reuse `sendTask` with optimistic updates so messages appear instantly: + +```typescript +const sendMessage = useCallback(async (task: string) => { + const tempMsg = { + id: `opt-${Date.now()}`, + role: "user", + content: task, + createdAt: new Date().toISOString(), + }; + setOptimistic((prev) => [...prev, tempMsg]); + + try { + await api.sendTask(sessionId, task); + } catch (err) { + setOptimistic((prev) => prev.filter((m) => m.id !== tempMsg.id)); + } +}, [sessionId]); +``` + +## Stopping Tasks + +Stop the current task but keep the session alive for follow-ups: + +```typescript +export async function stopTask(id: string) { + await v3.sessions.stop(id, { strategy: "task" }); +} +``` + +`strategy: "task"` stops only the running task. `strategy: "session"` would destroy the sandbox entirely. + +## Live Browser View + +Every session has a `liveUrl`. Embed it in an iframe — no X-Frame-Options or CSP restrictions: + +```tsx +