diff --git a/.cursor/skills/alert-manager/SKILL.md b/.cursor/skills/alert-manager/SKILL.md new file mode 100644 index 0000000000..3cece47ca5 --- /dev/null +++ b/.cursor/skills/alert-manager/SKILL.md @@ -0,0 +1,337 @@ +--- +name: alert-manager +description: 'Configure SEO alerts for ranking drops, traffic changes, technical issues, competitor movements. SEO预警/排名监控' +version: "6.0.0" +license: Apache-2.0 +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when setting up monitoring alerts for rankings, traffic, backlinks, technical issues, or AI visibility changes." +argument-hint: " [metric]" +metadata: + author: aaron-he-zhu + version: "6.0.0" + geo-relevance: "low" + tags: + - seo + - geo + - seo-alerts + - ranking-alerts + - traffic-monitoring + - competitor-alerts + - automated-monitoring + - anomaly-detection + - SEO预警 + - SEOアラート + - SEO알림 + - alertas-seo + triggers: + # EN-formal + - "set up SEO alerts" + - "monitor rankings" + - "ranking notifications" + - "traffic alerts" + - "competitor alerts" + - "automated monitoring" + # EN-casual + - "notify me when rankings drop" + - "alert me if rankings drop" + - "notify me of traffic changes" + - "watch competitor changes" + - "watch my keywords for changes" + - "alert me about changes" + # EN-question + - "how to monitor my rankings" + - "how to set up SEO alerts" + # ZH-pro + - "SEO预警" + - "排名监控" + - "流量报警" + - "竞品变动提醒" + # ZH-casual + - "排名掉了提醒我" + - "流量异常" + - "有变化通知我" + # JA + - "SEOアラート" + - "ランキング監視" + # KO + - "SEO 알림" + - "순위 모니터링" + # ES + - "alertas SEO" + - "monitoreo de rankings" + # PT + - "alertas de SEO" + # Misspellings + - "SEO allerts" +--- + +# Alert Manager + + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This monitoring skill follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + + +Sets up proactive monitoring alerts for critical SEO and GEO metrics. Triggers notifications when rankings drop, traffic changes significantly, technical issues occur, or competitors make moves. + +**System role**: Monitoring layer skill. It turns performance changes into deltas, alerts, and next actions. + +## When This Must Trigger + +Use this when the conversation involves any of these situations — even if the user does not use SEO terminology: + +Use this whenever the task needs time-aware change detection, escalation, or stakeholder-ready visibility. + +- Setting up SEO monitoring systems +- Creating ranking drop alerts +- Monitoring technical SEO health +- Tracking competitor movements +- Alerting on content performance changes +- Monitoring GEO/AI visibility changes +- Setting up brand mention alerts + +## What This Skill Does + +1. **Alert Configuration**: Sets up custom alert thresholds +2. **Multi-Metric Monitoring**: Tracks rankings, traffic, technical issues +3. **Threshold Management**: Defines when alerts trigger +4. **Priority Classification**: Categorizes alerts by severity +5. **Notification Setup**: Configures how alerts are delivered +6. **Alert Response Plans**: Creates action plans for each alert type +7. **Alert History**: Tracks alert patterns over time + +## Quick Start + +Start with one of these prompts. Finish with a short handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Set Up Alerts + +``` +Set up SEO monitoring alerts for [domain] +``` + +``` +Create ranking drop alerts for my top 20 keywords +``` + +### Configure Specific Alerts + +``` +Alert me when [specific condition] +``` + +``` +Set up competitor monitoring for [competitor domains] +``` + +### Review Alert System + +``` +Review and optimize my current SEO alerts +``` + +## Skill Contract + +**Expected output**: a delta summary, alert/report output, and a short handoff summary ready for `memory/monitoring/`. + +- **Reads**: current metrics, previous baselines, alert thresholds, and reporting context from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available. +- **Writes**: a user-facing monitoring deliverable plus a reusable summary that can be stored under `memory/monitoring/`. +- **Promotes**: significant changes, confirmed anomalies, and follow-up actions to `memory/open-loops.md` and `memory/decisions.md`. +- **Next handoff**: use the `Next Best Skill` below when a change needs action. + +## Data Sources + +> **Note:** All integrations are optional. This skill works without any API keys — users provide data manually when no tools are connected. + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +**With ~~SEO tool + ~~search console + ~~web crawler connected:** +Automatically monitor real-time metric feeds for ranking changes via ~~SEO tool API, indexing and coverage alerts from ~~search console, and technical health alerts from ~~web crawler. Set up automated threshold-based alerts with notification delivery. + +**With manual data only:** +Ask the user to provide: +1. Current baseline metrics for alert thresholds (rankings, traffic, backlinks) +2. Critical keywords or pages to monitor +3. Alert priority levels and notification preferences +4. Historical data to understand normal fluctuation ranges +5. Manual reporting on metric changes when they check their tools + +Proceed with the alert configuration using provided parameters. User will need to manually check metrics and report changes for alert triggers. + +## Instructions + +When a user requests alert setup: + +1. **Define Alert Categories** + + ```markdown + ## SEO Alert System Configuration + + **Domain**: [domain] + **Configured Date**: [date] + + ### Alert Categories + + | Category | Description | Typical Urgency | + |----------|-------------|-----------------| + | Ranking Alerts | Keyword position changes | Medium-High | + | Traffic Alerts | Organic traffic fluctuations | High | + | Technical Alerts | Site health issues | Critical | + | Backlink Alerts | Link profile changes | Medium | + | Competitor Alerts | Competitor movements | Low-Medium | + | GEO Alerts | AI visibility changes | Medium | + | Brand Alerts | Brand mentions and reputation | Medium | + ``` + +2. **Configure Alert Rules by Category** + + For each relevant category (Rankings, Traffic, Technical, Backlinks, Competitors, GEO/AI, Brand), define alert name, trigger condition, threshold, and priority level. + + > **Reference**: See [references/alert-configuration-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/alert-manager/references/alert-configuration-templates.md) for complete alert tables, threshold examples, and response plan templates for all 7 categories. + +3. **Define Alert Response Plans** + + Map each priority level (Critical, High, Medium, Low) to a response time and immediate action steps. + +4. **Set Up Alert Delivery** + + Configure notification channels (Email, SMS, Slack), recipient routing by role, suppression rules (duplicate cooldown, maintenance windows), and escalation paths. + +5. **Create Alert Summary** + + ```markdown + # SEO Alert System Summary + + **Domain**: [domain] + **Configured**: [date] + **Total Active Alerts**: [X] + + ## Alert Count by Category + + | Category | Critical | High | Medium | Low | Total | + |----------|----------|------|--------|-----|-------| + | Rankings | [X] | [X] | [X] | [X] | [X] | + | Traffic | [X] | [X] | [X] | [X] | [X] | + | Technical | [X] | [X] | [X] | [X] | [X] | + | Backlinks | [X] | [X] | [X] | [X] | [X] | + | Competitors | [X] | [X] | [X] | [X] | [X] | + | GEO | [X] | [X] | [X] | [X] | [X] | + | **Total** | **[X]** | **[X]** | **[X]** | **[X]** | **[X]** | + + ## Quick Reference + + ### If You Get a Critical Alert + + 1. Don't panic + 2. Check alert details + 3. Follow response plan + 4. Document actions taken + 5. Update stakeholders + + ### Weekly Alert Review Checklist + + - [ ] Review all alerts triggered + - [ ] Identify patterns + - [ ] Adjust thresholds if needed + - [ ] Update response plans + - [ ] Clean up false positives + ``` + +## Validation Checkpoints + +### Input Validation +- [ ] Alert thresholds are based on realistic baseline data +- [ ] Critical keywords and pages clearly identified +- [ ] Response plans defined for each alert priority level +- [ ] Notification channels configured with appropriate recipients + +### Output Validation +- [ ] Every metric cites its data source and collection date +- [ ] Alert thresholds account for normal metric fluctuations +- [ ] Response plans are specific and time-bound +- [ ] Source of each alert trigger clearly stated (~~SEO tool API alert, ~~search console notification, ~~web crawler alert, or manual user check) + +## Example + +**User**: "Set up ranking drop alerts for my top keywords" + +**Output**: + +```markdown +## Ranking Alert Configuration + +### Critical Keywords (Immediate Alert) + +| Keyword | Current | Alert If | Priority | +|---------|---------|----------|----------| +| best project management software | 2 | Drops to 5+ | 🔴 Critical | +| project management tools | 4 | Drops to 8+ | 🔴 Critical | +| team collaboration software | 1 | Any drop | 🔴 Critical | + +### Important Keywords (Same-Day Alert) + +| Keyword | Current | Alert If | Priority | +|---------|---------|----------|----------| +| agile project management | 7 | Drops out of top 10 | 🔴 High | +| kanban software | 9 | Drops out of top 10 | 🔴 High | + +### Alert Response Plan + +**If Critical Keyword Drops**: +1. Check if page is still indexed (site:url) +2. Look for algorithm update announcements +3. Analyze what changed in SERP +4. Review competitor ranking changes +5. Check for technical issues on page +6. Create recovery action plan within 24 hours + +**Notification**: Email + Slack to SEO team immediately +``` + +## Tips for Success + +1. **Start simple** - Don't create too many alerts initially +2. **Tune thresholds** - Adjust based on normal fluctuations +3. **Avoid alert fatigue** - Too many alerts = ignored alerts +4. **Document response plans** - Know what to do when alerts fire +5. **Review regularly** - Alerts need maintenance as your SEO matures +6. **Include positive alerts** - Track wins, not just problems + +## Alert Threshold Quick Reference + +| Metric | Warning | Critical | Frequency | +|--------|---------|----------|-----------| +| Organic traffic | -15% WoW | -30% WoW | Daily | +| Keyword positions | >3 position drop | >5 position drop | Daily | +| Pages indexed | -5% change | -20% change | Weekly | +| Crawl errors | >10 new/day | >50 new/day | Daily | +| Core Web Vitals | "Needs Improvement" | "Poor" | Weekly | +| Backlinks lost | >5% in 1 week | >15% in 1 week | Weekly | +| AI citation loss | Any key query | >20% queries | Weekly | +| Security issues | Any detected | Any detected | Daily | + +> **Reference**: See [references/alert-threshold-guide.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/alert-manager/references/alert-threshold-guide.md) for baseline establishment, threshold setting methodology, fatigue prevention, escalation paths, and response playbooks. + + +### Save Results + +After delivering monitoring data or reports to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to `memory/monitoring/YYYY-MM-DD-.md` containing: +- One-line headline finding or status change +- Top 3-5 actionable items +- Open loops or anomalies requiring follow-up +- Source data references + +If any findings should influence ongoing strategy, recommend promoting key conclusions to `memory/hot-cache.md`. + +## Reference Materials + +- [Alert Threshold Guide](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/alert-manager/references/alert-threshold-guide.md) — Recommended thresholds by metric, fatigue prevention strategies, and escalation path templates + +## Next Best Skill + +- **Primary**: [rank-tracker](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/rank-tracker/SKILL.md) — pair alerts with a baseline measurement workflow. diff --git a/.cursor/skills/alert-manager/references/alert-configuration-templates.md b/.cursor/skills/alert-manager/references/alert-configuration-templates.md new file mode 100644 index 0000000000..c962aed99a --- /dev/null +++ b/.cursor/skills/alert-manager/references/alert-configuration-templates.md @@ -0,0 +1,293 @@ +# Alert Configuration Templates + +Detailed alert configuration templates for each alert category. Use these templates when setting up a new alert system for a domain. + +--- + +## Ranking Alerts + +### Position Drop Alerts + +| Alert Name | Condition | Threshold | Priority | Action | +|------------|-----------|-----------|----------|--------| +| Critical Drop | Any top 3 keyword drops 5+ positions | Position change >=5 | Critical | Immediate investigation | +| Major Drop | Top 10 keyword drops out of top 10 | Position >10 | High | Same-day review | +| Moderate Drop | Any keyword drops 10+ positions | Position change >=10 | Medium | Weekly review | +| Competitor Overtake | Competitor passes you for key term | Comp position < yours | Medium | Analysis needed | + +### Position Improvement Alerts + +| Alert Name | Condition | Threshold | Priority | +|------------|-----------|-----------|----------| +| New Top 3 | Keyword enters top 3 | Position <=3 | Positive | +| Page 1 Entry | Keyword enters top 10 | Position <=10 | Positive | +| Significant Climb | Keyword improves 10+ positions | Change >=+10 | Positive | + +### SERP Feature Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| Snippet Lost | Lost featured snippet ownership | High | +| Snippet Won | Won new featured snippet | Positive | +| AI Overview Change | Appeared/disappeared in AI Overview | Medium | + +### Keywords to Monitor + +| Keyword | Current Rank | Alert Threshold | Priority | +|---------|--------------|-----------------|----------| +| [keyword 1] | [X] | Drop >=3 | Critical | +| [keyword 2] | [X] | Drop >=5 | High | +| [keyword 3] | [X] | Drop >=10 | Medium | + +--- + +## Traffic Alerts + +### Traffic Decline Alerts + +| Alert Name | Condition | Threshold | Priority | +|------------|-----------|-----------|----------| +| Traffic Crash | Day-over-day decline | >=50% drop | Critical | +| Significant Drop | Week-over-week decline | >=30% drop | High | +| Moderate Decline | Month-over-month decline | >=20% drop | Medium | +| Trend Warning | 3 consecutive weeks decline | Any decline | Medium | + +### Traffic Anomaly Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| Traffic Spike | Unusual increase | Investigate | +| Zero Traffic | Page receiving 0 visits | High | +| Bot Traffic | Unusual traffic pattern | Medium | + +### Page-Level Alerts + +| Page Type | Alert Condition | Priority | +|-----------|-----------------|----------| +| Homepage | Any 20%+ decline | Critical | +| Top 10 pages | Any 30%+ decline | High | +| Conversion pages | Any 25%+ decline | High | +| Blog posts | Any 40%+ decline | Medium | + +### Conversion Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| Conversion Drop | Organic conversions down 30%+ | Critical | +| CVR Decline | Conversion rate drops 20%+ | High | + +--- + +## Technical SEO Alerts + +### Critical Technical Alerts + +| Alert Name | Condition | Priority | Response Time | +|------------|-----------|----------|---------------| +| Site Down | HTTP 5xx errors | Critical | Immediate | +| SSL Expiry | Certificate expiring in 14 days | Critical | Same day | +| Robots.txt Block | Important pages blocked | Critical | Same day | +| Index Dropped | Pages dropping from index | Critical | Same day | + +### Crawl & Index Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| Crawl Errors Spike | Errors increase 50%+ | High | +| New 404 Pages | 404 errors on important pages | Medium | +| Redirect Chains | 3+ redirect hops detected | Medium | +| Duplicate Content | New duplicates detected | Medium | +| Index Coverage Drop | Indexed pages decline 10%+ | High | + +### Performance Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| Core Web Vitals Fail | CWV drops to "Poor" | High | +| Page Speed Drop | Load time increases 50%+ | Medium | +| Mobile Issues | Mobile usability errors | High | + +### Security Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| Security Issue | GSC security warning | Critical | +| Manual Action | Google manual action | Critical | +| Malware Detected | Site flagged for malware | Critical | + +--- + +## Backlink Alerts + +### Link Loss Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| High-Value Link Lost | DA 70+ link removed | High | +| Multiple Links Lost | 10+ links lost in a day | Medium | +| Referring Domain Lost | Lost entire domain's links | Medium | + +### Link Gain Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| High-Value Link | New DA 70+ link | Positive | +| Suspicious Links | Many low-quality links | Review | +| Negative SEO | Spam link attack pattern | High | + +### Link Profile Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| Toxic Score Increase | Toxic score up 20%+ | High | +| Anchor Over-Optimization | Exact match anchors >30% | Medium | + +--- + +## Competitor Monitoring Alerts + +### Ranking Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| Competitor Overtake | Competitor passes you | Medium | +| Competitor Top 3 | Competitor enters top 3 on key term | Medium | +| Competitor Content | Competitor publishes on your topic | Info | + +### Activity Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| New Backlinks | Competitor gains high-DA link | Info | +| Content Update | Competitor updates ranking content | Info | +| New Content | Competitor publishes new content | Info | + +### Competitors to Monitor + +| Competitor | Domain | Monitor Keywords | Alert Priority | +|------------|--------|------------------|----------------| +| [Competitor 1] | [domain] | [X] keywords | High | +| [Competitor 2] | [domain] | [X] keywords | Medium | +| [Competitor 3] | [domain] | [X] keywords | Low | + +--- + +## GEO (AI Visibility) Alerts + +### AI Citation Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| Citation Lost | Lost AI Overview citation | Medium | +| Citation Won | New AI Overview citation | Positive | +| Citation Position Drop | Dropped from 1st to 3rd+ source | Medium | +| New AI Overview | AI Overview appears for tracked keyword | Info | + +### GEO Trend Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| Citation Rate Drop | AI citation rate drops 20%+ | High | +| GEO Competitor | Competitor cited where you're not | Medium | + +--- + +## Brand Monitoring Alerts + +### Mention Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| Brand Mention | New brand mention online | Info | +| Negative Mention | Negative sentiment mention | High | +| Review Alert | New review on key platforms | Medium | +| Unlinked Mention | Brand mention without link | Opportunity | + +### Reputation Alerts + +| Alert Name | Condition | Priority | +|------------|-----------|----------| +| Review Rating Drop | Average rating drops | High | +| Negative Press | Negative news article | High | +| Competitor Comparison | Named in competitor comparison | Medium | + +--- + +## Alert Response Plans + +### Critical Alert Response + +**Response Time**: Immediate (within 1 hour) + +| Alert Type | Immediate Actions | +|------------|-------------------| +| Site Down | 1. Check server status 2. Contact hosting 3. Check DNS | +| Traffic Crash | 1. Check for algorithm update 2. Review GSC errors 3. Check competitors | +| Manual Action | 1. Review GSC message 2. Identify issue 3. Begin remediation | +| Critical Rank Drop | 1. Check if page indexed 2. Review SERP 3. Analyze competitors | + +### High Priority Response + +**Response Time**: Same day + +| Alert Type | Actions | +|------------|---------| +| Major Rank Drops | Analyze cause, create recovery plan | +| Traffic Decline | Investigate source, check technical issues | +| Backlink Loss | Attempt recovery outreach | +| CWV Failure | Diagnose and fix performance issues | + +### Medium Priority Response + +**Response Time**: Within 48 hours + +| Alert Type | Actions | +|------------|---------| +| Moderate Rank Changes | Monitor trend, plan content updates | +| Competitor Movement | Analyze competitor changes | +| New 404s | Set up redirects, update internal links | + +### Low Priority + +**Response Time**: Weekly review + +| Alert Type | Actions | +|------------|---------| +| Positive Changes | Document wins, understand cause | +| Info Alerts | Log for trend analysis | + +--- + +## Alert Notification Setup + +### Notification Channels + +| Priority | Channels | Frequency | +|----------|----------|-----------| +| Critical | Email + SMS + Slack | Immediate | +| High | Email + Slack | Immediate | +| Medium | Email + Slack | Daily digest | +| Low | Email | Weekly digest | + +### Alert Recipients + +| Role | Critical | High | Medium | Low | +|------|----------|------|--------|-----| +| SEO Manager | Yes | Yes | Yes | Yes | +| Dev Team | Yes | Yes (tech only) | No | No | +| Marketing Lead | Yes | Yes | No | No | +| Executive | Yes | No | No | No | + +### Alert Suppression + +- Suppress duplicate alerts for 24 hours +- Don't alert on known issues (maintenance windows) +- Batch low-priority alerts into digests + +### Alert Escalation + +| If No Response In | Escalate To | +|-------------------|-------------| +| 1 hour (Critical) | SEO Manager -> Director | +| 4 hours (High) | Team Lead -> Manager | +| 24 hours (Medium) | Team -> Lead | diff --git a/.cursor/skills/alert-manager/references/alert-threshold-guide.md b/.cursor/skills/alert-manager/references/alert-threshold-guide.md new file mode 100644 index 0000000000..9b4099872e --- /dev/null +++ b/.cursor/skills/alert-manager/references/alert-threshold-guide.md @@ -0,0 +1,377 @@ +# Alert Threshold Guide + +Complete reference for configuring SEO/GEO alert thresholds. Covers baseline establishment, threshold setting methodology, tuning process, alert routing configuration, notification channel setup, and response playbooks for each alert type. + +--- + +## 1. Baseline Establishment Process + +Before setting any alert thresholds, you must establish a baseline that represents normal metric behavior for your site. Without a baseline, you will either set thresholds too tight (causing alert fatigue) or too loose (missing real problems). + +### Baseline Collection Timeline + +| Metric Category | Minimum Baseline Period | Ideal Baseline Period | Why | +|----------------|------------------------|----------------------|-----| +| Organic traffic | 4 weeks | 8-12 weeks | Accounts for weekly cycles and monthly patterns | +| Keyword rankings | 2-4 weeks | 4-8 weeks | Rankings fluctuate daily; need to establish normal range | +| Backlink metrics | 4 weeks | 8 weeks | Link acquisition is lumpy; need to see natural cadence | +| Technical metrics | 2 weeks | 4 weeks | Most technical metrics are relatively stable | +| Core Web Vitals | 4 weeks (28-day rolling) | 8 weeks | CrUX data is 28-day rolling average | +| AI citations | 4 weeks | 8 weeks | AI answer composition changes frequently | + +### Baseline Data Collection Steps + +| Step | Action | Output | +|------|--------|--------| +| 1 | Record daily metric values for the baseline period | Raw data spreadsheet | +| 2 | Calculate mean (average) for each metric | Central tendency | +| 3 | Calculate standard deviation for each metric | Normal variation range | +| 4 | Identify outliers (values > 2 standard deviations from mean) | Anomaly list | +| 5 | Remove known outliers (holidays, outages, one-time events) | Clean baseline | +| 6 | Recalculate mean and standard deviation on clean data | Final baseline values | +| 7 | Document seasonal patterns if baseline covers enough time | Seasonal adjustment notes | + +### Baseline Metrics to Record + +| Metric | Daily | Weekly | Monthly | +|--------|-------|--------|---------| +| Organic sessions | Record | Calculate WoW % change | Calculate MoM % change | +| Keyword positions (top 20) | Record | Calculate average movement | Calculate net position change | +| Keywords in top 10 | Record | Calculate weekly count | Calculate monthly trend | +| Crawl errors | Record | Calculate weekly new errors | Calculate monthly trend | +| New backlinks | N/A | Record weekly count | Calculate monthly velocity | +| Lost backlinks | N/A | Record weekly count | Calculate monthly velocity | +| Core Web Vitals | N/A | Record from CrUX | Calculate monthly trend | +| AI citations | N/A | Record weekly count | Calculate monthly trend | +| Pages indexed | N/A | Record weekly count | Calculate monthly change | +| Server response time | Record | Calculate weekly average | Calculate monthly average | + +--- + +## 2. Threshold Setting Methodology + +### The Standard Deviation Method + +For most metrics, set thresholds based on standard deviations from your baseline mean. + +| Threshold Level | Formula | Meaning | +|----------------|---------|---------| +| **Info** | Mean +/- 1 standard deviation | Normal fluctuation range; log but do not alert | +| **Warning** | Mean +/- 1.5 standard deviations | Unusual but not necessarily problematic | +| **Critical** | Mean +/- 2 standard deviations | Statistically significant anomaly; investigate | +| **Emergency** | Mean +/- 3 standard deviations | Extreme anomaly; immediate action required | + +**Example calculation:** + +``` +Metric: Daily organic sessions +Baseline mean: 10,000 sessions/day +Standard deviation: 800 sessions/day + +Info range: 8,200 - 11,800 (normal) +Warning: < 8,800 or > 11,200 +Critical: < 8,400 or > 11,600 +Emergency: < 7,600 or > 12,400 +``` + +### The Percentage Method + +For metrics where standard deviation is not practical, use percentage-based thresholds. + +| Metric | Warning Threshold | Critical Threshold | Comparison Period | +|--------|------------------|-------------------|-------------------| +| Organic traffic | -15% vs. comparison | -30% vs. comparison | Week over week | +| Keyword positions | >3 position average drop | >5 position average drop | Week over week | +| Pages indexed | -5% change | -20% change | Week over week | +| Referring domains | -5% loss | -15% loss | Month over month | +| Crawl error rate | >2x baseline rate | >5x baseline rate | Day over day | +| Conversion rate | -20% drop | -40% drop | Week over week | + +### The Absolute Value Method + +For binary or count-based metrics, use absolute thresholds. + +| Metric | Warning Threshold | Critical Threshold | +|--------|------------------|-------------------| +| New crawl errors | >10 new errors/day | >50 new errors/day | +| Server 5xx errors | Any occurrence | >5 occurrences/hour | +| Security issues | N/A | Any detection | +| Manual penalties | N/A | Any notification | +| SSL certificate expiry | <30 days to expiry | <7 days to expiry | +| Robots.txt changes | Any unexpected change | Key pages blocked | + +--- + +## 3. Threshold Configuration by Metric Category + +### Traffic Thresholds + +| Metric | Comparison | Warning | Critical | Emergency | +|--------|-----------|---------|----------|-----------| +| Total organic sessions | WoW | -15% | -30% | -50% | +| Total organic sessions | DoD | -25% (weekday) | -40% | Site appears down | +| Non-brand sessions | WoW | -20% | -35% | -50% | +| Organic conversions | WoW | -20% | -40% | -60% | +| Organic revenue | WoW | -15% | -30% | -50% | +| Bounce rate | WoW | +10pp | +20pp | +30pp | +| Page-level traffic (top 10 pages) | WoW | -25% | -40% | -60% | + +**Note:** Day-over-day traffic thresholds need day-of-week adjustment. Monday traffic typically differs from Saturday traffic. Compare Monday to Monday, not Monday to Sunday. + +### Ranking Thresholds + +| Metric | Scope | Warning | Critical | +|--------|-------|---------|----------| +| Position change (Tier 1 keywords) | Individual keyword | Drop >= 3 | Drop >= 5 | +| Position change (Tier 2 keywords) | Individual keyword | Drop >= 5 | Drop >= 10 | +| Position change (Tier 3 keywords) | Individual keyword | Drop >= 10 | Drop off page 3 | +| Average position (all keywords) | Aggregate | +2.0 (worsening) | +5.0 (worsening) | +| Keywords in top 10 | Count | -10% of count | -20% of count | +| Keywords in top 3 | Count | Any decrease | -3 or more | +| Brand keyword position | Individual | Any drop from #1 | Drops below #3 | +| Featured snippet lost | Individual | Any loss | Loss of 3+ snippets | + +### Technical Thresholds + +| Metric | Warning | Critical | Emergency | +|--------|---------|----------|-----------| +| New 4xx errors | >5/day | >20/day | >100/day | +| New 5xx errors | >1/day | >5/day | >20/day | +| Crawl rate change | -30% vs. baseline | -60% vs. baseline | Near-zero crawl | +| Index coverage drop | -5% | -15% | -30% | +| Average server response time | >500ms | >1000ms | >2000ms | +| LCP (mobile) | Moves to "Needs Improvement" | Moves to "Poor" | >6s | +| CLS | >0.1 | >0.25 | >0.5 | +| INP | >200ms | >500ms | >1000ms | +| Robots.txt change | Any unexpected edit | Pages blocked | Entire site blocked | +| Sitemap errors | New errors | Sitemap inaccessible | Sitemap returning 5xx | + +### Backlink Thresholds + +| Metric | Warning | Critical | +|--------|---------|----------| +| Referring domains lost (weekly) | >5% of total | >15% of total | +| High-authority link lost (DR 60+) | Any loss | Loss of 3+ in one week | +| Toxic link spike | >10 new toxic links/week | >50 new toxic links/week | +| Anchor text over-optimization | Exact match reaches 20% | Exact match reaches 30% | +| Negative SEO pattern | Unusual link velocity from low-DR sites | Massive spam link spike | + +### GEO / AI Visibility Thresholds + +| Metric | Warning | Critical | +|--------|---------|----------| +| AI citation rate | Drops 10+ percentage points | Drops below 10% | +| Key query citation lost | Any Tier 1 query | 3+ Tier 1 queries | +| Citation position degradation | Average position worsens by 2+ | Dropped from citations entirely | +| Competitor gains citation you lost | 1 instance | Pattern across queries | + +--- + +## 4. Alert Routing Configuration + +### Routing Matrix + +| Alert Category | P0 (Emergency) | P1 (Urgent) | P2 (Important) | P3 (Monitor) | +|---------------|----------------|-------------|----------------|--------------| +| **Traffic** | SEO Lead + Eng Manager + VP | SEO Lead + Marketing Mgr | SEO Team | Weekly digest | +| **Rankings** | SEO Lead + Content Lead | SEO Team | SEO Team | Weekly digest | +| **Technical** | SEO Lead + Eng Lead + DevOps | SEO Lead + Eng Team | SEO Team + Eng | Weekly digest | +| **Backlinks** | SEO Lead | SEO Team | SEO Team | Weekly digest | +| **Competitor** | N/A | SEO Lead | SEO Team | Weekly digest | +| **GEO/AI** | SEO Lead + Content Lead | SEO Team | SEO Team | Weekly digest | +| **Security** | SEO Lead + Eng Manager + VP + Legal | All above | N/A | N/A | + +### Role-Based Alert Filtering + +| Role | Receives | Does Not Receive | +|------|---------|-----------------| +| SEO Lead | All P0, P1, P2 alerts | P3 (weekly digest only) | +| SEO Analyst | P1, P2 in their area | P0 (escalation only), other areas | +| Content Lead | P0-P1 ranking + GEO alerts | Technical alerts, backlink alerts | +| Engineering Lead | P0-P1 technical alerts | Ranking, content, backlink alerts | +| Marketing VP | P0 only | P1-P3 (receives weekly summary) | +| DevOps | P0 technical + security | All non-infrastructure alerts | + +--- + +## 5. Notification Channel Setup + +### Channel Selection by Priority + +| Priority | Primary Channel | Secondary Channel | Escalation Channel | +|----------|----------------|-------------------|-------------------| +| P0 | SMS + Phone call | Slack (#seo-emergencies) | PagerDuty / on-call rotation | +| P1 | Slack (#seo-alerts) | Email | SMS (if not acknowledged in 4h) | +| P2 | Email | Slack (#seo-daily) | Auto-escalate to P1 after 1 week | +| P3 | Weekly digest email | Dashboard | Auto-escalate to P2 after 1 month | + +### Notification Content Requirements + +Every alert notification should include: + +| Field | Required | Example | +|-------|----------|---------| +| Alert name | Yes | "Critical Ranking Drop" | +| Priority level | Yes | "P0 — Emergency" | +| Metric affected | Yes | "Position for 'project management software'" | +| Current value | Yes | "Position 12" | +| Previous value | Yes | "Position 3 (yesterday)" | +| Threshold breached | Yes | "Dropped >5 positions" | +| Timestamp | Yes | "2025-01-15 09:00 UTC" | +| Affected URL | Yes (if applicable) | "yoursite.com/blog/pm-guide" | +| Quick action link | Yes | Link to relevant tool/dashboard | +| Suggested first step | Recommended | "Check if page is still indexed: site:yoursite.com/blog/pm-guide" | + +### Notification Suppression Rules + +| Rule | Configuration | Reason | +|------|-------------|--------| +| Duplicate cooldown | Do not re-alert on same metric for 24 hours | Prevent alert storms | +| Maintenance window | Suppress non-security alerts during scheduled maintenance | Avoid known-cause alerts | +| Weekend adjustment | Increase traffic thresholds by 20% on weekends | Weekend traffic naturally lower | +| Holiday adjustment | Suppress traffic alerts on major holidays | Known seasonal impact | +| Recovery auto-close | Auto-close alert if metric returns to normal within 48h | Reduce stale alerts | +| Batch related alerts | Group multiple ranking drops into single "Ranking Alert" | Reduce notification volume | + +--- + +## 6. Threshold Tuning Guide + +### When to Tune Thresholds + +| Signal | Action | +|--------|--------| +| Too many false positives (>30% of alerts are noise) | Widen thresholds by 0.5 standard deviations | +| Missed a real problem | Tighten the specific threshold that should have caught it | +| Seasonal change approaching | Adjust baselines for known seasonal patterns | +| Major site change (redesign, migration) | Re-establish baseline from scratch (2-4 week observation) | +| New competitor enters market | Add competitor monitoring, adjust ranking sensitivity | +| After algorithm update | Let metrics stabilize for 2-4 weeks, then recalibrate | + +### Monthly Threshold Review Checklist + +| Check | Action | +|-------|--------| +| Review all alerts fired in the past month | Count true positives vs. false positives | +| Calculate false positive rate | If >30%, thresholds are too tight | +| Check for missed events | If a real issue was not alerted, threshold is too loose | +| Review metric baselines | Recalculate mean and standard deviation with latest data | +| Adjust seasonal baselines | Incorporate seasonal patterns from year-over-year data | +| Update keyword tiers | Promote/demote keywords based on current business priority | +| Verify notification routing | Confirm all recipients are still in the correct roles | +| Test alert delivery | Send a test alert through each channel to verify delivery | + +### Threshold Evolution Over Time + +| Site Maturity | Threshold Approach | Rationale | +|-------------|-------------------|-----------| +| New site (0-6 months) | Wide thresholds, few alerts | Metrics are volatile; avoid noise | +| Growing (6-18 months) | Moderate thresholds, expand coverage | Enough data for meaningful baselines | +| Established (18+ months) | Tight thresholds, comprehensive | Stable baselines, can detect subtle changes | +| Post-migration | Reset to wide, re-tighten over 4-8 weeks | Old baselines are invalid | + +--- + +## 7. Playbook Templates by Alert Type + +### Playbook: Organic Traffic Emergency (P0) + +**Trigger:** Organic traffic drops >50% day-over-day + +| Step | Time | Action | Tool | +|------|------|--------|------| +| 1 | 0 min | Verify site is accessible from multiple locations | Manual browser check, uptime monitor | +| 2 | 5 min | Check Google Search Status Dashboard for outages | Google Status Dashboard | +| 3 | 10 min | Check Search Console for manual actions or security issues | ~~search console | +| 4 | 15 min | Check robots.txt for accidental blocking | Direct URL check | +| 5 | 20 min | Check for noindex tags added to key pages | Crawl or manual page inspection | +| 6 | 30 min | Review recent deployments or CMS changes | Deploy log, git history | +| 7 | 45 min | Check server logs for unusual patterns | Server access logs | +| 8 | 60 min | If unresolved, escalate to Engineering Manager | Slack/phone | + +### Playbook: Security Alert (P0) + +**Trigger:** Google Search Console security issue or manual action + +| Step | Time | Action | +|------|------|--------| +| 1 | 0 min | Read the exact message in Search Console | +| 2 | 5 min | Notify Engineering Manager and VP Marketing | +| 3 | 15 min | Scan site for malware or injected content | +| 4 | 30 min | If compromised: take affected pages offline, rotate all credentials | +| 5 | 1 hour | Identify attack vector and patch vulnerability | +| 6 | 2 hours | Clean all affected pages, submit for re-review | +| 7 | 24 hours | Verify resolution in Search Console | +| 8 | 1 week | Post-incident review and security hardening | + +### Playbook: Algorithm Update Impact (P1-P2) + +**Trigger:** Confirmed Google algorithm update + ranking/traffic changes + +| Step | Time | Action | +|------|------|--------| +| 1 | Day 0 | Confirm update via Google Search Status Dashboard or official channels | +| 2 | Day 0 | Document pre-update baseline metrics (rankings, traffic, visibility) | +| 3 | Day 1-3 | Monitor daily — do not make changes while update is rolling out | +| 4 | Day 7 | First analysis: which pages/keywords improved, which declined | +| 5 | Day 7 | Analyze pattern: content quality? link profile? technical? YMYL? | +| 6 | Day 14 | Develop action plan based on analysis | +| 7 | Day 14-60 | Implement improvements (content quality, E-E-A-T signals, technical fixes) | +| 8 | Next update | Re-evaluate impact after next core update | + +### Playbook: Backlink Attack / Negative SEO (P1) + +**Trigger:** Unusual spike in low-quality backlinks (>100 new links from spam domains in one week) + +| Step | Time | Action | +|------|------|--------| +| 1 | Day 0 | Verify the spike in ~~link database | +| 2 | Day 0 | Identify the pattern (same anchor text? same link network? same country?) | +| 3 | Day 1 | Export all new toxic links | +| 4 | Day 1 | Create disavow file with identified spam domains | +| 5 | Day 2 | Upload disavow to Google Search Console | +| 6 | Day 2 | Document the attack pattern for future reference | +| 7 | Day 7 | Re-check for continued spam link activity | +| 8 | Day 14 | Verify disavow processed, monitor rankings for impact | + +### Playbook: Core Web Vitals Degradation (P2) + +**Trigger:** Any CWV metric moves from "Good" to "Needs Improvement" or "Poor" + +| Step | Time | Action | +|------|------|--------| +| 1 | Day 0 | Identify which metric degraded and which page groups are affected | +| 2 | Day 1 | Run PageSpeed Insights on representative pages | +| 3 | Day 1 | Check recent deployments for potential cause (new scripts, images, layout changes) | +| 4 | Day 2 | Create engineering ticket with diagnosis and fix recommendations | +| 5 | Day 3-14 | Engineering implements fix | +| 6 | Day 14 | Verify improvement in lab data (PageSpeed Insights) | +| 7 | Day 42 | Verify improvement in field data (CrUX — 28-day rolling window) | + +--- + +## 8. Alert System Maintenance + +### Quarterly System Review + +| Task | Frequency | Owner | +|------|-----------|-------| +| Recalculate all baselines with latest data | Quarterly | SEO Lead | +| Review and update keyword tier assignments | Quarterly | SEO Team | +| Audit notification routing (team changes, role changes) | Quarterly | SEO Lead | +| Test all notification channels (SMS, Slack, email) | Quarterly | SEO Lead | +| Review alert response times (are SLAs being met?) | Quarterly | SEO Lead | +| Archive resolved alerts older than 90 days | Quarterly | SEO Analyst | +| Update playbooks based on lessons learned | Quarterly | SEO Team | + +### Alert Effectiveness Metrics + +Track these metrics about your alerting system itself: + +| Metric | Target | Meaning | +|--------|--------|---------| +| False positive rate | <30% | % of alerts that were not actionable | +| Mean time to acknowledge (MTTA) | P0: <15min, P1: <4h | Time from alert to first human response | +| Mean time to resolve (MTTR) | P0: <2h, P1: <24h | Time from alert to resolution | +| Missed incident rate | 0% | Real problems that were not alerted | +| Alert volume per week | Manageable for team size | If overwhelming, thresholds need tuning | diff --git a/.cursor/skills/backlink-analyzer/SKILL.md b/.cursor/skills/backlink-analyzer/SKILL.md new file mode 100644 index 0000000000..ce0a2e7977 --- /dev/null +++ b/.cursor/skills/backlink-analyzer/SKILL.md @@ -0,0 +1,301 @@ +--- +name: backlink-analyzer +description: 'Analyze backlink profiles: link authority, toxic links, building opportunities, competitor link gaps. 外链分析/反向链接' +version: "6.0.0" +license: Apache-2.0 +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when analyzing backlink profiles, link quality, toxic links, referring domains, or anchor text distribution." +argument-hint: "" +metadata: + author: aaron-he-zhu + version: "6.0.0" + geo-relevance: "low" + tags: + - seo + - backlinks + - link-building + - link-profile + - toxic-links + - off-page-seo + - link-audit + - referring-domains + - disavow + - ahrefs-alternative + - 外链分析 + - 被リンク + - 백링크 + - backlinks-seo + triggers: + # EN-formal + - "analyze backlinks" + - "check link profile" + - "find toxic links" + - "link building opportunities" + - "link profile analysis" + - "backlink audit" + - "link quality" + # EN-casual + - "who links to me" + - "I have spammy links" + - "how do I get more backlinks" + - "how do I get more links" + - "disavow links" + - "link building outreach" + - "disavow file" + # EN-question + - "how to build backlinks" + - "how to find toxic backlinks" + # ZH-pro + - "外链分析" + - "反向链接" + - "有毒链接" + - "链接建设" + # ZH-casual + - "外链怎么做" + - "有垃圾外链" + - "谁链接到我" + - "友链" + - "互换友链" + - "外链建设" + # JA + - "被リンク分析" + - "バックリンク" + - "リンク構築" + # KO + - "백링크 분석" + - "링크 빌딩" + - "누가 내 사이트 링크해?" + - "백링크 어떻게 늘려?" + # ES + - "análisis de backlinks" + - "enlaces entrantes" + # PT + - "análise de backlinks" + # Misspellings + - "backlink anaylsis" + - "backlnk analysis" +--- + +# Backlink Analyzer + + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This monitoring skill follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + + +Analyzes, monitors, and optimizes backlink profiles. Identifies link quality, discovers opportunities, and tracks competitor link building activities. + +**System role**: Monitoring layer skill. It turns performance changes into deltas, alerts, and next actions. + +## When This Must Trigger + +Use this when the conversation involves any of these situations — even if the user does not use SEO terminology: + +Use this whenever the task needs time-aware change detection, escalation, or stakeholder-ready visibility. + +- Auditing your current backlink profile +- Identifying toxic or harmful links +- Discovering link building opportunities +- Analyzing competitor backlink strategies +- Monitoring new and lost links +- Evaluating link quality for outreach +- Preparing for link disavow + +## What This Skill Does + +1. **Profile Analysis**: Comprehensive backlink profile overview +2. **Quality Assessment**: Evaluates link authority and relevance +3. **Toxic Link Detection**: Identifies harmful links +4. **Competitor Analysis**: Compares link profiles across competitors +5. **Opportunity Discovery**: Finds link building prospects +6. **Trend Monitoring**: Tracks link acquisition over time +7. **Disavow Guidance**: Helps create disavow files + +## Quick Start + +Start with one of these prompts. Finish with a short handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Analyze Your Profile + +``` +Analyze backlink profile for [domain] +``` + +### Find Opportunities + +``` +Find link building opportunities by analyzing [competitor domains] +``` + +### Detect Issues + +``` +Check for toxic backlinks on [domain] +``` + +### Compare Profiles + +``` +Compare backlink profiles: [your domain] vs [competitor domains] +``` + +## Skill Contract + +**Expected output**: a delta summary, alert/report output, and a short handoff summary ready for `memory/monitoring/`. + +- **Reads**: current metrics, previous baselines, alert thresholds, and reporting context from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available. +- **Writes**: a user-facing monitoring deliverable plus a reusable summary that can be stored under `memory/monitoring/`. +- **Promotes**: significant changes, confirmed anomalies, and follow-up actions to `memory/open-loops.md` and `memory/decisions.md`. +- **Next handoff**: use the `Next Best Skill` below when a change needs action. + +## Data Sources + +> **Note:** All integrations are optional. This skill works without any API keys — users provide data manually when no tools are connected. + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +**With ~~link database + ~~SEO tool connected:** +Automatically pull comprehensive backlink profiles including referring domains, anchor text distribution, link quality metrics (DA/DR), link velocity, and toxic link detection from ~~link database. Competitor backlink data from ~~SEO tool for gap analysis. + +**With manual data only:** +Ask the user to provide: +1. Backlink export CSV (with source domains, anchor text, link type) +2. Referring domains list with authority metrics +3. Competitor domains for comparison +4. Recent link gains/losses if tracking changes +5. Any known toxic or spammy links + +Proceed with the full analysis using provided data. Note in the output which metrics are from automated collection vs. user-provided data. + +## Instructions + +When a user requests backlink analysis: + +1. **Generate Profile Overview** -- Key metrics (total backlinks, referring domains, DA/DR, dofollow ratio), link velocity (30d/90d/year), authority distribution chart, profile health score. + +2. **Analyze Link Quality** -- Top quality backlinks table, link type distribution, anchor text analysis (brand/exact/partial/URL/generic), geographic distribution. + +3. **Identify Toxic Links** -- Toxic score, risk indicators by type (spam, PBN, link farms, irrelevant), high-risk links to review, disavow recommendations (domain-level and URL-level). + +4. **Compare Against Competitors** -- Profile comparison table (referring domains, DA/DR, velocity, avg link DA), unique referring domains, link intersection analysis, competitor content attracting most links. + +5. **Find Link Building Opportunities** -- Link intersection prospects, broken link opportunities, unlinked mentions, resource page opportunities, guest post prospects, priority matrix (effort vs impact). + +6. **Track Link Changes** -- New and lost links for last 30 days with DA, type, anchor, dates. Net change and links to recover. + +7. **Generate Backlink Report** -- Executive summary, strengths, concerns, opportunities, competitive position, recommended actions (immediate/short-term/long-term), KPIs to track. + + > **Reference**: See [references/analysis-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/backlink-analyzer/references/analysis-templates.md) for complete output templates for all 7 steps above. + +### CITE Item Mapping + +When running `domain-authority-auditor` after this analysis, the following data feeds directly into CITE scoring: + +| Backlink Metric | CITE Item | Dimension | +|----------------|-----------|-----------| +| Referring domains count | C01 (Referring Domain Volume) | Citation | +| Authority distribution (DA breakdown) | C02 (Referring Domains Quality) | Citation | +| Link velocity | C04 (Link Velocity) | Citation | +| Geographic distribution | C10 (Link Source Diversity) | Citation | +| Dofollow/Nofollow ratio | T02 (Dofollow Ratio Normality) | Trust | +| Toxic link analysis | T01 (Link Profile Naturalness), T03 (Link-Traffic Coherence) | Trust | +| Competitive link intersection | T05 (Profile Uniqueness) | Trust | + +## Validation Checkpoints + +### Input Validation +- [ ] Target domain backlink data is complete and current +- [ ] Competitor domains specified for comparison analysis +- [ ] Backlink data includes necessary fields (source domain, anchor text, link type) +- [ ] Authority metrics available (DA/DR or equivalent) + +### Output Validation +- [ ] Every metric cites its data source and collection date +- [ ] Toxic link assessments include risk justification +- [ ] Link opportunity recommendations are specific and actionable +- [ ] Source of each data point clearly stated (~~link database data, ~~SEO tool data, user-provided, or estimated) + +## Example + +**User**: "Find link building opportunities by analyzing HubSpot, Salesforce, and Mailchimp" + +**Output**: + +```markdown +## Link Intersection Analysis + +### Sites linking to 2+ competitors (not you) + +| Domain | DA | HubSpot | Salesforce | Mailchimp | Opportunity | +|--------|-----|---------|------------|-----------|-------------| +| g2.com | 91 | ✅ | ✅ | ✅ | Get listed/reviewed | +| capterra.com | 89 | ✅ | ✅ | ✅ | Submit for review | +| entrepreneur.com | 92 | ✅ | ✅ | ❌ | Pitch guest post | +| techcrunch.com | 94 | ✅ | ❌ | ✅ | PR/news pitch | + +### Top 5 Immediate Opportunities + +1. **G2.com** (DA 91) - All competitors listed + - Action: Create detailed G2 profile + - Effort: Low + - Impact: High authority + referral traffic + +2. **Entrepreneur.com** (DA 92) - 2 competitors have links + - Action: Pitch contributed article + - Effort: High + - Impact: High authority + brand exposure + +3. **MarketingProfs** (DA 75) - All competitors featured + - Action: Apply for expert contribution + - Effort: Medium + - Impact: Relevant audience + quality link + +### Estimated Impact + +If you acquire links from top 10 opportunities: +- New referring domains: +10 +- Average DA of new links: 82 +- Estimated ranking impact: +2-5 positions for competitive keywords +``` + +## Tips for Success + +1. **Quality over quantity** - One DA 80 link beats ten DA 20 links +2. **Monitor regularly** - Catch lost links and toxic links early +3. **Study competitors** - Learn from their link building success +4. **Diversify your profile** - Mix of link types and anchors +5. **Disavow carefully** - Only disavow clearly toxic links + +## Link Quality and Strategy Reference + +> **Reference**: See [references/link-quality-rubric.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/backlink-analyzer/references/link-quality-rubric.md) for the complete link quality scoring matrix (6 weighted factors), toxic link identification criteria, link profile health benchmarks, and disavow file guidance. + +> **Reference**: See [references/outreach-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/backlink-analyzer/references/outreach-templates.md) for email outreach frameworks, subject line formulas, response rate benchmarks, follow-up sequences, and templates for each link building strategy. + + +### Save Results + +After delivering monitoring data or reports to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to `memory/monitoring/YYYY-MM-DD-.md` containing: +- One-line headline finding or status change +- Top 3-5 actionable items +- Open loops or anomalies requiring follow-up +- Source data references + +If any findings should influence ongoing strategy, recommend promoting key conclusions to `memory/hot-cache.md`. + + +**Gate check recommended**: If toxic link ratio exceeds 15%, recommend running domain-authority-auditor to assess overall domain trust impact. + +## Reference Materials + +- [Link Quality Rubric](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/backlink-analyzer/references/link-quality-rubric.md) — Quality scoring matrix with weighted factors and toxic link identification criteria +- [Outreach Templates](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/backlink-analyzer/references/outreach-templates.md) — Email frameworks, subject line formulas, and response rate benchmarks + +## Next Best Skill + +- **Primary**: [domain-authority-auditor](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/domain-authority-auditor/SKILL.md) — translate link findings into a domain-level trust view. diff --git a/.cursor/skills/backlink-analyzer/references/analysis-templates.md b/.cursor/skills/backlink-analyzer/references/analysis-templates.md new file mode 100644 index 0000000000..d1809dc291 --- /dev/null +++ b/.cursor/skills/backlink-analyzer/references/analysis-templates.md @@ -0,0 +1,354 @@ +# Backlink Analysis Output Templates + +Detailed output templates for each step of the backlink analysis workflow. Use these templates when generating analysis deliverables. + +--- + +## 1. Profile Overview Template + +```markdown +## Backlink Profile Overview + +**Domain**: [domain] +**Analysis Date**: [date] + +### Key Metrics + +| Metric | Value | Industry Avg | Status | +|--------|-------|--------------|--------| +| Total Backlinks | [X] | [Y] | [Above/Below avg] | +| Referring Domains | [X] | [Y] | [status] | +| Domain Authority | [X] | [Y] | [status] | +| Domain Rating | [X] | [Y] | [status] | +| Dofollow Links | [X] ([Y]%) | [Z]% | [status] | +| Nofollow Links | [X] ([Y]%) | [Z]% | [status] | + +### Link Velocity + +| Period | New Links | Lost Links | Net Change | +|--------|-----------|------------|------------| +| Last 30 days | [X] | [Y] | [+/-Z] | +| Last 90 days | [X] | [Y] | [+/-Z] | +| Last year | [X] | [Y] | [+/-Z] | + +### Authority Distribution + +``` +DA 80-100: [X]% +DA 60-79: [X]% +DA 40-59: [X]% +DA 20-39: [X]% +DA 0-19: [X]% +``` + +**Profile Health Score**: [X]/100 +``` + +--- + +## 2. Link Quality Analysis Template + +```markdown +## Link Quality Analysis + +### Top Quality Backlinks + +| Source Domain | DA | Link Type | Anchor | Target Page | +|---------------|-----|-----------|--------|-------------| +| [domain 1] | [DA] | Editorial | [anchor] | [page] | +| [domain 2] | [DA] | Guest Post | [anchor] | [page] | +| [domain 3] | [DA] | Resource | [anchor] | [page] | + +### Link Type Distribution + +| Type | Count | Percentage | Assessment | +|------|-------|------------|------------| +| Editorial | [X] | [Y]% | High quality | +| Guest posts | [X] | [Y]% | Good | +| Resource pages | [X] | [Y]% | Good | +| Directory | [X] | [Y]% | Moderate | +| Forum/Comments | [X] | [Y]% | Low quality | +| Sponsored/Paid | [X] | [Y]% | Risky | + +### Anchor Text Analysis + +| Anchor Type | Count | Percentage | Status | +|-------------|-------|------------|--------| +| Brand name | [X] | [Y]% | Natural | +| Exact match | [X] | [Y]% | [Warning if >30%] | +| Partial match | [X] | [Y]% | Natural | +| URL/Naked | [X] | [Y]% | Natural | +| Generic | [X] | [Y]% | Natural | + +**Top Anchor Texts**: +1. "[anchor 1]" - [X] links +2. "[anchor 2]" - [X] links +3. "[anchor 3]" - [X] links + +### Geographic Distribution + +| Country | Links | Percentage | +|---------|-------|------------| +| [Country 1] | [X] | [Y]% | +| [Country 2] | [X] | [Y]% | +| [Country 3] | [X] | [Y]% | +``` + +--- + +## 3. Toxic Link Analysis Template + +```markdown +## Toxic Link Analysis + +### Risk Summary + +**Toxic Score**: [X]/100 +**High Risk Links**: [X] +**Medium Risk Links**: [X] +**Action Required**: [Yes/No] + +### Toxic Link Indicators + +| Risk Type | Count | Examples | +|-----------|-------|----------| +| Spammy domains | [X] | [domains] | +| Link farms | [X] | [domains] | +| PBN suspected | [X] | [domains] | +| Irrelevant sites | [X] | [domains] | +| Foreign language spam | [X] | [domains] | +| Penalized domains | [X] | [domains] | + +### High-Risk Links to Review + +| Source Domain | Risk Score | Issue | Recommendation | +|---------------|------------|-------|----------------| +| [domain 1] | 95/100 | Link farm | Disavow | +| [domain 2] | 85/100 | Spam site | Disavow | +| [domain 3] | 72/100 | PBN | Investigate | + +### Disavow Recommendations + +**Domains to disavow** ([X] total): +``` +domain:[spam-site-1.com] +domain:[spam-site-2.com] +domain:[link-farm.com] +``` + +**Individual URLs to disavow** ([X] total): +``` +[specific-url-1] +[specific-url-2] +``` +``` + +--- + +## 4. Competitive Backlink Analysis Template + +```markdown +## Competitive Backlink Analysis + +### Profile Comparison + +| Metric | You | Competitor 1 | Competitor 2 | Competitor 3 | +|--------|-----|--------------|--------------|--------------| +| Referring Domains | [X] | [X] | [X] | [X] | +| Domain Authority | [X] | [X] | [X] | [X] | +| Domain Rating | [X] | [X] | [X] | [X] | +| Link Velocity (30d) | [X] | [X] | [X] | [X] | +| Avg Link DA | [X] | [X] | [X] | [X] | + +### Unique Referring Domains + +**Links only you have**: [X] domains +**Links competitors share**: [X] domains +**Links competitors have, you don't**: [X] domains -- Opportunity + +### Link Intersection Analysis + +**Sites linking to competitors but not you**: + +| Domain | DA | Links to Comp 1 | Comp 2 | Comp 3 | Opportunity | +|--------|-----|-----------------|--------|--------|-------------| +| [domain 1] | [DA] | Yes | Yes | Yes | High - All competitors | +| [domain 2] | [DA] | Yes | Yes | No | High - 2 competitors | +| [domain 3] | [DA] | Yes | No | No | Medium - 1 competitor | + +### Content Getting Most Links (Competitor Analysis) + +| Competitor | Content | Backlinks | Content Type | +|------------|---------|-----------|--------------| +| [Comp 1] | [Title/URL] | [X] | [Type] | +| [Comp 2] | [Title/URL] | [X] | [Type] | +| [Comp 3] | [Title/URL] | [X] | [Type] | + +**Insight**: [What content types attract most links in this niche] +``` + +--- + +## 5. Link Building Opportunities Template + +```markdown +## Link Building Opportunities + +### High-Priority Opportunities + +#### 1. Link Intersection Prospects + +Sites linking to multiple competitors but not you: + +| Domain | DA | Why Link | Contact Approach | +|--------|-----|----------|------------------| +| [domain 1] | [DA] | [resource page about X] | Suggest your resource | +| [domain 2] | [DA] | [links to similar tools] | Pitch your tool | +| [domain 3] | [DA] | [industry roundup] | Request inclusion | + +#### 2. Broken Link Opportunities + +| Source Page | Broken Link | Suggested Replacement | +|-------------|-------------|----------------------| +| [URL] | [broken URL] | [your relevant page] | + +#### 3. Unlinked Mentions + +| Site | Mention | Your Page to Link | +|------|---------|-------------------| +| [domain] | Mentioned your brand | [homepage] | +| [domain] | Referenced your data | [research page] | + +#### 4. Resource Page Opportunities + +| Resource Page | Topic | Your Relevant Content | +|---------------|-------|----------------------| +| [URL] | [topic] | [your content] | + +#### 5. Guest Post Prospects + +| Site | DA | Topic Fit | Contact | +|------|-----|-----------|---------| +| [domain] | [DA] | [relevance] | [contact info/page] | + +### Link Building Priority Matrix + +| Opportunity Type | Effort | Impact | Priority | +|------------------|--------|--------|----------| +| Link intersection | Medium | High | Highest | +| Broken links | Low | Medium | High | +| Unlinked mentions | Low | Medium | High | +| Resource pages | Medium | High | High | +| Guest posts | High | High | Medium | +``` + +--- + +## 6. Link Change Tracking Template + +```markdown +## Link Change Tracking + +### New Links (Last 30 Days) + +| Source | DA | Type | Anchor | Date | +|--------|-----|------|--------|------| +| [domain 1] | [DA] | [type] | [anchor] | [date] | + +**Total new links**: [X] +**Average DA of new links**: [X] +**Best new link**: [domain] (DA [X]) + +### Lost Links (Last 30 Days) + +| Source | DA | Reason | Action | +|--------|-----|--------|--------| +| [domain 1] | [DA] | Page removed | Reach out | +| [domain 2] | [DA] | Link removed | Investigate | + +**Total lost links**: [X] +**Net change**: [+/-X] + +### Links to Recover + +| Lost Link | Value | Recovery Strategy | +|-----------|-------|-------------------| +| [domain 1] | High | Contact webmaster | +| [domain 2] | High | Update content they linked to | +``` + +--- + +## 7. Backlink Report Template + +```markdown +# Backlink Analysis Report + +**Domain**: [domain] +**Report Date**: [date] +**Period Analyzed**: [period] + +## Executive Summary + +Your backlink profile is [healthy/needs attention/concerning]. + +**Key Stats**: +- Referring domains: [X] ([+/-Y] vs last month) +- Average link authority: [X] DA +- Link velocity: [X] new links/month +- Toxic link percentage: [X]% + +## Profile Strengths + +1. [Strength 1] +2. [Strength 2] +3. [Strength 3] + +## Areas of Concern + +1. [Concern 1] +2. [Concern 2] + +## Opportunities Identified + +| Opportunity | Potential Links | Effort | Priority | +|-------------|-----------------|--------|----------| +| Link intersection | [X] sites | Medium | High | +| Broken links | [X] sites | Low | High | +| Resource pages | [X] sites | Medium | Medium | + +## Competitive Position + +Your referring domains rank #[X] among [Y] competitors. + +| Rank | Domain | Referring Domains | +|------|--------|-------------------| +| 1 | [domain] | [X] | +| 2 | [domain] | [X] | +| 3 | [domain] | [X] | + +## Recommended Actions + +### Immediate (This Week) +- [ ] Disavow [X] toxic links identified +- [ ] Reach out to [X] unlinked mentions + +### Short-term (This Month) +- [ ] Pursue [X] link intersection opportunities +- [ ] Fix [X] broken link opportunities +- [ ] Recover [X] recently lost links + +### Long-term (This Quarter) +- [ ] Create linkable asset targeting [topic] +- [ ] Launch guest posting campaign +- [ ] Build [X] resource page links + +## KPIs to Track + +| Metric | Current | 3-Month Target | +|--------|---------|----------------| +| Referring domains | [X] | [Y] | +| Average DA of new links | [X] | [Y] | +| Link velocity | [X]/mo | [Y]/mo | +| Toxic link % | [X]% | <5% | +``` diff --git a/.cursor/skills/backlink-analyzer/references/link-quality-rubric.md b/.cursor/skills/backlink-analyzer/references/link-quality-rubric.md new file mode 100644 index 0000000000..03e801a492 --- /dev/null +++ b/.cursor/skills/backlink-analyzer/references/link-quality-rubric.md @@ -0,0 +1,292 @@ +# Link Quality Rubric + +Comprehensive reference for evaluating backlink quality. Use this rubric to assess individual links, audit entire link profiles, perform competitive link gap analysis, and prepare disavow files. + +--- + +## 1. Individual Link Quality Evaluation + +### Scoring Methodology + +Evaluate each link across six factors. Multiply score (1-5) by factor weight to produce a weighted score. Sum all weighted scores for a final Link Quality Score (LQS). + +**Rating Scale:** +- **LQS 4.0-5.0**: Premium link — high authority, topically relevant, editorial placement +- **LQS 2.5-3.9**: Acceptable link — provides value, typical of healthy profiles +- **LQS 1.0-2.4**: Low quality — minimal value, review for potential risk + +### Factor 1: Domain Authority (25% weight) + +| Score | DR / DA Range | Characteristics | Examples | +|-------|-------------|-----------------|---------| +| 5 | DR 70+ | Major publication, established authority | NYTimes, Forbes, BBC, major university sites | +| 4 | DR 50-69 | Strong domain, recognized in industry | Industry publications, large blogs, government sites | +| 3 | DR 30-49 | Moderate authority, established site | Mid-tier blogs, regional publications, niche authorities | +| 2 | DR 15-29 | Low authority, newer or smaller site | Small blogs, newer companies, personal sites | +| 1 | DR <15 | Very low authority | New sites, abandoned sites, thin content sites | + +**Notes:** +- DR/DA is a proxy, not the sole indicator. A DR 30 site that is highly relevant to your niche may be more valuable than a DR 70 site in an unrelated field. +- Check if the domain's authority is organic (earned over time) or inflated (bought links, PBN). + +### Factor 2: Topical Relevance (25% weight) + +| Score | Relevance Level | Description | +|-------|----------------|-------------| +| 5 | Exact match | Same niche, same subtopic. A link from a CRM review site to your CRM product. | +| 4 | Closely related | Same industry, adjacent topic. A marketing blog linking to your email tool. | +| 3 | Broadly related | Same general field. A business blog linking to your SaaS product. | +| 2 | Tangentially related | Loose connection. A general news site mentioning your product in a tech roundup. | +| 1 | Unrelated | No topical connection. A cooking blog linking to your B2B software. | + +**How to assess relevance:** +1. Read the linking page content. Is it about your topic? +2. Check the linking site's overall focus. Is it in your industry? +3. Look at the surrounding content. Does the link make editorial sense? +4. Check the site's other outbound links. Are they topically coherent? + +### Factor 3: Traffic to Linking Page (15% weight) + +| Score | Estimated Monthly Traffic | Characteristics | +|-------|--------------------------|-----------------| +| 5 | 10,000+ visits/month | High-traffic page, likely drives referral traffic | +| 4 | 1,000-9,999 visits/month | Solid traffic, some referral value | +| 3 | 100-999 visits/month | Moderate traffic, primarily SEO value | +| 2 | 10-99 visits/month | Low traffic, SEO value only | +| 1 | <10 visits/month | No meaningful traffic, minimal value | + +**Why traffic matters:** +- Links from pages with real traffic are more likely to be genuine editorial placements. +- Google likely weights links from pages that receive traffic more highly. +- Referral traffic from the link provides direct business value beyond SEO. + +### Factor 4: Link Position (15% weight) + +| Score | Position | Description | +|-------|----------|-------------| +| 5 | In-content, editorial | Naturally placed within the article body as a citation or resource | +| 4 | In-content, contextual | Within the body text but in a "resources" or "further reading" section | +| 3 | Author bio or about section | Part of a contributor's bio or about page | +| 2 | Sidebar or dedicated links section | Widget, blogroll, or sidebar placement | +| 1 | Footer, sitewide, or hidden | Footer link, sitewide template link, or visually obscured | + +**Key principle:** Editorial in-content links carry the most weight because they represent a genuine endorsement. Footer and sitewide links are devalued by search engines. + +### Factor 5: Anchor Text (10% weight) + +| Score | Anchor Type | Example (for a CRM product) | +|-------|------------|----------------------------| +| 5 | Descriptive, natural | "this customer relationship management platform" | +| 4 | Partial match, natural | "CRM tools for small businesses" | +| 3 | Brand name | "Acme CRM" | +| 2 | Naked URL | "https://acmecrm.com" | +| 1 | Generic | "click here", "read more", "this website" | + +**Important nuance:** A natural link profile has a MIX of all anchor types. Too many exact-match anchors (score 5) can signal manipulation. The ideal distribution is: +- Brand anchors: 30-40% +- Naked URLs: 15-25% +- Generic anchors: 10-20% +- Descriptive/partial match: 15-25% +- Exact match: 5-15% + +### Factor 6: Follow Status (10% weight) + +| Score | Status | Description | +|-------|--------|-------------| +| 5 | Dofollow, editorial | Standard followed link from editorial content | +| 4 | Dofollow, non-editorial | Followed link from directory, profile, or user-generated content | +| 3 | Sponsored (rel="sponsored") | Properly disclosed sponsored/paid link | +| 2 | UGC (rel="ugc") | User-generated content link (forums, comments) | +| 1 | Nofollow (rel="nofollow") | Explicitly nofollowed link | + +**Notes:** +- Google treats nofollow as a "hint" rather than a directive since 2019. +- Nofollow links from high-authority sites (e.g., Wikipedia) still provide brand value and referral traffic. +- A healthy profile naturally includes a mix of followed and nofollowed links. Typical ratio: 60-80% dofollow, 20-40% nofollow. + +--- + +## 2. Example Link Profile Assessments + +### Example A: Strong Link Profile + +| Characteristic | Value | Assessment | +|---------------|-------|-----------| +| Total referring domains | 1,200 | Healthy for a mid-size SaaS company | +| Dofollow ratio | 72% | Natural distribution | +| Average linking domain DR | 38 | Solid average authority | +| Top anchor: brand name | 35% | Natural brand dominance | +| Exact match anchors | 8% | Within safe range | +| Topical relevance (sampled) | 75% related | Strong relevance signal | +| Link velocity | +25/month net | Steady organic growth | +| Toxic link estimate | 3% | Below 5% threshold — healthy | + +**Verdict:** Healthy profile with natural link distribution. Continue current strategy. + +### Example B: At-Risk Link Profile + +| Characteristic | Value | Assessment | +|---------------|-------|-----------| +| Total referring domains | 800 | Adequate but thin for competitive niche | +| Dofollow ratio | 92% | Suspiciously high — may indicate link manipulation | +| Average linking domain DR | 18 | Low average authority | +| Top anchor: exact match keyword | 42% | Over-optimized — risk of penalty | +| Exact match anchors | 42% | Far above safe threshold (>15%) | +| Topical relevance (sampled) | 30% related | Many irrelevant links | +| Link velocity | +80/month net | Unnaturally high — investigate | +| Toxic link estimate | 18% | Above 10% threshold — action needed | + +**Verdict:** Profile shows signs of manipulation. Immediate actions needed: disavow toxic links, diversify anchor text, slow down link acquisition pace. + +### Example C: New Site Link Profile + +| Characteristic | Value | Assessment | +|---------------|-------|-----------| +| Total referring domains | 45 | Expected for a 6-month-old site | +| Dofollow ratio | 65% | Natural | +| Average linking domain DR | 28 | Reasonable for early-stage outreach | +| Top anchor: brand name | 40% | Healthy | +| Exact match anchors | 5% | Conservative and safe | +| Topical relevance (sampled) | 80% related | Well-targeted outreach | +| Link velocity | +8/month net | Appropriate for new site | +| Toxic link estimate | 1% | Clean profile | + +**Verdict:** Healthy foundation. Focus on scaling link acquisition while maintaining quality standards. + +--- + +## 3. Competitive Link Gap Analysis Methodology + +### Step-by-Step Process + +**Step 1: Identify competitors** +Select 3-5 direct competitors who rank for your target keywords. + +**Step 2: Pull referring domain data** +Export the full referring domain list for each competitor from ~~link database. + +**Step 3: Create intersection matrix** + +| Referring Domain | You | Comp 1 | Comp 2 | Comp 3 | Overlap Count | +|-----------------|-----|--------|--------|--------|---------------| +| example-a.com | No | Yes | Yes | Yes | 3 | +| example-b.com | No | Yes | Yes | No | 2 | +| example-c.com | No | Yes | No | No | 1 | +| example-d.com | Yes | Yes | Yes | Yes | 3 (already have) | + +**Step 4: Prioritize opportunities** + +| Priority | Criteria | Rationale | +|----------|---------|-----------| +| Highest | Links to 3+ competitors, DR 50+, relevant | If all competitors have it, it is likely linkable | +| High | Links to 2+ competitors, DR 30+, relevant | Strong signal of willingness to link in niche | +| Medium | Links to 1 competitor, DR 50+, relevant | May be less accessible but high value | +| Lower | Links to 1 competitor, DR <30, or low relevance | Diminishing returns | + +**Step 5: Analyze link context** +For each high-priority opportunity, visit the actual linking page to understand: +- Why did they link to your competitor? (resource page, mention, guest post, etc.) +- What content on your site could replace or complement that link? +- What outreach angle would work? (broken link, better resource, relationship) + +**Step 6: Create outreach plan** +Build a prioritized list with contact information, outreach angle, and template selection. + +--- + +## 4. Disavow File Format Guide + +### When to Disavow + +Only disavow links when you have clear evidence of risk. Unnecessary disavow can hurt your rankings. + +| Situation | Disavow? | Reasoning | +|-----------|----------|-----------| +| Obvious PBN links | Yes | Clear manipulation signal | +| Paid links you cannot get removed | Yes | After attempting removal | +| Spam attack (negative SEO) | Yes | Protect from third-party manipulation | +| Low-quality directory links | Maybe | Only if pattern is excessive | +| Foreign language spam | Yes | If clearly unnatural | +| Low-DA sites with real content | No | Low quality is not toxic | +| Nofollow links from any source | No | Already nofollowed; no risk | + +### Disavow File Format + +The disavow file is a plain text file (.txt) uploaded to Google Search Console. + +``` +# Disavow file for example.com +# Generated: [date] +# Reason: Toxic link cleanup + +# Individual URLs to disavow +https://spam-site.com/page-with-link +https://another-spam.com/toxic-page + +# Entire domains to disavow (use for sites with multiple toxic links) +domain:link-farm-example.com +domain:pbn-network-site.com +domain:spam-directory.net +``` + +### Disavow File Best Practices + +| Practice | Why | +|----------|-----| +| Comment every entry or group | Future auditors need to understand why | +| Use `domain:` for sites with multiple bad links | More thorough than individual URLs | +| Use individual URLs when only one page is toxic | Avoid disavowing good links from the same domain | +| Keep a changelog | Track what was added and when | +| Review quarterly | Remove entries if domains have been cleaned up | +| Never disavow your own domain | Common mistake that causes severe damage | +| Back up before uploading | Keep previous version in case of errors | + +### Disavow Review Workflow + +| Step | Action | Tool | +|------|--------|------| +| 1 | Export full backlink profile | ~~link database | +| 2 | Filter for known toxic patterns | Spam score, DR <10, foreign spam | +| 3 | Manual review of flagged links | Visit each flagged domain | +| 4 | Attempt removal via email first | Contact webmasters | +| 5 | Wait 2 weeks for removal responses | Track outreach results | +| 6 | Add non-removed toxic links to disavow | Format as .txt file | +| 7 | Upload to Google Search Console | Disavow Links tool | +| 8 | Document all actions and dates | Internal records | +| 9 | Re-check in 4-6 weeks | Verify processing | + +--- + +## 5. Link Profile Health Benchmarks + +### Healthy Profile Indicators + +| Metric | Healthy Range | Warning Sign | Critical | +|--------|-------------|--------------|----------| +| Dofollow ratio | 60-80% | >90% | >95% | +| Exact match anchor % | <15% | 15-25% | >25% | +| Brand anchor % | 25-45% | <15% | <5% | +| Toxic link % | <5% | 5-10% | >10% | +| Referring domain growth | Positive, steady | Flat | Declining | +| Average linking DR | 25+ | 15-25 | <15 | +| Link diversity (unique domains / total links) | >0.3 | 0.1-0.3 | <0.1 | +| Topical relevance (sampled) | >60% | 40-60% | <40% | + +### Industry-Specific Benchmarks + +Authority expectations vary significantly by industry vertical. + +| Industry | Typical DR Range (Top 10 Sites) | Typical Referring Domains | Link Difficulty | +|----------|-------------------------------|--------------------------|----------------| +| Finance / Insurance | DR 60-90 | 5,000-50,000+ | Very High | +| Health / Medical | DR 50-85 | 3,000-30,000+ | Very High | +| Technology / SaaS | DR 40-80 | 1,000-20,000+ | High | +| E-commerce (general) | DR 35-75 | 500-15,000+ | High | +| Legal | DR 40-70 | 1,000-10,000+ | High | +| Education | DR 50-90 | 2,000-25,000+ | Medium-High | +| Local services | DR 15-45 | 50-500 | Medium | +| B2B niche | DR 25-60 | 200-5,000+ | Medium | +| Blog / Content site | DR 20-70 | 100-10,000+ | Medium | +| New startup | DR 5-25 | 10-200 | Starting point | + +_Note: These are general ranges. Actual requirements depend on your specific keyword competition._ diff --git a/.cursor/skills/backlink-analyzer/references/outreach-templates.md b/.cursor/skills/backlink-analyzer/references/outreach-templates.md new file mode 100644 index 0000000000..c6c25cf4b9 --- /dev/null +++ b/.cursor/skills/backlink-analyzer/references/outreach-templates.md @@ -0,0 +1,578 @@ +# Outreach Templates + +Copy-ready outreach email templates for each link building strategy. Includes subject line variations, follow-up sequences, personalization tips, and response handling scripts. + +--- + +## General Outreach Principles + +Before using any template, follow these rules: + +| Principle | Why It Matters | +|-----------|---------------| +| **Personalize every email** | Generic emails get deleted. Reference specific content. | +| **Lead with value** | Explain what is in it for them before making your ask. | +| **Keep it short** | 100-150 words maximum for initial outreach. | +| **One clear ask** | Do not combine multiple requests in one email. | +| **Professional sender address** | Use name@yourdomain.com, not a free email provider. | +| **No attachments on first email** | Attachments trigger spam filters and reduce trust. | +| **Follow up (once or twice)** | Most responses come from follow-ups, not initial emails. | +| **Track everything** | Log outreach in a spreadsheet or CRM for accountability. | + +--- + +## 1. Broken Link Building Templates + +### Template 1A: Broken Link — Direct Approach + +**Subject:** Found a broken link on your [topic] page + +**Body:** + +Hi [Name], + +I was reading your article on [specific article title] — great resource on [brief compliment about content]. + +I noticed the link to [description of broken link resource] in the [section name] section seems to be broken (returns a 404). + +I recently published a guide on [your topic] that covers similar ground: [Your URL] + +It might work as a replacement if you are updating the page. Either way, wanted to give you a heads-up about the broken link. + +Best, +[Your Name] + +--- + +### Template 1B: Broken Link — Roundup Page + +**Subject:** Quick heads-up about [their page title] + +**Body:** + +Hi [Name], + +Your [topic] resource page is one of my go-to references — really well curated. + +I noticed [X] links on the page are no longer working: +- [Broken URL 1] — returns 404 +- [Broken URL 2] — domain expired + +If you are updating the page, I have a [content type] that covers [topic]: [Your URL] + +Happy to suggest other replacement resources too if that would help. + +Thanks for maintaining such a useful list, +[Your Name] + +--- + +### Follow-Up (5-7 days after initial email) + +**Subject:** Re: [original subject] + +**Body:** + +Hi [Name], + +Just bumping this up in case it got buried. I spotted a broken link on your [page title] and thought you would want to know. + +No worries if the page is staying as-is — just wanted to make sure you saw it. + +[Your Name] + +--- + +## 2. Guest Post Pitching Templates + +### Template 2A: Guest Post — Topic Pitch + +**Subject:** Guest post idea: [proposed title] + +**Body:** + +Hi [Name], + +I have been following [their site name] for a while — your recent piece on [specific article] was especially [specific compliment]. + +I would love to contribute a guest post on [proposed topic]. Here is what I have in mind: + +**Title:** [Proposed title] +**Angle:** [1-2 sentences describing the unique angle] +**Why your readers would care:** [1 sentence on value to their audience] + +I have written for [1-2 relevant publications] previously. Here are a couple of samples: +- [Sample URL 1] +- [Sample URL 2] + +Would this be a fit for [their site name]? + +Best, +[Your Name] +[Your title / credentials] + +--- + +### Template 2B: Guest Post — Expertise Pitch + +**Subject:** [Your expertise area] contributor for [their site] + +**Body:** + +Hi [Name], + +I am [Your Name], a [your role/expertise] with [X years] experience in [field]. I noticed [their site] covers [topic area] extensively and thought I could contribute something useful. + +Three topic ideas that might work for your audience: + +1. [Title idea 1] — [one-line description] +2. [Title idea 2] — [one-line description] +3. [Title idea 3] — [one-line description] + +Happy to adjust angles or pitch different ideas. I can also share writing samples if helpful. + +Thanks, +[Your Name] + +--- + +### Follow-Up (7-10 days after initial email) + +**Subject:** Re: [original subject] + +**Body:** + +Hi [Name], + +Checking back on my guest post pitch. I know editorial calendars fill up fast, so no worries if the timing does not work. + +If any of the topics I suggested could work down the road, happy to keep in touch for a future slot. + +[Your Name] + +--- + +## 3. Resource Page Outreach Templates + +### Template 3A: Resource Page — Direct Suggestion + +**Subject:** Resource for your [topic] page + +**Body:** + +Hi [Name], + +I found your [topic] resource page while researching [related topic] — it is a really well-organized collection. + +I thought [your resource title] might be a good addition to the [specific section] section. It covers [brief description of what it covers and why it is useful]. + +Here is the link: [Your URL] + +No pressure at all — just thought it might be useful for your readers. + +Best, +[Your Name] + +--- + +### Template 3B: Resource Page — Value-Add Approach + +**Subject:** A few resources for your [topic] page + +**Body:** + +Hi [Name], + +I have been using your [topic] resource page as a reference and really appreciate the curation work. + +I wanted to suggest a few resources you might consider adding (not all mine): + +1. [External resource title] — [URL] — Great for [reason] +2. [Your resource title] — [Your URL] — Covers [topic] +3. [Another external resource] — [URL] — Useful for [reason] + +I included a couple of third-party resources alongside mine since they genuinely complement your page. + +Thanks for maintaining such a useful list, +[Your Name] + +--- + +## 4. Unlinked Mention Outreach Templates + +### Template 4A: Unlinked Brand Mention + +**Subject:** Thanks for mentioning [brand name] + +**Body:** + +Hi [Name], + +Just came across your article [article title] — thanks for mentioning [your brand/product]. Really appreciate the kind words about [specific thing they said]. + +Quick request: would you be able to add a link to [Your URL] where you mention us? It would help your readers find us directly and help us out with attribution. + +Totally understand if it is not possible. Either way, glad you found [product/service] useful. + +Best, +[Your Name] + +--- + +### Template 4B: Unlinked Data/Research Mention + +**Subject:** Thanks for citing our [research/data] + +**Body:** + +Hi [Name], + +I noticed you referenced our [study/statistic/data point] in your article [article title]. Thanks for citing our research. + +If you are able to add a link to the original source, it would help your readers verify the data and access the full [study/report]: [Your URL] + +We actually just updated it with [new data point] that might be relevant to your piece as well. + +Thanks, +[Your Name] + +--- + +### Follow-Up (5-7 days) + +**Subject:** Re: [original subject] + +**Body:** + +Hi [Name], + +Just a quick follow-up on adding a link for the mention of [brand/research] in your article. I know updating published content can be low priority, so no rush. + +If it helps, the exact URL is: [Your URL] + +Thanks again for the mention, +[Your Name] + +--- + +## 5. Digital PR / Data-Driven Outreach Templates + +### Template 5A: Original Research Pitch + +**Subject:** New data: [key finding headline] + +**Body:** + +Hi [Name], + +We just published [study/survey/analysis] that found [most surprising or newsworthy finding]. + +Key findings: +- [Finding 1 — the headline stat] +- [Finding 2 — supporting data] +- [Finding 3 — counterintuitive insight] + +Full report: [Your URL] + +Given your coverage of [their beat/topic], I thought this might be worth a mention. Happy to provide additional data, quotes, or custom analysis for your audience. + +[Your Name] +[Your title] + +--- + +### Template 5B: Expert Commentary Pitch + +**Subject:** Expert source for your [topic] coverage + +**Body:** + +Hi [Name], + +I saw you are covering [topic/trend] and thought I could be a useful source. + +I am [Your Name], [your credentials — brief]. I have [specific experience relevant to their coverage]. + +A couple of angles I could provide commentary on: +- [Angle 1] +- [Angle 2] + +Happy to jump on a quick call or provide written quotes. Available on short notice. + +[Your Name] +[Your title, company] +[Phone number for urgent requests] + +--- + +## 6. HARO / Source Request Templates + +### Template 6A: HARO Response — Expert Source + +**Subject:** [HARO] Re: [original query title] + +**Body:** + +Hi [Journalist Name], + +Re: your query on [topic]. + +**Source:** [Your Name], [Title] at [Company] +**Credentials:** [1-2 sentences on relevant expertise] + +**Response:** + +[2-3 paragraphs directly answering their query. Be specific, quotable, and concise. Lead with the most valuable insight.] + +**Key quote:** "[One highly quotable sentence they can use directly]" + +Happy to elaborate or provide additional data. Available at [email] or [phone]. + +[Your Name] + +--- + +### Template 6B: HARO Response — Data Source + +**Subject:** [HARO] Re: [original query title] — with data + +**Body:** + +Hi [Journalist Name], + +For your piece on [topic], here is data from our [study/platform/analysis]: + +- [Statistic 1]: [data point with context] +- [Statistic 2]: [data point with context] +- [Statistic 3]: [data point with context] + +Source: [Your URL for attribution] + +**Expert quote from [Your Name], [Title]:** +"[Quotable insight interpreting the data]" + +Full dataset available if needed for additional analysis. + +[Your Name] +[Contact info] + +--- + +## 7. Skyscraper Technique Templates + +### Template 7A: Skyscraper — Better Resource + +**Subject:** Updated resource on [topic] + +**Body:** + +Hi [Name], + +I noticed you linked to [competitor's article title] in your post on [their article title]. + +We just published an updated version of that topic: [Your URL] + +It includes [specific improvements over the original]: +- [Improvement 1 — e.g., "2025 data instead of 2022"] +- [Improvement 2 — e.g., "interactive calculator included"] +- [Improvement 3 — e.g., "covers 3 additional sub-topics"] + +If you think it would be a better resource for your readers, I would appreciate you considering swapping the link. No worries either way. + +Best, +[Your Name] + +--- + +## 8. Relationship Building Templates + +### Template 8A: Initial Relationship — No Ask + +**Subject:** Loved your piece on [topic] + +**Body:** + +Hi [Name], + +Just read your article on [specific article title] and wanted to say it was genuinely one of the best pieces I have read on [topic]. + +The section on [specific section] was especially useful — I actually shared it with my team and we are implementing [specific takeaway]. + +No ask here, just wanted to let you know your work is making an impact. + +[Your Name] + +--- + +### Template 8B: Follow-Up After Relationship Building (2-4 weeks later) + +**Subject:** [New topic] — thought of your readers + +**Body:** + +Hi [Name], + +Following up on our exchange a few weeks back. I just published something your audience might find useful: [Your URL] + +It covers [brief description] with a focus on [specific angle]. + +Would love to hear your thoughts if you get a chance to read it. + +Best, +[Your Name] + +--- + +## 9. Follow-Up Sequences + +### Standard Follow-Up Timeline + +| Email | Timing | Purpose | Tone | +|-------|--------|---------|------| +| Initial outreach | Day 0 | Make the ask | Professional, value-forward | +| Follow-up 1 | Day 5-7 | Gentle reminder | Casual, brief | +| Follow-up 2 | Day 14 | Final attempt | Short, no-pressure close | +| Stop | After follow-up 2 | Do not send more | Move on | + +### Follow-Up 2 Template (Final Attempt) + +**Subject:** Re: [original subject] + +**Body:** + +Hi [Name], + +Last follow-up on this — I know you are busy. + +[One-sentence reminder of what you asked] + +If the timing is not right, no worries at all. Feel free to bookmark [Your URL] for whenever it might be useful. + +Best, +[Your Name] + +--- + +## 10. Response Handling Scripts + +### Positive Response — They Will Add the Link + +**Reply:** + +That is great, [Name] — really appreciate it. + +The exact URL is: [Your URL] +Preferred anchor text (just a suggestion): [anchor text] + +Let me know if you need anything else. Happy to return the favor anytime. + +Best, +[Your Name] + +--- + +### Positive Response — They Want a Guest Post + +**Reply:** + +Wonderful, I would love to contribute. Here is what I am thinking: + +**Title:** [Proposed title] +**Outline:** +1. [Section 1] +2. [Section 2] +3. [Section 3] + +**Estimated length:** [word count] +**Delivery timeline:** [date] + +Do you have any editorial guidelines or specific requirements I should follow? + +Best, +[Your Name] + +--- + +### Neutral Response — They Are Interested but Noncommittal + +**Reply:** + +Totally understand, [Name]. No rush at all. + +I will keep [Your URL] updated with [latest data/content], so it will be here whenever the timing works. + +Feel free to reach out if I can ever be a source or contributor for [their site]. + +Best, +[Your Name] + +--- + +### Negative Response — They Decline + +**Reply:** + +Completely understand, [Name]. Thanks for letting me know. + +If anything changes or if I can ever be helpful as a source, do not hesitate to reach out. + +Best, +[Your Name] + +_Note: Never argue, push back, or send additional follow-ups after a decline. Keep the relationship positive for potential future opportunities._ + +--- + +### No Response — After Full Sequence + +Do not send further emails. Add to a "re-engage in 3-6 months" list. When you re-engage, use a completely new angle or piece of content. Never reference the fact that they did not respond previously. + +--- + +## 11. Personalization Tips + +### Research Checklist Before Sending + +| Check | Where to Find | How to Use | +|-------|-------------|-----------| +| Their name (correct spelling) | About page, LinkedIn, byline | Use in greeting and body | +| Recent article they wrote | Their blog, Google "[name] + [site]" | Reference in opening line | +| Their social media | Twitter/X, LinkedIn | Mention a recent post or shared interest | +| Their publication's audience | About page, media kit | Tailor your value proposition | +| Content they have linked to before | ~~link database, their recent articles | Match the type of content they prefer | +| How they prefer to be contacted | Website contact page, social bio | Some prefer Twitter DMs over email | + +### Personalization Levels + +| Level | Effort | Response Rate Impact | When to Use | +|-------|--------|---------------------|-------------| +| **Zero** (template only) | Minimal | Baseline (lowest) | Never recommended | +| **Basic** (name + site name) | Low | +20-30% | Bulk outreach to lower-priority targets | +| **Moderate** (+ specific article reference) | Medium | +50-80% | Standard outreach to mid-tier targets | +| **Deep** (+ shared interest, social reference, mutual connection) | High | +100-200% | High-priority targets (DR 60+ sites, key relationships) | + +--- + +## 12. Subject Line Variations by Strategy + +### High-Performing Subject Line Patterns + +| Strategy | Subject Lines (pick one) | +|----------|------------------------| +| **Broken link** | "Found a broken link on your [topic] page" / "Quick heads-up about [page title]" / "Broken resource on [their site]" | +| **Guest post** | "Guest post idea: [title]" / "[Topic] contributor for [their site]" / "Content pitch for [their site]" | +| **Resource page** | "Resource for your [topic] page" / "Suggestion for your [topic] list" / "Addition for [page title]?" | +| **Unlinked mention** | "Thanks for mentioning [brand]" / "Re: your mention of [brand/data]" / "Quick favor re: [their article]" | +| **Digital PR** | "New data: [headline stat]" / "Exclusive: [finding]" / "[Topic] research for your coverage" | +| **Skyscraper** | "Updated resource on [topic]" / "Better version of [competitor content]" / "Thought you'd want to see this" | + +### Subject Lines to Avoid + +| Avoid | Why | +|-------|-----| +| "Link exchange opportunity" | Screams spam and violates Google guidelines | +| "SEO partnership" | Immediately signals manipulative intent | +| ALL CAPS or excessive punctuation | Triggers spam filters, looks unprofessional | +| "I'd love a backlink" | Too direct; leads with your need, not their value | +| Misleading subjects ("Re:" when no prior conversation) | Damages trust immediately | +| Long subjects (>60 characters) | Gets truncated in inbox, lower open rates | diff --git a/.cursor/skills/competitor-analysis/SKILL.md b/.cursor/skills/competitor-analysis/SKILL.md new file mode 100644 index 0000000000..11c1efc917 --- /dev/null +++ b/.cursor/skills/competitor-analysis/SKILL.md @@ -0,0 +1,309 @@ +--- +name: competitor-analysis +description: 'Analyze competitor SEO/GEO: keywords, content, backlinks, AI citations, traffic share gaps. 竞品分析/竞争对手' +version: "6.0.0" +license: Apache-2.0 +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when analyzing competitor SEO strategy, comparing domains, benchmarking against competitors, or finding competitor keywords and content gaps." +argument-hint: "" +metadata: + author: aaron-he-zhu + version: "6.0.0" + geo-relevance: "medium" + tags: + - seo + - geo + - competitor-analysis + - competitive-intelligence + - benchmarking + - competitor-keywords + - competitor-backlinks + - market-analysis + - spyfu-alternative + - 竞品分析 + - 競合分析 + - 경쟁분석 + - analisis-competitivo + triggers: + # EN-formal + - "analyze competitors" + - "competitor SEO" + - "competitive analysis" + - "competitor keywords" + - "competitor backlinks" + - "market analysis" + - "competitive intelligence" + # EN-casual + - "what are my competitors doing" + - "what are they doing differently" + - "why do they rank higher" + - "spy on competitor SEO" + - "what are they doing better" + - "why do they outrank me" + # EN-question + - "who are my SEO competitors" + - "how do I beat my competitors" + - "why do competitors rank higher" + # EN-competitor + - "SpyFu alternative" + - "Semrush competitor analysis" + - "Ahrefs competitor tool" + # ZH-pro + - "竞品分析" + - "竞争对手分析" + - "竞品SEO" + - "对标分析" + - "竞争情报" + # ZH-casual + - "竞品怎么做的" + - "他们排名为什么比我高" + - "看看对手在干什么" + - "为什么他们排名好" + # JA + - "競合分析" + - "競合SEO分析" + - "ライバル分析" + # KO + - "경쟁 분석" + - "경쟁사 SEO" + - "경쟁사 키워드" + # ES + - "análisis de competidores" + - "análisis competitivo SEO" + # PT + - "análise de concorrentes" + # Misspellings + - "competitve analysis" + - "compeditor analysis" +--- + +# Competitor Analysis + + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This research skill follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + + +This skill provides comprehensive analysis of competitor SEO and GEO strategies, revealing what's working in your market and identifying opportunities to outperform the competition. + +**System role**: Research layer skill. It turns market signals into reusable strategic inputs for the rest of the library. + +## When This Must Trigger + +Use this when the conversation involves any of these situations — even if the user does not use SEO terminology: + +Use this whenever the task needs reusable market intelligence that should influence strategy, not just an ad hoc answer. + +- Entering a new market or niche +- Planning content strategy based on competitor success +- Understanding why competitors rank higher +- Finding backlink and partnership opportunities +- Identifying content gaps competitors are missing +- Analyzing competitor AI citation strategies +- Benchmarking your SEO performance + +## What This Skill Does + +1. **Keyword Analysis**: Identifies keywords competitors rank for +2. **Content Audit**: Analyzes competitor content strategies and formats +3. **Backlink Profiling**: Reviews competitor link-building approaches +4. **Technical Assessment**: Evaluates competitor site health +5. **GEO Analysis**: Identifies how competitors appear in AI responses +6. **Gap Identification**: Finds opportunities competitors miss +7. **Strategy Extraction**: Reveals actionable insights from competitor success + +## Quick Start + +Start with one of these prompts. Finish with a short handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Basic Competitor Analysis + +``` +Analyze SEO strategy for [competitor URL] +``` + +``` +Compare my site [URL] against [competitor 1], [competitor 2], [competitor 3] +``` + +### Specific Analysis + +``` +What content is driving the most traffic for [competitor]? +``` + +``` +Analyze why [competitor] ranks #1 for [keyword] +``` + +### GEO-Focused Analysis + +``` +How is [competitor] getting cited in AI responses? What can I learn? +``` + +## Skill Contract + +**Expected output**: a prioritized research brief, evidence-backed findings, and a short handoff summary ready for `memory/research/`. + +- **Reads**: user goals, target market inputs, available tool data, and prior strategy from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available. +- **Writes**: a user-facing research deliverable plus a reusable summary that can be stored under `memory/research/`. +- **Promotes**: durable keyword priorities, competitor facts, entity candidates, and strategic decisions to `CLAUDE.md`, `memory/decisions.md`, and `memory/research/`; hand canonical entity work to `entity-optimizer`. +- **Next handoff**: use the `Next Best Skill` below when the findings are ready to drive action. + +## Data Sources + +> **Note:** All integrations are optional. This skill works without any API keys — users provide data manually when no tools are connected. + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +**With ~~SEO tool + ~~analytics + ~~AI monitor connected:** +Automatically pull competitor keyword rankings, backlink profiles, top performing content, domain authority metrics from ~~SEO tool. Compare against your site's metrics from ~~analytics and ~~search console. Check AI citation patterns for both your site and competitors using ~~AI monitor. + +**With manual data only:** +Ask the user to provide: +1. Competitor URLs to analyze (2-5 recommended) +2. Your own site URL and current metrics (traffic, rankings if known) +3. Industry or niche context +4. Specific aspects to focus on (keywords, content, backlinks, etc.) +5. Any known competitor strengths or weaknesses + +Proceed with the full analysis using provided data. Note in the output which metrics are from automated collection vs. user-provided data. + +## Instructions + +When a user requests competitor analysis: + +1. **Identify Competitors** + + If not specified, help identify competitors: + + ```markdown + ### Competitor Identification Framework + + **Direct Competitors** (same product/service) + - Search "[your main keyword]" and note top 5 organic results + - Check who's advertising for your keywords + - Ask: Who do customers compare you to? + + **Indirect Competitors** (different solution, same problem) + - Search problem-focused keywords + - Look at alternative solutions + + **Content Competitors** (compete for same keywords) + - May not sell same product + - Rank for your target keywords + - Include media sites, blogs, aggregators + ``` + +2. **Gather Competitor Data** + + Collect for each competitor: URL, domain age, estimated traffic, domain authority, business model, target audience, and key offerings. + +3. **Analyze Keyword Rankings** + + Document total keywords ranking, top 10/top 3 counts, top performing keywords (with position, volume, traffic, page URL), keyword distribution by intent, and keyword gaps. + +4. **Audit Content Strategy** + + Analyze content volume by type, top performing content, content patterns (word count, frequency, formats), content themes, and success factors. + +5. **Analyze Backlink Profile** + + Review total backlinks, referring domains, link quality distribution, top linking domains, link acquisition patterns, and linkable assets. + +6. **Technical SEO Assessment** + + Evaluate Core Web Vitals, mobile-friendliness, site architecture, internal linking quality, URL structure, and technical strengths/weaknesses. + +7. **GEO/AI Citation Analysis** + + Test competitor content in AI systems: document which queries cite them, GEO strategies observed (definitions, statistics, Q&A, authority signals), and GEO opportunities they are missing. + +8. **Synthesize Competitive Intelligence** + + Produce a final report with: Executive Summary, Competitive Landscape comparison table, CITE domain authority comparison, Strengths to Learn From, Weaknesses to Exploit, Keyword Opportunities, Content Strategy Recommendations, and Action Plan (Immediate / Short-term / Long-term). + + > **Reference**: See [references/analysis-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/competitor-analysis/references/analysis-templates.md) for detailed templates for each step. + +## Validation Checkpoints + +### Input Validation +- [ ] Competitor URLs verified as relevant to your niche +- [ ] Analysis scope defined (comprehensive or specific focus area) +- [ ] Your own site metrics available for comparison +- [ ] Minimum 2-3 competitors identified for meaningful patterns + +### Output Validation +- [ ] Every recommendation cites specific data points (not generic advice) +- [ ] Competitor strengths backed by measurable evidence (metrics, rankings) +- [ ] Opportunities based on identifiable gaps, not assumptions +- [ ] Action plan items are specific and actionable (not vague strategies) +- [ ] Source of each data point clearly stated (~~SEO tool data, ~~analytics data, ~~AI monitor data, user-provided, or estimated) + +## Example + +> **Reference**: See [references/example-report.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/competitor-analysis/references/example-report.md) for a complete example analyzing HubSpot's marketing keyword dominance. + +## Advanced Analysis Types + +### Content Gap Analysis + +``` +Show me content [competitor] has that I don't, sorted by traffic potential +``` + +### Link Intersection + +``` +Find sites linking to [competitor 1] AND [competitor 2] but not me +``` + +### SERP Feature Analysis + +``` +What SERP features do competitors win? (Featured snippets, PAA, etc.) +``` + +### Historical Tracking + +``` +How has [competitor]'s SEO strategy evolved over the past year? +``` + +## Tips for Success + +1. **Analyze 3-5 competitors** for comprehensive view +2. **Include indirect competitors** - they often have innovative approaches +3. **Look beyond rankings** - analyze content quality, user experience +4. **Study their failures** - avoid their mistakes +5. **Monitor regularly** - competitor strategies evolve +6. **Focus on actionable insights** - what can you actually implement? + + + +### Save Results + +After delivering findings to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to `memory/research/competitor-analysis/YYYY-MM-DD-.md` containing: +- One-line headline finding +- Top 3-5 actionable items +- Open loops or blockers +- Source data references + +If any findings should influence ongoing strategy, recommend promoting key conclusions to `memory/hot-cache.md`. + +## Reference Materials + +- [Analysis Templates](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/competitor-analysis/references/analysis-templates.md) — Detailed templates for each analysis step (profile, keywords, content, backlinks, technical, GEO, synthesis) +- [Battlecard Template](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/competitor-analysis/references/battlecard-template.md) — Quick-reference competitive battlecard for sales and marketing teams +- [Positioning Frameworks](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/competitor-analysis/references/positioning-frameworks.md) — Positioning maps, messaging matrices, narrative analysis, and differentiation frameworks +- [Example Report](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/competitor-analysis/references/example-report.md) — Complete example analyzing HubSpot's marketing keyword dominance + +## Next Best Skill + +- **Primary**: [content-gap-analysis](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/content-gap-analysis/SKILL.md) — turn competitor findings into a focused opportunity map. diff --git a/.cursor/skills/competitor-analysis/references/analysis-templates.md b/.cursor/skills/competitor-analysis/references/analysis-templates.md new file mode 100644 index 0000000000..1e1e157167 --- /dev/null +++ b/.cursor/skills/competitor-analysis/references/analysis-templates.md @@ -0,0 +1,285 @@ +# Competitor Analysis — Analysis Templates + +Templates for each step of the competitor analysis workflow. Use these to structure your output. + +## Competitor Profile Template + +```markdown +## Competitor Profile: [Name] + +**Basic Info** +- URL: [website] +- Domain Age: [years] +- Estimated Traffic: [monthly visits] +- Domain Authority/Rating: [score] + +**Business Model** +- Type: [SaaS/E-commerce/Content/etc.] +- Target Audience: [description] +- Key Offerings: [products/services] +``` + +## Keyword Analysis Template + +```markdown +### Keyword Analysis: [Competitor] + +**Total Keywords Ranking**: [X] +**Keywords in Top 10**: [X] +**Keywords in Top 3**: [X] + +#### Top Performing Keywords + +| Keyword | Position | Volume | Traffic Est. | Page | +|---------|----------|--------|--------------|------| +| [kw 1] | [pos] | [vol] | [traffic] | [url] | +| [kw 2] | [pos] | [vol] | [traffic] | [url] | + +#### Keyword Distribution by Intent + +- Informational: [X]% ([keywords]) +- Commercial: [X]% ([keywords]) +- Transactional: [X]% ([keywords]) +- Navigational: [X]% ([keywords]) + +#### Keyword Gaps (They rank, you don't) + +| Keyword | Their Position | Volume | Opportunity | +|---------|----------------|--------|-------------| +| [kw 1] | [pos] | [vol] | [analysis] | +``` + +## Content Analysis Template + +```markdown +### Content Analysis: [Competitor] + +**Content Volume** +- Total Pages: [X] +- Blog Posts: [X] +- Landing Pages: [X] +- Resource Pages: [X] + +**Content Performance** + +#### Top Performing Content + +| Title | URL | Est. Traffic | Keywords | Backlinks | +|-------|-----|--------------|----------|-----------| +| [title 1] | [url] | [traffic] | [X] | [X] | + +**Content Patterns** + +- Average word count: [X] words +- Publishing frequency: [X] posts/month +- Content formats used: + - Blog posts: [X]% + - Guides/tutorials: [X]% + - Case studies: [X]% + - Tools/calculators: [X]% + - Videos: [X]% + +**Content Themes** + +| Theme | # Articles | Combined Traffic | +|-------|------------|------------------| +| [theme 1] | [X] | [traffic] | +| [theme 2] | [X] | [traffic] | + +**What Makes Their Content Successful** + +1. [Success factor 1 with example] +2. [Success factor 2 with example] +3. [Success factor 3 with example] +``` + +## Backlink Analysis Template + +```markdown +### Backlink Analysis: [Competitor] + +**Overview** +- Total Backlinks: [X] +- Referring Domains: [X] +- Domain Rating: [X] + +**Link Quality Distribution** +- High Authority (DR 70+): [X]% +- Medium Authority (DR 30-69): [X]% +- Low Authority (DR <30): [X]% + +**Top Linking Domains** + +| Domain | DR | Link Type | Target Page | +|--------|-----|-----------|-------------| +| [domain 1] | [DR] | [type] | [page] | + +**Link Acquisition Patterns** + +- Guest posts: [X]% +- Editorial/organic: [X]% +- Resource pages: [X]% +- Directories: [X]% +- Other: [X]% + +**Linkable Assets (Content attracting links)** + +| Asset | Type | Backlinks | Why It Works | +|-------|------|-----------|--------------| +| [asset 1] | [type] | [X] | [reason] | +``` + +## Technical SEO Assessment Template + +```markdown +### Technical Analysis: [Competitor] + +**Site Performance** +- Core Web Vitals: [Pass/Fail] +- LCP: [X]s +- FID: [X]ms +- CLS: [X] +- Mobile-friendly: [Yes/No] + +**Site Structure** +- Site architecture depth: [X] levels +- Internal linking quality: [Rating] +- URL structure: [Clean/Messy] +- Sitemap present: [Yes/No] + +**Technical Strengths** +1. [Strength 1] +2. [Strength 2] + +**Technical Weaknesses** +1. [Weakness 1] +2. [Weakness 2] +``` + +## GEO/AI Citation Analysis Template + +```markdown +### GEO Analysis: [Competitor] + +**AI Visibility Assessment** + +Test competitor content in AI systems for relevant queries: + +| Query | AI Mentions Competitor? | What's Cited | Why | +|-------|------------------------|--------------|-----| +| [query 1] | Yes/No | [content] | [reason] | +| [query 2] | Yes/No | [content] | [reason] | + +**GEO Strategies Observed** + +1. **Clear Definitions** + - Example: [quote from their content] + - Effectiveness: [rating] + +2. **Quotable Statistics** + - Example: [quote from their content] + - Effectiveness: [rating] + +3. **Q&A Format Content** + - Examples found: [X] pages + - Topics covered: [list] + +4. **Authority Signals** + - Expert authorship: [Yes/No] + - Citations to sources: [Yes/No] + - Original research: [Yes/No] + +**GEO Opportunities They're Missing** + +| Topic | Why Missing | Your Opportunity | +|-------|-------------|------------------| +| [topic 1] | [reason] | [action] | +``` + +## Synthesis Report Template + +```markdown +# Competitive Analysis Report + +**Analysis Date**: [Date] +**Competitors Analyzed**: [List] +**Your Site**: [URL] + +## Executive Summary + +[2-3 paragraph overview of key findings and recommendations] + +## Competitive Landscape + +| Metric | You | Competitor 1 | Competitor 2 | Competitor 3 | +|--------|-----|--------------|--------------|--------------| +| Domain Authority | [X] | [X] | [X] | [X] | +| Organic Traffic | [X] | [X] | [X] | [X] | +| Keywords Top 10 | [X] | [X] | [X] | [X] | +| Backlinks | [X] | [X] | [X] | [X] | +| Content Pages | [X] | [X] | [X] | [X] | + +**Domain Authority Comparison (Recommended)** + +When domain-level comparison is needed, run `domain-authority-auditor` for each competitor to get CITE scores: + +| Domain | CITE Score | C (Citation) | I (Identity) | T (Trust) | E (Eminence) | Veto | +|--------|-----------|-------------|-------------|----------|-------------|------| +| Your domain | [score] | [score] | [score] | [score] | [score] | [pass/fail] | +| Competitor 1 | [score] | [score] | [score] | [score] | [score] | [pass/fail] | +| Competitor 2 | [score] | [score] | [score] | [score] | [score] | [pass/fail] | + +This reveals domain authority gaps that inform link building and brand strategy beyond keyword-level competition. + +## Competitor Strengths to Learn From + +### [Competitor 1] +- **Strength**: [description] +- **Why It Works**: [analysis] +- **How to Apply**: [action item] + +[Repeat for each competitor] + +## Competitor Weaknesses to Exploit + +### Gap 1: [Description] +- Who's weak: [competitors] +- Opportunity size: [estimate] +- Recommended action: [specific steps] + +[Repeat for each gap] + +## Keyword Opportunities + +### Keywords to Target (Competitor overlap) +| Keyword | Volume | Avg Position | Best Strategy | +|---------|--------|--------------|---------------| +| [kw] | [vol] | [pos] | [strategy] | + +### Untapped Keywords (No competitor coverage) +| Keyword | Volume | Difficulty | Opportunity | +|---------|--------|------------|-------------| +| [kw] | [vol] | [diff] | [description] | + +## Content Strategy Recommendations + +Based on competitor analysis: + +1. **Create**: [Content type] about [topic] because [reason] +2. **Improve**: [Existing content] to match/exceed [competitor content] +3. **Promote**: [Content] to sites like [competitor's link sources] + +## Action Plan + +### Immediate (This Week) +1. [Action item] +2. [Action item] + +### Short-term (This Month) +1. [Action item] +2. [Action item] + +### Long-term (This Quarter) +1. [Action item] +2. [Action item] +``` diff --git a/.cursor/skills/competitor-analysis/references/battlecard-template.md b/.cursor/skills/competitor-analysis/references/battlecard-template.md new file mode 100644 index 0000000000..66407a53c3 --- /dev/null +++ b/.cursor/skills/competitor-analysis/references/battlecard-template.md @@ -0,0 +1,256 @@ +# Competitive Battlecard Template + +A fill-in-the-blank template for creating competitive battlecards that equip sales, marketing, and content teams with actionable intelligence. Maintain one battlecard per major competitor and review quarterly. + +## Overview + +A competitive battlecard is a concise reference document that summarizes a competitor's strengths, weaknesses, positioning, and how to compete against them. Battlecards are living documents that should be updated as competitors evolve. + +**Audience:** Sales teams, content strategists, marketing leadership +**Update frequency:** Quarterly review minimum; update immediately on major competitor changes +**Length target:** 2-3 pages per competitor (scannable, not exhaustive) + +--- + +## Battlecard Template + +### Header + +``` +COMPETITIVE BATTLECARD: [Competitor Name] +Last Updated: [Date] +Updated By: [Name/Team] +Confidence Level: [High/Medium/Low] — based on data recency and source quality +``` + +--- + +### Section 1: Competitor Overview + +| Field | Details | +|-------|---------| +| **Company Name** | [Name] | +| **Website** | [URL] | +| **Founded** | [Year] | +| **Headquarters** | [Location] | +| **Company Size** | [Employees] | +| **Funding/Revenue** | [Known funding rounds or estimated revenue] | +| **Target Customer** | [Primary audience: SMB, mid-market, enterprise, etc.] | +| **Pricing Model** | [Freemium, subscription, usage-based, custom, etc.] | +| **Pricing Range** | [Entry price → Enterprise price] | + +**One-Sentence Summary:** +> [Competitor] is a [category] that helps [target audience] to [primary benefit] by [mechanism]. + +--- + +### Section 2: Their Pitch + +**Tagline/Slogan:** +> [Their exact tagline from website] + +**Top 3 Claimed Differentiators:** +1. [Differentiator 1 — their claim, not your assessment] +2. [Differentiator 2] +3. [Differentiator 3] + +**Positioning Statement (Reverse-Engineered):** +> For [their target audience], [product] is the [category] that [key benefit] because [reason to believe]. + +**Key Messages They Repeat:** +- [Message 1 — found in blog, ads, sales decks] +- [Message 2] +- [Message 3] + +--- + +### Section 3: Strengths (Be Honest) + +Credibility depends on honestly assessing where competitors are genuinely strong. Sugarcoating weaknesses or ignoring strengths reduces trust in the battlecard. + +| Strength | Evidence | Impact on Deals | +|----------|---------|----------------| +| [Strength 1] | [Where you observed this — reviews, demos, customer feedback] | [How this affects your competitive win rate] | +| [Strength 2] | [Evidence] | [Impact] | +| [Strength 3] | [Evidence] | [Impact] | + +--- + +### Section 4: Weaknesses + +| Weakness | Evidence | How to Exploit | +|----------|---------|---------------| +| [Weakness 1] | [Sources: G2 reviews, customer complaints, technical limitations] | [Talking point or demo moment that highlights this gap] | +| [Weakness 2] | [Evidence] | [How to exploit] | +| [Weakness 3] | [Evidence] | [How to exploit] | + +**Common Complaints (from review sites):** +- "[Exact quote from G2/Capterra/TrustRadius]" — [Source, Date] +- "[Exact quote]" — [Source, Date] +- "[Exact quote]" — [Source, Date] + +--- + +### Section 5: Your Differentiators + +For each differentiator, provide the claim AND the proof. Unsupported claims erode credibility. + +| Differentiator | Your Advantage | Proof Point | How to Demo/Show | +|---------------|---------------|------------|-----------------| +| [Differentiator 1] | [What you do better] | [Data, testimonial, or demo evidence] | [Specific demo step or slide] | +| [Differentiator 2] | [What you do better] | [Proof] | [How to show] | +| [Differentiator 3] | [What you do better] | [Proof] | [How to show] | + +--- + +### Section 6: Feature Comparison + +| Feature/Capability | You | [Competitor] | Notes | +|-------------------|-----|-------------|-------| +| [Feature 1] | [Yes/No/Partial + detail] | [Yes/No/Partial + detail] | [Context] | +| [Feature 2] | [Yes/No/Partial] | [Yes/No/Partial] | [Context] | +| [Feature 3] | [Yes/No/Partial] | [Yes/No/Partial] | [Context] | +| [Feature 4] | [Yes/No/Partial] | [Yes/No/Partial] | [Context] | +| [Feature 5] | [Yes/No/Partial] | [Yes/No/Partial] | [Context] | +| [Integration A] | [Yes/No] | [Yes/No] | [Context] | +| [Integration B] | [Yes/No] | [Yes/No] | [Context] | + +--- + +### Section 7: Pricing Comparison + +| Tier | You | [Competitor] | Advantage | +|------|-----|-------------|-----------| +| Entry/Free | [Price + what's included] | [Price + what's included] | [Who wins at this tier and why] | +| Mid-tier | [Price + what's included] | [Price + what's included] | [Who wins] | +| Enterprise | [Price + what's included] | [Price + what's included] | [Who wins] | + +**Hidden Costs to Highlight:** +- [Competitor charges extra for X, which you include] +- [Competitor requires Y add-on for common use case] +- [Competitor's pricing scales poorly because Z] + +--- + +### Section 8: Objection Handling + +| When They Say... | You Respond With... | Supporting Evidence | +|-----------------|--------------------|--------------------| +| "[Competitor] has more features" | "[Your response — focus on outcomes, not feature count]" | [Case study, data point, or demo] | +| "[Competitor] is cheaper" | "[Your response — focus on total value, ROI, or hidden costs]" | [TCO comparison, customer quote] | +| "[Competitor] is more established" | "[Your response — focus on innovation, agility, or support quality]" | [Growth metrics, customer satisfaction data] | +| "We're already using [Competitor]" | "[Your response — focus on switching ease, quick wins, or pain points]" | [Migration case study, time-to-value data] | +| "[Competitor] integrates with [tool]" | "[Your response — confirm your integration or alternative]" | [Integration docs, workaround, or roadmap] | + +--- + +### Section 9: Landmine Questions + +Questions to ask prospects early in the sales process that highlight your advantages and surface competitor weaknesses. Use these in discovery calls. + +| Landmine Question | What It Exposes | Your Advantage | +|------------------|----------------|---------------| +| "How important is [capability you have, they don't] to your workflow?" | Creates need for your differentiator | [Your capability] | +| "Have you experienced [common pain point with competitor]?" | Surfaces known competitor weakness | [Your solution to that pain] | +| "What's your timeline for seeing ROI from this tool?" | Highlights time-to-value differences | [Your faster time-to-value] | +| "How does your team currently handle [use case you excel at]?" | Opens discussion where you shine | [Your approach to this use case] | + +--- + +### Section 10: Win/Loss Analysis + +| Theme | Win Reasons (Why We Won) | Loss Reasons (Why We Lost) | +|-------|------------------------|---------------------------| +| Product | [What product features drove the win] | [What product gaps caused the loss] | +| Pricing | [Price advantage or value perception] | [Price disadvantage or perceived poor value] | +| Relationship | [Sales process, support quality] | [Better existing relationship with competitor] | +| Brand | [Brand trust, market perception] | [Competitor brand stronger in this segment] | + +**Recent Win Story:** +> [Brief narrative: who was the customer, what were they comparing, why did they choose you] + +**Recent Loss Story:** +> [Brief narrative: who was the customer, what were they comparing, why did they choose competitor] + +--- + +### Section 11: SEO/Content Intelligence + +| Dimension | [Competitor] | Your Position | +|-----------|-------------|--------------| +| Domain Authority/Rating | [Score] | [Score] | +| Organic traffic (est.) | [Monthly visits] | [Monthly visits] | +| Keywords in top 10 | [Count] | [Count] | +| Top-performing content | [URL + topic] | [Your equivalent or gap] | +| Content publishing cadence | [Posts/month] | [Posts/month] | +| Backlink count | [Count] | [Count] | +| AI citation frequency | [High/Medium/Low] | [High/Medium/Low] | + +**Content Strategy Observations:** +- [What content themes drive their traffic] +- [What formats they use effectively] +- [Where their content is weak or outdated] + +--- + +## Battlecard Maintenance Guidelines + +### Update Triggers + +Update the battlecard immediately when any of these occur: + +| Trigger | What to Update | +|---------|---------------| +| Competitor launches new feature | Feature comparison, differentiators, landmine questions | +| Competitor changes pricing | Pricing comparison, objection handling | +| Competitor raises funding / IPO | Overview section, positioning | +| Major review trends change | Weaknesses, objection handling, win/loss | +| You launch competing feature | Differentiators, feature comparison | +| Significant win or loss against them | Win/loss analysis, objection handling | +| Competitor publishes major content | SEO/content intelligence | + +### Quarterly Review Checklist + +- [ ] Verify all pricing information is current +- [ ] Check for new features launched by competitor +- [ ] Review latest G2/Capterra/TrustRadius reviews for new themes +- [ ] Update win/loss analysis with recent deals +- [ ] Refresh SEO/content metrics +- [ ] Confirm differentiators are still accurate +- [ ] Test all landmine questions with sales team for relevance +- [ ] Archive outdated information (don't delete -- move to "Historical" section) + +### Data Sources for Battlecard Updates + +| Source | What to Gather | Update Frequency | +|--------|---------------|-----------------| +| Competitor website | Pricing, features, messaging, positioning | Monthly | +| G2/Capterra reviews | Strengths, weaknesses, customer sentiment | Quarterly | +| LinkedIn/social media | Team changes, company news, content strategy | Monthly | +| Industry press/blogs | Funding, partnerships, market perception | As published | +| Sales team feedback | Win/loss themes, objection patterns | Monthly | +| SEO tools | Traffic, rankings, backlinks, content changes | Monthly | +| AI system queries | AI citation patterns, brand mentions | Quarterly | +| Customer feedback | Competitive switching reasons | Quarterly | + +--- + +## Example: Populated Battlecard Header + +``` +COMPETITIVE BATTLECARD: SEMrush +Last Updated: 2026-02-01 +Updated By: Content Strategy Team +Confidence Level: High + +One-Sentence Summary: +SEMrush is an all-in-one SEO and digital marketing platform that helps marketing +professionals manage SEO, PPC, content, and social media campaigns from a single dashboard. + +Tagline: "Online Marketing Can Be Easy" + +Positioning Statement: +For digital marketing professionals and agencies, SEMrush is the all-in-one marketing +toolkit that provides competitive intelligence and workflow automation because it combines +55+ tools across SEO, PPC, content, and social in one platform. +``` diff --git a/.cursor/skills/competitor-analysis/references/example-report.md b/.cursor/skills/competitor-analysis/references/example-report.md new file mode 100644 index 0000000000..4ef522d40a --- /dev/null +++ b/.cursor/skills/competitor-analysis/references/example-report.md @@ -0,0 +1,75 @@ +# Competitor Analysis — Example Report + +This is a complete example output showing the expected format for competitor analysis deliverables. + +## Prompt + +**User**: "Analyze why HubSpot ranks so well for marketing-related keywords" + +## Example Output + +```markdown +# Competitive Analysis: HubSpot + +## SEO Strategy Overview + +HubSpot dominates marketing keywords through a combination of: +1. **Massive content moat** - 10,000+ blog posts +2. **Free tools as linkbait** - Website grader, email signature generator +3. **Educational brand** - Academy, certifications, courses +4. **Topic cluster model** - Pioneered the pillar/cluster approach + +## What Makes Them Successful + +### Content Strategy + +**Publishing Volume**: 50-100 posts/month +**Average Word Count**: 2,500+ words +**Content Types**: +- In-depth guides (35%) +- How-to tutorials (25%) +- Templates & examples (20%) +- Data/research (10%) +- Tools & calculators (10%) + +**Top Performing Content Pattern**: +1. Ultimate guides on broad topics +2. Free templates with email gate +3. Statistics roundup posts +4. Definition posts ("What is [term]") + +### GEO Success Factors + +HubSpot appears in AI responses frequently because: + +1. **Clear definitions** at the start of every post + > "Inbound marketing is a business methodology that attracts customers by creating valuable content and experiences tailored to them." + +2. **Quotable statistics** + > "Companies that blog get 55% more website visitors" + +3. **Comprehensive coverage** - AI trusts their authority + +### Linkable Assets + +| Asset | Backlinks | Why It Works | +|-------|-----------|--------------| +| Website Grader | 45,000+ | Free, instant value | +| Marketing Statistics | 12,000+ | Quotable reference | +| Blog Ideas Generator | 8,500+ | Solves real problem | + +## Weaknesses to Exploit + +1. **Content becoming dated** - Many posts 3+ years old +2. **Generic advice** - Lacks industry-specific depth +3. **Enterprise focus** - Underserves solopreneurs +4. **Slow innovation** - Same formats for years + +## Your Opportunities + +1. Create more specific, niche content they can't cover +2. Target long-tail keywords they ignore +3. Build interactive tools in emerging areas +4. Add original research they don't have +5. Focus on GEO-optimized definitions in your niche +``` diff --git a/.cursor/skills/competitor-analysis/references/positioning-frameworks.md b/.cursor/skills/competitor-analysis/references/positioning-frameworks.md new file mode 100644 index 0000000000..42cba0ac50 --- /dev/null +++ b/.cursor/skills/competitor-analysis/references/positioning-frameworks.md @@ -0,0 +1,320 @@ +# Positioning Frameworks + +Comprehensive frameworks for analyzing competitor positioning, developing your own positioning strategy, and identifying differentiation opportunities. Use these frameworks to map competitive landscapes, craft positioning statements, and find messaging vulnerabilities. + +## Overview + +Positioning is how your product or brand occupies a distinct place in the mind of your target audience relative to competitors. Strong positioning makes your value proposition clear, your differentiation obvious, and your target audience feel understood. + +This reference covers: +1. Positioning statement templates +2. 2x2 positioning map methodology +3. Category strategy options +4. Differentiation playbooks +5. Messaging vulnerability analysis + +--- + +## 1. Positioning Statement Templates + +### Classic Positioning Statement + +The foundational template used across industries: + +``` +For [target audience], +[product/brand] is the [category] +that [key benefit / point of difference] +because [reason to believe / proof point]. +``` + +**Example (SEO tool):** +> For growth-stage SaaS marketers, Clearscope is the content optimization platform that ensures every article ranks on page one because it uses real-time SERP data and NLP to grade content against ranking competitors. + +### Extended Positioning Statement + +Adds competitive context and emotional resonance: + +``` +For [target audience] who [situation/need], +[product/brand] is the [category] +that [functional benefit] +unlike [competitive alternative] +because [unique capability / proof]. +This matters because [emotional benefit / outcome]. +``` + +**Example:** +> For content teams who struggle to consistently rank new articles, MarketMuse is the content planning platform that identifies exactly which topics to cover, unlike manual keyword research tools, because it uses AI-driven topic models trained on ranking content. This matters because teams stop guessing and start publishing with confidence. + +### Before/After/Bridge Positioning + +Focuses on transformation: + +``` +BEFORE: [Current painful state for target audience] +AFTER: [Desired improved state] +BRIDGE: [Your product] makes this possible by [mechanism]. +``` + +### Problem-Agitation-Solution Positioning + +Focuses on pain point amplification: + +``` +PROBLEM: [What the target audience struggles with] +AGITATION: [Why this problem is worse than they think — consequences, hidden costs] +SOLUTION: [How your product solves it differently than alternatives] +``` + +--- + +## 2. Positioning Map (2x2 Matrix) Methodology + +### How to Build a Positioning Map + +A positioning map plots competitors on two key dimensions to visualize the competitive landscape and identify open positioning space. + +#### Step 1: Choose Your Axes + +Select two dimensions that matter most to your target audience. The axes should be: +- **Meaningful to buyers** (not internal metrics) +- **Differentiating** (competitors should spread across the map) +- **Independent** (the two dimensions should not be correlated) + +#### Common Axis Pairs for SEO/Marketing + +| Axis Pair | X-Axis | Y-Axis | Best For | +|-----------|--------|--------|---------| +| Value Positioning | Price (Low → High) | Capability (Basic → Advanced) | Understanding market tiers | +| UX Positioning | Ease of Use (Complex → Simple) | Power (Limited → Comprehensive) | Evaluating UX/capability tradeoffs | +| Audience Positioning | SMB Focus ← → Enterprise Focus | Point Solution ← → Full Platform | Identifying segment gaps | +| Innovation Positioning | Established/Stable ← → Innovative/Cutting-Edge | Niche ← → Broad | Timing market positioning | +| Content Positioning | Data-Driven ← → Opinion-Driven | Beginner ← → Expert | Content strategy differentiation | + +#### Step 2: Plot Competitors + +Place each competitor (including yourself) on the map based on objective assessment. + +``` + HIGH CAPABILITY + │ + Enterprise │ All-in-One + Suites │ Platforms + │ + LOW ───────────────┼─────────────── HIGH + PRICE │ PRICE + │ + Free/Basic │ Premium + Tools │ Specialists + │ + LOW CAPABILITY +``` + +#### Step 3: Identify White Space + +Look for quadrants or areas where: +- **No competitor exists** (market opportunity) +- **Only weak competitors exist** (displacement opportunity) +- **Crowded clusters exist** (differentiation challenge -- avoid or reframe) + +#### Step 4: Choose Your Position + +Select a position that: +- Aligns with your actual product capabilities +- Serves an underserved audience segment +- Is defensible (hard for competitors to copy) +- Connects to a clear value narrative + +### Positioning Map Anti-Patterns + +| Anti-Pattern | Description | Fix | +|-------------|------------|-----| +| Aspiration mapping | Plotting yourself where you want to be, not where you are | Be honest about current position; create a roadmap to desired position | +| Vanity axes | Choosing dimensions that make you look good but don't matter to buyers | Validate axes with customer research | +| Missing competitors | Only plotting direct competitors, missing substitutes | Include indirect competitors and alternative solutions | +| Static mapping | Building the map once and never updating | Refresh quarterly as market shifts | + +--- + +## 3. Category Strategy Options + +How you define your category determines your competitive set and positioning flexibility. + +### Strategy 1: Win the Existing Category + +**When to use:** You have a genuinely superior product in an established category. +**Approach:** Accept the existing category definition and compete on being the best. +**Messaging:** "The best [category] for [audience]" +**Risk:** Head-to-head competition with established players. + +**Example:** "The best SEO tool for content marketers" (competing within "SEO tools") + +### Strategy 2: Create a New Sub-Category + +**When to use:** You have a genuine differentiator that deserves its own label. +**Approach:** Segment the existing category and own the new segment. +**Messaging:** "The first [new sub-category]" +**Risk:** Market may not recognize the sub-category. + +**Example:** "Content optimization platform" (sub-category of "SEO tools" focused on content) + +### Strategy 3: Create a New Category + +**When to use:** Your product genuinely doesn't fit existing categories. +**Approach:** Define a new category and position yourself as the category creator. +**Messaging:** "Introducing [new category]: [definition]" +**Risk:** High education cost; market may not adopt the category. + +**Example:** "GEO optimization platform" (new category combining SEO + AI visibility) + +### Strategy 4: Reframe the Category + +**When to use:** The existing category frames competition in a way that disadvantages you. +**Approach:** Change how buyers think about the problem, shifting the evaluation criteria. +**Messaging:** "Stop thinking about [old category]. Start thinking about [new frame]." +**Risk:** Confusing prospects who use existing category to search/evaluate. + +**Example:** "Not another SEO tool -- a revenue intelligence platform" (reframing from SEO to revenue) + +### Category Strategy Decision Matrix + +| Factor | Win Existing | New Sub-Category | New Category | Reframe | +|--------|-------------|-----------------|-------------|---------| +| Product differentiation | Low-Medium | Medium-High | Very High | Medium | +| Market education cost | Low | Medium | Very High | High | +| Competitive intensity | High | Medium | Low (initially) | Medium | +| SEO/search difficulty | High (competitive terms) | Medium (new terms) | Low (no competition) | Medium | +| Sales cycle impact | Short (known category) | Medium | Long (education needed) | Medium-Long | + +--- + +## 4. Differentiation Playbooks + +### Types of Differentiation + +Not all differentiation is equal. Stronger forms are harder to copy. + +| Type | Strength | Durability | Examples | +|------|---------|-----------|---------| +| **Feature** | Low | Low (easily copied) | "We have feature X" | +| **Integration** | Medium | Medium | "We connect to Y ecosystem" | +| **Experience** | Medium-High | Medium-High | "Our UX is designed for Z workflow" | +| **Data/Network** | High | High | "Our data from N users makes results better" | +| **Methodology** | High | High | "We invented the X framework" | +| **Mission/Values** | High | Very High | "We're the only [category] focused on [mission]" | + +### Differentiation Audit Template + +For each competitor, assess your differentiation strength: + +| Dimension | Your Approach | Competitor's Approach | Differentiation Strength | Defensibility | +|-----------|-------------|---------------------|------------------------|--------------| +| Core technology | [Your tech] | [Their tech] | [Weak/Medium/Strong] | [Easy/Hard to copy] | +| Target audience | [Your audience] | [Their audience] | [Weak/Medium/Strong] | [Easy/Hard to copy] | +| Pricing model | [Your model] | [Their model] | [Weak/Medium/Strong] | [Easy/Hard to copy] | +| Content/education | [Your approach] | [Their approach] | [Weak/Medium/Strong] | [Easy/Hard to copy] | +| Customer support | [Your approach] | [Their approach] | [Weak/Medium/Strong] | [Easy/Hard to copy] | +| Data advantage | [Your data] | [Their data] | [Weak/Medium/Strong] | [Easy/Hard to copy] | +| Brand/community | [Your brand] | [Their brand] | [Weak/Medium/Strong] | [Easy/Hard to copy] | + +### The "Only We" Test + +For each claimed differentiator, apply this test: + +> "Only [your company] [does X] because [unique reason]." + +If a competitor could truthfully make the same claim, it is not a true differentiator. Revise until the statement is uniquely yours. + +**Strong example:** +> "Only Clearscope grades content against real-time SERP competitor analysis because we built a proprietary NLP model trained on ranking content patterns." + +**Weak example:** +> "Only we offer great customer support." (Every company claims this.) + +### Differentiation Messaging Formula + +``` +We're the only [category] that [unique capability] +which means [customer benefit] +so you can [desired outcome]. +``` + +--- + +## 5. Messaging Vulnerability Analysis + +### Identifying Competitor Messaging Vulnerabilities + +A messaging vulnerability is a gap between what a competitor claims and what they actually deliver, or a message that sounds good but collapses under scrutiny. + +#### Vulnerability Types + +| Vulnerability Type | Description | How to Exploit | +|-------------------|------------|---------------| +| **Promise-Reality Gap** | They claim X but reviews say Y | Reference review data; offer proof of your delivery | +| **Specificity Gap** | They use vague claims ("best-in-class") without proof | Be specific with your claims; use data | +| **Audience Mismatch** | Their messaging targets one audience but product serves another | Speak directly to the underserved audience | +| **Legacy Positioning** | Their positioning is outdated; product has evolved | Position against their OLD story, which is stuck in market perception | +| **Feature Overload** | They list features without connecting to outcomes | Lead with outcomes, not features | +| **Price Sensitivity** | They avoid discussing price, suggesting it's high or confusing | Be transparent about pricing; create TCO comparisons | + +#### Competitor Messaging Audit Worksheet + +For each competitor, analyze their messaging across touchpoints: + +| Touchpoint | Their Message | Vulnerability? | Your Counter-Message | +|-----------|-------------|---------------|---------------------| +| Homepage hero | [Their headline] | [Yes/No — what's weak?] | [Your alternative angle] | +| Pricing page | [How they frame pricing] | [Yes/No — what's hidden?] | [Your transparency approach] | +| Blog/content | [Content themes and tone] | [Yes/No — what's missing?] | [Your content differentiation] | +| Social media | [Social messaging and engagement] | [Yes/No — what's performative?] | [Your authentic approach] | +| Sales emails/outreach | [Known sales messaging] | [Yes/No — what's pushy/generic?] | [Your consultative approach] | +| Customer reviews | [What customers actually say] | [Yes/No — gap from their claims?] | [Highlight alignment of your claims + reviews] | + +### Counter-Positioning Strategies + +| Strategy | When to Use | Messaging Pattern | +|----------|-----------|-----------------| +| **Contrast** | When competitor is dominant but has clear weakness | "Unlike [competitor], we [your strength]" | +| **Flanking** | When competitor ignores a valuable segment | "Built specifically for [underserved segment]" | +| **Reframing** | When competitor's strength is actually a weakness in disguise | "[Competitor's feature] sounds good until you realize [negative consequence]" | +| **Elevation** | When competing on features is a losing game | "Stop comparing features. What matters is [higher-level outcome]" | +| **Specificity** | When competitor uses vague claims | "[Specific metric] for [specific audience] in [specific timeframe]" | + +### Messaging Strength Test + +Rate each competitor's messaging on these dimensions (1-5): + +| Dimension | What to Evaluate | Score | +|-----------|-----------------|-------| +| Clarity | Can you understand their value prop in 5 seconds? | [1-5] | +| Specificity | Do they use concrete numbers and claims? | [1-5] | +| Differentiation | Is their message distinct from competitors? | [1-5] | +| Proof | Do they back claims with evidence? | [1-5] | +| Audience fit | Does the message resonate with their target? | [1-5] | +| Consistency | Is messaging consistent across all touchpoints? | [1-5] | +| Emotional resonance | Does it connect with real pain or aspiration? | [1-5] | + +**Total Score** = Sum / 35 + +| Score Range | Assessment | +|------------|-----------| +| 0.8-1.0 | Very strong messaging -- find a niche angle to compete | +| 0.6-0.79 | Solid messaging -- exploit specific gaps | +| 0.4-0.59 | Average messaging -- multiple attack vectors available | +| Below 0.4 | Weak messaging -- opportunity to dominate with clarity | + +--- + +## Applying These Frameworks Together + +### Recommended Workflow + +1. **Start with Positioning Maps** to understand the landscape visually +2. **Analyze Category Strategy** to decide how to frame your competitive set +3. **Build Positioning Statement** using the templates +4. **Audit Differentiation** to ensure claims are defensible +5. **Identify Messaging Vulnerabilities** to find attack angles +6. **Create Battlecards** (see [battlecard-template.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/competitor-analysis/references/battlecard-template.md)) incorporating all insights +7. **Review quarterly** as the competitive landscape shifts diff --git a/.cursor/skills/content-gap-analysis/SKILL.md b/.cursor/skills/content-gap-analysis/SKILL.md new file mode 100644 index 0000000000..0e4e0e7883 --- /dev/null +++ b/.cursor/skills/content-gap-analysis/SKILL.md @@ -0,0 +1,287 @@ +--- +name: content-gap-analysis +description: 'Find content gaps: topics and keywords competitors cover that you don''t, with editorial calendar. 内容缺口/选题规划' +version: "6.0.0" +license: Apache-2.0 +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when finding content gaps between two domains, discovering missing topics, or identifying coverage holes versus competitors." +argument-hint: " " +metadata: + author: aaron-he-zhu + version: "6.0.0" + geo-relevance: "medium" + tags: + - seo + - geo + - content-gaps + - topic-analysis + - content-strategy + - editorial-calendar + - competitive-gap + - content-opportunities + - 内容缺口 + - コンテンツギャップ + - 콘텐츠갭 + - brechas-contenido + triggers: + # EN-formal + - "find content gaps" + - "content opportunities" + - "topic analysis" + - "content strategy gaps" + - "editorial calendar" + - "untapped topics" + # EN-casual + - "what am I missing" + - "topics to cover" + - "what do competitors write about" + - "what should I cover next" + - "topics I haven't written about" + - "they cover this but I don't" + # EN-question + - "what topics am I missing" + - "what content should I create" + # ZH-pro + - "内容缺口分析" + - "选题规划" + - "内容机会" + - "竞品话题" + # ZH-casual + - "缺什么内容" + - "竞品写了什么" + - "还应该写什么" + # JA + - "コンテンツギャップ" + - "コンテンツ機会" + # KO + - "콘텐츠 갭 분석" + - "콘텐츠 기회" + # ES + - "brechas de contenido" + - "oportunidades de contenido" + # PT + - "lacunas de conteúdo" + # Misspellings + - "content gab analysis" +--- + +# Content Gap Analysis + + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This research skill follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + + +Identifies content opportunities by analyzing gaps between a site's content and competitors'. Surfaces missing topics, untapped keywords, and content formats worth creating. + +**System role**: Research layer skill. It turns market signals into reusable strategic inputs for the rest of the library. + +## When This Must Trigger + +Use this when the conversation involves any of these situations — even if the user does not use SEO terminology: + +Use this whenever the task needs reusable market intelligence that should influence strategy, not just an ad hoc answer. + +- Planning content strategy and editorial calendar +- Finding quick-win content opportunities +- Understanding where competitors outperform you +- Identifying underserved topics in your niche +- Expanding into adjacent topic areas +- Prioritizing content creation efforts +- Finding GEO opportunities competitors miss + +## What This Skill Does + +1. **Keyword Gap Analysis**: Finds keywords competitors rank for that you don't +2. **Topic Coverage Mapping**: Identifies topic areas needing more content +3. **Content Format Gaps**: Reveals missing content types (videos, tools, guides) +4. **Audience Need Mapping**: Matches gaps to audience journey stages +5. **GEO Opportunity Detection**: Finds AI-answerable topics you're missing +6. **Priority Scoring**: Ranks gaps by impact and effort +7. **Content Calendar Creation**: Plans gap-filling content schedule + +## Quick Start + +Start with one of these prompts. Finish with a short handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Basic Gap Analysis + +``` +Find content gaps between my site [URL] and [competitor URLs] +``` + +``` +What content am I missing compared to my top 3 competitors? +``` + +### Topic-Specific Analysis + +``` +Find content gaps in [topic area] compared to industry leaders +``` + +``` +What [content type] do competitors have that I don't? +``` + +### Audience-Focused + +``` +What content gaps exist for [audience segment] in my niche? +``` + +## Skill Contract + +**Expected output**: a prioritized research brief, evidence-backed findings, and a short handoff summary ready for `memory/research/`. + +- **Reads**: user goals, target market inputs, available tool data, and prior strategy from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available. +- **Writes**: a user-facing research deliverable plus a reusable summary that can be stored under `memory/research/`. +- **Promotes**: durable keyword priorities, competitor facts, entity candidates, and strategic decisions to `CLAUDE.md`, `memory/decisions.md`, and `memory/research/`; hand canonical entity work to `entity-optimizer`. +- **Next handoff**: use the `Next Best Skill` below when the findings are ready to drive action. + +## Data Sources + +> **Note:** All integrations are optional. This skill works without any API keys — users provide data manually when no tools are connected. + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +**With ~~SEO tool + ~~search console + ~~analytics + ~~AI monitor connected:** +Automatically pull your site's content inventory from ~~search console and ~~analytics (indexed pages, traffic per page, keywords ranking), competitor content data from ~~SEO tool (ranking keywords, top pages, backlink counts), and AI citation patterns from ~~AI monitor. Keyword overlap analysis and gap identification can be automated. + +**With manual data only:** +Ask the user to provide: +1. Your site URL and content inventory (list of published content with topics) +2. Competitor URLs (3-5 sites) +3. Your current traffic and keyword performance (if available) +4. Known content strengths and weaknesses +5. Industry context and business goals + +Proceed with the full analysis using provided data. Note in the output which metrics are from automated collection vs. user-provided data. + +## Instructions + +When a user requests content gap analysis: + +1. **Define Analysis Scope** + + Clarify parameters: + + ```markdown + ### Analysis Parameters + + **Your Site**: [URL] + **Competitors to Analyze**: [URLs or "identify for me"] + **Topic Focus**: [specific area or "all"] + **Content Types**: [blogs, guides, tools, videos, or "all"] + **Audience**: [target audience] + **Business Goals**: [traffic, leads, authority, etc.] + ``` + +2. **Audit Your Existing Content** + + Document total indexed pages, content by type and topic cluster, top performing content, and content strengths/weaknesses. + +3. **Analyze Competitor Content** + + For each competitor: document content volume, monthly traffic, content distribution by type, topic coverage vs. yours, and unique content they have. + +4. **Identify Keyword Gaps** + + Find keywords competitors rank for that you do not. Categorize into High Priority (high volume, achievable difficulty), Quick Wins (lower volume, low difficulty), and Long-term (high volume, high difficulty). Include keyword overlap analysis. + +5. **Map Topic Gaps** + + Create a topic coverage comparison matrix across all competitors. For each missing topic cluster, document business relevance, competitor coverage, opportunity size, sub-topics, and recommended pillar/cluster approach. + +6. **Identify Content Format Gaps** + + Compare format distribution (guides, tutorials, comparisons, case studies, tools, templates, video, infographics, research) against competitors and industry averages. For each gap, assess effort and expected impact. + +7. **Analyze GEO/AI Gaps** + + Identify topics where competitors get AI citations but you do not. Document missing Q&A content, definition/explanation content, and comparison content. Score each by traditional SEO value and GEO value. + +8. **Map to Audience Journey** + + Compare funnel stage coverage (Awareness, Consideration, Decision, Retention) against competitor averages. Detail specific gaps at each stage. + +9. **Prioritize and Create Action Plan** + + Produce a final report with: Executive Summary, Prioritized Gap List (Tier 1 Quick Wins, Tier 2 Strategic Builds, Tier 3 Long-term), Content Calendar, and Success Metrics. + + > **Reference**: See [references/analysis-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/content-gap-analysis/references/analysis-templates.md) for detailed templates for each step. + +## Validation Checkpoints + +### Input Validation +- [ ] Your content inventory is complete or representative sample provided +- [ ] Competitor URLs identified (minimum 2-3 competitors) +- [ ] Analysis scope defined (specific topics or comprehensive) +- [ ] Business goals and priorities clarified + +### Output Validation +- [ ] Every recommendation cites specific data points (not generic advice) +- [ ] Gap analysis compares like-to-like content (topic clusters to topic clusters) +- [ ] Priority scoring based on measurable criteria (volume, difficulty, business fit) +- [ ] Content calendar maps gaps to realistic timeframes +- [ ] Source of each data point clearly stated (~~SEO tool data, ~~analytics data, ~~AI monitor data, user-provided, or estimated) + +## Example + +> **Reference**: See [references/example-report.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/content-gap-analysis/references/example-report.md) for a complete example analyzing SaaS marketing blog gaps vs. HubSpot and Drift. + +## Advanced Analysis + +### Competitive Cluster Comparison + +``` +Compare our topic cluster coverage for [topic] vs top 5 competitors +``` + +### Temporal Gap Analysis + +``` +What content have competitors published in the last 6 months that we haven't covered? +``` + +### Intent-Based Gaps + +``` +Find gaps in our [commercial/informational] intent content +``` + +## Tips for Success + +1. **Focus on actionable gaps** - Not all gaps are worth filling +2. **Consider your resources** - Prioritize based on ability to execute +3. **Quality over quantity** - Better to fill 5 gaps well than 20 poorly +4. **Track what works** - Measure gap-filling success +5. **Update regularly** - Gaps change as competitors publish +6. **Include GEO opportunities** - Don't just optimize for traditional search + + + +### Save Results + +After delivering findings to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to `memory/research/content-gap-analysis/YYYY-MM-DD-.md` containing: +- One-line headline finding +- Top 3-5 actionable items +- Open loops or blockers +- Source data references + +If any findings should influence ongoing strategy, recommend promoting key conclusions to `memory/hot-cache.md`. + +## Reference Materials + +- [Analysis Templates](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/content-gap-analysis/references/analysis-templates.md) — Detailed templates for each analysis step (inventory, competitor content, keyword gaps, topic gaps, format gaps, GEO gaps, journey, prioritized report) +- [Gap Analysis Frameworks](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/content-gap-analysis/references/gap-analysis-frameworks.md) — Content audit matrices, funnel mapping, and gap prioritization scoring methodologies +- [Example Report](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/content-gap-analysis/references/example-report.md) — Complete example analyzing SaaS marketing blog gaps vs. HubSpot and Drift + +## Next Best Skill + +- **Primary**: [seo-content-writer](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/seo-content-writer/SKILL.md) — turn missing topics into a draft or content roadmap. diff --git a/.cursor/skills/content-gap-analysis/references/analysis-templates.md b/.cursor/skills/content-gap-analysis/references/analysis-templates.md new file mode 100644 index 0000000000..487919a67e --- /dev/null +++ b/.cursor/skills/content-gap-analysis/references/analysis-templates.md @@ -0,0 +1,335 @@ +# Content Gap Analysis — Analysis Templates + +Templates for each step of the content gap analysis workflow. Use these to structure your output. + +## Content Inventory Template + +```markdown +## Your Content Inventory + +**Total Indexed Pages**: [X] +**Content by Type**: +- Blog posts: [X] +- Landing pages: [X] +- Resource pages: [X] +- Tools/calculators: [X] +- Case studies: [X] + +**Content by Topic Cluster**: + +| Topic | Articles | Keywords Ranking | Traffic | +|-------|----------|------------------|---------| +| [topic 1] | [X] | [X] | [X] | +| [topic 2] | [X] | [X] | [X] | +| [topic 3] | [X] | [X] | [X] | + +**Top Performing Content**: +1. [Title] - [traffic] visits - [keywords] keywords +2. [Title] - [traffic] visits - [keywords] keywords +3. [Title] - [traffic] visits - [keywords] keywords + +**Content Strengths**: +- [Strength 1] +- [Strength 2] + +**Content Weaknesses**: +- [Weakness 1] +- [Weakness 2] +``` + +## Competitor Content Analysis Template + +```markdown +## Competitor Content Analysis + +### Competitor 1: [Name/URL] + +**Content Volume**: [X] pages +**Monthly Traffic**: [X] visits + +**Content Distribution**: +| Type | Count | Est. Traffic | +|------|-------|--------------| +| Blog posts | [X] | [X] | +| Guides | [X] | [X] | +| Tools | [X] | [X] | +| Videos | [X] | [X] | + +**Topic Coverage**: +| Topic | Articles | Your Coverage | +|-------|----------|---------------| +| [topic] | [X] | [X or "None"] | + +**Unique Content They Have**: +1. [Content piece] - [traffic] - [why it works] +2. [Content piece] - [traffic] - [why it works] + +[Repeat for each competitor] +``` + +## Keyword Gap Analysis Template + +```markdown +## Keyword Gap Analysis + +### Keywords Competitors Rank For (You Don't) + +**High Priority Gaps** (High volume, achievable difficulty) + +| Keyword | Volume | Difficulty | Competitor | Their Position | +|---------|--------|------------|------------|----------------| +| [kw 1] | [vol] | [diff] | [comp] | [pos] | +| [kw 2] | [vol] | [diff] | [comp] | [pos] | +| [kw 3] | [vol] | [diff] | [comp] | [pos] | + +**Quick Win Gaps** (Lower volume, low difficulty) + +| Keyword | Volume | Difficulty | Competitor | Their Position | +|---------|--------|------------|------------|----------------| +| [kw 1] | [vol] | [diff] | [comp] | [pos] | + +**Long-term Gaps** (High volume, high difficulty) + +| Keyword | Volume | Difficulty | Competitor | Their Position | +|---------|--------|------------|------------|----------------| +| [kw 1] | [vol] | [diff] | [comp] | [pos] | + +### Keyword Overlap Analysis + +``` +Venn Diagram Representation: + + You Competitor 1 + ○ ○ + / \ / \ + / \ / \ + / A \ B / C \ + / \ / \ + ○─────────○─────○─────────○ + Competitor 2 + +A: Keywords only you rank for: [X] +B: Overlap with Comp 1: [X] +C: Keywords all competitors share: [X] +Gap: Keywords they all have, you don't: [X] +``` + +**Unique Keywords (Your Advantage)**: +| Keyword | Your Position | Volume | +|---------|---------------|--------| +| [kw] | [pos] | [vol] | +``` + +## Topic Gap Analysis Template + +```markdown +## Topic Gap Analysis + +### Topic Coverage Comparison + +| Topic Area | You | Comp 1 | Comp 2 | Comp 3 | Gap? | +|------------|-----|--------|--------|--------|------| +| [Topic 1] | ✅ [X] | ✅ [X] | ✅ [X] | ✅ [X] | No | +| [Topic 2] | ❌ 0 | ✅ [X] | ✅ [X] | ✅ [X] | **Yes** | +| [Topic 3] | ✅ [X] | ✅ [X] | ❌ 0 | ✅ [X] | Partial | +| [Topic 4] | ❌ 0 | ✅ [X] | ✅ [X] | ❌ 0 | **Yes** | + +### Missing Topic Clusters + +#### Gap 1: [Topic Area] + +**Why it matters**: [Business relevance] +**Competitor coverage**: [Who covers it and how] +**Opportunity size**: [Traffic/keyword potential] + +**Sub-topics to cover**: +1. [Sub-topic] - [X] search volume +2. [Sub-topic] - [X] search volume +3. [Sub-topic] - [X] search volume + +**Recommended approach**: +- Pillar content: [topic] +- Cluster articles: [list] +- Supporting content: [list] +``` + +## Content Format Gap Template + +```markdown +## Content Format Gap Analysis + +### Format Distribution Comparison + +| Format | You | Comp 1 | Comp 2 | Industry Avg | +|--------|-----|--------|--------|--------------| +| Long-form guides | [X] | [X] | [X] | [X] | +| Tutorials | [X] | [X] | [X] | [X] | +| Comparison posts | [X] | [X] | [X] | [X] | +| Case studies | [X] | [X] | [X] | [X] | +| Tools/calculators | [X] | [X] | [X] | [X] | +| Templates | [X] | [X] | [X] | [X] | +| Video content | [X] | [X] | [X] | [X] | +| Infographics | [X] | [X] | [X] | [X] | +| Original research | [X] | [X] | [X] | [X] | + +### Format Gaps to Fill + +#### Gap: [Format Type] + +**Current state**: You have [X], competitors average [Y] +**Best examples**: [Competitor content examples] +**Opportunity**: [Description] +**Effort to create**: [Low/Medium/High] +**Expected impact**: [Low/Medium/High] + +**Recommended first project**: +[Specific content idea] +``` + +## GEO Content Gap Template + +```markdown +## GEO Content Gap Analysis + +### AI-Answerable Topics Assessment + +**Topics where competitors get AI citations (you don't)**: + +| Topic | AI Cites | Why They're Cited | Your Gap | +|-------|----------|-------------------|----------| +| [topic 1] | [Comp] | [reason] | [what you need] | +| [topic 2] | [Comp] | [reason] | [what you need] | + +### GEO-Optimized Content Gaps + +**Missing Q&A Content**: +| Question | Search Volume | Currently Answered By | +|----------|---------------|----------------------| +| [question] | [vol] | [competitor] | + +**Missing Definition/Explanation Content**: +| Term | Search Volume | Best Current Source | +|------|---------------|---------------------| +| [term] | [vol] | [source] | + +**Missing Comparison Content**: +| Comparison | Search Volume | Best Current Source | +|------------|---------------|---------------------| +| [A vs B] | [vol] | [source] | + +### GEO Opportunity Score + +| Topic | Traditional SEO Value | GEO Value | Combined Priority | +|-------|----------------------|-----------|-------------------| +| [topic] | [score] | [score] | [priority] | +``` + +## Audience Journey Gap Template + +```markdown +## Audience Journey Gap Analysis + +### Funnel Stage Coverage + +| Stage | Your Content | Competitor Avg | Gap | +|-------|--------------|----------------|-----| +| Awareness | [X] articles | [X] articles | [+/-X] | +| Consideration | [X] articles | [X] articles | [+/-X] | +| Decision | [X] articles | [X] articles | [+/-X] | +| Retention | [X] articles | [X] articles | [+/-X] | + +### Journey Gap Details + +#### Awareness Stage Gaps +- Missing: [topics/content] +- Opportunity: [description] + +#### Consideration Stage Gaps +- Missing: [topics/content] +- Opportunity: [description] + +#### Decision Stage Gaps +- Missing: [topics/content] +- Opportunity: [description] +``` + +## Prioritized Report Template + +```markdown +# Content Gap Analysis Report + +## Executive Summary + +**Analysis Date**: [Date] +**Sites Analyzed**: [Your site] vs [Competitors] + +**Key Findings**: +1. [Most significant gap] +2. [Second significant gap] +3. [Third significant gap] + +**Total Opportunity**: +- Keywords gaps identified: [X] +- Estimated traffic opportunity: [X]/month +- Quick wins available: [X] pieces + +--- + +## Prioritized Gap List + +### Tier 1: Quick Wins (Do Now) + +| Content to Create | Target Keyword | Volume | Difficulty | Impact | +|-------------------|----------------|--------|------------|--------| +| [Title idea] | [keyword] | [vol] | [diff] | High | +| [Title idea] | [keyword] | [vol] | [diff] | High | + +**Why prioritize**: Low effort, immediate ranking potential + +### Tier 2: Strategic Builds (This Quarter) + +| Content to Create | Target Keyword | Volume | Difficulty | Impact | +|-------------------|----------------|--------|------------|--------| +| [Title idea] | [keyword] | [vol] | [diff] | High | + +**Why prioritize**: High value, requires more resources + +### Tier 3: Long-term Investments (This Year) + +| Content to Create | Target Keyword | Volume | Difficulty | Impact | +|-------------------|----------------|--------|------------|--------| +| [Title idea] | [keyword] | [vol] | [diff] | High | + +**Why prioritize**: Builds authority, competitive differentiator + +--- + +## Content Calendar Recommendation + +### Month 1 +| Week | Content | Type | Target Keyword | Status | +|------|---------|------|----------------|--------| +| 1 | [Title] | [Type] | [Keyword] | Planned | +| 2 | [Title] | [Type] | [Keyword] | Planned | +| 3 | [Title] | [Type] | [Keyword] | Planned | +| 4 | [Title] | [Type] | [Keyword] | Planned | + +### Month 2 +[Continue...] + +### Month 3 +[Continue...] + +--- + +## Success Metrics + +Track these to measure gap-filling success: + +| Metric | Current | 3-Month Target | 6-Month Target | +|--------|---------|----------------|----------------| +| Keyword coverage | [X] | [X] | [X] | +| Topic clusters complete | [X] | [X] | [X] | +| Traffic from new content | [X] | [X] | [X] | +| AI citations | [X] | [X] | [X] | +``` diff --git a/.cursor/skills/content-gap-analysis/references/example-report.md b/.cursor/skills/content-gap-analysis/references/example-report.md new file mode 100644 index 0000000000..0a4438dce6 --- /dev/null +++ b/.cursor/skills/content-gap-analysis/references/example-report.md @@ -0,0 +1,47 @@ +# Content Gap Analysis — Example Report + +This is a complete example output showing the expected format for content gap analysis deliverables. + +## Prompt + +**User**: "Find content gaps for my SaaS marketing blog compared to HubSpot and Drift" + +## Example Output + +```markdown +# Content Gap Analysis: SaaS Marketing Blog + +## Executive Summary + +Compared to HubSpot and Drift, your blog has significant gaps in: +1. **Interactive tools** - They have 15+, you have 0 +2. **Comparison content** - Missing "[Your Tool] vs [Competitor]" pages +3. **GEO-optimized definitions** - No glossary or term definitions + +Total opportunity: ~25,000 monthly visits from 45 keyword gaps + +## Top Keyword Gaps + +### Quick Wins (Difficulty <40) + +| Keyword | Volume | Difficulty | Who Ranks | +|---------|--------|------------|-----------| +| saas marketing metrics | 1,200 | 32 | HubSpot #3 | +| b2b email sequences | 890 | 28 | Drift #5 | +| saas onboarding emails | 720 | 25 | Neither! | +| marketing qualified lead definition | 1,800 | 35 | HubSpot #1 | + +### Content Format Gaps + +**You're missing**: +- [ ] Interactive ROI calculator (HubSpot gets 15k visits/mo from theirs) +- [ ] Email template library (Drift's gets 8k visits/mo) +- [ ] Marketing glossary (HubSpot's definition pages rank for 500+ keywords) + +## Recommended Content Calendar + +**Week 1**: "SaaS Marketing Metrics: Complete Guide" (Quick win) +**Week 2**: "What is a Marketing Qualified Lead?" (GEO opportunity) +**Week 3**: "B2B Email Sequence Templates" (Format gap) +**Week 4**: "[Your Tool] vs HubSpot" (Comparison gap) +``` diff --git a/.cursor/skills/content-gap-analysis/references/gap-analysis-frameworks.md b/.cursor/skills/content-gap-analysis/references/gap-analysis-frameworks.md new file mode 100644 index 0000000000..a9ebc5a462 --- /dev/null +++ b/.cursor/skills/content-gap-analysis/references/gap-analysis-frameworks.md @@ -0,0 +1,318 @@ +# Gap Analysis Frameworks + +Complete frameworks for systematic keyword gap identification, content format gap analysis, funnel stage gap mapping, opportunity scoring models, and content calendar integration. Use these frameworks to transform gap analysis from ad-hoc observation into repeatable process. + +## Overview + +Content gap analysis answers three questions: +1. **What are competitors covering that you are not?** (Keyword and topic gaps) +2. **What content formats are expected but missing?** (Format gaps) +3. **Where in the buyer journey does your content fail?** (Funnel gaps) + +This reference provides structured methodologies for each question, plus scoring and prioritization systems. + +--- + +## 1. Systematic Keyword Gap Methodology + +### Step-by-Step Process + +#### Step 1: Define Your Keyword Universe + +Before finding gaps, establish what you already rank for: + +| Data Source | What It Provides | How to Collect | +|------------|-----------------|---------------| +| ~~search console | Keywords driving impressions and clicks to your site | Export Performance report (last 6 months) | +| ~~SEO tool | Full keyword profile including positions 1-100 | Domain keyword export | +| Content audit | Topics covered by existing content | Manual or automated URL crawl + categorization | + +**Output:** A master list of all keywords you currently rank for (positions 1-100). + +#### Step 2: Build Competitor Keyword Profiles + +For each competitor (3-5 recommended): + +| Competitor | Total Keywords | Keywords in Top 10 | Keywords in Top 3 | Estimated Traffic | +|-----------|---------------|-------------------|-------------------|------------------| +| [Competitor A] | [Count] | [Count] | [Count] | [Monthly est.] | +| [Competitor B] | [Count] | [Count] | [Count] | [Monthly est.] | +| [Competitor C] | [Count] | [Count] | [Count] | [Monthly est.] | +| **You** | [Count] | [Count] | [Count] | [Monthly est.] | + +#### Step 3: Calculate Keyword Overlap + +Identify four keyword segments: + +``` +┌──────────────────────────────────────────────────────────┐ +│ │ +│ A: Keywords ONLY you rank for (your unique advantage) │ +│ │ +│ B: Keywords you AND competitors share (competitive) │ +│ │ +│ C: Keywords ONLY competitors rank for (your gaps) │ +│ │ +│ D: Keywords NO ONE ranks for (market opportunity) │ +│ │ +└──────────────────────────────────────────────────────────┘ +``` + +| Segment | Size | Strategic Meaning | Action | +|---------|------|------------------|--------| +| A (Only you) | [Count] | Your content moat | Protect and strengthen | +| B (Shared) | [Count] | Competitive battleground | Improve rankings | +| C (Only them) | [Count] | Your content gaps | Prioritize and create | +| D (No one) | [Count] | Untapped market | Evaluate and pioneer | + +#### Step 4: Filter and Categorize Gaps (Segment C) + +Not all gaps are worth filling. Filter by: + +| Filter | Threshold | Purpose | +|--------|-----------|---------| +| Minimum search volume | >100/month (adjust for niche) | Ensure traffic potential | +| Maximum keyword difficulty | 70% bounce rate | Missing "next step" content or CTAs | +| Interest → Consideration | Pages per session | <2 pages/session | Missing comparison/evaluation content | +| Consideration → Intent | Demo/trial requests | Low conversion from comparison pages | Missing trust content (case studies, reviews) | +| Intent → Purchase | Cart/signup abandonment | High abandonment rate | Missing objection-handling content | +| Purchase → Retention | Churn rate | High early churn | Missing onboarding/help content | + +--- + +## 4. Opportunity Scoring Model + +### Multi-Factor Gap Scoring + +Score each identified gap on 5 factors (1-5 scale each): + +| Factor | Weight | Score 1 (Low) | Score 3 (Medium) | Score 5 (High) | +|--------|--------|--------------|-----------------|----------------| +| **Search Demand** | 25% | <100 monthly searches | 500-2,000 searches | >5,000 searches | +| **Competitive Density** | 20% | All competitors cover it well | 1-2 competitors cover it | No competitor covers it | +| **Business Relevance** | 25% | Tangential to your offering | Related to your offering | Core to your offering | +| **Creation Effort** | 15% | Requires new capabilities | Moderate effort | Quick to create | +| **Conversion Potential** | 15% | Pure awareness (top-funnel) | Consideration stage | Decision/transactional stage | + +**Gap Priority Score** = Σ (Factor Weight x Score) + +### Priority Tiers + +| Tier | Score Range | Timeline | Action | +|------|-----------|----------|--------| +| **P0 -- Fill Immediately** | 4.0-5.0 | This sprint / this week | High demand + low competition + high relevance | +| **P1 -- Fill This Quarter** | 3.0-3.9 | Next 1-3 months | Good demand + some competition + relevant | +| **P2 -- Plan for Future** | 2.0-2.9 | Next 3-6 months | Moderate opportunity, requires more resources | +| **P3 -- Monitor** | 1.0-1.9 | Track quarterly | Low priority but may become relevant | + +### Quick-Win Identification + +A "quick win" gap scores high on Demand + Relevance and low on Effort + Competition: + +``` +Quick Win Score = (Search Demand + Business Relevance) - (Creation Effort + Competitive Density) + Higher is better +``` + +| Quick Win Score | Assessment | +|----------------|-----------| +| 4+ | Strong quick win -- create this content first | +| 2-3 | Moderate quick win -- include in next content sprint | +| 0-1 | Not a quick win -- may still be strategically important | +| Negative | Avoid -- high effort/competition relative to demand | + +--- + +## 5. Content Calendar Integration + +### Gap-to-Calendar Workflow + +#### Step 1: Group Gaps by Topic Cluster + +Group related gaps into clusters rather than addressing them individually: + +| Cluster | Related Gaps | Combined Volume | Pillar Needed? | Cluster Pages Needed | +|---------|-------------|----------------|---------------|---------------------| +| [Cluster A] | Gap 1, Gap 3, Gap 7 | [Sum of volumes] | [Yes/No] | [Count] | +| [Cluster B] | Gap 2, Gap 5 | [Sum of volumes] | [Yes/No] | [Count] | +| [Cluster C] | Gap 4, Gap 6, Gap 8, Gap 9 | [Sum of volumes] | [Yes/No] | [Count] | + +#### Step 2: Sequence by Priority and Dependencies + +| Order | Content Piece | Gap(s) Addressed | Priority | Dependencies | Target Publish | +|-------|-------------|-----------------|---------|-------------|---------------| +| 1 | [Pillar page for Cluster A] | Gap 1, 3, 7 (overview) | P0 | None | Week 1 | +| 2 | [Quick-win article] | Gap 2 | P0 | None | Week 2 | +| 3 | [Cluster A subtopic 1] | Gap 3 (deep dive) | P0 | Pillar published | Week 3 | +| 4 | [Cluster A subtopic 2] | Gap 7 (deep dive) | P1 | Pillar published | Week 4 | +| 5 | [Comparison page] | Gap 5 | P1 | None | Week 5 | + +#### Step 3: Assign Resources and Track + +| Content Piece | Writer | Reviewer | Target Date | Status | Gap Closed? | +|-------------|--------|---------|------------|--------|------------| +| [Title] | [Name] | [Name] | [Date] | [Draft/Review/Published] | [Yes/No/Partial] | + +### Calendar Cadence by Team Size + +| Team Size | Monthly Output | Gap Fill Rate | Full Gap Close Timeline | +|-----------|---------------|--------------|----------------------| +| Solo | 4-6 pieces/month | 3-4 gaps/month | 6-12 months for 30 gaps | +| Small (2-3) | 8-15 pieces/month | 6-10 gaps/month | 3-6 months for 30 gaps | +| Medium (4-6) | 15-25 pieces/month | 10-20 gaps/month | 2-3 months for 30 gaps | +| Large (7+) | 25+ pieces/month | 20+ gaps/month | 1-2 months for 30 gaps | + +### Post-Publication Gap Validation + +After publishing gap-filling content, validate that the gap is actually closed: + +| Checkpoint | Timeframe | What to Check | Success Criteria | +|-----------|-----------|--------------|-----------------| +| Indexing | 1-2 weeks | Is the page indexed? | Appears in Google index | +| Initial ranking | 2-4 weeks | Is it ranking for target keyword? | Appears in top 100 | +| Competitive ranking | 2-3 months | Has it reached competitive positions? | Top 20 or improving trend | +| Traffic impact | 3-6 months | Is it driving meaningful traffic? | Meeting traffic projections | +| Gap closure | 6 months | Has the gap been effectively closed? | Ranking comparable to competitors | + +--- + +## Framework Selection Guide + +| Situation | Primary Framework | Secondary Framework | +|-----------|------------------|-------------------| +| "We need more traffic" | Keyword Gap Methodology | Content Calendar Integration | +| "Competitors outrank us everywhere" | Keyword Gap + Format Gap | Opportunity Scoring | +| "Our conversion rate is low" | Funnel Stage Gap | Format Gap (decision-stage formats) | +| "We don't know what to write next" | All three gap types | Opportunity Scoring + Calendar | +| "We have limited resources" | Opportunity Scoring (quick wins) | Keyword Gap (filtered by difficulty) | +| "We're entering a new market" | Keyword Gap (comprehensive) | Format Gap + Funnel Gap | diff --git a/.cursor/skills/content-quality-auditor/SKILL.md b/.cursor/skills/content-quality-auditor/SKILL.md new file mode 100644 index 0000000000..c3679a8e27 --- /dev/null +++ b/.cursor/skills/content-quality-auditor/SKILL.md @@ -0,0 +1,403 @@ +--- +name: content-quality-auditor +description: 'Publish-readiness gate: 80-item CORE-EEAT audit with weighted scoring, veto checks, and fix plan. 内容质量/EEAT评分' +version: "6.0.0" +license: Apache-2.0 +allowed-tools: WebFetch +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when auditing content quality before publishing. Runs CORE-EEAT 80-item scoring with veto checks. Also when the user asks for E-E-A-T analysis or publish readiness." +argument-hint: " [keyword]" +metadata: + author: aaron-he-zhu + version: "6.0.0" + geo-relevance: "high" + tags: + - seo + - geo + - e-e-a-t + - core-eeat + - content-quality + - content-scoring + - helpful-content + - publish-readiness + - 内容质量 + - コンテンツ品質 + - 콘텐츠품질 + - auditoria-eeat + triggers: + # EN-formal + - "audit content quality" + - "EEAT score" + - "CORE-EEAT audit" + - "content quality check" + - "content assessment" + - "quality score" + # EN-casual + - "is this ready to publish" + - "grade my article" + - "check before publishing" + - "how good is my content" + - "is my content good enough to rank" + - "rate my content quality" + # EN-question + - "is my content ready to publish" + - "how do I improve content quality" + # ZH-pro + - "内容质量审计" + - "EEAT评分" + - "内容评估" + # ZH-casual + - "文章能发吗" + - "内容打几分" + - "文章写得怎么样" + # JA + - "コンテンツ品質監査" + - "E-E-A-T評価" + # KO + - "콘텐츠 품질 감사" + - "EEAT 점수" + # ES + - "auditoría de calidad de contenido" + - "puntuación EEAT" + # PT + - "auditoria de qualidade" + # Misspellings + - "EEAT scroe" +--- + +# Content Quality Auditor + +> Based on [CORE-EEAT Content Benchmark](https://github.com/aaron-he-zhu/core-eeat-content-benchmark). Full benchmark reference: [references/core-eeat-benchmark.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/core-eeat-benchmark.md) + + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This cross-cutting skill is part of the protocol layer and follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + + +This skill evaluates content quality across 80 standardized criteria organized in 8 dimensions. It produces a comprehensive audit report with per-item scoring, dimension and system scores, weighted totals by content type, and a prioritized action plan. + +**System role**: Publish Readiness Gate. It decides whether content is ready to ship, what blocks publication, and what should be promoted into durable project memory. + +## When This Must Trigger + +Use this when content needs a quality check before publishing — even if the user doesn't use audit terminology: + +- User asks "is this ready to publish" or "how good is this" +- User just finished writing with seo-content-writer or content-refresher +- **PostToolUse hook auto-triggers**: after content is written or substantially edited, the hook recommends this audit. When hook-triggered, skip setup questions — audit the content that was just produced. +- Auditing content quality before publishing +- Evaluating existing content for improvement opportunities +- Benchmarking content against CORE-EEAT standards +- Comparing content quality against competitors +- Assessing both GEO readiness (AI citation potential) and SEO strength (source credibility) +- Running periodic content quality checks as part of a content maintenance program +- After writing or optimizing content with seo-content-writer or geo-content-optimizer + +## What This Skill Does + +1. **Full 80-Item Audit**: Scores every CORE-EEAT check item as Pass/Partial/Fail +2. **Dimension Scoring**: Calculates scores for all 8 dimensions (0-100 each) +3. **System Scoring**: Computes GEO Score (CORE) and SEO Score (EEAT) +4. **Weighted Totals**: Applies content-type-specific weights for final score +5. **Veto Detection**: Flags critical trust violations (T04, C01, R10) +6. **Priority Ranking**: Identifies Top 5 improvements sorted by impact +7. **Action Plan**: Generates specific, actionable improvement steps + +## Quick Start + +Start with one of these prompts. Finish with a publish verdict and a handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Audit Content + +``` +Audit this content against CORE-EEAT: [content text or URL] +``` + +``` +Run a content quality audit on [URL] as a [content type] +``` + +### Audit with Content Type + +``` +CORE-EEAT audit for this product review: [content] +``` + +``` +Score this how-to guide against the 80-item benchmark: [content] +``` + +### Comparative Audit + +``` +Audit my content vs competitor: [your content] vs [competitor content] +``` + +## Skill Contract + +**Gate verdict**: **SHIP** (no veto items, dimension scores above threshold) / **FIX** (issues found but no veto) / **BLOCK** (veto item T04, C01, or R10 failed). Always state the verdict prominently at the top of the report. + +**Expected output**: a CORE-EEAT audit report, a publish-readiness verdict, and a short handoff summary ready for `memory/audits/content/`. + +- **Reads**: the target content, content type, supporting evidence, and any prior decisions from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available. +- **Writes**: a user-facing audit report plus a reusable summary that can be stored under `memory/audits/content/`. +- **Promotes**: veto items and publish blockers to `memory/hot-cache.md` (auto-saved, no user confirmation needed). Top improvement priorities to `memory/open-loops.md`. +- **Next handoff**: use the `Next Best Skill` below once the verdict is clear. + +## Data Sources + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +**With ~~web crawler + ~~SEO tool connected:** +Automatically fetch page content, extract HTML structure, check schema markup, verify internal/external links, and pull competitor content for comparison. + +**With manual data only:** +Ask the user to provide: +1. Content text, URL, or file path +2. Content type (if not auto-detectable): Product Review, How-to Guide, Comparison, Landing Page, Blog Post, FAQ Page, Alternative, Best-of, or Testimonial +3. Optional: competitor content for benchmarking + +Proceed with the full 80-item audit using provided data. Note in the output which items could not be fully evaluated due to missing access (e.g., backlink data, schema markup, site-level signals). + +## Decision Gates + +When stopping to ask, always: (1) state the specific value and threshold, (2) offer numbered options with outcomes. + +**Stop and ask the user when:** +- Content is under minimum word count for its type (blog/guide: 300 words; product/landing page: 150 words; FAQ: fewer than 3 entries with 50+ words each) — state the actual count and offer: (1) expand to minimum, (2) continue audit with Insufficient Data flags, (3) cancel +- Content type cannot be auto-detected — state what you detected and ask to confirm before proceeding +- Content is primarily media (video/image) with minimal text — ask whether to audit transcript, alt text, or skip +- More than 50% of a dimension's items are N/A — name the dimension and ask: (1) provide supplementary data, (2) mark entire dimension as Insufficient Data +- Any veto item triggers — flag it immediately with the item ID and ask: (1) stop for immediate fix, (2) continue full audit and flag in report + +**Continue silently (never stop for):** +- Individual Partial scores within a dimension +- Missing SEO tool data (mark items as N/A and continue) +- Low overall score (the report is the deliverable, not a judgment call) +- User not specifying content type (auto-detect and state your assumption) + +## Instructions + +When a user requests a content quality audit: + +### Step 1: Preparation + +```markdown +### Audit Setup + +**Content**: [title or URL] +**Content Type**: [auto-detected or user-specified] +**Dimension Weights**: [loaded from content-type weight table] + +#### Veto Check (Emergency Brake) + +| Veto Item | Status | Action | +|-----------|--------|--------| +| T04: Disclosure Statements | ✅ Pass / ⚠️ VETO | [If VETO: "Add disclosure banner at page top immediately"] | +| C01: Intent Alignment | ✅ Pass / ⚠️ VETO | [If VETO: "Rewrite title and first paragraph"] | +| R10: Content Consistency | ✅ Pass / ⚠️ VETO | [If VETO: "Verify all data before publishing"] | +``` + +If any veto item triggers, flag it prominently at the top of the report and recommend immediate action before continuing the full audit. + +### Step 2: CORE Audit (40 items) + +Evaluate each item against the criteria in [references/core-eeat-benchmark.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/core-eeat-benchmark.md). + +Score each item: +- **Pass** = 10 points (fully meets criteria) +- **Partial** = 5 points (partially meets criteria) +- **Fail** = 0 points (does not meet criteria) + +```markdown +### C — Contextual Clarity + +| ID | Check Item | Score | Notes | +|----|-----------|-------|-------| +| C01 | Intent Alignment | Pass/Partial/Fail | [specific observation] | +| C02 | Direct Answer | Pass/Partial/Fail | [specific observation] | +| ... | ... | ... | ... | +| C10 | Semantic Closure | Pass/Partial/Fail | [specific observation] | + +**C Score**: [X]/100 +``` + +Repeat the same table format for **O** (Organization), **R** (Referenceability), and **E** (Exclusivity), scoring all 10 items per dimension. + +### Step 3: EEAT Audit (40 items) + +```markdown +### Exp — Experience + +| ID | Check Item | Score | Notes | +|----|-----------|-------|-------| +| Exp01 | First-Person Narrative | Pass/Partial/Fail | [specific observation] | +| ... | ... | ... | ... | + +**Exp Score**: [X]/100 +``` + +Repeat the same table format for **Ept** (Expertise), **A** (Authority), and **T** (Trust), scoring all 10 items per dimension. + +See [references/item-reference.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/content-quality-auditor/references/item-reference.md) for the complete 80-item ID lookup table and site-level item handling notes. + +### Step 4: Scoring & Report + +Calculate scores and generate the final report: + +```markdown +## CORE-EEAT Audit Report + +### Overview + +- **Content**: [title] +- **Content Type**: [type] +- **Audit Date**: [date] +- **Total Score**: [score]/100 ([rating]) +- **GEO Score**: [score]/100 | **SEO Score**: [score]/100 +- **Veto Status**: ✅ No triggers / ⚠️ [item] triggered + +### Dimension Scores + +| Dimension | Score | Rating | Weight | Weighted | +|-----------|-------|--------|--------|----------| +| C — Contextual Clarity | [X]/100 | [rating] | [X]% | [X] | +| O — Organization | [X]/100 | [rating] | [X]% | [X] | +| R — Referenceability | [X]/100 | [rating] | [X]% | [X] | +| E — Exclusivity | [X]/100 | [rating] | [X]% | [X] | +| Exp — Experience | [X]/100 | [rating] | [X]% | [X] | +| Ept — Expertise | [X]/100 | [rating] | [X]% | [X] | +| A — Authority | [X]/100 | [rating] | [X]% | [X] | +| T — Trust | [X]/100 | [rating] | [X]% | [X] | +| **Weighted Total** | | | | **[X]/100** | + +**Score Calculation**: +- GEO Score = (C + O + R + E) / 4 +- SEO Score = (Exp + Ept + A + T) / 4 +- Weighted Score = Σ (dimension_score × content_type_weight) + +**Rating Scale**: 90-100 Excellent | 75-89 Good | 60-74 Medium | 40-59 Low | 0-39 Poor + +### N/A Item Handling + +When an item cannot be evaluated (e.g., A01 Backlink Profile requires site-level data not available): + +1. Mark the item as "N/A" with reason +2. Exclude N/A items from the dimension score calculation +3. Dimension Score = (sum of scored items) / (number of scored items x 10) x 100 +4. If more than 50% of a dimension's items are N/A, flag the dimension as "Insufficient Data" and exclude it from the weighted total +5. Recalculate weighted total using only dimensions with sufficient data, re-normalizing weights to sum to 100% + +**Example**: Authority dimension with 8 N/A items and 2 scored items (A05=8, A07=5): +- Dimension score = (8+5) / (2 x 10) x 100 = 65 +- But 8/10 items are N/A (>50%), so flag as "Insufficient Data -- Authority" +- Exclude A dimension from weighted total; redistribute its weight proportionally to remaining dimensions + +### Per-Item Scores + +#### CORE — Content Body (40 Items) + +| ID | Check Item | Score | Notes | +|----|-----------|-------|-------| +| C01 | Intent Alignment | [Pass/Partial/Fail] | [observation] | +| C02 | Direct Answer | [Pass/Partial/Fail] | [observation] | +| ... | ... | ... | ... | + +#### EEAT — Source Credibility (40 Items) + +| ID | Check Item | Score | Notes | +|----|-----------|-------|-------| +| Exp01 | First-Person Narrative | [Pass/Partial/Fail] | [observation] | +| ... | ... | ... | ... | + +### Top 5 Priority Improvements + +Sorted by: weight × points lost (highest impact first) + +1. **[ID] [Name]** — [specific modification suggestion] + - Current: [Fail/Partial] | Potential gain: [X] weighted points + - Action: [concrete step] + +2. **[ID] [Name]** — [specific modification suggestion] + - Current: [Fail/Partial] | Potential gain: [X] weighted points + - Action: [concrete step] + +3–5. [Same format] + +### Action Plan + +#### Quick Wins (< 30 minutes each) +- [ ] [Action 1] +- [ ] [Action 2] + +#### Medium Effort (1-2 hours) +- [ ] [Action 3] +- [ ] [Action 4] + +#### Strategic (Requires planning) +- [ ] [Action 5] +- [ ] [Action 6] + +### Recommended Next Steps + +- For full content rewrite: use `seo-content-writer` with CORE-EEAT constraints +- For GEO optimization: use `geo-content-optimizer` targeting failed GEO-First items +- For content refresh: use `content-refresher` with weak dimensions as focus +- For technical fixes: run `/seo:check-technical` for site-level issues +``` + +### Save Results + +After delivering findings to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to the appropriate `memory/` path using filename `YYYY-MM-DD-.md` containing: +- One-line verdict or headline finding +- Top 3-5 actionable items +- Open loops or blockers +- Source data references + +If any veto-level issue was found (CORE-EEAT T04, C01, R10 or CITE T03, T05, T09), also append a one-liner to `memory/hot-cache.md` without asking. + +## Validation Checkpoints + +### Input Validation +- [ ] Content source identified (text, URL, or file path) +- [ ] Content type confirmed (auto-detected or user-specified) +- [ ] Content is substantial enough for meaningful audit (≥300 words) +- [ ] If comparative audit, competitor content also provided + +### Output Validation +- [ ] All 80 items scored (or marked N/A with reason) +- [ ] All 8 dimension scores calculated correctly +- [ ] Weighted total matches content-type weight configuration +- [ ] Veto items checked and flagged if triggered +- [ ] Top 5 improvements sorted by weighted impact, not arbitrary +- [ ] Every recommendation is specific and actionable (not generic advice) +- [ ] Action plan includes concrete steps with effort estimates + +## Example + +See [references/item-reference.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/content-quality-auditor/references/item-reference.md) for a complete scored example showing the C dimension with all 10 items, priority improvements, and weighted scoring. + +## Tips for Success + +1. **Start with veto items** — T04, C01, R10 are deal-breakers regardless of total score + > These veto items are consistent with the CORE-EEAT benchmark (Section 3), which defines them as items that can override the overall score. +2. **Focus on high-weight dimensions** — Different content types prioritize different dimensions +3. **GEO-First items matter most for AI visibility** — Prioritize items tagged GEO 🎯 if AI citation is the goal +4. **Some EEAT items need site-level data** — Don't penalize content for things only observable at the site level (backlinks, brand recognition) +5. **Use the weighted score, not just the raw average** — A product review with strong Exclusivity matters more than strong Authority +6. **Re-audit after improvements** — Run again to verify score improvements and catch regressions +7. **Pair with CITE for domain-level context** — A high content score on a low-authority domain signals a different priority than the reverse; run [domain-authority-auditor](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/domain-authority-auditor/SKILL.md) for the full 120-item picture + +## Reference Materials + +- [CORE-EEAT Content Benchmark](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/core-eeat-benchmark.md) — Full 80-item benchmark with dimension definitions, scoring criteria, and GEO-First item markers +- [references/item-reference.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/content-quality-auditor/references/item-reference.md) — All 80 item IDs in a compact lookup table + site-level item handling notes + scored example report + +## Next Best Skill + +- **Primary**: [content-refresher](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/content-refresher/SKILL.md) — turn failed checks into a concrete rewrite plan. diff --git a/.cursor/skills/content-quality-auditor/references/item-reference.md b/.cursor/skills/content-quality-auditor/references/item-reference.md new file mode 100644 index 0000000000..49bf51045a --- /dev/null +++ b/.cursor/skills/content-quality-auditor/references/item-reference.md @@ -0,0 +1,99 @@ +# CORE-EEAT Item Reference + +Quick reference for all 80 CORE-EEAT audit items. Full scoring criteria in [core-eeat-benchmark.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/core-eeat-benchmark.md). + +## Complete Item Reference + +| ID | Item | ID | Item | +|----|------|----|------| +| C01 | Intent Alignment | Exp01 | First-Person Narrative | +| C02 | Direct Answer | Exp02 | Sensory Details | +| C03 | Query Coverage | Exp03 | Process Documentation | +| C04 | Definition First | Exp04 | Tangible Proof | +| C05 | Topic Scope | Exp05 | Usage Duration | +| C06 | Audience Targeting | Exp06 | Problems Encountered | +| C07 | Semantic Coherence | Exp07 | Before/After Comparison | +| C08 | Use Case Mapping | Exp08 | Quantified Metrics | +| C09 | FAQ Coverage | Exp09 | Repeated Testing | +| C10 | Semantic Closure | Exp10 | Limitations Acknowledged | +| O01 | Heading Hierarchy | Ept01 | Author Identity | +| O02 | Summary Box | Ept02 | Credentials Display | +| O03 | Data Tables | Ept03 | Professional Vocabulary | +| O04 | List Formatting | Ept04 | Technical Depth | +| O05 | Schema Markup | Ept05 | Methodology Rigor | +| O06 | Section Chunking | Ept06 | Edge Case Awareness | +| O07 | Visual Hierarchy | Ept07 | Historical Context | +| O08 | Anchor Navigation | Ept08 | Reasoning Transparency | +| O09 | Information Density | Ept09 | Cross-domain Integration | +| O10 | Multimedia Structure | Ept10 | Editorial Process | +| R01 | Data Precision | A01 | Backlink Profile | +| R02 | Citation Density | A02 | Media Mentions | +| R03 | Source Hierarchy | A03 | Industry Awards | +| R04 | Evidence-Claim Mapping | A04 | Publishing Record | +| R05 | Methodology Transparency | A05 | Brand Recognition | +| R06 | Timestamp & Versioning | A06 | Social Proof | +| R07 | Entity Precision | A07 | Knowledge Graph Presence | +| R08 | Internal Link Graph | A08 | Entity Consistency | +| R09 | HTML Semantics | A09 | Partnership Signals | +| R10 | Content Consistency | A10 | Community Standing | +| E01 | Original Data | T01 | Legal Compliance | +| E02 | Novel Framework | T02 | Contact Transparency | +| E03 | Primary Research | T03 | Security Standards | +| E04 | Contrarian View | T04 | Disclosure Statements | +| E05 | Proprietary Visuals | T05 | Editorial Policy | +| E06 | Gap Filling | T06 | Correction & Update Policy | +| E07 | Practical Tools | T07 | Ad Experience | +| E08 | Depth Advantage | T08 | Risk Disclaimers | +| E09 | Synthesis Value | T09 | Review Authenticity | +| E10 | Forward Insights | T10 | Customer Support | + +**Note on site-level items**: Most Authority items (A01-A10) and several Trust items (T01-T03, T05, T07, T10) require site-level or organization-level data that may not be observable from a single page. When auditing a standalone page without site context, mark these as "N/A — requires site-level data" and exclude from the dimension average. + +## Example Audit Report + +**User**: "Audit this blog post against CORE-EEAT: [paste of 'Best Project Management Tools for Remote Teams 2025']" + +**Output** (partial — showing one dimension to demonstrate format): + +```markdown +## CORE-EEAT Audit Report + +### Overview + +- **Content**: "Best Project Management Tools for Remote Teams 2025" +- **Content Type**: Blog Post / Comparison +- **Audit Date**: 2025-06-15 +- **Veto Status**: No triggers + +### C -- Contextual Clarity (scored dimension example) + +| ID | Check Item | Score | Points | Notes | +|-----|--------------------|---------|--------|-------------------------------------------------------------| +| C01 | Intent Alignment | Pass | 10 | Matches "best X" comparison intent; title and body aligned | +| C02 | Direct Answer | Partial | 5 | Answer appears in first 300 words but no summary box | +| C03 | Query Coverage | Pass | 10 | Covers "project management tools", "remote team software", "best PM tools" | +| C04 | Definition First | Pass | 10 | Key terms ("PM tool", "async collaboration") defined on first use | +| C05 | Topic Scope | Partial | 5 | States what's covered but not what's excluded | +| C06 | Audience Targeting | Pass | 10 | Explicitly targets "remote team leads and managers" | +| C07 | Semantic Coherence | Pass | 10 | Logical flow: intro > criteria > tools > comparison > verdict | +| C08 | Use Case Mapping | Pass | 10 | Decision matrix for team size, budget, and features | +| C09 | FAQ Coverage | Fail | 0 | No FAQ section despite long-tail potential ("free PM tools for small teams") | +| C10 | Semantic Closure | Partial | 5 | Conclusion present but doesn't loop back to opening promise | + +**C Dimension Score**: 75/100 (Good) +**Blog Post weight for C**: 25% +**Weighted contribution**: 18.75 + +#### Priority Improvements from C Dimension + +1. **C09 FAQ Coverage** -- Add FAQ section with 3-5 long-tail questions + - Current: Fail (0) | Potential gain: 2.5 weighted points + - Action: Add FAQ with "Are there free PM tools for small remote teams?", "How to migrate between PM tools?", etc. + +2. **C02 Direct Answer** -- Add a summary box above the fold + - Current: Partial (5) | Potential gain: 1.25 weighted points + - Action: Insert a "Top 3 Picks" callout box in the first 150 words + +[... remaining 7 dimensions (O, R, E, Exp, Ept, A, T) follow the same per-item format ...] +[... then: Dimension Scores table, Top 5 Priority Improvements, Action Plan, Recommended Next Steps ...] +``` diff --git a/.cursor/skills/content-refresher/SKILL.md b/.cursor/skills/content-refresher/SKILL.md new file mode 100644 index 0000000000..5c1967a909 --- /dev/null +++ b/.cursor/skills/content-refresher/SKILL.md @@ -0,0 +1,396 @@ +--- +name: content-refresher +description: 'Refresh outdated posts with current stats, new sections, freshness signals to restore rankings. 内容更新/排名恢复' +version: "6.0.0" +license: Apache-2.0 +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when updating outdated content, refreshing old articles, improving declining pages, or adding new information to existing content." +argument-hint: "" +metadata: + author: aaron-he-zhu + version: "6.0.0" + geo-relevance: "medium" + tags: + - seo + - geo + - content-refresh + - content-update + - content-decay + - ranking-recovery + - evergreen-content + - content-lifecycle + - 内容更新 + - コンテンツ更新 + - 콘텐츠갱신 + - actualizar-contenido + triggers: + # EN-formal + - "update old content" + - "refresh content" + - "content is outdated" + - "improve declining rankings" + - "revive old blog posts" + - "content decay" + - "content refresh strategy" + # EN-casual + - "traffic is dropping" + - "ranking dropped" + - "this post is outdated" + - "traffic is declining on this page" + - "rankings dropped for this article" + - "my old content needs updating" + # EN-question + - "how to fix declining traffic" + - "why is my content losing rankings" + - "how often should I update content" + # EN-competitor + - "Clearscope content refresh" + - "MarketMuse content update" + # ZH-pro + - "内容更新" + - "内容刷新" + - "排名恢复" + - "内容衰减" + - "内容生命周期" + # ZH-casual + - "排名下降了" + - "文章过时了" + - "流量掉了" + - "老文章怎么办" + # JA + - "コンテンツ更新" + - "コンテンツリフレッシュ" + - "記事更新" + # KO + - "콘텐츠 갱신" + - "콘텐츠 업데이트" + - "순위 하락" + - "순위 하락 원인" + - "오래된 글 어떻게 해?" + # ES + - "actualizar contenido" + - "refrescar contenido antiguo" + # PT + - "atualizar conteúdo" + # Misspellings + - "content refesh" + - "content refreshh" +--- + +# Content Refresher + + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This optimization skill follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + + +This skill helps identify and revitalize outdated content to reclaim lost rankings and traffic. It analyzes content freshness, identifies update opportunities, and guides the refresh process for maximum SEO and GEO impact. + +**System role**: Optimization layer skill. It turns weak pages, structures, and technical issues into prioritized repair work. + +## When This Must Trigger + +Use this when the conversation involves any of these situations — even if the user does not use SEO terminology: + +Use this whenever the task needs a diagnosis or repair plan that should feed directly into remediation work, not just a one-time opinion. + +- Content has lost rankings or traffic over time +- Statistics and information are outdated +- Competitors have published better content +- Content needs updating for a new year +- Industry changes require content updates +- Adding new sections to existing content +- Converting old content for GEO optimization + +## What This Skill Does + +1. **Freshness Analysis**: Identifies outdated content needing updates +2. **Performance Tracking**: Finds content with declining traffic +3. **Gap Identification**: Spots missing information competitors have +4. **Update Prioritization**: Ranks content by refresh potential +5. **Refresh Recommendations**: Provides specific update guidance +6. **GEO Enhancement**: Updates content for AI citation potential +7. **Republishing Strategy**: Advises on date and promotion tactics + +## Quick Start + +Start with one of these prompts. Finish with a short handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Identify Content to Refresh + +``` +Find content on [domain] that needs refreshing +``` + +``` +Which of my blog posts have lost the most traffic? +``` + +### Refresh Specific Content + +``` +Refresh this article for [current year]: [URL/content] +``` + +``` +Update this content to outrank [competitor URL]: [your URL] +``` + +### Content Refresh Strategy + +``` +Create a content refresh strategy for [domain/topic] +``` + +## Skill Contract + +**Expected output**: a scored diagnosis, prioritized repair plan, and a short handoff summary ready for `memory/audits/`. + +- **Reads**: the current page or site state, symptoms, prior audits, and current priorities from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available. +- **Writes**: a user-facing audit or optimization plan plus a reusable summary that can be stored under `memory/audits/`. +- **Promotes**: blocking defects, repeated weaknesses, and fix priorities to `memory/open-loops.md` and `memory/decisions.md`. +- **Next handoff**: use the `Next Best Skill` below when the repair path is clear. + +## Data Sources + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +**With ~~analytics + ~~search console + ~~SEO tool connected:** +Claude can automatically pull historical traffic trends from ~~analytics, fetch impression and ranking data from ~~search console, retrieve keyword position history from ~~SEO tool, and identify content with declining performance. This enables data-driven refresh prioritization. + +**With manual data only:** +Ask the user to provide: +1. Traffic data or screenshots showing performance trends +2. Ranking screenshots or history for key pages +3. Content publish dates and last update dates +4. List of pages the user suspects need refreshing + +Proceed with the analysis using provided data. Note in the output which findings are from automated data vs. manual review. + +## Instructions + +When a user requests content refresh help: + +1. **CORE-EEAT Quick Score — Identify Weak Dimensions** + + Before refreshing, run a quick CORE-EEAT assessment to focus effort on the weakest areas. Reference: [CORE-EEAT Benchmark](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/core-eeat-benchmark.md) + + ```markdown + ### CORE-EEAT Quick Assessment + + **Content**: [title or URL] + **Content Type**: [type] + + Rapidly score each dimension (estimate 0-100): + + | Dimension | Quick Score | Key Weakness | Refresh Priority | + |-----------|-----------|--------------|-----------------| + | C — Contextual Clarity | [X]/100 | [main issue] | 🔴/🟡/🟢 | + | O — Organization | [X]/100 | [main issue] | 🔴/🟡/🟢 | + | R — Referenceability | [X]/100 | [main issue] | 🔴/🟡/🟢 | + | E — Exclusivity | [X]/100 | [main issue] | 🔴/🟡/🟢 | + | Exp — Experience | [X]/100 | [main issue] | 🔴/🟡/🟢 | + | Ept — Expertise | [X]/100 | [main issue] | 🔴/🟡/🟢 | + | A — Authority | [X]/100 | [main issue] | 🔴/🟡/🟢 | + | T — Trust | [X]/100 | [main issue] | 🔴/🟡/🟢 | + + **Weakest Dimensions** (focus refresh here): + 1. [Dimension] — [what needs fixing] + 2. [Dimension] — [what needs fixing] + + **Refresh Strategy**: Focus on 🔴 dimensions first, then 🟡. + + _For full 80-item audit, use [content-quality-auditor](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/content-quality-auditor/SKILL.md)_ + ``` + +2. **Identify Content Refresh Candidates** + + ```markdown + ## Content Refresh Analysis + + ### Refresh Candidate Identification + + **Criteria for Content Refresh**: + - Published more than 6 months ago + - Contains dated information (years, statistics) + - Declining traffic trend + - Lost keyword rankings + - Outdated references or broken links + - Missing topics competitors now cover + - No GEO optimization + + ### Content Audit Results + + | Content | Published | Last Updated | Traffic Trend | Priority | + |---------|-----------|--------------|---------------|----------| + | [Title 1] | [date] | [date] | ↓ -45% | 🔴 High | + | [Title 2] | [date] | Never | ↓ -30% | 🔴 High | + | [Title 3] | [date] | [date] | ↓ -20% | 🟡 Medium | + | [Title 4] | [date] | [date] | → 0% | 🟡 Medium | + + ### Refresh Prioritization Matrix + + ``` + High Traffic + High Decline = 🔴 Refresh Immediately + High Traffic + Low Decline = 🟡 Schedule Refresh + Low Traffic + High Decline = 🟡 Evaluate & Decide + Low Traffic + Low Decline = 🟢 Low Priority + ``` + ``` + +3. **Analyze Individual Content for Refresh** + + ```markdown + ## Content Refresh Analysis: [Title] + + **URL**: [URL] + **Published**: [date] + **Last Updated**: [date] + **Word Count**: [X] + + ### Performance Metrics + + | Metric | 6 Mo Ago | Current | Change | + |--------|----------|---------|--------| + | Organic Traffic | [X]/mo | [X]/mo | [+/-X]% | + | Avg Position | [X] | [X] | [+/-X] | + | Impressions | [X] | [X] | [+/-X]% | + | CTR | [X]% | [X]% | [+/-X]% | + + ### Keywords Analysis + + | Keyword | Old Position | Current Position | Change | + |---------|--------------|------------------|--------| + | [kw 1] | [X] | [X] | ↓ [X] | + | [kw 2] | [X] | [X] | ↓ [X] | + | [kw 3] | [X] | [X] | ↓ [X] | + + ### Why This Content Needs Refresh + + 1. **Outdated information**: [specific examples] + 2. **Competitive gap**: [what competitors added] + 3. **Missing topics**: [new subtopics to cover] + 4. **SEO issues**: [current optimization problems] + 5. **GEO potential**: [AI citation opportunities] + ``` + +4. **Identify Specific Updates Needed** + + ```markdown + ## Refresh Requirements + + ### Outdated Elements + + | Element | Current | Update Needed | + |---------|---------|---------------| + | Year references | "[old year]" | Update to [current year] | + | Statistics | "[old stat]" | Find current data | + | Tool mentions | "[old tool]" | Add newer tools | + | Links | [X] broken | Fix or replace | + | Screenshots | Outdated UI | Recapture | + + ### Missing Information + + **Topics competitors now cover that you don't**: + + | Topic | Competitor Coverage | Words Needed | Priority | + |-------|---------------------|--------------|----------| + | [Topic 1] | 3/5 competitors | ~300 words | High | + | [Topic 2] | 2/5 competitors | ~200 words | Medium | + | [Topic 3] | 4/5 competitors | ~400 words | High | + + ### SEO Updates Needed + + - [ ] Update title tag with current year + - [ ] Refresh meta description + - [ ] Add new H2 sections for [topics] + - [ ] Update internal links to newer content + - [ ] Add FAQ section for featured snippets + - [ ] Refresh images and add new alt text + + ### GEO Updates Needed + + - [ ] Add clear definition at start + - [ ] Include quotable statistics with sources + - [ ] Add Q&A formatted sections + - [ ] Update sources with current citations + - [ ] Create standalone factual statements + ``` + +5. **Create Refresh Plan** — Structural changes, content additions, statistics/links/images to update + + > **Reference**: See [references/refresh-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/content-refresher/references/refresh-templates.md) for the full refresh plan template (Step 5). + +6. **Write Refresh Content** — Updated introduction, new sections, refreshed statistics, new FAQ section + + > **Reference**: See [references/refresh-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/content-refresher/references/refresh-templates.md) for the refresh content writing template (Step 6). + +7. **Optimize for GEO During Refresh** — Clear definitions, quotable statements, Q&A sections, updated citations + + > **Reference**: See [references/refresh-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/content-refresher/references/refresh-templates.md) for the GEO enhancement template (Step 7). + +8. **Generate Republishing Strategy** — Date strategy (update/add "last updated"/keep original), technical implementation, promotion plan + + > **Reference**: See [references/refresh-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/content-refresher/references/refresh-templates.md) for the republishing strategy template (Step 8). + +9. **Create Refresh Report** — Summary of changes, updates completed, expected outcomes, next review date + + > **Reference**: See [references/refresh-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/content-refresher/references/refresh-templates.md) for the refresh report template (Step 9). + +## Validation Checkpoints + +### Input Validation +- [ ] Target content URL or title clearly identified +- [ ] Historical performance data available (traffic trends, rankings) +- [ ] Content publish/update dates known +- [ ] If comparing to competitors, competitor URLs provided + +### Output Validation +- [ ] Every recommendation cites specific data points (not generic advice) +- [ ] Outdated elements identified with specific examples and replacement data +- [ ] All suggested additions include word counts and section locations +- [ ] Source of each data point clearly stated (~~analytics data, ~~search console, ~~SEO tool, user-provided, or estimated) + +## Example + +> **Reference**: See [references/refresh-example.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/content-refresher/references/refresh-example.md) for a full worked example (cloud hosting refresh) and the comprehensive content refresh checklist. + +## Tips for Success + +1. **Prioritize by ROI** - Refresh high-potential content first +2. **Don't just add dates** - Make substantial improvements +3. **Beat competitors** - Add what they have and more +4. **Track results** - Monitor ranking changes post-refresh +5. **Schedule regular audits** - Check content health quarterly +6. **Optimize for GEO** - Every refresh is a GEO opportunity + +> **Reference data**: For content decay signal taxonomy, lifecycle stages, refresh vs. rewrite decision framework, and update strategy by content type, see [references/content-decay-signals.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/content-refresher/references/content-decay-signals.md). + + +### Save Results + +After delivering audit or optimization findings to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to `memory/audits/content-refresher/YYYY-MM-DD-.md` containing: +- One-line verdict or headline finding +- Top 3-5 actionable items +- Open loops or blockers +- Source data references + +If any veto-level issue was found (CORE-EEAT T04, C01, R10 or CITE T03, T05, T09), also append a one-liner to `memory/hot-cache.md` without asking. + + +**Gate check recommended**: Run content-quality-auditor on refreshed content before republishing. + +## Reference Materials + +- [Content Decay Signals](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/content-refresher/references/content-decay-signals.md) — Decay indicators, lifecycle stages, and refresh triggers by content type +- [Refresh Templates](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/content-refresher/references/refresh-templates.md) — Detailed output templates for steps 5-9 (refresh plan, content writing, GEO enhancement, republishing, report) +- [Refresh Example & Checklist](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/content-refresher/references/refresh-example.md) — Full worked example and pre/post-refresh checklist + +## Next Best Skill + +- **Primary**: [content-quality-auditor](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/content-quality-auditor/SKILL.md) — re-score the refreshed content before shipping. diff --git a/.cursor/skills/content-refresher/references/content-decay-signals.md b/.cursor/skills/content-refresher/references/content-decay-signals.md new file mode 100644 index 0000000000..9eb7dd3c55 --- /dev/null +++ b/.cursor/skills/content-refresher/references/content-decay-signals.md @@ -0,0 +1,404 @@ +# Content Decay Signals + +Comprehensive decay detection system with automated monitoring setup, severity scoring, refresh playbooks by content type, and ROI estimation for content refresh investments. + +## Decay Signal Detection System + +### Primary Signals (High Reliability) + +These signals directly indicate content performance decline and should trigger immediate investigation. + +#### 1. Organic Traffic Decline + +| Severity | Threshold | Detection Window | Action | +|----------|-----------|-----------------|--------| +| Watch | 10-20% decline | Month-over-month | Add to monitoring list | +| Warning | 20-40% decline | Month-over-month | Schedule refresh within 2 weeks | +| Critical | 40-60% decline | Month-over-month | Refresh this week | +| Emergency | >60% decline | Month-over-month | Investigate immediately (may be technical issue) | + +**Detection method**: Compare current month's organic sessions to same month previous year (to account for seasonality) and to previous month (for trend detection). + +**False positive check**: Before attributing traffic decline to content decay, rule out: +- Seasonal variations (compare year-over-year, not just month-over-month) +- Algorithm updates (check if decline coincides with known Google updates) +- Technical issues (crawl errors, indexation problems, site speed regression) +- Tracking code changes (analytics misconfiguration) + +#### 2. Ranking Position Drops + +| Severity | Threshold | Detection Window | Action | +|----------|-----------|-----------------|--------| +| Watch | 1-3 positions lost | 2-week average | Monitor | +| Warning | 3-5 positions lost | 2-week average | Investigate cause | +| Critical | 5-10 positions lost | 2-week average | Schedule immediate refresh | +| Emergency | Dropped off page 1 to page 3+ | Any timeframe | Priority refresh or rewrite | + +**Detection method**: Track primary keyword positions weekly. Use 2-week rolling averages to smooth daily fluctuations. + +#### 3. Click-Through Rate Decline + +| Severity | Threshold | Context | Action | +|----------|-----------|---------|--------| +| Watch | CTR below expected for position | Position stable, CTR dropping | Review title and meta description | +| Warning | CTR dropped 20%+ vs. baseline | With stable impressions | Rewrite title tag and meta description | +| Critical | CTR dropped 40%+ vs. baseline | May indicate stale SERP appearance | Full refresh of title, description, and structured data | + +**Expected CTR by position** (organic, desktop, approximate): + +| Position | Expected CTR Range | Below This = Investigate | +|----------|--------------------|-------------------------| +| 1 | 25-35% | <20% | +| 2 | 12-18% | <10% | +| 3 | 8-12% | <6% | +| 4-5 | 5-8% | <4% | +| 6-10 | 2-5% | <2% | + +--- + +### Secondary Signals (Moderate Reliability) + +These signals suggest potential decay but may have other causes. Use them to corroborate primary signals. + +#### 4. Engagement Metric Decline + +| Metric | Decay Indicator | Possible Cause | +|--------|----------------|---------------| +| Bounce rate increase >15% | Content no longer satisfies intent | Outdated information, better competitor content | +| Time on page decrease >20% | Users leaving faster | Content not comprehensive enough | +| Scroll depth decrease | Users not reading full content | Front-loading outdated info, losing interest | +| Pages per session decrease | Users not exploring further | Poor internal linking, irrelevant content | + +#### 5. Content Freshness Indicators + +| Indicator | Decay Risk | Detection | +|-----------|-----------|-----------| +| Published >12 months ago, never updated | High | CMS date audit | +| Contains year references 2+ years old | High | Text search for year patterns | +| Statistics from 3+ years ago | Medium | Manual review or text search for "20XX" | +| Broken external links (>10% of total) | Medium | Monthly crawl report | +| Screenshots of outdated UI | Medium | Manual visual review | +| References to discontinued products/tools | High | Manual review | + +#### 6. Competitive Displacement Signals + +| Signal | Detection Method | Severity | +|--------|-----------------|----------| +| New competitor content ranking above you | SERP monitoring | High | +| Competitor content is longer and more comprehensive | Manual comparison | Medium | +| Competitor has more recent publication date displayed in SERP | SERP monitoring | Medium | +| Featured snippet lost to competitor | SERP monitoring | High | +| AI overview now answers query without click | SERP monitoring | High | + +--- + +### Tertiary Signals (Low Reliability, Supporting Evidence) + +These signals alone do not indicate decay but strengthen the case when combined with primary or secondary signals. + +| Signal | What It Suggests | +|--------|-----------------| +| Fewer social shares over time | Content less share-worthy (may be stale) | +| Decrease in backlink acquisition | Content no longer being cited as a resource | +| Fewer comments or engagement | Community interest waning | +| Content not appearing in AI responses | Not structured for GEO or information is outdated | + +--- + +## Automated Monitoring Setup + +### Monitoring Dashboard Configuration + +Set up these automated checks to catch decay early. + +#### Weekly Checks + +| Check | Data Source | Alert Threshold | +|-------|-----------|----------------| +| Keyword position changes | Rank tracker | Any target keyword drops >3 positions | +| Crawl errors on key pages | Search Console | Any new crawl error on monitored pages | +| Index coverage changes | Search Console | Any page drops from index | + +#### Monthly Checks + +| Check | Data Source | Alert Threshold | +|-------|-----------|----------------| +| Traffic comparison (MoM) | Analytics | >15% decline on any monitored page | +| CTR comparison | Search Console | >20% CTR decline for any target keyword | +| Broken link scan | Crawler | Any new broken links on monitored pages | +| Competitor SERP changes | SERP tracker | New competitor enters top 5 | + +#### Quarterly Checks + +| Check | Data Source | Process | +|-------|-----------|---------| +| Content freshness audit | CMS + manual | Review all content older than 6 months | +| Statistics accuracy check | Manual | Verify top 20 pages have current data | +| Engagement trend review | Analytics | Compare engagement metrics across quarters | +| Full competitive content gap | SEO tool | Identify new competitor content opportunities | + +### Alert Priority Matrix + +When multiple signals fire simultaneously, use this matrix to determine response urgency. + +| Primary Signal + Secondary Signal | Priority | Response | +|----------------------------------|----------|----------| +| Traffic decline + Position drop | P1 (Critical) | Refresh within 48 hours | +| Traffic decline + CTR decline | P1 (Critical) | Rewrite title/description immediately, schedule content refresh | +| Position drop + Competitor displacement | P2 (High) | Refresh within 1 week | +| Traffic decline + Engagement decline | P2 (High) | Refresh within 1 week | +| CTR decline only | P3 (Medium) | Rewrite title and meta description this week | +| Freshness indicators only | P3 (Medium) | Schedule refresh within 2 weeks | +| Engagement decline only | P4 (Low) | Investigate and schedule if confirmed | + +--- + +## Decay Severity Scoring + +### Composite Decay Score + +Calculate a 0-100 decay severity score by summing weighted signal scores. + +| Signal Category | Weight | Score Range | +|----------------|--------|-------------| +| Traffic decline | 30% | 0 = no decline, 100 = >60% decline | +| Position drops | 25% | 0 = stable, 100 = dropped off page 1 | +| CTR decline | 15% | 0 = stable, 100 = >40% decline | +| Content freshness | 15% | 0 = updated this quarter, 100 = >2 years stale | +| Competitive displacement | 15% | 0 = no new competitors, 100 = displaced from top 3 | + +### Score Interpretation + +| Composite Score | Decay Stage | Action | +|----------------|-------------|--------| +| 0-20 | Healthy | Continue monitoring | +| 21-40 | Early decay | Add to refresh queue (next month) | +| 41-60 | Active decay | Schedule refresh (this week) | +| 61-80 | Significant decay | Immediate refresh or rewrite decision | +| 81-100 | Terminal decay | Rewrite, redirect, or retire | + +--- + +## Refresh Playbooks by Content Type + +### Blog Post / Article Refresh Playbook + +| Step | Action | Time Estimate | +|------|--------|--------------| +| 1 | Update title with current year or hook | 10 min | +| 2 | Rewrite introduction with fresh angle | 20 min | +| 3 | Update all statistics with current sources | 30-60 min | +| 4 | Add 1-2 new sections covering gaps | 60-90 min | +| 5 | Update screenshots and images | 30 min | +| 6 | Add or update FAQ section | 20 min | +| 7 | Refresh internal links | 15 min | +| 8 | Update meta description | 5 min | +| 9 | Add/update schema markup | 10 min | +| 10 | Update dateModified and republish | 5 min | +| **Total** | | **3-4 hours** | + +### Product/Service Page Refresh Playbook + +| Step | Action | Time Estimate | +|------|--------|--------------| +| 1 | Update pricing, features, specifications | 30 min | +| 2 | Add new customer testimonials/reviews | 20 min | +| 3 | Update product images | 30 min | +| 4 | Refresh comparison tables | 20 min | +| 5 | Update internal links to related products | 15 min | +| 6 | Verify and update schema markup | 10 min | +| **Total** | | **2-2.5 hours** | + +### Statistics/Data Roundup Refresh Playbook + +| Step | Action | Time Estimate | +|------|--------|--------------| +| 1 | Verify every statistic is still current | 60-90 min | +| 2 | Replace outdated stats with current data | 60 min | +| 3 | Add new statistics from recent studies | 30 min | +| 4 | Update source links and citations | 30 min | +| 5 | Update year references throughout | 15 min | +| 6 | Add new visualization if data changed significantly | 30 min | +| 7 | Update title, meta description with year | 10 min | +| **Total** | | **4-5 hours** | + +### How-To Guide Refresh Playbook + +| Step | Action | Time Estimate | +|------|--------|--------------| +| 1 | Verify all steps are still accurate | 30 min | +| 2 | Update screenshots for UI changes | 60 min | +| 3 | Add new methods or alternative approaches | 30 min | +| 4 | Update tool recommendations | 15 min | +| 5 | Add troubleshooting section if missing | 20 min | +| 6 | Update FAQ with new common questions | 15 min | +| 7 | Test all links and embedded resources | 15 min | +| **Total** | | **3-3.5 hours** | + +--- + +## ROI Estimation for Content Refresh + +### Cost-Benefit Framework + +| Factor | Measurement | +|--------|------------| +| **Cost of refresh** | Writer hours x hourly rate + tool costs | +| **Current monthly traffic value** | Organic sessions x conversion rate x avg order value | +| **Projected traffic recovery** | Based on decay stage and content potential | +| **Time to recover** | Typically 4-8 weeks for rankings to respond | + +### Traffic Recovery Benchmarks + +Based on industry data for content refreshes (not rewrites): + +| Decay Stage at Refresh | Typical Traffic Recovery | Recovery Timeline | +|------------------------|------------------------|-------------------| +| Early decay | 90-110% of peak (often exceeds) | 2-4 weeks | +| Active decay | 70-90% of peak | 4-8 weeks | +| Significant decay | 40-70% of peak | 6-12 weeks | +| Terminal decay | 10-40% of peak (rewrite may be better) | 8-16 weeks | + +### ROI Calculation Template + +``` +Refresh Cost: + Writer time: [X hours] x [$Y/hour] = $[Z] + Tool costs: $[A] (one-time crawl, research tools) + Total cost: $[Z + A] + +Monthly Traffic Value (before decay): + Peak monthly organic sessions: [N] + Conversion rate: [X]% + Average conversion value: $[Y] + Peak monthly value: [N] x [X]% x $[Y] = $[V] + +Expected Recovery: + Projected recovery: [%] of peak = $[V x %] per month + Current monthly value: $[current] + Monthly value increase: $[V x % - current] + +ROI: + Payback period: $[total cost] / $[monthly value increase] = [months] + 12-month ROI: ($[monthly value increase] x 12 - $[total cost]) / $[total cost] x 100 = [X]% +``` + +### Refresh Priority Scoring + +When choosing which content to refresh first, score each candidate: + +| Factor | Weight | Score (1-10) | +|--------|--------|-------------| +| Current traffic value | 25% | Higher traffic = higher score | +| Decay severity | 20% | More decay = more urgency | +| Competitive opportunity | 20% | Weaker competition = higher score | +| Refresh difficulty | 15% | Easier refresh = higher score | +| Strategic importance | 10% | Aligns with business goals = higher score | +| Backlink equity | 10% | More backlinks = more worth preserving | + +**Priority formula**: Weighted score total. Refresh highest-scoring content first. + +--- + +## Content Retirement Decision + +Not all decaying content should be refreshed. Use this checklist to decide when to retire content instead. + +### Retire When + +- [ ] Content targets a keyword with zero search volume +- [ ] Topic is no longer relevant to your business +- [ ] No backlinks worth preserving +- [ ] Content never ranked well even when fresh +- [ ] Cost to refresh exceeds projected 12-month value recovery +- [ ] Content cannibalizes a better-performing page on the same topic + +### Retirement Options + +| Option | When to Use | Implementation | +|--------|------------|---------------| +| 301 redirect | Content has backlinks or residual traffic | Redirect to best related page | +| Consolidate | Multiple weak pages on same topic | Merge into one strong page, redirect others | +| Noindex | Page has internal utility but should not rank | Add noindex, keep page accessible | +| Delete (410) | Content has no value, no links, no traffic | Return 410 Gone status | + +### Post-Retirement Monitoring + +After retiring content, monitor for 4 weeks: +- Verify redirects are working (no 404 errors) +- Check that target pages are receiving redirected traffic +- Monitor rankings of consolidated/target pages +- Ensure no orphan pages were created by removing internal links + +--- + +## Content Decay Signal Taxonomy + +### Decay Indicators + +| Signal | Source | Severity | Detection Method | +|--------|--------|----------|-----------------| +| Traffic decline >20% MoM | Analytics | High | Monthly traffic comparison | +| Position drop >5 positions | Rank tracker | High | Weekly rank monitoring | +| Outdated statistics/dates | Manual review | Medium | Annual content audit | +| Broken external links | Crawler | Medium | Monthly crawl reports | +| Decreased CTR | Search Console | Medium | Quarterly CTR analysis | +| Competitor new content | SERP monitoring | Medium | Monthly SERP checks | +| User engagement drop | Analytics | Low | Quarterly engagement review | +| Index coverage issues | Search Console | High | Weekly coverage monitoring | + +### Content Decay Stages + +| Stage | Symptoms | Urgency | Recommended Action | +|-------|---------|---------|-------------------| +| **Early decay** | Slight traffic/position dip | Low | Monitor for 2-4 weeks | +| **Active decay** | Consistent decline across 2+ months | Medium | Schedule refresh within 2 weeks | +| **Significant decay** | 50%+ traffic loss, page 2+ | High | Immediate refresh or rewrite | +| **Terminal decay** | No organic traffic, deindexed | Critical | Rewrite, redirect, or retire | + +## Refresh vs. Rewrite Decision Framework + +| Factor | Refresh (Update) | Rewrite (New version) | +|--------|-----------------|---------------------| +| Content quality | Good foundation, needs updating | Fundamentally flawed or outdated approach | +| Position | Was ranking well, now dropping | Never ranked well despite optimization | +| URL age | 1+ years, has earned backlinks | Young URL with no backlink equity | +| Backlinks | Has external links pointing to it | No backlinks worth preserving | +| Scope of changes needed | <50% of content changing | >50% needs rewriting | +| Search intent | Intent hasn't changed | Search intent has evolved | + +**Decision rule:** If the URL has backlinks and was ranking, REFRESH. If not, consider REWRITE at a new URL (with 301 redirect if old URL has any equity). + +## Content Lifecycle Model + +``` +CREATE → PROMOTE → MAINTAIN → REFRESH → [REFRESH again] or RETIRE + │ │ │ │ │ + │ Month 1 Month 2-6 Month 6-12 When terminal + │ Social, Monitor Update facts, 301 redirect + │ outreach, rankings, add new sections, to related + │ email fix issues improve depth content +``` + +### Lifecycle Actions by Phase + +| Phase | Duration | Key Actions | Metrics to Track | +|-------|----------|------------|-----------------| +| Create | Week 1 | Publish, submit to Search Console | Indexation | +| Promote | Month 1 | Social shares, email, outreach | Referral traffic, backlinks | +| Maintain | Months 2-6 | Monitor, fix broken links, respond to comments | Rankings, traffic trend | +| Refresh | Months 6-12+ | Update data, add sections, improve structure | Traffic recovery, new keywords | +| Retire | When terminal | 301 redirect to best alternative | Redirect traffic recovery | + +## Update Strategy by Content Type + +| Content Type | Refresh Frequency | Key Updates | Shelf Life | +|-------------|-------------------|------------|-----------| +| Statistics roundups | Every 6 months | Replace old stats, add new sources | 6-12 months | +| Tool comparisons | Every 3-6 months | Update pricing, features, screenshots | 3-6 months | +| How-to guides | Annually | Update steps, screenshots, links | 12-18 months | +| Evergreen guides | Every 12-18 months | Add new sections, update examples | 18-24 months | +| News/trend content | Don't refresh | Archive or redirect | 1-3 months | +| Case studies | Rarely | Update results if available | 2-3 years | +| Glossary/definitions | As needed | Update when definitions evolve | 2-5 years | + diff --git a/.cursor/skills/content-refresher/references/refresh-example.md b/.cursor/skills/content-refresher/references/refresh-example.md new file mode 100644 index 0000000000..40dcc1887d --- /dev/null +++ b/.cursor/skills/content-refresher/references/refresh-example.md @@ -0,0 +1,143 @@ +# Content Refresher — Worked Example & Checklist + +Referenced from [SKILL.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/content-refresher/SKILL.md). + +--- + +## Worked Example + +**User**: "Refresh my blog post about 'best cloud hosting providers'" + +**Output**: + +```markdown +### CORE-EEAT Quick Assessment + +**Content**: "Best Cloud Hosting Providers 2023" +**Content Type**: Commercial comparison / listicle + +| Dimension | Quick Score | Key Weakness | Refresh Priority | +|-----------|-----------|--------------|-----------------| +| C — Contextual Clarity | 60/100 | Title says 2023 — stale intent signal | 🔴 | +| O — Organization | 75/100 | Good comparison tables but no summary box | 🟡 | +| R — Referenceability | 35/100 | Pricing from Q1 2023, 3 broken links | 🔴 | +| E — Exclusivity | 50/100 | No original benchmarks or test data | 🟡 | +| Exp — Experience | 30/100 | No first-person testing narrative | 🔴 | +| Ept — Expertise | 65/100 | Author bio present but lacks credentials | 🟡 | +| A — Authority | 55/100 | 12 backlinks, was ranking page 1 | 🟢 | +| T — Trust | 60/100 | Affiliate links present but not disclosed | 🔴 | + +**Weakest Dimensions** (focus refresh here): +1. **Experience** — Add hands-on testing results ("We migrated a test site to each provider") +2. **Referenceability** — Replace all 2023 pricing/uptime data with current figures + +## Content Refresh Analysis: Best Cloud Hosting Providers 2023 + +**URL**: cloudhosting.com/best-cloud-hosting +**Published**: 2023-02-14 +**Last Updated**: Never +**Word Count**: 2,100 + +### Performance Metrics + +| Metric | 6 Mo Ago | Current | Change | +|--------|----------|---------|--------| +| Organic Traffic | 3,200/mo | 1,400/mo | -56% | +| Avg Position | 4.2 | 14.8 | ↓ 10.6 | +| Impressions | 18,000 | 9,500 | -47% | +| CTR | 6.1% | 2.3% | -3.8% | + +### Content Decay Signals Identified + +1. **Outdated year in title and H1** — "2023" signals stale content to users and search engines +2. **Pricing data 18+ months old** — AWS Lightsail listed at $3.50/mo (now $5/mo), DigitalOcean at $4/mo (now $6/mo) +3. **Missing new entrants** — No mention of Hetzner Cloud or Vultr, which 4/5 top competitors now cover +4. **3 broken outbound links** — Provider comparison pages that have moved or been retired + +### Refresh vs. Rewrite Decision + +| Factor | Assessment | +|--------|-----------| +| Content quality | Good structure, solid comparison tables — foundation is sound | +| URL equity | 12 referring domains, 18 months old | +| Scope of changes | ~40% of content needs updating | +| Search intent | Unchanged — still commercial comparison | + +**Decision**: **REFRESH** — The URL has earned backlinks, the structure is solid, and less than 50% needs rewriting. Keep the URL, update in place. + +## Content Refresh Plan + +**Current Title**: "Best Cloud Hosting Providers 2023" +**Refreshed Title**: "Best Cloud Hosting Providers 2024: 7 Platforms Tested & Compared" + +### Specific Refresh Actions + +1. **Update all pricing and specs** (~30 min) + - Replace 2023 pricing for all 5 listed providers with current data + - Add uptime stats from the last 12 months (source: UptimeRobot public status pages) + - Update feature comparison table with current plan tiers + +2. **Add 2 missing providers + testing narrative** (~600 words) + - Add Hetzner Cloud and Vultr sections with same comparison format + - Write intro paragraph: "We deployed a WordPress benchmark site to each provider and measured TTFB, uptime, and support response times over 30 days" + +3. **Add affiliate disclosure and FAQ section** (~200 words) + - Add disclosure statement below introduction: "This post contains affiliate links. See our editorial policy." + - Add FAQ with 4 questions targeting People Also Ask (e.g., "What is the cheapest cloud hosting?", "Is cloud hosting faster than shared hosting?") + - Implement FAQ schema markup for rich result eligibility + +4. **Fix broken links and update internal links** (~15 min) + - Replace 3 broken outbound links with current provider URLs + - Add internal links to cloudhosting.com/vps-vs-cloud and cloudhosting.com/hosting-speed-test + +### Republishing Strategy + +**Recommendation**: Update Published Date — this is a major overhaul (40%+ new content, new providers, fresh test data). Update `dateModified` in Article schema, resubmit URL in Search Console, and share on social as "Updated for 2024." + +### Expected Outcomes + +| Metric | Current | 30-Day Target | 90-Day Target | +|--------|---------|---------------|---------------| +| Avg Position | 14.8 | 8-10 | 3-6 | +| Organic Traffic | 1,400/mo | 2,200/mo | 3,500/mo | +| Featured Snippets | 0 | 1 (FAQ) | 2+ | +``` + +--- + +## Content Refresh Checklist + +```markdown +### Pre-Refresh +- [ ] Analyze current performance metrics +- [ ] Identify outdated information +- [ ] Research competitor updates +- [ ] Note missing topics + +### Content Updates +- [ ] Update year references +- [ ] Refresh statistics with sources +- [ ] Add new examples and case studies +- [ ] Expand thin sections +- [ ] Add new relevant sections +- [ ] Create FAQ section + +### SEO Updates +- [ ] Update title tag +- [ ] Refresh meta description +- [ ] Optimize headers +- [ ] Update internal links +- [ ] Add new images with alt text + +### GEO Updates +- [ ] Add clear definition +- [ ] Include quotable statements +- [ ] Add Q&A formatted content +- [ ] Update source citations + +### Technical +- [ ] Update schema dateModified +- [ ] Clear page cache +- [ ] Update sitemap +- [ ] Test page speed +``` diff --git a/.cursor/skills/content-refresher/references/refresh-templates.md b/.cursor/skills/content-refresher/references/refresh-templates.md new file mode 100644 index 0000000000..8b9e52a826 --- /dev/null +++ b/.cursor/skills/content-refresher/references/refresh-templates.md @@ -0,0 +1,253 @@ +# Content Refresh Templates + +Detailed output templates for content-refresher steps 5-9. Referenced from [SKILL.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/content-refresher/SKILL.md). + +--- + +## Step 5: Create Refresh Plan + +```markdown +## Content Refresh Plan + +### Title/URL +**Current**: [current title] +**Refreshed**: [updated title with year/hook] + +### Structural Changes + +**Keep As-Is**: +- [Section 1] - Still relevant and accurate +- [Section 2] - Still relevant and accurate + +**Update/Expand**: +- [Section 3] - Update statistics, add [X] words +- [Section 4] - Add new examples from [current year] + +**Add New Sections**: +- [New Section 1] - [description, ~X words] +- [New Section 2] - [description, ~X words] +- FAQ Section - [X questions for featured snippets] + +**Remove/Consolidate**: +- [Section 5] - Outdated, remove or redirect topic + +### Content Additions + +**New Word Count Target**: [X] words (+[Y] from current) + +| Section | Current | After Refresh | Notes | +|---------|---------|---------------|-------| +| Introduction | [X] | [X] | Add hook, update context | +| [Section 1] | [X] | [X] | Keep | +| [Section 2] | [X] | [X] | Update stats | +| [New Section] | 0 | [X] | Add entirely | +| FAQ | 0 | [X] | Add for GEO | +| Conclusion | [X] | [X] | Update CTA | + +### Specific Updates + +**Statistics to Update**: + +| Old Statistic | New Statistic | Source | +|---------------|---------------|--------| +| "[old stat]" | "[find current]" | [source] | +| "[old stat]" | "[find current]" | [source] | + +**Links to Update**: + +| Anchor Text | Old URL | New URL | Reason | +|-------------|---------|---------|--------| +| "[anchor]" | [old] | [new] | Broken | +| "[anchor]" | [old] | [new] | Better resource | + +**Images to Update**: + +| Image | Action | New Alt Text | +|-------|--------|--------------| +| [img 1] | Replace | "[keyword-rich alt]" | +| [img 2] | Keep | Update alt text | +``` + +--- + +## Step 6: Write Refresh Content + +```markdown +## Refreshed Content Sections + +### Updated Introduction + +[Write new introduction with:] +- Updated hook for current year +- Fresh statistics +- Clear value proposition +- Primary keyword in first 100 words + +### New Section: [Title] + +[Write new section covering:] +- [Topic competitors now cover] +- Current information and examples +- GEO-optimized with quotable statements + +### Updated Statistics Section + +**Replace**: +> "[Old statement with outdated stat]" + +**With**: +> "[New statement with current stat] (Source, [current year])" + +### New FAQ Section + +## Frequently Asked Questions + +### [Question matching PAA/common query]? + +[Direct answer in 40-60 words, optimized for featured snippets] + +### [Question 2]? + +[Direct answer] + +### [Question 3]? + +[Direct answer] +``` + +--- + +## Step 7: Optimize for GEO During Refresh + +```markdown +## GEO Enhancement Opportunities + +### Add Clear Definitions + +**Add at start of article**: +> **[Topic]** is [clear, quotable definition in 40-60 words that +> AI systems can cite directly]. + +### Add Quotable Statements + +**Transform**: +> "Email marketing is effective for businesses." + +**Into**: +> "Email marketing delivers an average ROI of $42 for every $1 +> invested, making it the highest-ROI digital marketing channel +> according to the Data & Marketing Association ([current year])." + +### Add Q&A Sections + +Structure content with questions AI might answer: +- What is [topic]? +- How does [topic] work? +- Why is [topic] important? +- What are the benefits of [topic]? + +### Update Citations + +- Add sources for all statistics +- Link to authoritative references +- Include publication dates +- Use recent sources (last 2 years) +``` + +--- + +## Step 8: Generate Republishing Strategy + +```markdown +## Republishing Strategy + +### Date Strategy + +**Options**: + +1. **Update Published Date** + - Use when: Major overhaul (50%+ new content) + - Pros: Signals freshness to Google + - Cons: Loses "original" authority + +2. **Add "Last Updated" Date** + - Use when: Moderate updates (20-50% new) + - Pros: Shows both original and fresh + - Cons: Original date visible + +3. **Keep Original Date** + - Use when: Minor updates (<20% new) + - Pros: Maintains authority + - Cons: Doesn't signal update + +**Recommendation**: [Option X] because [reason] + +### Technical Implementation + +- [ ] Update `dateModified` in schema +- [ ] Update sitemap lastmod +- [ ] Clear cache after publishing +- [ ] Resubmit to ~~search console + +### Promotion Strategy + +**Immediately after refresh**: +- [ ] Share on social media as "updated for [current year]" +- [ ] Send to email list if significant update +- [ ] Update internal links with fresh anchors +- [ ] Reach out for new backlinks + +**Track Results**: +- [ ] Monitor rankings for 4-6 weeks +- [ ] Track traffic changes +- [ ] Watch for featured snippet capture +- [ ] Check AI citation improvements +``` + +--- + +## Step 9: Create Refresh Report + +```markdown +# Content Refresh Report + +## Summary + +**Content**: [Title] +**Refresh Date**: [Date] +**Refresh Level**: [Major/Moderate/Minor] + +## Changes Made + +| Element | Before | After | +|---------|--------|-------| +| Word count | [X] | [Y] (+[Z]%) | +| Sections | [X] | [Y] | +| Statistics | [X] outdated | [Y] current | +| Internal links | [X] | [Y] | +| Images | [X] | [Y] | +| FAQ questions | 0 | [X] | + +## Updates Completed + +- [x] Updated title with current year +- [x] Refreshed meta description +- [x] Added [X] new sections +- [x] Updated [X] statistics with sources +- [x] Fixed [X] broken links +- [x] Added FAQ section for GEO +- [x] Implemented FAQ schema +- [x] Updated images and alt text + +## Expected Outcomes + +| Metric | Current | 30-Day Target | 90-Day Target | +|--------|---------|---------------|---------------| +| Avg Position | [X] | [Y] | [Z] | +| Organic Traffic | [X]/mo | [Y]/mo | [Z]/mo | +| Featured Snippets | 0 | 1+ | 2+ | + +## Next Review + +Schedule next refresh review: [Date - 6 months from now] +``` diff --git a/.cursor/skills/domain-authority-auditor/SKILL.md b/.cursor/skills/domain-authority-auditor/SKILL.md new file mode 100644 index 0000000000..1840cfd38e --- /dev/null +++ b/.cursor/skills/domain-authority-auditor/SKILL.md @@ -0,0 +1,394 @@ +--- +name: domain-authority-auditor +description: '40-item CITE domain audit: citation, impact, trust, entity scoring with veto checks. 域名权威/网站可信度' +version: "6.0.0" +license: Apache-2.0 +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when auditing domain trust and authority. Runs CITE 40-item scoring with veto checks. Also when the user asks about domain credibility or citation trustworthiness." +argument-hint: "" +metadata: + author: aaron-he-zhu + version: "6.0.0" + geo-relevance: "medium" + tags: + - seo + - geo + - domain-authority + - domain-rating + - domain-trust + - cite-framework + - site-authority + - 域名权威 + - ドメイン権威 + - 도메인권위 + - autoridad-dominio + triggers: + # EN-formal + - "audit domain authority" + - "CITE audit" + - "domain trust score" + - "domain credibility check" + - "domain rating" + - "site authority" + # EN-casual + - "how trustworthy is my site" + - "is my domain credible" + - "is my domain trustworthy" + - "domain credibility score" + - "Google penalty recovery" + - "my site got penalized" + # EN-question + - "how authoritative is my site" + - "what is my domain authority" + # ZH-pro + - "域名权威审计" + - "网站可信度" + - "域名评分" + # ZH-casual + - "域名可信吗" + - "权威度多少" + - "网站可信度怎么样" + # JA + - "ドメイン権威" + - "ドメイン評価" + # KO + - "도메인 권위" + - "도메인 신뢰도" + # ES + - "autoridad de dominio" + - "auditoría de dominio" + # PT + - "autoridade de domínio" + # Misspellings + - "domain autority" +--- + +# Domain Authority Auditor + +> Based on [CITE Domain Rating](https://github.com/aaron-he-zhu/cite-domain-rating). Full benchmark reference: [references/cite-domain-rating.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/cite-domain-rating.md) + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This cross-cutting skill is part of the protocol layer and follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + + +This skill evaluates domain authority across 40 standardized criteria organized in 4 dimensions. It produces a comprehensive audit report with per-item scoring, dimension and weighted scores by domain type, veto item checks, and a prioritized action plan. + +**Sister skill**: [content-quality-auditor](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/content-quality-auditor/SKILL.md) evaluates content at the page level (80 items). This skill evaluates the domain behind the content (40 items). Together they provide a complete 120-item assessment. + +> **Namespace note**: CITE uses C01-C10 for Citation items; CORE-EEAT uses C01-C10 for Contextual Clarity items. In combined 120-item assessments, prefix with the framework name (e.g., CITE-C01 vs CORE-C01) to avoid confusion. + +**System role**: Citation Trust Gate. It decides whether a domain is credible enough to support ranking, citation, and brand authority work. + +## When This Must Trigger + +Use this when domain credibility or citation trustworthiness is in question — even if the user doesn't use audit terminology: + +- User asks "how trustworthy is my site" or "is my domain credible" +- When backlink-analyzer finds toxic link ratio above 15%, its handoff summary recommends this gate check +- Evaluating domain authority before a GEO campaign +- Benchmarking your domain against competitors +- Assessing whether a domain is trustworthy as a citation source +- Running periodic domain health checks or after link building campaigns +- Identifying manipulation red flags (PBNs, link farms, penalty history) +- Cross-referencing with content-quality-auditor for full 120-item assessment + +## What This Skill Does + +1. **Full 40-Item Audit**: Scores every CITE check item as Pass/Partial/Fail +2. **Dimension Scoring**: Calculates scores for all 4 dimensions (0-100 each) +3. **Weighted Totals**: Applies domain-type-specific weights for CITE Score +4. **Veto Detection**: Flags critical manipulation signals (T03, T05, T09) +5. **Priority Ranking**: Identifies Top 5 improvements sorted by impact +6. **Action Plan**: Generates specific, actionable improvement steps +7. **Cross-Reference**: Optionally pairs with CORE-EEAT for combined diagnosis + +## Quick Start + +Start with one of these prompts. Finish with a citation-trust verdict and a handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Audit Your Domain + +``` +Audit domain authority for [domain] +Run a CITE domain audit on [domain] as a [domain type] +``` + +### Audit with Domain Type + +``` +CITE audit for example.com as an e-commerce site +Score this SaaS domain against the 40-item benchmark: [domain] +``` + +### Comparative Audit + +``` +Compare domain authority: [your domain] vs [competitor 1] vs [competitor 2] +``` + +### Combined Assessment + +``` +Run full 120-item assessment on [domain]: CITE domain audit + CORE-EEAT content audit on [sample pages] +``` + +## Skill Contract + +**Gate verdict**: **TRUSTED** (no veto items, scores above threshold) / **CAUTIOUS** (issues found but no veto) / **UNTRUSTED** (veto item T03, T05, or T09 failed). Always state the verdict prominently at the top of the report. + +**Expected output**: a CITE audit report, a citation-trust verdict, and a short handoff summary ready for `memory/audits/domain/`. + +- **Reads**: the target domain, supporting authority signals, comparison domains, and prior decisions from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available. +- **Writes**: a user-facing authority report plus a reusable summary that can be stored under `memory/audits/domain/`. +- **Promotes**: veto items and domain risks to `memory/hot-cache.md` (auto-saved). Authority context to `memory/audits/domain/`. Results feed into entity-optimizer as authority input for brand's canonical profile. +- **Next handoff**: use the `Next Best Skill` below once the trust picture is clear. + +## Data Sources + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +> **Note:** All integrations are optional. This skill works without any API keys — users provide data manually when no tools are connected. + +**With ~~link database + ~~SEO tool + ~~AI monitor + ~~knowledge graph + ~~brand monitor connected:** +Automatically pull backlink profiles and link quality metrics from ~~link database, domain authority scores and keyword rankings from ~~SEO tool, AI citation data from ~~AI monitor, entity presence from ~~knowledge graph, and brand mention data from ~~brand monitor. + +**With manual data only:** +Ask the user to provide: +1. Domain to evaluate +2. Domain type (if not auto-detectable): Content Publisher, Product & Service, E-commerce, Community & UGC, Tool & Utility, or Authority & Institutional +3. Backlink data: referring domains count, domain authority, top linking domains +4. Traffic estimates (from any SEO tool or SimilarWeb) +5. Competitor domains for comparison (optional) + +Proceed with the full 40-item audit using provided data. Note in the output which items could not be fully evaluated due to missing access (e.g., AI citation data, knowledge graph queries, WHOIS history). + +## Instructions + +When a user requests a domain authority audit: + +### Step 1: Preparation + +```markdown +### Audit Setup + +**Domain**: [domain] +**Domain Type**: [auto-detected or user-specified] +**Dimension Weights**: [from domain-type weight table below] + +#### Domain-Type Weight Table + +> Canonical source: `references/cite-domain-rating.md`. This inline copy is for convenience. + +| Dim | Default | Content Publisher | Product & Service | E-commerce | Community & UGC | Tool & Utility | Authority & Institutional | +|-----|:-------:|:-:|:-:|:-:|:-:|:-:|:-:| +| C | 35% | **40%** | 25% | 20% | 35% | 25% | **45%** | +| I | 20% | 15% | **30%** | 20% | 10% | **30%** | 20% | +| T | 25% | 20% | 25% | **35%** | 25% | 25% | 20% | +| E | 20% | 25% | 20% | 25% | **30%** | 20% | 15% | + +#### Veto Check (Emergency Brake) + +| Veto Item | Status | Action | +|-----------|--------|--------| +| T03: Link-Traffic Coherence | ✅ Pass / ⚠️ VETO | [If VETO: "Audit backlink profile; disavow toxic links"] | +| T05: Backlink Profile Uniqueness | ✅ Pass / ⚠️ VETO | [If VETO: "Flag as manipulation network; investigate link sources"] | +| T09: Penalty & Deindex History | ✅ Pass / ⚠️ VETO | [If VETO: "Address penalty first; all other optimization is futile"] | +``` + +If any veto item triggers, flag it prominently at the top of the report. CITE Score is capped at 39 (Poor) regardless of other scores. + +### Step 2: C + I Audit (20 items) + +Evaluate each item against the criteria in [references/cite-domain-rating.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/cite-domain-rating.md). + +Score each item: +- **Pass** = 10 points (fully meets criteria) +- **Partial** = 5 points (partially meets criteria) +- **Fail** = 0 points (does not meet criteria) + +```markdown +### C — Citation + +| ID | Check Item | Score | Notes | +|----|-----------|-------|-------| +| C01 | Referring Domains Volume | Pass/Partial/Fail | [specific observation] | +| C02 | Referring Domains Quality | Pass/Partial/Fail | [specific observation] | +| ... | ... | ... | ... | +| C10 | Link Source Diversity | Pass/Partial/Fail | [specific observation] | + +**C Score**: [X]/100 + +### I — Identity + +| ID | Check Item | Score | Notes | +|----|-----------|-------|-------| +| I01 | Knowledge Graph Presence | Pass/Partial/Fail | [specific observation] | +| ... | ... | ... | ... | + +**I Score**: [X]/100 +``` + +### Step 3: T + E Audit (20 items) + +Same format for Trust and Eminence dimensions. + +```markdown +### T — Trust + +| ID | Check Item | Score | Notes | +|----|-----------|-------|-------| +| T01 | Link Profile Naturalness | Pass/Partial/Fail | [specific observation] | +| ... | ... | ... | ... | + +**T Score**: [X]/100 + +### E — Eminence + +| ID | Check Item | Score | Notes | +|----|-----------|-------|-------| +| E01 | Organic Search Visibility | Pass/Partial/Fail | [specific observation] | +| ... | ... | ... | ... | + +**E Score**: [X]/100 +``` + +**Note**: Some items require specialized data (C05-C08 AI citation data, I01 knowledge graph queries, T04-T05 IP/profile analysis). Score what is observable; mark unverifiable items as "N/A — requires [data source]" and exclude from dimension average. + +### Step 4: Scoring & Report + +Calculate scores and generate the final report: + +```markdown +## CITE Domain Authority Report + +### Overview + +- **Domain**: [domain] +- **Domain Type**: [type] +- **Audit Date**: [date] +- **CITE Score**: [score]/100 ([rating]) +- **Veto Status**: ✅ No triggers / ⚠️ [item] triggered — Score capped at 39 + +### Dimension Scores + +| Dimension | Score | Rating | Weight | Weighted | +|-----------|-------|--------|--------|----------| +| C — Citation | [X]/100 | [rating] | [X]% | [X] | +| I — Identity | [X]/100 | [rating] | [X]% | [X] | +| T — Trust | [X]/100 | [rating] | [X]% | [X] | +| E — Eminence | [X]/100 | [rating] | [X]% | [X] | +| **CITE Score** | | | | **[X]/100** | + +**Score Calculation**: CITE Score = C × [w_C] + I × [w_I] + T × [w_T] + E × [w_E] + +**Rating Scale**: 90-100 Excellent | 75-89 Good | 60-74 Medium | 40-59 Low | 0-39 Poor + +### Per-Item Scores + +| ID | Check Item | Score | Notes | +|----|-----------|-------|-------| +| C01 | Referring Domains Volume | [Pass/Partial/Fail] | [observation] | +| C02 | Referring Domains Quality | [Pass/Partial/Fail] | [observation] | +| ... | ... | ... | ... | +| E10 | Industry Share of Voice | [Pass/Partial/Fail] | [observation] | + +### Top 5 Priority Improvements + +Sorted by: weight × points lost (highest impact first) + +1. **[ID] [Name]** — [specific modification suggestion] + - Current: [Fail/Partial] | Potential gain: [X] weighted points + - Action: [concrete step] +2. **[ID] [Name]** — [specific modification suggestion] + - Current: [Fail/Partial] | Potential gain: [X] weighted points + - Action: [concrete step] +3–5. [Same format] + +### Action Plan + +#### Quick Wins (< 1 week) +- [ ] [Action 1] +- [ ] [Action 2] +#### Medium Effort (1-4 weeks) +- [ ] [Action 3] +- [ ] [Action 4] +#### Strategic (1-3 months) +- [ ] [Action 5] +- [ ] [Action 6] + +### Cross-Reference with CORE-EEAT + +For a complete assessment, pair this CITE audit with a CORE-EEAT content audit: + +| Assessment | Score | Rating | +|-----------|-------|--------| +| CITE (Domain) | [X]/100 | [rating] | +| CORE-EEAT (Content) | [Run content-quality-auditor on sample pages] | — | + +**Diagnosis Matrix**: +- High CITE + High CORE-EEAT → Maintain and expand +- High CITE + Low CORE-EEAT → Prioritize content quality +- Low CITE + High CORE-EEAT → Build domain authority +- Low CITE + Low CORE-EEAT → Start with content, then domain + +### Recommended Next Steps + +- For domain authority building: focus on top 5 priorities above +- For content improvement: use `content-quality-auditor` on key pages +- For backlink strategy: use `backlink-analyzer` for detailed link analysis +- For competitor benchmarking: use `competitor-analysis` with CITE scores +- For tracking progress: run `/seo:report` with CITE score trends +``` + +### Save Results + +After delivering findings to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to the appropriate `memory/` path using filename `YYYY-MM-DD-.md` containing: +- One-line verdict or headline finding +- Top 3-5 actionable items +- Open loops or blockers +- Source data references + +If any veto-level issue was found (CORE-EEAT T04, C01, R10 or CITE T03, T05, T09), also append a one-liner to `memory/hot-cache.md` without asking. + +## Validation Checkpoints + +### Input Validation +- [ ] Domain identified and accessible +- [ ] Domain type confirmed (auto-detected or user-specified) +- [ ] Backlink data available (at minimum: referring domains count, DA/DR) +- [ ] If comparative audit, competitor domains also specified + +### Output Validation +- [ ] All 40 items scored (or marked N/A with reason) +- [ ] All 4 dimension scores calculated correctly +- [ ] Weighted CITE Score matches domain-type weight configuration +- [ ] All 3 veto items checked first and flagged if triggered +- [ ] Top 5 improvements sorted by weighted impact, not arbitrary +- [ ] Every recommendation is specific and actionable (not generic advice) +- [ ] Action plan includes concrete steps with effort estimates + +## Example + +See [references/example-report.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/domain-authority-auditor/references/example-report.md) for a complete CITE audit of cloudhosting.com showing veto check, dimension scores, top 5 improvements, action plan, and cross-reference with CORE-EEAT. + +## Tips for Success + +1. **Start with veto items** — T03, T05, T09 can invalidate the entire score +2. **Identify domain type first** — Different types have very different weight profiles +3. **AI citation items (C05-C08) matter most for GEO** — Test by querying AI engines with niche-relevant questions +4. **Some items need specialized tools** — Knowledge graph queries, AI citation monitoring, and IP diversity analysis may require manual research if tools aren't connected +5. **Pair with CORE-EEAT for full picture** — Domain authority without content quality (or vice versa) tells only half the story + +## Reference Materials + +- [CITE Domain Rating](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/cite-domain-rating.md) — Full 40-item benchmark with dimension definitions, scoring criteria, domain-type weight tables, and veto items +- [references/example-report.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/domain-authority-auditor/references/example-report.md) — Complete CITE audit example with scored dimensions, top 5 improvements, action plan, and CORE-EEAT cross-reference + +## Next Best Skill + +- **Primary**: [backlink-analyzer](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/backlink-analyzer/SKILL.md) — turn trust or citation issues into link-level investigation. diff --git a/.cursor/skills/domain-authority-auditor/references/example-report.md b/.cursor/skills/domain-authority-auditor/references/example-report.md new file mode 100644 index 0000000000..fe20e30132 --- /dev/null +++ b/.cursor/skills/domain-authority-auditor/references/example-report.md @@ -0,0 +1,99 @@ +# CITE Domain Authority Report — Example + +Full example audit output for reference. See the [SKILL.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/domain-authority-auditor/SKILL.md) for the complete workflow. + +## Example + +**User**: "Audit domain authority for cloudhosting.com as a content publisher" + +**Output**: + +```markdown +## CITE Domain Authority Report + +### Overview + +- **Domain**: cloudhosting.com +- **Domain Type**: Content Publisher +- **Audit Date**: 2025-02-03 +- **CITE Score**: 69.9/100 (Medium) +- **Veto Status**: ✅ No triggers + +#### Veto Check (Emergency Brake) + +| Veto Item | Status | Action | +|-----------|--------|--------| +| T03: Link-Traffic Coherence | ✅ Pass | Link growth correlates with traffic growth | +| T05: Backlink Profile Uniqueness | ✅ Pass | No PBN patterns detected; diverse link sources | +| T09: Penalty & Deindex History | ✅ Pass | No manual actions; clean penalty history | + +### Dimension Scores + +| Dimension | Score | Rating | Weight | Weighted | +|-----------|-------|--------|--------|----------| +| C — Citation | 72/100 | Medium | 40% | 28.8 | +| I — Identity | 58/100 | Low | 15% | 8.7 | +| T — Trust | 81/100 | Good | 20% | 16.2 | +| E — Eminence | 65/100 | Medium | 25% | 16.25 | +| **CITE Score** | | | | **69.9/100** | + +**Score Calculation**: +- CITE Score = 72 × 0.40 + 58 × 0.15 + 81 × 0.20 + 65 × 0.25 = 69.9 + +**Rating Scale**: 90-100 Excellent | 75-89 Good | 60-74 Medium | 40-59 Low | 0-39 Poor + +### Top 5 Priority Improvements + +Sorted by: weight × points lost (highest impact first) + +1. **I01 Knowledge Graph Presence** — Create entity entry in Google Knowledge Graph + - Current: Fail | Potential gain: 1.5 weighted points + - Action: Create Wikidata entry for CloudHost Inc. with P856 (website), P452 (industry), P571 (inception) + +2. **C05 AI Citation Volume** — Increase citations in AI-generated answers + - Current: Partial | Potential gain: 2.0 weighted points + - Action: Optimize top 10 pages for GEO; add definitive statements AI can quote directly + +3. **I03 Brand SERP Control** — Branded SERP shows only 4 of 10 results from owned properties + - Current: Partial | Potential gain: 0.75 weighted points + - Action: Claim Google Business Profile; build out social profiles; create CrunchBase entry + +4. **E04 Content Freshness Cadence** — 40% of content is >12 months without update + - Current: Partial | Potential gain: 1.25 weighted points + - Action: Establish monthly content refresh schedule; prioritize top 20 traffic pages + +5. **I05 Schema.org Completeness** — Organization schema missing sameAs, founder, foundingDate + - Current: Partial | Potential gain: 0.75 weighted points + - Action: Add complete Organization schema with sameAs links to Wikidata, LinkedIn, CrunchBase + +### Action Plan + +#### Quick Wins (< 1 week) +- [ ] Add sameAs, founder, and foundingDate to Organization schema +- [ ] Claim Google Business Profile for branded SERP control + +#### Medium Effort (1-4 weeks) +- [ ] Create Wikidata entry with complete properties and references +- [ ] Optimize top 10 pages with GEO-friendly definitive statements +- [ ] Create or complete CrunchBase, LinkedIn company page profiles + +#### Strategic (1-3 months) +- [ ] Launch monthly content refresh program targeting stale pages +- [ ] Build topical authority through 3-4 pillar content clusters +- [ ] Pursue digital PR to earn mentions on industry publications (TechCrunch, G2) + +### Cross-Reference with CORE-EEAT + +| Assessment | Score | Rating | +|-----------|-------|--------| +| CITE (Domain) | 69.9/100 | Medium | +| CORE-EEAT (Content) | Run content-quality-auditor on sample pages | — | + +**Diagnosis**: Low CITE + unknown CORE-EEAT → Run `/seo:audit-page` on top 5 landing pages to determine whether to prioritize content quality or domain authority first. + +### Recommended Next Steps + +- For entity building: run `entity-optimizer` to strengthen I-dimension signals +- For content audit: use `content-quality-auditor` on key pages +- For tracking progress: run `/seo:report` with CITE score trends quarterly +``` diff --git a/.cursor/skills/entity-optimizer/SKILL.md b/.cursor/skills/entity-optimizer/SKILL.md new file mode 100644 index 0000000000..7a2a6c5029 --- /dev/null +++ b/.cursor/skills/entity-optimizer/SKILL.md @@ -0,0 +1,376 @@ +--- +name: entity-optimizer +description: 'Build entity presence in Knowledge Graph, Wikidata, AI systems for brand recognition and citations. 实体优化/知识图谱' +version: "6.0.0" +license: Apache-2.0 +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when optimizing entity presence for Knowledge Graph, Wikidata, or AI engine disambiguation. Also for brand entity canonicalization." +argument-hint: "" +metadata: + author: aaron-he-zhu + version: "6.0.0" + geo-relevance: "high" + tags: + - seo + - geo + - entity-optimization + - knowledge-graph + - knowledge-panel + - brand-entity + - wikidata + - entity-disambiguation + - 实体优化 + - エンティティ + - 엔티티 + - entidad-seo + triggers: + # EN-formal + - "optimize entity presence" + - "build knowledge graph" + - "improve knowledge panel" + - "entity audit" + - "establish brand entity" + - "entity disambiguation" + # EN-casual + - "Google doesn't know my brand" + - "no knowledge panel" + - "establish my brand" + - "establish my brand as an entity" + - "get a Google knowledge card" + - "no Wikipedia entry" + # EN-question + - "how to get a knowledge panel" + - "how to build brand entity" + # ZH-pro + - "实体优化" + - "知识图谱" + - "品牌实体" + - "知识面板" + - "品牌词" + - "品牌词优化" + # ZH-casual + - "品牌搜不到" + - "没有知识面板" + - "Google不认识我的品牌" + # JA + - "エンティティ最適化" + - "ナレッジパネル" + # KO + - "엔티티 최적화" + - "지식 패널" + - "구글이 내 브랜드 모르는데?" + - "지식 패널 만들려면?" + # ES + - "optimización de entidad" + - "panel de conocimiento" + # PT + - "otimização de entidade" + # Misspellings + - "knowlege panel" + - "enity optimization" +--- + +# Entity Optimizer + + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This cross-cutting skill is part of the protocol layer and follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + + +Audits, builds, and maintains entity identity across search engines and AI systems. Entities — the people, organizations, products, and concepts that search engines and AI systems recognize as distinct things — are the foundation of how both Google and LLMs decide *what a brand is* and *whether to cite it*. + +**Why entities matter for SEO + GEO:** + +- **SEO**: Google's Knowledge Graph powers Knowledge Panels, rich results, and entity-based ranking signals. A well-defined entity earns SERP real estate. +- **GEO**: AI systems resolve queries to entities before generating answers. If an AI cannot identify an entity, it cannot cite it — no matter how good the content is. + +**System role**: Canonical Entity Profile. It acts as the source of truth for entity identity, associations, and disambiguation across the library. + +## When This Must Trigger + +Use this when brand or entity identity needs to be established or verified — even if the user doesn't use entity terminology: + +- User says "Google doesn't know my brand" or "no knowledge panel" +- Auto-recommended when `memory/entities/candidates.md` accumulates 3 or more uncanonized entity candidates from other skills +- Establishing a new brand/person/product as a recognized entity +- Auditing current entity presence across Knowledge Graph, Wikidata, and AI systems +- Improving or correcting a Knowledge Panel +- Building entity associations (entity ↔ topic, entity ↔ industry) +- Resolving entity disambiguation issues (your entity confused with another) +- Strengthening entity signals for AI citation +- After launching a new brand, product, or organization +- Preparing for a site migration (preserving entity identity) +- Running periodic entity health checks + +## What This Skill Does + +1. **Entity Audit**: Evaluates current entity presence across search and AI systems +2. **Knowledge Graph Analysis**: Checks Google Knowledge Graph, Wikidata, and Wikipedia status +3. **AI Entity Resolution Test**: Queries AI systems to see how they identify and describe the entity +4. **Entity Signal Mapping**: Identifies all signals that establish entity identity +5. **Gap Analysis**: Finds missing or weak entity signals +6. **Entity Building Plan**: Creates actionable plan to establish or strengthen entity presence +7. **Disambiguation Strategy**: Resolves confusion with similarly-named entities + +## Quick Start + +Start with one of these prompts. Finish with a canonical entity profile and a handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Entity Audit + +``` +Audit entity presence for [brand/person/organization] +``` + +``` +How well do search engines and AI systems recognize [entity name]? +``` + +### Build Entity Presence + +``` +Build entity presence for [new brand] in the [industry] space +``` + +``` +Establish [person name] as a recognized expert in [topic] +``` + +### Fix Entity Issues + +``` +My Knowledge Panel shows incorrect information — fix entity signals for [entity] +``` + +``` +AI systems confuse [my entity] with [other entity] — help me disambiguate +``` + +## Skill Contract + +**Expected output**: an entity audit, a canonical entity profile, and a short handoff summary ready for `memory/entities/`. + +- **Reads**: the entity name, primary domain, known profiles, topic associations, and prior brand context from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available. +- **Writes**: a user-facing entity report plus a reusable profile that can be stored under `memory/entities/`. +- **Promotes**: canonical names, sameAs links, disambiguation notes, and entity gaps to `CLAUDE.md`, `memory/entities/`, and `memory/open-loops.md`. + +This skill is the sole writer of canonical entity profiles at `memory/entities/.md`. Other skills write entity candidates to `memory/entities/candidates.md` only. When 3+ candidates accumulate, this skill should be recommended. + +- **Next handoff**: use the `Next Best Skill` below once the entity truth is clear. + +## Data Sources + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +**With ~~knowledge graph + ~~SEO tool + ~~AI monitor + ~~brand monitor connected:** +Query Knowledge Graph API for entity status, pull branded search data from ~~SEO tool, test AI citation with ~~AI monitor, track brand mentions with ~~brand monitor. + +**With manual data only:** +Ask the user to provide: +1. Entity name, type (Person, Organization, Brand, Product, Creative Work, Event) +2. Primary website / domain +3. Known existing profiles (Wikipedia, Wikidata, social media, industry directories) +4. Top 3-5 topics/industries the entity should be associated with +5. Any known disambiguation issues (other entities with same/similar name) + +Without tools, Claude provides entity optimization strategy and recommendations based on information the user provides. The user must run search queries, check Knowledge Panels, and test AI responses to supply the raw data for analysis. + +Proceed with the audit using public search results, AI query testing, and SERP analysis. Note which items require tool access for full evaluation. + +## Instructions + +When a user requests entity optimization: + +### Step 1: Entity Discovery + +Establish the entity's current state across all systems. + +```markdown +### Entity Profile + +**Entity Name**: [name] +**Entity Type**: [Person / Organization / Brand / Product / Creative Work / Event] +**Primary Domain**: [URL] +**Target Topics**: [topic 1, topic 2, topic 3] + +#### Current Entity Presence + +| Platform | Status | Details | +|----------|--------|---------| +| Google Knowledge Panel | ✅ Present / ❌ Absent / ⚠️ Incorrect | [details] | +| Wikidata | ✅ Listed / ❌ Not listed | [QID if exists] | +| Wikipedia | ✅ Article / ⚠️ Mentioned only / ❌ Absent | [notability assessment] | +| Google Knowledge Graph API | ✅ Entity found / ❌ Not found | [entity ID, types, score] | +| Schema.org on site | ✅ Complete / ⚠️ Partial / ❌ Missing | [Organization/Person/Product schema] | + +#### AI Entity Resolution Test + +**Note**: Claude cannot directly query other AI systems or perform real-time web searches without tool access. When running without ~~AI monitor or ~~knowledge graph tools, ask the user to run these test queries and report the results, or use the user-provided information to assess entity presence. + +Test how AI systems identify this entity by querying: +- "What is [entity name]?" +- "Who founded [entity name]?" (for organizations) +- "What does [entity name] do?" +- "[entity name] vs [competitor]" + +| AI System | Recognizes Entity? | Description Accuracy | Cites Entity's Content? | +|-----------|-------------------|---------------------|------------------------| +| ChatGPT | ✅ / ⚠️ / ❌ | [accuracy notes] | [yes/no/partially] | +| Claude | ✅ / ⚠️ / ❌ | [accuracy notes] | [yes/no/partially] | +| Perplexity | ✅ / ⚠️ / ❌ | [accuracy notes] | [yes/no/partially] | +| Google AI Overview | ✅ / ⚠️ / ❌ | [accuracy notes] | [yes/no/partially] | +``` + +### Step 2: Entity Signal Audit + +Evaluate entity signals across 6 categories. For the detailed 47-signal checklist with verification methods, see [references/entity-signal-checklist.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/entity-optimizer/references/entity-signal-checklist.md). + +Evaluate each signal as Pass / Fail / Partial with a specific action for each gap. The 6 categories are: + +1. **Structured Data Signals** -- Organization/Person schema, sameAs links, @id consistency, author schema +2. **Knowledge Base Signals** -- Wikidata, Wikipedia, CrunchBase, industry directories +3. **Consistent NAP+E Signals** -- Name/description/logo/social consistency across platforms +4. **Content-Based Entity Signals** -- About page, author pages, topical authority, branded backlinks +5. **Third-Party Entity Signals** -- Authoritative mentions, co-citation, reviews, press coverage +6. **AI-Specific Entity Signals** -- Clear definitions, disambiguation, verifiable claims, crawlability + +> **Reference**: Use the audit template in [references/entity-signal-checklist.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/entity-optimizer/references/entity-signal-checklist.md) for the full 47-signal checklist with verification methods for each category. + +### Step 3: Report & Action Plan + +```markdown +## Entity Optimization Report + +### Overview + +- **Entity**: [name] +- **Entity Type**: [type] +- **Audit Date**: [date] + +### Signal Category Summary + +| Category | Status | Key Findings | +|----------|--------|-------------| +| Structured Data | ✅ Strong / ⚠️ Gaps / ❌ Missing | [key findings] | +| Knowledge Base | ✅ Strong / ⚠️ Gaps / ❌ Missing | [key findings] | +| Consistency (NAP+E) | ✅ Strong / ⚠️ Gaps / ❌ Missing | [key findings] | +| Content-Based | ✅ Strong / ⚠️ Gaps / ❌ Missing | [key findings] | +| Third-Party | ✅ Strong / ⚠️ Gaps / ❌ Missing | [key findings] | +| AI-Specific | ✅ Strong / ⚠️ Gaps / ❌ Missing | [key findings] | + +### Critical Issues + +[List any issues that severely impact entity recognition — disambiguation problems, incorrect Knowledge Panel, missing from Knowledge Graph entirely] + +### Top 5 Priority Actions + +Sorted by: impact on entity recognition × effort required + +1. **[Signal]** — [specific action] + - Impact: [High/Medium] | Effort: [Low/Medium/High] + - Why: [explanation of how this improves entity recognition] + +2. **[Signal]** — [specific action] + - Impact: [High/Medium] | Effort: [Low/Medium/High] + - Why: [explanation] + +3–5. [Same format] + +### Entity Building Roadmap + +#### Week 1-2: Foundation (Structured Data + Consistency) +- [ ] Implement/fix Organization or Person schema with full properties +- [ ] Add sameAs links to all authoritative profiles +- [ ] Audit and fix NAP+E consistency across all platforms +- [ ] Ensure About page is entity-rich and well-structured + +#### Month 1: Knowledge Bases +- [ ] Create or update Wikidata entry with complete properties +- [ ] Ensure CrunchBase / industry directory profiles are complete +- [ ] Build Wikipedia notability (or plan path to notability) +- [ ] Submit to relevant authoritative directories + +#### Month 2-3: Authority Building +- [ ] Secure mentions on authoritative industry sites +- [ ] Build co-citation signals with established entities +- [ ] Create topical content clusters that reinforce entity-topic associations +- [ ] Pursue PR opportunities that generate entity mentions + +#### Ongoing: AI-Specific Optimization +- [ ] Test AI entity resolution quarterly +- [ ] Update factual claims to remain current and verifiable +- [ ] Monitor AI systems for incorrect entity information +- [ ] Ensure new content reinforces entity identity signals + +### Cross-Reference + +- **CORE-EEAT relevance**: Items A07 (Knowledge Graph Presence) and A08 (Entity Consistency) directly overlap — entity optimization strengthens Authority dimension +- **CITE relevance**: CITE I01-I10 (Identity dimension) measures entity signals at domain level — entity optimization feeds these scores +- For content-level audit: `content-quality-auditor` +- For domain-level audit: `domain-authority-auditor` +``` + +### Save Results + +After delivering findings to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to the appropriate `memory/` path using filename `YYYY-MM-DD-.md` containing: +- One-line verdict or headline finding +- Top 3-5 actionable items +- Open loops or blockers +- Source data references + +If any veto-level issue was found (CORE-EEAT T04, C01, R10 or CITE T03, T05, T09), also append a one-liner to `memory/hot-cache.md` without asking. + +## Validation Checkpoints + +### Input Validation +- [ ] Entity name and type identified +- [ ] Primary domain/website confirmed +- [ ] Target topics/industries specified +- [ ] Disambiguation context provided (if entity name is common) + +### Output Validation +- [ ] All 6 signal categories evaluated +- [ ] AI entity resolution tested with at least 3 queries +- [ ] Knowledge Panel status checked +- [ ] Wikidata/Wikipedia status verified +- [ ] Schema.org markup on primary site audited +- [ ] Every recommendation is specific and actionable +- [ ] Roadmap includes concrete steps with timeframes +- [ ] Cross-reference with CORE-EEAT A07/A08 and CITE I01-I10 noted + +## Example + +> **Reference**: See [references/example-audit-report.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/entity-optimizer/references/example-audit-report.md) for a complete example entity audit report for a B2B SaaS company (CloudMetrics), including AI entity resolution test results, entity health summary, top 3 priority actions, and CORE-EEAT/CITE cross-references. + +## Tips for Success + +1. **Start with Wikidata** — It's the single most influential editable knowledge base; a complete Wikidata entry with references often triggers Knowledge Panel creation within weeks +2. **sameAs is your most powerful Schema.org property** — It directly tells search engines "I am this entity in the Knowledge Graph"; always include Wikidata URL first +3. **Test AI recognition before and after** — Query ChatGPT, Claude, Perplexity, and Google AI Overview before optimizing, then again after; this is the most direct GEO metric +4. **Entity signals compound** — Unlike content SEO, entity signals from different sources reinforce each other; 5 weak signals together are stronger than 1 strong signal alone +5. **Consistency beats completeness** — A consistent entity name and description across 10 platforms beats a perfect profile on just 2 +6. **Don't neglect disambiguation** — If your entity name is shared with anything else, disambiguation is the first priority; all other signals are wasted if they're attributed to the wrong entity +7. **Pair with CITE I-dimension for domain context** — Entity audit tells you how well the entity is recognized; CITE Identity (I01-I10) tells you how well the domain represents that entity; use both together + +## Entity Type Reference + +> **Reference**: See [references/entity-type-reference.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/entity-optimizer/references/entity-type-reference.md) for entity types with key signals, schemas, and disambiguation strategies by situation. + +## Knowledge Panel & Wikidata Optimization + +> **Reference**: See [references/knowledge-panel-wikidata-guide.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/entity-optimizer/references/knowledge-panel-wikidata-guide.md) for Knowledge Panel claiming/editing, common issues and fixes, Wikidata entry creation, key properties by entity type, and AI entity resolution optimization. + +## Reference Materials + +Detailed guides for entity optimization: +- [references/entity-signal-checklist.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/entity-optimizer/references/entity-signal-checklist.md) — Complete signal checklist with verification methods +- [references/knowledge-graph-guide.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/entity-optimizer/references/knowledge-graph-guide.md) — Wikidata, Wikipedia, and Knowledge Graph optimization playbook + +## Next Best Skill + +- **Primary**: [schema-markup-generator](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/schema-markup-generator/SKILL.md) — turn entity truth into machine-readable implementation. diff --git a/.cursor/skills/entity-optimizer/references/entity-signal-checklist.md b/.cursor/skills/entity-optimizer/references/entity-signal-checklist.md new file mode 100644 index 0000000000..b6b772fe59 --- /dev/null +++ b/.cursor/skills/entity-optimizer/references/entity-signal-checklist.md @@ -0,0 +1,137 @@ +# Entity Signal Checklist + +> Part of [entity-optimizer](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/entity-optimizer/SKILL.md). See also: [knowledge-graph-guide.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/entity-optimizer/references/knowledge-graph-guide.md) + +Complete checklist of entity signals organized by priority and verification method. Use this as a systematic audit guide — work through each signal, verify its status, and note actions needed. + +## Priority 1: Foundation Signals (Must-Have) + +These signals form the minimum viable entity identity. Without them, search engines and AI systems cannot reliably identify the entity. + +### On-Site Structured Data + +| # | Signal | Verification Method | Pass Criteria | +|---|--------|-------------------|---------------| +| 1 | Organization or Person schema on homepage | Run Google Rich Results Test on homepage | Schema present with name, url, logo, description | +| 2 | sameAs property links to all authoritative profiles | Inspect schema markup | Links to Wikipedia, Wikidata, LinkedIn, social profiles | +| 3 | Consistent @id used across all pages | Inspect schema on 5+ pages | Same @id (typically homepage URL + #organization) on every page | +| 4 | About page exists with entity-rich content | Manual review | First paragraph defines entity clearly; includes founding date, key people, mission | +| 5 | Contact page with verifiable information | Manual review | Physical address, phone, email — matches other directory listings | + +### Key External Profiles + +| # | Signal | Verification Method | Pass Criteria | +|---|--------|-------------------|---------------| +| 6 | Wikidata entry exists | Search wikidata.org | Entry with label, description, key properties, and references | +| 7 | Google Business Profile (if applicable) | Search "[entity] Google Business" | Claimed, verified, complete profile | +| 8 | LinkedIn company/person page | Search LinkedIn | Complete profile matching entity name and description | +| 9 | CrunchBase profile (for companies/products) | Search crunchbase.com | Entry with description, founding info, key people | +| 10 | Primary industry directory listing | Search top 3 industry directories | Listed with correct entity information | + +### Branded Search Presence + +| # | Signal | Verification Method | Pass Criteria | +|---|--------|-------------------|---------------| +| 11 | Branded search returns correct entity | Google "[entity name]" | Entity's website is #1; Knowledge Panel appears or SERP clearly identifies entity | +| 12 | No disambiguation confusion | Google "[entity name]" | No other prominent entity dominates results for the same name | +| 13 | Branded search volume exists | Check ~~SEO tool | Measurable branded search volume (any amount > 0) | + +## Priority 2: Authority Signals (Should-Have) + +These signals establish the entity as recognized and authoritative. They separate a "registered entity" from a "known entity." + +### Knowledge Graph Depth + +| # | Signal | Verification Method | Pass Criteria | +|---|--------|-------------------|---------------| +| 14 | Google Knowledge Panel present | Google "[entity name]" | Knowledge Panel displayed with correct information | +| 15 | Knowledge Panel attributes complete | Review Knowledge Panel | Key attributes filled (founded, CEO, location, industry, etc.) | +| 16 | Knowledge Panel image correct | Review Knowledge Panel | Preferred image displayed | +| 17 | Wikipedia article (or strong notability path) | Search Wikipedia | Article exists, or entity has 3+ independent reliable sources for future article | +| 18 | Wikidata properties complete | Review Wikidata entry | 10+ properties with references | + +### Third-Party Validation + +| # | Signal | Verification Method | Pass Criteria | +|---|--------|-------------------|---------------| +| 19 | Authoritative media mentions | Google News search for entity | 3+ mentions in recognized publications | +| 20 | Industry awards or recognitions | Search "[entity] award" | At least 1 verifiable award or recognition | +| 21 | Co-citation with established entities | Search for entity alongside competitors | Appears in "X vs Y" comparisons, listicles, or industry roundups | +| 22 | Speaking engagements or publications | Search event/conference sites | Appears as speaker, author, or contributor | +| 23 | Reviews on third-party platforms | Check G2, Trustpilot, Yelp, etc. | Reviews exist with reasonable volume and rating | + +### Content Authority + +| # | Signal | Verification Method | Pass Criteria | +|---|--------|-------------------|---------------| +| 24 | Topical content depth in target areas | Site search for target topics | 10+ pages covering target topics in depth | +| 25 | Author pages with credentials | Review author pages | Author schema, credentials, sameAs to external profiles | +| 26 | Original research or data published | Review content | At least 1 piece of original data/research cited by others | +| 27 | Entity mentioned in own content naturally | Search site for entity name | Entity name appears contextually (not just in header/footer) | + +## Priority 3: AI-Specific Signals (Must-Have for GEO) + +These signals specifically help AI systems recognize, understand, and cite the entity. + +### AI Recognition + +| # | Signal | Verification Method | Pass Criteria | +|---|--------|-------------------|---------------| +| 28 | ChatGPT recognizes entity | Ask "What is [entity]?" | Correct description returned | +| 29 | Perplexity recognizes entity | Ask "What is [entity]?" | Correct description with source citations | +| 30 | Google AI Overview mentions entity | Search branded + topical queries | Entity appears in AI-generated overview | +| 31 | AI description is accurate | Compare AI output to entity's self-description | No factual errors in AI's response | +| 32 | AI associates entity with correct topics | Ask "[entity] expertise areas" | Correct topic associations returned | + +### AI Optimization + +| # | Signal | Verification Method | Pass Criteria | +|---|--------|-------------------|---------------| +| 33 | Entity definition quotable in first paragraph | Review About page and key pages | Clear, factual, self-contained definition suitable for AI quotation | +| 34 | Factual claims are verifiable | Cross-reference claims with external sources | All claims about entity can be verified via third-party sources | +| 35 | Entity name used consistently | Audit all platforms | Identical name format everywhere (no abbreviations in some places, full name in others) | +| 36 | Content is crawlable by AI systems | Check robots.txt for AI bot access | Not blocking GPTBot, ClaudeBot, or other AI crawlers (unless intentional) | +| 37 | Fresh information available | Check update dates | Key entity pages updated within last 6 months | + +## Priority 4: Advanced Signals (Nice-to-Have) + +These signals provide marginal gains but demonstrate thoroughness and maturity. + +### Extended Knowledge Base Presence + +| # | Signal | Verification Method | Pass Criteria | +|---|--------|-------------------|---------------| +| 38 | Multiple language entries in Wikidata | Check Wikidata labels | Labels and descriptions in languages matching target markets | +| 39 | DBpedia entry | Search dbpedia.org | Entry exists (auto-generated from Wikipedia) | +| 40 | Google Knowledge Graph ID known | Search Google Knowledge Graph API | Entity has a kg: identifier | +| 41 | ISNI or VIAF identifier (for persons) | Search isni.org or viaf.org | Identifier exists and links correctly | + +### Social Entity Signals + +| # | Signal | Verification Method | Pass Criteria | +|---|--------|-------------------|---------------| +| 42 | Social profiles bidirectionally linked | Check website links to social AND social links to website | Both directions verified on all platforms | +| 43 | Consistent entity description across social | Compare bios on all platforms | Same core description, adapted for platform length limits | +| 44 | Social engagement demonstrates real audience | Review engagement metrics | Engagement patterns consistent with genuine audience (not bot-like) | + +### Technical Entity Signals + +| # | Signal | Verification Method | Pass Criteria | +|---|--------|-------------------|---------------| +| 45 | Entity homepage has strong backlink profile | Check ~~link database | Homepage DR/DA above industry median | +| 46 | Branded anchor text in backlinks | Analyze anchor text distribution | Entity name appears naturally in inbound link anchor text | +| 47 | Entity subdomain consistency | Check all subdomains | Same entity schema and branding across all subdomains | + +## How to Use This Checklist + +Work through signals by priority tier. For each signal, mark status as ✅ (present and correct), ⚠️ (present but incomplete), or ❌ (absent). Focus on completing each priority tier before moving to the next. + +### Priority Action Matrix + +| Current State | Focus Area | Expected Timeline | +|--------------|-----------|-------------------| +| Most Priority 1 signals ❌ | Priority 1 foundation signals only | 2-4 weeks | +| Priority 1 mostly ✅, Priority 2 mixed | Priority 2 authority signals | 1-2 months | +| Priority 1-2 mostly ✅ | Priority 3 AI-specific signals | 2-3 months | +| Priority 1-3 mostly ✅ | Selective Priority 4 for completeness | Ongoing | +| All tiers mostly ✅ | Maintenance + quarterly re-audit | Quarterly review | diff --git a/.cursor/skills/entity-optimizer/references/entity-type-reference.md b/.cursor/skills/entity-optimizer/references/entity-type-reference.md new file mode 100644 index 0000000000..1bffe7d948 --- /dev/null +++ b/.cursor/skills/entity-optimizer/references/entity-type-reference.md @@ -0,0 +1,24 @@ +# Entity Type Reference + +Reference tables for entity types, key signals, and disambiguation strategies. + +## Entity Types and Key Signals + +| Entity Type | Primary Signals | Secondary Signals | Key Schema | +|-------------|----------------|-------------------|------------| +| **Person** | Author pages, social profiles, publication history | Speaking, awards, media mentions | Person, ProfilePage | +| **Organization** | Registration records, Wikidata, industry listings | Press coverage, partnerships, awards | Organization, Corporation | +| **Brand** | Trademark, branded search volume, social presence | Reviews, brand mentions, visual identity | Brand, Organization | +| **Product** | Product pages, reviews, comparison mentions | Awards, expert endorsements, market share | Product, SoftwareApplication | +| **Creative Work** | Publication record, citations, reviews | Awards, adaptations, cultural impact | CreativeWork, Book, Movie | +| **Event** | Event listings, press coverage, social buzz | Sponsorships, speaker profiles, attendance | Event | + +## Disambiguation Strategy by Situation + +| Situation | Strategy | +|-----------|----------| +| **Common name, unique entity** | Strengthen all signals; let signal volume resolve ambiguity | +| **Name collision with larger entity** | Add qualifier consistently (e.g., "Acme Software" not just "Acme"); use sameAs extensively; build topic-specific authority that differentiates | +| **Name collision with similar entity** | Geographic, industry, or product qualifiers; ensure Schema @id is unique and consistent; prioritize Wikidata disambiguation | +| **Abbreviation/acronym conflict** | Prefer full name in structured data; use abbreviation only in contexts where entity is already established | +| **Merged or renamed entity** | Redirect old entity signals; update all structured data; create explicit "formerly known as" content; update Wikidata | diff --git a/.cursor/skills/entity-optimizer/references/example-audit-report.md b/.cursor/skills/entity-optimizer/references/example-audit-report.md new file mode 100644 index 0000000000..dc3648167f --- /dev/null +++ b/.cursor/skills/entity-optimizer/references/example-audit-report.md @@ -0,0 +1,59 @@ +# Example: Entity Optimization Report + +Full example output for an entity audit request. + +**User**: "Audit entity presence for CloudMetrics, our B2B SaaS analytics platform at cloudmetrics.io" + +**Output**: + +```markdown +## Entity Optimization Report + +### Entity Profile + +**Entity Name**: CloudMetrics +**Entity Type**: Organization (B2B SaaS) +**Primary Domain**: cloudmetrics.io +**Target Topics**: analytics platform, business intelligence, enterprise analytics + +### AI Entity Resolution Test + +Queries tested with results reported by user: + +| Query | Result | Assessment | +|-------|--------|------------| +| "What is CloudMetrics?" | Described as "an analytics tool" with no further detail | Partial recognition -- generic description, no mention of B2B focus or key features | +| "Best analytics platforms for enterprises" | CloudMetrics not mentioned in any AI response | Not recognized as a player in the enterprise analytics space | +| "CloudMetrics vs Datadog" | Correctly identified as a competitor to Datadog, but feature comparison was incomplete and partially inaccurate | Partial -- entity is associated with the right category but attributes are thin | +| "Who founded CloudMetrics?" | No answer found by any AI system tested | Entity leadership not present in AI knowledge bases | + +### Entity Health Summary + +| Signal Category | Status | Key Findings | +|-----------------|--------|--------------| +| Knowledge Graph | Missing | No Wikidata entry exists; no Google Knowledge Panel triggers for branded queries | +| Structured Data | Partial | Organization schema present on homepage with name, url, and logo; missing Person schema for CEO and leadership team; no sameAs links to external profiles | +| Web Presence | Strong | Consistent NAP across LinkedIn, Twitter/X, G2, and Crunchbase; social profiles link back to cloudmetrics.io; branded search returns owned properties in top 5 | +| Content-Based | Partial | About page exists but opens with marketing copy rather than an entity-defining statement; no dedicated author pages for leadership | +| Third-Party | Partial | Listed on G2 and Crunchbase; 2 industry publication mentions found; no awards or analyst coverage | +| AI-Specific | Weak | AI systems have only surface-level awareness; entity definition is not quotable from any authoritative source | + +### Top 3 Priority Actions + +1. **Create Wikidata entry** with key properties: instance of (P31: business intelligence software company), official website (P856: cloudmetrics.io), inception (P571), country (P17) + - Impact: High | Effort: Low + - Why: Wikidata is the foundational knowledge base that feeds Google Knowledge Graph, Bing, and AI training pipelines; without it, the entity cannot be formally resolved + +2. **Add Person schema for leadership team** on the About/Team page, including name, jobTitle, sameAs links to LinkedIn profiles, and worksFor pointing to the Organization entity + - Impact: High | Effort: Low + - Why: Addresses the "Who founded CloudMetrics?" gap directly; Person schema for key people creates bidirectional entity associations that strengthen organizational identity + +3. **Build Wikipedia notability through independent press coverage** -- target 3-5 articles in industry publications (TechCrunch, VentureBeat, Analytics India Magazine) that mention CloudMetrics by name with verifiable claims + - Impact: High | Effort: High + - Why: Wikipedia notability requires coverage in independent reliable sources; press mentions simultaneously feed AI training data, build third-party entity signals, and create the citation foundation for a future Wikipedia article + +### Cross-Reference + +- **CORE-EEAT**: A07 (Knowledge Graph Presence) scored Fail, A08 (Entity Consistency) scored Pass -- entity optimization should focus on knowledge base gaps rather than consistency +- **CITE**: I-dimension weakest area is I01 (Knowledge Graph Presence) -- completing Wikidata entry and earning Knowledge Panel directly improves domain identity score +``` diff --git a/.cursor/skills/entity-optimizer/references/knowledge-graph-guide.md b/.cursor/skills/entity-optimizer/references/knowledge-graph-guide.md new file mode 100644 index 0000000000..ed7ad0aeb4 --- /dev/null +++ b/.cursor/skills/entity-optimizer/references/knowledge-graph-guide.md @@ -0,0 +1,399 @@ +# Knowledge Graph Optimization Guide + +> Part of [entity-optimizer](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/entity-optimizer/SKILL.md). See also: [entity-signal-checklist.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/entity-optimizer/references/entity-signal-checklist.md) + +Comprehensive playbook for establishing and maintaining entity presence across Google Knowledge Graph, Wikidata, Wikipedia, and other knowledge bases. + +## How Knowledge Graphs Work + +### The Entity Web + +Knowledge graphs are interconnected databases of entities and their relationships. Search engines and AI systems use them as ground truth for entity understanding. + +``` +Your Entity +├── is described by → Wikidata entry +├── is described by → Wikipedia article +├── is described by → Schema.org markup on your site +├── is linked to → Social profiles (LinkedIn, X, etc.) +├── is mentioned by → News articles, industry sites +├── is associated with → Topics, industries, other entities +└── is recognized by → Google Knowledge Graph, Bing Satori, AI training data +``` + +### Which Knowledge Graphs Matter + +| Knowledge Graph | Who Uses It | Impact | +|----------------|-------------|--------| +| **Google Knowledge Graph** | Google Search, Google AI | Powers Knowledge Panels, rich results, entity understanding in search | +| **Wikidata** | Google, Bing, Apple, Amazon, AI systems | Open data feeds multiple knowledge graphs; primary structured data source | +| **Wikipedia** | Google, all AI systems | Training data for every major LLM; Knowledge Panel descriptions often sourced here | +| **Bing Satori** | Bing, Copilot | Powers Bing's entity understanding and Microsoft Copilot | +| **Schema.org (your site)** | All search engines, AI crawlers | First-party structured data you control directly | +| **DBpedia** | Research, some AI systems | Auto-extracted from Wikipedia; relevant for academic/research entities | + +### Data Flow + +``` +Your Website (Schema.org) ─┐ +Wikidata ──────────────────┤ +Wikipedia ─────────────────┼──→ Google Knowledge Graph ──→ Knowledge Panel +Industry Directories ──────┤ AI Search Results +News/Media Mentions ───────┤ Rich Results +Social Profiles ───────────┘ +``` + +Understanding this flow is key: you influence the Knowledge Graph by controlling the **source signals** that feed it. + +## Google Knowledge Graph + +### Getting Into the Knowledge Graph + +There is no "submit to Knowledge Graph" form. Google builds its Knowledge Graph from multiple sources. To get included: + +1. **Have a Wikidata entry** — This is the most direct path +2. **Earn a Wikipedia article** — Strongest single signal +3. **Implement Schema.org markup** — Provides structured self-description +4. **Get mentioned on authoritative sites** — Third-party validation +5. **Build branded search demand** — Signals that users look for your entity + +### Checking Your Knowledge Graph Status + +**Method 1: Google Search** +Search for your entity name in quotes. If a Knowledge Panel appears on the right, you're in the Knowledge Graph. + +**Method 2: Knowledge Graph API** +``` +GET https://kgsearch.googleapis.com/v1/entities:search?query=[entity]&key=[API_KEY] +``` + +Response includes: +- `@id`: Your Knowledge Graph ID (e.g., `kg:/m/0wrt4g`) +- `name`: Entity name as Google understands it +- `description`: Short entity description +- `detailedDescription`: Longer description (usually from Wikipedia) +- `resultScore`: Confidence score (higher = more established entity) + +**Method 3: ~~knowledge graph** +If connected, query directly for entity status and attributes. + +### Claiming Your Knowledge Panel + +1. Search for your entity on Google +2. If Knowledge Panel appears, look for "Claim this knowledge panel" link at bottom +3. Verify via official website, Search Console, YouTube, or other Google property +4. Once claimed, you can suggest edits (but Google has final say) + +### Common Knowledge Panel Fixes + +| Problem | Solution | +|---------|----------| +| **No Knowledge Panel** | Build Wikidata entry + Schema.org + authoritative mentions. Timeline: 2-6 months. | +| **Wrong image** | Update preferred image on: Wikidata (P18), About page, social profiles. Claim panel and suggest preferred image. | +| **Wrong description** | Edit Wikidata description. Update first paragraph of About page and Wikipedia article. | +| **Missing attributes** | Add properties to Wikidata and Schema.org. Claim panel and suggest additions. | +| **Outdated information** | Update Wikidata, About page, Wikipedia, and social profiles. Request refresh via claimed panel. | +| **Wrong entity shown** | Disambiguation needed. See Wikidata section below for disambiguation strategy. | + +## Wikidata + +### Why Wikidata Is Critical + +Wikidata is the **single most influential editable knowledge base** for entity optimization: +- Google uses it as a primary source for Knowledge Panels +- Bing uses it for Satori knowledge graph +- AI systems reference it during entity resolution +- It's open and you can edit it (within their guidelines) + +### Creating a Wikidata Entry + +#### Step 1: Check Eligibility + +Wikidata requires "notability" — the entity must be referenced in at least one external source. Unlike Wikipedia, the notability bar is lower: a company mentioned in a news article, a product with reviews, or a person with published work typically qualifies. + +#### Step 2: Create the Item + +1. Go to https://www.wikidata.org/wiki/Special:NewItem +2. Fill in: + - **Label**: Official entity name + - **Description**: Short description (e.g., "American software company" or "SEO optimization tool") + - **Aliases**: Alternative names, abbreviations, former names + +#### Step 3: Add Core Statements + +Essential properties for each entity type: + +**Organizations:** +| Property | Code | Example | +|----------|------|---------| +| instance of | P31 | business (Q4830453) or specific type | +| official website | P856 | https://example.com | +| inception | P571 | 2020-01-15 | +| country | P17 | United States (Q30) | +| headquarters location | P159 | San Francisco (Q62) | +| industry | P452 | software industry (Q638608) | +| founded by | P112 | [founder's Wikidata item] | +| CEO | P169 | [CEO's Wikidata item] | + +**Persons:** +| Property | Code | Example | +|----------|------|---------| +| instance of | P31 | human (Q5) | +| occupation | P106 | software engineer (Q183888) | +| employer | P108 | [company Wikidata item] | +| educated at | P69 | [university Wikidata item] | +| country of citizenship | P27 | [country item] | +| official website | P856 | https://example.com | + +**Products/Software:** +| Property | Code | Example | +|----------|------|---------| +| instance of | P31 | software (Q7397) or web application (Q189210) | +| developer | P178 | [company Wikidata item] | +| official website | P856 | https://example.com | +| programming language | P277 | Python (Q28865) | +| operating system | P306 | Linux (Q388) | +| software license | P275 | Apache-2.0 (Q13785927) | +| inception | P571 | 2023-06-01 | + +#### Step 4: Add External Identifiers + +These link your Wikidata item to other knowledge bases: + +| Identifier | Code | Purpose | +|-----------|------|---------| +| official website | P856 | Primary web presence | +| X (Twitter) username | P2002 | Social presence | +| LinkedIn organization ID | P4264 | Professional presence | +| GitHub username | P2037 | Technical presence | +| CrunchBase ID | P2087 | Business data | +| Google Knowledge Graph ID | P2671 | Google entity link | +| App Store ID | P3861 | Mobile presence | + +#### Step 5: Add References + +**Every statement must have a reference.** Unreferenced statements may be removed. + +Good reference sources: +- Official website (for factual claims like founding date) +- News articles (for events, milestones) +- Industry reports (for market position) +- Government registries (for legal entity information) + +### Wikidata Maintenance + +| Task | Frequency | Why | +|------|-----------|-----| +| Review existing statements | Quarterly | Ensure accuracy; update changed information | +| Add new properties | When new information available | Keep entry comprehensive | +| Check for vandalism | Monthly | Others can edit your entry | +| Add new references | When new coverage appears | Strengthen statement credibility | +| Update identifiers | When new profiles created | Keep links current | + +## Wikipedia + +### Notability Requirements + +Wikipedia requires entities to meet "general notability guidelines" (GNG): +- **Significant coverage** in **reliable, independent sources** +- Coverage must be **non-trivial** (not just a mention or directory listing) +- Sources must be **independent** of the entity (not press releases, not entity's own content) + +### Building Toward Notability + +If the entity doesn't have a Wikipedia article yet: + +1. **Audit existing coverage**: Search Google News, academic databases, and industry publications for mentions +2. **Identify gaps**: What kinds of coverage are missing? +3. **Build coverage first, then article**: The article is the last step, not the first + +Coverage-building strategies: +| Strategy | Timeline | Notability Impact | +|----------|----------|-------------------| +| Industry report mentions | 3-6 months | Medium — depends on report authority | +| News article coverage | 1-3 months | High — especially from recognized publications | +| Conference speaking + coverage | 3-12 months | Medium — needs post-event coverage | +| Academic paper citations | 6-12+ months | High — very strong for GNG | +| Award recognition | Variable | Medium — depends on award authority | +| Book publication or feature | 6-12+ months | High — strong independent source | + +### Wikipedia Article Best Practices + +**DO:** +- Write in neutral, encyclopedic tone +- Use only independent, reliable sources as references +- Follow Wikipedia's Manual of Style +- Disclose any conflict of interest on your Talk page +- Let the community review and improve the article + +**DO NOT:** +- Write promotional content +- Use the entity's own website as a primary source +- Create the article from a company account without disclosure +- Remove criticism or negative but sourced information +- Pay someone to write the article without disclosure (violates Wikipedia policy) + +### Wikipedia's Impact on AI + +Wikipedia is disproportionately important for AI systems because: +- It's in the training data of every major LLM +- AI systems treat it as a high-trust source +- Wikipedia's structured format makes it easy for AI to extract and cite +- The first paragraph of a Wikipedia article often becomes the AI's entity definition + +This makes Wikipedia presence one of the highest-impact entity optimization actions for GEO. + +## Schema.org Entity Markup + +### Minimum Viable Entity Schema + +Every entity should have at minimum this markup on the homepage: + +**Organization:** +```json +{ + "@context": "https://schema.org", + "@type": "Organization", + "@id": "https://example.com/#organization", + "name": "Example Corp", + "url": "https://example.com", + "logo": "https://example.com/logo.png", + "description": "Example Corp is a [what it is] that [what it does].", + "foundingDate": "2020-01-15", + "founder": { + "@type": "Person", + "name": "Jane Smith", + "@id": "https://example.com/about/jane-smith#person" + }, + "sameAs": [ + "https://www.wikidata.org/wiki/Q12345678", + "https://en.wikipedia.org/wiki/Example_Corp", + "https://www.linkedin.com/company/example-corp", + "https://x.com/examplecorp", + "https://www.crunchbase.com/organization/example-corp" + ] +} +``` + +**Person:** +```json +{ + "@context": "https://schema.org", + "@type": "Person", + "@id": "https://example.com/about/jane-smith#person", + "name": "Jane Smith", + "url": "https://example.com/about/jane-smith", + "image": "https://example.com/photos/jane-smith.jpg", + "jobTitle": "CEO", + "worksFor": { + "@type": "Organization", + "@id": "https://example.com/#organization" + }, + "description": "Jane Smith is [who they are] specializing in [expertise areas].", + "sameAs": [ + "https://www.wikidata.org/wiki/Q87654321", + "https://www.linkedin.com/in/janesmith", + "https://x.com/janesmith" + ] +} +``` + +### sameAs Best Practices + +The `sameAs` property is the **primary entity disambiguation signal** in Schema.org. It tells search engines "this is the same entity as the one on these other platforms." + +**Must include (when available):** +1. Wikidata URL (most important for Knowledge Graph) +2. Wikipedia URL +3. LinkedIn URL +4. Official social media profiles + +**Include when relevant:** +5. CrunchBase URL +6. GitHub URL +7. IMDb URL (for people in entertainment) +8. Industry directory URLs + +**Common mistakes:** +- Linking to generic pages instead of entity-specific URLs +- Inconsistent: Schema says "Example Corp" but LinkedIn says "Example Corporation" +- Missing Wikidata link (this is the single most impactful sameAs) +- Including dead or redirecting URLs + +### Cross-Page Entity Consistency + +Every page on the site should reference the same entity with the same `@id`: + +```json +{ + "@type": "WebPage", + "publisher": { + "@type": "Organization", + "@id": "https://example.com/#organization" + } +} +``` + +For articles: +```json +{ + "@type": "Article", + "author": { + "@type": "Person", + "@id": "https://example.com/about/jane-smith#person" + }, + "publisher": { + "@type": "Organization", + "@id": "https://example.com/#organization" + } +} +``` + +This creates a consistent entity graph that search engines can confidently map to Knowledge Graph entries. + +## Monitoring Entity Health + +### Quarterly Entity Health Check + +| Check | How | What to Look For | +|-------|-----|-----------------| +| Knowledge Panel accuracy | Google entity name | Correct info, image, attributes | +| Wikidata entry | Visit Wikidata page | No vandalism, info still current | +| AI entity resolution | Query 3+ AI systems | Accurate recognition and description | +| Schema.org validation | Google Rich Results Test | No errors, complete entity data | +| Branded search SERP | Google "[entity name]" | Clean SERP, no disambiguation issues | +| Social profile consistency | Visit all profiles | Same name, description, links | + +### Entity Health Metrics to Track + +| Metric | Tool | Target | +|--------|------|--------| +| Knowledge Panel presence | Google Search | Present and accurate | +| Branded search CTR | ~~search console | > 50% for exact brand name | +| AI recognition rate | Manual testing | Recognized by 3/3 major AI systems | +| Wikidata completeness | Wikidata | 15+ properties with references | +| Schema.org error count | Google Search Console | 0 errors | +| Brand mention volume | ~~brand monitor | Stable or growing trend | + +### Recovery Playbooks + +**Entity disappeared from Knowledge Graph:** +1. Check if Wikidata entry was deleted or merged +2. Verify Schema.org markup hasn't changed +3. Look for major algorithm updates that might have affected entity recognition +4. Rebuild signals: start with Wikidata, then Schema.org, then external mentions +5. Timeline: 2-8 weeks for recovery + +**AI systems giving incorrect entity info:** +1. Identify which sources have incorrect information +2. Correct information at source (Wikidata, Wikipedia, About page) +3. AI systems will update over time (training data refresh + live search) +4. For urgent issues, some AI systems have feedback mechanisms +5. Timeline: weeks to months depending on AI system update cycles + +**Knowledge Panel showing wrong entity:** +1. Claim the Knowledge Panel (if you haven't already) +2. Strengthen disambiguation signals (see SKILL.md Disambiguation Strategy) +3. Add qualifier to entity name if needed +4. Build more unique entity signals (original content, specific topic associations) +5. Timeline: 1-3 months diff --git a/.cursor/skills/entity-optimizer/references/knowledge-panel-wikidata-guide.md b/.cursor/skills/entity-optimizer/references/knowledge-panel-wikidata-guide.md new file mode 100644 index 0000000000..b718f4ef88 --- /dev/null +++ b/.cursor/skills/entity-optimizer/references/knowledge-panel-wikidata-guide.md @@ -0,0 +1,81 @@ +# Knowledge Panel & Wikidata Optimization Guide + +Detailed instructions for Knowledge Panel optimization, Wikidata entry management, and AI entity resolution. + +## Knowledge Panel Optimization + +### Claiming and Editing + +1. **Google Knowledge Panel**: Claim via Google's verification process (search for entity -> click "Claim this knowledge panel") +2. **Bing Knowledge Panel**: Driven by Wikidata and LinkedIn -- update those sources +3. **AI Knowledge**: Driven by training data -- ensure authoritative sources describe entity correctly + +### Common Knowledge Panel Issues + +| Issue | Root Cause | Fix | +|-------|-----------|-----| +| No panel appears | Entity not in Knowledge Graph | Build Wikidata entry + structured data + authoritative mentions | +| Wrong image | Image sourced from incorrect page | Update Wikidata image; ensure preferred image on About page and social profiles | +| Wrong description | Description pulled from wrong source | Edit Wikidata description; ensure About page has clear entity description in first paragraph | +| Missing attributes | Incomplete structured data | Add properties to Schema.org markup and Wikidata entry | +| Wrong entity shown | Disambiguation failure | Strengthen unique signals; add qualifiers; resolve Wikidata disambiguation | +| Outdated info | Source data not updated | Update Wikidata, About page, and all profile pages | + +## Wikidata Best Practices + +### Creating a Wikidata Entry + +1. **Check notability**: Entity must have at least one authoritative reference +2. **Create item**: Add label, description, and aliases in relevant languages +3. **Add statements**: instance of, official website, social media links, founding date, founders, industry +4. **Add identifiers**: official website (P856), social media IDs, CrunchBase ID, ISNI, VIAF +5. **Add references**: Every statement should have a reference to an authoritative source + +**Important**: Wikipedia's Conflict of Interest (COI) policy prohibits individuals and organizations from creating or editing articles about themselves. Instead of directly editing Wikipedia: (1) Focus on building notability through independent reliable sources (press coverage, industry publications, academic citations); (2) If you believe a Wikipedia article is warranted, consider engaging an independent Wikipedia editor through the Requested Articles process; (3) Ensure all claims about the entity are verifiable through third-party sources before any Wikipedia involvement. + +### Key Wikidata Properties by Entity Type + +| Property | Code | Person | Org | Brand | Product | +|----------|------|:------:|:---:|:-----:|:-------:| +| instance of | P31 | human | organization type | brand | product type | +| official website | P856 | yes | yes | yes | yes | +| occupation / industry | P106/P452 | yes | yes | -- | -- | +| founded by | P112 | -- | yes | yes | -- | +| inception | P571 | -- | yes | yes | yes | +| country | P17 | yes | yes | -- | -- | +| social media | various | yes | yes | yes | yes | +| employer | P108 | yes | -- | -- | -- | +| developer | P178 | -- | -- | -- | yes | + +## AI Entity Optimization + +### How AI Systems Resolve Entities + +``` +User query -> Entity extraction -> Entity resolution -> Knowledge retrieval -> Answer generation +``` + +AI systems follow this pipeline: +1. **Extract** entity mentions from the query +2. **Resolve** each mention to a known entity (or fail -> "I'm not sure") +3. **Retrieve** associated knowledge about the entity +4. **Generate** response citing sources that confirmed the entity's attributes + +### Signals AI Systems Use for Entity Resolution + +| Signal Type | What AI Checks | How to Optimize | +|-------------|---------------|-----------------| +| **Training data presence** | Was entity in pre-training corpus? | Get mentioned in high-quality, widely-crawled sources | +| **Retrieval augmentation** | Does entity appear in live search results? | Strong SEO presence for branded queries | +| **Structured data** | Can entity be matched to Knowledge Graph? | Complete Wikidata + Schema.org | +| **Contextual co-occurrence** | What topics/entities appear alongside? | Build consistent topic associations across content | +| **Source authority** | Are sources about entity trustworthy? | Get mentioned by authoritative, well-known sources | +| **Recency** | Is information current? | Keep all entity profiles and content updated | + +### Entity-Specific GEO Tactics + +1. **Define clearly**: First paragraph of About page and key pages should define the entity in a way AI can quote directly +2. **Be consistent**: Use identical entity description across all platforms +3. **Build associations**: Create content that explicitly connects entity to target topics +4. **Earn mentions**: Third-party authoritative mentions are stronger entity signals than self-description +5. **Stay current**: Outdated entity information causes AI to lose confidence and stop citing diff --git a/.cursor/skills/geo-content-optimizer/SKILL.md b/.cursor/skills/geo-content-optimizer/SKILL.md new file mode 100644 index 0000000000..5ee0a58407 --- /dev/null +++ b/.cursor/skills/geo-content-optimizer/SKILL.md @@ -0,0 +1,420 @@ +--- +name: geo-content-optimizer +description: 'Optimize content for AI citations in ChatGPT, Perplexity, AI Overviews, Gemini, Claude. AI引用优化/GEO优化/AI搜索' +version: "6.0.0" +license: Apache-2.0 +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when optimizing content for AI engines like ChatGPT, Perplexity, AI Overviews, Gemini, Claude, or Copilot. Also for AI citation optimization and generative engine visibility." +argument-hint: " [target AI engine]" +metadata: + author: aaron-he-zhu + version: "6.0.0" + geo-relevance: "high" + tags: + - geo + - ai-citations + - chatgpt-optimization + - perplexity-optimization + - google-ai-overview + - gemini + - generative-engine-optimization + - llm-citations + - ai-seo + - quotable-content + - AI引用优化 + - GEO优化 + - AI最適化 + - AI최적화 + - optimizacion-ia + triggers: + # EN-formal + - "optimize for AI" + - "get cited by ChatGPT" + - "AI optimization" + - "appear in AI answers" + - "GEO optimization" + - "generative engine optimization" + - "AI-friendly content" + - "LLM citations" + # EN-casual + - "get cited by AI" + - "show up in ChatGPT answers" + - "AI doesn't mention my brand" + - "make content AI-quotable" + - "how do I get AI to mention me" + - "ChatGPT doesn't know my brand" + # EN-question + - "how to appear in AI answers" + - "how to get cited by AI" + - "why doesn't AI mention my brand" + # EN-competitor + - "Perplexity optimization" + - "how to rank in ChatGPT answers" + - "AI Overview optimization tool" + # ZH-pro + - "AI引用优化" + - "GEO优化" + - "生成式引擎优化" + - "AI搜索优化" + - "AI可引用内容" + # ZH-casual + - "让AI引用我" + - "ChatGPT搜不到我" + - "AI不提我的品牌" + - "怎么让AI推荐我" + - "AI搜不到" + # JA + - "AIコンテンツ最適化" + - "AI引用されるコンテンツ" + - "ChatGPT対策" + - "AI検索最適化" + # KO + - "AI 최적화" + - "AI 검색 최적화" + - "ChatGPT 인용" + # ES + - "optimización para IA" + - "aparecer en respuestas de IA" + - "citación de IA" + # PT + - "otimização para IA" + - "aparecer nas respostas da IA" + # Misspellings + - "generative engine optimisation" + - "GEO optimisation" +--- + +# GEO Content Optimizer + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This build skill follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + + +This skill optimizes content to appear in AI-generated responses. As AI systems increasingly answer user queries directly, getting cited by these systems directly impacts visibility. + +**System role**: Build layer skill. It turns briefs and signals into assets that other skills can review, publish, and monitor. + +## When This Must Trigger + +Use this when the conversation involves any of these situations — even if the user does not use SEO terminology: + +Use this whenever the task needs a shippable asset or transformation that should feed directly into quality review, deployment, or monitoring. + +- Optimizing existing content for AI citations +- Creating new content designed for both SEO and GEO +- Improving chances of appearing in AI Overviews +- Making content more quotable by AI systems +- Adding authority signals that AI systems trust +- Structuring content for AI comprehension +- Competing for visibility in the AI-first search era + +## What This Skill Does + +1. **Citation Optimization**: Makes content more likely to be quoted by AI +2. **Structure Enhancement**: Formats content for AI comprehension +3. **Authority Building**: Adds signals that AI systems trust +4. **Factual Enhancement**: Improves accuracy and verifiability +5. **Quote Creation**: Creates memorable, citeable statements +6. **Source Attribution**: Adds proper citations that AI can verify +7. **GEO Scoring**: Evaluates content's AI-friendliness + +## Quick Start + +Start with one of these prompts. Finish with a short handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Optimize Existing Content + +``` +Optimize this content for GEO/AI citations: [content or URL] +``` + +``` +Make this article more likely to be cited by AI systems +``` + +### Create GEO-Optimized Content + +``` +Write content about [topic] optimized for both SEO and GEO +``` + +### GEO Audit + +``` +Audit this content for GEO readiness and suggest improvements +``` + +## Skill Contract + +**Expected output**: a ready-to-use asset or implementation-ready transformation plus a short handoff summary ready for `memory/content/`. + +- **Reads**: the brief, target keywords, entity inputs, quality constraints, and prior decisions from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available. +- **Writes**: a user-facing content, metadata, or schema deliverable plus a reusable summary that can be stored under `memory/content/`. +- **Promotes**: approved angles, messaging choices, missing evidence, and publish blockers to `CLAUDE.md`, `memory/decisions.md`, and `memory/open-loops.md`. +- **Next handoff**: use the `Next Best Skill` below when the asset is ready for review or deployment. + +## Data Sources + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +> **Note:** All integrations are optional. This skill works without any API keys — users provide data manually when no tools are connected. + +**With ~~AI monitor + ~~SEO tool connected:** +Automatically pull AI citation patterns (which content is being cited by ChatGPT, Claude, Perplexity), current AI visibility scores, competitor citation frequency, and AI Overview appearance tracking. + +**With manual data only:** +Ask the user to provide: +1. Target queries where they want AI citations +2. Current content URL or full content text +3. Any known instances where competitors are being cited by AI + +Proceed with the full workflow using provided data. Note in the output which metrics are from automated collection vs. user-provided data. + +## Instructions + +When a user requests GEO optimization: + +1. **Load CORE-EEAT GEO-First Optimization Targets** + + Before optimizing, load GEO-critical items from the [CORE-EEAT Benchmark](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/core-eeat-benchmark.md): + + ```markdown + ### CORE-EEAT GEO-First Targets + + These items have the highest impact on AI engine citation. Use as optimization checklist: + + **Top 6 Priority Items**: + | Rank | ID | Standard | Why It Matters | + |------|----|----------|---------------| + | 1 | C02 | Direct Answer in first 150 words | All engines extract from first paragraph | + | 2 | C09 | Structured FAQ with Schema | Directly matches AI follow-up queries | + | 3 | O03 | Data in tables, not prose | Most extractable structured format | + | 4 | O05 | JSON-LD Schema Markup | Helps AI understand content type | + | 5 | E01 | Original first-party data | AI prefers exclusive, verifiable sources | + | 6 | O02 | Key Takeaways / Summary Box | First choice for AI summary citations | + + **All GEO-First Items** (optimize for all when possible): + C02, C04, C05, C07, C08, C09 | O02, O03, O04, O05, O06, O09 + R01, R02, R03, R04, R05, R07, R09 | E01, E02, E03, E04, E06, E08, E09, E10 + Exp10 | Ept05, Ept08 | A08 + + **AI Engine Preferences**: + | Engine | Priority Items | + |--------|----------------| + | Google AI Overview | C02, O03, O05, C09 | + | ChatGPT Browse | C02, R01, R02, E01 | + | Perplexity AI | E01, R03, R05, Ept05 | + | Claude | R04, Ept08, Exp10, R03 | + + _Full benchmark: [references/core-eeat-benchmark.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/core-eeat-benchmark.md)_ + ``` + +2. **Analyze Current Content** + + ```markdown + ## GEO Analysis: [Content Title] + + ### Current State Assessment + + | GEO Factor | Current Score (1-10) | Notes | + |------------|---------------------|-------| + | Clear definitions | [X] | [notes] | + | Quotable statements | [X] | [notes] | + | Factual density | [X] | [notes] | + | Source citations | [X] | [notes] | + | Q&A format | [X] | [notes] | + | Authority signals | [X] | [notes] | + | Content freshness | [X] | [notes] | + | Structure clarity | [X] | [notes] | + | **GEO Readiness** | **[avg]/10** | **Average across factors** | + + **Primary Weaknesses**: + 1. [Weakness 1] + 2. [Weakness 2] + 3. [Weakness 3] + + **Quick Wins**: + 1. [Quick improvement 1] + 2. [Quick improvement 2] + ``` + +3. **Apply GEO Optimization Techniques** + + > **GEO fundamentals**: AI systems prioritize content that is authoritative (expert credentials, proper citations), accurate (verifiable, up-to-date), clear (well-structured, unambiguous), and quotable (standalone answers, specific data). See [references/geo-optimization-techniques.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/geo-content-optimizer/references/geo-optimization-techniques.md) for details. + + Apply the six core optimization techniques: definition optimization, quotable statement creation, authority signal enhancement, structure optimization, factual density improvement, and FAQ schema implementation. + + > **Reference**: See [references/geo-optimization-techniques.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/geo-content-optimizer/references/geo-optimization-techniques.md) for detailed before/after examples, templates, and checklists for each technique. + + Key principles: + - **Definitions**: 25-50 words, standalone, starting with the term + - **Quotable statements**: Specific statistics with sources, verifiable facts + - **Authority signals**: Expert quotes with credentials, proper source citations + - **Structure**: Q&A format, comparison tables, numbered lists + - **Factual density**: Replace vague claims with specific data points + - **FAQ schema**: JSON-LD FAQPage markup matching visible content + +4. **Generate GEO-Optimized Output** + + ```markdown + ## GEO Optimization Report + + ### Changes Made + + **Definitions Added/Improved**: + 1. [Definition 1] - [location in content] + 2. [Definition 2] - [location in content] + + **Quotable Statements Created**: + 1. "[Statement 1]" + 2. "[Statement 2]" + + **Authority Signals Added**: + 1. [Expert quote/citation] + 2. [Source attribution] + + **Structural Improvements**: + 1. [Change 1] + 2. [Change 2] + + ### Before/After GEO Score + + | GEO Factor | Before (1-10) | After (1-10) | Change | + |------------|---------------|--------------|--------| + | Clear definitions | [X] | [X] | +[X] | + | Quotable statements | [X] | [X] | +[X] | + | Factual density | [X] | [X] | +[X] | + | Source citations | [X] | [X] | +[X] | + | Q&A format | [X] | [X] | +[X] | + | Authority signals | [X] | [X] | +[X] | + | **Overall GEO Score** | **[avg]/10** | **[avg]/10** | **+[X]** | + + ### AI Query Coverage + + This content is now optimized to answer: + - "What is [topic]?" ✅ + - "How does [topic] work?" ✅ + - "Why is [topic] important?" ✅ + - "[Topic] vs [alternative]" ✅ + - "Best [topic] for [use case]" ✅ + ``` + +5. **CORE-EEAT GEO Self-Check** + + After optimization, verify GEO-First items: + + ```markdown + ### CORE-EEAT GEO Post-Optimization Check + + | ID | Standard | Status | Notes | + |----|----------|--------|-------| + | C02 | Direct Answer in first 150 words | ✅/⚠️/❌ | [notes] | + | C04 | Key terms defined on first use | ✅/⚠️/❌ | [notes] | + | C09 | Structured FAQ with Schema | ✅/⚠️/❌ | [notes] | + | O02 | Summary Box / Key Takeaways | ✅/⚠️/❌ | [notes] | + | O03 | Comparisons in tables | ✅/⚠️/❌ | [notes] | + | O05 | JSON-LD Schema Markup | ✅/⚠️/❌ | [notes] | + | O06 | Section chunking (3–5 sentences) | ✅/⚠️/❌ | [notes] | + | R01 | ≥5 precise data points with units | ✅/⚠️/❌ | [notes] | + | R02 | ≥1 citation per 500 words | ✅/⚠️/❌ | [notes] | + | R04 | Claims backed by evidence | ✅/⚠️/❌ | [notes] | + | R07 | Full entity names | ✅/⚠️/❌ | [notes] | + | E01 | Original first-party data | ✅/⚠️/❌ | [notes] | + | Exp10 | Limitations acknowledged | ✅/⚠️/❌ | [notes] | + | Ept08 | Reasoning transparency | ✅/⚠️/❌ | [notes] | + + **Items Needing Attention**: [list any ⚠️/❌ items] + + _For full 80-item audit, use [content-quality-auditor](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/content-quality-auditor/SKILL.md)_ + ``` + +## Validation Checkpoints + +### Input Validation +- [ ] Content source identified (URL, full text, or content draft) +- [ ] Target AI queries or topics clearly defined +- [ ] Current GEO baseline assessed (if optimizing existing content) + +### Output Validation +- [ ] At least 3 clear, quotable definitions added +- [ ] Factual density improved with at least 5 verifiable statistics +- [ ] All claims have source citations from authoritative sources +- [ ] Q&A format sections cover top 5 user queries +- [ ] GEO score improvement of at least 50% from baseline +- [ ] Source of each data point clearly stated (~~AI monitor data, user-provided, or estimated) + +## Example + +**User**: "Optimize this paragraph for GEO: 'Email marketing is a good way to reach customers. It's been around for a while and many businesses use it. You can send newsletters, promotions, and other messages.'" + +**Output**: + +```markdown +## GEO-Optimized Version + +**Email marketing** is a digital marketing strategy that uses email to promote +products, build customer relationships, and drive conversions. According to +the Data & Marketing Association, email marketing delivers an average ROI +of $42 for every $1 invested, making it the highest-performing digital +marketing channel. + +### Key email marketing formats include: + +1. **Newsletters**: Regular updates sharing company news, industry insights, + and valuable content to maintain subscriber engagement +2. **Promotional emails**: Time-sensitive offers, discounts, and product + announcements designed to drive immediate sales +3. **Transactional emails**: Order confirmations, shipping updates, and + account notifications with 8x higher open rates than marketing emails +4. **Automated sequences**: Pre-scheduled email series triggered by user + actions, such as welcome series or abandoned cart reminders + +> **Key statistic**: 81% of small businesses rely on email as their primary +> customer acquisition channel (Emarsys, 2024). + +--- + +### Changes Made: + +Changes: added clear definition, 2 stats with sources, structured list, DMA/Emarsys citations, 3 quotable facts. **GEO Score**: 1/10 → 8/10. +``` + +## GEO Optimization Checklist + +> **Reference**: See the GEO Readiness Checklist in [references/geo-optimization-techniques.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/geo-content-optimizer/references/geo-optimization-techniques.md) for the full checklist covering definitions, quotable content, authority, structure, and technical elements. + +## Tips for Success + +1. **Answer the question first** - Put the answer in the first sentence +2. **Be specific** - Vague content doesn't get cited +3. **Cite sources** - AI systems trust verifiable information +4. **Stay current** - Update statistics and facts regularly +5. **Match query format** - Questions deserve direct answers +6. **Build authority** - Expert credentials increase citation likelihood + + +### Save Results + +After delivering content or optimization output to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to `memory/content/YYYY-MM-DD-.md` containing: +- One-line description of what was created +- Target keyword and content type +- Open loops or items needing review +- Source data references + +**Gate check recommended**: Run content-quality-auditor before publishing (PostToolUse hook will remind automatically). + +If any findings should influence ongoing strategy, recommend promoting key conclusions to `memory/hot-cache.md`. + +## Reference Materials + +- [AI Citation Patterns](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/geo-content-optimizer/references/ai-citation-patterns.md) - How Google AI Overviews, ChatGPT, Perplexity, and Claude select and cite sources +- [Quotable Content Examples](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/geo-content-optimizer/references/quotable-content-examples.md) - Before/after examples of content optimized for AI citation + +## Next Best Skill + +- **Primary**: [content-quality-auditor](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/content-quality-auditor/SKILL.md) — verify the optimized content is strong enough to ship and cite. diff --git a/.cursor/skills/geo-content-optimizer/references/ai-citation-patterns.md b/.cursor/skills/geo-content-optimizer/references/ai-citation-patterns.md new file mode 100644 index 0000000000..6430c20a9c --- /dev/null +++ b/.cursor/skills/geo-content-optimizer/references/ai-citation-patterns.md @@ -0,0 +1,504 @@ +# AI Citation Patterns + +How different AI systems select and cite content. Understanding these patterns helps optimize content for AI visibility. + +## Google AI Overviews + +### Citation Behavior + +**Format preferences**: +- Prefers structured, factual content +- Cites multiple sources per overview +- Shows source links as footnotes +- Displays "Sources" section at bottom + +**What gets cited**: +- Clear, direct answers to queries +- Statistics with recent dates +- Step-by-step instructions +- Comparison tables +- Definition blocks +- List-formatted content + +**Content structure preferences**: +- Short paragraphs (2-3 sentences) +- Bullet points and numbered lists +- Clear headings matching query intent +- Tables for comparison data +- FAQ formats + +**Authority signals**: +- Domain authority (trusted sites favored) +- E-E-A-T signals (expertise, authoritativeness, trustworthiness) +- Recent publication/update dates +- Author credentials visible +- Citations to other authoritative sources + +**Citation frequency**: Typically cites 3-8 sources per AI Overview + +--- + +## ChatGPT (with Browsing) + +### Citation Behavior + +**Format preferences**: +- Inline citations with numbers [1], [2] +- "Sources" list at end of response +- Clickable source links +- Sometimes quotes directly with quotation marks + +**What gets cited**: +- Specific facts and statistics +- Expert quotes +- Technical explanations +- Recent information (prioritizes freshness) +- Authoritative domain content +- Well-structured, scannable content + +**Source selection patterns**: +- Favors .edu, .gov, .org domains +- Prioritizes recognized brands/publishers +- Values comprehensive content over thin pages +- Prefers content with clear attribution +- Looks for consensus across multiple sources + +**Quoting behavior**: +- Pulls exact quotes when information is distinctive +- Paraphrases general information +- Combines information from multiple sources +- Attributes specific claims to sources + +**Citation frequency**: 1-6 sources per response depending on complexity + +--- + +## Perplexity AI + +### Citation Behavior + +**Format preferences**: +- Superscript numbers [1] inline +- Numbered source list with snippets +- Shows brief excerpt from each source +- Displays domain name and publish date + +**What gets cited**: +- Recent content (strong freshness bias) +- Authoritative sources +- Content with clear, quotable statements +- Statistical data with sources +- Primary sources over secondary +- Content matching query intent precisely + +**Content structure preferences**: +- Extremely well-structured content +- Clear topic sentences +- Quotable, standalone statements +- Factual density (stats, data, specifics) +- Headings that match question formats + +**Authority signals**: +- Domain credibility +- Author expertise +- Publication reputation +- Recency of content +- Depth of coverage + +**Citation frequency**: Typically 5-10 sources per response (more than others) + +**Unique behavior**: Often shows "Follow-up Questions" that can reveal additional citation opportunities + +--- + +## Claude (Knowledge-Based Responses) + +### Citation Behavior + +**Note**: Claude typically relies on training data rather than live web access, but understanding preferences helps create citeable content. + +**Format preferences**: +- When citing, uses clear attribution phrases +- "According to [source]..." +- "Research from [source] shows..." +- May reference general knowledge without specific citations + +**What gets remembered/prioritized**: +- Clear, authoritative definitions +- Widely-accepted facts and statistics +- Well-established methodologies +- Consensus information +- Content from recognized authorities + +**Content characteristics valued**: +- Factual accuracy and precision +- Logical structure and clarity +- Comprehensive explanations +- Technical accuracy +- Unambiguous language + +--- + +## Common Traits Across All AI Systems + +### Universal Citation Factors + +**Content quality**: +- Factual accuracy (incorrect info won't be cited) +- Clear, unambiguous language +- Proper grammar and spelling +- Comprehensive coverage +- Up-to-date information + +**Structure**: +- Scannable format (headings, lists, tables) +- Logical organization +- Clear topic segmentation +- Short paragraphs +- Visual hierarchy + +**Authority**: +- Domain credibility +- Author credentials +- Source citations in content +- Expertise signals +- Editorial quality + +**Relevance**: +- Precise match to query intent +- Topic focus (not meandering) +- Keyword-topic alignment +- Depth of coverage on specific topic + +--- + +## Optimal Content Structures for Citation + +### 1. Definition Blocks + +AI systems love clear, quotable definitions. + +**Structure**: +```markdown +**[Term]** is [clear category] that [primary function], [key characteristic]. +``` + +**Example**: +> **Search Engine Optimization (SEO)** is a digital marketing practice that improves website visibility in organic search results by optimizing content, technical elements, and authority signals. + +**Why it works**: Standalone, complete, unambiguous, proper scope. + +--- + +### 2. Statistic Blocks + +Facts with sources are highly citeable. + +**Structure**: +```markdown +According to [Source], [specific statistic] as of [timeframe]. +``` + +**Example**: +> According to HubSpot's 2024 State of Marketing Report, 82% of marketers actively invest in content marketing, making it the most widely adopted digital marketing strategy. + +**Why it works**: Specific, attributed, recent, verifiable. + +--- + +### 3. Q&A Pairs + +Question-answer formats match AI query patterns. + +**Structure**: +```markdown +### [Question matching common query]? + +[Direct answer in 40-60 words] + +[Optional supporting detail] +``` + +**Example**: +> ### How long does SEO take to show results? +> +> SEO typically takes 3-6 months to show significant results for new websites, though this varies based on competition, domain authority, and strategy. Established sites may see improvements in 1-3 months for less competitive keywords. + +**Why it works**: Matches query format, provides concise answer, includes qualifiers. + +--- + +### 4. Comparison Tables + +Structured comparisons are easy for AI to parse and cite. + +**Structure**: +```markdown +| Feature | Option A | Option B | +|---------|----------|----------| +| [Factor 1] | [Specific value] | [Specific value] | +| [Factor 2] | [Specific value] | [Specific value] | +| **Best for** | [Use case] | [Use case] | +``` + +**Example**: +| Factor | Technical SEO | On-Page SEO | +|--------|---------------|-------------| +| Focus | Site infrastructure | Content optimization | +| Timeframe | 1-3 months | Ongoing | +| Complexity | High | Medium | +| **Best for** | Site-wide issues | Individual page improvements | + +**Why it works**: Clear comparison, specific values, scannable format. + +--- + +### 5. Step-by-Step Processes + +Numbered lists for "how to" queries. + +**Structure**: +```markdown +1. **[Action]** - [Brief explanation] +2. **[Action]** - [Brief explanation] +3. **[Action]** - [Brief explanation] +``` + +**Example**: +> To conduct keyword research: +> 1. **Identify seed keywords** - List 5-10 topics your audience searches for +> 2. **Use keyword research tools** - Expand seed keywords into hundreds of variations +> 3. **Analyze search intent** - Determine what content format each keyword requires +> 4. **Evaluate competition** - Assess ranking difficulty for each keyword +> 5. **Prioritize keywords** - Choose based on volume, difficulty, and relevance + +**Why it works**: Clear process, actionable steps, logical sequence. + +--- + +### 6. List-Based Content + +Curated lists with brief explanations. + +**Structure**: +```markdown +**[Item name]**: [Clear description with key benefit] +``` + +**Example**: +> Top on-page SEO factors: +> - **Title tags**: Most important on-page element; include primary keyword within first 60 characters +> - **Header tags**: Structure content hierarchically; use one H1, multiple H2s for main sections +> - **Meta descriptions**: Don't directly impact rankings but affect CTR; keep under 160 characters +> - **URL structure**: Use descriptive, keyword-rich URLs without unnecessary parameters + +**Why it works**: Scannable, specific, actionable. + +--- + +### 7. Before/After Examples + +Concrete examples showing transformation. + +**Structure**: +```markdown +**Before**: [Weak example] +**After**: [Strong example] +**Why it's better**: [Explanation] +``` + +**Example**: +> **Before**: "Email marketing is pretty effective." +> **After**: "Email marketing delivers an average ROI of $42 for every $1 spent, according to the Data & Marketing Association." +> **Why it's better**: Specific statistic, attributed source, quantifiable claim. + +**Why it works**: Shows concrete improvement, demonstrates principle. + +--- + +### 8. Key Insight Callouts + +Highlighted important points. + +**Structure**: +```markdown +> **Key insight**: [Memorable, quotable statement] +``` + +**Example**: +> **Key insight**: According to Google's John Mueller, internal linking is one of the most underutilized SEO tactics, with properly structured internal links often delivering faster ranking improvements than external link building. + +**Why it works**: Visually distinct, authoritative, quotable. + +--- + +## Content Optimization by Query Type + +### Informational Queries ("What is...", "How does...", "Why...") + +**AI citation priorities**: +1. Clear definitions +2. Comprehensive explanations +3. Expert perspectives +4. Supporting statistics +5. Real-world examples + +**Optimal structure**: +- Definition in first paragraph +- "Why it matters" section +- How it works explanation +- Common use cases +- Expert quotes or citations + +--- + +### Comparison Queries ("[A] vs [B]", "Best [category]") + +**AI citation priorities**: +1. Comparison tables +2. Clear pros/cons lists +3. Use case recommendations +4. Specific differentiators +5. Verdict or recommendation + +**Optimal structure**: +- Quick comparison table upfront +- Individual descriptions +- Feature-by-feature comparison +- "Choose X if..." recommendations +- Summary verdict + +--- + +### How-To Queries ("How to...", "Steps to...") + +**AI citation priorities**: +1. Numbered step-by-step processes +2. Required tools/prerequisites +3. Time estimates +4. Success indicators +5. Troubleshooting tips + +**Optimal structure**: +- Prerequisites listed first +- Clear numbered steps +- Sub-steps where needed +- Visual indicators of progress +- Common problems and solutions + +--- + +### Statistical Queries ("How much...", "How many...", "Statistics about...") + +**AI citation priorities**: +1. Specific numbers with sources +2. Recent data (within 1-2 years) +3. Multiple data points +4. Context for statistics +5. Trend information + +**Optimal structure**: +- Lead with key statistic +- Source attribution immediately after +- Context and interpretation +- Related statistics +- Takeaways from data + +--- + +## Citation Likelihood Factors + +### High Citation Likelihood + +- [ ] Content from recognized authority domains +- [ ] Published or updated within 12 months +- [ ] Clear, standalone statements +- [ ] Proper source attribution +- [ ] Specific statistics with dates +- [ ] Structured with headings/lists/tables +- [ ] Comprehensive topic coverage +- [ ] Author credentials visible +- [ ] Technical accuracy verified +- [ ] Consensus with other sources + +### Medium Citation Likelihood + +- [ ] Content from less-known but quality domains +- [ ] Published 1-2 years ago +- [ ] Clear but requires slight context +- [ ] General industry claims +- [ ] Good structure but less scannable +- [ ] Moderate depth of coverage +- [ ] No author listed but quality content +- [ ] Some supporting evidence + +### Low Citation Likelihood + +- [ ] Content from unknown/low-authority domains +- [ ] Published 3+ years ago without updates +- [ ] Vague or ambiguous statements +- [ ] No sources cited +- [ ] Poor content structure (walls of text) +- [ ] Thin or superficial coverage +- [ ] Promotional or biased tone +- [ ] Factual inconsistencies +- [ ] No expertise signals + +--- + +## AI System Comparison Summary + +| Factor | Google AI Overviews | ChatGPT | Perplexity | Claude | +|--------|---------------------|---------|------------|--------| +| **Freshness bias** | High | Medium | Very high | N/A (training data) | +| **Authority weight** | Very high | High | High | High | +| **Structure importance** | High | Medium | Very high | Medium | +| **Citation count** | 3-8 | 1-6 | 5-10 | N/A | +| **Quotable focus** | High | Medium | Very high | High | +| **Domain trust** | Very high | High | Medium | High | +| **Factual density** | High | High | Very high | Very high | + +--- + +## Tracking AI Citations + +### Manual Monitoring + +**Check if your content appears in**: +- Google AI Overviews for target keywords +- ChatGPT responses (search your domain in ChatGPT) +- Perplexity results for relevant queries +- Other AI search engines + +**Test queries**: +- Exact-match questions from your FAQ +- Definitions of terms you've defined +- Statistics you've cited with attribution +- Processes you've documented + +### Indicators of AI Visibility + +- Increased direct traffic (AI users clicking sources) +- Traffic spikes from unusual referrers +- Engagement metrics: low bounce rate, high time-on-page +- Return visitors (AI users coming back for more depth) + +--- + +## Optimization Checklist for AI Citations + +Content ready for AI citation should have: + +- [ ] At least 3 clear, quotable definitions +- [ ] 5+ specific statistics with sources and dates +- [ ] Q&A format sections covering top queries +- [ ] Comparison tables where relevant +- [ ] Numbered lists for processes +- [ ] Content published or updated within 12 months +- [ ] Author credentials visible +- [ ] External citations to authoritative sources +- [ ] Structured with clear H2/H3 headings +- [ ] Short paragraphs (2-4 sentences) +- [ ] No promotional language +- [ ] Technical accuracy verified +- [ ] Mobile-friendly formatting diff --git a/.cursor/skills/geo-content-optimizer/references/geo-optimization-techniques.md b/.cursor/skills/geo-content-optimizer/references/geo-optimization-techniques.md new file mode 100644 index 0000000000..cfc343a748 --- /dev/null +++ b/.cursor/skills/geo-content-optimizer/references/geo-optimization-techniques.md @@ -0,0 +1,235 @@ +# GEO Optimization Techniques + +Detailed techniques for optimizing content for AI citation across Google AI Overviews, ChatGPT, Perplexity AI, Claude, and Gemini. + +## Definition Optimization + +AI systems love clear, quotable definitions. + +**Before** (Weak for GEO): +> SEO is really important for businesses and involves various +> techniques to improve visibility online through search engines. + +**After** (Strong for GEO): +> **Search Engine Optimization (SEO)** is the practice of optimizing +> websites and content to rank higher in search engine results pages +> (SERPs), increasing organic traffic and visibility. + +**Definition Template**: +"[Term] is [clear category/classification] that [primary function/purpose], +[key characteristic or benefit]." + +**Checklist for GEO-Optimized Definitions**: +- [ ] Starts with the term being defined +- [ ] Provides clear category (what type of thing it is) +- [ ] Explains primary function or purpose +- [ ] Uses precise, unambiguous language +- [ ] Can stand alone as a complete answer +- [ ] Is 25-50 words for optimal citation length + +## Quotable Statement Optimization + +AI systems cite specific, standalone statements. Transform vague +content into quotable facts. + +**Weak (Not quotable)**: +> Email marketing is pretty effective and lots of companies use it. + +**Strong (Quotable)**: +> Email marketing delivers an average ROI of $42 for every $1 spent, +> making it one of the highest-performing digital marketing channels. + +**Types of Quotable Statements**: + +1. **Statistics** + - Include specific numbers + - Cite the source + - Add context (timeframe, comparison) + + Example: "According to [Source], [specific statistic] as of [date]." + +2. **Facts** + - Verifiable information + - Unambiguous language + - Authoritative source + + Example: "[Subject] was [fact], according to [authoritative source]." + +3. **Definitions** (covered above) + +4. **Comparisons** + - Clear comparison structure + - Specific differentiators + + Example: "Unlike [A], [B] [specific difference], which means [implication]." + +5. **How-to Steps** + - Numbered, clear steps + - Action-oriented language + + Example: "To [achieve goal], [step 1], then [step 2], and finally [step 3]." + +## Authority Signal Enhancement + +**Expert Attribution** + +Add expert quotes and credentials: + +> "AI will transform how we search for information," says Dr. Jane Smith, +> AI Research Director at Stanford University. + +**Source Citations** + +Properly cite sources that AI can verify: + +Before: +> Studies show that most people prefer video content. + +After: +> According to Wyzowl's 2024 Video Marketing Statistics report, +> 91% of consumers want to see more online video content from brands. + +**Authority Elements to Add**: +- [ ] Author byline with credentials +- [ ] Expert quotes with attribution +- [ ] Citations to peer-reviewed research +- [ ] References to recognized authorities +- [ ] Original data or research +- [ ] Case studies with named companies +- [ ] Industry statistics with sources + +## Structure Optimization for GEO + +AI systems parse structured content more effectively. + +**Q&A Format** + +Transform content into question-answer pairs: + +```html +

What is [Topic]?

+

[Direct answer in 40-60 words]

+ +

How does [Topic] work?

+

[Clear explanation with steps if applicable]

+ +

Why is [Topic] important?

+

[Specific reasons with evidence]

+``` + +**Comparison Tables** + +For comparison queries, use clear tables: + +| Feature | Option A | Option B | +|---------|----------|----------| +| [Feature 1] | [Specific value] | [Specific value] | +| [Feature 2] | [Specific value] | [Specific value] | +| **Best for** | [Use case] | [Use case] | + +**Numbered Lists** + +For process or list queries: + +1. **Step 1: [Action]** - [Brief explanation] +2. **Step 2: [Action]** - [Brief explanation] +3. **Step 3: [Action]** - [Brief explanation] + +**Definition Boxes** + +Highlight key definitions: + +> **Key Definition**: [Term] refers to [clear definition]. + +## Factual Density Improvement + +AI systems prefer fact-rich content over opinion-heavy content. + +**Content Transformation**: + +**Low factual density**: +> Social media marketing is very popular nowadays. Many businesses +> use it and find it helpful for reaching customers. + +**High factual density**: +> Social media marketing reaches 4.9 billion users globally (Statista, 2024). +> Businesses using social media marketing report 66% higher lead generation +> rates compared to non-users (HubSpot State of Marketing Report, 2024). +> The most effective platforms for B2B marketing are LinkedIn (96% usage), +> Twitter (82%), and Facebook (80%). + +**Factual Enhancement Checklist**: +- [ ] Add specific statistics with sources +- [ ] Include exact dates, numbers, percentages +- [ ] Replace vague claims with verified facts +- [ ] Add recent data (within last 2 years) +- [ ] Include multiple data points per section +- [ ] Cross-reference with authoritative sources + +## FAQ Optimization for GEO + +FAQ sections are highly effective for GEO because: +- They match question-based AI queries +- They provide concise, structured answers +- FAQ schema helps AI understand Q&A pairs + +**FAQ Structure**: + +## Frequently Asked Questions + +### [Question matching common query]? + +[Direct answer: 40-60 words] +[Supporting detail or example] + +### [Question matching common query]? + +[Direct answer: 40-60 words] +[Supporting detail or example] + +**FAQ Schema (JSON-LD)**: + +```json +{ + "@context": "https://schema.org", + "@type": "FAQPage", + "mainEntity": [{ + "@type": "Question", + "name": "[Question text]", + "acceptedAnswer": { + "@type": "Answer", + "text": "[Answer text]" + } + }] +} +``` + +## GEO Readiness Checklist + +Use this checklist for any content: + +**Definitions & Clarity** +- [ ] Key terms are clearly defined +- [ ] Definitions can stand alone as answers +- [ ] Language is precise and unambiguous + +**Quotable Content** +- [ ] Specific statistics included +- [ ] Facts have source citations +- [ ] Memorable statements created + +**Authority** +- [ ] Expert quotes or credentials present +- [ ] Authoritative sources cited +- [ ] Original data or research included + +**Structure** +- [ ] Q&A format sections included +- [ ] Clear headings match common queries +- [ ] Comparison tables where relevant +- [ ] Numbered lists for processes + +**Technical** +- [ ] FAQ schema markup added +- [ ] Content freshness indicated +- [ ] Sources are verifiable diff --git a/.cursor/skills/geo-content-optimizer/references/quotable-content-examples.md b/.cursor/skills/geo-content-optimizer/references/quotable-content-examples.md new file mode 100644 index 0000000000..ddc73201f1 --- /dev/null +++ b/.cursor/skills/geo-content-optimizer/references/quotable-content-examples.md @@ -0,0 +1,484 @@ +# Quotable Content Examples + +Before/after examples of content optimized for AI citation. Each example shows the transformation from generic to quotable. + +## Example 1: Definition Block + +### Before (Generic, Not Quotable) + +> SEO is really important for businesses and involves various techniques to improve visibility online through search engines. It's been around for a while and many businesses use it to get more traffic to their websites. + +**Problems**: +- Vague language ("really important", "various techniques") +- No clear classification +- Meandering structure +- Not standalone + +**Citation likelihood**: 1/10 + +--- + +### After (Clear, Quotable) + +> **Search Engine Optimization (SEO)** is a digital marketing practice that improves website rankings in organic search results through content optimization, technical improvements, and authority building. According to BrightEdge research, organic search drives 53% of all website traffic, making SEO the highest-impact channel for sustainable online visibility. + +**Improvements**: +- Clear term + category classification +- Specific components listed +- Authoritative statistic with source +- Standalone statement +- Precise language + +**Citation likelihood**: 9/10 + +--- + +## Example 2: Statistical Content + +### Before (Weak) + +> Email marketing is pretty effective and lots of companies use it. It has a good return on investment compared to other marketing channels. + +**Problems**: +- No specific numbers +- No source attribution +- Vague comparisons ("pretty effective", "lots", "good") +- Not verifiable + +**Citation likelihood**: 2/10 + +--- + +### After (Strong) + +> Email marketing delivers an average ROI of $42 for every $1 spent, according to the Data & Marketing Association's 2024 research. This 4,200% return makes email the highest-performing digital marketing channel, outperforming social media (28% ROI) and paid search (23% ROI) by significant margins. + +**Improvements**: +- Specific statistic with exact numbers +- Source attribution with year +- Comparative data +- Verifiable claim +- Context provided + +**Citation likelihood**: 9/10 + +--- + +## Example 3: Process/How-To Content + +### Before (Unclear) + +> To do keyword research, you should think about what your customers might search for and then use some tools to find more keywords. Look at what your competitors are doing too. Then pick the best keywords for your content. + +**Problems**: +- Vague steps ("think about", "some tools") +- No clear structure +- Missing specifics +- No actionable guidance + +**Citation likelihood**: 2/10 + +--- + +### After (Clear Process) + +> To conduct effective keyword research: +> +> 1. **Identify seed keywords** - List 5-10 core topics your target audience searches for +> 2. **Expand with research tools** - Use tools like Google Keyword Planner or Ahrefs to generate 100+ related keywords +> 3. **Analyze search intent** - Categorize each keyword as informational, commercial, or transactional +> 4. **Assess competition** - Evaluate ranking difficulty using domain authority and SERP analysis +> 5. **Prioritize strategically** - Select 10-15 keywords balancing search volume (1,000+ monthly searches) with achievable competition +> +> This process typically takes 2-4 hours for a comprehensive initial keyword list. + +**Improvements**: +- Numbered, sequential steps +- Specific actions in each step +- Concrete numbers and tools +- Time estimate included +- Actionable guidance + +**Citation likelihood**: 8/10 + +--- + +## Example 4: Comparison Content + +### Before (Vague Comparison) + +> WordPress and Shopify are both popular website builders. WordPress is more flexible while Shopify is easier to use. The choice depends on what you need. + +**Problems**: +- No specific differentiators +- Vague claims ("more flexible", "easier") +- No clear recommendation criteria +- Not helpful for decision-making + +**Citation likelihood**: 2/10 + +--- + +### After (Structured Comparison) + +> | Factor | WordPress | Shopify | +> |--------|-----------|---------| +> | **Best for** | Content-heavy sites, blogs, custom needs | E-commerce, quick setup | +> | **Setup time** | 4-8 hours | 1-2 hours | +> | **Monthly cost** | $10-50 (hosting + theme) | $29-299 (subscription) | +> | **Customization** | Unlimited (50,000+ plugins) | Limited to Shopify apps | +> | **E-commerce** | Requires WooCommerce plugin | Built-in, optimized | +> | **SEO control** | Complete control | Good but limited | +> +> **Choose WordPress if**: You need maximum flexibility, run a content-first site, or have technical resources. +> +> **Choose Shopify if**: E-commerce is your primary goal, you want fast setup, or you lack technical expertise. + +**Improvements**: +- Structured table format +- Specific, comparable metrics +- Clear use case recommendations +- Quantifiable differences +- Decision framework + +**Citation likelihood**: 9/10 + +--- + +## Example 5: Expert Content + +### Before (No Authority) + +> Many people think that social media is important for SEO. It can help you get more visibility and traffic. + +**Problems**: +- No expert attribution +- Vague claims ("many people think") +- No specific mechanism explained +- Weak authority signals + +**Citation likelihood**: 1/10 + +--- + +### After (Expert-Backed) + +> While social media doesn't directly impact search rankings, it influences SEO through indirect channels. "Social signals drive discovery, which leads to backlinks and brand searches—both powerful ranking factors," explains Rand Fishkin, founder of SparkToro and former CEO of Moz. Research from Hootsuite found that content promoted on social media earns 2.3x more backlinks than non-promoted content within the first 30 days of publication. + +**Improvements**: +- Expert quote with credentials +- Specific mechanism explained +- Research data with source +- Quantifiable impact (2.3x) +- Authority signals + +**Citation likelihood**: 9/10 + +--- + +## Example 6: Q&A Content + +### Before (Incomplete Answer) + +> **How long does SEO take?** +> +> It depends on a lot of factors. Sometimes it's fast, sometimes it takes a while. New sites usually take longer than established ones. + +**Problems**: +- No specific timeframe +- "It depends" without explaining what it depends on +- Vague language ("fast", "a while", "longer") +- Not actionable + +**Citation likelihood**: 1/10 + +--- + +### After (Complete Answer) + +> **How long does SEO take to show results?** +> +> SEO typically takes 3-6 months to show significant results for new websites. Established sites with existing authority may see improvements in 1-3 months for less competitive keywords. Results depend on four key factors: +> +> 1. **Domain authority** - New domains take 6-12 months; established domains see faster results +> 2. **Competition level** - Low-competition keywords rank in 1-3 months; high-competition may take 12+ months +> 3. **Implementation quality** - Comprehensive optimization accelerates results +> 4. **Existing backlink profile** - Sites with 20+ quality backlinks see 40% faster improvements (Ahrefs study) +> +> Most businesses should budget 6 months for measurable ROI from SEO efforts. + +**Improvements**: +- Specific timeframes with ranges +- Factors clearly explained +- Differentiated by scenario +- Supporting data with source +- Actionable planning guidance + +**Citation likelihood**: 9/10 + +--- + +## Example 7: List Content + +### Before (Thin List) + +> Here are some important on-page SEO factors: +> - Title tags +> - Meta descriptions +> - Headers +> - Content +> - Links +> - Images + +**Problems**: +- No explanations +- No prioritization +- Not actionable +- Missing context + +**Citation likelihood**: 2/10 + +--- + +### After (Rich List) + +> Critical on-page SEO factors ranked by impact: +> +> 1. **Title tags** - Most important on-page element; include primary keyword within first 60 characters. Title tags directly influence both rankings and CTR. +> +> 2. **Content quality and depth** - Comprehensive content (1,500+ words for competitive keywords) outranks thin content. Focus on topical authority over keyword density. +> +> 3. **Header structure (H1-H6)** - Use one H1 with primary keyword, multiple H2s for main sections. Proper hierarchy helps search engines understand content structure. +> +> 4. **Internal linking** - Link to 3-5 related pages using descriptive anchor text. Internal links distribute page authority and help search engines discover content. +> +> 5. **Image optimization** - Compress images to under 100KB, use descriptive alt text with target keywords. Page speed and accessibility both impact rankings. +> +> 6. **URL structure** - Use descriptive, keyword-rich URLs (example.com/keyword-topic) avoiding parameters. Clean URLs improve click-through rates by 25% (Backlinko study). +> +> Optimize these six factors before moving to advanced tactics. + +**Improvements**: +- Prioritized ranking +- Specific guidance for each +- Actionable recommendations +- Supporting data +- Clear next step + +**Citation likelihood**: 8/10 + +--- + +## Example 8: Trend/Prediction Content + +### Before (Speculation) + +> AI is going to change SEO a lot in the future. Things will be different and SEO professionals will need to adapt. + +**Problems**: +- Vague predictions ("a lot", "different") +- No specific changes identified +- No timeframe +- No evidence + +**Citation likelihood**: 1/10 + +--- + +### After (Evidence-Based Trend) + +> AI is fundamentally transforming SEO search behavior. According to Gartner's 2024 research, AI-powered search will reduce traditional search engine traffic by 25% by 2026, as users increasingly rely on AI chatbots for information. +> +> Three specific shifts SEO professionals must prepare for: +> +> 1. **Zero-click content consumption** - Users get answers without visiting websites, requiring optimization for AI citations rather than clicks +> +> 2. **Conversation-based queries** - Natural language questions replace keyword-based searches, demanding content that answers specific questions +> +> 3. **Source attribution value** - Being cited by AI systems (Generative Engine Optimization/GEO) becomes as important as ranking #1 +> +> Forrester predicts that by 2025, 30% of organic traffic will come from AI system citations rather than traditional search results, making GEO optimization critical for visibility. + +**Improvements**: +- Specific statistics with sources +- Clear timeframes +- Concrete changes identified +- Multiple research citations +- Actionable implications + +**Citation likelihood**: 9/10 + +--- + +## Example 9: Technical Explanation + +### Before (Complex, Unclear) + +> Core Web Vitals are metrics that Google uses to measure user experience. They look at how fast your site loads and how stable it is when people use it. You should try to improve them. + +**Problems**: +- Oversimplified without specifics +- No concrete metrics +- Vague improvement guidance +- Missing thresholds + +**Citation likelihood**: 2/10 + +--- + +### After (Clear, Specific) + +> Core Web Vitals are three specific metrics Google uses to measure page experience: +> +> | Metric | Measures | Good Score | Impact | +> |--------|----------|------------|--------| +> | **LCP (Largest Contentful Paint)** | Loading performance | <2.5 seconds | How quickly main content appears | +> | **FID (First Input Delay)** | Interactivity | <100 milliseconds | How quickly page responds to user input | +> | **CLS (Cumulative Layout Shift)** | Visual stability | <0.1 | How much content shifts during loading | +> +> According to Google's 2024 documentation, pages meeting all three thresholds rank higher and receive 24% more clicks than pages failing these metrics. Core Web Vitals became an official ranking factor in June 2021 as part of Google's Page Experience update. +> +> Test your Core Web Vitals with ~~page speed tool. + +**Improvements**: +- Three specific metrics defined +- Clear thresholds provided +- Table format for scannability +- Official data with source +- Testing tool referenced + +**Citation likelihood**: 9/10 + +--- + +## Example 10: Case Study Content + +### Before (Vague Results) + +> We improved our client's SEO and they got more traffic. They were really happy with the results and saw an increase in their business. + +**Problems**: +- No specific numbers +- No timeframe +- No methodology shared +- Not reproducible + +**Citation likelihood**: 1/10 + +--- + +### After (Data-Rich Case Study) + +> **Case Study: 312% Organic Traffic Increase in 6 Months** +> +> **Client**: B2B SaaS company (project management software) +> +> **Challenge**: Only 450 monthly organic visitors, ranking #20+ for target keywords +> +> **Strategy implemented**: +> 1. Created 24 pillar pages targeting high-intent keywords +> 2. Built internal linking hub connecting 150 existing pages +> 3. Optimized 80 existing pages for featured snippets +> 4. Secured 45 high-authority backlinks through expert roundups +> +> **Results (6 months)**: +> - Organic traffic: 450 → 1,854 monthly visitors (+312%) +> - Keyword rankings: 3 keywords in top 10 → 47 keywords in top 10 +> - Featured snippets: 0 → 12 owned snippets +> - Lead conversions: 8 → 41 monthly leads (+412%) +> +> **Key insight**: 80% of traffic growth came from optimizing existing content rather than creating new pages, demonstrating the power of content refreshing strategies. + +**Improvements**: +- Specific metrics with percentages +- Clear timeframe +- Detailed methodology +- Reproducible tactics +- Key learning identified + +**Citation likelihood**: 9/10 + +--- + +## Transformation Checklist + +To make any content more quotable: + +**Definitions**: +- [ ] Replace vague language with precise terms +- [ ] Add clear category classification +- [ ] Make statement standalone +- [ ] Include scope and boundaries + +**Statistics**: +- [ ] Add specific numbers +- [ ] Include source attribution +- [ ] Specify timeframe/date +- [ ] Add context for interpretation +- [ ] Verify accuracy + +**Processes**: +- [ ] Number steps clearly +- [ ] Make each step actionable +- [ ] Add time estimates +- [ ] Include specific tools/methods +- [ ] Provide success criteria + +**Comparisons**: +- [ ] Use table format +- [ ] Include specific, comparable metrics +- [ ] Add "choose if..." recommendations +- [ ] Quantify differences +- [ ] Cover key decision factors + +**Lists**: +- [ ] Prioritize items +- [ ] Add explanations to each +- [ ] Include specific guidance +- [ ] Provide examples +- [ ] Make actionable + +**Expert content**: +- [ ] Add attributed quotes +- [ ] Include credentials +- [ ] Reference studies/research +- [ ] Cite authoritative sources +- [ ] Quantify claims + +--- + +## Content Optimization Pattern + +**Generic → Quotable transformation follows this pattern**: + +1. **Add specificity** - Replace "many" with "73%", "fast" with "under 2.5 seconds" +2. **Include attribution** - Add sources for all claims +3. **Structure clearly** - Use tables, lists, numbered steps +4. **Quantify everything** - Numbers > adjectives +5. **Make standalone** - Each statement should work in isolation +6. **Add context** - Explain why, not just what +7. **Use precise language** - Eliminate ambiguity +8. **Include timeframes** - When was this measured/true? +9. **Show authority** - Reference experts, studies, data +10. **Enable verification** - Link to sources, cite methodology + +--- + +## Quick Quotability Test + +Ask these questions about your content: + +1. **Can AI quote this without additional context?** - If no, add context +2. **Does it include specific numbers?** - If no, add data +3. **Is the source clear?** - If no, add attribution +4. **Is language precise and unambiguous?** - If no, clarify +5. **Would an expert approve this?** - If no, add authority signals +6. **Is it scannable?** - If no, add structure +7. **Is it up-to-date?** - If no, update or add date context +8. **Can it be verified?** - If no, add sources +9. **Is it specific to a use case?** - If no, add context +10. **Does it answer a complete question?** - If no, expand + +If you answer "yes" to 8+ questions, content is highly quotable. +If you answer "yes" to 5-7 questions, content is moderately quotable. +If you answer "yes" to fewer than 5, content needs significant optimization. diff --git a/.cursor/skills/improve-codebase-architecture/DEEPENING.md b/.cursor/skills/improve-codebase-architecture/DEEPENING.md new file mode 100644 index 0000000000..ecaf5d7dcf --- /dev/null +++ b/.cursor/skills/improve-codebase-architecture/DEEPENING.md @@ -0,0 +1,37 @@ +# Deepening + +How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**. + +## Dependency categories + +When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam. + +### 1. In-process + +Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed. + +### 2. Local-substitutable + +Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface. + +### 3. Remote but owned (Ports & Adapters) + +Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter. + +Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."* + +### 4. True external (Mock) + +Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter. + +## Seam discipline + +- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection. +- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them. + +## Testing strategy: replace, don't layer + +- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them. +- Write new tests at the deepened module's interface. The **interface is the test surface**. +- Tests assert on observable outcomes through the interface, not internal state. +- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface. diff --git a/.cursor/skills/improve-codebase-architecture/INTERFACE-DESIGN.md b/.cursor/skills/improve-codebase-architecture/INTERFACE-DESIGN.md new file mode 100644 index 0000000000..3197723a0d --- /dev/null +++ b/.cursor/skills/improve-codebase-architecture/INTERFACE-DESIGN.md @@ -0,0 +1,44 @@ +# Interface Design + +When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best. + +Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**. + +## Process + +### 1. Frame the problem space + +Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate: + +- The constraints any new interface would need to satisfy +- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md)) +- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete + +Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel. + +### 2. Spawn sub-agents + +Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module. + +Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint: + +- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point." +- Agent 2: "Maximise flexibility — support many use cases and extension." +- Agent 3: "Optimise for the most common caller — make the default case trivial." +- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies." + +Include both [LANGUAGE.md](LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language. + +Each sub-agent outputs: + +1. Interface (types, methods, params — plus invariants, ordering, error modes) +2. Usage example showing how callers use it +3. What the implementation hides behind the seam +4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md)) +5. Trade-offs — where leverage is high, where it's thin + +### 3. Present and compare + +Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**. + +After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu. diff --git a/.cursor/skills/improve-codebase-architecture/LANGUAGE.md b/.cursor/skills/improve-codebase-architecture/LANGUAGE.md new file mode 100644 index 0000000000..530c27630a --- /dev/null +++ b/.cursor/skills/improve-codebase-architecture/LANGUAGE.md @@ -0,0 +1,53 @@ +# Language + +Shared vocabulary for every suggestion this skill makes. Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point. + +## Terms + +**Module** +Anything with an interface and an implementation. Deliberately scale-agnostic — applies equally to a function, class, package, or tier-spanning slice. +_Avoid_: unit, component, service. + +**Interface** +Everything a caller must know to use the module correctly. Includes the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. +_Avoid_: API, signature (too narrow — those refer only to the type-level surface). + +**Implementation** +What's inside a module — its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise. + +**Depth** +Leverage at the interface — the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface. A module is **shallow** when the interface is nearly as complex as the implementation. + +**Seam** _(from Michael Feathers)_ +A place where you can alter behaviour without editing in that place. The *location* at which a module's interface lives. Choosing where to put the seam is its own design decision, distinct from what goes behind it. +_Avoid_: boundary (overloaded with DDD's bounded context). + +**Adapter** +A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside). + +**Leverage** +What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests. + +**Locality** +What maintainers get from depth. Change, bugs, knowledge, and verification concentrate at one place rather than spreading across callers. Fix once, fixed everywhere. + +## Principles + +- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface. +- **The deletion test.** Imagine deleting the module. If complexity vanishes, the module wasn't hiding anything (it was a pass-through). If complexity reappears across N callers, the module was earning its keep. +- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape. +- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it. + +## Relationships + +- A **Module** has exactly one **Interface** (the surface it presents to callers and tests). +- **Depth** is a property of a **Module**, measured against its **Interface**. +- A **Seam** is where a **Module**'s **Interface** lives. +- An **Adapter** sits at a **Seam** and satisfies the **Interface**. +- **Depth** produces **Leverage** for callers and **Locality** for maintainers. + +## Rejected framings + +- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead. +- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know. +- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**. diff --git a/.cursor/skills/improve-codebase-architecture/SKILL.md b/.cursor/skills/improve-codebase-architecture/SKILL.md new file mode 100644 index 0000000000..05984a6096 --- /dev/null +++ b/.cursor/skills/improve-codebase-architecture/SKILL.md @@ -0,0 +1,71 @@ +--- +name: improve-codebase-architecture +description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. +--- + +# Improve Codebase Architecture + +Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability. + +## Glossary + +Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](LANGUAGE.md). + +- **Module** — anything with an interface and an implementation (function, class, package, slice). +- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature. +- **Implementation** — the code inside. +- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation. +- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.") +- **Adapter** — a concrete thing satisfying an interface at a seam. +- **Leverage** — what callers get from depth. +- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place. + +Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list): + +- **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep. +- **The interface is the test surface.** +- **One adapter = hypothetical seam. Two adapters = real seam.** + +This skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. + +## Process + +### 1. Explore + +Read the project's domain glossary and any ADRs in the area you're touching first. + +Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: + +- Where does understanding one concept require bouncing between many small modules? +- Where are modules **shallow** — interface nearly as complex as the implementation? +- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)? +- Where do tightly-coupled modules leak across their seams? +- Which parts of the codebase are untested, or hard to test through their current interface? + +Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want. + +### 2. Present candidates + +Present a numbered list of deepening opportunities. For each candidate: + +- **Files** — which files/modules are involved +- **Problem** — why the current architecture is causing friction +- **Solution** — plain English description of what would change +- **Benefits** — explained in terms of locality and leverage, and also in how tests would improve + +**Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service." + +**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids. + +Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?" + +### 3. Grilling loop + +Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive. + +Side effects happen inline as decisions crystallize: + +- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist. +- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there. +- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md). +- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). diff --git a/.cursor/skills/internal-linking-optimizer/SKILL.md b/.cursor/skills/internal-linking-optimizer/SKILL.md new file mode 100644 index 0000000000..d83f3eb972 --- /dev/null +++ b/.cursor/skills/internal-linking-optimizer/SKILL.md @@ -0,0 +1,351 @@ +--- +name: internal-linking-optimizer +description: 'Optimize internal links: site architecture, authority distribution, orphan pages, crawl depth analysis. 内链优化/站内架构' +version: "6.0.0" +license: Apache-2.0 +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when improving internal link structure, anchor text distribution, orphan pages, or site architecture." +argument-hint: "" +metadata: + author: aaron-he-zhu + version: "6.0.0" + geo-relevance: "low" + tags: + - seo + - internal-linking + - site-architecture + - link-equity + - orphan-pages + - topical-authority + - crawl-depth + - 内链优化 + - 内部リンク + - 내부링크 + - enlaces-internos + triggers: + # EN-formal + - "fix internal links" + - "improve site architecture" + - "link structure" + - "distribute page authority" + - "internal linking strategy" + - "site navigation" + - "link equity" + # EN-casual + - "orphan pages" + - "site architecture is messy" + - "pages have no links pointing to them" + - "pages have no links" + - "site structure is messy" + # EN-question + - "how to improve internal linking" + - "how to fix orphan pages" + # ZH-pro + - "内链优化" + - "站内链接" + - "网站架构" + - "权重传递" + - "锚文本优化" + # ZH-casual + - "内链怎么做" + - "孤立页面" + - "网站结构乱" + # JA + - "内部リンク最適化" + - "サイト構造" + # KO + - "내부 링크 최적화" + - "사이트 구조" + # ES + - "enlaces internos" + - "arquitectura del sitio" + # PT + - "links internos" + # Misspellings + - "internal linkng" +--- + +# Internal Linking Optimizer + + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This optimization skill follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + + +This skill analyzes your site's internal link structure and provides recommendations to improve SEO through strategic internal linking. It helps distribute authority, establish topical relevance, and improve crawlability. + +**System role**: Optimization layer skill. It turns weak pages, structures, and technical issues into prioritized repair work. + +## When This Must Trigger + +Use this when the conversation involves any of these situations — even if the user does not use SEO terminology: + +Use this whenever the task needs a diagnosis or repair plan that should feed directly into remediation work, not just a one-time opinion. + +- Improving site architecture for SEO +- Distributing authority to important pages +- Fixing orphan pages with no internal links +- Creating topic cluster internal link strategies +- Optimizing anchor text for SEO +- Recovering pages that have lost rankings +- Planning internal links for new content + +## What This Skill Does + +1. **Link Structure Analysis**: Maps current internal linking patterns +2. **Authority Flow Mapping**: Shows how PageRank flows through site +3. **Orphan Page Detection**: Finds pages with no internal links +4. **Anchor Text Optimization**: Improves anchor text diversity +5. **Topic Cluster Linking**: Creates pillar-cluster link strategies +6. **Link Opportunity Finding**: Identifies where to add links +7. **Navigation Optimization**: Improves site-wide link elements + +## Quick Start + +Start with one of these prompts. Finish with a short handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Analyze Current Structure + +``` +Analyze internal linking structure for [domain/sitemap] +``` + +``` +Find internal linking opportunities for [URL] +``` + +### Create Linking Strategy + +``` +Create internal linking plan for topic cluster about [topic] +``` + +``` +Suggest internal links for this new article: [content/URL] +``` + +### Fix Issues + +``` +Find orphan pages on [domain] +``` + +``` +Optimize anchor text across the site +``` + +## Skill Contract + +**Expected output**: a scored diagnosis, prioritized repair plan, and a short handoff summary ready for `memory/audits/`. + +- **Reads**: the current page or site state, symptoms, prior audits, and current priorities from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available. +- **Writes**: a user-facing audit or optimization plan plus a reusable summary that can be stored under `memory/audits/`. +- **Promotes**: blocking defects, repeated weaknesses, and fix priorities to `memory/open-loops.md` and `memory/decisions.md`. +- **Next handoff**: use the `Next Best Skill` below when the repair path is clear. + +## Data Sources + +> **Note:** All integrations are optional. This skill works without any API keys — users provide data manually when no tools are connected. + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +**With ~~web crawler + ~~analytics connected:** +Claude can automatically perform a full site crawl via ~~web crawler to map the complete link graph, fetch page performance metrics from ~~analytics to identify high-value pages, and analyze link flow throughout the site. This enables data-driven internal linking strategies. + +**With manual data only:** +Ask the user to provide: +1. Sitemap URL or list of important pages +2. Key page URLs that need more internal links +3. Content categories or topic clusters +4. Any existing link structure documentation + +Proceed with the analysis using provided data. Note in the output which findings are from automated crawl vs. manual review. + +## Instructions + +When a user requests internal linking optimization: + +1. **Analyze Current Internal Link Structure** + + ```markdown + ## Internal Link Structure Analysis + + ### Overview + + **Domain**: [domain] + **Total Pages Analyzed**: [X] + **Total Internal Links**: [X] + **Average Links per Page**: [X] + + ### Link Distribution + + | Links per Page | Page Count | Percentage | + |----------------|------------|------------| + | 0 (Orphan) | [X] | [X]% | + | 1-5 | [X] | [X]% | + | 6-10 | [X] | [X]% | + | 11-20 | [X] | [X]% | + | 20+ | [X] | [X]% | + + ### Top Linked Pages + + | Page | Internal Links | Authority | Notes | + |------|----------------|-----------|-------| + | [URL 1] | [X] | High | [notes] | + | [URL 2] | [X] | High | [notes] | + | [URL 3] | [X] | Medium | [notes] | + + ### Under-Linked Important Pages + + | Page | Current Links | Traffic | Recommended Links | + |------|---------------|---------|-------------------| + | [URL 1] | [X] | [X]/mo | [X]+ | + | [URL 2] | [X] | [X]/mo | [X]+ | + + **Structure Score**: [X]/10 + ``` + +2. **Identify Orphan Pages** + + ```markdown + ## Orphan Page Analysis + + ### Definition + Orphan pages have no internal links pointing to them, making them + hard for users and search engines to discover. + + ### Orphan Pages Found: [X] + + | Page | Traffic | Priority | Recommended Action | + |------|---------|----------|-------------------| + | [URL 1] | [X]/mo | High | Link from [pages] | + | [URL 2] | [X]/mo | Medium | Add to navigation | + | [URL 3] | 0 | Low | Consider deleting/redirecting | + + ### Fix Strategy + + **High Priority Orphans** (have traffic/rankings): + 1. [URL] - Add links from: [relevant pages] + 2. [URL] - Add links from: [relevant pages] + + **Medium Priority Orphans** (potentially valuable): + 1. [URL] - Add to category/tag page + 2. [URL] - Link from related content + + **Low Priority Orphans** (consider removing): + 1. [URL] - Redirect to [better page] + 2. [URL] - Delete or noindex + ``` + +3. **Analyze Anchor Text Distribution** + + > **CORE-EEAT alignment**: Internal linking quality maps to R08 (Internal Link Graph) in the CORE-EEAT benchmark -- use descriptive anchors, ensure links support topical authority. See [content-quality-auditor](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/content-quality-auditor/SKILL.md) for full audit. + + ```markdown + ## Anchor Text Analysis + + ### Current Anchor Text Patterns + + **Most Used Anchors**: + + | Anchor Text | Count | Target Pages | Assessment | + |-------------|-------|--------------|------------| + | "click here" | [X] | [X] pages | ❌ Not descriptive | + | "read more" | [X] | [X] pages | ❌ Not descriptive | + | "[exact keyword]" | [X] | [page] | ⚠️ May be over-optimized | + | "[descriptive phrase]" | [X] | [page] | ✅ Good | + + ### Anchor Text Distribution by Page + + **Page: [Important URL]** + + | Anchor Text | Source Page | Status | + |-------------|-------------|--------| + | "[anchor 1]" | [source URL] | ✅/⚠️/❌ | + | "[anchor 2]" | [source URL] | ✅/⚠️/❌ | + + **Issues Found**: + - Over-optimized anchors: [X] instances + - Generic anchors: [X] instances + - Same anchor to multiple pages: [X] instances + + ### Anchor Text Recommendations + + **For Page: [URL]** + + Current: "[current anchor]" used [X] times + + Recommended variety: + - "[variation 1]" - Use from [page type] + - "[variation 2]" - Use from [page type] + - "[variation 3]" - Use from [page type] + + **Anchor Score**: [X]/10 + ``` + +4. **Create Topic Cluster Link Strategy** — Map current pillar/cluster links, recommend link structure, list specific links to add + + > **Reference**: See [references/linking-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/references/linking-templates.md) for the topic cluster link strategy template (Step 4). + +5. **Find Contextual Link Opportunities** — Analyze each page for topic-relevant link opportunities, prioritize high-impact additions + + > **Reference**: See [references/linking-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/references/linking-templates.md) for the contextual link opportunities template (Step 5). + +6. **Optimize Navigation and Footer Links** — Analyze main/footer/sidebar/breadcrumb navigation, recommend pages to add or remove + + > **Reference**: See [references/linking-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/references/linking-templates.md) for the navigation optimization template (Step 6). + +7. **Generate Link Implementation Plan** — Executive summary, current state metrics, phased priority actions (weeks 1-4+), implementation guide, tracking plan + + > **Reference**: See [references/linking-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/references/linking-templates.md) for the full implementation plan template (Step 7). + +## Validation Checkpoints + +### Input Validation +- [ ] Site structure or sitemap provided (URL or file) +- [ ] Target pages or topic clusters clearly defined +- [ ] If optimizing specific page, page URL or content provided + +### Output Validation +- [ ] Every recommendation cites specific data points (not generic advice) +- [ ] All link suggestions include source page, target page, and recommended anchor text +- [ ] Orphan page lists include URLs and recommended actions +- [ ] Source of each data point clearly stated (~~web crawler data, ~~analytics, user-provided, or manual analysis) + +## Example + +> **Reference**: See [references/linking-example.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/references/linking-example.md) for a full worked example (email marketing best practices internal linking opportunities). + +## Tips for Success + +1. **Quality over quantity** - Add relevant links, not random ones +2. **User-first thinking** - Links should help users navigate +3. **Vary anchor text** - Avoid over-optimization +4. **Link to important pages** - Distribute authority strategically +5. **Regular audits** - Internal links need maintenance as content grows + + +### Save Results + +After delivering audit or optimization findings to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to `memory/audits/internal-linking-optimizer/YYYY-MM-DD-.md` containing: +- One-line verdict or headline finding +- Top 3-5 actionable items +- Open loops or blockers +- Source data references + +If any veto-level issue was found (CORE-EEAT T04, C01, R10 or CITE T03, T05, T09), also append a one-liner to `memory/hot-cache.md` without asking. + +## Reference Materials + +- [Link Architecture Patterns](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/references/link-architecture-patterns.md) — Architecture models (hub-and-spoke, silo, flat, pyramid, mesh), anchor text diversity framework, link equity flow model, and internal link audit checklist +- [Linking Templates](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/references/linking-templates.md) — Detailed output templates for steps 6-7 (navigation optimization, implementation plan) +- [Linking Example](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/references/linking-example.md) — Full worked example for internal linking opportunities + +## Next Best Skill + +- **Primary**: [on-page-seo-auditor](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/SKILL.md) — verify that revised internal links support the page-level goals. diff --git a/.cursor/skills/internal-linking-optimizer/references/link-architecture-patterns.md b/.cursor/skills/internal-linking-optimizer/references/link-architecture-patterns.md new file mode 100644 index 0000000000..24d2f3de2f --- /dev/null +++ b/.cursor/skills/internal-linking-optimizer/references/link-architecture-patterns.md @@ -0,0 +1,362 @@ +# Link Architecture Patterns + +Detailed architecture models with implementation guides, migration strategies, and measurement frameworks for internal linking optimization. + +## Architecture Model Deep Dives + +### 1. Hub-and-Spoke (Topic Cluster) Model + +#### Overview + +The hub-and-spoke model organizes content around central "pillar" pages (hubs) that link to and from related "cluster" articles (spokes). This is the most widely recommended architecture for content-driven sites targeting topical authority. + +#### Structure Diagram + +``` + ┌──────────────┐ + │ Homepage │ + └──────┬───────┘ + │ + ┌──────────────┼──────────────┐ + │ │ │ + ┌──────▼──────┐ ┌────▼────┐ ┌──────▼──────┐ + │ Hub A │ │ Hub B │ │ Hub C │ + │ (Pillar) │ │(Pillar) │ │ (Pillar) │ + └──┬───┬───┬──┘ └────┬────┘ └──┬───┬───┬──┘ + │ │ │ │ │ │ │ + A1 A2 A3 B1 B2 C1 C2 C3 + └───┼───┘ └───┼───┘ + cross-links cross-links +``` + +#### Implementation Steps + +1. **Identify 3-7 core topics** that define your business expertise +2. **Create pillar pages** (2,000-5,000 words) that broadly cover each core topic +3. **Map cluster articles** (800-2,000 words) that dive deep into subtopics +4. **Implement bidirectional links**: every cluster article links to its pillar, every pillar links to all its clusters +5. **Add cross-links** between related cluster articles within the same hub +6. **Add bridge links** between hubs where subtopics overlap + +#### Link Rules + +| Link Type | Direction | Anchor Text Strategy | +|-----------|-----------|---------------------| +| Pillar → Cluster | Pillar links to each cluster | Descriptive: "learn about [subtopic]" | +| Cluster → Pillar | Every cluster links back to pillar | Partial match: "our complete [topic] guide" | +| Cluster ↔ Cluster | Between related clusters in same hub | Natural: "as we covered in [related article]" | +| Hub ↔ Hub (bridge) | Between related pillar pages | Branded/natural: "see also our [topic] resource" | + +#### When to Use +- Content marketing sites and blogs +- SaaS companies building topical authority +- Publishers covering defined topic areas +- Any site with 50-500 content pages + +#### Measurement + +| Metric | Target | Tool | +|--------|--------|------| +| Pillar page rankings for head terms | Top 10 | Rank tracker | +| Cluster article rankings for long-tail | Top 20 | Rank tracker | +| Internal links per cluster article | 3-5 minimum | Crawl report | +| Click depth from homepage to cluster | ≤3 clicks | Crawl report | +| Organic traffic to hub pages | Month-over-month growth | Analytics | + +--- + +### 2. Silo Structure + +#### Overview + +The silo model creates strict vertical hierarchies where content is organized into isolated "silos" (categories). Links flow vertically within a silo but rarely cross between silos. This concentrates topical relevance within each silo. + +#### Structure Diagram + +``` + ┌──────────────┐ + │ Homepage │ + └──────┬───────┘ + │ + ┌─────────────────┼─────────────────┐ + │ │ │ + ┌────▼─────┐ ┌────▼─────┐ ┌────▼─────┐ + │ Silo A │ │ Silo B │ │ Silo C │ + │ Category │ │ Category │ │ Category │ + └────┬─────┘ └────┬─────┘ └────┬─────┘ + │ │ │ + ┌────▼─────┐ ┌────▼─────┐ ┌────▼─────┐ + │ Sub-cat │ │ Sub-cat │ │ Sub-cat │ + └────┬─────┘ └────┬─────┘ └────┬─────┘ + │ │ │ + ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ + │ Pages │ │ Pages │ │ Pages │ + └─────────┘ └─────────┘ └─────────┘ + + No horizontal links between silos (strict model) +``` + +#### Implementation Steps + +1. **Define 5-15 top-level categories** (silos) based on your product/service taxonomy +2. **Create category landing pages** with overview content and links to subcategories +3. **Build subcategory pages** linking down to individual product/content pages +4. **Enforce vertical linking**: pages link up to their parent and down to their children +5. **Use breadcrumbs** to reinforce the hierarchy visually and structurally +6. **Limit cross-silo links** to only the most relevant connections (strict model) or allow them strategically (modified model) + +#### Link Rules + +| Link Type | Direction | Allowed? | +|-----------|-----------|----------| +| Parent → Child | Downward within silo | Always | +| Child → Parent | Upward within silo | Always | +| Sibling ↔ Sibling | Horizontal within same parent | Yes | +| Cross-silo | Between different silos | Strict: No. Modified: Sparingly | +| All pages → Homepage | Upward to root | Yes (via navigation) | + +#### When to Use +- Large e-commerce sites (100+ product categories) +- Directory sites with clear taxonomy +- Sites where categories are truly distinct topics +- Enterprises with separate business lines + +#### Limitations +- Overly strict silos can trap link equity in one branch +- Cross-topic content becomes difficult to place +- Users may need to navigate up and over to find related content +- Modified silo (allowing some cross-links) often works better in practice + +--- + +### 3. Flat Architecture + +#### Overview + +A flat architecture keeps all pages within 2-3 clicks of the homepage. There is minimal hierarchy; instead, pages are broadly interlinked. This maximizes crawlability and distributes link equity evenly. + +#### Structure Diagram + +``` + ┌──────────┐ + │ Homepage │ + └────┬─────┘ + │ + ┌──────────────┼──────────────┐ + │ │ │ │ │ │ │ + P1 P2 P3 P4 P5 P6 P7 + └────┼────┼────┼────┼────┼────┘ + └────┴────┴────┘ + (cross-linked freely) +``` + +#### Implementation Steps + +1. **Link all key pages from the homepage** (directly or via a comprehensive sitemap page) +2. **Keep URL structure shallow**: /category/page, not /category/subcategory/year/page +3. **Cross-link freely** between related pages at the same level +4. **Use comprehensive navigation** menus, footer links, or HTML sitemaps +5. **Limit total pages** to keep the architecture manageable + +#### When to Use +- Small sites with fewer than 100 pages +- Portfolio sites +- Small business brochure sites +- Startups with limited content + +#### Scaling Limits + +| Site Size | Flat Architecture Feasibility | +|-----------|------------------------------| +| <50 pages | Ideal | +| 50-100 pages | Manageable with good navigation | +| 100-500 pages | Difficult; consider hub-and-spoke | +| 500+ pages | Not recommended; switch to hierarchical model | + +--- + +### 4. Pyramid Architecture + +#### Overview + +The pyramid model mirrors traditional website hierarchies: a single homepage at the top, branching into categories, subcategories, and finally individual pages. Authority flows from top to bottom, concentrating at higher levels. + +#### Structure Diagram + +``` +Level 0: Homepage + / \ +Level 1: Category A Category B + / \ / \ +Level 2: Sub A1 Sub A2 Sub B1 Sub B2 + / \ / \ / \ / \ +Level 3: P1 P2 P3 P4 P5 P6 P7 P8 +``` + +#### Implementation Steps + +1. **Design a clear hierarchy** with 3-4 levels maximum +2. **Homepage links to all top-level categories** prominently +3. **Category pages link to all subcategories** within them +4. **Subcategory pages link to all child pages** +5. **Implement breadcrumbs** to support the hierarchy +6. **Add "related content" cross-links** at the page level to offset authority concentration + +#### Authority Flow Considerations + +| Level | Typical Authority | Action to Improve | +|-------|-------------------|-------------------| +| Homepage | Highest | Ensure links to priority categories are prominent | +| Categories | High | Link from blog content, not just navigation | +| Subcategories | Medium | Add contextual links from other sections | +| Individual pages | Lowest | Cross-link, feature in "popular posts" widgets | + +#### When to Use +- News and media sites +- Large blogs (500+ posts) +- Corporate sites with many divisions +- Government/educational sites + +--- + +### 5. Mesh/Matrix Architecture + +#### Overview + +The mesh model allows free-form linking between any related pages, regardless of hierarchy. Every page can link to any other relevant page. This creates a dense web of connections, similar to Wikipedia's link structure. + +#### Structure Diagram + +``` + P1 ←──→ P2 ←──→ P3 + ↕ ╲ ↕ ╱ ↕ + P4 ←──→ P5 ←──→ P6 + ↕ ╱ ↕ ╲ ↕ + P7 ←──→ P8 ←──→ P9 +``` + +#### Implementation Steps + +1. **Set linking rules** to prevent chaos: link only when topically relevant +2. **Use contextual anchors** that describe the destination page +3. **Set a link budget** per page (5-15 contextual links per 1,000 words) +4. **Review link density regularly** to prune irrelevant connections +5. **Maintain a link map** (spreadsheet or tool) to track the network + +#### Governance Rules + +| Rule | Purpose | +|------|---------| +| Every link must have topical relevance | Prevents link dilution | +| Maximum 15 contextual links per 1,000 words | Prevents link farms | +| Review links quarterly | Prunes outdated connections | +| Use descriptive anchor text only | Maintains semantic value | +| No reciprocal link trading between unrelated pages | Prevents manipulation patterns | + +#### When to Use +- Knowledge bases and documentation sites +- Wikis and encyclopedias +- Research repositories +- FAQ/help center sites + +--- + +## Migration Between Models + +### Common Migration Paths + +| From | To | Reason | Difficulty | +|------|----|--------|-----------| +| Flat → Hub-and-Spoke | Site grew beyond 100 pages | Medium | +| Silo → Hub-and-Spoke | Silos too rigid, need cross-topic links | Medium | +| Pyramid → Hub-and-Spoke | Want to build topical clusters | High | +| No structure → Any model | Starting from disorganized state | High | +| Hub-and-Spoke → Hybrid | Need both clusters and strict categories | Medium | + +### Migration Steps (General) + +1. **Audit current state**: Map all existing internal links using a crawler +2. **Design target architecture**: Choose model, map pages to their new positions +3. **Create a link change plan**: Document every link addition, removal, and anchor text change +4. **Implement in phases**: Start with highest-priority cluster/silo, then expand +5. **Preserve existing equity**: Do not remove links that pass significant value without replacement +6. **Monitor impact**: Track rankings and traffic for 4-8 weeks after each phase +7. **Iterate**: Adjust the plan based on measured results + +### Migration Risk Mitigation + +| Risk | Mitigation | +|------|-----------| +| Temporary ranking drops | Migrate one section at a time, not all at once | +| Broken internal links | Run crawl after each phase to verify | +| Lost link equity | Ensure no orphan pages created during migration | +| Anchor text disruption | Change anchors gradually, not all at once | + +--- + +## Measurement Framework + +### Key Metrics by Architecture Model + +| Metric | Hub-and-Spoke | Silo | Flat | Pyramid | Mesh | +|--------|---------------|------|------|---------|------| +| Avg click depth | ≤3 | ≤4 | ≤2 | ≤4 | ≤3 | +| Orphan pages | 0 | 0 | 0 | 0 | 0 | +| Avg internal links per page | 5-10 | 3-7 | 8-15 | 3-5 | 8-15 | +| Cross-section links | Many | Few | N/A | Some | Many | +| Authority concentration | Distributed to hubs | Concentrated in silo tops | Even | Top-heavy | Even | + +### Monthly Monitoring Checklist + +| Check | Tool | Action if Failing | +|-------|------|-------------------| +| Orphan pages count | Crawl report | Add internal links immediately | +| Average click depth | Crawl report | Add shortcuts to deep pages | +| Crawl depth distribution | Crawl report | Flatten deep branches | +| Internal link count per page | Crawl report | Add links to under-linked pages | +| Anchor text diversity | Manual audit | Vary anchors for over-optimized pages | +| Broken internal links | Crawl report | Fix or remove broken links | +| New content linked within 48 hours | Editorial process | Add to related pages upon publishing | + +### ROI Estimation + +| Architecture Change | Typical Impact | Timeline to See Results | +|--------------------|---------------|----------------------| +| Fix orphan pages | +15-30% traffic to those pages | 2-4 weeks | +| Build first topic cluster | +10-25% traffic to cluster pages | 4-8 weeks | +| Reduce click depth by 1 level | +5-15% crawl efficiency | 2-6 weeks | +| Anchor text optimization | +5-10% ranking improvement for target terms | 4-12 weeks | +| Full architecture migration | +20-50% overall organic traffic | 3-6 months | + +--- + +## Hybrid Architecture Strategies + +Most real-world sites combine elements from multiple models. Common hybrid patterns: + +### Hub-and-Spoke + Silo (Recommended for Medium-Large Sites) + +``` +Homepage + ├── Category Silo A + │ ├── Hub A1 (pillar) ←→ Cluster articles + │ └── Hub A2 (pillar) ←→ Cluster articles + ├── Category Silo B + │ ├── Hub B1 (pillar) ←→ Cluster articles + │ └── Hub B2 (pillar) ←→ Cluster articles + └── Cross-category bridge links (A1 ↔ B2 where relevant) +``` + +- **Silos** provide category organization for navigation and URL structure +- **Hubs** within each silo build topical authority for specific keyword clusters +- **Bridge links** connect related content across silos where user intent overlaps + +### Implementation Priority Order + +1. Fix structural issues first (orphan pages, broken links) +2. Implement primary architecture model +3. Add cross-linking strategy +4. Optimize anchor text +5. Monitor and iterate + +This order ensures each phase builds on a solid foundation rather than optimizing details on a broken structure. diff --git a/.cursor/skills/internal-linking-optimizer/references/linking-example.md b/.cursor/skills/internal-linking-optimizer/references/linking-example.md new file mode 100644 index 0000000000..ef8703eea6 --- /dev/null +++ b/.cursor/skills/internal-linking-optimizer/references/linking-example.md @@ -0,0 +1,42 @@ +# Internal Linking Optimizer — Worked Example + +Referenced from [SKILL.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/SKILL.md). + +--- + +## Worked Example + +**User**: "Find internal linking opportunities for my blog post about 'email marketing best practices'" + +**Output**: + +```markdown +## Internal Linking Opportunities + +**Page**: /blog/email-marketing-best-practices/ +**Current Internal Links**: 2 + +### Recommended Links to Add + +| Section | Text to Link | Target Page | Anchor | +|---------|--------------|-------------|--------| +| Para 2 | "building your email list" | /blog/grow-email-list/ | "building your email list" | +| Para 5 | "subject lines" | /blog/email-subject-lines/ | "write compelling subject lines" | +| Section on segmentation | "audience segments" | /blog/email-segmentation-guide/ | "segment your audience" | +| CTA section | "marketing automation" | /services/email-automation/ | "email automation services" | +| Conclusion | "email marketing tools" | /blog/best-email-tools/ | "top email marketing tools" | + +### Pages That Should Link TO This Article + +| Source Page | Location | Anchor Text | +|-------------|----------|-------------| +| /blog/digital-marketing-guide/ | Email section | "email marketing best practices" | +| /services/marketing-services/ | Related content | "email marketing strategies" | +| /blog/lead-generation-tips/ | Email mention | "email marketing techniques" | + +### Priority Actions + +1. Add 5 outbound internal links (listed above) +2. Request 3 inbound links from related pages +3. Add to "Marketing" category page +``` diff --git a/.cursor/skills/internal-linking-optimizer/references/linking-templates.md b/.cursor/skills/internal-linking-optimizer/references/linking-templates.md new file mode 100644 index 0000000000..ce5e1e4c40 --- /dev/null +++ b/.cursor/skills/internal-linking-optimizer/references/linking-templates.md @@ -0,0 +1,219 @@ +# Internal Linking Optimizer — Output Templates + +Detailed output templates for internal-linking-optimizer steps 4-7. Referenced from [SKILL.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/SKILL.md). + +--- + +## Step 4: Create Topic Cluster Link Strategy + +```markdown +## Topic Cluster Internal Linking + +### Cluster: [Main Topic] + +**Pillar Page**: [URL] +**Cluster Articles**: [X] + +### Current Link Map + +``` +[Pillar Page] + ├── [Cluster Article 1] ←→ [linked?] + ├── [Cluster Article 2] ←→ [linked?] + ├── [Cluster Article 3] ←→ [linked?] + └── [Cluster Article 4] ←→ [linked?] +``` + +### Recommended Link Structure + +``` +[Pillar Page] + ├── Links TO all cluster articles ✅ + │ + ├── [Cluster Article 1] + │ ├── Link TO pillar ✅ + │ └── Link TO related cluster articles + │ + ├── [Cluster Article 2] + │ ├── Link TO pillar ✅ + │ └── Link TO related cluster articles + │ + └── [etc.] +``` + +### Links to Add + +| From Page | To Page | Anchor Text | Location | +|-----------|---------|-------------|----------| +| [URL 1] | [URL 2] | "[anchor]" | [paragraph/section] | +| [URL 2] | [URL 3] | "[anchor]" | [paragraph/section] | +| [Pillar] | [Cluster 1] | "[anchor]" | [section] | +``` + +--- + +## Step 5: Find Contextual Link Opportunities + +```markdown +## Contextual Link Opportunities + +### Link Opportunity Analysis + +For each page, find relevant pages to link to based on: +- Topic relevance +- Keyword overlap +- User journey logic +- Authority distribution needs + +### Opportunities Found + +**Page: [URL 1]** +**Topic**: [topic] +**Current internal links**: [X] + +| Opportunity | Target Page | Anchor Text | Why Link | +|-------------|-------------|-------------|----------| +| Paragraph 2 mentions "[topic]" | [URL] | "[topic phrase]" | Topic match | +| Section on "[subject]" | [URL] | "[anchor]" | Related guide | +| CTA at end | [URL] | "[anchor]" | User journey | + +**Page: [URL 2]** +[Continue for each page...] + +### Priority Link Additions + +**High Impact Links** (add these first): + +1. **From**: [Source URL] + **To**: [Target URL] + **Anchor**: "[anchor text]" + **Why**: [reason - e.g., "Target page needs authority boost"] + **Where to add**: [specific location in content] + +2. **From**: [Source URL] + **To**: [Target URL] + [etc.] +``` + +--- + +## Step 6: Optimize Navigation and Footer Links + +```markdown +## Site-Wide Link Optimization + +### Current Navigation Analysis + +**Main Navigation**: +- Links present: [list] +- Missing important pages: [list] +- Too many links: [Yes/No] + +**Footer Navigation**: +- Links present: [list] +- SEO value: [assessment] + +### Navigation Recommendations + +| Element | Current | Recommended | Reason | +|---------|---------|-------------|--------| +| Main nav | [X] links | [Y] links | [reason] | +| Footer | [X] links | [Y] links | [reason] | +| Sidebar | [status] | [recommendation] | [reason] | +| Breadcrumbs | [status] | [recommendation] | [reason] | + +### Pages to Add to Navigation + +1. [Page] - Add to [location] because [reason] +2. [Page] - Add to [location] because [reason] + +### Pages to Remove from Navigation + +1. [Page] - Move to [footer/remove] because [reason] +``` + +--- + +## Step 7: Generate Link Implementation Plan + +```markdown +# Internal Linking Optimization Plan + +**Site**: [domain] +**Analysis Date**: [date] + +## Executive Summary + +- Total link opportunities found: [X] +- Orphan pages to fix: [X] +- Estimated traffic impact: [+X%] +- Priority actions: [X] + +## Current State + +| Metric | Current | Target | Gap | +|--------|---------|--------|-----| +| Avg links per page | [X] | [X] | [X] | +| Orphan pages | [X] | 0 | [X] | +| Over-optimized anchors | [X]% | <10% | [X]% | +| Topic cluster coverage | [X]% | 100% | [X]% | + +## Priority Actions + +### Phase 1: Critical Fixes (Week 1) + +**Fix Orphan Pages**: +- [ ] [URL] - Add links from [X] pages +- [ ] [URL] - Add links from [X] pages + +**High-Value Link Additions**: +- [ ] Link [Page A] to [Page B] with "[anchor]" +- [ ] Link [Page A] to [Page C] with "[anchor]" + +### Phase 2: Topic Clusters (Week 2-3) + +**Cluster 1: [Topic]** +- [ ] Ensure pillar links to all [X] cluster articles +- [ ] Add [X] cross-links between cluster articles + +**Cluster 2: [Topic]** +- [ ] [Tasks] + +### Phase 3: Optimization (Week 4+) + +**Anchor Text Diversity**: +- [ ] Vary anchors for [Page] - currently [X]% exact match +- [ ] [Additional tasks] + +**Navigation Updates**: +- [ ] Add [Page] to main navigation +- [ ] Update footer links + +## Implementation Guide + +### Adding Internal Links + +Best practices: +1. Add links contextually within content +2. Use descriptive anchor text (not "click here") +3. Link to relevant, helpful pages +4. Aim for 3-10 internal links per 1,000 words +5. Vary anchor text for the same target + +### Anchor Text Guidelines + +| Type | Example | Usage | +|------|---------|-------| +| Exact match | "keyword research" | 10-20% | +| Partial match | "tips for keyword research" | 30-40% | +| Branded | "Brand's guide to..." | 10-20% | +| Natural | "this article", "learn more" | 20-30% | + +## Tracking Success + +Monitor these metrics weekly: +- [ ] Rankings for target keywords +- [ ] Traffic to previously orphan pages +- [ ] Crawl stats in ~~search console +- [ ] Internal link distribution changes +``` diff --git a/.cursor/skills/keyword-research/SKILL.md b/.cursor/skills/keyword-research/SKILL.md new file mode 100644 index 0000000000..fdbb208b11 --- /dev/null +++ b/.cursor/skills/keyword-research/SKILL.md @@ -0,0 +1,435 @@ +--- +name: keyword-research +description: 'Find high-value SEO keywords: search volume, difficulty, intent classification, topic clusters. 关键词研究/内容选题' +version: "6.0.0" +license: Apache-2.0 +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when starting keyword research for a new page, topic, or campaign. Also when the user asks about search volume, keyword difficulty, topic clusters, long-tail keywords, or what to write about." +argument-hint: " [market/language]" +metadata: + author: aaron-he-zhu + version: "6.0.0" + geo-relevance: "medium" + tags: + - seo + - geo + - keywords + - keyword-research + - search-volume + - keyword-difficulty + - topic-clusters + - long-tail-keywords + - search-intent + - content-calendar + - ahrefs + - semrush + - google-keyword-planner + - 关键词研究 + - SEO关键词 + - キーワード調査 + - 키워드분석 + - palabras-clave + triggers: + # EN-formal + - "keyword research" + - "find keywords" + - "keyword analysis" + - "keyword discovery" + - "search volume analysis" + - "keyword difficulty" + - "topic research" + - "identify ranking opportunities" + # EN-casual + - "what should I write about" + - "what are people searching for" + - "what are people googling" + - "find me topics to write" + - "give me keyword ideas" + - "which keywords should I target" + - "why is my traffic low" + - "I need content ideas" + # EN-question + - "how do I find good keywords" + - "what keywords should I target" + - "how competitive is this keyword" + # EN-competitor + - "Ahrefs keyword explorer alternative" + - "Semrush keyword magic tool" + - "Google Keyword Planner alternative" + - "Ubersuggest alternative" + # ZH-pro + - "关键词研究" + - "关键词分析" + - "搜索量查询" + - "关键词难度" + - "SEO关键词" + - "长尾关键词" + - "词库整理" + - "关键词布局" + - "关键词挖掘" + # ZH-casual + - "写什么内容好" + - "找选题" + - "帮我挖词" + - "不知道写什么" + - "查关键词" + - "选词" + - "帮我找词" + # JA + - "キーワード調査" + - "キーワードリサーチ" + - "SEOキーワード分析" + - "検索ボリューム" + - "ロングテールキーワード" + - "検索意図分析" + # KO + - "키워드 리서치" + - "키워드 분석" + - "검색량 분석" + - "키워드 어떻게 찾아요?" + - "검색어 분석" + - "경쟁도 낮은 키워드는?" + # ES + - "investigación de palabras clave" + - "análisis de palabras clave" + - "volumen de búsqueda" + - "posicionamiento web" + - "cómo encontrar palabras clave" + # PT + - "pesquisa de palavras-chave" + # Misspellings + - "keywrod research" + - "keywork research" +--- + +# Keyword Research + + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This research skill follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + + +Discovers, analyzes, and prioritizes keywords for SEO and GEO content strategies. Identifies high-value opportunities based on search volume, competition, intent, and business relevance. + +**System role**: Research layer skill. It turns market signals into reusable strategic inputs for the rest of the library. + +## When This Must Trigger + +Use this when the conversation involves any of these situations — even if the user does not use SEO terminology: + +Use this whenever the task needs reusable market intelligence that should influence strategy, not just an ad hoc answer. + +- Starting a new content strategy or campaign +- Expanding into new topics or markets +- Finding keywords for a specific product or service +- Identifying long-tail keyword opportunities +- Understanding search intent for your industry +- Planning content calendars +- Researching keywords for GEO optimization + +## What This Skill Does + +1. **Keyword Discovery**: Generates comprehensive keyword lists from seed terms +2. **Intent Classification**: Categorizes keywords by user intent (informational, navigational, commercial, transactional) +3. **Difficulty Assessment**: Evaluates competition level and ranking difficulty +4. **Opportunity Scoring**: Prioritizes keywords by potential ROI +5. **Clustering**: Groups related keywords into topic clusters +6. **GEO Relevance**: Identifies keywords likely to trigger AI responses + +## Quick Start + +Start with one of these prompts. Finish with a short handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Basic Keyword Research + +``` +Research keywords for [topic/product/service] +``` + +``` +Find keyword opportunities for a [industry] business targeting [audience] +``` + +### With Specific Goals + +``` +Find low-competition keywords for [topic] with commercial intent +``` + +``` +Identify question-based keywords for [topic] that AI systems might answer +``` + +### Competitive Research + +``` +What keywords is [competitor URL] ranking for that I should target? +``` + +## Skill Contract + +**Expected output**: a prioritized research brief, evidence-backed findings, and a short handoff summary ready for `memory/research/`. + +- **Reads**: user goals, target market inputs, available tool data, and prior strategy from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available. +- **Writes**: a user-facing research deliverable plus a reusable summary that can be stored under `memory/research/`. +- **Promotes**: durable keyword priorities, competitor facts, entity candidates, and strategic decisions to `CLAUDE.md`, `memory/decisions.md`, and `memory/research/`; hand canonical entity work to `entity-optimizer`. +- **Next handoff**: use the `Next Best Skill` below when the findings are ready to drive action. + +## Data Sources + +> **Note:** All integrations are optional. This skill works without any API keys — users provide data manually when no tools are connected. + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +**With ~~SEO tool + ~~search console connected:** +Automatically pull historical search volume data, keyword difficulty scores, SERP analysis, current rankings from ~~search console, and competitor keyword overlap. The skill will fetch seed keyword metrics, related keyword suggestions, and search trend data. + +**With manual data only:** +Ask the user to provide: +1. Seed keywords or topic description +2. Target audience and geographic location +3. Business goals (traffic, leads, sales) +4. Current domain authority (if known) or site age +5. Any known keyword performance data or search volume estimates + +Proceed with the full analysis using provided data. Note in the output which metrics are from automated collection vs. user-provided data. + +## Instructions + +When a user requests keyword research: + +At the start of each phase, announce: **[Phase X/8: Name]** so the user can track progress. + +### Phase 1/8: Scope + + Ask clarifying questions if not provided: + - What is your product/service/topic? + - Who is your target audience? + - What is your business goal? (traffic, leads, sales) + - What is your current domain authority? (new site, established, etc.) + - Any specific geographic targeting? + - Preferred language? + +### Phase 2/8: Discover + + Start with: + - Core product/service terms + - Problem-focused keywords (what issues do you solve?) + - Solution-focused keywords (how do you help?) + - Audience-specific terms + - Industry terminology + +### Phase 3/8: Variations + + For each seed keyword, generate variations: + + ```markdown + ## Keyword Expansion Patterns + + ### Modifiers + - Best [keyword] + - Top [keyword] + - [keyword] for [audience] + - [keyword] near me + - [keyword] [year] + - How to [keyword] + - What is [keyword] + - [keyword] vs [alternative] + - [keyword] examples + - [keyword] tools + + ### Long-tail Variations + - [keyword] for beginners + - [keyword] for small business + - Free [keyword] + - [keyword] software/tool/service + - [keyword] template + - [keyword] checklist + - [keyword] guide + ``` + +### Phase 4/8: Classify + + Categorize each keyword: + + | Intent | Signals | Example | Content Type | + |--------|---------|---------|--------------| + | Informational | what, how, why, guide, learn | "what is SEO" | Blog posts, guides | + | Navigational | brand names, specific sites | "google analytics login" | Homepage, product pages | + | Commercial | best, review, vs, compare | "best SEO tools [current year]" | Comparison posts, reviews | + | Transactional | buy, price, discount, order | "buy SEO software" | Product pages, pricing | + +### Phase 5/8: Score + + Score each keyword (1-100 scale): + + ```markdown + ### Difficulty Factors + + **High Difficulty (70-100)** + - Major brands ranking + - High domain authority competitors + - Established content (1000+ backlinks) + - Paid ads dominating SERP + + **Medium Difficulty (40-69)** + - Mix of authority and niche sites + - Some opportunities for quality content + - Moderate backlink requirements + + **Low Difficulty (1-39)** + - Few authoritative competitors + - Thin or outdated content ranking + - Long-tail variations + - New or emerging topics + ``` + +#### Opportunity Score + + Formula: `Opportunity = (Volume × Intent Value) / Difficulty` + + **Intent Value** assigns a numeric weight by search intent: + - Informational = 1 + - Navigational = 1 + - Commercial = 2 + - Transactional = 3 + + ```markdown + ### Opportunity Matrix + + | Scenario | Volume | Difficulty | Intent | Priority | + |----------|--------|------------|--------|----------| + | Quick Win | Low-Med | Low | High | ⭐⭐⭐⭐⭐ | + | Growth | High | Medium | High | ⭐⭐⭐⭐ | + | Long-term | High | High | High | ⭐⭐⭐ | + | Research | Low | Low | Low | ⭐⭐ | + ``` + +### Phase 6/8: GEO-Check — AI Answer Overlap + + Keywords likely to trigger AI responses: + + ```markdown + ### GEO-Relevant Keywords + + **High GEO Potential** + - Question formats: "What is...", "How does...", "Why is..." + - Definition queries: "[term] meaning", "[term] definition" + - Comparison queries: "[A] vs [B]", "difference between..." + - List queries: "best [category]", "top [number] [items]" + - How-to queries: "how to [action]", "steps to [goal]" + + **AI Answer Indicators** + - Query is factual/definitional + - Answer can be summarized concisely + - Topic is well-documented online + - Low commercial intent + ``` + +### Phase 7/8: Cluster + + Group keywords into content clusters: + + ```markdown + ## Topic Cluster: [Main Topic] + + **Pillar Content**: [Primary keyword] + - Search volume: [X] + - Difficulty: [X] + - Content type: Comprehensive guide + + **Cluster Content**: + + ### Sub-topic 1: [Secondary keyword] + - Volume: [X] + - Difficulty: [X] + - Links to: Pillar + - Content type: [Blog post/Tutorial/etc.] + + ### Sub-topic 2: [Secondary keyword] + - Volume: [X] + - Difficulty: [X] + - Links to: Pillar + Sub-topic 1 + - Content type: [Blog post/Tutorial/etc.] + + [Continue for all cluster keywords...] + ``` + +### Phase 8/8: Deliver + + Produce a report containing: Executive Summary, Top Keyword Opportunities (Quick Wins, Growth, GEO), Topic Clusters, Content Calendar, and Next Steps. + + **Quality bar** — every recommendation must include at least one specific number. If it reads like the left column, rewrite it before including. + + | ❌ Generic (rewrite before including) | ✅ Actionable | + |---|---| + | "Target long-tail keywords for better results" | "Target 'project management for nonprofits' (vol: 320, KD: 22) — no DR>40 sites in top 10" | + | "This keyword has good potential" | "Opportunity 8.4: vol 4,800, KD 28, transactional intent — gap analysis shows no content updated since 2023 in top 5" | + | "Consider creating content around this topic" | "Write '[Tool A] vs [Tool B] for small teams' — 1,200/mo searches, current #1 is a 2022 article with 12 backlinks" | + | "Optimize your page for this keyword" | "Add primary keyword to H1 (currently missing), write a 40-word direct answer in paragraph 1, add 3 internal links from your /blog/ cluster" | + + > **Reference**: See [references/example-report.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/keyword-research/references/example-report.md) for the full report template and example. + +## Validation Checkpoints + +### Input Validation +- [ ] Seed keywords or topic description clearly provided +- [ ] Target audience and business goals specified +- [ ] Geographic and language targeting confirmed +- [ ] Domain authority or site maturity level established + +### Output Validation +- [ ] Every recommendation cites specific data points (not generic advice) +- [ ] Search volume and difficulty scores included for each keyword +- [ ] Keywords grouped by intent and mapped to content types +- [ ] Topic clusters show clear pillar-to-cluster relationships +- [ ] Source of each data point clearly stated (~~SEO tool data, user-provided, or estimated) + +## Example + +> **Reference**: See [references/example-report.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/keyword-research/references/example-report.md) for a complete example report for "project management software for small businesses". + +### Advanced Usage + +- **Intent Mapping**: `Map all keywords for [topic] by search intent and funnel stage` +- **Seasonal Analysis**: `Identify seasonal keyword trends for [industry]` +- **Competitor Gap**: `What keywords do [competitor 1], [competitor 2] rank for that I'm missing?` +- **Local Keywords**: `Research local keywords for [business type] in [city/region]` + +## Tips for Success + +1. **Start with seed keywords** that describe your core offering +2. **Don't ignore long-tail** - they often have highest conversion rates +3. **Match content to intent** - informational queries need guides, not sales pages +4. **Group into clusters** for topical authority +5. **Prioritize quick wins** to build momentum and credibility +6. **Include GEO keywords** in your strategy for AI visibility +7. **Review quarterly** - keyword dynamics change over time + + + +### Save Results + +After delivering findings to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to `memory/research/keyword-research/YYYY-MM-DD-.md` containing: +- One-line headline finding +- Top 3-5 actionable items +- Open loops or blockers +- Source data references + +If any findings should influence ongoing strategy, recommend promoting key conclusions to `memory/hot-cache.md`. + +## Reference Materials + +- [Keyword Intent Taxonomy](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/keyword-research/references/keyword-intent-taxonomy.md) — Complete intent classification with signal words and content strategies +- [Topic Cluster Templates](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/keyword-research/references/topic-cluster-templates.md) — Hub-and-spoke architecture templates for pillar and cluster content +- [Keyword Prioritization Framework](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/keyword-research/references/keyword-prioritization-framework.md) — Priority scoring matrix, categories, and seasonal keyword patterns +- [Example Report](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/keyword-research/references/example-report.md) — Complete example keyword research report for project management software + +## Next Best Skill + +- **Primary**: [competitor-analysis](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/competitor-analysis/SKILL.md) — turn keyword opportunities into a competitive benchmark. diff --git a/.cursor/skills/keyword-research/references/example-report.md b/.cursor/skills/keyword-research/references/example-report.md new file mode 100644 index 0000000000..3c0a0f495a --- /dev/null +++ b/.cursor/skills/keyword-research/references/example-report.md @@ -0,0 +1,96 @@ +# Keyword Research — Example Report + +This is a complete example output showing the expected format for keyword research deliverables. + +## Prompt + +**User**: "Research keywords for a project management software company targeting small businesses" + +## Example Output + +```markdown +# Keyword Research Report: Project Management Software + +**Generated**: [current month and year] +**Target Audience**: Small business owners and teams +**Business Goal**: Software signups and trials + +## Executive Summary + +- Total keywords analyzed: 150+ +- High-priority opportunities: 23 +- Estimated traffic potential: 45,000/month +- Recommended focus areas: + - Task management workflows + - Team collaboration + - Small business productivity + +## Top Keyword Opportunities + +### Quick Wins (Priority: Immediate) + +| Keyword | Volume | Difficulty | Intent | Score | +|---------|--------|------------|--------|-------| +| project management for small teams | 1,200 | 28 | Commercial | 92 | +| simple task management software | 890 | 25 | Commercial | 89 | +| best free project management tool | 2,400 | 35 | Commercial | 85 | +| how to manage remote team projects | 720 | 22 | Informational | 82 | +| project tracking spreadsheet alternative | 480 | 18 | Commercial | 80 | + +### Growth Keywords (Priority: 3-6 months) + +| Keyword | Volume | Difficulty | Intent | Score | +|---------|--------|------------|--------|-------| +| project management software | 18,000 | 72 | Commercial | 65 | +| best project management tools [current year] | 8,500 | 65 | Commercial | 62 | +| project management app | 12,000 | 68 | Commercial | 58 | + +### GEO Opportunities (AI-citation potential) + +| Keyword | Type | AI Potential | Recommended Format | +|---------|------|--------------|-------------------| +| what is project management | Definition | ⭐⭐⭐⭐⭐ | Clear definition + methodology | +| agile vs waterfall | Comparison | ⭐⭐⭐⭐⭐ | Side-by-side comparison table | +| project management methodologies | List | ⭐⭐⭐⭐ | Comprehensive list with pros/cons | +| how to create a project plan | How-to | ⭐⭐⭐⭐ | Step-by-step guide | +| project management best practices | List | ⭐⭐⭐⭐ | Numbered best practices | + +## Topic Clusters + +### Cluster 1: Project Management Fundamentals + +**Pillar**: "Complete Guide to Project Management" (8,500 volume) + +Cluster articles: +1. What is project management? (2,200 volume) +2. Project management methodologies explained (1,800 volume) +3. How to create a project plan (1,400 volume) +4. Project management best practices (1,200 volume) +5. Project management roles and responsibilities (890 volume) + +### Cluster 2: Team Collaboration + +**Pillar**: "Team Collaboration Tools Guide" (4,200 volume) + +Cluster articles: +1. How to improve team communication (1,600 volume) +2. Remote team management tips (1,400 volume) +3. Best practices for distributed teams (920 volume) +4. Team productivity tools comparison (780 volume) + +## Content Calendar Recommendations + +| Month | Content | Target Keyword | Type | +|-------|---------|----------------|------| +| Week 1 | Simple Task Management Guide | simple task management software | Blog + Demo | +| Week 2 | Project Management for Small Teams | project management for small teams | Pillar Page | +| Week 3 | Agile vs Waterfall: Complete Comparison | agile vs waterfall | Comparison | +| Week 4 | Free PM Tools Roundup | best free project management tool | Listicle | + +## Next Steps + +1. **Immediate**: Create landing pages for top 5 quick-win keywords +2. **Week 1-2**: Write pillar content for "Project Management Fundamentals" +3. **Week 3-4**: Build out cluster content with internal linking +4. **Ongoing**: Track rankings and adjust strategy based on performance +``` diff --git a/.cursor/skills/keyword-research/references/keyword-intent-taxonomy.md b/.cursor/skills/keyword-research/references/keyword-intent-taxonomy.md new file mode 100644 index 0000000000..7e5f362506 --- /dev/null +++ b/.cursor/skills/keyword-research/references/keyword-intent-taxonomy.md @@ -0,0 +1,324 @@ +# Keyword Intent Taxonomy + +A comprehensive classification system for understanding search intent, mapping keywords to content strategies, and aligning with conversion funnels. + +## Overview + +Search intent (also called user intent or query intent) is the underlying goal a user has when typing a query into a search engine or AI system. Correctly classifying intent determines content format, tone, depth, and conversion strategy. + +This taxonomy defines **4 primary intent types**, each with **3-4 sub-categories**, along with signal words, SERP feature correlations, and content format recommendations. + +--- + +## Primary Intent Types + +### 1. Informational Intent + +The user wants to **learn something**. They are seeking knowledge, not a product. + +#### Sub-categories + +| Sub-category | Description | Example Queries | +|-------------|------------|----------------| +| **Educational** | Broad learning about a topic | "what is SEO", "content marketing explained", "how search engines work" | +| **Instructional** | Step-by-step guidance on completing a task | "how to set up Google Analytics", "how to write a meta description", "how to do keyword research" | +| **Exploratory** | Open-ended research to understand options | "types of SEO strategies", "content marketing trends", "link building techniques" | +| **Troubleshooting** | Diagnosing and fixing a problem | "why is my site not ranking", "Google indexing issues", "404 error fix" | + +#### Signal Words and Modifiers + +**Strong informational signals:** +- what, what is, what are, what does +- how, how to, how does, how do I +- why, why is, why does, why do +- when, when to, when should +- who, who is, who does +- where, where to, where can I +- guide, tutorial, learn, explain +- examples, tips, ideas, ways +- definition, meaning, difference between +- history of, basics of, introduction to +- pros and cons, advantages, disadvantages +- best practices, checklist, steps + +**Weak informational signals (may overlap with commercial):** +- overview, comparison, review (can be commercial) +- list of, types of, methods + +#### SERP Feature Correlation + +| SERP Feature | Frequency for Informational | Notes | +|-------------|---------------------------|-------| +| Featured Snippet | Very High | Especially for "what is" and "how to" queries | +| People Also Ask | Very High | Almost always present for informational queries | +| Knowledge Panel | High | For entity-related informational queries | +| AI Overview | Very High | AI systems prioritize informational answers | +| Video Carousel | Medium-High | Especially for instructional queries | +| Image Pack | Medium | For visual/diagram-seeking queries | +| Shopping Results | Very Low | Rarely appears for pure informational | + +#### Content Format Recommendations + +| Sub-category | Best Formats | Target Length | Key Elements | +|-------------|-------------|--------------|-------------| +| Educational | Definitive guides, explainers, glossary entries | 1,500-3,000 words | Clear definitions, examples, visuals | +| Instructional | Step-by-step tutorials, how-to guides, video walkthroughs | 2,000-4,000 words | Numbered steps, screenshots, code samples | +| Exploratory | Listicles, roundups, trend reports, comparison tables | 2,000-3,500 words | Categories, pros/cons, use cases | +| Troubleshooting | FAQ pages, debug guides, knowledge base articles | 800-2,000 words | Problem-solution pairs, error codes, screenshots | + +--- + +### 2. Navigational Intent + +The user wants to **find a specific website, page, or resource**. They already know where they want to go. + +#### Sub-categories + +| Sub-category | Description | Example Queries | +|-------------|------------|----------------| +| **Brand Search** | Looking for a specific company or product | "Ahrefs", "HubSpot CRM", "Moz Pro" | +| **Product/Feature Search** | Looking for a specific feature or tool within a known brand | "Ahrefs keyword explorer", "Google Search Console coverage report" | +| **Login/Access** | Trying to access an account or dashboard | "Ahrefs login", "Google Analytics sign in", "SEMrush dashboard" | +| **Support/Docs** | Seeking help documentation for a known product | "Ahrefs API documentation", "Google Search Console help" | + +#### Signal Words and Modifiers + +**Strong navigational signals:** +- [brand name] (standalone) +- [brand name] login, sign in, sign up +- [brand name] pricing, plans +- [brand name] support, help, docs +- [brand name] [feature name] +- [brand name] download, app +- official, website, site +- [brand name] alternatives (borderline commercial) + +#### SERP Feature Correlation + +| SERP Feature | Frequency for Navigational | Notes | +|-------------|---------------------------|-------| +| Sitelinks | Very High | Brand queries almost always show sitelinks | +| Knowledge Panel | High | For established brands with Google entity | +| Featured Snippet | Low | Rarely for pure navigational | +| People Also Ask | Medium | Often brand-related questions | +| AI Overview | Low | AI usually defers to direct navigation | + +#### Content Format Recommendations + +| Sub-category | Best Formats | Key Elements | +|-------------|-------------|-------------| +| Brand Search | Homepage, about page, landing pages | Clear branding, value prop, navigation | +| Product/Feature Search | Product pages, feature pages | Feature details, CTAs, screenshots | +| Login/Access | Login page, getting started guide | Fast load, clear login form, password reset | +| Support/Docs | Knowledge base, documentation hub | Search functionality, categorized articles | + +--- + +### 3. Commercial Investigation Intent + +The user is **researching before making a purchase decision**. They are comparing options, reading reviews, and evaluating alternatives. + +#### Sub-categories + +| Sub-category | Description | Example Queries | +|-------------|------------|----------------| +| **Comparison** | Evaluating two or more specific options | "Ahrefs vs SEMrush", "WordPress vs Squarespace for SEO" | +| **Review-seeking** | Looking for opinions and evaluations | "Ahrefs review 2026", "best SEO tool reviews", "is Moz worth it" | +| **Best-of Research** | Seeking curated top options in a category | "best SEO tools", "top keyword research tools", "best free backlink checkers" | +| **Evaluation** | Assessing fit for a specific need | "SEO tools for small business", "enterprise SEO platform features", "SEO tool for agencies" | + +#### Signal Words and Modifiers + +**Strong commercial signals:** +- best, top, leading +- vs, versus, compared to, comparison +- review, reviews, rating, ratings +- alternative, alternatives to +- like [brand], similar to +- for [audience], for [use case] +- pros and cons (when about products) +- worth it, is [product] good +- features, capabilities, integrations +- pricing, cost, how much +- free vs paid, premium + +**Seasonal/temporal commercial signals:** +- [product] [year] (e.g., "best SEO tools 2026") +- new, latest, updated + +#### SERP Feature Correlation + +| SERP Feature | Frequency for Commercial | Notes | +|-------------|------------------------|-------| +| People Also Ask | Very High | Comparison and evaluation questions | +| Featured Snippet | High | Especially for "best" and comparison queries | +| AI Overview | High | AI often synthesizes comparisons | +| Shopping Results | Medium | When products have direct purchase path | +| Video Carousel | Medium | Review and comparison videos | +| Ads (top) | Very High | Advertisers target commercial intent heavily | + +#### Content Format Recommendations + +| Sub-category | Best Formats | Target Length | Key Elements | +|-------------|-------------|--------------|-------------| +| Comparison | Side-by-side comparison pages, "X vs Y" articles | 2,500-4,000 words | Feature tables, pricing tables, verdict | +| Review-seeking | In-depth reviews, user testimonials, case studies | 2,000-3,500 words | Honest pros/cons, screenshots, scoring | +| Best-of Research | Ranked listicles, category roundups | 3,000-5,000 words | Criteria explanation, mini-reviews, comparison table | +| Evaluation | Buying guides, use-case guides, ROI calculators | 2,000-3,500 words | Decision criteria, audience segmentation, recommendations | + +--- + +### 4. Transactional Intent + +The user wants to **complete a specific action**, typically a purchase, signup, or download. + +#### Sub-categories + +| Sub-category | Description | Example Queries | +|-------------|------------|----------------| +| **Purchase** | Ready to buy a product or service | "buy Ahrefs subscription", "SEMrush pricing plans", "order SEO audit" | +| **Signup/Trial** | Ready to create an account or start a trial | "Ahrefs free trial", "sign up for Moz", "create Google Search Console account" | +| **Download** | Wants to download software, template, or resource | "download Screaming Frog", "SEO checklist PDF download", "free keyword template" | +| **Hire/Engage** | Ready to hire a professional or agency | "hire SEO consultant", "SEO agency near me", "freelance SEO expert" | + +#### Signal Words and Modifiers + +**Strong transactional signals:** +- buy, purchase, order, subscribe +- price, pricing, cost, discount, coupon, deal +- free trial, demo, signup, sign up, register +- download, install, get +- hire, book, schedule, request quote +- near me, in [location] +- cheap, affordable, budget +- premium, pro, enterprise +- [product] discount code, [product] coupon + +#### SERP Feature Correlation + +| SERP Feature | Frequency for Transactional | Notes | +|-------------|---------------------------|-------| +| Shopping Results | Very High | Dominant for product purchase queries | +| Ads (top + bottom) | Very High | Maximum ad coverage | +| Local Pack | High | For service-based transactional queries | +| Sitelinks | Medium | For brand-specific transactional | +| Featured Snippet | Low | Rarely for pure transactional | +| AI Overview | Low-Medium | Sometimes for pricing/comparison | + +#### Content Format Recommendations + +| Sub-category | Best Formats | Key Elements | +|-------------|-------------|-------------| +| Purchase | Product pages, pricing pages, checkout | Clear pricing, CTAs, trust signals, reviews | +| Signup/Trial | Landing pages, signup forms, onboarding | Minimal friction, benefits, social proof | +| Download | Resource landing pages, gated content | Preview, form, instant delivery | +| Hire/Engage | Service pages, contact forms, portfolios | Credentials, case studies, clear next step | + +--- + +## Intent Mapping to Conversion Funnel + +### Full Funnel Alignment + +``` +FUNNEL STAGE INTENT TYPE CONTENT GOAL +───────────────────────────────────────────────────────────── +Awareness → Informational Attract & educate + (Educational, Exploratory) + +Interest → Informational Deepen engagement + (Instructional) + +Consideration → Commercial Investigation Build preference + (Best-of, Comparison) + +Evaluation → Commercial Investigation Overcome objections + (Review, Evaluation) + +Decision → Transactional Convert + (Purchase, Signup, Hire) + +Retention → Navigational Support & retain + (Support/Docs, Login) + +Advocacy → Informational Enable sharing + (Educational — about you) +``` + +### Conversion Potential by Intent + +| Intent Type | Avg. Conversion Rate | Typical CTA | Nurture Length | +|------------|---------------------|-------------|---------------| +| Informational | 0.5-2% | Newsletter signup, content download | Long (weeks-months) | +| Navigational | N/A (already engaged) | Login, access feature | N/A | +| Commercial Investigation | 2-5% | Free trial, demo request, comparison download | Medium (days-weeks) | +| Transactional | 5-15% | Buy now, subscribe, hire | Short (immediate-days) | + +--- + +## Mixed Intent Queries + +Many real-world queries blend multiple intent types. Recognize and address the dominant + secondary intent. + +### Common Mixed Intent Patterns + +| Query Pattern | Primary Intent | Secondary Intent | Content Strategy | +|--------------|---------------|-----------------|-----------------| +| "best [product] for [use case]" | Commercial | Informational | Buying guide with educational context | +| "how to [task] with [product]" | Instructional | Navigational | Tutorial featuring the product | +| "[product] review and pricing" | Commercial | Transactional | Review with clear pricing CTAs | +| "what is [concept] tools" | Informational | Commercial | Explainer that transitions to tool recommendations | +| "[product] free download" | Transactional | Navigational | Landing page with download + product info | + +### Handling Mixed Intent in Content + +1. **Lead with the primary intent** -- answer the dominant question first +2. **Bridge to the secondary intent** -- naturally transition to the secondary need +3. **Match SERP format** -- if SERPs show mixed results, your content should too +4. **Segment CTAs** -- provide different CTAs for different intent segments within the page + +--- + +## SEO-Specific Keyword Intent Examples + +### SEO Industry Keyword Classification + +| Keyword | Intent | Sub-category | Recommended Content | +|---------|--------|-------------|-------------------| +| what is SEO | Informational | Educational | Definitive guide with visuals | +| how to do keyword research | Informational | Instructional | Step-by-step tutorial | +| best SEO tools 2026 | Commercial | Best-of Research | Ranked listicle with mini-reviews | +| Ahrefs vs SEMrush | Commercial | Comparison | Side-by-side feature comparison | +| buy Ahrefs subscription | Transactional | Purchase | Pricing/product page | +| Google Search Console login | Navigational | Login/Access | Login page or redirect | +| why is my site not indexing | Informational | Troubleshooting | Debug guide with solutions | +| SEO agency for ecommerce | Transactional | Hire/Engage | Service page with portfolio | +| is Moz worth it | Commercial | Review-seeking | Honest review with alternatives | +| SEO checklist template | Transactional | Download | Gated resource landing page | +| types of backlinks | Informational | Exploratory | Categorized explainer | +| SEMrush pricing | Commercial | Evaluation | Pricing breakdown page | + +--- + +## Applying Intent Taxonomy in Keyword Research + +### Step-by-Step Classification Process + +1. **Read the query literally** -- what is the user asking for? +2. **Check for signal words** -- match against the signal word tables above +3. **Verify against SERP** -- what does Google actually show? The SERP is the ground truth +4. **Identify sub-category** -- narrow from primary intent to sub-category +5. **Check for mixed intent** -- does the query blend two types? +6. **Map to content format** -- select format based on intent + sub-category +7. **Assign funnel stage** -- determine where this fits in the buyer journey +8. **Set conversion expectation** -- align CTA and goals with intent type + +### Common Classification Mistakes + +| Mistake | Example | Why It's Wrong | Correct Classification | +|---------|---------|---------------|----------------------| +| Treating all "best" queries as informational | "best CRM software" | User is comparing products to buy | Commercial Investigation | +| Treating all questions as informational | "how much does Ahrefs cost" | User is evaluating a purchase | Commercial / Transactional | +| Ignoring local intent | "SEO services" | May have strong local intent in many contexts | Transactional (local) | +| Missing navigational intent | "HubSpot blog" | User wants a specific page | Navigational | +| Assuming single intent | "SEO tools" | Could be informational OR commercial | Mixed -- check SERP | diff --git a/.cursor/skills/keyword-research/references/keyword-prioritization-framework.md b/.cursor/skills/keyword-research/references/keyword-prioritization-framework.md new file mode 100644 index 0000000000..e32b7dda99 --- /dev/null +++ b/.cursor/skills/keyword-research/references/keyword-prioritization-framework.md @@ -0,0 +1,41 @@ +# Keyword Prioritization Framework + +Systematic scoring methodology for ranking keywords by strategic value. + +## Relationship to Opportunity Score + +**Which score to use**: Use the Priority Score (below) for initial keyword triage and shortlisting. Use the Opportunity Score (Step 6 in the main workflow) for final content calendar prioritization, where the additional GEO and competitive factors provide more nuanced ranking. + +## Priority Scoring Matrix + +Score each keyword 1-5 on these factors, then calculate weighted total: + +| Factor | Weight | Score 1 (Low) | Score 5 (High) | +|--------|--------|---------------|----------------| +| Search Volume | 20% | <100/mo | >10,000/mo | +| Keyword Difficulty | 25% | KD >80 (hard) | KD <20 (easy) | +| Business Relevance | 30% | Tangential to offering | Core to offering | +| Search Intent Match | 15% | Informational only | Transactional/commercial | +| Trend Direction | 10% | Declining | Growing | + +**Priority Score** = Σ(Factor Weight × Score) / 5 + +## Priority Categories + +| Priority | Score Range | Action | +|----------|------------|--------| +| P0 — Must Target | 4.0-5.0 | Create content immediately | +| P1 — High Value | 3.0-3.9 | Queue for next content sprint | +| P2 — Opportunity | 2.0-2.9 | Plan for future content calendar | +| P3 — Monitor | 1.0-1.9 | Track but don't prioritize | + +## Seasonal Keyword Patterns + +### Seasonal Analysis Framework + +| Season Trigger | Example Keywords | Planning Lead Time | Content Strategy | +|---------------|-----------------|-------------------|-----------------| +| Calendar events | "Black Friday SEO", "New Year marketing plan" | 3-4 months ahead | Publish 6-8 weeks before peak | +| Industry events | "[Conference] takeaways", "Google algorithm update" | 1-2 months / reactive | Pre-plan templates, react quickly | +| Budget cycles | "marketing budget template Q1", "SEO ROI report" | 2-3 months ahead | Target planning season (Oct-Dec) | +| Seasonal demand | "summer marketing ideas", "holiday email campaigns" | 2-3 months ahead | Refresh annually with new data | diff --git a/.cursor/skills/keyword-research/references/topic-cluster-templates.md b/.cursor/skills/keyword-research/references/topic-cluster-templates.md new file mode 100644 index 0000000000..da6ec594d2 --- /dev/null +++ b/.cursor/skills/keyword-research/references/topic-cluster-templates.md @@ -0,0 +1,286 @@ +# Topic Cluster Templates + +Planning worksheets, architecture patterns, and measurement frameworks for building topic clusters that establish topical authority and drive organic traffic. + +## Overview + +A topic cluster is a group of interlinked content pieces organized around a central pillar page. The pillar covers a broad topic comprehensively, while cluster pages dive deep into specific subtopics. Internal links bind the cluster together, signaling topical authority to search engines and AI systems. + +--- + +## Topic Cluster Planning Worksheet + +### Step 1: Define the Pillar Topic + +Use this template to evaluate whether a topic deserves a full cluster: + +| Field | Your Input | +|-------|-----------| +| **Pillar Topic** | [Broad topic name] | +| **Pillar Keyword** | [Head keyword, typically 1-3 words] | +| **Monthly Search Volume** | [Volume] | +| **Keyword Difficulty** | [KD score] | +| **Business Relevance** | [1-5 scale: how core is this to your product/service?] | +| **Current Ranking** | [Your current position, or "Not ranking"] | +| **Competitor Coverage** | [How many competitors have pillar content on this?] | +| **Estimated Cluster Size** | [How many subtopics can you identify?] | +| **Content Assets Available** | [Existing content you can repurpose or link] | + +**Pillar viability checklist:** +- [ ] At least 8-12 subtopics can be identified +- [ ] Combined cluster keyword volume exceeds 5,000/month +- [ ] Topic is directly relevant to your product or service +- [ ] You can provide unique expertise or data on this topic +- [ ] Competitors have not yet built a dominant cluster + +### Step 2: Map Cluster Subtopics + +| # | Subtopic | Target Keyword | Volume | KD | Intent | Content Format | Status | +|---|---------|---------------|--------|-----|--------|---------------|--------| +| 1 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] | +| 2 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] | +| 3 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] | +| 4 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] | +| 5 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] | +| 6 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] | +| 7 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] | +| 8 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] | + +### Step 3: Define Internal Linking Map + +| Source Page | Links To | Anchor Text Strategy | +|------------|---------|---------------------| +| Pillar | Cluster 1, 2, 3... (all) | Descriptive, keyword-relevant anchors | +| Cluster 1 | Pillar + Cluster 2, 3 | Natural contextual links | +| Cluster 2 | Pillar + Cluster 1, 4 | Natural contextual links | +| Cluster 3 | Pillar + Cluster 1 | Natural contextual links | + +**Linking rules:** +- Every cluster page MUST link to the pillar page +- The pillar page MUST link to every cluster page +- Cluster pages SHOULD link to 2-3 related cluster pages where contextually relevant +- Use descriptive anchor text (not "click here" or bare URLs) +- Link placement should be within body content, not just in a footer list + +--- + +## Hub-and-Spoke Architecture Patterns + +### Pattern 1: Classic Hub-Spoke (Best for Educational Topics) + +``` + ┌──────────────────┐ + ┌────│ What is [Topic]? │ + │ └──────────────────┘ + │ ┌──────────────────┐ + ├────│ [Topic] Benefits │ + │ └──────────────────┘ +┌───────────────┐ │ ┌──────────────────┐ +│ PILLAR: │───┼────│ [Topic] Examples │ +│ Complete │ │ └──────────────────┘ +│ Guide to │ │ ┌──────────────────┐ +│ [Topic] │ ├────│ [Topic] Tools │ +└───────────────┘ │ └──────────────────┘ + │ ┌──────────────────┐ + ├────│ [Topic] Mistakes │ + │ └──────────────────┘ + │ ┌──────────────────┐ + └────│ [Topic] Checklist │ + └──────────────────┘ +``` + +**Best for:** Broad educational topics where subtopics don't overlap much. +**Example:** "Content Marketing" pillar with spokes for strategy, types, examples, tools, metrics, mistakes. + +### Pattern 2: Layered Cluster (Best for Technical Topics) + +``` + ┌─────────────────────────────┐ + ┌────│ BEGINNER CLUSTER │ + │ │ - Getting Started │ + │ │ - Basic Concepts │ + │ │ - First Steps Tutorial │ + │ └─────────────────────────────┘ +┌──────────┐ │ ┌─────────────────────────────┐ +│ PILLAR: │───┼────│ INTERMEDIATE CLUSTER │ +│ Complete │ │ │ - Advanced Techniques │ +│ Guide │ │ │ - Common Patterns │ +└──────────┘ │ │ - Optimization Strategies │ + │ └─────────────────────────────┘ + │ ┌─────────────────────────────┐ + └────│ ADVANCED CLUSTER │ + │ - Expert Strategies │ + │ - Edge Cases │ + │ - Integration Guides │ + └─────────────────────────────┘ +``` + +**Best for:** Topics with clear skill progressions (programming, technical SEO, data analysis). +**Example:** "Technical SEO" pillar with beginner (crawling basics), intermediate (JavaScript rendering), advanced (log file analysis) layers. + +### Pattern 3: Use-Case Cluster (Best for Product/Service Topics) + +``` + ┌──────────────────────┐ + ┌────│ [Topic] for SMBs │ + │ └──────────────────────┘ + │ ┌──────────────────────┐ +┌──────────┐ ├────│ [Topic] for Enterprise│ +│ PILLAR: │───┤ └──────────────────────┘ +│ [Topic] │ │ ┌──────────────────────┐ +│ Guide │ ├────│ [Topic] for Agencies │ +└──────────┘ │ └──────────────────────┘ + │ ┌──────────────────────┐ + ├────│ [Topic] for Ecommerce │ + │ └──────────────────────┘ + │ ┌──────────────────────┐ + └────│ [Topic] for SaaS │ + └──────────────────────┘ +``` + +**Best for:** Products/services with distinct audience segments. +**Example:** "SEO Strategy" pillar with spokes for different business types (ecommerce SEO, SaaS SEO, local SEO, B2B SEO). + +### Pattern 4: Process Cluster (Best for How-To Topics) + +``` +┌──────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ +│ PILLAR: │────→│ Step 1: │────→│ Step 2: │────→│ Step 3: │────→│ Step 4: │ +│ How to │ │ Research │ │ Plan │ │ Execute │ │ Measure │ +│ [Process]│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ +└──────────┘ │ │ │ │ + ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ + │Sub-guide │ │Template │ │Tutorial │ │Dashboard │ + │ 1a │ │ 2a │ │ 3a │ │ Guide │ + └─────────┘ └─────────┘ └─────────┘ └─────────┘ +``` + +**Best for:** Multi-step processes where each step is complex enough for its own article. +**Example:** "Link Building" pillar with sequential steps (prospecting, outreach, content creation, tracking). + +--- + +## Internal Linking Patterns Within Clusters + +### Linking Density Guidelines + +| Cluster Size | Min Links Per Cluster Page | Max Links Per Cluster Page | Pillar Link Density | +|-------------|--------------------------|--------------------------|-------------------| +| 5-8 pages | 2-3 internal links | 5-6 internal links | Link to every cluster page | +| 9-15 pages | 3-4 internal links | 6-8 internal links | Link to every cluster page | +| 16+ pages | 4-5 internal links | 8-10 internal links | Link to top cluster pages, categorize rest | + +### Anchor Text Strategy + +| Link Type | Anchor Text Approach | Example | +|-----------|---------------------|---------| +| Cluster → Pillar | Broad keyword or branded | "our complete guide to keyword research" | +| Pillar → Cluster | Specific keyword for that cluster page | "learn about long-tail keyword strategies" | +| Cluster → Cluster | Contextual, conversational | "this connects to how you assess keyword difficulty" | + +### Linking Anti-Patterns to Avoid + +| Anti-Pattern | Why It's Bad | Fix | +|-------------|-------------|-----| +| Footer-only links to cluster pages | Low link equity, poor UX | Move links into body content | +| Generic anchors ("click here", "read more") | No keyword signal | Use descriptive, keyword-relevant anchors | +| Orphan cluster pages (no inbound links) | Search engines can't discover/value them | Add contextual links from pillar and related clusters | +| Over-linking (20+ internal links per page) | Dilutes link equity, feels spammy | Keep to 5-10 relevant internal links | +| Linking only to pillar (ignoring sibling clusters) | Misses cross-cluster relevance | Link to 2-3 related sibling pages | + +--- + +## Content Calendar Integration + +### Cluster Build Sequence + +The order you publish cluster content matters. Follow this sequence for maximum impact: + +| Phase | What to Publish | Why This Order | +|-------|----------------|---------------| +| **Phase 1: Pillar** | Publish the pillar page first | Establishes the hub; cluster pages need something to link to | +| **Phase 2: Quick-win clusters** | Publish 3-4 lowest-difficulty cluster pages | Build early traffic and indexing momentum | +| **Phase 3: High-value clusters** | Publish highest-volume cluster pages | Leverage pillar authority for competitive terms | +| **Phase 4: Long-tail clusters** | Publish remaining niche subtopics | Fill coverage gaps, capture long-tail traffic | +| **Phase 5: Update cycle** | Refresh pillar with new links; update outdated clusters | Maintain freshness signals | + +### Sample Content Calendar for One Cluster + +| Week | Content Piece | Type | Target Keyword | Word Count | Dependencies | +|------|--------------|------|---------------|-----------|-------------| +| 1 | Complete Guide to [Pillar Topic] | Pillar | [Head keyword] | 3,500-5,000 | None | +| 2 | What is [Subtopic A]? | Cluster | [Long-tail A] | 1,500-2,000 | Pillar published | +| 3 | How to [Subtopic B] | Cluster | [Long-tail B] | 2,000-2,500 | Pillar published | +| 4 | [Subtopic C] vs [Subtopic D] | Cluster | [Long-tail C] | 2,000-2,500 | Pillar published | +| 5 | Best [Subtopic E] Tools | Cluster | [Long-tail E] | 2,500-3,000 | Pillar published | +| 6 | [Subtopic F] for Beginners | Cluster | [Long-tail F] | 1,500-2,000 | Pillar published | +| 7 | [Subtopic G] Checklist | Cluster | [Long-tail G] | 1,000-1,500 | Pillar published | +| 8 | Update Pillar + add all internal links | Update | -- | -- | All clusters published | + +### Publishing Cadence Recommendations + +| Team Size | Cluster Build Time | Recommended Cadence | +|-----------|-------------------|-------------------| +| Solo content creator | 6-8 weeks per cluster | 1 cluster per quarter | +| Small team (2-3 writers) | 3-4 weeks per cluster | 1 cluster per month | +| Content team (4-6 writers) | 2-3 weeks per cluster | 2 clusters per month | +| Large team (7+ writers) | 1-2 weeks per cluster | 1 cluster per week | + +--- + +## Cluster Performance Measurement Framework + +### Key Metrics by Level + +#### Cluster-Level Metrics + +| Metric | What It Measures | Target | How to Track | +|--------|-----------------|--------|-------------| +| Total cluster traffic | Aggregate organic visits to all pages in cluster | Growing month-over-month | Analytics: filter by URL folder/tag | +| Keyword coverage | Number of keywords cluster ranks for | 50+ keywords per mature cluster | SEO tool: filter by cluster URLs | +| Average position | Mean ranking across all cluster keywords | Improving trend toward top 10 | SEO tool: average position report | +| Internal link equity | PageRank flow within cluster | Pillar has highest internal links | Site audit tool: internal link report | +| Cluster completeness | Percentage of planned subtopics published | 100% within planned timeframe | Content calendar tracking | + +#### Page-Level Metrics (Per Cluster Page) + +| Metric | Pillar Target | Cluster Page Target | +|--------|-------------|-------------------| +| Organic traffic | Highest in cluster | Proportional to keyword volume | +| Keywords ranking | 50-200+ | 10-50 | +| Backlinks | Attracts most links | Some organic links | +| Avg. time on page | 4-8 minutes | 2-5 minutes | +| Bounce rate | <60% | <70% | +| Internal CTR | High clicks to cluster pages | Clicks to pillar + sibling pages | + +### Performance Review Cadence + +| Timeframe | What to Review | Action If Underperforming | +|-----------|---------------|--------------------------| +| 2 weeks post-publish | Indexing status, initial impressions | Fix indexing issues, check for crawl errors | +| 1 month post-publish | Early ranking signals, traffic | Optimize titles/metas, add internal links | +| 3 months post-publish | Ranking positions, traffic trends | Content refresh, add missing subtopics, build links | +| 6 months post-publish | Full performance assessment | Major content update or strategic pivot | +| Quarterly (ongoing) | Cluster-level aggregate trends | Identify declining pages, plan refreshes | + +### Cluster Health Scorecard + +Rate each cluster quarterly on these dimensions: + +| Dimension | Score 1 (Poor) | Score 3 (Average) | Score 5 (Excellent) | +|-----------|---------------|-------------------|-------------------| +| Traffic growth | Declining | Flat | Growing 10%+ MoM | +| Keyword coverage | <20 keywords | 20-50 keywords | 50+ keywords | +| Top 10 rankings | 0 keywords in top 10 | 1-5 in top 10 | 5+ in top 10 | +| Content freshness | Not updated in 12+ months | Updated within 6 months | Updated within 3 months | +| Internal linking | Missing links, orphan pages | Basic linking in place | Full cross-linking with relevant anchors | +| Completeness | <50% of subtopics covered | 50-80% covered | 80-100% covered | + +**Cluster Health Score** = Average of all dimension scores + +| Score Range | Health Status | Action | +|------------|--------------|--------| +| 4.0-5.0 | Healthy | Maintain cadence, expand to adjacent clusters | +| 3.0-3.9 | Needs attention | Refresh outdated content, fill subtopic gaps | +| 2.0-2.9 | At risk | Major content update, link building campaign | +| 1.0-1.9 | Failing | Strategic review -- consider merging, rewriting, or retiring | diff --git a/.cursor/skills/memory-management/SKILL.md b/.cursor/skills/memory-management/SKILL.md new file mode 100644 index 0000000000..c9ec3af3b5 --- /dev/null +++ b/.cursor/skills/memory-management/SKILL.md @@ -0,0 +1,342 @@ +--- +name: memory-management +description: 'Persist SEO/GEO campaign context across Claude sessions with automatic hot-list, active work, and archive tiers. 项目记忆/跨会话' +version: "7.0.0" +license: Apache-2.0 +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when reviewing, archiving, or cleaning up campaign memory. Also when the user asks to check saved findings, manage hot cache, or archive old data." +argument-hint: "[review|archive|cleanup]" +metadata: + author: aaron-he-zhu + version: "7.0.0" + geo-relevance: "low" + tags: + - seo + - geo + - project-memory + - context-management + - campaign-tracking + - session-context + - hot-cache + - 项目记忆 + - プロジェクト記憶 + - 프로젝트메모리 + - memoria-proyecto + triggers: + # EN-formal + - "remember project context" + - "save SEO data" + - "track campaign progress" + - "store keyword data" + - "manage project memory" + - "project context" + - "refresh wiki index" + - "build wiki index" + - "wiki lint" + # EN-casual + - "remember this for next time" + - "save my keyword data" + - "keep track of this campaign" + - "what did we decide last time" + - "what do we know so far" + - "project status" + # EN-question + - "how to save project progress" + # ZH-pro + - "项目记忆管理" + - "SEO数据保存" + - "跨会话记忆" + - "刷新wiki索引" + - "项目状况" + # ZH-casual + - "保存进度" + - "上次说了什么" + - "记住这个" + # JA + - "プロジェクト記憶" + - "SEOデータ保存" + # KO + - "프로젝트 메모리" + - "데이터 저장" + # ES + - "memoria del proyecto" + - "guardar progreso" + # PT + - "memória do projeto" +--- + +# Memory Management + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This cross-cutting skill is part of the protocol layer and follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + +This skill implements a three-tier memory system (HOT/WARM/COLD) for SEO and GEO projects. HOT memory (80 lines max) loads automatically every session via the SessionStart hook. WARM memory loads on demand per skill. COLD memory is archived data queried only when explicitly requested. The skill manages the full lifecycle: capture, promote, demote, and archive. + +**System role**: Campaign Memory Loop. It defines how project context is captured, promoted, archived, and handed off across sessions. It is the sole executor of WARM-to-COLD archival and the aggregator for cross-skill project status queries. + +## When This Must Trigger + +Use this whenever project state should survive the current session — even if the user doesn't use memory terminology: + +- User says "remember this", "save this", "keep track of this" +- User asks "what did we decide", "what do we know", "project status" +- Setting up memory structure for a new SEO project +- After completing audits, ranking checks, or performance reports (Stop hook reminds automatically) +- When project context needs updating (new keywords, competitors, priorities) +- When you need to look up historical data or project-specific terminology +- After 30+ days of work to clean up and archive stale data +- When open-loops.md has items older than 7 days (SessionStart hook reminds automatically) + +## What This Skill Does + +1. **HOT Cache Management**: Maintains `memory/hot-cache.md` (80 lines max) — loaded automatically every session by SessionStart hook +2. **WARM Storage**: Organizes dated findings in `memory/` subdirectories — loaded on demand by relevant skills +3. **COLD Archive**: Moves stale data (90+ days unreferenced) to `memory/archive/` with date prefix +4. **Promotion**: Elevates frequently-referenced findings from WARM to HOT (3+ refs in 7 days, or 2+ skill refs) +5. **Demotion**: Moves unreferenced HOT items to WARM (30 days), WARM to COLD (90 days) +6. **Cross-Skill Aggregation**: When user asks "what do we know", aggregates from all `memory/` subdirectories +7. **Open Loop Tracking**: Maintains `memory/open-loops.md`, reminds user of stale items via SessionStart hook +8. **Wiki Index Maintenance**: Compiles `memory/wiki/index.md` — a structured, auto-refreshed index of all WARM files with precise fields (score, 健康度, status, next_action, mtime) and best-effort summaries. Supports project isolation via `memory/wiki//index.md`. Auto-refreshed on PostToolUse; user confirmation not required (index is a fully rebuildable derived artifact). Delete `memory/wiki/` at any time to revert to pre-wiki behavior. +9. **Wiki Compiled Pages** (Phase 2): Generates interlinked entity, keyword, and topic pages from WARM files with source hash tracking, contradiction detection, and confidence-labeled reconciliation. Requires user confirmation before writing. +10. **Wiki Lint** (Phase 2): Detects contradictions, orphan pages, stale claims, missing pages, and source hash mismatches across wiki and WARM files via `/seo:wiki-lint`. +11. **WARM Retirement Preview** (Phase 3): `wiki-lint --retire-preview` lists WARM files fully covered by wiki compiled pages as retirement candidates. Actual archival to COLD requires explicit user confirmation. + +## Quick Start + +Start with one of these prompts. Finish with a hot-cache update plan and a handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Initialize Wiki Index + +``` +Refresh wiki index +``` + +``` +Build wiki index for [project name] +``` + +Generates `memory/wiki/index.md` from existing WARM files. Required once to enable wiki features; subsequent refreshes happen automatically. + +### Initialize Memory Structure + +``` +Set up SEO memory for [project name] +``` + +``` +Initialize memory structure for a new [industry] website optimization project +``` + +### Update After Analysis + +``` +Update memory after ranking check for [keyword group] +``` + +``` +Refresh hot cache with latest competitor analysis findings +``` + +### Query Stored Context + +``` +What are our hero keywords? +``` + +``` +Show me the last ranking update date for [keyword category] +``` + +``` +Look up our primary competitors and their domain authority +``` + +### Promotion and Demotion + +``` +Promote [keyword] to hot cache +``` + +``` +Archive stale data that hasn't been referenced in 30+ days +``` + +### Glossary Management + +``` +Add [term] to project glossary: [definition] +``` + +``` +What does [internal jargon] mean in this project? +``` + +## Skill Contract + +**Expected output**: a memory update plan, hot-cache changes, and a short handoff summary. + +- **Reads**: current campaign facts, new findings from other skills, approved decisions, and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). +- **Writes**: updates to `memory/hot-cache.md`, `memory/open-loops.md`, `memory/decisions.md`, and related `memory/` folders. Manages WARM-to-COLD archival in `memory/archive/`. Compiles `memory/wiki/index.md` (auto-refreshed) and wiki compiled pages (user-confirmed). +- **Promotes**: durable strategy, blockers, terminology, entity candidates, and major deltas. Applies temperature lifecycle rules: promote to HOT on high reference frequency, demote on staleness. +- **Next handoff**: use the `Next Best Skill` below when the project memory baseline is ready for active work. + +### Temperature Lifecycle Rules + +> See [references/promotion-demotion-rules.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/memory-management/references/promotion-demotion-rules.md) for the full promotion/demotion table and action procedures. + +### Hook Integration + +This skill's behavior is reinforced by the library's prompt-based hooks: +- **SessionStart**: loads `memory/hot-cache.md`, reminds of stale open loops; loads `memory/wiki//index.md` (or global `index.md`) if it exists; provides light-user guidance based on Quick Status when `next_action` items are available +- **PostToolUse**: after any WARM file write, silently refreshes `memory/wiki/index.md` (Phase 1); prompts to update compiled pages (Phase 2) +- **Stop**: prompts to save session findings, auto-saves veto issues to hot-cache; appends changelog entry to index.md bottom + +## Data Sources + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +**With ~~SEO tool + ~~analytics + ~~search console connected:** +Automatically populate memory from historical data: keyword rankings over time, competitor domain authority changes, traffic metrics, conversion data, backlink profile evolution. The skill will fetch current rankings, alert on significant changes, and update both hot cache and cold storage. + +**With manual data only:** +Ask the user to provide: +1. Current target keywords with priority levels +2. Primary competitors (3-5 domains) +3. Key performance metrics and last update date +4. Active campaigns and their status +5. Any project-specific terminology or abbreviations + +Proceed with memory structure creation using provided data. Note in CLAUDE.md which data requires manual updates vs. automated refresh. + +## Instructions + +When a user requests SEO memory management: + +### 1. Initialize Memory Structure + +For new projects, create the directory structure defined in the [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). Key directories: `memory/` (decisions, open-loops, glossary, entities, research, content, audits, monitoring) plus `memory/wiki/` (auto-managed compiled index with optional per-project subdirectories). + +> **Templates**: [hot-cache-template.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/memory-management/references/hot-cache-template.md) · [glossary-template.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/memory-management/references/glossary-template.md) · [Wiki spec](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/proposal-wiki-layer-v3.md) + +### 2. Context Lookup Flow + +When a user references something unclear, follow this lookup sequence: + +**Step 1: Check CLAUDE.md (Hot Cache)** +- Is it in active keywords? +- Is it in primary competitors? +- Is it in current priorities or campaigns? + +**Step 2: Check Wiki Index** (`memory/wiki/index.md` or project-level) — locate relevant WARM files + +**Step 3: Check memory/glossary.md** +- Is it defined as project terminology? +- Is it a custom segment or shorthand? + +**Step 4: Check Cold Storage** +- Search memory/research/keywords/ for historical keyword context +- Search memory/research/competitors/ for past analyses +- Search memory/monitoring/reports/ for archived mentions + +**Step 5: Ask User** +- If not found in any layer, ask for clarification +- Log the new term in glossary if it's project-specific + +Example lookup: + +```markdown +User: "Update rankings for our hero KWs" + +Step 1: Check CLAUDE.md → Found "Hero Keywords (Priority 1)" section +Step 2: Extract keyword list from hot cache +Step 3: Execute ranking check +Step 4: Update both CLAUDE.md and memory/monitoring/rank-history/YYYY-MM-DD-ranks.csv +``` + +### 3. Promotion & Demotion Logic + +> **Reference**: See [references/promotion-demotion-rules.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/memory-management/references/promotion-demotion-rules.md) for detailed promotion/demotion triggers (keywords, competitors, metrics, campaigns) and the action procedures for each. + +### 4. Update Triggers, Archive Management & Cross-Skill Integration + +> **Reference**: See [references/update-triggers-integration.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/memory-management/references/update-triggers-integration.md) for the complete update procedures after ranking checks, competitor analyses, audits, and reports; monthly/quarterly archive routines; and integration points with all 8 connected skills (keyword-research, rank-tracker, competitor-analysis, content-gap-analysis, seo-content-writer, content-quality-auditor, domain-authority-auditor). + +### 5. Memory Hygiene Checks + +When invoked for review or cleanup: + +1. **Line count check**: Count lines in `memory/hot-cache.md`. If >80, list oldest entries for archival. +2. **Byte check**: If hot-cache exceeds 25KB, warn and recommend trimming long entries. +3. **Staleness scan**: List memory files older than 30 days that have not been referenced. Recommend archival for files >90 days. +4. **Frontmatter audit**: Check that all memory files (except hot-cache.md) have `name`, `description`, and `type` in their frontmatter. Report any missing fields. + +### 6. Save Results + +After delivering any memory update or aggregation to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to the appropriate `memory/` path using filename `YYYY-MM-DD-.md` containing: +- One-line verdict or headline finding +- Top 3-5 actionable items +- Open loops or blockers +- Source data references + +If any veto-level issue was found (CORE-EEAT T04, C01, R10 or CITE T03, T05, T09), also append a one-liner to `memory/hot-cache.md` without asking. + +## Validation Checkpoints + +### Structure Validation +- [ ] memory/hot-cache.md exists and is under 80 lines +- [ ] memory/ directory structure matches the shared state model +- [ ] glossary.md exists and is populated with project basics +- [ ] All historical data files include timestamps in filename or metadata + +### Content Validation +- [ ] CLAUDE.md "Last Updated" date is current +- [ ] Every keyword in hot cache has current rank, target rank, and status +- [ ] Every competitor has domain authority and position assessment +- [ ] Every active campaign has status percentage and expected completion date +- [ ] Key Metrics Snapshot shows "Previous" values for comparison + +### Lookup Validation +- [ ] Test lookup flow: reference a term → verify it finds it in correct layer +- [ ] Test promotion: manually promote item → verify it appears in CLAUDE.md +- [ ] Test demotion: manually archive item → verify removed from CLAUDE.md +- [ ] Glossary contains all custom segments and shorthand used in CLAUDE.md + +### Update Validation +- [ ] After ranking check, `memory/monitoring/rank-history/` has a dated snapshot or export +- [ ] After competitor analysis, `memory/research/competitors/` has a dated file +- [ ] After audit, top action items appear in CLAUDE.md priorities +- [ ] After monthly report, metrics snapshot reflects new data + +## Examples + +> **Reference**: See [references/examples.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/memory-management/references/examples.md) for three complete examples: (1) updating hero keyword rankings with memory refresh, (2) glossary lookup flow, and (3) initializing memory for a new e-commerce project. + +## Advanced Features + +- **Smart Context Loading**: `Load full context for [campaign name]` — retrieves hot cache + all cold storage files for a campaign +- **Memory Health Check**: `Run memory health check` — finds orphaned files, missing timestamps, stale items, broken references +- **Bulk Promotion/Demotion**: `Promote all keywords ranking in top 10 to hot cache` / `Demote all completed campaigns from Q3` +- **Memory Snapshot**: `Create memory snapshot for [date/milestone]` — point-in-time copy for major milestones +- **Cross-Project Memory**: `Compare memory with [other project]` — keyword overlaps, competitor intersections across projects +- **Wiki Lint**: `/seo:wiki-lint [--fix] [--project name] [--retire-preview]` — contradictions, orphans, stale claims, hash mismatches. See [commands/wiki-lint.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/commands/wiki-lint.md) + +## Practical Limitations + +- **Concurrent access**: Use timestamped filenames to avoid overwrites from parallel sessions. +- **Cold storage retrieval**: WARM/COLD files only load on demand. Hot cache is the primary cross-session mechanism. +- **Data freshness**: Stale data (>90 days) should be flagged for refresh. Wiki index `mtime` field helps detect staleness. +- **Wiki compilation**: Index is best-effort for summaries; precise fields (score, status, mtime) are deterministic. Delete `memory/wiki/` anytime to revert. + +## Reference Materials + +- [CORE-EEAT Content Benchmark](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/core-eeat-benchmark.md) — Content quality scoring stored in memory +- [CITE Domain Rating](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/cite-domain-rating.md) — Domain authority scoring stored in memory + +## Next Best Skill + +- **Primary**: [keyword-research](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/keyword-research/SKILL.md) — seed or refresh campaign strategy with current demand signals. diff --git a/.cursor/skills/memory-management/references/examples.md b/.cursor/skills/memory-management/references/examples.md new file mode 100644 index 0000000000..c114b5ea53 --- /dev/null +++ b/.cursor/skills/memory-management/references/examples.md @@ -0,0 +1,138 @@ +# Memory Management Examples + +Detailed examples showing memory management in action. + +--- + +## Example 1: Update Rankings for Hero Keywords + +**User**: "Update rankings for our hero keywords" + +**Assistant**: + +```markdown +I'll update rankings for your hero keywords. Let me check the hot cache for the list. + +[Reads CLAUDE.md, finds Hero Keywords section:] +- keyword research tools (currently #15, target #5) +- best seo software (currently #23, target #10) +- free backlink checker (currently #8, target #3) +- content optimization guide (currently #12, target #5) +- technical seo audit (currently #18, target #8) + +[If ~~SEO tool connected: runs automated ranking check] +[If manual: asks user for current rankings] + +--- + +## Ranking Update - December 15, 2024 + +| Keyword | Previous | Current | Change | Target | Status | +|---------|----------|---------|--------|--------|--------| +| keyword research tools | #15 | #12 | up 3 | #5 | Improving | +| best seo software | #23 | #24 | down 1 | #10 | Stable | +| free backlink checker | #8 | #6 | up 2 | #3 | Near target | +| content optimization guide | #12 | #11 | up 1 | #5 | Improving | +| technical seo audit | #18 | #16 | up 2 | #8 | Improving | + +### Notable Changes +- **free backlink checker** moved to #6 (only 3 positions from target!) +- **keyword research tools** gained 3 positions (strong movement) +- All other keywords showing stable or positive movement + +### Updated Files +1. CLAUDE.md -> Hero Keywords table updated with current ranks +2. memory/monitoring/rank-history/2024-12-15-ranks.csv -> New row added: + `2024-12-15,keyword research tools,12,best seo software,24,free backlink checker,6,...` + +### Recommendations +1. Push additional content/backlinks to "free backlink checker" pages to hit #3 target +2. Investigate why "keyword research tools" suddenly gained 3 positions (replicate success) +3. Monitor "best seo software" for any negative trends + +Hot cache refreshed. Next ranking check recommended: December 22, 2024. +``` + +--- + +## Example 2: Glossary Lookup + +**User**: "What does 'quick wins' mean in our project?" + +**Assistant**: + +```markdown +Let me look that up in the project memory. + +[Step 1: Check CLAUDE.md -> not found] +[Step 2: Check memory/glossary.md -> found!] + +From your project glossary: + +**Quick Wins** +- **Definition**: Low-difficulty, high-value target keywords +- **Keyword Count**: 25 keywords +- **Context**: This segment includes keywords where you can achieve page 1 rankings within 30-60 days due to low competition, despite having decent search volume + +According to your memory files, your current quick wins are stored in: +`memory/research/keywords/long-tail-keywords.md` (tagged with "quick-win" label) + +Would you like me to show you the current list of quick win keywords? +``` + +--- + +## Example 3: Initialize Memory for New Project + +**User**: "Set up memory for a new e-commerce site selling outdoor gear" + +**Assistant**: + +```markdown +I'll set up the two-layer memory system for your outdoor gear e-commerce site. + +## Creating Directory Structure + +[Creates: memory/glossary.md, memory/research/, memory/content/, memory/monitoring/, etc.] + +## CLAUDE.md (Hot Cache) - Initial Setup + +I'll need some information to populate the hot cache: + +1. **Target Keywords**: What are your top 10 hero keywords? + (e.g., "hiking backpacks", "camping tents", "outdoor clothing") + +2. **Primary Competitors**: Who are your top 3-5 competitors? + (e.g., rei.com, backcountry.com, moosejaw.com) + +3. **Current Metrics** (if available): + - Domain authority? + - Current organic traffic? + - Any existing rankings? + +4. **Active Initiatives**: + - Are you launching a new category? + - Running a content campaign? + - Focusing on any specific product line? + +5. **Project Terminology**: + - Any internal product names or abbreviations? + - How do you segment your keyword strategy? + +Please provide what you have, and I'll create your initial CLAUDE.md and glossary. We can start with basics and enrich as we gather more data. + +--- + +Once you provide this information, I'll generate: +- CLAUDE.md with your initial hot cache +- memory/glossary.md with project terminology +- memory/research/keywords/ structure with placeholder files +- memory/research/competitors/ with initial competitor list +- memory/content/calendar/active-calendar.md for Q1 2025 + +After setup, you can use commands like: +- "Update rankings for hero keywords" +- "Add new competitor [domain]" +- "Promote [keyword] to hot cache" +- "Archive campaigns from Q3 2024" +``` diff --git a/.cursor/skills/memory-management/references/glossary-template.md b/.cursor/skills/memory-management/references/glossary-template.md new file mode 100644 index 0000000000..2e3edd309d --- /dev/null +++ b/.cursor/skills/memory-management/references/glossary-template.md @@ -0,0 +1,64 @@ +# Glossary Template + +Use this template to create the project glossary at memory/glossary.md. + +### 3. Glossary Structure (memory/glossary.md) + +```markdown +# [Project Name] - SEO Glossary + +**Purpose**: Project-specific terminology, brand terms, internal jargon, and abbreviations. + +**Last Updated**: [Date] + +## Brand Terms + +| Term | Full Name | Context | +|------|-----------|---------| +| [abbreviation] | [full name] | [when/how it's used] | + +## Product Names + +| Internal Name | Public Name | Category | +|---------------|-------------|----------| +| [code name] | [market name] | [product type] | + +## Custom Segments + +| Segment Name | Definition | Keyword Count | +|--------------|------------|---------------| +| Hero KWs | Top 10 revenue-driving keywords | 10 | +| Quick Wins | Low-difficulty, high-value targets | 25 | +| Brand Defense | Brand + modifier combinations | 15 | + +## Competitor Shorthand + +| Shorthand | Full Domain | Notes | +|-----------|-------------|-------| +| Comp A | competitor-a.com | Main competitor, [industry] | +| Comp B | competitor-b.com | Niche competitor, [specialty] | + +## Project Acronyms + +| Acronym | Full Term | Definition | +|---------|-----------|------------| +| [ABC] | [Full term] | [What it means in this project] | + +## Internal Jargon + +| Phrase | Meaning | Example Usage | +|--------|---------|---------------| +| [phrase] | [definition] | "Check rankings for [phrase]" | + +## Historical Context + +- **Project started**: [Date] +- **Major algorithm updates affecting us**: [List with dates] +- **Site migrations/redesigns**: [List with dates] +- **Key milestones**: [List with dates] + +--- + +_This glossary helps decode project shorthand and maintain consistency across reports and communications._ +``` + diff --git a/.cursor/skills/memory-management/references/hot-cache-template.md b/.cursor/skills/memory-management/references/hot-cache-template.md new file mode 100644 index 0000000000..a57a46bd55 --- /dev/null +++ b/.cursor/skills/memory-management/references/hot-cache-template.md @@ -0,0 +1,96 @@ +# Hot Cache (CLAUDE.md) Template + +Use this template when initializing memory for a new SEO project. + +### 2. Hot Cache (CLAUDE.md) Structure + +Create or update CLAUDE.md with this template: + +```markdown +# [Project Name] - SEO Memory (Hot Cache) + +**Last Updated**: [Date] +**Project Status**: [Active/Maintenance/Growth] + +## Active Target Keywords (Top 10-20) + +### Hero Keywords (Priority 1) +| Keyword | Current Rank | Target Rank | Volume | Status | +|---------|--------------|-------------|--------|--------| +| [keyword 1] | #[X] | #[Y] | [vol] | [tracking/optimizing/achieved] | +| [keyword 2] | #[X] | #[Y] | [vol] | [tracking/optimizing/achieved] | + +### Secondary Keywords (Priority 2) +| Keyword | Current Rank | Target Rank | Volume | Status | +|---------|--------------|-------------|--------|--------| +| [keyword 1] | #[X] | #[Y] | [vol] | [tracking/optimizing/achieved] | + +_Full keyword research: memory/research/keywords/_ + +## Primary Competitors (Top 3-5) + +1. **[Competitor 1]** (DA: [X]) + - Main strengths: [brief] + - Our position vs. them: [ahead/behind/competitive] + +2. **[Competitor 2]** (DA: [X]) + - Main strengths: [brief] + - Our position vs. them: [ahead/behind/competitive] + +_Detailed analyses: memory/research/competitors/_ + +## Current Optimization Priorities + +1. **[Priority 1]** - [Brief description] + - Status: [not started/in progress/completed] + - Expected impact: [high/medium/low] + - Deadline: [date] + +2. **[Priority 2]** - [Brief description] + - Status: [not started/in progress/completed] + - Expected impact: [high/medium/low] + - Deadline: [date] + +## Key Metrics Snapshot + +**Last Metrics Update**: [Date] + +| Metric | Current | Previous | Change | Target | +|--------|---------|----------|--------|--------| +| Organic Traffic | [X] | [X] | [+/-X%] | [target] | +| Avg. Position | [X] | [X] | [+/-X] | [target] | +| Total Keywords Ranking | [X] | [X] | [+/-X] | [target] | +| Page 1 Rankings | [X] | [X] | [+/-X] | [target] | +| Domain Authority | [X] | [X] | [+/-X] | [target] | +| CITE Score | [X] | [X] | [+/-X] | [target] | +| Last Content Audit Score | [score]/100 | ([rating]) | — [date] | [page audited] | +| Total Backlinks | [X] | [X] | [+/-X%] | [target] | + +_Historical data: memory/monitoring/reports/ and memory/monitoring/rank-history/_ + +## Active Campaigns + +### [Campaign Name 1] +- **Duration**: [Start date] - [End date] +- **Goal**: [Specific goal] +- **Status**: [planning/active/completed] +- **Progress**: [X]% +- **Key activities**: [brief list] + +### [Campaign Name 2] +- **Duration**: [Start date] - [End date] +- **Goal**: [Specific goal] +- **Status**: [planning/active/completed] +- **Progress**: [X]% +- **Key activities**: [brief list] + +_Campaign plans and archives: memory/content/calendar/_ + +## Quick Reference Notes + +- [Important note 1] +- [Important note 2] +- [Important note 3] + +_For project terminology, see: memory/glossary.md_ +``` diff --git a/.cursor/skills/memory-management/references/promotion-demotion-rules.md b/.cursor/skills/memory-management/references/promotion-demotion-rules.md new file mode 100644 index 0000000000..01332cb1b7 --- /dev/null +++ b/.cursor/skills/memory-management/references/promotion-demotion-rules.md @@ -0,0 +1,58 @@ +# Promotion and Demotion Rules + +Detailed triggers and actions for moving items between the hot cache (CLAUDE.md) and cold storage (memory/ subdirectories). + +## Promotion Logic + +**Promote to Hot Cache when:** + +### Keyword promotion triggers: +- Keyword referenced in 3+ conversations within 7 days +- Keyword showing significant movement (5+ position change) +- Keyword targeted in new active campaign +- Keyword suddenly driving traffic spike + +### Competitor promotion triggers: +- Competitor mentioned in 3+ recent analyses +- Competitor showing aggressive SEO activity +- Competitor launching competing content + +### Metric promotion triggers: +- Metric requested frequently for reporting +- Metric showing anomalous behavior +- Metric tied to active priority/campaign + +**Promotion action:** +```markdown +1. Add item to relevant section in CLAUDE.md +2. Add note: "Promoted [date] - [reason]" +3. Keep detailed data in cold storage +4. Set reminder to review in 30 days +``` + +## Demotion Logic + +**Demote to Cold Storage when:** + +### Keyword demotion triggers: +- Not referenced in 30+ days +- Target rank achieved and stable for 60+ days +- Keyword no longer in active strategy +- Keyword replaced by higher-priority target + +### Competitor demotion triggers: +- No significant activity in 60+ days +- Fell out of top 5 competitors by relevance +- No longer targeting same keywords + +### Campaign demotion triggers: +- Campaign completed 30+ days ago +- Campaign cancelled or postponed indefinitely + +**Demotion action:** +```markdown +1. Remove from CLAUDE.md +2. Archive full data in memory/[category]/archive/ +3. Add line to CLAUDE.md: "Last reviewed [category]: [date]" +4. Keep 1-line summary if historically significant +``` diff --git a/.cursor/skills/memory-management/references/update-triggers-integration.md b/.cursor/skills/memory-management/references/update-triggers-integration.md new file mode 100644 index 0000000000..00faa54c43 --- /dev/null +++ b/.cursor/skills/memory-management/references/update-triggers-integration.md @@ -0,0 +1,102 @@ +# Update Triggers & Cross-Skill Integration + +Systematic memory update procedures triggered by specific events, plus integration points with other SEO skills. + +## Update Triggers + +After specific events, update memory systematically: + +### After Ranking Check +```markdown +1. Update CLAUDE.md -> Hero Keywords table (current ranks) +2. Save a dated snapshot to memory/monitoring/rank-history/YYYY-MM-DD-ranks.csv +3. Note any keywords with significant movement +4. Update "Last Metrics Update" date in CLAUDE.md +5. If hero keyword moves +/-5 positions, create alert note +``` + +### After Competitor Analysis +```markdown +1. Update CLAUDE.md -> Primary Competitors section (DA, position vs. them) +2. Save full report to memory/research/competitors/YYYY-MM-DD-analysis.md +3. Update competitor overview notes in memory/research/competitors/ +4. Note new competitor strategies in hot cache +``` + +### After Audit (Technical/Content/Backlink) +```markdown +1. Save full report to memory/audits/[type]/YYYY-MM-DD-[audit-name].md +2. Extract top 3-5 action items -> CLAUDE.md Current Optimization Priorities +3. Update Key Metrics Snapshot if audit includes metrics +4. Create campaign entry if audit spawns new initiative +``` + +### After Monthly/Quarterly Report +```markdown +1. Save report to memory/monitoring/reports/[period]/YYYY-MM-report.md +2. Update all metrics in CLAUDE.md Key Metrics Snapshot +3. Review hot cache -> demote stale items +4. Update campaign statuses +5. Archive completed campaigns +``` + +## Archive Management + +### Monthly Archive Routine +```markdown +1. Review CLAUDE.md for items not referenced in 30 days +2. Move stale items to appropriate cold storage +3. Create monthly snapshot: memory/monitoring/snapshots/YYYY-MM-CLAUDE.md +4. Compress old rank-history exports (keep recent snapshots easiest to access) +5. Update glossary with new terms from the month +``` + +### Quarterly Archive Routine +```markdown +1. Review entire cold storage structure +2. Compress files older than 6 months +3. Create quarterly summary report +4. Update project timeline in glossary +5. Audit all active campaigns -> archive completed ones +``` + +## Cross-Skill Memory Integration + +This skill coordinates with other SEO skills: + +### When keyword-research runs: +- Add discovered keywords to memory/research/keywords/ +- Promote top opportunities to CLAUDE.md if high-value +- Update glossary if new terminology emerges + +### When rank-tracker runs: +- Update memory/monitoring/rank-history/ +- Refresh CLAUDE.md Hero Keywords table +- Flag significant movements for hot cache notes + +### When competitor-analysis runs: +- Update competitor files in memory/research/competitors/ +- Refresh CLAUDE.md Primary Competitors section +- Add new competitors if they outrank current top 5 + +### When content-gap-analysis runs: +- Store full findings in memory/research/content-gaps/ +- Promote gap opportunities to CLAUDE.md priorities +- Update memory/content/calendar/ with recommended topics + +### When seo-content-writer produces content: +- Log to memory/content/published/YYYY-MM-DD-[slug].md +- Track target keyword and publish date +- Set reminder to check performance in 30 days + +### When content-quality-auditor runs: +- Save full report to `memory/audits/content/YYYY-MM-DD-core-eeat-[page-slug].md` +- Update CLAUDE.md Key Metrics with latest score +- If score < 60 (Poor/Low), flag in Active Campaigns section +- Track dimension scores for trend analysis + +### When domain-authority-auditor runs: +- Save full report to memory/audits/domain/YYYY-MM-DD-cite-audit.md +- Update CITE Score in CLAUDE.md Key Metrics Snapshot +- Note veto item status and dimension scores +- Compare against previous CITE audit if available diff --git a/.cursor/skills/meta-tags-optimizer/SKILL.md b/.cursor/skills/meta-tags-optimizer/SKILL.md new file mode 100644 index 0000000000..1e3a81c9f9 --- /dev/null +++ b/.cursor/skills/meta-tags-optimizer/SKILL.md @@ -0,0 +1,417 @@ +--- +name: meta-tags-optimizer +description: 'Optimize title tags, meta descriptions, Open Graph, Twitter cards for maximum CTR with A/B variations. 标题优化/元描述/CTR' +version: "6.0.0" +license: Apache-2.0 +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when optimizing title tags, meta descriptions, Open Graph tags, or Twitter Cards for a page." +argument-hint: "" +metadata: + author: aaron-he-zhu + version: "6.0.0" + geo-relevance: "low" + tags: + - seo + - meta-tags + - title-tag + - meta-description + - open-graph + - twitter-card + - ctr-optimization + - social-sharing + - 标题优化 + - 元描述 + - メタタグ + - 메타태그 + - meta-tags-seo + triggers: + # EN-formal + - "optimize title tag" + - "write meta description" + - "improve CTR" + - "Open Graph tags" + - "social media preview" + - "title optimization" + - "meta tags" + - "Twitter cards" + # EN-casual + - "my title tag needs work" + - "low click-through rate" + - "fix my meta tags" + - "OG tags not showing" + - "social preview looks wrong" + - "my click rate is low" + # EN-question + - "how to write a good title tag" + - "how to improve click-through rate" + - "what is a good meta description" + # EN-competitor + - "Yoast SEO title tool" + - "RankMath title optimizer" + # ZH-pro + - "标题标签优化" + - "元描述优化" + - "OG标签" + - "点击率提升" + - "社交预览" + - "TDK优化" + # ZH-casual + - "标题不好" + - "点击率太低" + - "社交分享预览不对" + - "标题怎么写" + - "TDK怎么写" + # JA + - "メタタグ最適化" + - "タイトルタグ" + - "CTR改善" + # KO + - "메타 태그 최적화" + - "제목 태그" + - "클릭률 개선" + # ES + - "optimizar meta tags" + - "mejorar CTR" + - "etiquetas Open Graph" + # PT + - "otimizar meta tags" + # Misspellings + - "meta discription" + - "tittle tag" +--- + +# Meta Tags Optimizer + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This build skill follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + + +This skill creates compelling, optimized meta tags that improve click-through rates from search results and enhance social media sharing. It covers title tags, meta descriptions, and social meta tags. + +**System role**: Build layer skill. It turns briefs and signals into assets that other skills can review, publish, and monitor. + +## When This Must Trigger + +Use this when the conversation involves any of these situations — even if the user does not use SEO terminology: + +Use this whenever the task needs a shippable asset or transformation that should feed directly into quality review, deployment, or monitoring. + +- Creating meta tags for new pages +- Optimizing existing meta tags for better CTR +- Preparing pages for social media sharing +- Fixing duplicate or missing meta tags +- A/B testing title and description variations +- Optimizing for specific SERP features +- Creating meta tags for different page types + +## What This Skill Does + +1. **Title Tag Creation**: Writes compelling, keyword-optimized titles +2. **Meta Description Writing**: Creates click-worthy descriptions +3. **Open Graph Optimization**: Prepares pages for social sharing +4. **Twitter Card Setup**: Optimizes Twitter-specific meta tags +5. **CTR Analysis**: Suggests improvements for better click rates +6. **Character Counting**: Ensures proper length for SERP display +7. **A/B Test Suggestions**: Provides variations for testing + +## Quick Start + +Start with one of these prompts. Finish with a short handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Create Meta Tags + +``` +Create meta tags for a page about [topic] targeting [keyword] +``` + +``` +Write title and meta description for this content: [content/URL] +``` + +### Optimize Existing Tags + +``` +Improve these meta tags for better CTR: [current tags] +``` + +### Social Media Tags + +``` +Create Open Graph and Twitter card tags for [page/URL] +``` + +## Skill Contract + +**Expected output**: a ready-to-use asset or implementation-ready transformation plus a short handoff summary ready for `memory/content/`. + +- **Reads**: the brief, target keywords, entity inputs, quality constraints, and prior decisions from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available. +- **Writes**: a user-facing content, metadata, or schema deliverable plus a reusable summary that can be stored under `memory/content/`. +- **Promotes**: approved angles, messaging choices, missing evidence, and publish blockers to `CLAUDE.md`, `memory/decisions.md`, and `memory/open-loops.md`. +- **Next handoff**: use the `Next Best Skill` below when the asset is ready for review or deployment. + +## Data Sources + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +**With ~~search console + ~~SEO tool connected:** +Automatically pull current meta tags, CTR data by query, competitor title/description patterns, SERP preview data, and impression/click metrics to identify optimization opportunities. + +**With manual data only:** +Ask the user to provide: +1. Current title and meta description (if optimizing existing) +2. Target primary keyword and 2-3 secondary keywords +3. Page URL and main content/value proposition +4. Competitor URLs or examples of well-performing titles in the SERP + +Proceed with the full workflow using provided data. Note in the output which metrics are from automated collection vs. user-provided data. + +## Instructions + +When a user requests meta tag optimization: + +1. **Gather Page Information** + + ```markdown + ### Page Analysis + + **Page URL**: [URL] + **Page Type**: [blog/product/landing/service/homepage] + **Primary Keyword**: [keyword] + **Secondary Keywords**: [keywords] + **Target Audience**: [audience] + **Primary CTA**: [action you want users to take] + **Unique Value Prop**: [what makes this page special] + ``` + +2. **Create Optimized Title Tag** + + ```markdown + ### Title Tag Optimization + + **Requirements**: + - Length: 50-60 characters (displays fully in SERP) + - Include primary keyword (preferably near front) + - Make it compelling and click-worthy + - Match search intent + - Include brand name if appropriate + + **Title Tag Formula Options**: + + 1. **Keyword | Benefit | Brand** + "[Primary Keyword]: [Benefit] | [Brand Name]" + + 2. **Number + Keyword + Promise** + "[Number] [Keyword] That [Promise/Result]" + + 3. **How-to Format** + "How to [Keyword]: [Benefit/Result]" + + 4. **Question Format** + "What is [Keyword]? [Brief Answer/Hook]" + + 5. **Year + Keyword** + "[Keyword] in [Year]: [Hook/Update]" + + **Generated Title Options**: + + | Option | Title | Length | Power Words | Keyword Position | + |--------|-------|--------|-------------|------------------| + | 1 | [Title] | [X] chars | [words] | [Front/Middle] | + | 2 | [Title] | [X] chars | [words] | [Front/Middle] | + | 3 | [Title] | [X] chars | [words] | [Front/Middle] | + + **Recommended**: Option [X] + **Reasoning**: [Why this option is best] + + **Title Tag Code**: + ```html + [Selected Title] + ``` + ``` + +3. **Write Meta Description** + + ```markdown + ### Meta Description Optimization + + **Requirements**: + - Length: 150-160 characters (displays fully in SERP) + - Include primary keyword naturally + - Include clear call-to-action + - Match page content accurately + - Create urgency or curiosity + - Avoid duplicate descriptions + + **Meta Description Formula**: + + [What the page offers] + [Benefit to user] + [Call-to-action] + + **Power Elements to Include**: + - Numbers and statistics + - Current year + - Emotional triggers + - Action verbs + - Unique value proposition + + **Generated Description Options**: + + | Option | Description | Length | CTA | Emotional Trigger | + |--------|-------------|--------|-----|-------------------| + | 1 | [Description] | [X] chars | [CTA] | [Trigger] | + | 2 | [Description] | [X] chars | [CTA] | [Trigger] | + | 3 | [Description] | [X] chars | [CTA] | [Trigger] | + + **Recommended**: Option [X] + **Reasoning**: [Why this option is best] + + **Meta Description Code**: + ```html + + ``` + ``` + +4. **Create Open Graph, Twitter Card, and Additional Meta Tags** + + Generate OG tags (og:type, og:url, og:title, og:description, og:image), Twitter Card tags, canonical URL, robots, viewport, author, and article-specific tags. Then combine into a complete meta tag block. + + > **Reference**: See [references/meta-tag-code-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/meta-tags-optimizer/references/meta-tag-code-templates.md) for OG type selection guide, Twitter card type selection, all HTML code templates, and the complete meta tag block template. + +5. **CORE-EEAT Alignment Check** + + Verify meta tags align with content quality standards. Reference: [CORE-EEAT Benchmark](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/core-eeat-benchmark.md) + + ```markdown + ### CORE-EEAT Meta Tag Alignment + + | Check | Status | Notes | + |-------|--------|-------| + | **C01 Intent Alignment**: Title promise matches actual content delivery | ✅/⚠️/❌ | [Does the title accurately represent what the page delivers?] | + | **C02 Direct Answer**: Meta description reflects the core answer available in first 150 words | ✅/⚠️/❌ | [Does the description preview the direct answer?] | + + **If C01 fails**: Title is misleading — rewrite to match actual content. + **If C02 fails**: Content may need restructuring to front-load the answer, or description should better reflect available content. + ``` + +9. **Provide CTR Optimization Tips** + + ```markdown + ## CTR Optimization Analysis + + ### Power Words Used + - [Word 1] - Creates [emotion/action] + - [Word 2] - Creates [emotion/action] + + ### CTR Boosting Elements + + | Element | Present | Impact | + |---------|---------|--------| + | Numbers | Yes/No | +20-30% CTR | + | Current Year | Yes/No | +15-20% CTR | + | Power Words | Yes/No | +10-15% CTR | + | Question | Yes/No | +10-15% CTR | + | Brackets | Yes/No | +10% CTR | + + ### A/B Test Suggestions + + Test these variations: + + **Version A** (Current): + - Title: [Title] + - Description: [Description] + + **Version B** (Test): + - Title: [Alternative title] + - Description: [Alternative description] + - Hypothesis: [Why this might perform better] + ``` + +## Validation Checkpoints + +### Input Validation +- [ ] Primary keyword confirmed and matches page content +- [ ] Page type identified (blog/product/landing/service/homepage) +- [ ] Target audience and search intent clearly defined +- [ ] Unique value proposition articulated + +### Output Validation +- [ ] Title length 50-60 characters (displays fully in SERP) +- [ ] Meta description length 150-160 characters +- [ ] Primary keyword appears in both title and description +- [ ] Open Graph image specified (1200x630px recommended) +- [ ] All HTML syntax valid (no unclosed quotes or tags) +- [ ] Source of each data point clearly stated (~~search console CTR data, ~~SEO tool competitor data, user-provided, or estimated) + +## Example + +**User**: "Create meta tags for a blog post about 'how to start a podcast in [current year]'" + +**Output**: + +```markdown +## Meta Tags: How to Start a Podcast ([current year]) + +### Title Tag +```html +How to Start a Podcast in [current year]: Complete Beginner's Guide +``` +**Length**: ~55 characters ✅ +**Keyword**: "how to start a podcast" at front ✅ +**Power Words**: "Complete", "Beginner's" ✅ + +### Meta Description +```html + +``` +**Length**: ~163 characters ✅ +**Keyword**: Included naturally ✅ +**CTA**: "Start podcasting today!" ✅ + +_Complete meta tag block (with OG, Twitter, Article tags) generated using template from [references/meta-tag-code-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/meta-tags-optimizer/references/meta-tag-code-templates.md)._ + +### A/B Test Variations + +**Title Variation B**: +"Start a Podcast in [current year]: Step-by-Step Guide (+ Free Checklist)" + +**Title Variation C**: +"How to Start a Podcast: [current year] Guide [Equipment + Software + Tips]" + +**Description Variation B**: +"Want to start a podcast in [current year]? This guide covers everything: equipment ($100 budget option), best hosting platforms, recording tips, and how to get your first 1,000 listeners." +``` + +## Tips for Success + +1. **Front-load keywords** - Put important terms at the beginning +2. **Match intent** - Description should preview what page delivers +3. **Be specific** - Vague descriptions get ignored +4. **Test variations** - Small changes can significantly impact CTR +5. **Update regularly** - Add current year, refresh messaging +6. **Check competitors** - See what's working in your SERP + + +### Save Results + +After delivering content or optimization output to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to `memory/content/YYYY-MM-DD-.md` containing: +- One-line description of what was created +- Target keyword and content type +- Open loops or items needing review +- Source data references + +**Gate check recommended**: Run content-quality-auditor before publishing (PostToolUse hook will remind automatically). + +If any findings should influence ongoing strategy, recommend promoting key conclusions to `memory/hot-cache.md`. + +## Reference Materials + +- [Meta Tag Formulas](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/meta-tags-optimizer/references/meta-tag-formulas.md) — Proven title and description formulas +- [CTR and Social Reference](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/meta-tags-optimizer/references/ctr-and-social-reference.md) — Page-type templates, CTR data, OG best practices + +## Next Best Skill + +- **Primary**: [schema-markup-generator](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/schema-markup-generator/SKILL.md) — complete the SERP packaging with structured data. diff --git a/.cursor/skills/meta-tags-optimizer/references/ctr-and-social-reference.md b/.cursor/skills/meta-tags-optimizer/references/ctr-and-social-reference.md new file mode 100644 index 0000000000..8fc5205c80 --- /dev/null +++ b/.cursor/skills/meta-tags-optimizer/references/ctr-and-social-reference.md @@ -0,0 +1,149 @@ +# CTR Optimization, Social Tags, and Page-Type Templates + +Reference tables for click-through rate optimization, Open Graph best practices, meta description copywriting frameworks, and page-type meta tag templates. + +--- + +## Page-Type Meta Tag Templates + +### Homepage + +```html +[Brand Name] - [Primary Value Proposition] + +``` + +### Product Page + +```html +[Product Name] - [Key Benefit] | [Brand] + +``` + +### Blog Post + +```html +[How to/What is/Number] [Keyword] [Benefit/Year] + +``` + +### Service Page + +```html +[Service] in [Location] - [Brand] | [Differentiator] + +``` + +--- + +## Title Tag Formula Patterns + +### Proven Title Formulas + +| Formula | Template | Example | Best For | +|---------|----------|---------|---------| +| How-To | How to [Achieve Result] ([Year]) | How to Improve SEO Rankings (2026) | Informational guides | +| Number List | [Number] [Adjective] [Topic] for [Audience] | 15 Proven SEO Strategies for E-commerce | Listicles | +| Question | [Question]? Here's [Answer Preview] | What Is Technical SEO? Complete Guide | Definition content | +| Comparison | [Option A] vs [Option B]: [Differentiator] | Ahrefs vs SEMrush: Which SEO Tool Wins? | Comparison pages | +| Year-Based | Best [Topic] in [Year] ([Tested/Ranked]) | Best SEO Tools in 2026 (Expert Tested) | Evergreen + fresh | +| Benefit-Driven | [Benefit]: [How to Achieve It] | Rank #1 on Google: 10-Step SEO Checklist | High-CTR pages | +| Parenthetical | [Topic] ([Modifier]) | Link Building Guide (With Templates) | Adding value signal | +| Negative | [Number] [Topic] Mistakes [Consequence] | 7 SEO Mistakes That Kill Your Rankings | Problem-awareness content | + +### Title Tag Power Words + +| Category | Power Words | Use Sparingly | +|----------|-----------|---------------| +| Urgency | Now, Today, Quick, Fast, Instant, 2026 | Don't overuse; pair with substance | +| Value | Free, Proven, Complete, Essential, Ultimate | Avoid hyperbole without backing | +| Specificity | [Exact number], Step-by-Step, Checklist, Template | More specific = more clicks | +| Curiosity | Secret, Little-Known, Surprising, Actually | Must deliver on the promise | +| Authority | Expert, Research-Backed, Data-Driven, Tested | Only use when genuinely expert content | +| Emotional | Best, Worst, Mistakes, Warning, Powerful | Balance emotion with credibility | + +### Title Tag Length Optimization + +| Length Range | SERP Behavior | Recommendation | +|-------------|--------------|----------------| +| <30 characters | May appear thin | Expand with modifier or brand | +| 30-50 characters | Fully displayed on all devices | Ideal for mobile-first | +| 50-60 characters | Full display on desktop, may truncate mobile | Sweet spot for desktop | +| 60-65 characters | Truncated on some devices | Front-load keywords | +| >65 characters | Truncated everywhere | Avoid — key info gets cut | + +--- + +## Meta Description Copywriting Frameworks + +### AIDA Framework + +| Element | What It Does | Example | +|---------|-------------|---------| +| **A**ttention | Hook with a bold claim or question | "Want to double your organic traffic?" | +| **I**nterest | Build relevance | "This guide covers 15 proven strategies..." | +| **D**esire | Show benefit | "...used by top-ranking sites to increase traffic by 200%." | +| **A**ction | CTA | "Read the full guide now." | + +**Full Example**: "Want to double your organic traffic? This guide covers 15 proven SEO strategies used by top-ranking sites to increase traffic by 200%. Read the full guide now." (158 chars) + +### PAS Framework + +| Element | What It Does | Example | +|---------|-------------|---------| +| **P**roblem | Identify pain point | "Struggling to rank on Google?" | +| **A**gitate | Amplify the problem | "Most SEO guides are outdated and miss key ranking factors." | +| **S**olution | Offer the solution | "Our 2026 guide covers what actually works. Read now." | + +### Benefit-Proof-CTA Framework + +| Element | Example | +|---------|---------| +| Benefit | "Learn the exact SEO process that grew our traffic 5x" | +| Proof | "— with real data from 200+ audits." | +| CTA | "Get the free checklist." | + +--- + +## CTR Optimization Data + +### Factors That Increase Organic CTR + +| Factor | CTR Impact | Implementation | +|--------|-----------|----------------| +| Number in title | +20-30% | "7 Ways", "15 Tips", "2026" | +| Question in title | +14% | Start with How, What, Why | +| Emotional words | +7% | "Proven", "Essential", "Mistake" | +| Brackets/parentheses | +38% | "[Guide]", "(With Examples)" | +| Current year | +10-15% | "Best SEO Tools 2026" | +| Power words | +12% | See Power Words table above | +| Match search intent | +15-25% | Align title with SERP expectations | +| Rich results (schema) | +30% | FAQ, HowTo, Review stars | + +--- + +## Open Graph Best Practices by Platform + +### Platform-Specific OG Optimization + +| Platform | Image Size | Title Length | Description Length | Special Tags | +|----------|-----------|-------------|-------------------|-------------| +| Facebook | 1200x630px | 40-60 chars | 125-155 chars | og:type, og:locale | +| Twitter/X | 1200x600px | 70 chars max | 200 chars | twitter:card, twitter:site | +| LinkedIn | 1200x627px | 70 chars | 150 chars | Standard OG tags | +| Pinterest | 1000x1500px (2:3) | 100 chars | 500 chars | og:type=article preferred | +| Slack | 500x500px min | Full title | First ~300 chars | Standard OG tags | + +### OG Tag Checklist + +| Tag | Required? | Notes | +|-----|----------|-------| +| og:title | Yes | Can differ from HTML title; optimize for social sharing | +| og:description | Yes | Social-optimized; can differ from meta description | +| og:image | Yes | Must be absolute URL; minimum 200x200px, ideal 1200x630px | +| og:url | Yes | Canonical URL | +| og:type | Yes | "website" for homepage, "article" for blog posts | +| og:site_name | Recommended | Your brand name | +| og:locale | Recommended | e.g., "en_US" | +| twitter:card | Recommended | "summary_large_image" for articles | +| twitter:site | Recommended | @yourbrand | diff --git a/.cursor/skills/meta-tags-optimizer/references/meta-tag-code-templates.md b/.cursor/skills/meta-tags-optimizer/references/meta-tag-code-templates.md new file mode 100644 index 0000000000..88d5b62867 --- /dev/null +++ b/.cursor/skills/meta-tags-optimizer/references/meta-tag-code-templates.md @@ -0,0 +1,153 @@ +# Meta Tag Code Templates + +HTML code templates for Open Graph tags, Twitter cards, additional meta tags, and complete meta tag blocks. + +--- + +## Open Graph Tags (Facebook, LinkedIn, etc.) + +**Required OG Tags**: + +```html + + + + + + + + + + +``` + +**OG Type Selection Guide**: + +| Page Type | og:type | +|-----------|---------| +| Blog post | article | +| Homepage | website | +| Product | product | +| Video | video.other | +| Profile | profile | + +**OG Title Considerations**: +- Can be different from title tag +- Optimize for social sharing context +- More conversational tone acceptable +- Up to 60 characters ideal + +**OG Description Considerations**: +- Can be longer than meta description (up to 200 chars) +- Focus on shareability +- What would make someone click when shared? + +**OG Image Requirements**: +- Recommended size: 1200x630 pixels +- Minimum size: 600x315 pixels +- Format: JPG or PNG +- Keep text to less than 20% of image +- Include branding subtly + +--- + +## Twitter Card Tags + +**Card Type Selection**: + +| Card Type | Best For | Image Size | +|-----------|----------|------------| +| summary | Articles, blogs | 144x144 min | +| summary_large_image | Visual content | 300x157 min | +| player | Video/audio | 640x360 min | +| app | Mobile apps | 800x418 | + +**Twitter Card Code**: + +```html + + + + + + + + +``` + +**Twitter-Specific Considerations**: +- Shorter titles work better (under 70 chars) +- Include @mentions if relevant +- Hashtag-relevant terms can help discovery +- Test with Twitter Card Validator + +--- + +## Additional Recommended Meta Tags + +**Canonical URL** (Prevent duplicates): +```html + +``` + +**Robots Tag** (Indexing control): +```html + +``` + +**Viewport** (Mobile optimization): +```html + +``` + +**Author** (For articles): +```html + +``` + +**Language**: +```html + +``` + +**Article-Specific** (For blog posts): +```html + + + + + +``` + +--- + +## Complete Meta Tag Block Template + +Copy and paste this complete meta tag block: + +```html + +[Optimized Title] + + + + + + + + + + + + + + + + + + + + + + +``` diff --git a/.cursor/skills/meta-tags-optimizer/references/meta-tag-formulas.md b/.cursor/skills/meta-tags-optimizer/references/meta-tag-formulas.md new file mode 100644 index 0000000000..dd1399f2be --- /dev/null +++ b/.cursor/skills/meta-tags-optimizer/references/meta-tag-formulas.md @@ -0,0 +1,355 @@ +# Meta Tag Formulas Reference + +Extended title tag formulas, meta description templates, A/B testing methodology, seasonal patterns, CTR benchmarks, and multi-language optimization guidance. + +--- + +## Title Tag Formulas by Content Type + +### Informational Content + +| # | Formula | Template | Example | +|---|---------|----------|---------| +| 1 | How-To + Year | How to [Action] in [Year] | How to Build Backlinks in 2026 | +| 2 | How-To + Result | How to [Action] ([Result]) | How to Write Meta Tags (Rank Higher) | +| 3 | Definitive Guide | The Definitive Guide to [Topic] | The Definitive Guide to Technical SEO | +| 4 | Complete Guide | [Topic]: The Complete Guide ([Year]) | Schema Markup: The Complete Guide (2026) | +| 5 | Beginner's Guide | [Topic] for Beginners: [Promise] | SEO for Beginners: Rank in 30 Days | +| 6 | What Is | What Is [Topic]? [Short Clarifier] | What Is E-E-A-T? Google's Quality Standard | +| 7 | Everything You Need | Everything You Need to Know About [Topic] | Everything You Need to Know About Core Web Vitals | +| 8 | Step-by-Step | [Topic]: A Step-by-Step Guide | Link Building: A Step-by-Step Guide | + +### Listicle Content + +| # | Formula | Template | Example | +|---|---------|----------|---------| +| 9 | Numbered Tips | [N] [Topic] Tips That [Result] | 12 On-Page SEO Tips That Boost Rankings | +| 10 | Best Of | [N] Best [Items] in [Year] ([Qualifier]) | 9 Best SEO Tools in 2026 (Expert Tested) | +| 11 | Ways To | [N] Ways to [Achieve Goal] [Timeframe] | 7 Ways to Increase Organic Traffic This Month | +| 12 | Strategies | [N] [Adjective] [Topic] Strategies for [Audience] | 15 Proven Content Strategies for SaaS | +| 13 | Examples | [N] [Topic] Examples [Value Add] | 20 Meta Description Examples (+ Templates) | +| 14 | Mistakes | [N] [Topic] Mistakes [Negative Consequence] | 10 Title Tag Mistakes That Hurt Your CTR | +| 15 | Secrets | [N] [Topic] Secrets [Experts/Pros] Use | 5 SEO Secrets Top Agencies Use | +| 16 | Reasons | [N] Reasons [Why/To] [Statement] | 8 Reasons Your Site Isn't Ranking | + +### Comparison Content + +| # | Formula | Template | Example | +|---|---------|----------|---------| +| 17 | A vs B | [A] vs [B]: [Differentiator] | Ahrefs vs SEMrush: Which Tool Is Better? | +| 18 | A vs B + Year | [A] vs [B] ([Year]): [Angle] | WordPress vs Webflow (2026): Honest Comparison | +| 19 | A vs B + Winner | [A] vs [B]: Which [Category] Wins? | Yoast vs Rank Math: Which SEO Plugin Wins? | +| 20 | Alternatives | [N] Best [Product] Alternatives in [Year] | 7 Best Ahrefs Alternatives in 2026 | + +### Commercial / Transactional Content + +| # | Formula | Template | Example | +|---|---------|----------|---------| +| 21 | Product + Benefit | [Product] - [Primary Benefit] \| [Brand] | SEO Audit Tool - Find Issues in Minutes \| SiteChecker | +| 22 | Pricing | [Product] Pricing: [Value Statement] | Semrush Pricing: Plans from $119/mo (2026) | +| 23 | Review | [Product] Review ([Year]): [Verdict] | Surfer SEO Review (2026): Worth the Price? | +| 24 | Free Tool | Free [Tool Type]: [What It Does] | Free Meta Tag Generator: Preview Your SERP Listing | + +### Local SEO Content + +| # | Formula | Template | Example | +|---|---------|----------|---------| +| 25 | Service + Location | [Service] in [City] - [Brand] \| [Differentiator] | Plumber in Austin - FastFix \| Same-Day Service | +| 26 | Best + Location | Best [Service] in [City] ([Year]) | Best Coffee Shops in Portland (2026) | +| 27 | Near Me Style | [Service] Near [Location]: [Value] | SEO Agency Near Chicago: Free Site Audit | +| 28 | Location Guide | [Topic] in [Location]: [Qualifier] Guide | Restaurants in Brooklyn: The Local's Guide | + +### Problem-Awareness Content + +| # | Formula | Template | Example | +|---|---------|----------|---------| +| 29 | Warning | Warning: [Problem] [Consequence] | Warning: These SEO Tactics Will Get You Penalized | +| 30 | Why + Problem | Why [Problem Exists] (And How to Fix It) | Why Your Meta Descriptions Are Ignored (And How to Fix It) | +| 31 | Stop Doing | Stop [Bad Practice]: [Better Alternative] | Stop Keyword Stuffing: What to Do Instead | +| 32 | Truth About | The Truth About [Topic] [Revelation] | The Truth About SEO in 2026: What Changed | + +--- + +## Meta Description Templates + +### By Content Type + +#### Blog Posts / Articles + +| # | Template | Character Count | +|---|----------|-----------------| +| 1 | Learn [topic] with our [qualifier] guide. Covers [point 1], [point 2], and [point 3]. [CTA]. | ~140-155 | +| 2 | [Question]? This [year] guide explains [what], [why], and [how]. Get actionable tips now. | ~130-150 | +| 3 | Discover [N] [adjective] [topic] strategies that [result]. Backed by [proof element]. Read the full guide. | ~145-160 | +| 4 | [Bold claim about topic]. We tested [N] [methods/tools] and found what works. See the results. | ~130-150 | + +#### Product / Service Pages + +| # | Template | Character Count | +|---|----------|-----------------| +| 5 | [Product] helps you [benefit]. [Feature 1], [Feature 2], [Feature 3]. [Price/offer]. [CTA]. | ~140-155 | +| 6 | Looking for [solution]? [Product] [key differentiator]. Trusted by [social proof]. [CTA]. | ~130-150 | +| 7 | [Product] - [primary benefit] in [timeframe]. [Star rating] from [N]+ reviews. [CTA]. | ~130-145 | + +#### E-commerce / Category Pages + +| # | Template | Character Count | +|---|----------|-----------------| +| 8 | Shop [category] from [Brand]. [N]+ [items] starting at $[price]. Free shipping on orders over $[amount]. | ~145-160 | +| 9 | Browse our [adjective] collection of [products]. [Unique selling point]. [Guarantee/offer]. Order today. | ~140-155 | + +#### Comparison Pages + +| # | Template | Character Count | +|---|----------|-----------------| +| 10 | [A] vs [B]: which is better for [use case]? We compared [criteria]. See the winner + detailed breakdown. | ~145-160 | +| 11 | Comparing [A] and [B] on [criteria 1], [criteria 2], and price. Our [year] verdict inside. | ~130-145 | + +#### Local Business Pages + +| # | Template | Character Count | +|---|----------|-----------------| +| 12 | [Service] in [City] by [Brand]. [Experience] years of experience. [N]-star rated. [CTA] — call [phone] today. | ~150-160 | +| 13 | Need [service] in [location]? [Brand] offers [differentiator]. [Guarantee]. Book your [offer] now. | ~140-155 | + +--- + +## A/B Testing Methodology for Titles and Descriptions + +### Pre-Test Preparation + +1. **Baseline metrics** — Record current CTR, average position, impressions, and clicks for the target page (minimum 30 days of data from ~~search console). +2. **Hypothesis** — State what you expect to change and why: "Adding a number to the title will increase CTR by X% because listicle titles outperform generic ones at this SERP position." +3. **Single variable** — Change only ONE element per test (title OR description, not both). +4. **Minimum sample** — Wait until the page has accumulated at least 1,000 impressions in the test period before drawing conclusions. + +### Test Execution Steps + +| Step | Action | Duration | +|------|--------|----------| +| 1 | Record baseline CTR for 30 days | 30 days | +| 2 | Implement title/description change | Day 0 | +| 3 | Allow Google to re-crawl and update SERP | 3-7 days | +| 4 | Monitor new CTR (exclude first 7 days) | 30+ days | +| 5 | Compare new CTR vs. baseline at same avg. position | — | +| 6 | Decide: keep, revert, or iterate | — | + +### What to Test (Priority Order) + +| Priority | Element | Test Variable | Expected Impact | +|----------|---------|--------------|-----------------| +| 1 | Title tag | Add/remove number | +15-25% CTR | +| 2 | Title tag | Add/remove year | +10-15% CTR | +| 3 | Title tag | Add brackets/parentheses | +10-38% CTR | +| 4 | Title tag | Change power word | +5-12% CTR | +| 5 | Title tag | Reorder keyword placement | +5-10% CTR | +| 6 | Meta description | Add CTA | +5-10% CTR | +| 7 | Meta description | Add numbers/statistics | +5-15% CTR | +| 8 | Meta description | Change emotional tone | +3-8% CTR | + +### Interpreting Results + +| Scenario | Interpretation | Action | +|----------|---------------|--------| +| CTR up, position stable | Title/description change is working | Keep the change | +| CTR up, position up | Improved engagement signals helping rankings | Keep and document | +| CTR down, position stable | Change was negative | Revert immediately | +| CTR flat, position stable | Change had no impact | Try a bolder variation | +| CTR up, position down | Higher CTR but lower impressions | Evaluate net click change | + +### Statistical Significance Checklist + +- [ ] Minimum 1,000 impressions in test period +- [ ] Test ran for at least 30 days (after re-crawl) +- [ ] Average position did not shift more than 2 positions +- [ ] No major algorithm updates during test period +- [ ] No seasonal bias (compare similar months year-over-year) +- [ ] CTR change exceeds 10% relative difference + +--- + +## Seasonal Title Patterns + +### Calendar-Driven Updates + +| Season/Event | Title Modifier | Example | +|-------------|---------------|---------| +| New Year (Jan) | [Year] Edition, Updated for [Year] | SEO Checklist: 2026 Edition | +| Q1 Planning | [Year] Strategy, Q1 [Year] | Content Strategy for Q1 2026 | +| Spring | Spring [Year], Fresh | Spring 2026 SEO Audit Checklist | +| Back to School (Aug-Sep) | Fall [Year], New Season | Fall 2026 Marketing Trends | +| Black Friday (Nov) | Black Friday [Year], Holiday | Black Friday SEO Prep Guide (2026) | +| End of Year (Dec) | [Year] Wrap-Up, [Next Year] Preview | 2026 SEO Wrap-Up + 2027 Predictions | +| Any month | [Month] [Year] | Best SEO Tools (February 2026) | + +### Evergreen + Fresh Hybrid Strategy + +Keep the core title evergreen but append a freshness signal: + +| Base Title (Evergreen) | Freshness Signal | Combined | +|-----------------------|------------------|----------| +| How to Start a Blog | (Updated Feb 2026) | How to Start a Blog (Updated Feb 2026) | +| Best CRM Software | [2026 Rankings] | Best CRM Software [2026 Rankings] | +| SEO Beginner's Guide | - Latest Edition | SEO Beginner's Guide - Latest Edition | + +**Update cadence**: Refresh the year/date modifier every 3-6 months for pages targeting "best", "top", or year-based queries. + +--- + +## CTR Benchmarks by Industry + +### Average Organic CTR by SERP Position (All Industries) + +| Position | Desktop CTR | Mobile CTR | Combined Avg | +|----------|------------|------------|-------------| +| 1 | 31.7% | 26.9% | 29.3% | +| 2 | 17.5% | 15.1% | 16.3% | +| 3 | 11.3% | 10.2% | 10.8% | +| 4 | 7.9% | 7.1% | 7.5% | +| 5 | 5.8% | 5.2% | 5.5% | +| 6 | 4.4% | 3.9% | 4.2% | +| 7 | 3.5% | 3.1% | 3.3% | +| 8 | 2.9% | 2.5% | 2.7% | +| 9 | 2.5% | 2.1% | 2.3% | +| 10 | 2.2% | 1.8% | 2.0% | + +### CTR Variation by Industry Vertical + +| Industry | Avg CTR (Pos 1) | Avg CTR (Pos 1-3) | Notes | +|----------|----------------|-------------------|-------| +| Technology / SaaS | 25-30% | 50-55% | High competition; rich results common | +| E-commerce | 20-25% | 40-45% | Shopping results reduce organic CTR | +| Healthcare | 28-35% | 55-60% | Users seek authoritative sources | +| Finance | 22-28% | 45-50% | Featured snippets capture clicks | +| Travel | 18-24% | 38-44% | Maps and hotel packs reduce CTR | +| Legal | 30-38% | 58-65% | High intent; fewer SERP features | +| Education | 26-32% | 52-58% | Informational queries; high trust needed | +| Real Estate | 20-26% | 42-48% | Local packs reduce organic CTR | +| Food / Recipes | 15-22% | 35-42% | Recipe carousels dominate top positions | +| B2B Services | 28-34% | 55-62% | Less SERP competition; niche queries | + +### When Your CTR Is Below Benchmark + +| CTR vs. Benchmark | Likely Cause | Recommended Action | +|-------------------|-------------|-------------------| +| 50%+ below | Title does not match intent | Rewrite title to align with query intent | +| 25-50% below | Weak title or strong SERP features | Add power words, numbers, or brackets | +| 10-25% below | Competitors have better titles | Analyze top 3 competitor titles and differentiate | +| At benchmark | Performing as expected | Test incremental improvements | +| Above benchmark | Strong title; optimize further | Protect current title; test description instead | + +--- + +## Multi-Language Title Optimization + +### General Principles + +1. **Do not translate literally** -- Adapt the title formula to the target language's natural phrasing and cultural norms. +2. **Character limits vary** -- CJK characters are wider; effective SERP display length is shorter by character count. +3. **Keyword research per locale** -- Search volume and intent differ across languages. Always do locale-specific keyword research. +4. **Brand name placement** -- Some markets prefer brand-first; others prefer keyword-first. + +### Language-Specific Considerations + +| Language | Max Chars (SERP) | Key Differences | Example Adaptation | +|----------|-----------------|-----------------|-------------------| +| English | 55-60 | Standard baseline | How to Learn SEO (2026 Guide) | +| Spanish | 55-60 | Longer phrases; use abbreviations | Como Aprender SEO: Guia Completa 2026 | +| French | 55-60 | Accented characters count same | Guide SEO Complet : Comment se Classer en 2026 | +| German | 50-55 | Compound words are long | SEO-Leitfaden 2026: Schritt-fur-Schritt | +| Japanese | 30-35 | CJK characters take ~2x width | SEO対策ガイド2026【初心者向け】 | +| Chinese (Simplified) | 28-32 | CJK characters; brackets common | SEO优化指南（2026完整版） | +| Korean | 30-35 | CJK width; particles add length | SEO 최적화 가이드 2026 [초보자용] | +| Arabic | 50-55 | RTL display; test SERP rendering | دليل تحسين محركات البحث 2026 | +| Portuguese (BR) | 55-60 | Similar to Spanish | Guia de SEO 2026: Como Ranquear no Google | +| Hindi | 45-50 | Devanagari takes more width | SEO कैसे करें: 2026 गाइड | + +### Multi-Language Meta Description Tips + +| Principle | Detail | +|-----------|--------| +| Localize the CTA | "Learn more" may not translate well; use culturally appropriate CTAs | +| Adjust character targets | For CJK, aim for 70-80 characters; for Latin-script languages, 150-160 | +| Use local proof points | Reference local statistics, regulations, or market leaders | +| Test SERP rendering | Use Google's SERP preview in the target locale to check truncation | +| Separate hreflang tags | Ensure each language version has the correct hreflang annotation | + +--- + +## Title Tag Modifier Library + +### Modifiers by Purpose + +| Purpose | Modifiers | +|---------|----------| +| Freshness | 2026, Updated, Latest, New, This Month, This Week | +| Comprehensiveness | Complete, Ultimate, Definitive, A-to-Z, Full, In-Depth | +| Ease | Easy, Simple, Quick, Beginner, No-Code, DIY | +| Speed | Fast, Instant, [N]-Minute, Today, Quick-Start | +| Authority | Expert, Pro, Advanced, Research-Backed, Data-Driven | +| Value | Free, Cheap, Budget, Affordable, Open-Source | +| Format | Guide, Checklist, Template, Cheat Sheet, Playbook, Toolkit | +| Exclusivity | Insider, Members-Only, Exclusive, First Look, Early Access | +| Social Proof | Trusted, [N]+ Users, Award-Winning, #1 Rated | +| Scarcity | Limited, Last Chance, Ending Soon, Only [N] Left | + +### Modifier Placement Rules + +| Position | When to Use | Example | +|----------|------------|---------| +| Front | When modifier IS the keyword ("Free", "Best") | Free SEO Audit Tool for Small Business | +| Middle | When clarifying the topic | SEO Tools (Free) for Small Business | +| End (parenthetical) | When adding value signal | SEO Tools for Small Business (Free) | +| End (pipe/dash) | When adding brand | SEO Tools for Small Business \| Brand | + +--- + +## Common Title Tag Mistakes + +| Mistake | Why It Hurts | Fix | +|---------|-------------|-----| +| Keyword stuffing | Google may rewrite your title | Use primary keyword once; vary phrasing | +| Too generic ("Home", "Welcome") | Zero CTR differentiation | Write a benefit-driven title | +| All caps | Looks spammy; may be rewritten | Use title case or sentence case | +| Missing primary keyword | Misses ranking signal | Include target keyword naturally | +| Duplicate titles across pages | Cannibalization; Google may pick wrong page | Unique title per page | +| Brand name first (non-branded query) | Wastes prime keyword space | Put brand at end after pipe | +| No emotional hook | Blends in with competitors | Add one power word or number | +| Exceeding 60 characters | Key info truncated in SERP | Front-load; keep under 60 chars | +| Misleading clickbait | High bounce rate hurts rankings | Title must match content delivery | +| Ignoring SERP context | Title doesn't stand out among competitors | Check live SERP before finalizing | + +--- + +## Quick-Reference: Title Formula Selection Flowchart + +``` +START: What type of content is this? +| ++-- Informational (how-to, guide, tutorial) +| +-- Is it step-by-step? --> Use Formula #2 or #8 +| +-- Is it a definition? --> Use Formula #6 +| +-- Is it comprehensive? --> Use Formula #3 or #4 +| +-- Is it for beginners? --> Use Formula #5 +| ++-- Listicle (tips, tools, examples) +| +-- Is it "best of"? --> Use Formula #10 +| +-- Is it mistakes/warnings? --> Use Formula #14 or #29 +| +-- Is it tips/strategies? --> Use Formula #9 or #12 +| +-- Is it examples? --> Use Formula #13 +| ++-- Comparison +| +-- Two products/tools? --> Use Formula #17 or #18 +| +-- Multiple alternatives? --> Use Formula #20 +| ++-- Commercial / Product +| +-- Product page? --> Use Formula #21 +| +-- Pricing page? --> Use Formula #22 +| +-- Review? --> Use Formula #23 +| +-- Free tool? --> Use Formula #24 +| ++-- Local +| +-- Service page? --> Use Formula #25 +| +-- Best-of local? --> Use Formula #26 +| +-- Near me? --> Use Formula #27 +``` diff --git a/.cursor/skills/on-page-seo-auditor/SKILL.md b/.cursor/skills/on-page-seo-auditor/SKILL.md new file mode 100644 index 0000000000..170bee1145 --- /dev/null +++ b/.cursor/skills/on-page-seo-auditor/SKILL.md @@ -0,0 +1,364 @@ +--- +name: on-page-seo-auditor +description: 'Audit on-page SEO: titles, headers, images, links with scored report and fix priorities. 页面SEO审计/排名诊断' +version: "6.0.0" +license: Apache-2.0 +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when auditing a page's on-page SEO health, checking heading structure, keyword placement, image optimization, or content quality signals." +argument-hint: " [keyword]" +allowed-tools: WebFetch +metadata: + author: aaron-he-zhu + version: "6.0.0" + geo-relevance: "medium" + tags: + - seo + - on-page-audit + - page-optimization + - seo-score + - content-audit + - h1-optimization + - meta-audit + - seo-checklist + - yoast-alternative + - screaming-frog-alternative + - 页面SEO + - 网页优化 + - ページSEO + - 페이지감사 + - auditoria-seo + triggers: + # EN-formal + - "audit page SEO" + - "on-page SEO check" + - "SEO score" + - "page optimization" + - "on-page audit" + - "SEO page analysis" + - "content audit" + # EN-casual + - "what SEO issues does this page have" + - "check my page" + - "score my page" + - "why isn't this page ranking" + - "what's wrong with this page's SEO" + - "is my page optimized" + - "my rankings tanked" + - "why did my rankings drop" + # EN-question + - "why is my page not ranking" + - "how do I improve my page SEO" + - "what SEO problems does this page have" + # EN-competitor + - "Screaming Frog alternative" + - "Yoast SEO alternative" + # ZH-pro + - "页面SEO审计" + - "网页优化检查" + - "SEO评分" + - "页面诊断" + - "页面优化分析" + # ZH-casual + - "页面有什么问题" + - "为什么排不上去" + - "检查一下我的页面" + - "SEO打分" + - "排名上不去怎么办" + - "网页收录问题" + # JA + - "ページSEO監査" + - "オンページSEO" + - "ページ最適化" + - "SEOスコア" + # KO + - "페이지 SEO 감사" + - "온페이지 SEO" + - "SEO 점수" + - "이 페이지 뭐가 문제야?" + - "왜 순위가 안 올라가?" + - "SEO 점수 확인해줘" + # ES + - "auditoría SEO on-page" + - "análisis de página SEO" + - "puntuación SEO" + # PT + - "auditoria SEO on-page" + # Misspellings + - "on page SEO aduit" + - "SEO scroe" +--- + +# On-Page SEO Auditor + + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This optimization skill follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + + +This skill performs detailed on-page SEO audits to identify issues and optimization opportunities. It analyzes all on-page elements that affect search rankings and provides actionable recommendations. + +**System role**: Optimization layer skill. It turns weak pages, structures, and technical issues into prioritized repair work. + +## When This Must Trigger + +Use this when the conversation involves any of these situations — even if the user does not use SEO terminology: + +Use this whenever the task needs a diagnosis or repair plan that should feed directly into remediation work, not just a one-time opinion. + +- Auditing pages before or after publishing +- Identifying why a page isn't ranking well +- Optimizing existing content for better performance +- Creating pre-publish SEO checklists +- Comparing your on-page SEO to competitors +- Systematic site-wide SEO improvements +- Training team members on SEO best practices + +## What This Skill Does + +1. **Title Tag Analysis**: Evaluates title optimization and CTR potential +2. **Meta Description Review**: Checks description quality and length +3. **Header Structure Audit**: Analyzes H1-H6 hierarchy +4. **Content Quality Assessment**: Reviews content depth and optimization +5. **Keyword Usage Analysis**: Checks keyword placement and density +6. **Internal Link Review**: Evaluates internal linking structure +7. **Image Optimization Check**: Audits alt text and file optimization +8. **Technical On-Page Review**: Checks URL, canonical, and mobile factors + +## Quick Start + +Start with one of these prompts. Finish with a short handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Audit a Single Page + +``` +Audit the on-page SEO of [URL] +``` + +``` +Check SEO issues on this page targeting [keyword]: [URL/content] +``` + +### Compare Against Competitors + +``` +Compare on-page SEO of [your URL] vs [competitor URL] for [keyword] +``` + +### Audit Content Before Publishing + +``` +Pre-publish SEO audit for this content targeting [keyword]: [content] +``` + +## Skill Contract + +**Expected output**: a scored diagnosis, prioritized repair plan, and a short handoff summary ready for `memory/audits/`. + +- **Reads**: the current page or site state, symptoms, prior audits, and current priorities from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available. +- **Writes**: a user-facing audit or optimization plan plus a reusable summary that can be stored under `memory/audits/`. +- **Promotes**: blocking defects, repeated weaknesses, and fix priorities to `memory/open-loops.md` and `memory/decisions.md`. +- **Next handoff**: use the `Next Best Skill` below when the repair path is clear. + +## Data Sources + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +**With ~~SEO tool + ~~web crawler connected:** +Claude can automatically pull page HTML via ~~web crawler, fetch keyword search volume and difficulty from ~~SEO tool, retrieve click-through rate data from ~~search console, and download competitor pages for comparison. This enables fully automated audits with live data. + +**With manual data only:** +Ask the user to provide: +1. Page URL or complete HTML content +2. Target primary and secondary keywords +3. Competitor page URLs for comparison (optional) + +Proceed with the full audit using provided data. Note in the output which findings are from automated crawl vs. manual review. + +## Instructions + +When a user requests an on-page SEO audit: + +1. **Gather Page Information** + + ```markdown + ### Audit Setup + + **Page URL**: [URL] + **Target Keyword**: [primary keyword] + **Secondary Keywords**: [additional keywords] + **Page Type**: [blog/product/landing/service] + **Business Goal**: [traffic/conversions/authority] + ``` + +2. **Audit Title Tag** + + ```markdown + ## Title Tag Analysis + + **Current Title**: [title] + **Character Count**: [X] characters + + | Criterion | Status | Notes | + |-----------|--------|-------| + | Length (50-60 chars) | ✅/⚠️/❌ | [notes] | + | Keyword included | ✅/⚠️/❌ | Position: [front/middle/end] | + | Keyword at front | ✅/⚠️/❌ | [notes] | + | Unique across site | ✅/⚠️/❌ | [notes] | + | Compelling/clickable | ✅/⚠️/❌ | [notes] | + | Matches intent | ✅/⚠️/❌ | [notes] | + + **Title Score**: [X]/10 + + **Issues Found**: + - [Issue 1] + - [Issue 2] + + **Recommended Title**: + "[Optimized title suggestion]" + + **Why**: [Explanation of improvements] + ``` + +3. **Audit Meta Description** + + ```markdown + ## Meta Description Analysis + + **Current Description**: [description] + **Character Count**: [X] characters + + | Criterion | Status | Notes | + |-----------|--------|-------| + | Length (150-160 chars) | ✅/⚠️/❌ | [notes] | + | Keyword included | ✅/⚠️/❌ | [notes] | + | Call-to-action present | ✅/⚠️/❌ | [notes] | + | Unique across site | ✅/⚠️/❌ | [notes] | + | Accurately describes page | ✅/⚠️/❌ | [notes] | + | Compelling copy | ✅/⚠️/❌ | [notes] | + + **Description Score**: [X]/10 + + **Issues Found**: + - [Issue 1] + + **Recommended Description**: + "[Optimized description suggestion]" ([X] chars) + ``` + +4. **Audit Header Structure** + + ```markdown + ## Header Structure Analysis + + ### Current Header Hierarchy + + ``` + H1: [H1 text] + H2: [H2 text] + H3: [H3 text] + H3: [H3 text] + H2: [H2 text] + H3: [H3 text] + H2: [H2 text] + ``` + + | Criterion | Status | Notes | + |-----------|--------|-------| + | Single H1 | ✅/⚠️/❌ | Found: [X] H1s | + | H1 includes keyword | ✅/⚠️/❌ | [notes] | + | Logical hierarchy | ✅/⚠️/❌ | [notes] | + | H2s include keywords | ✅/⚠️/❌ | [X]/[Y] contain keywords | + | No skipped levels | ✅/⚠️/❌ | [notes] | + | Descriptive headers | ✅/⚠️/❌ | [notes] | + + **Header Score**: [X]/10 + + **Issues Found**: + - [Issue 1] + - [Issue 2] + + **Recommended Changes**: + - H1: [suggestion] + - H2s: [suggestions] + ``` + +5. **Audit Content Quality** — Word count, reading level, comprehensiveness, formatting, E-E-A-T signals, content elements checklist, gap identification + + > **Reference**: See [references/audit-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/references/audit-templates.md) for the content quality template (Step 5). + +6. **Audit Keyword Usage** — Primary/secondary keyword placement across all page elements, LSI/related terms, density analysis + + > **Reference**: See [references/audit-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/references/audit-templates.md) for the keyword optimization template (Step 6). + +7. **Audit Internal Links** — Link count, anchor text relevance, broken links, recommended additions + + > **Reference**: See [references/audit-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/references/audit-templates.md) for the internal linking template (Step 7). + +8. **Audit Images** — Alt text, file names, sizes, formats, lazy loading + + > **Reference**: See [references/audit-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/references/audit-templates.md) for the image optimization template (Step 8). + +9. **Audit Technical On-Page Elements** — URL, canonical, mobile, speed, HTTPS, schema + + > **Reference**: See [references/audit-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/references/audit-templates.md) for the technical on-page template (Step 9). + +10. **CORE-EEAT Content Quality Quick Scan** — 17 on-page-relevant items from the 80-item CORE-EEAT benchmark + + > **Reference**: See [references/audit-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/references/audit-templates.md) for the CORE-EEAT quick scan template (Step 10). Full benchmark: [CORE-EEAT Benchmark](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/core-eeat-benchmark.md). + +11. **Generate Audit Summary** — Overall score with visual breakdown, priority issues (critical/important/minor), quick wins, detailed recommendations, competitor comparison, action checklist, expected results + + > **Reference**: See [references/audit-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/references/audit-templates.md) for the full audit summary template (Step 11). + +## Validation Checkpoints + +### Input Validation +- [ ] Target keyword(s) clearly specified by user +- [ ] Page content accessible (either via URL or provided HTML) +- [ ] If competitor comparison requested, competitor URL provided + +### Output Validation +- [ ] Every recommendation cites specific data points (not generic advice) +- [ ] Scores based on measurable criteria, not subjective opinion +- [ ] All suggested changes include specific locations (title tag, H2 #3, paragraph 5, etc.) +- [ ] Source of each data point clearly stated (~~SEO tool data, user-provided, ~~web crawler, or manual review) + +## Example + +> **Reference**: See [references/audit-example.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/references/audit-example.md) for a full worked example (noise-cancelling headphones audit) and page-type checklists (blog post, product page, landing page). + +## Tips for Success + +1. **Prioritize issues by impact** - Fix critical issues first +2. **Compare to competitors** - See what's working for top rankings +3. **Balance optimization and readability** - Don't over-optimize +4. **Audit regularly** - Content degrades over time +5. **Test changes** - Track ranking changes after updates + +> **Scoring details**: For the complete weight distribution, scoring scale, issue resolution playbook, and industry benchmarks, see [references/scoring-rubric.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/references/scoring-rubric.md). + + +### Save Results + +After delivering audit or optimization findings to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to `memory/audits/on-page-seo-auditor/YYYY-MM-DD-.md` containing: +- One-line verdict or headline finding +- Top 3-5 actionable items +- Open loops or blockers +- Source data references + +If any veto-level issue was found (CORE-EEAT T04, C01, R10 or CITE T03, T05, T09), also append a one-liner to `memory/hot-cache.md` without asking. + +## Reference Materials + +- [Scoring Rubric](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/references/scoring-rubric.md) — Detailed scoring criteria, weight distribution, and grade boundaries for on-page audits +- [Audit Templates](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/references/audit-templates.md) — Detailed output templates for steps 5-11 (content quality, keywords, links, images, technical, CORE-EEAT scan, audit summary) +- [Audit Example & Checklists](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/references/audit-example.md) — Full worked example and page-type checklists (blog, product, landing page) + +## Next Best Skill + +- **Primary**: [content-refresher](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/content-refresher/SKILL.md) — turn page-level findings into concrete edits. diff --git a/.cursor/skills/on-page-seo-auditor/references/audit-example.md b/.cursor/skills/on-page-seo-auditor/references/audit-example.md new file mode 100644 index 0000000000..60b2b59882 --- /dev/null +++ b/.cursor/skills/on-page-seo-auditor/references/audit-example.md @@ -0,0 +1,109 @@ +# On-Page SEO Auditor — Worked Example & Page Type Checklists + +Referenced from [SKILL.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/SKILL.md). + +--- + +## Worked Example + +**User**: "Audit the on-page SEO of https://example.com/best-noise-cancelling-headphones targeting 'best noise cancelling headphones'" + +**Output**: + +```markdown +# On-Page SEO Audit Report + +**Page**: https://example.com/best-noise-cancelling-headphones +**Target Keyword**: best noise cancelling headphones +**Secondary Keywords**: wireless noise cancelling headphones, ANC headphones, noise cancelling headphones review +**Page Type**: commercial (reviews/roundup) +**Audit Date**: 2025-01-15 + +## Summary + +| Audit Area | Score | Key Finding | +|------------|-------|-------------| +| Title Tag | 8/10 | Good keyword placement; slightly long at 63 chars | +| Meta Description | 6/10 | Missing CTA; keyword present but generic copy | +| Header Structure | 9/10 | Clean hierarchy; H2s cover all major products | +| Content Quality | 7/10 | 2,400 words is solid; lacks original test data | +| Keyword Optimization | 8/10 | Strong placement; density at 1.2% is healthy | +| Internal Links | 5/10 | Only 2 internal links; missing links to brand pages | +| Images | 6/10 | 3/8 images missing alt text; no WebP format | +| Technical Elements | 7/10 | Missing Product schema; good URL and mobile | + +## Overall Score: 71/100 + +Calculation: (8x0.15 + 6x0.05 + 9x0.10 + 7x0.25 + 8x0.15 + 5x0.10 + 6x0.10 + 7x0.10) x 10 = 71 + +Score Breakdown: +████████░░ Title Tag: 8/10 (15%) +██████░░░░ Meta Description: 6/10 ( 5%) +█████████░ Headers: 9/10 (10%) +███████░░░ Content: 7/10 (25%) +████████░░ Keywords: 8/10 (15%) +█████░░░░░ Internal Links: 5/10 (10%) +██████░░░░ Images: 6/10 (10%) +███████░░░ Technical: 7/10 (10%) + +## Priority Issues + +### Critical +1. **Internal linking severely underdeveloped** — Only 2 internal links found. Add links to individual headphone review pages (/sony-wh1000xm5-review, /bose-qc-ultra-review) and the headphones category page. Target 5-8 contextual internal links. +2. **3 product images missing alt text** — Images for Sony WH-1000XM5, Bose QC Ultra, and Apple AirPods Max have empty alt attributes. Each missing alt tag is a lost ranking signal in Google Images. + +### Important +1. **Meta description lacks call-to-action** — Current description states facts but does not compel clicks. Add "Compare prices and features" or "See our top picks" to drive CTR. + +## Quick Wins + +1. **Add alt text to 3 images** (5 min) — Use descriptive text like "Sony WH-1000XM5 noise cancelling headphones on desk" instead of empty attributes. +2. **Rewrite meta description with CTA** (5 min) — Change to: "Compare the 10 best noise cancelling headphones for 2025. Expert-tested picks from Sony, Bose, and Apple with pros, cons, and pricing. See our top picks." +3. **Add 4+ internal links** (10 min) — Link product names to their individual review pages and add a "See all headphones" link to the category hub. +``` + +--- + +## Audit Checklists by Page Type + +### Blog Post Checklist + +```markdown +- [ ] Title includes keyword and is compelling +- [ ] Meta description has keyword and CTA +- [ ] Single H1 with keyword +- [ ] H2s cover main topics +- [ ] Keyword in first 100 words +- [ ] 1,500+ words for competitive topics +- [ ] 3+ internal links with varied anchors +- [ ] Images with descriptive alt text +- [ ] FAQ section with schema +- [ ] Author bio with credentials +``` + +### Product Page Checklist + +```markdown +- [ ] Product name in title +- [ ] Price and availability in description +- [ ] H1 is product name +- [ ] Product features in H2s +- [ ] Multiple product images with alt text +- [ ] Customer reviews visible +- [ ] Product schema implemented +- [ ] Related products linked +- [ ] Clear CTA button +``` + +### Landing Page Checklist + +```markdown +- [ ] Keyword-optimized title +- [ ] Benefit-focused meta description +- [ ] Clear H1 value proposition +- [ ] Supporting H2 sections +- [ ] Trust signals (testimonials, logos) +- [ ] Single clear CTA +- [ ] Fast page load speed +- [ ] Mobile-optimized layout +``` diff --git a/.cursor/skills/on-page-seo-auditor/references/audit-templates.md b/.cursor/skills/on-page-seo-auditor/references/audit-templates.md new file mode 100644 index 0000000000..660944145d --- /dev/null +++ b/.cursor/skills/on-page-seo-auditor/references/audit-templates.md @@ -0,0 +1,315 @@ +# On-Page SEO Auditor — Output Templates + +Detailed output templates for on-page-seo-auditor steps 5-11. Referenced from [SKILL.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/SKILL.md). + +--- + +## Step 5: Audit Content Quality + +```markdown +## Content Quality Analysis + +**Word Count**: [X] words +**Reading Level**: [Grade level] +**Estimated Read Time**: [X] minutes + +| Criterion | Status | Notes | +|-----------|--------|-------| +| Sufficient length | ✅/⚠️/❌ | [comparison to ranking content] | +| Comprehensive coverage | ✅/⚠️/❌ | [notes] | +| Unique value/insights | ✅/⚠️/❌ | [notes] | +| Up-to-date information | ✅/⚠️/❌ | [notes] | +| Proper formatting | ✅/⚠️/❌ | [notes] | +| Readability | ✅/⚠️/❌ | [notes] | +| E-E-A-T signals | ✅/⚠️/❌ | [notes] | + +**Content Elements Present**: +- [ ] Introduction with keyword +- [ ] Clear sections/structure +- [ ] Bullet points/lists +- [ ] Tables where appropriate +- [ ] Images/visuals +- [ ] Examples/case studies +- [ ] Statistics with sources +- [ ] Expert quotes +- [ ] FAQ section +- [ ] Conclusion with CTA + +**Content Score**: [X]/10 + +**Gaps Identified**: +- [Missing topic/section 1] +- [Missing topic/section 2] + +**Recommendations**: +1. [Specific improvement] +2. [Specific improvement] +``` + +--- + +## Step 6: Audit Keyword Usage + +```markdown +## Keyword Optimization Analysis + +**Primary Keyword**: "[keyword]" +**Keyword Density**: [X]% + +### Keyword Placement + +| Location | Present | Notes | +|----------|---------|-------| +| Title tag | ✅/❌ | Position: [X] | +| Meta description | ✅/❌ | [notes] | +| H1 | ✅/❌ | [notes] | +| First 100 words | ✅/❌ | Word position: [X] | +| H2 headings | ✅/❌ | In [X]/[Y] H2s | +| Body content | ✅/❌ | [X] occurrences | +| URL slug | ✅/❌ | [notes] | +| Image alt text | ✅/❌ | In [X]/[Y] images | +| Conclusion | ✅/❌ | [notes] | + +### Secondary Keywords + +| Keyword | Occurrences | Status | +|---------|-------------|--------| +| [keyword 1] | [X] | ✅/⚠️/❌ | +| [keyword 2] | [X] | ✅/⚠️/❌ | + +### LSI/Related Terms + +**Present**: [list of related terms found] +**Missing**: [important related terms not found] + +**Keyword Score**: [X]/10 + +**Issues**: +- [Issue 1] + +**Recommendations**: +- [Suggestion 1] +``` + +--- + +## Step 7: Audit Internal Links + +```markdown +## Internal Linking Analysis + +**Total Internal Links**: [X] +**Unique Internal Links**: [X] + +| Criterion | Status | Notes | +|-----------|--------|-------| +| Number of internal links | ✅/⚠️/❌ | [X] (recommend 3-5+) | +| Relevant anchor text | ✅/⚠️/❌ | [notes] | +| Links to related content | ✅/⚠️/❌ | [notes] | +| Links to important pages | ✅/⚠️/❌ | [notes] | +| No broken links | ✅/⚠️/❌ | [X] broken found | +| Natural placement | ✅/⚠️/❌ | [notes] | + +**Current Internal Links**: +1. "[Anchor text]" → [URL] +2. "[Anchor text]" → [URL] +3. "[Anchor text]" → [URL] + +**Internal Linking Score**: [X]/10 + +**Recommended Additional Links**: +1. Add link to "[Related page]" with anchor "[suggested anchor]" +2. Add link to "[Related page]" with anchor "[suggested anchor]" + +**Anchor Text Improvements**: +- Change "[current anchor]" to "[improved anchor]" +``` + +--- + +## Step 8: Audit Images + +```markdown +## Image Optimization Analysis + +**Total Images**: [X] + +### Image Audit Table + +| Image | Alt Text | File Name | Size | Status | +|-------|----------|-----------|------|--------| +| [img1] | [alt or "missing"] | [filename] | [KB] | ✅/⚠️/❌ | +| [img2] | [alt or "missing"] | [filename] | [KB] | ✅/⚠️/❌ | + +| Criterion | Status | Notes | +|-----------|--------|-------| +| All images have alt text | ✅/⚠️/❌ | [X]/[Y] have alt | +| Alt text includes keywords | ✅/⚠️/❌ | [notes] | +| Descriptive file names | ✅/⚠️/❌ | [notes] | +| Appropriate file sizes | ✅/⚠️/❌ | [notes] | +| Modern formats (WebP) | ✅/⚠️/❌ | [notes] | +| Lazy loading enabled | ✅/⚠️/❌ | [notes] | + +**Image Score**: [X]/10 + +**Recommendations**: +1. Add alt text to image [X]: "[suggested alt text]" +2. Compress image [Y]: Currently [X]KB, should be under [Y]KB +3. Rename [filename] to [better-filename] +``` + +--- + +## Step 9: Audit Technical On-Page Elements + +```markdown +## Technical On-Page Analysis + +| Element | Current Value | Status | Recommendation | +|---------|---------------|--------|----------------| +| URL | [URL] | ✅/⚠️/❌ | [notes] | +| URL length | [X] chars | ✅/⚠️/❌ | [notes] | +| URL keywords | [present/absent] | ✅/⚠️/❌ | [notes] | +| Canonical tag | [URL or "missing"] | ✅/⚠️/❌ | [notes] | +| Mobile-friendly | [yes/no] | ✅/⚠️/❌ | [notes] | +| Page speed | [X]s | ✅/⚠️/❌ | [notes] | +| HTTPS | [yes/no] | ✅/⚠️/❌ | [notes] | +| Schema markup | [types or "none"] | ✅/⚠️/❌ | [notes] | + +**Technical Score**: [X]/10 +``` + +--- + +## Step 10: CORE-EEAT Content Quality Quick Scan + +Run a quick scan of on-page-relevant CORE-EEAT items. Reference: [CORE-EEAT Benchmark](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/core-eeat-benchmark.md) + +```markdown +## CORE-EEAT Quick Scan + +Content-relevant items from the 80-item benchmark: + +| ID | Check Item | Status | Notes | +|----|-----------|--------|-------| +| C01 | Intent Alignment | ✅/⚠️/❌ | Title promise = content delivery | +| C02 | Direct Answer | ✅/⚠️/❌ | Core answer in first 150 words | +| C09 | FAQ Coverage | ✅/⚠️/❌ | Structured FAQ present | +| C10 | Semantic Closure | ✅/⚠️/❌ | Conclusion answers opening | +| O01 | Heading Hierarchy | ✅/⚠️/❌ | H1→H2→H3, no skipping | +| O02 | Summary Box | ✅/⚠️/❌ | TL;DR or Key Takeaways | +| O03 | Data Tables | ✅/⚠️/❌ | Comparisons in tables | +| O05 | Schema Markup | ✅/⚠️/❌ | Appropriate JSON-LD | +| O06 | Section Chunking | ✅/⚠️/❌ | Single topic per section | +| R01 | Data Precision | ✅/⚠️/❌ | ≥5 precise numbers | +| R02 | Citation Density | ✅/⚠️/❌ | ≥1 per 500 words | +| R06 | Timestamp | ✅/⚠️/❌ | Updated <1 year | +| R08 | Internal Link Graph | ✅/⚠️/❌ | Descriptive anchors | +| R10 | Content Consistency | ✅/⚠️/❌ | No contradictions | +| Exp01 | First-Person Narrative | ✅/⚠️/❌ | "I tested" or "We found" | +| Ept01 | Author Identity | ✅/⚠️/❌ | Byline + bio present | +| T04 | Disclosure Statements | ✅/⚠️/❌ | Affiliate links disclosed | + +**CORE-EEAT Quick Score**: [X]/17 items passing + +> For a complete 80-item audit with weighted scoring, use `content-quality-auditor`. +``` + +--- + +## Step 11: Generate Audit Summary + +```markdown +# On-Page SEO Audit Report + +**Page**: [URL] +**Target Keyword**: [keyword] +**Audit Date**: [date] + +## Overall Score: [X]/100 + +``` +Score Breakdown: +████████░░ Title Tag: 8/10 +██████░░░░ Meta Description: 6/10 +█████████░ Headers: 9/10 +███████░░░ Content: 7/10 +██████░░░░ Keywords: 6/10 +█████░░░░░ Internal Links: 5/10 +████░░░░░░ Images: 4/10 +████████░░ Technical: 8/10 +``` + +## Priority Issues + +### 🔴 Critical (Fix Immediately) +1. [Critical issue 1] +2. [Critical issue 2] + +### 🟡 Important (Fix Soon) +1. [Important issue 1] +2. [Important issue 2] + +### 🟢 Minor (Nice to Have) +1. [Minor issue 1] +2. [Minor issue 2] + +## Quick Wins + +These changes will have immediate impact: + +1. **[Change 1]**: [Why and how] +2. **[Change 2]**: [Why and how] +3. **[Change 3]**: [Why and how] + +## Detailed Recommendations + +### Title Tag +- **Current**: [current title] +- **Recommended**: [new title] +- **Impact**: [expected improvement] + +### Meta Description +- **Current**: [current description] +- **Recommended**: [new description] +- **Impact**: [expected improvement] + +### Content Improvements +1. [Specific content change with location] +2. [Specific content change with location] + +### Internal Linking +1. Add link: "[anchor]" → [destination] +2. Add link: "[anchor]" → [destination] + +### Image Optimization +1. [Image 1]: [change needed] +2. [Image 2]: [change needed] + +## Competitor Comparison + +| Element | Your Page | Top Competitor | Gap | +|---------|-----------|----------------|-----| +| Word count | [X] | [Y] | [+/-Z] | +| Internal links | [X] | [Y] | [+/-Z] | +| Images | [X] | [Y] | [+/-Z] | +| H2 headings | [X] | [Y] | [+/-Z] | + +## Action Checklist + +- [ ] Update title tag +- [ ] Rewrite meta description +- [ ] Add keyword to H1 +- [ ] Add [X] more internal links +- [ ] Add alt text to [X] images +- [ ] Add [X] more content sections +- [ ] Implement FAQ schema +- [ ] [Additional action items] + +## Expected Results + +After implementing these changes: +- Estimated ranking improvement: [X] positions +- Estimated CTR improvement: [X]% +- Estimated traffic increase: [X]% +``` diff --git a/.cursor/skills/on-page-seo-auditor/references/scoring-rubric.md b/.cursor/skills/on-page-seo-auditor/references/scoring-rubric.md new file mode 100644 index 0000000000..037f2a2106 --- /dev/null +++ b/.cursor/skills/on-page-seo-auditor/references/scoring-rubric.md @@ -0,0 +1,496 @@ +# On-Page SEO Scoring Rubric + +Detailed scoring criteria for each of the 8 audit sections. Use this rubric to ensure consistent, objective scoring across audits. + +## How to Use This Rubric + +1. Score each section independently using the criteria below +2. Apply the section weight to calculate the weighted score +3. Sum all weighted scores for the overall page score (out of 100) +4. Use calibration examples to verify your scoring is consistent + +## Section 1: Title Tag (Weight: 15%, Max: 15 points) + +### Scoring Criteria + +| Criterion | Points | Requirement | +|-----------|--------|-------------| +| Keyword presence | 3 | Primary keyword appears in title | +| Keyword position | 2 | Primary keyword in first half of title | +| Length optimization | 2 | Between 50-60 characters | +| Uniqueness | 2 | Title is unique across the site | +| Compelling copy | 2 | Includes benefit, modifier, or hook | +| Intent match | 2 | Title matches search intent accurately | +| Brand inclusion | 1 | Brand name present (at end) | +| No truncation risk | 1 | Displays fully in SERP without cutoff | + +### Calibration Examples + +**Score 15/15 (Excellent)**: +- Title: "Keyword Research: 7 Proven Methods to Find Low-Competition Keywords | Brand" +- 58 characters, keyword at front, benefit-driven, unique, brand at end + +**Score 11/15 (Good)**: +- Title: "The Complete Guide to Keyword Research for Beginners" +- 52 characters, keyword present but not at front, no brand, still compelling + +**Score 7/15 (Needs Work)**: +- Title: "Keyword Research" +- Too short (16 chars), no benefit, no brand, not compelling, generic + +**Score 3/15 (Poor)**: +- Title: "Blog Post #47 - Untitled" +- No keyword, no benefit, not descriptive, not unique + +**Score 0/15 (Missing)**: +- No title tag present, or title tag is empty + +## Section 2: Meta Description (Weight: 5%, Max: 5 points) + +### Scoring Criteria + +| Criterion | Points | Requirement | +|-----------|--------|-------------| +| Keyword inclusion | 1 | Primary keyword appears naturally | +| Length optimization | 1 | Between 150-160 characters | +| Call-to-action | 1 | Contains explicit or implicit CTA | +| Unique description | 1 | Not duplicated from other pages | +| Accurate summary | 1 | Accurately describes page content | + +### Calibration Examples + +**Score 5/5 (Excellent)**: +- Description: "Learn 7 proven keyword research methods that top SEOs use to find low-competition opportunities. Includes free templates, real examples, and step-by-step walkthroughs. Get started today." +- 155 chars, keyword present, CTA ("Get started"), accurate, unique + +**Score 3/5 (Needs Work)**: +- Description: "This page talks about keyword research and some tips you might find useful for SEO." +- 83 chars (too short), weak copy, no CTA, vague + +**Score 0/5 (Missing)**: +- No meta description set; search engine generates snippet automatically + +## Section 3: Header Structure (Weight: 10%, Max: 10 points) + +### Scoring Criteria + +| Criterion | Points | Requirement | +|-----------|--------|-------------| +| Single H1 present | 2 | Exactly one H1 on the page | +| H1 contains keyword | 2 | Primary keyword in H1 text | +| Logical hierarchy | 2 | No skipped levels (H1→H2→H3, not H1→H3) | +| H2s cover key subtopics | 2 | H2s address main topic facets | +| Descriptive headers | 1 | Headers describe section content clearly | +| Keyword variations in H2s | 1 | Secondary keywords or LSI terms in subheadings | + +### Calibration Examples + +**Score 10/10 (Excellent)**: +``` +H1: How to Do Keyword Research: A Step-by-Step Guide + H2: What Is Keyword Research and Why Does It Matter? + H2: 7 Keyword Research Methods That Work + H3: Method 1: Seed Keyword Brainstorming + H3: Method 2: Competitor Keyword Analysis + H3: Method 3: Google Autocomplete Mining + H2: Free Keyword Research Tools Compared + H2: How to Prioritize Keywords by Difficulty + H2: Keyword Research FAQ +``` +- Single H1 with keyword, logical hierarchy, descriptive H2s with variations + +**Score 6/10 (Needs Work)**: +``` +H1: Keyword Research +H2: Introduction +H2: Methods +H2: Tools +H2: Conclusion +``` +- Single H1 but generic, H2s are vague, no keyword variations + +**Score 2/10 (Poor)**: +``` +H1: Welcome to Our Blog +H1: Keyword Research Guide +H3: Some Tips +H2: More Information +``` +- Multiple H1s, skipped levels, generic, no keyword strategy + +## Section 4: Content Quality (Weight: 25%, Max: 25 points) + +### Scoring Criteria + +| Criterion | Points | Requirement | +|-----------|--------|-------------| +| Sufficient length | 4 | Meets minimum for query type (see benchmarks) | +| Comprehensive coverage | 4 | Covers all major subtopics that top-ranking pages cover | +| Unique value | 4 | Original insights, data, or perspective not found elsewhere | +| Up-to-date information | 3 | Statistics, dates, and references are current | +| Proper formatting | 3 | Uses lists, tables, bold, images to improve readability | +| Readability | 3 | Appropriate reading level for target audience | +| E-E-A-T signals | 4 | Author byline, credentials, first-person experience, cited sources | + +### Content Length Benchmarks (for "Sufficient length" criterion) + +| Query Type | Minimum for 4/4 | Minimum for 3/4 | Minimum for 2/4 | Below 1/4 | +|-----------|-----------------|-----------------|-----------------|-----------| +| Informational | 1,500+ words | 1,000-1,499 | 500-999 | <500 | +| Commercial | 1,200+ words | 800-1,199 | 400-799 | <400 | +| Transactional | 500+ words | 350-499 | 200-349 | <200 | +| Local | 400+ words | 250-399 | 150-249 | <150 | + +### Calibration Examples + +**Score 25/25 (Excellent)**: +- 2,400-word guide on keyword research +- Covers all subtopics competitors cover plus unique methods +- Contains original data from author's experiments +- All statistics from the last 12 months +- Well-formatted with tables, lists, images, code examples +- Written at appropriate level for target audience +- Author byline with SEO credentials, first-person "I tested" language + +**Score 16/25 (Good)**: +- 1,600-word guide, covers main subtopics +- Some unique insights but mostly curated information +- Most statistics current, a few outdated +- Good formatting but could use more visual elements +- Author byline present but limited credentials + +**Score 8/25 (Needs Work)**: +- 700-word article on an informational query (too thin) +- Missing several subtopics competitors cover +- No original data or insights +- Several outdated statistics +- Wall of text with minimal formatting +- No author byline or E-E-A-T signals + +## Section 5: Keyword Optimization (Weight: 15%, Max: 15 points) + +### Scoring Criteria + +| Criterion | Points | Requirement | +|-----------|--------|-------------| +| Keyword in title | 2 | Primary keyword in title tag | +| Keyword in H1 | 2 | Primary keyword in H1 | +| Keyword in first 100 words | 2 | Primary keyword appears early in content | +| Keyword density (0.5-2.5%) | 2 | Natural density, not stuffed, not too sparse | +| Secondary keywords present | 2 | 2-3 secondary/related keywords used | +| LSI/semantic terms | 2 | Related terms and synonyms present | +| Keyword in URL | 1 | Primary keyword in URL slug | +| Keyword in image alt text | 1 | At least one image alt contains keyword naturally | +| Keyword in meta description | 1 | Primary keyword in meta description | + +### Keyword Density Guidelines + +| Density | Score Impact | Assessment | +|---------|-------------|-----------| +| 0.5-1.0% | Full points | Natural, well-integrated | +| 1.0-2.0% | Full points | Acceptable, slightly keyword-focused | +| 2.0-2.5% | -1 point | Borderline, review for naturalness | +| 2.5-3.0% | -2 points | Over-optimized, needs reduction | +| >3.0% | 0 points for density | Keyword stuffing, immediate fix needed | +| <0.5% | -1 point | Under-optimized, add more natural usage | + +### Calibration Examples + +**Score 15/15 (Excellent)**: +- "keyword research" in title (position 1), H1, first sentence, URL slug, 1 image alt +- Density: 1.2% across 2,000 words (24 occurrences, well-distributed) +- Secondary keywords: "keyword tool", "search volume", "keyword difficulty" all present +- LSI terms: "SEO", "search terms", "Google", "organic traffic", "SERP" present + +**Score 9/15 (Needs Work)**: +- Keyword in title and H1, but not in first 100 words +- Density: 0.3% (too sparse for a 2,000-word article) +- Missing secondary keywords +- No LSI/semantic terms beyond the primary keyword + +## Section 6: Internal/External Links (Weight: 10%, Max: 10 points) + +### Scoring Criteria + +| Criterion | Points | Requirement | +|-----------|--------|-------------| +| Internal link count | 2 | 3-5+ contextual internal links (per 1,000 words) | +| Internal link relevance | 2 | Links point to topically related pages | +| Descriptive anchor text | 2 | Anchors describe destination, not "click here" | +| External link quality | 2 | Links to authoritative, relevant external sources | +| No broken links | 1 | All links return 200 status | +| Link placement | 1 | Links placed naturally within content flow | + +### Internal Link Count Guidelines + +| Content Length | Minimum Links | Ideal Range | Too Many | +|---------------|--------------|-------------|---------| +| <500 words | 2 | 2-4 | >8 | +| 500-1,000 words | 3 | 3-6 | >12 | +| 1,000-2,000 words | 4 | 5-10 | >20 | +| 2,000+ words | 5 | 8-15 | >25 | + +### Calibration Examples + +**Score 10/10 (Excellent)**: +- 8 internal links in a 2,000-word article +- All link to relevant related content +- Anchor text like "learn about keyword difficulty scoring" (descriptive) +- 3 external links to authoritative sources (Google documentation, industry studies) +- Zero broken links + +**Score 5/10 (Needs Work)**: +- 2 internal links in a 2,000-word article (too few) +- One link uses "click here" anchor text +- No external links to sources +- One broken link found + +## Section 7: Image Optimization (Weight: 10%, Max: 10 points) + +### Scoring Criteria + +| Criterion | Points | Requirement | +|-----------|--------|-------------| +| All images have alt text | 3 | Every image has descriptive alt attribute | +| Alt text includes keywords | 2 | At least 1 image alt naturally includes primary keyword | +| Descriptive file names | 1 | Files named descriptively (keyword-research-tool.webp, not IMG_4532.jpg) | +| Optimized file sizes | 2 | Images compressed appropriately (<200KB for photos, <50KB for graphics) | +| Modern formats | 1 | Uses WebP or AVIF where supported | +| Lazy loading | 1 | Below-fold images use loading="lazy" | + +### Image Size Guidelines + +| Image Type | Target Size | Format | Notes | +|-----------|------------|--------|-------| +| Hero/banner | <200KB | WebP | Resize to actual display dimensions | +| Content photos | <150KB | WebP | Compress at 80% quality | +| Screenshots | <100KB | WebP/PNG | Use PNG only if text clarity critical | +| Icons/graphics | <30KB | SVG/WebP | SVG preferred for vector graphics | +| Thumbnails | <50KB | WebP | Generate at actual thumbnail dimensions | + +### Calibration Examples + +**Score 10/10 (Excellent)**: +- 5 images, all with descriptive alt text +- Alt text: "screenshot of Ahrefs keyword research tool showing difficulty score" +- Files named: keyword-research-tool-ahrefs.webp +- All images <150KB, WebP format, lazy loading on below-fold images + +**Score 4/10 (Needs Work)**: +- 3 images, 1 missing alt text +- Alt text on others: "image1", "screenshot" (not descriptive) +- Files named: IMG_3421.jpg, photo.png +- One image is 1.2MB uncompressed JPEG + +## Section 8: Page-Level Technical (Weight: 10%, Max: 10 points) + +### Scoring Criteria + +| Criterion | Points | Requirement | +|-----------|--------|-------------| +| Clean URL structure | 2 | Short, descriptive, keyword-containing URL | +| Correct canonical tag | 2 | Self-referencing canonical or appropriate cross-domain canonical | +| Mobile-friendly | 2 | Passes mobile-friendly test, responsive layout | +| Page speed (LCP) | 2 | LCP ≤2.5s on mobile | +| HTTPS | 1 | Page served over HTTPS with valid certificate | +| Schema markup | 1 | Appropriate schema type implemented (Article, FAQ, HowTo, etc.) | + +### URL Quality Guidelines + +| Aspect | Good | Bad | +|--------|------|-----| +| Length | /blog/keyword-research-guide | /blog/2024/01/15/the-complete-ultimate-guide-to-keyword-research-for-beginners-and-experts | +| Keywords | /services/seo-audit | /services/page-id-4532 | +| Characters | lowercase, hyphens | UPPERCASE, underscores, special chars | +| Parameters | /products/shoes (clean) | /products?id=432&color=red&size=9 | + +### Calibration Examples + +**Score 10/10 (Excellent)**: +- URL: /blog/keyword-research-guide (clean, keyword-present) +- Self-referencing canonical tag present +- Fully responsive, passes mobile-friendly test +- LCP: 1.8s on mobile +- HTTPS with valid certificate +- Article + FAQ schema implemented + +**Score 5/10 (Needs Work)**: +- URL: /blog/?p=4532 (not descriptive) +- No canonical tag +- Mobile-friendly but some tap targets too small +- LCP: 3.2s (needs improvement) +- HTTPS present +- No schema markup + +## Overall Score Calculation + +### Formula + +``` +Overall Score = Sum of (Section Score / Section Max * Section Weight * 100) +``` + +### Example Calculation + +| Section | Raw Score | Max | Weight | Weighted Score | +|---------|-----------|-----|--------|---------------| +| Title Tag | 12 | 15 | 15% | 12.0 | +| Meta Description | 4 | 5 | 5% | 4.0 | +| Header Structure | 8 | 10 | 10% | 8.0 | +| Content Quality | 20 | 25 | 25% | 20.0 | +| Keyword Optimization | 11 | 15 | 15% | 11.0 | +| Internal/External Links | 7 | 10 | 10% | 7.0 | +| Image Optimization | 6 | 10 | 10% | 6.0 | +| Page-Level Technical | 8 | 10 | 10% | 8.0 | +| **Total** | | | **100%** | **76.0/100** | + +### Overall Score Interpretation + +| Score Range | Grade | Assessment | +|------------|-------|-----------| +| 90-100 | A+ | Exceptional — minor tweaks only | +| 80-89 | A | Strong — a few optimization opportunities | +| 70-79 | B | Good — several areas need attention | +| 60-69 | C | Average — significant improvements needed | +| 50-59 | D | Below average — major issues present | +| <50 | F | Poor — comprehensive overhaul required | + +## Calibration Guidance + +### Avoiding Common Scoring Errors + +1. **Halo effect**: A great title does not mean great content. Score each section independently. +2. **Recency bias**: Do not inflate scores for recently published content. Freshness is one factor among many. +3. **Tool dependency**: If you cannot verify a metric (e.g., page speed without tool access), note it as "unverified" rather than guessing. +4. **Competitor anchoring**: Score against the rubric criteria, not relative to competitors. Competitor comparison is a separate analysis step. +5. **Intent mismatch**: A page with perfect technical SEO but wrong intent alignment should still score low on Content Quality. + +### When to Adjust Weights + +The default weights suit most content pages. Consider adjusting for: + +| Page Type | Increase Weight | Decrease Weight | Reason | +|-----------|----------------|----------------|--------| +| E-commerce product | Image Optimization, Technical | Content Quality | Products need visuals and speed more than long-form | +| Long-form guide | Content Quality, Keywords | Image Optimization | Content depth matters most | +| Landing page | Technical, Title | Content Quality | Speed and CTR drive conversions | +| Local service page | Technical, Links | Keywords | NAP consistency and local signals matter more | + +Always document weight adjustments and the reasoning in the audit report. + +--- + +## Scoring Rubric + +### Section Weight Distribution + +| Audit Section | Weight | Max Score | Rationale | +|--------------|--------|-----------|-----------| +| Title Tag | 15% | 15 | Strongest single ranking signal | +| Meta Description | 5% | 5 | CTR impact, not direct ranking factor | +| Header Structure | 10% | 10 | Content organization, semantic signals | +| Content Quality | 25% | 25 | Strongest holistic ranking factor | +| Keyword Optimization | 15% | 15 | Relevance signals | +| Internal/External Links | 10% | 10 | Authority flow, context signals | +| Image Optimization | 10% | 10 | Accessibility + image search opportunity | +| Page-Level Technical | 10% | 10 | Core Web Vitals, mobile, security | + +### Scoring Scale per Factor + +| Score | Meaning | Action Required | +|-------|---------|-----------------| +| 10/10 | Excellent — follows all best practices | None | +| 7-9/10 | Good — minor improvements possible | Optional optimization | +| 4-6/10 | Needs work — notable issues | Fix within this week | +| 1-3/10 | Poor — significant problems | Fix immediately (Critical) | +| 0/10 | Missing or broken | Fix immediately (Blocking) | + +### Scoring Conversion Formula + +Each section is scored out of 10, then converted to the 100-point overall score using section weights: + +``` +Overall Score = Sum of (section_score x section_weight) x 10 +``` + +Where section weights are: Title 0.15, Meta 0.05, Headers 0.10, Content 0.25, Keywords 0.15, Links 0.10, Images 0.10, Technical 0.10. + +**Worked example:** + +| Section | Score /10 | Weight | Weighted | +|---------|-----------|--------|----------| +| Title Tag | 8 | 0.15 | 1.20 | +| Meta Description | 6 | 0.05 | 0.30 | +| Header Structure | 9 | 0.10 | 0.90 | +| Content Quality | 7 | 0.25 | 1.75 | +| Keyword Optimization | 8 | 0.15 | 1.20 | +| Internal/External Links | 5 | 0.10 | 0.50 | +| Image Optimization | 6 | 0.10 | 0.60 | +| Page-Level Technical | 7 | 0.10 | 0.70 | +| **Total** | | **1.00** | **7.15** | + +**Overall Score** = 7.15 x 10 = **71 / 100** + +## Common Issue Resolution Playbook + +### Title Tag Issues + +| Issue | Impact | Quick Fix Template | +|-------|--------|-------------------| +| Missing title | Critical | Add: "[Primary Keyword]: [Benefit] | [Brand]" | +| Too long (>60 chars) | Medium | Shorten: move brand to end, remove filler words | +| Too short (<30 chars) | Medium | Expand: add modifier, benefit, or year | +| Missing keyword | High | Rewrite to include primary keyword in first half | +| Duplicate title | High | Make each page title unique; add page-specific modifier | + +### Meta Description Issues + +| Issue | Impact | Quick Fix Template | +|-------|--------|-------------------| +| Missing description | Medium | Write: "[What this page covers]. [Key benefit]. [CTA]." (150-160 chars) | +| Too long (>160 chars) | Low | Trim from end; ensure core message fits in 150 chars | +| Missing keyword | Low | Naturally incorporate primary keyword | +| No CTA | Low | Add: "Learn more", "Discover", "Find out", "Get started" | +| Duplicated across pages | Medium | Write unique description for each page | + +### Header Issues + +| Issue | Impact | Quick Fix | +|-------|--------|-----------| +| Missing H1 | Critical | Add one H1 per page containing primary keyword | +| Multiple H1s | High | Keep one H1, convert others to H2 | +| Skipped heading levels | Medium | Use sequential hierarchy: H1→H2→H3 | +| Headers not descriptive | Medium | Rewrite to include keyword variations | +| No H2s (single long block) | Medium | Break content into sections with descriptive H2s every 200-300 words | + +### Content Issues + +| Issue | Impact | Quick Fix | +|-------|--------|-----------| +| Thin content (<300 words) | Critical | Expand with subtopics, FAQ, examples | +| Keyword stuffing (>3%) | High | Reduce usage, use synonyms and related terms | +| No structured data | Medium | Add relevant schema (FAQ, HowTo, Article) | +| Missing internal links | Medium | Add 3-5 contextual internal links | +| No images | Low | Add 2-3 relevant images with alt text | + +## Industry Benchmark Data + +### Content Length Benchmarks by Query Type + +| Query Type | Top 10 Average Word Count | Recommended Minimum | +|-----------|--------------------------|-------------------| +| Informational (guides) | 2,200 words | 1,500 words | +| Commercial (reviews) | 1,800 words | 1,200 words | +| Transactional (product) | 800 words | 500 words | +| Local (service pages) | 600 words | 400 words | +| Definition queries | 1,200 words | 800 words | + +### Page Speed Benchmarks + +| Metric | Good | Needs Improvement | Poor | +|--------|------|-------------------|------| +| LCP | ≤2.5s | 2.5-4.0s | >4.0s | +| FID/INP | ≤100ms/200ms | 100-300ms | >300ms | +| CLS | ≤0.1 | 0.1-0.25 | >0.25 | +| TTFB | ≤800ms | 800-1800ms | >1800ms | + diff --git a/.cursor/skills/performance-reporter/SKILL.md b/.cursor/skills/performance-reporter/SKILL.md new file mode 100644 index 0000000000..27ae07d35e --- /dev/null +++ b/.cursor/skills/performance-reporter/SKILL.md @@ -0,0 +1,263 @@ +--- +name: performance-reporter +description: 'Generate SEO/GEO dashboards: rankings, traffic, backlinks, AI visibility for stakeholders. SEO报告/绩效仪表盘' +version: "6.0.0" +license: Apache-2.0 +compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations." +homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills" +when_to_use: "Use when generating SEO performance reports, traffic summaries, ranking reports, or stakeholder-facing dashboards." +argument-hint: " [date range]" +metadata: + author: aaron-he-zhu + version: "6.0.0" + geo-relevance: "medium" + tags: + - seo + - geo + - seo-reporting + - performance-report + - kpi-dashboard + - traffic-report + - monthly-report + - stakeholder-report + - SEO报告 + - SEOレポート + - SEO리포트 + - informe-seo + triggers: + # EN-formal + - "generate SEO report" + - "performance report" + - "traffic report" + - "SEO dashboard" + - "SEO analytics" + - "monthly report" + # EN-casual + - "report to stakeholders" + - "monthly SEO report" + - "show me my SEO results" + - "present SEO results to my boss" + - "report to my boss" + - "monthly SEO summary" + # EN-question + - "how are my SEO metrics" + - "how is my SEO performing" + # ZH-pro + - "SEO报告" + - "绩效仪表盘" + - "流量报告" + - "数据看板" + # ZH-casual + - "出SEO报告" + - "汇报给老板" + - "看看数据" + - "月报" + - "出月报" + - "周报" + # JA + - "SEOレポート" + - "パフォーマンスレポート" + # KO + - "SEO 리포트" + - "성과 보고서" + # ES + - "informe SEO" + - "reporte de rendimiento" + # PT + - "relatório SEO" + # Misspellings + - "SEO repoort" +--- + +# Performance Reporter + + +> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills) +> **System Mode**: This monitoring skill follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md). + + +This skill creates comprehensive SEO and GEO performance reports that combine multiple metrics into actionable insights. It produces executive summaries, detailed analyses, and visual data presentations for stakeholder communication. + +**System role**: Monitoring layer skill. It turns performance changes into deltas, alerts, and next actions. + +## When This Must Trigger + +Use this when the conversation involves any of these situations — even if the user does not use SEO terminology: + +Use this whenever the task needs time-aware change detection, escalation, or stakeholder-ready visibility. + +- Monthly/quarterly SEO reporting +- Executive stakeholder updates +- Client reporting for agencies +- Tracking campaign performance +- Combining multiple SEO metrics +- Creating GEO visibility reports +- Documenting ROI from SEO efforts + +## What This Skill Does + +1. **Data Aggregation**: Combines multiple SEO data sources +2. **Trend Analysis**: Identifies patterns across metrics +3. **Executive Summaries**: Creates high-level overviews +4. **Visual Reports**: Presents data in clear formats +5. **Benchmark Comparison**: Tracks against goals and competitors +6. **Content Quality Tracking**: Integrates CORE-EEAT scores across audited pages +7. **ROI Calculation**: Measures SEO investment returns +8. **Recommendations**: Suggests actions based on data + +## Quick Start + +Start with one of these prompts. Finish with a short handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md). + +### Generate Performance Report + +``` +Create an SEO performance report for [domain] for [time period] +``` + +### Executive Summary + +``` +Generate an executive summary of SEO performance for [month/quarter] +``` + +### Specific Report Types + +``` +Create a GEO visibility report for [domain] +``` + +``` +Generate a content performance report +``` + +## Skill Contract + +**Expected output**: a delta summary, alert/report output, and a short handoff summary ready for `memory/monitoring/`. + +- **Reads**: current metrics, previous baselines, alert thresholds, and reporting context from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available. +- **Writes**: a user-facing monitoring deliverable plus a reusable summary that can be stored under `memory/monitoring/`. +- **Promotes**: significant changes, confirmed anomalies, and follow-up actions to `memory/open-loops.md` and `memory/decisions.md`. +- **Next handoff**: use the `Next Best Skill` below when a change needs action. + +## Data Sources + +> **Note:** All integrations are optional. This skill works without any API keys — users provide data manually when no tools are connected. + +> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md) for tool category placeholders. + +**With ~~analytics + ~~search console + ~~SEO tool + ~~AI monitor connected:** +Automatically aggregate traffic metrics from ~~analytics, search performance data from ~~search console, ranking and backlink data from ~~SEO tool, and GEO visibility metrics from ~~AI monitor. Creates comprehensive multi-source reports with historical trends. + +**With manual data only:** +Ask the user to provide: +1. Analytics screenshots or traffic data export (sessions, users, conversions) +2. Search Console data (impressions, clicks, average position) +3. Keyword ranking data for the reporting period +4. Backlink metrics (referring domains, new/lost links) +5. Key performance indicators and goals for comparison +6. AI citation data if tracking GEO metrics + +Proceed with the full analysis using provided data. Note in the output which metrics are from automated collection vs. user-provided data. + +## Instructions + +When a user requests a performance report: + +1. **Define Report Parameters** -- Domain, report period, comparison period, report type (Monthly/Quarterly/Annual), audience (Executive/Technical/Client), focus areas. + +2. **Create Executive Summary** -- Overall performance rating, key wins/watch areas/action required, metrics at a glance table (traffic, rankings, conversions, DA, AI citations), SEO ROI calculation. + +3. **Report Organic Traffic Performance** -- Traffic overview (sessions, users, pageviews, bounce rate), traffic trend visualization, traffic by source/device, top performing pages. + +4. **Report Keyword Rankings** -- Rankings overview by position range, distribution change visualization, top improvements and declines, SERP feature performance. + +5. **Report GEO/AI Performance** -- AI citation overview, citations by topic, GEO wins, optimization opportunities. + +6. **Report Domain Authority (CITE Score)** -- If a CITE audit has been run, include CITE dimension scores (C/I/T/E) with period-over-period trends and veto status. If no audit exists, note as "Not yet evaluated." + +7. **Content Quality (CORE-EEAT Score)** -- If content-quality-auditor has been run, include average scores across all 8 CORE-EEAT dimensions with trends. If no audit exists, note as "Not yet evaluated." + +8. **Report Backlink Performance** -- Link profile summary, weekly link acquisition, notable new links, competitive position. + +9. **Report Content Performance** -- Publishing summary, top performing content, content needing attention, content ROI. + +10. **Generate Recommendations** -- Immediate/short-term/long-term actions with priority, expected impact, and owner. Goals for next period. + +11. **Compile Full Report** -- Combine all sections with table of contents, appendix (data sources, methodology, glossary). + + > **Reference**: See [references/report-output-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/performance-reporter/references/report-output-templates.md) for complete output templates for all 11 report sections. + +## Validation Checkpoints + +### Input Validation +- [ ] Reporting period clearly defined with comparison period +- [ ] All required data sources available or alternatives noted +- [ ] Target audience identified (executive/technical/client) +- [ ] Performance goals and KPIs established for benchmarking + +### Output Validation +- [ ] Every metric cites its data source and collection date +- [ ] Trends include period-over-period comparisons +- [ ] Recommendations are specific, prioritized, and actionable +- [ ] Source of each data point clearly stated (~~analytics data, ~~search console data, ~~SEO tool data, user-provided, or estimated) + +## Example + +**User**: "Create a monthly SEO report for cloudhosting.com for January 2025" + +**Output** (abbreviated -- full report uses templates from all 11 steps): + +```markdown +# CloudHosting SEO & GEO Performance Report — January 2025 + +## Executive Summary — Overall Performance: Good + +| Metric | Jan 2025 | Dec 2024 | Change | Target | Status | +|--------|----------|----------|--------|--------|--------| +| Organic Traffic | 52,100 | 45,200 | +15.3% | 50,000 | On track | +| Keywords Top 10 | 87 | 79 | +8 | 90 | Watch | +| Organic Conversions | 684 | 612 | +11.8% | 700 | Watch | +| Domain Rating | 54 | 53 | +1 | 55 | Watch | +| AI Citations | 18 | 12 | +50.0% | 20 | Watch | + +**SEO ROI**: $8,200 invested / $41,040 organic revenue = 400% + +**Immediate**: Fix 37 crawl errors on /pricing/ pages +**This Month**: Optimize mobile LCP; publish 3 AI Overview comparison pages +**This Quarter**: Build Wikidata entry for CloudHost Inc. +``` + +## Tips for Success + +1. **Lead with insights** - Start with what matters, not raw data +2. **Visualize data** - Charts and graphs improve comprehension +3. **Compare periods** - Context makes data meaningful +4. **Include actions** - Every report should drive decisions +5. **Customize for audience** - Executives need different info than technical teams +6. **Track GEO metrics** - AI visibility is increasingly important + + +### Save Results + +After delivering monitoring data or reports to the user, ask: + +> "Save these results for future sessions?" + +If yes, write a dated summary to `memory/monitoring/YYYY-MM-DD-.md` containing: +- One-line headline finding or status change +- Top 3-5 actionable items +- Open loops or anomalies requiring follow-up +- Source data references + +If any findings should influence ongoing strategy, recommend promoting key conclusions to `memory/hot-cache.md`. + +## Reference Materials + +- [Report Output Templates](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/performance-reporter/references/report-output-templates.md) — Complete output templates for all 11 report sections +- [KPI Definitions](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/performance-reporter/references/kpi-definitions.md) — SEO/GEO metric definitions with benchmarks, good ranges, warning thresholds, trend analysis, and attribution guidance +- [Report Templates by Audience](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/performance-reporter/references/report-templates.md) — Copy-ready templates for executive, marketing, technical, and client audiences + +## Next Best Skill + +- **Primary**: [alert-manager](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/alert-manager/SKILL.md) — turn reporting insights into ongoing monitoring rules. diff --git a/.cursor/skills/performance-reporter/references/kpi-definitions.md b/.cursor/skills/performance-reporter/references/kpi-definitions.md new file mode 100644 index 0000000000..74632b0361 --- /dev/null +++ b/.cursor/skills/performance-reporter/references/kpi-definitions.md @@ -0,0 +1,524 @@ +# SEO/GEO KPI Definitions + +Complete glossary of SEO and GEO key performance indicators with calculation formulas, data sources, benchmark ranges by industry, and interpretation guidance. + +--- + +## 1. Organic Search KPIs + +### Organic Sessions + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Number of visits to your site originating from organic (unpaid) search engine results | +| **Formula** | Count of sessions where medium = "organic" | +| **Data Source** | ~~analytics (Google Analytics, Adobe Analytics, or equivalent) | +| **Good Range** | Growing month-over-month; 3-10% MoM growth is healthy | +| **Warning** | Decline >10% MoM without known seasonal cause | +| **Segmentation** | Always separate brand vs. non-brand organic sessions | + +**Interpretation:** +- Growing organic sessions with stable conversion rate = SEO strategy is working. +- Growing sessions but declining conversions = traffic quality issue; check keyword targeting. +- Flat sessions despite new content = content not ranking or cannibalizing existing pages. + +--- + +### Organic Click-Through Rate (CTR) + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Percentage of search impressions that result in a click to your site | +| **Formula** | (Organic Clicks / Organic Impressions) x 100 | +| **Data Source** | ~~search console | +| **Good Range** | >3% overall; varies significantly by position and query type | +| **Warning** | <1.5% overall or declining trend | +| **Segmentation** | By query type (brand vs. non-brand), by page, by position range | + +**Benchmarks by Position:** + +| Position | Expected CTR Range | +|----------|-------------------| +| #1 | 25-35% | +| #2 | 12-18% | +| #3 | 8-13% | +| #4-5 | 4-8% | +| #6-10 | 2-5% | +| #11-20 | 0.5-2% | + +**Interpretation:** +- High impressions but low CTR = title tags and meta descriptions need optimization. +- CTR declining for stable positions = SERP features (AI Overview, PAA) stealing clicks. +- CTR higher than position benchmarks = strong brand recognition or compelling snippets. + +--- + +### Average Position + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Mean ranking position across all tracked keywords or queries | +| **Formula** | Sum of all positions / count of keywords | +| **Data Source** | ~~search console (query-level), ~~SEO tool (keyword-level) | +| **Good Range** | <20 for tracked keywords; improving trend | +| **Warning** | >30 or rising (worsening) trend | +| **Segmentation** | By keyword group, by page, by intent type | + +**Interpretation:** +- Average position is a directional indicator, not an absolute measure. A few very low-ranking keywords can drag the average down significantly. +- Always pair with keyword distribution (how many keywords in top 10, top 20, etc.) for a complete picture. + +--- + +### Keyword Visibility Score + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Weighted score combining keyword positions and search volumes into a single index | +| **Formula** | Sum of (estimated CTR at position x monthly search volume) for each keyword | +| **Data Source** | ~~SEO tool | +| **Good Range** | Growing over time; absolute value depends on niche | +| **Warning** | Declining trend for 3+ consecutive weeks | +| **Segmentation** | By topic cluster, by competitor | + +**Interpretation:** +- Visibility score accounts for both ranking position and keyword importance (volume). +- A single high-volume keyword moving from #1 to #5 can cause a larger visibility drop than 20 low-volume keywords dropping off page 1. + +--- + +### Pages Indexed + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Number of your pages included in Google's search index | +| **Formula** | Count of valid indexed pages in Index Coverage report | +| **Data Source** | ~~search console (Index Coverage / Pages report) | +| **Good Range** | Indexed count close to total intended indexable pages; growing with new content | +| **Warning** | Indexed count dropping without intentional removal; large gap between submitted and indexed | +| **Segmentation** | By sitemap, by content type, by subdirectory | + +**Interpretation:** +- Indexed < submitted = quality or technical issues preventing indexing. +- Sudden drop in indexed pages = possible noindex tag, robots.txt change, or manual action. +- Indexed > intended = duplicate content, parameter URLs, or faceted navigation issues. + +--- + +### Organic Conversion Rate + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Percentage of organic sessions that complete a defined conversion goal | +| **Formula** | (Organic Conversions / Organic Sessions) x 100 | +| **Data Source** | ~~analytics | +| **Good Range** | >2% for lead generation; >1% for e-commerce (varies by industry) | +| **Warning** | <0.5% or declining while traffic grows | +| **Segmentation** | By landing page, by keyword intent, by device | + +**Industry Benchmarks:** + +| Industry | Typical Organic CVR | +|----------|-------------------| +| SaaS / Software | 2-5% | +| E-commerce | 1-3% | +| Finance | 3-6% | +| Healthcare | 2-4% | +| B2B Services | 2-5% | +| Media / Publishing | 0.5-2% (ad-supported) | +| Education | 2-5% | + +--- + +### Non-Brand Organic Traffic Share + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Percentage of organic traffic coming from non-branded search queries | +| **Formula** | (Organic sessions - brand query sessions) / Organic sessions x 100 | +| **Data Source** | ~~search console + ~~analytics | +| **Good Range** | >50% of total organic; growing | +| **Warning** | <30% (over-reliance on brand awareness, not SEO) | +| **Segmentation** | Trend over time | + +**Interpretation:** +- High non-brand share = SEO is driving new audience discovery. +- Low non-brand share = organic traffic is mostly people who already know your brand; SEO is underperforming for acquisition. + +--- + +## 2. GEO / AI Visibility KPIs + +### AI Citation Rate + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Percentage of monitored queries where your content is cited in AI-generated answers | +| **Formula** | (Queries where you are cited / Total monitored queries with AI answers) x 100 | +| **Data Source** | ~~AI monitor | +| **Good Range** | >20% of monitored queries | +| **Warning** | <5% or declining trend | +| **Segmentation** | By topic cluster, by content type | + +--- + +### AI Citation Position + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Your average position among cited sources in AI-generated responses | +| **Formula** | Sum of citation positions / count of citations | +| **Data Source** | ~~AI monitor | +| **Good Range** | Top 3 sources on average | +| **Warning** | Not cited or consistently cited in position 5+ | +| **Segmentation** | By query, by topic | + +--- + +### AI Answer Coverage + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Percentage of your target topics that appear in AI-generated answers | +| **Formula** | (Topics with AI answers / Total target topics) x 100 | +| **Data Source** | ~~AI monitor | +| **Good Range** | Growing over time as AI answers expand | +| **Warning** | Declining coverage may indicate content quality issues | +| **Segmentation** | By topic cluster | + +--- + +### Brand Mention in AI Responses + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Number of times your brand is mentioned in AI-generated responses across monitored queries | +| **Formula** | Count of AI responses containing your brand name | +| **Data Source** | ~~AI monitor | +| **Good Range** | Growing; present in responses for your key topics | +| **Warning** | Zero mentions for topics where you are an authority | +| **Segmentation** | By query category | + +--- + +## 3. Domain Authority KPIs + +### Domain Rating / Domain Authority + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Proprietary metric estimating the overall strength of a domain's backlink profile (0-100 scale) | +| **Formula** | Varies by tool (logarithmic scale based on backlink quantity and quality) | +| **Data Source** | ~~SEO tool (Ahrefs DR, Moz DA, or equivalent) | +| **Good Range** | Growing; competitive with top-ranking sites in your niche | +| **Warning** | Declining or significantly below competitors | +| **Segmentation** | Compare against competitors | + +**Benchmarks by Site Stage:** + +| Site Stage | Typical DR/DA | +|-----------|--------------| +| Brand new (0-6 months) | 0-15 | +| Early growth (6-18 months) | 15-30 | +| Established (18-36 months) | 25-50 | +| Mature (3+ years) | 40-70+ | +| Industry leader | 70-90+ | + +--- + +### Referring Domains + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Count of unique domains that link to your site | +| **Formula** | Count of distinct root domains with at least one dofollow or nofollow link | +| **Data Source** | ~~link database | +| **Good Range** | Growing MoM; higher than primary competitors | +| **Warning** | Net loss of referring domains for 2+ consecutive months | +| **Segmentation** | By authority tier (DR 0-20, 20-40, 40-60, 60+) | + +--- + +### Backlink Growth Rate + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Net new backlinks acquired per month | +| **Formula** | New backlinks gained - backlinks lost in the period | +| **Data Source** | ~~link database | +| **Good Range** | Positive and steady; proportional to content output | +| **Warning** | Negative for 2+ months; sudden spikes (may indicate spam) | +| **Segmentation** | By link quality tier | + +--- + +### Toxic Link Ratio + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Percentage of your backlinks classified as toxic or spammy | +| **Formula** | (Toxic backlinks / Total backlinks) x 100 | +| **Data Source** | ~~link database (toxic score/spam score) | +| **Good Range** | <5% | +| **Warning** | 5-10% (monitor and clean up) | +| **Critical** | >10% (immediate disavow action needed) | +| **Segmentation** | By toxic type (PBN, spam, irrelevant) | + +--- + +## 4. Technical SEO KPIs + +### Core Web Vitals + +| Metric | Definition | Good | Needs Improvement | Poor | +|--------|-----------|------|-------------------|------| +| **LCP** (Largest Contentful Paint) | Time to render largest content element | <=2.5s | 2.5-4.0s | >4.0s | +| **CLS** (Cumulative Layout Shift) | Visual stability during page load | <=0.1 | 0.1-0.25 | >0.25 | +| **INP** (Interaction to Next Paint) | Responsiveness to user interactions | <=200ms | 200-500ms | >500ms | + +**Data Source:** ~~search console (Core Web Vitals report), Chrome UX Report, PageSpeed Insights + +--- + +### Crawl Budget Utilization + +| Attribute | Detail | +|-----------|--------| +| **Definition** | How efficiently search engine crawlers are spending their crawl budget on your site | +| **Formula** | (Useful pages crawled / Total pages crawled) x 100 | +| **Data Source** | ~~search console (Crawl Stats), server logs | +| **Good Range** | >80% of crawled pages are indexable, valuable pages | +| **Warning** | High crawl of non-indexable or low-value pages | +| **Segmentation** | By content type, by HTTP status code | + +--- + +### Index Coverage Rate + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Percentage of submitted pages that are successfully indexed | +| **Formula** | (Indexed pages / Submitted pages) x 100 | +| **Data Source** | ~~search console | +| **Good Range** | >90% for sites with curated sitemaps | +| **Warning** | <80% or declining | +| **Segmentation** | By sitemap, by exclusion reason | + +--- + +## 5. Content Performance KPIs + +### Content Efficiency Score + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Ratio of content investment to organic traffic generated | +| **Formula** | Organic sessions per content piece / cost per content piece | +| **Data Source** | ~~analytics + internal cost tracking | +| **Good Range** | Improving over time; varies by content type | +| **Warning** | Declining efficiency despite continued investment | +| **Segmentation** | By content type, by topic, by author | + +--- + +### Content Decay Rate + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Percentage of existing content losing organic traffic over a defined period | +| **Formula** | (Pages with >20% traffic decline over 6 months / Total pages with traffic) x 100 | +| **Data Source** | ~~analytics | +| **Good Range** | <20% of pages decaying per 6-month period | +| **Warning** | >30% of pages decaying | +| **Segmentation** | By content age, by topic, by content type | + +--- + +### Organic Revenue Per Session + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Average revenue generated per organic search session | +| **Formula** | Total organic revenue / Total organic sessions | +| **Data Source** | ~~analytics (e-commerce tracking or goal values) | +| **Good Range** | Stable or growing; varies hugely by industry | +| **Warning** | Declining while traffic grows (traffic quality deteriorating) | +| **Segmentation** | By landing page, by keyword intent, by device | + +--- + +## 6. Competitive KPIs + +### Share of Voice (SOV) + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Your visibility as a percentage of total visibility across tracked keywords | +| **Formula** | (Your visibility score / Sum of all tracked competitors' visibility scores) x 100 | +| **Data Source** | ~~SEO tool | +| **Good Range** | Growing; leading in your core topic areas | +| **Warning** | Declining for 3+ consecutive months | +| **Segmentation** | By topic cluster, by competitor | + +--- + +### Competitive Keyword Overlap + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Percentage of your tracked keywords where a specific competitor also ranks in the top 20 | +| **Formula** | (Keywords where both rank in top 20 / Your total tracked keywords) x 100 | +| **Data Source** | ~~SEO tool | +| **Good Range** | Context-dependent; high overlap for direct competitors is expected | +| **Warning** | New competitor appearing with high overlap indicates emerging threat | +| **Segmentation** | By competitor, by keyword group | + +--- + +## 7. ROI and Business Impact KPIs + +### SEO ROI + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Return on investment from SEO activities | +| **Formula** | ((Organic Revenue - SEO Investment) / SEO Investment) x 100 | +| **Data Source** | ~~analytics + internal cost tracking | +| **Good Range** | >200% annually (SEO compounds over time) | +| **Warning** | <100% after 12+ months of investment | +| **Segmentation** | By content type, by campaign | + +**Note:** SEO ROI should be measured over 12+ month horizons. Short-term ROI calculations are misleading because SEO benefits compound over time. + +--- + +### Organic Traffic Value + +| Attribute | Detail | +|-----------|--------| +| **Definition** | Estimated cost to acquire equivalent traffic through paid search | +| **Formula** | Sum of (monthly organic clicks per keyword x CPC for that keyword) | +| **Data Source** | ~~SEO tool (traffic value calculation) | +| **Good Range** | Growing; significantly higher than SEO investment | +| **Warning** | Declining traffic value despite stable traffic (keywords losing CPC value) | +| **Segmentation** | By keyword group, by page | + +**Interpretation:** +- Organic traffic value represents how much you would need to spend on PPC to get the same traffic. +- Useful for communicating SEO value to stakeholders who understand paid media budgets. +- A site with $50K/month organic traffic value that spends $10K/month on SEO is getting a 5:1 return. + +--- + +## SEO/GEO Metric Definitions and Benchmarks + +### Organic Search Metrics + +| Metric | Definition | Good Range | Warning | Source | +|--------|-----------|-----------|---------|--------| +| Organic sessions | Visits from organic search | Growing MoM | >10% decline | ~~analytics | +| Keyword visibility | % of target keywords in top 100 | >60% | <40% | ~~SEO tool | +| Average position | Mean position across tracked keywords | <20 | >30 | ~~search console | +| Organic CTR | Clicks / impressions from search | >3% | <1.5% | ~~search console | +| Pages indexed | Pages in Google index | Growing | Dropping | ~~search console | +| Organic conversion rate | Conversions / organic sessions | >2% | <0.5% | ~~analytics | +| Non-brand organic traffic | Organic traffic minus brand searches | >50% of total organic | <30% | ~~analytics | + +### GEO/AI Visibility Metrics + +| Metric | Definition | Good Range | Warning | Source | +|--------|-----------|-----------|---------|--------| +| AI citation rate | % of monitored queries citing your content | >20% | <5% | ~~AI monitor | +| AI citation position | Average position in AI response citations | Top 3 sources | Not cited | ~~AI monitor | +| AI answer coverage | % of your topics appearing in AI answers | Growing | Declining | ~~AI monitor | +| Brand mention in AI | Times your brand is mentioned in AI responses | Growing | Zero | ~~AI monitor | + +### Domain Authority Metrics + +| Metric | Definition | Good Range | Warning | Source | +|--------|-----------|-----------|---------|--------| +| Domain Rating/Authority | Overall domain strength | Growing | Declining | ~~SEO tool | +| Referring domains | Unique domains linking to you | Growing MoM | Loss >10% MoM | ~~link database | +| Backlink growth rate | Net new backlinks per month | Positive | Negative trend | ~~link database | +| Toxic link ratio | Toxic links / total links | <5% | >10% | ~~link database | + +## Reporting Templates by Audience + +### Executive Report (C-Suite / Leadership) + +**Focus:** Business outcomes, ROI, competitive position +**Length:** 1 page + appendix +**Frequency:** Monthly or Quarterly + +| Section | Content | +|---------|---------| +| Traffic & Revenue | Organic traffic trend + attributed revenue | +| Competitive Position | Visibility share vs. top 3 competitors | +| AI Visibility | AI citation trend and coverage | +| Key Wins | Top 3 achievements with business impact | +| Risks | Top 3 concerns with proposed mitigation | +| Investment Ask | Resources needed for next period | + +### Marketing Team Report + +**Focus:** Channel performance, content effectiveness, technical health +**Length:** 2-3 pages +**Frequency:** Monthly + +| Section | Content | +|---------|---------| +| Keyword Performance | Rankings gained/lost, new keywords discovered | +| Content Performance | Top pages by traffic, engagement, conversions | +| Technical Health | Crawl errors, speed scores, indexation | +| Backlink Profile | New links, lost links, quality assessment | +| GEO Performance | AI citation changes, new citations | +| Action Items | P0-P3 prioritized task list | + +### Technical SEO Report + +**Focus:** Crawlability, indexation, speed, errors +**Length:** Detailed +**Frequency:** Weekly or Bi-weekly + +| Section | Content | +|---------|---------| +| Crawl Stats | Pages crawled, errors, crawl budget usage | +| Index Coverage | Indexed/excluded/errored pages | +| Core Web Vitals | LCP, CLS, INP trends | +| Error Log | New 4xx/5xx errors with resolution status | +| Schema Validation | New warnings, rich result eligibility | +| Technical Debt | Outstanding issues by priority | + +## Trend Analysis Framework + +### Period-Over-Period Analysis + +| Comparison | Best For | Limitation | +|-----------|---------|-----------| +| Week over week (WoW) | Detecting sudden changes | Noisy, affected by day-of-week patterns | +| Month over month (MoM) | Identifying trends | Seasonal bias | +| Year over year (YoY) | Accounting for seasonality | Does not reflect recent trajectory | +| Rolling 30-day average | Smoothing noise | Lags behind real changes | + +### Trend Interpretation Guidelines + +| Pattern | Likely Cause | Recommended Action | +|---------|-------------|-------------------| +| Steady growth | Strategy is working | Continue, optimize high performers | +| Sudden spike then drop | Viral content or algorithm volatility | Investigate cause, build on if repeatable | +| Gradual decline | Content decay, competition, technical debt | Comprehensive audit needed | +| Flat line | Plateau — existing strategy maxed out | New content areas, new link strategies | +| Seasonal pattern | Industry/demand cycles | Plan content calendar around peaks | + +## SEO Attribution Guidance + +### Attribution Challenges in SEO + +| Challenge | Impact | Mitigation | +|----------|--------|-----------| +| Long conversion paths | SEO rarely gets last-touch credit | Use assisted conversions report | +| Brand vs. non-brand | Brand searches inflate organic metrics | Always separate brand/non-brand | +| Cross-device journeys | Mobile search to desktop conversion | Enable cross-device tracking | +| SEO + paid overlap | Cannibalization or lift? | Test turning off paid for branded terms | +| Content assists sales | Hard to attribute | Track content touches in CRM | + diff --git a/.cursor/skills/performance-reporter/references/report-output-templates.md b/.cursor/skills/performance-reporter/references/report-output-templates.md new file mode 100644 index 0000000000..fa0f0fdfaf --- /dev/null +++ b/.cursor/skills/performance-reporter/references/report-output-templates.md @@ -0,0 +1,417 @@ +# Performance Report Output Templates + +Detailed output templates for each step of the performance reporting workflow. Use these templates when generating reports for stakeholders. + +--- + +## 1. Report Configuration Template + +```markdown +## Report Configuration + +**Domain**: [domain] +**Report Period**: [start date] to [end date] +**Comparison Period**: [previous period for comparison] +**Report Type**: [Monthly/Quarterly/Annual/Custom] +**Audience**: [Executive/Technical/Client] +**Focus Areas**: [Rankings/Traffic/Content/Backlinks/GEO] +``` + +--- + +## 2. Executive Summary Template + +```markdown +# SEO Performance Report + +**Domain**: [domain] +**Period**: [date range] +**Prepared**: [date] + +--- + +## Executive Summary + +### Overall Performance: [Excellent/Good/Needs Attention/Critical] + +**Key Highlights**: + +Wins: +- [Win 1 - e.g., "Organic traffic increased 25%"] +- [Win 2 - e.g., "3 new #1 rankings achieved"] +- [Win 3 - e.g., "Conversion rate improved 15%"] + +Watch Areas: +- [Area 1 - e.g., "Mobile rankings declining slightly"] +- [Area 2 - e.g., "Competitor gaining ground on key terms"] + +Action Required: +- [Issue 1 - e.g., "Technical SEO audit needed"] + +### Key Metrics at a Glance + +| Metric | This Period | Last Period | Change | Target | Status | +|--------|-------------|-------------|--------|--------|--------| +| Organic Traffic | [X] | [Y] | [+/-Z%] | [T] | [status] | +| Keyword Rankings (Top 10) | [X] | [Y] | [+/-Z] | [T] | [status] | +| Organic Conversions | [X] | [Y] | [+/-Z%] | [T] | [status] | +| Domain Authority | [X] | [Y] | [+/-Z] | [T] | [status] | +| AI Citations | [X] | [Y] | [+/-Z%] | [T] | [status] | + +### SEO ROI + +**Investment**: $[X] (content, tools, effort) +**Organic Revenue**: $[Y] +**ROI**: [Z]% +``` + +--- + +## 3. Organic Traffic Analysis Template + +```markdown +## Organic Traffic Analysis + +### Traffic Overview + +| Metric | This Period | vs Last Period | vs Last Year | +|--------|-------------|----------------|--------------| +| Sessions | [X] | [+/-Y%] | [+/-Z%] | +| Users | [X] | [+/-Y%] | [+/-Z%] | +| Pageviews | [X] | [+/-Y%] | [+/-Z%] | +| Avg. Session Duration | [X] | [+/-Y%] | [+/-Z%] | +| Bounce Rate | [X]% | [+/-Y%] | [+/-Z%] | +| Pages per Session | [X] | [+/-Y] | [+/-Z] | + +### Traffic Trend + +``` +[Month 1] ████████████████████ [X] +[Month 2] █████████████████████ [Y] +[Month 3] ███████████████████████ [Z] +[Current] ████████████████████████ [W] +``` + +### Traffic by Source + +| Channel | Sessions | % of Total | Change | +|---------|----------|------------|--------| +| Organic Search | [X] | [Y]% | [+/-Z%] | +| Direct | [X] | [Y]% | [+/-Z%] | +| Referral | [X] | [Y]% | [+/-Z%] | +| Social | [X] | [Y]% | [+/-Z%] | + +### Top Performing Pages + +| Page | Sessions | Change | Conversions | +|------|----------|--------|-------------| +| [Page 1] | [X] | [+/-Y%] | [Z] | +| [Page 2] | [X] | [+/-Y%] | [Z] | +| [Page 3] | [X] | [+/-Y%] | [Z] | + +### Traffic by Device + +| Device | Sessions | Change | Conv. Rate | +|--------|----------|--------|------------| +| Desktop | [X] ([Y]%) | [+/-Z%] | [%] | +| Mobile | [X] ([Y]%) | [+/-Z%] | [%] | +| Tablet | [X] ([Y]%) | [+/-Z%] | [%] | +``` + +--- + +## 4. Keyword Ranking Performance Template + +```markdown +## Keyword Ranking Performance + +### Rankings Overview + +| Position Range | Keywords | Change | Traffic Impact | +|----------------|----------|--------|----------------| +| Position 1 | [X] | [+/-Y] | [Z] sessions | +| Position 2-3 | [X] | [+/-Y] | [Z] sessions | +| Position 4-10 | [X] | [+/-Y] | [Z] sessions | +| Position 11-20 | [X] | [+/-Y] | [Z] sessions | +| Position 21-50 | [X] | [+/-Y] | [Z] sessions | + +### Top Ranking Improvements + +| Keyword | Previous | Current | Change | Traffic | +|---------|----------|---------|--------|---------| +| [kw 1] | [X] | [Y] | +[Z] | [sessions] | + +### Rankings That Declined + +| Keyword | Previous | Current | Change | Impact | Action | +|---------|----------|---------|--------|--------|--------| +| [kw 1] | [X] | [Y] | -[Z] | -[sessions] | [action] | + +### SERP Feature Performance + +| Feature | Won | Lost | Opportunities | +|---------|-----|------|---------------| +| Featured Snippets | [X] | [Y] | [Z] | +| People Also Ask | [X] | [Y] | [Z] | +| Local Pack | [X] | [Y] | [Z] | +``` + +--- + +## 5. GEO/AI Visibility Template + +```markdown +## GEO (AI Visibility) Performance + +### AI Citation Overview + +| Metric | This Period | Last Period | Change | +|--------|-------------|-------------|--------| +| Keywords with AI Overview | [X]/[Y] | [X]/[Y] | [+/-Z] | +| Your AI Citations | [X] | [Y] | [+/-Z%] | +| Citation Rate | [X]% | [Y]% | [+/-Z%] | +| Avg Citation Position | [X] | [Y] | [+/-Z] | + +### AI Citation by Topic + +| Topic Cluster | Opportunities | Citations | Rate | +|---------------|---------------|-----------|------| +| [Topic 1] | [X] | [Y] | [Z]% | + +### GEO Wins This Period + +| Query | Citation Status | Source Page | Impact | +|-------|-----------------|-------------|--------| +| [query 1] | New citation | [page] | High visibility | + +### GEO Optimization Opportunities + +| Query | AI Overview | You Cited? | Gap | Action | +|-------|-------------|------------|-----|--------| +| [query] | Yes | No | [gap] | [action] | +``` + +--- + +## 6. Domain Authority (CITE Score) Template + +```markdown +## Domain Authority (CITE Score) + +### CITE Score Summary + +| Metric | This Period | Last Period | Change | +|--------|-------------|-------------|--------| +| CITE Score | [X]/100 | [Y]/100 | [+/-Z] | +| C -- Citation | [X]/100 | [Y]/100 | [+/-Z] | +| I -- Identity | [X]/100 | [Y]/100 | [+/-Z] | +| T -- Trust | [X]/100 | [Y]/100 | [+/-Z] | +| E -- Eminence | [X]/100 | [Y]/100 | [+/-Z] | + +**Veto Status**: No triggers / [item] triggered + +### Key Changes + +- [Notable improvement or concern 1] +- [Notable improvement or concern 2] + +_For full 40-item evaluation, run `/seo:audit-domain`_ +``` + +**Note**: If no previous CITE audit exists, note this section as "Not yet evaluated -- run domain-authority-auditor for baseline" and skip. + +--- + +## 7. Content Quality (CORE-EEAT Score) Template + +```markdown +## Content Quality (CORE-EEAT Score) + +### Content Quality Summary + +| Metric | Value | +|--------|-------| +| Pages Audited | [count] | +| Average CORE-EEAT Score | [score]/100 ([rating]) | +| Average GEO Score (CORE) | [score]/100 | +| Average SEO Score (EEAT) | [score]/100 | +| Veto Items Triggered | [count] ([item IDs]) | + +### Dimension Averages Across Audited Pages + +| Dimension | Average Score | Trend | +|-----------|--------------|-------| +| C -- Contextual Clarity | [score] | [up/down/stable] | +| O -- Organization | [score] | [up/down/stable] | +| R -- Referenceability | [score] | [up/down/stable] | +| E -- Exclusivity | [score] | [up/down/stable] | +| Exp -- Experience | [score] | [up/down/stable] | +| Ept -- Expertise | [score] | [up/down/stable] | +| A -- Authority | [score] | [up/down/stable] | +| T -- Trust | [score] | [up/down/stable] | + +### Key Content Quality Changes + +- [Notable score changes since last report] +- [Pages with significant quality improvements/declines] + +_For full 80-item evaluation, run `/seo:audit-page` on individual pages._ +``` + +**Note**: If no content quality audit exists, note this section as "Content quality not yet evaluated -- run `/seo:audit-page` on key landing pages to establish baseline" and skip. + +--- + +## 8. Backlink Performance Template + +```markdown +## Backlink Performance + +### Link Profile Summary + +| Metric | This Period | Last Period | Change | +|--------|-------------|-------------|--------| +| Total Backlinks | [X] | [Y] | [+/-Z] | +| Referring Domains | [X] | [Y] | [+/-Z] | +| Domain Authority | [X] | [Y] | [+/-Z] | +| Avg. Link DA | [X] | [Y] | [+/-Z] | + +### Link Acquisition + +| Period | New Links | Lost Links | Net | +|--------|-----------|------------|-----| +| Week 1 | [X] | [Y] | [+/-Z] | +| Week 2 | [X] | [Y] | [+/-Z] | +| Week 3 | [X] | [Y] | [+/-Z] | +| Week 4 | [X] | [Y] | [+/-Z] | +| **Total** | **[X]** | **[Y]** | **[+/-Z]** | + +### Notable New Links + +| Source | DA | Type | Value | +|--------|-----|------|-------| +| [domain 1] | [DA] | [type] | High | + +### Competitive Position + +Your referring domains rank #[X] of [Y] competitors. +``` + +--- + +## 9. Content Performance Template + +```markdown +## Content Performance + +### Content Publishing Summary + +| Metric | This Period | Last Period | Target | +|--------|-------------|-------------|--------| +| New articles published | [X] | [Y] | [Z] | +| Content updates | [X] | [Y] | [Z] | +| Total word count | [X] | [Y] | - | + +### Top Performing Content + +| Content | Traffic | Rankings | Conversions | Status | +|---------|---------|----------|-------------|--------| +| [Title 1] | [X] | [Y] keywords | [Z] | Top performer | +| [Title 2] | [X] | [Y] keywords | [Z] | Growing | + +### Content Needing Attention + +| Content | Issue | Traffic Change | Action | +|---------|-------|----------------|--------| +| [Title] | [issue] | -[X]% | [action] | + +### Content ROI + +| Content Piece | Investment | Traffic Value | ROI | +|---------------|------------|---------------|-----| +| [Title 1] | $[X] | $[Y] | [Z]% | +``` + +--- + +## 10. Recommendations Template + +```markdown +## Recommendations & Next Steps + +### Immediate Actions (This Week) + +| Priority | Action | Expected Impact | Owner | +|----------|--------|-----------------|-------| +| High | [Action 1] | [Impact] | [Owner] | + +### Short-term (This Month) + +| Priority | Action | Expected Impact | Owner | +|----------|--------|-----------------|-------| +| Medium | [Action 1] | [Impact] | [Owner] | + +### Long-term (This Quarter) + +| Priority | Action | Expected Impact | Owner | +|----------|--------|-----------------|-------| +| Planned | [Action 1] | [Impact] | [Owner] | + +### Goals for Next Period + +| Metric | Current | Target | Action to Achieve | +|--------|---------|--------|-------------------| +| Organic Traffic | [X] | [Y] | [action] | +| Keywords Top 10 | [X] | [Y] | [action] | +| AI Citations | [X] | [Y] | [action] | +| Referring Domains | [X] | [Y] | [action] | +``` + +--- + +## 11. Full Report Compilation Template + +```markdown +# [Company] SEO & GEO Performance Report + +## [Month/Quarter] [Year] + +--- + +### Table of Contents + +1. Executive Summary +2. Organic Traffic Performance +3. Keyword Rankings +4. GEO/AI Visibility +5. Domain Authority (CITE Score) +6. Content Quality (CORE-EEAT Score) +7. Backlink Analysis +8. Content Performance +9. Technical Health +10. Competitive Landscape +11. Recommendations +12. Appendix + +--- + +[Include all sections from above] + +--- + +## Appendix + +### Data Sources +- ~~analytics (traffic and conversion data) +- ~~search console (search performance) +- ~~SEO tool (rankings and backlinks) +- ~~AI monitor (GEO metrics) + +### Methodology +[Explain how metrics were calculated] + +### Glossary +- **GEO**: Generative Engine Optimization +- **DA**: Domain Authority +- [Additional terms] +``` diff --git a/.cursor/skills/performance-reporter/references/report-templates.md b/.cursor/skills/performance-reporter/references/report-templates.md new file mode 100644 index 0000000000..2312194dbe --- /dev/null +++ b/.cursor/skills/performance-reporter/references/report-templates.md @@ -0,0 +1,383 @@ +# SEO/GEO Report Templates + +Copy-ready report templates for executive, marketing, and technical audiences. Each template includes example data to illustrate proper formatting and data presentation. + +--- + +## 1. Executive Report Template + +Use this template for C-suite, VP-level, or board reporting. Focuses on business impact, competitive position, and strategic recommendations. Keep to 1 page plus optional appendix. + +--- + +```markdown +# SEO & GEO Performance Summary + +**Period:** January 2025 +**Prepared for:** Leadership Team +**Prepared by:** [Name], SEO Lead + +--- + +## Performance at a Glance + +| KPI | Jan 2025 | Dec 2024 | MoM Change | YoY Change | Target | Status | +|-----|----------|----------|------------|------------|--------|--------| +| Organic Revenue | $142,000 | $128,000 | +10.9% | +34% | $130,000 | On track | +| Organic Sessions | 285,000 | 261,000 | +9.2% | +28% | 270,000 | On track | +| Keywords in Top 10 | 187 | 172 | +15 | +62 | 180 | On track | +| AI Citations | 34 | 28 | +21.4% | N/A | 30 | On track | +| Domain Rating | 52 | 51 | +1 | +8 | 55 | In progress | +| Organic CVR | 2.8% | 2.6% | +0.2pp | +0.5pp | 2.5% | On track | + +## Competitive Position + +**Share of Voice Ranking:** #2 of 5 tracked competitors (up from #3 in Q3) + +| Rank | Competitor | Visibility Share | +|------|-----------|-----------------| +| 1 | CompetitorA.com | 28% | +| **2** | **YourSite.com** | **24%** | +| 3 | CompetitorB.com | 21% | +| 4 | CompetitorC.com | 16% | +| 5 | CompetitorD.com | 11% | + +## Key Wins + +1. **Achieved #1 ranking for "project management software"** — estimated $18K/month traffic value +2. **AI citation rate increased to 34%** — up from 22% in Q3, now cited in AI responses for core product queries +3. **Published research report generated 45 backlinks** — from sites including TechCrunch (DR 94) and Forbes (DR 95) + +## Risks & Mitigation + +1. **Google core update expected in February** — monitoring closely; content quality scores above benchmark +2. **CompetitorA increased content production 2x** — accelerating our editorial calendar in response +3. **Mobile CWV scores degraded** — engineering team addressing LCP issue, fix scheduled for Feb 15 + +## Investment & ROI + +| Item | Jan Spend | Organic Revenue | Cumulative ROI (12mo) | +|------|----------|----------------|----------------------| +| SEO team | $12,000 | $142,000 | 418% | +| Content production | $8,000 | (included above) | (included above) | +| Tools & data | $2,500 | (included above) | (included above) | +| **Total** | **$22,500** | **$142,000** | **418%** | + +## Ask for Next Period + +- Approve $5,000 budget increase for digital PR campaign targeting Q2 product launch +- Engineering allocation: 20 hours for Core Web Vitals remediation +``` + +--- + +## 2. Marketing Team Report Template + +Use this template for marketing managers, content teams, and channel leads. Provides detailed performance data with actionable insights. + +--- + +```markdown +# Monthly SEO & GEO Performance Report + +**Domain:** yoursite.com +**Period:** January 1-31, 2025 +**Comparison:** vs. December 2024 and January 2024 +**Prepared:** February 3, 2025 + +--- + +## 1. Traffic Performance + +### Overview + +| Metric | Jan 2025 | Dec 2024 | MoM | Jan 2024 | YoY | +|--------|----------|----------|-----|----------|-----| +| Organic Sessions | 285,000 | 261,000 | +9.2% | 223,000 | +27.8% | +| Organic Users | 198,000 | 182,000 | +8.8% | 158,000 | +25.3% | +| Organic Pageviews | 412,000 | 378,000 | +9.0% | 318,000 | +29.6% | +| Bounce Rate | 42% | 44% | -2pp | 48% | -6pp | +| Avg Session Duration | 3:12 | 3:05 | +3.8% | 2:48 | +14.3% | +| Pages/Session | 2.4 | 2.3 | +4.3% | 2.1 | +14.3% | + +### Traffic by Device + +| Device | Sessions | % of Total | MoM Change | CVR | +|--------|----------|------------|------------|-----| +| Desktop | 142,500 (50%) | 50% | +7.1% | 3.2% | +| Mobile | 131,100 (46%) | 46% | +11.5% | 2.1% | +| Tablet | 11,400 (4%) | 4% | +5.6% | 2.8% | + +### Non-Brand vs. Brand Split + +| Segment | Sessions | % of Organic | MoM Change | +|---------|----------|-------------|------------| +| Non-brand | 184,000 | 64.6% | +12.1% | +| Brand | 101,000 | 35.4% | +4.1% | + +**Insight:** Non-brand growth outpacing brand growth indicates SEO is driving new audience discovery effectively. + +## 2. Keyword Rankings + +### Position Distribution + +| Range | Jan 2025 | Dec 2024 | Change | +|-------|----------|----------|--------| +| Position #1 | 23 | 19 | +4 | +| Position #2-3 | 41 | 38 | +3 | +| Position #4-10 | 123 | 115 | +8 | +| Position #11-20 | 89 | 94 | -5 | +| Position #21-50 | 156 | 162 | -6 | +| Not ranking | 68 | 72 | -4 | +| **Total tracked** | **500** | **500** | — | + +### Top 5 Ranking Improvements + +| Keyword | Volume | Old Rank | New Rank | Change | Est. Traffic | +|---------|--------|----------|----------|--------|-------------| +| project management software | 18,100 | 4 | 1 | +3 | +4,200/mo | +| best CRM for small business | 8,200 | 12 | 6 | +6 | +380/mo | +| team collaboration tools | 6,500 | 8 | 3 | +5 | +420/mo | +| agile methodology guide | 4,400 | 22 | 9 | +13 | +180/mo | +| remote work software | 5,100 | 15 | 7 | +8 | +210/mo | + +### Top 5 Ranking Declines + +| Keyword | Volume | Old Rank | New Rank | Change | Action | +|---------|--------|----------|----------|--------|--------| +| kanban board software | 3,600 | 5 | 11 | -6 | Content refresh scheduled Feb 10 | +| project planning template | 2,900 | 7 | 14 | -7 | Competitor published superior template | +| time tracking tools | 4,100 | 9 | 15 | -6 | New SERP features displacing organic | +| workflow automation | 3,200 | 6 | 9 | -3 | Monitoring, within normal fluctuation | +| sprint planning guide | 1,800 | 3 | 8 | -5 | Content update needed with 2025 examples | + +## 3. Content Performance + +### Top Performing Content (by Organic Traffic) + +| Page | Sessions | MoM | Rankings | Conversions | +|------|----------|-----|----------|-------------| +| /blog/project-management-guide | 18,400 | +22% | 12 KWs top 10 | 184 | +| /product/features | 15,200 | +8% | 8 KWs top 10 | 456 | +| /blog/crm-comparison | 12,100 | +15% | 9 KWs top 10 | 121 | +| /resources/templates | 9,800 | +31% | 6 KWs top 10 | 98 | +| /blog/remote-work-tips | 8,600 | +5% | 5 KWs top 10 | 43 | + +### Content Needing Refresh (Decaying Traffic) + +| Page | Sessions | MoM | Age | Action | +|------|----------|-----|-----|--------| +| /blog/2023-trends | 2,100 | -35% | 14mo | Rewrite as 2025 trends | +| /blog/old-tool-comparison | 1,400 | -28% | 18mo | Update with current pricing/features | +| /guides/beginner-pm | 3,200 | -18% | 10mo | Add interactive elements, update screenshots | + +## 4. GEO / AI Visibility + +| Metric | Jan 2025 | Dec 2024 | Change | +|--------|----------|----------|--------| +| Queries with AI Overview | 78/500 | 72/500 | +6 | +| Your citations in AI | 34 | 28 | +6 | +| Citation rate | 43.6% | 38.9% | +4.7pp | +| Avg citation position | 2.1 | 2.4 | +0.3 (better) | + +### New AI Citations Won + +- "best project management software" — cited as #1 source +- "how to create a project plan" — cited as #2 source +- "agile vs waterfall" — cited as #3 source + +## 5. Backlink Performance + +| Metric | Jan 2025 | Dec 2024 | Change | +|--------|----------|----------|--------| +| Total referring domains | 1,847 | 1,812 | +35 | +| New links acquired | 62 | 48 | +14 | +| Links lost | 27 | 31 | -4 (fewer lost) | +| Average new link DR | 41 | 38 | +3 | + +### Notable New Links + +| Source | DR | Type | +|--------|-----|------| +| TechCrunch | 94 | Press mention (research report) | +| Forbes | 95 | Expert quote in roundup | +| HubSpot Blog | 93 | Resource citation | + +## 6. Action Items + +| Priority | Action | Owner | Deadline | +|----------|--------|-------|----------| +| P0 | Fix mobile LCP issue (currently 3.8s) | Engineering | Feb 15 | +| P1 | Refresh kanban board software article | Content | Feb 10 | +| P1 | Publish 2025 trends article (replace 2023 version) | Content | Feb 14 | +| P2 | Build links to CRM comparison page (target: 5 new) | SEO | Feb 28 | +| P2 | Optimize 3 pages for AI citation (add structured data) | SEO | Feb 21 | +| P3 | Research new keyword opportunities in "AI tools" space | SEO | Feb 28 | +``` + +--- + +## 3. Technical SEO Report Template + +Use this template for engineering teams, dev leads, and technical stakeholders. Focuses on crawlability, indexation, performance, and error resolution. + +--- + +```markdown +# Technical SEO Health Report + +**Domain:** yoursite.com +**Period:** January 2025 +**Prepared:** February 3, 2025 + +--- + +## 1. Crawl Health + +### Crawl Stats Summary + +| Metric | Jan 2025 | Dec 2024 | Change | Status | +|--------|----------|----------|--------|--------| +| Total pages crawled | 12,400 | 11,800 | +5.1% | Normal | +| Avg crawl rate (pages/day) | 400 | 381 | +5.0% | Normal | +| Avg response time | 320ms | 290ms | +10.3% | Monitor | +| Crawl errors | 18 | 12 | +6 | Investigate | + +### Crawl Budget Efficiency + +| Page Type | Pages Crawled | % of Crawl | Should Crawl? | +|-----------|-------------|-----------|---------------| +| Blog posts | 4,200 | 33.9% | Yes | +| Product pages | 3,100 | 25.0% | Yes | +| Category pages | 2,400 | 19.4% | Yes | +| Parameter URLs | 1,800 | 14.5% | No — block in robots.txt | +| Paginated archives | 900 | 7.3% | Partially — consolidate | + +**Action:** Block parameter URLs via robots.txt to reclaim 14.5% of crawl budget. + +## 2. Index Coverage + +### Index Status + +| Status | Count | Change | Action | +|--------|-------|--------|--------| +| Valid (indexed) | 2,847 | +23 | None — healthy growth | +| Valid with warnings | 42 | +3 | Review warnings | +| Excluded (intentional) | 1,204 | +8 | Verify intentional | +| Excluded (error) | 67 | +12 | Fix errors | + +### Exclusion Reasons (Top 5) + +| Reason | Count | Change | Priority | +|--------|-------|--------|----------| +| Crawled, not indexed | 34 | +8 | P1 — improve content quality | +| Duplicate without canonical | 15 | +2 | P2 — add canonical tags | +| Blocked by robots.txt | 12 | 0 | Verify intentional | +| Soft 404 | 6 | +2 | P1 — fix or redirect | +| Server error (5xx) | 0 | 0 | Clean | + +## 3. Core Web Vitals + +### Field Data (CrUX — 28-day rolling) + +| Metric | Mobile | Desktop | Status | +|--------|--------|---------|--------| +| LCP | 3.8s (Poor) | 2.1s (Good) | Mobile needs fix | +| CLS | 0.08 (Good) | 0.05 (Good) | Passing | +| INP | 180ms (Good) | 120ms (Good) | Passing | + +### LCP Diagnosis (Mobile) + +| Page Group | Mobile LCP | Issue | Fix | +|-----------|-----------|-------|-----| +| /blog/* | 4.2s | Hero images not optimized | Convert to WebP, add lazy loading | +| /product/* | 3.5s | Third-party script blocking render | Defer non-critical scripts | +| /resources/* | 3.1s | Large CSS bundle | Code-split CSS | + +**Estimated fix timeline:** 2 weeks (engineering sprint Feb 10-21) + +## 4. Error Log + +### New Errors This Period + +| Error Type | Count | Pages Affected | Priority | +|-----------|-------|---------------|----------| +| 404 Not Found | 8 | /blog/deleted-post-1, /old/page-2, +6 | P1 | +| 500 Server Error | 3 | /api/webhook (intermittent) | P0 | +| Redirect chain (3+ hops) | 5 | /old-url -> /new-url -> /final-url | P2 | +| Mixed content warning | 2 | /resources/old-guide, /tools/calc | P2 | + +### Error Resolution Status + +| Error | Opened | Status | Owner | +|-------|--------|--------|-------| +| 404 on /blog/deleted-post-1 | Jan 5 | Redirect created Jan 8 | SEO | +| 500 on /api/webhook | Jan 12 | Investigating | Backend | +| Redirect chain on /old-url | Jan 15 | Pending | SEO | + +## 5. Schema & Rich Results + +### Schema Validation + +| Schema Type | Pages | Valid | Warnings | Errors | +|------------|-------|-------|----------|--------| +| Article | 342 | 338 | 4 | 0 | +| Product | 89 | 87 | 0 | 2 | +| FAQ | 56 | 56 | 0 | 0 | +| HowTo | 23 | 23 | 0 | 0 | +| BreadcrumbList | 2,847 | 2,847 | 0 | 0 | + +**Action:** Fix 2 Product schema errors (missing "price" property on clearance items). + +## 6. Technical Debt Tracker + +| Item | Priority | Effort | Impact | Status | +|------|----------|--------|--------|--------| +| Block parameter URLs in robots.txt | P1 | Low | Crawl budget +14% | Scheduled Feb 5 | +| Fix mobile LCP (image optimization) | P0 | Medium | CWV pass rate | Sprint Feb 10-21 | +| Consolidate duplicate pages (42 pages) | P2 | Medium | Index quality | Backlog | +| Implement hreflang for EN-GB pages | P3 | High | International SEO | Q2 planned | +| Migrate HTTP resources to HTTPS | P2 | Low | Security + trust | Scheduled Feb 12 | + +## 7. Recommendations for Engineering + +1. **Immediate:** Resolve intermittent 500 errors on /api/webhook endpoint +2. **This sprint:** Optimize hero images on blog templates (convert to WebP, implement responsive sizes) +3. **Next sprint:** Defer third-party scripts on product pages (move to async loading) +4. **Backlog:** Implement edge caching for static blog content to improve TTFB +``` + +--- + +## 4. Report Assembly Guidelines + +### How to Combine Templates + +| Audience | Include Sections | Exclude | +|----------|-----------------|---------| +| CEO / Board | Executive template only | All technical detail | +| VP Marketing | Executive + Marketing sections 1-4, 6 | Crawl stats, schema details | +| Marketing Manager | Full Marketing template | Deep technical debugging | +| SEO Manager | Marketing + Technical templates | Executive ROI framing | +| Engineering Lead | Technical template only | Revenue, keyword details | +| Client (agency) | Executive + Marketing sections 1-3, 6 | Internal cost data, technical debt | + +### Data Freshness Requirements + +| Report Type | Maximum Data Age | Reason | +|------------|-----------------|--------| +| Executive monthly | 3 days after period end | Allow for data processing lag | +| Marketing weekly | 1 day after period end | Timely action items | +| Technical | Real-time where possible | Issues need immediate attention | +| Quarterly review | 5 days after quarter end | Allow for data reconciliation | + +### Report Delivery Checklist + +- [ ] All data sources verified and dated +- [ ] Period-over-period comparisons included +- [ ] Competitor context provided where relevant +- [ ] Action items are specific, assigned, and time-bound +- [ ] Report tailored to audience (no jargon for executives, full detail for technical) +- [ ] Visualizations are clear and labeled +- [ ] Sources cited for all external benchmarks +- [ ] Draft reviewed for accuracy before distribution diff --git a/.cursor/skills/playwright-testing/SKILL.md b/.cursor/skills/playwright-testing/SKILL.md new file mode 100644 index 0000000000..6512f12dc6 --- /dev/null +++ b/.cursor/skills/playwright-testing/SKILL.md @@ -0,0 +1,295 @@ +--- +name: playwright-testing +description: Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), test tags (@smoke, @fast, @critical, filtering with --grep), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testing. +--- + +# Playwright Testing + +This skill provides comprehensive guidance for all aspects of Playwright test development, from writing new tests to debugging and maintaining existing test suites. + +## Activity-Based Reference Guide + +Consult these references based on what you're doing: + +### Writing New Tests + +**When to use**: Creating new test files, writing test cases, implementing test scenarios + +| Activity | Reference Files | +| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| **Writing E2E tests** | [test-suite-structure.md](core/test-suite-structure.md), [locators.md](core/locators.md), [assertions-waiting.md](core/assertions-waiting.md) | +| **Writing component tests** | [component-testing.md](testing-patterns/component-testing.md), [test-suite-structure.md](core/test-suite-structure.md) | +| **Writing API tests** | [api-testing.md](testing-patterns/api-testing.md), [test-suite-structure.md](core/test-suite-structure.md) | +| **Writing GraphQL tests** | [graphql-testing.md](testing-patterns/graphql-testing.md), [api-testing.md](testing-patterns/api-testing.md) | +| **Writing visual regression tests** | [visual-regression.md](testing-patterns/visual-regression.md), [canvas-webgl.md](testing-patterns/canvas-webgl.md) | +| **Structuring test code with POM** | [page-object-model.md](core/page-object-model.md), [test-suite-structure.md](core/test-suite-structure.md) | +| **Setting up test data/fixtures** | [fixtures-hooks.md](core/fixtures-hooks.md), [test-data.md](core/test-data.md) | +| **Handling authentication** | [authentication.md](advanced/authentication.md), [authentication-flows.md](advanced/authentication-flows.md) | +| **Testing date/time features** | [clock-mocking.md](advanced/clock-mocking.md) | +| **Testing file upload/download** | [file-operations.md](testing-patterns/file-operations.md), [file-upload-download.md](testing-patterns/file-upload-download.md) | +| **Testing forms/validation** | [forms-validation.md](testing-patterns/forms-validation.md) | +| **Testing drag and drop** | [drag-drop.md](testing-patterns/drag-drop.md) | +| **Testing accessibility** | [accessibility.md](testing-patterns/accessibility.md) | +| **Testing security (XSS, CSRF)** | [security-testing.md](testing-patterns/security-testing.md) | +| **Using test annotations** | [annotations.md](core/annotations.md) | +| **Using test tags** | [test-tags.md](core/test-tags.md) | +| **Testing iframes** | [iframes.md](browser-apis/iframes.md) | +| **Testing canvas/WebGL** | [canvas-webgl.md](testing-patterns/canvas-webgl.md) | +| **Internationalization (i18n)** | [i18n.md](testing-patterns/i18n.md) | +| **Testing Electron apps** | [electron.md](testing-patterns/electron.md) | +| **Testing browser extensions** | [browser-extensions.md](testing-patterns/browser-extensions.md) | + +### Mobile & Responsive Testing + +**When to use**: Testing mobile devices, touch interactions, responsive layouts + +| Activity | Reference Files | +| ------------------------------- | -------------------------------------------------------------------------------- | +| **Device emulation** | [mobile-testing.md](advanced/mobile-testing.md) | +| **Touch gestures (swipe, tap)** | [mobile-testing.md](advanced/mobile-testing.md) | +| **Viewport/breakpoint testing** | [mobile-testing.md](advanced/mobile-testing.md) | +| **Mobile-specific UI** | [mobile-testing.md](advanced/mobile-testing.md), [locators.md](core/locators.md) | + +### Real-Time & Browser APIs + +**When to use**: Testing WebSockets, geolocation, permissions, multi-tab flows + +| Activity | Reference Files | +| ------------------------------- | ---------------------------------------------------------------------------------------- | +| **WebSocket/real-time testing** | [websockets.md](browser-apis/websockets.md) | +| **Geolocation mocking** | [browser-apis.md](browser-apis/browser-apis.md) | +| **Permission handling** | [browser-apis.md](browser-apis/browser-apis.md) | +| **Clipboard testing** | [browser-apis.md](browser-apis/browser-apis.md) | +| **Camera/microphone mocking** | [browser-apis.md](browser-apis/browser-apis.md) | +| **Multi-tab/popup flows** | [multi-context.md](advanced/multi-context.md) | +| **OAuth popup handling** | [third-party.md](advanced/third-party.md), [multi-context.md](advanced/multi-context.md) | + +### Debugging & Troubleshooting + +**When to use**: Test failures, element not found, timeouts, unexpected behavior + +| Activity | Reference Files | +| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| **Debugging test failures** | [debugging.md](debugging/debugging.md), [assertions-waiting.md](core/assertions-waiting.md) | +| **Fixing flaky tests** | [flaky-tests.md](debugging/flaky-tests.md), [debugging.md](debugging/debugging.md), [assertions-waiting.md](core/assertions-waiting.md) | +| **Debugging flaky parallel runs** | [flaky-tests.md](debugging/flaky-tests.md), [performance.md](infrastructure-ci-cd/performance.md), [fixtures-hooks.md](core/fixtures-hooks.md) | +| **Ensuring test isolation / avoiding state leak** | [flaky-tests.md](debugging/flaky-tests.md), [fixtures-hooks.md](core/fixtures-hooks.md), [performance.md](infrastructure-ci-cd/performance.md) | +| **Fixing selector issues** | [locators.md](core/locators.md), [debugging.md](debugging/debugging.md) | +| **Investigating timeout issues** | [assertions-waiting.md](core/assertions-waiting.md), [debugging.md](debugging/debugging.md) | +| **Using trace viewer** | [debugging.md](debugging/debugging.md) | +| **Debugging race conditions** | [flaky-tests.md](debugging/flaky-tests.md), [debugging.md](debugging/debugging.md), [assertions-waiting.md](core/assertions-waiting.md) | +| **Debugging console/JS errors** | [console-errors.md](debugging/console-errors.md), [debugging.md](debugging/debugging.md) | + +### Error & Edge Case Testing + +**When to use**: Testing error states, offline mode, network failures, validation + +| Activity | Reference Files | +| ------------------------------ | ----------------------------------------------------------------------------------------------------- | +| **Error boundary testing** | [error-testing.md](debugging/error-testing.md) | +| **Network failure simulation** | [error-testing.md](debugging/error-testing.md), [network-advanced.md](advanced/network-advanced.md) | +| **Offline mode testing** | [error-testing.md](debugging/error-testing.md), [service-workers.md](browser-apis/service-workers.md) | +| **Service worker testing** | [service-workers.md](browser-apis/service-workers.md) | +| **Loading state testing** | [error-testing.md](debugging/error-testing.md) | +| **Form validation testing** | [error-testing.md](debugging/error-testing.md) | + +### Multi-User & Collaboration Testing + +**When to use**: Testing features involving multiple users, roles, or real-time collaboration + +| Activity | Reference Files | +| ------------------------------ | ------------------------------------------------------------------------------------ | +| **Multiple users in one test** | [multi-user.md](advanced/multi-user.md) | +| **Real-time collaboration** | [multi-user.md](advanced/multi-user.md), [websockets.md](browser-apis/websockets.md) | +| **Role-based access testing** | [multi-user.md](advanced/multi-user.md) | +| **Concurrent action testing** | [multi-user.md](advanced/multi-user.md) | + +### Architecture Decisions + +**When to use**: Choosing test patterns, deciding between approaches, planning test architecture + +| Activity | Reference Files | +| ---------------------------- | --------------------------------------------------------- | +| **POM vs fixtures decision** | [pom-vs-fixtures.md](architecture/pom-vs-fixtures.md) | +| **Test type selection** | [test-architecture.md](architecture/test-architecture.md) | +| **Mock vs real services** | [when-to-mock.md](architecture/when-to-mock.md) | +| **Test suite structure** | [test-suite-structure.md](core/test-suite-structure.md) | + +### Framework-Specific Testing + +**When to use**: Testing React or Next.js applications + +| Activity | Reference Files | +| ------------------------- | ----------------------------------- | +| **Testing React apps** | [react.md](frameworks/react.md) | +| **Testing Next.js apps** | [nextjs.md](frameworks/nextjs.md) | + +### Refactoring & Maintenance + +**When to use**: Improving existing tests, code review, reducing duplication + +| Activity | Reference Files | +| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- | +| **Refactoring to Page Object Model** | [page-object-model.md](core/page-object-model.md), [test-suite-structure.md](core/test-suite-structure.md) | +| **Improving test organization** | [test-suite-structure.md](core/test-suite-structure.md), [page-object-model.md](core/page-object-model.md) | +| **Extracting common setup/teardown** | [fixtures-hooks.md](core/fixtures-hooks.md) | +| **Replacing brittle selectors** | [locators.md](core/locators.md) | +| **Removing explicit waits** | [assertions-waiting.md](core/assertions-waiting.md) | +| **Creating test data factories** | [test-data.md](core/test-data.md) | +| **Configuration setup** | [configuration.md](core/configuration.md) | + +### Infrastructure & Configuration + +**When to use**: Setting up projects, configuring CI/CD, optimizing performance + +| Activity | Reference Files | +| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| **Configuring Playwright project** | [configuration.md](core/configuration.md), [projects-dependencies.md](core/projects-dependencies.md) | +| **Setting up CI/CD pipelines** | [ci-cd.md](infrastructure-ci-cd/ci-cd.md), [github-actions.md](infrastructure-ci-cd/github-actions.md) | +| **GitHub Actions setup** | [github-actions.md](infrastructure-ci-cd/github-actions.md) | +| **GitLab CI setup** | [gitlab.md](infrastructure-ci-cd/gitlab.md) | +| **Other CI providers** | [other-providers.md](infrastructure-ci-cd/other-providers.md) | +| **Docker/container setup** | [docker.md](infrastructure-ci-cd/docker.md) | +| **Global setup & teardown** | [global-setup.md](core/global-setup.md) | +| **Project dependencies** | [projects-dependencies.md](core/projects-dependencies.md) | +| **Optimizing test performance** | [performance.md](infrastructure-ci-cd/performance.md), [test-suite-structure.md](core/test-suite-structure.md) | +| **Configuring parallel execution** | [parallel-sharding.md](infrastructure-ci-cd/parallel-sharding.md), [performance.md](infrastructure-ci-cd/performance.md) | +| **Isolating test data between workers** | [fixtures-hooks.md](core/fixtures-hooks.md), [performance.md](infrastructure-ci-cd/performance.md) | +| **Test coverage** | [test-coverage.md](infrastructure-ci-cd/test-coverage.md) | +| **Test reporting/artifacts** | [reporting.md](infrastructure-ci-cd/reporting.md) | + +### Advanced Patterns + +**When to use**: Complex scenarios, API mocking, network interception + +| Activity | Reference Files | +| ------------------------------------ | ------------------------------------------------------------------------------------------------------------ | +| **Mocking API responses** | [test-suite-structure.md](core/test-suite-structure.md), [network-advanced.md](advanced/network-advanced.md) | +| **Network interception** | [network-advanced.md](advanced/network-advanced.md), [assertions-waiting.md](core/assertions-waiting.md) | +| **GraphQL mocking** | [network-advanced.md](advanced/network-advanced.md) | +| **HAR recording/playback** | [network-advanced.md](advanced/network-advanced.md) | +| **Custom fixtures** | [fixtures-hooks.md](core/fixtures-hooks.md) | +| **Advanced waiting strategies** | [assertions-waiting.md](core/assertions-waiting.md) | +| **OAuth/SSO mocking** | [third-party.md](advanced/third-party.md), [multi-context.md](advanced/multi-context.md) | +| **Payment gateway mocking** | [third-party.md](advanced/third-party.md) | +| **Email/SMS verification mocking** | [third-party.md](advanced/third-party.md) | +| **Failing on console errors** | [console-errors.md](debugging/console-errors.md) | +| **Security testing (XSS, CSRF)** | [security-testing.md](testing-patterns/security-testing.md) | +| **Performance budgets & Web Vitals** | [performance-testing.md](testing-patterns/performance-testing.md) | +| **Lighthouse integration** | [performance-testing.md](testing-patterns/performance-testing.md) | +| **Test annotations (skip, fixme)** | [annotations.md](core/annotations.md) | +| **Test tags (@smoke, @fast)** | [test-tags.md](core/test-tags.md) | +| **Test steps for reporting** | [annotations.md](core/annotations.md) | + +## Quick Decision Tree + +``` +What are you doing? +│ +├─ Writing a new test? +│ ├─ E2E test → core/test-suite-structure.md, core/locators.md, core/assertions-waiting.md +│ ├─ Component test → testing-patterns/component-testing.md +│ ├─ API test → testing-patterns/api-testing.md, core/test-suite-structure.md +│ ├─ GraphQL test → testing-patterns/graphql-testing.md +│ ├─ Visual regression → testing-patterns/visual-regression.md +│ ├─ Visual/canvas test → testing-patterns/canvas-webgl.md, core/test-suite-structure.md +│ ├─ Accessibility test → testing-patterns/accessibility.md +│ ├─ Mobile/responsive test → advanced/mobile-testing.md +│ ├─ i18n/locale test → testing-patterns/i18n.md +│ ├─ Electron app test → testing-patterns/electron.md +│ ├─ Browser extension test → testing-patterns/browser-extensions.md +│ ├─ Multi-user test → advanced/multi-user.md +│ ├─ Form validation test → testing-patterns/forms-validation.md +│ └─ Drag and drop test → testing-patterns/drag-drop.md +│ +├─ Testing specific features? +│ ├─ File upload/download → testing-patterns/file-operations.md, testing-patterns/file-upload-download.md +│ ├─ Date/time dependent → advanced/clock-mocking.md +│ ├─ WebSocket/real-time → browser-apis/websockets.md +│ ├─ Geolocation/permissions → browser-apis/browser-apis.md +│ ├─ OAuth/SSO mocking → advanced/third-party.md, advanced/multi-context.md +│ ├─ Payments/email/SMS → advanced/third-party.md +│ ├─ iFrames → browser-apis/iframes.md +│ ├─ Canvas/WebGL/charts → testing-patterns/canvas-webgl.md +│ ├─ Service workers/PWA → browser-apis/service-workers.md +│ ├─ i18n/localization → testing-patterns/i18n.md +│ ├─ Security (XSS, CSRF) → testing-patterns/security-testing.md +│ └─ Performance/Web Vitals → testing-patterns/performance-testing.md +│ +├─ Architecture decisions? +│ ├─ POM vs fixtures → architecture/pom-vs-fixtures.md +│ ├─ Test type selection → architecture/test-architecture.md +│ ├─ Mock vs real services → architecture/when-to-mock.md +│ └─ Test suite structure → core/test-suite-structure.md +│ +├─ Framework-specific testing? +│ ├─ React app → frameworks/react.md +│ └─ Next.js app → frameworks/nextjs.md +│ +├─ Authentication testing? +│ ├─ Basic auth patterns → advanced/authentication.md +│ └─ Complex flows (MFA, reset) → advanced/authentication-flows.md +│ +├─ Test is failing/flaky? +│ ├─ Flaky test investigation → debugging/flaky-tests.md +│ ├─ Element not found → core/locators.md, debugging/debugging.md +│ ├─ Timeout issues → core/assertions-waiting.md, debugging/debugging.md +│ ├─ Race conditions → debugging/flaky-tests.md, debugging/debugging.md +│ ├─ Flaky only with multiple workers → debugging/flaky-tests.md, infrastructure-ci-cd/performance.md +│ ├─ State leak / isolation → debugging/flaky-tests.md, core/fixtures-hooks.md +│ ├─ Console/JS errors → debugging/console-errors.md, debugging/debugging.md +│ └─ General debugging → debugging/debugging.md +│ +├─ Testing error scenarios? +│ ├─ Network failures → debugging/error-testing.md, advanced/network-advanced.md +│ ├─ Offline (unexpected) → debugging/error-testing.md +│ ├─ Offline-first/PWA → browser-apis/service-workers.md +│ ├─ Error boundaries → debugging/error-testing.md +│ └─ Form validation → testing-patterns/forms-validation.md, debugging/error-testing.md +│ +├─ Refactoring existing code? +│ ├─ Implementing POM → core/page-object-model.md +│ ├─ Improving selectors → core/locators.md +│ ├─ Extracting fixtures → core/fixtures-hooks.md +│ ├─ Creating data factories → core/test-data.md +│ └─ Configuration setup → core/configuration.md +│ +├─ Setting up infrastructure? +│ ├─ CI/CD → infrastructure-ci-cd/ci-cd.md +│ ├─ GitHub Actions → infrastructure-ci-cd/github-actions.md +│ ├─ GitLab CI → infrastructure-ci-cd/gitlab.md +│ ├─ Other CI providers → infrastructure-ci-cd/other-providers.md +│ ├─ Docker/containers → infrastructure-ci-cd/docker.md +│ ├─ Sharding/parallel → infrastructure-ci-cd/parallel-sharding.md +│ ├─ Reporting/artifacts → infrastructure-ci-cd/reporting.md +│ ├─ Global setup/teardown → core/global-setup.md +│ ├─ Project dependencies → core/projects-dependencies.md +│ ├─ Test performance → infrastructure-ci-cd/performance.md +│ ├─ Test coverage → infrastructure-ci-cd/test-coverage.md +│ └─ Project config → core/configuration.md, core/projects-dependencies.md +│ +├─ Organizing tests? +│ ├─ Skip/fixme/slow tests → core/annotations.md +│ ├─ Test tags (@smoke, @fast) → core/test-tags.md +│ ├─ Filtering tests (--grep) → core/test-tags.md +│ ├─ Test steps → core/annotations.md +│ └─ Conditional execution → core/annotations.md +│ +└─ Running subset of tests? + ├─ By tag (@smoke, @critical) → core/test-tags.md + ├─ Exclude slow/flaky tests → core/test-tags.md + ├─ PR vs nightly tests → core/test-tags.md, infrastructure-ci-cd/ci-cd.md + └─ Project-specific filtering → core/test-tags.md, core/configuration.md +``` + +## Test Validation Loop + +After writing or modifying tests: + +1. **Run tests**: `npx playwright test --reporter=list` +2. **If tests fail**: + - Review error output and trace (`npx playwright show-trace`) + - Fix locators, waits, or assertions + - Re-run tests +3. **Only proceed when all tests pass** +4. **Run multiple times** for critical tests: `npx playwright test --repeat-each=5` diff --git a/.cursor/skills/playwright-testing/advanced/authentication-flows.md b/.cursor/skills/playwright-testing/advanced/authentication-flows.md new file mode 100644 index 0000000000..24ad08c177 --- /dev/null +++ b/.cursor/skills/playwright-testing/advanced/authentication-flows.md @@ -0,0 +1,360 @@ +# Complex Authentication Flow Patterns + +## Table of Contents + +1. [Email Verification Flows](#email-verification-flows) +2. [Password Reset](#password-reset) +3. [Session Timeout](#session-timeout) +4. [Remember Me Persistence](#remember-me-persistence) +5. [Logout Patterns](#logout-patterns) +6. [Tips](#tips) +7. [Related](#related) + +> **When to use**: Testing email verification, password reset, session timeout/expiration, or remember-me functionality. For basic auth setup (storage state, OAuth mocking, MFA, role-based access), see [authentication.md](authentication.md). + +--- + +## Email Verification Flows + +### Capturing Verification Tokens + +Intercept API responses to capture verification tokens for testing: + +```typescript +test('completes registration with email verification', async ({ page }) => { + let capturedToken = ''; + + await page.route('**/api/auth/register', async (route) => { + const response = await route.fetch(); + const body = await response.json(); + capturedToken = body.verificationToken; + await route.fulfill({ response }); + }); + + await page.goto('/register'); + await page.getByLabel('Name').fill('New User'); + await page.getByLabel('Email').fill('newuser@test.com'); + await page.getByLabel('Password', { exact: true }).fill('SecurePass!'); + await page.getByLabel('Confirm password').fill('SecurePass!'); + await page.getByRole('button', { name: 'Create account' }).click(); + + await expect(page.getByText('Check your inbox')).toBeVisible(); + + expect(capturedToken).toBeTruthy(); + await page.goto(`/verify?token=${capturedToken}`); + + await expect(page.getByText('Email confirmed')).toBeVisible(); +}); +``` + +### Fully Mocked Verification + +```typescript +test('verifies email with mocked endpoints', async ({ page }) => { + const mockToken = 'test-verification-abc123'; + + await page.route('**/api/auth/register', async (route) => { + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify({ message: 'Verification sent', verificationToken: mockToken }), + }); + }); + + await page.route(`**/api/auth/verify?token=${mockToken}`, async (route) => { + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify({ verified: true }), + }); + }); + + await page.goto('/register'); + await page.getByLabel('Email').fill('test@example.com'); + await page.getByLabel('Password', { exact: true }).fill('Password123!'); + await page.getByRole('button', { name: 'Sign up' }).click(); + + await expect(page.getByText('Check your inbox')).toBeVisible(); + + await page.goto(`/verify?token=${mockToken}`); + await expect(page.getByText('Email confirmed')).toBeVisible(); +}); +``` + +--- + +## Password Reset + +### Complete Reset Flow + +```typescript +test('resets password through email link', async ({ page }) => { + let resetToken = ''; + + await page.route('**/api/auth/forgot-password', async (route) => { + const response = await route.fetch(); + const body = await response.json(); + resetToken = body.resetToken; + await route.fulfill({ response }); + }); + + await page.goto('/forgot-password'); + await page.getByLabel('Email').fill('user@test.com'); + await page.getByRole('button', { name: 'Send link' }).click(); + + await expect(page.getByText('Reset email sent')).toBeVisible(); + + expect(resetToken).toBeTruthy(); + await page.goto(`/reset-password?token=${resetToken}`); + + await page.getByLabel('New password', { exact: true }).fill('NewPassword456!'); + await page.getByLabel('Confirm password').fill('NewPassword456!'); + await page.getByRole('button', { name: 'Update password' }).click(); + + await expect(page.getByText('Password updated')).toBeVisible(); +}); +``` + +### Expired Token Handling + +```typescript +test('shows error for expired reset token', async ({ page }) => { + await page.goto('/reset-password?token=expired-token'); + + await page.getByLabel('New password', { exact: true }).fill('NewPass!'); + await page.getByLabel('Confirm password').fill('NewPass!'); + await page.getByRole('button', { name: 'Update password' }).click(); + + await expect(page.getByRole('alert')).toContainText(/expired|invalid/i); +}); +``` + +### Password Strength Validation + +```typescript +test('enforces password requirements on reset', async ({ page }) => { + await page.goto('/reset-password?token=valid-token'); + + await page.getByLabel('New password', { exact: true }).fill('weak'); + await page.getByLabel('Confirm password').fill('weak'); + await page.getByRole('button', { name: 'Update password' }).click(); + + await expect(page.getByText(/at least 8 characters/i)).toBeVisible(); +}); +``` + +--- + +## Session Timeout + +### Detecting Expired Sessions + +```typescript +test('redirects to signin after session expires', async ({ page, context }) => { + await page.goto('/signin'); + await page.getByLabel('Email').fill('user@test.com'); + await page.getByLabel('Password').fill('Password!'); + await page.getByRole('button', { name: 'Sign in' }).click(); + await expect(page).toHaveURL('/home'); + + const cookies = await context.cookies(); + const sessionCookie = cookies.find((c) => c.name.includes('session')); + + if (sessionCookie) { + await context.clearCookies({ name: sessionCookie.name }); + } + + await page.goto('/profile'); + await expect(page).toHaveURL(/\/signin/); + await expect(page.getByText(/session.*expired|sign in again/i)).toBeVisible(); +}); +``` + +### Session Extension Warning + +```typescript +test('shows warning before session expires', async ({ page }) => { + await page.route('**/api/auth/session', async (route) => { + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify({ valid: true, expiresIn: 60 }), + }); + }); + + await page.goto('/home'); + + await expect(page.getByText(/session.*expir/i)).toBeVisible({ timeout: 10000 }); + await expect(page.getByRole('button', { name: /extend|stay signed in/i })).toBeVisible(); +}); +``` + +### Session Extension Action + +```typescript +test('extends session when user clicks extend', async ({ page }) => { + let sessionExtended = false; + + await page.route('**/api/auth/session', async (route) => { + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify({ valid: true, expiresIn: 60 }), + }); + }); + + await page.route('**/api/auth/refresh', async (route) => { + sessionExtended = true; + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify({ valid: true, expiresIn: 3600 }), + }); + }); + + await page.goto('/home'); + + await expect(page.getByRole('button', { name: /extend|stay signed in/i })).toBeVisible({ + timeout: 10000, + }); + await page.getByRole('button', { name: /extend|stay signed in/i }).click(); + + expect(sessionExtended).toBe(true); + await expect(page.getByText(/session.*expir/i)).not.toBeVisible(); +}); +``` + +--- + +## Remember Me Persistence + +### Persistent Session + +```typescript +test('persists session with remember me enabled', async ({ browser }) => { + const ctx1 = await browser.newContext(); + const page1 = await ctx1.newPage(); + + await page1.goto('/signin'); + await page1.getByLabel('Email').fill('user@test.com'); + await page1.getByLabel('Password').fill('Password!'); + await page1.getByLabel('Keep me signed in').check(); + await page1.getByRole('button', { name: 'Sign in' }).click(); + + await expect(page1).toHaveURL('/home'); + + const state = await ctx1.storageState(); + await ctx1.close(); + + const ctx2 = await browser.newContext({ storageState: state }); + const page2 = await ctx2.newPage(); + + await page2.goto('/home'); + await expect(page2).toHaveURL('/home'); + await expect(page2.getByText('Welcome')).toBeVisible(); + + await ctx2.close(); +}); +``` + +### Session-Only Login + +```typescript +test('session-only login does not persist across browser restarts', async ({ browser }) => { + const ctx1 = await browser.newContext(); + const page1 = await ctx1.newPage(); + + await page1.goto('/signin'); + await page1.getByLabel('Email').fill('user@test.com'); + await page1.getByLabel('Password').fill('Password!'); + // Leave "Remember me" unchecked + await expect(page1.getByLabel('Keep me signed in')).not.toBeChecked(); + await page1.getByRole('button', { name: 'Sign in' }).click(); + + await expect(page1).toHaveURL('/home'); + + // Only keep persistent cookies (filter out session cookies) + const cookies = await ctx1.cookies(); + await ctx1.close(); + + const persistentCookies = cookies.filter((c) => c.expires > 0); + const ctx2 = await browser.newContext(); + await ctx2.addCookies(persistentCookies); + const page2 = await ctx2.newPage(); + + await page2.goto('/home'); + + // Should redirect to login since session was not persisted + await expect(page2).toHaveURL(/\/signin/); + + await ctx2.close(); +}); +``` + +--- + +## Logout Patterns + +### Standard Logout with Session Cleanup + +```typescript +test.use({ storageState: '.auth/user.json' }); + +test('logs out and clears session', async ({ page, context }) => { + await page.goto('/home'); + + await page.getByRole('button', { name: /account|menu/i }).click(); + await page.getByRole('menuitem', { name: 'Sign out' }).click(); + + await expect(page).toHaveURL('/signin'); + + const cookies = await context.cookies(); + const sessionCookies = cookies.filter((c) => c.name.includes('session') || c.name.includes('token')); + expect(sessionCookies).toHaveLength(0); + + await page.goto('/home'); + await expect(page).toHaveURL(/\/signin/); +}); +``` + +### Logout from All Devices + +```typescript +test('logs out from all devices', async ({ page }) => { + let logoutAllCalled = false; + + await page.route('**/api/auth/logout-all', async (route) => { + logoutAllCalled = true; + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify({ message: 'Logged out everywhere' }), + }); + }); + + await page.goto('/settings/security'); + + await page.getByRole('button', { name: 'Sign out everywhere' }).click(); + await page.getByRole('dialog').getByRole('button', { name: 'Confirm' }).click(); + + expect(logoutAllCalled).toBe(true); + await expect(page).toHaveURL(/\/signin/); +}); +``` + +--- + +## Tips + +1. **Configure shorter session timeouts in test environments** — Enables testing timeout behavior without slow tests +2. **Test token expiration edge cases** — Expired tokens, invalid tokens, already-used tokens +3. **Verify cleanup on logout** — Check both cookies and localStorage are cleared +4. **Test the full flow end-to-end** — Password reset should verify login with new password works + +--- + +## Related + +- [authentication.md](authentication.md) — Storage state, OAuth mocking, MFA, role-based access, API login +- [fixtures-hooks.md](../core/fixtures-hooks.md) — Creating auth fixtures +- [third-party.md](./third-party.md) — Mocking external auth providers diff --git a/.cursor/skills/playwright-testing/advanced/authentication.md b/.cursor/skills/playwright-testing/advanced/authentication.md new file mode 100644 index 0000000000..02c2dd7b27 --- /dev/null +++ b/.cursor/skills/playwright-testing/advanced/authentication.md @@ -0,0 +1,871 @@ +# Authentication Testing + +## Table of Contents + +1. [Quick Reference](#quick-reference) +2. [Patterns](#patterns) +3. [Decision Guide](#decision-guide) +4. [Anti-Patterns](#anti-patterns) +5. [Troubleshooting](#troubleshooting) +6. [Related](#related) + +> **When to use**: Apps with login, session management, or protected routes. Authentication is the most common source of slow test suites. + +## Quick Reference + +```typescript +// Storage state reuse — the #1 pattern for fast auth +await page.goto("/login"); +await page.getByLabel("Username").fill("testuser@example.com"); +await page.getByLabel("Password").fill("secretPass123"); +await page.getByRole("button", { name: "Log in" }).click(); +await page.context().storageState({ path: ".auth/session.json" }); + +// Reuse in config — every test starts authenticated +{ + use: { + storageState: ".auth/session.json" + } +} + +// API login — skip the UI entirely +const context = await browser.newContext(); +const response = await context.request.post("/api/auth/login", { + data: { email: "testuser@example.com", password: "secretPass123" }, +}); +await context.storageState({ path: ".auth/session.json" }); +``` + +## Patterns + +### Storage State Reuse + +**Use when**: You need authenticated tests and want to avoid logging in before every test. +**Avoid when**: Tests require completely fresh sessions, or you are testing the login flow itself. + +`storageState` serializes cookies and localStorage to a JSON file. Load it in any browser context to start authenticated instantly. + +```typescript +// scripts/generate-auth.ts — run once to generate the state file +import { chromium } from "@playwright/test"; + +async function generateAuthState() { + const browser = await chromium.launch(); + const context = await browser.newContext(); + const page = await context.newPage(); + + await page.goto("http://localhost:4000/login"); + await page.getByLabel("Username").fill("testuser@example.com"); + await page.getByLabel("Password").fill("secretPass123"); + await page.getByRole("button", { name: "Log in" }).click(); + await page.waitForURL("/home"); + + await context.storageState({ path: ".auth/session.json" }); + await browser.close(); +} + +generateAuthState(); +``` + +```typescript +// playwright.config.ts — load saved state for all tests +import { defineConfig } from "@playwright/test"; + +export default defineConfig({ + use: { + baseURL: "http://localhost:4000", + storageState: ".auth/session.json", + }, +}); +``` + +```typescript +// tests/home.spec.ts — test starts already logged in +import { test, expect } from "@playwright/test"; + +test("authenticated user sees home page", async ({ page }) => { + await page.goto("/home"); + await expect(page.getByRole("heading", { name: "Home" })).toBeVisible(); +}); +``` + +### Global Setup Authentication + +**Use when**: You want to authenticate once before the entire test suite runs. +**Avoid when**: Different tests need different users, or your tokens expire faster than your suite runs. + +```typescript +// global-setup.ts +import { chromium, type FullConfig } from "@playwright/test"; + +async function globalSetup(config: FullConfig) { + const { baseURL } = config.projects[0].use; + const browser = await chromium.launch(); + const context = await browser.newContext(); + const page = await context.newPage(); + + await page.goto(`${baseURL}/login`); + await page.getByLabel("Username").fill(process.env.TEST_USER_EMAIL!); + await page.getByLabel("Password").fill(process.env.TEST_USER_PASSWORD!); + await page.getByRole("button", { name: "Log in" }).click(); + await page.waitForURL("**/home"); + + await context.storageState({ path: ".auth/session.json" }); + await browser.close(); +} + +export default globalSetup; +``` + +```typescript +// playwright.config.ts +import { defineConfig } from "@playwright/test"; + +export default defineConfig({ + globalSetup: require.resolve("./global-setup"), + use: { + baseURL: "http://localhost:4000", + storageState: ".auth/session.json", + }, +}); +``` + +Add `.auth/` to `.gitignore`. Auth state files contain session tokens and should never be committed. + +### Per-Worker Authentication + +**Use when**: Each parallel worker needs its own authenticated session to avoid race conditions for tests that modify server-side state. +**Avoid when**: Tests are read-only and a modifying shared session is safe, you can use a single shared account. + +> **Sharded runs**: `parallelIndex` resets per shard, so different shards can have workers with the same index. To avoid collisions, include the shard identifier in the username (e.g., `worker-${SHARD_INDEX}-${parallelIndex}@example.com`) by passing a `SHARD_INDEX` environment variable from your CI matrix. + +```typescript +// fixtures/auth.ts +import { test as base, type BrowserContext } from "@playwright/test"; + +type AuthFixtures = { + authenticatedContext: BrowserContext; +}; + +export const test = base.extend<{}, AuthFixtures>({ + authenticatedContext: [ + async ({ browser }, use) => { + const context = await browser.newContext(); + const page = await context.newPage(); + + await page.goto("/login"); + await page + .getByLabel("Username") + .fill(`worker-${test.info().parallelIndex}@example.com`); + await page.getByLabel("Password").fill("secretPass123"); + await page.getByRole("button", { name: "Log in" }).click(); + await page.waitForURL("/home"); + await page.close(); + + await use(context); + await context.close(); + }, + { scope: "worker" }, + ], +}); + +export { expect } from "@playwright/test"; +``` + +```typescript +// tests/settings.spec.ts +import { test, expect } from "../fixtures/auth"; + +test("update display name", async ({ authenticatedContext }) => { + const page = await authenticatedContext.newPage(); + await page.goto("/settings/profile"); + await page.getByLabel("Display name").fill("Updated Name"); + await page.getByRole("button", { name: "Save" }).click(); + await expect(page.getByText("Profile saved")).toBeVisible(); +}); +``` + +### Multiple Roles + +**Use when**: Your app has role-based access control and you need to test different permission levels. +**Avoid when**: Your app has a single user role. + +```typescript +// global-setup.ts — authenticate all roles +import { chromium, type FullConfig } from "@playwright/test"; + +const accounts = [ + { + role: "admin", + email: "admin@example.com", + password: process.env.ADMIN_PASSWORD!, + }, + { + role: "member", + email: "member@example.com", + password: process.env.MEMBER_PASSWORD!, + }, + { + role: "guest", + email: "guest@example.com", + password: process.env.GUEST_PASSWORD!, + }, +]; + +async function globalSetup(config: FullConfig) { + const { baseURL } = config.projects[0].use; + + for (const { role, email, password } of accounts) { + const browser = await chromium.launch(); + const context = await browser.newContext(); + const page = await context.newPage(); + + await page.goto(`${baseURL}/login`); + await page.getByLabel("Username").fill(email); + await page.getByLabel("Password").fill(password); + await page.getByRole("button", { name: "Log in" }).click(); + await page.waitForURL("**/home"); + + await context.storageState({ path: `.auth/${role}.json` }); + await browser.close(); + } +} + +export default globalSetup; +``` + +```typescript +// playwright.config.ts — one project per role +import { defineConfig } from "@playwright/test"; + +export default defineConfig({ + globalSetup: require.resolve("./global-setup"), + projects: [ + { + name: "admin", + use: { storageState: ".auth/admin.json" }, + testMatch: "**/*.admin.spec.ts", + }, + { + name: "member", + use: { storageState: ".auth/member.json" }, + testMatch: "**/*.member.spec.ts", + }, + { + name: "guest", + use: { storageState: ".auth/guest.json" }, + testMatch: "**/*.guest.spec.ts", + }, + { + name: "anonymous", + use: { storageState: { cookies: [], origins: [] } }, + testMatch: "**/*.anon.spec.ts", + }, + ], +}); +``` + +```typescript +// tests/admin-panel.admin.spec.ts +import { test, expect } from "@playwright/test"; + +test("admin can access user management", async ({ page }) => { + await page.goto("/admin/users"); + await expect( + page.getByRole("heading", { name: "User Management" }) + ).toBeVisible(); + await expect(page.getByRole("button", { name: "Remove user" })).toBeEnabled(); +}); +``` + +```typescript +// tests/admin-panel.guest.spec.ts +import { test, expect } from "@playwright/test"; + +test("guest cannot access admin panel", async ({ page }) => { + await page.goto("/admin/users"); + await expect(page.getByText("Access denied")).toBeVisible(); +}); +``` + +**Alternative**: Use a fixture that accepts a role parameter when you need role switching within a single spec file. + +```typescript +// fixtures/auth.ts — role-based fixture +import { test as base, type Page } from "@playwright/test"; +import fs from "fs"; + +type RoleFixtures = { + loginAs: (role: "admin" | "member" | "guest") => Promise; +}; + +export const test = base.extend({ + loginAs: async ({ browser }, use) => { + const pages: Page[] = []; + + await use(async (role) => { + const statePath = `.auth/${role}.json`; + if (!fs.existsSync(statePath)) { + throw new Error( + `Auth state for role "${role}" not found at ${statePath}` + ); + } + const context = await browser.newContext({ storageState: statePath }); + const page = await context.newPage(); + pages.push(page); + return page; + }); + + for (const page of pages) { + await page.context().close(); + } + }, +}); + +export { expect } from "@playwright/test"; +``` + +```typescript +// tests/role-comparison.spec.ts +import { test, expect } from "../fixtures/auth"; + +test("admin sees remove button, guest does not", async ({ loginAs }) => { + const adminPage = await loginAs("admin"); + await adminPage.goto("/admin/users"); + await expect( + adminPage.getByRole("button", { name: "Remove user" }) + ).toBeVisible(); + + const guestPage = await loginAs("guest"); + await guestPage.goto("/admin/users"); + await expect(guestPage.getByText("Access denied")).toBeVisible(); +}); +``` + +### OAuth/SSO Mocking + +**Use when**: Your app authenticates via a third-party OAuth provider and you cannot hit the real provider in tests. +**Avoid when**: You have a dedicated test tenant on the OAuth provider. + +A typical OAuth flow works like this: + +1. User clicks "Sign in with Provider" → browser navigates to `https://accounts.provider.com/authorize?...` +2. User authenticates on the provider's page → provider redirects back to your app's **callback route** (e.g. `http://localhost:4000/auth/callback?code=ABC&state=XYZ`) +3. Your backend exchanges the `code` for an access token, creates a session, and redirects the user to a logged-in page + +In tests you can short-circuit step 2 with `page.route()`: intercept the outbound request to the provider and respond with a `302` redirect straight to your callback route, supplying a mock `code` and `state`. Your backend still executes its normal callback handler — the only part that's mocked is the provider's authorization page. + +For cases where you want to skip the browser redirect entirely, a second approach calls a **test-only API endpoint** that creates the session server-side and returns the session cookie directly. + +```typescript +// tests/oauth-login.spec.ts — mock the callback route +import { test, expect } from "@playwright/test"; + +test("login via mocked OAuth flow", async ({ page }) => { + await page.route("https://accounts.provider.com/**", async (route) => { + const callbackUrl = new URL("http://localhost:4000/auth/callback"); + callbackUrl.searchParams.set("code", "mock-auth-code-xyz"); + callbackUrl.searchParams.set("state", "expected-state-value"); + await route.fulfill({ + status: 302, + headers: { location: callbackUrl.toString() }, + }); + }); + + await page.goto("/login"); + await page.getByRole("button", { name: "Sign in with Provider" }).click(); + + await page.waitForURL("/home"); + await expect(page.getByRole("heading", { name: "Home" })).toBeVisible(); +}); +``` + +```typescript +// tests/oauth-login.spec.ts — API-based session injection +import { test, expect } from "@playwright/test"; + +test("bypass OAuth entirely via API session injection", async ({ + page, +}) => { + // Call a test-only endpoint that creates a session without OAuth + const response = await page.request.post("/api/test/create-session", { + data: { + email: "oauth-user@example.com", + provider: "provider", + role: "member", + }, + }); + expect(response.ok()).toBeTruthy(); + + await page.context().storageState({ path: ".auth/oauth-user.json" }); + await page.goto("/home"); + await expect(page.getByRole("heading", { name: "Home" })).toBeVisible(); +}); +``` + +**Backend requirement**: Your backend must expose a test-only session creation endpoint (guarded by `NODE_ENV=test`) or accept a known test OAuth code. + +### MFA Handling + +**Use when**: Your app requires two-factor authentication (TOTP, SMS, email codes). +**Avoid when**: MFA is optional and you can disable it for test accounts. + +**Strategy 1**: Generate real TOTP codes from a shared secret. + +```typescript +// helpers/totp.ts +import * as OTPAuth from "otpauth"; + +export function generateTOTP(secret: string): string { + const totp = new OTPAuth.TOTP({ + secret: OTPAuth.Secret.fromBase32(secret), + digits: 6, + period: 30, + algorithm: "SHA1", + }); + return totp.generate(); +} +``` + +```typescript +// tests/mfa-login.spec.ts +import { test, expect } from "@playwright/test"; +import { generateTOTP } from "../helpers/totp"; + +test("login with TOTP two-factor auth", async ({ page }) => { + await page.goto("/login"); + await page.getByLabel("Username").fill("mfa-user@example.com"); + await page.getByLabel("Password").fill("secretPass123"); + await page.getByRole("button", { name: "Log in" }).click(); + + await expect(page.getByText("Enter your authentication code")).toBeVisible(); + + const code = generateTOTP(process.env.MFA_TOTP_SECRET!); + await page.getByLabel("Authentication code").fill(code); + await page.getByRole("button", { name: "Verify" }).click(); + + await page.waitForURL("/home"); + await expect(page.getByRole("heading", { name: "Home" })).toBeVisible(); +}); +``` + +**Strategy 2**: Mock MFA at the backend level. Have your backend accept a known bypass code (e.g., `000000`) when `NODE_ENV=test`. + +**Strategy 3**: Disable MFA for test accounts at the infrastructure level. + +### Session Refresh + +**Use when**: Your tokens expire during long test runs. +**Avoid when**: Your test suite runs quickly and tokens outlast the entire run. + +```typescript +// fixtures/auth-with-refresh.ts +import { test as base, type BrowserContext } from "@playwright/test"; +import fs from "fs"; + +type AuthFixtures = { + authenticatedPage: import("@playwright/test").Page; +}; + +export const test = base.extend({ + authenticatedPage: async ({ browser }, use) => { + const statePath = ".auth/session.json"; + + let context: BrowserContext; + if (fs.existsSync(statePath)) { + context = await browser.newContext({ storageState: statePath }); + const page = await context.newPage(); + + const response = await page.request.get("/api/auth/me"); + if (response.ok()) { + await use(page); + await context.close(); + return; + } + await context.close(); + } + + context = await browser.newContext(); + const page = await context.newPage(); + await page.goto("/login"); + await page.getByLabel("Username").fill(process.env.TEST_USER_EMAIL!); + await page.getByLabel("Password").fill(process.env.TEST_USER_PASSWORD!); + await page.getByRole("button", { name: "Log in" }).click(); + await page.waitForURL("/home"); + + await context.storageState({ path: statePath }); + + await use(page); + await context.close(); + }, +}); + +export { expect } from "@playwright/test"; +``` + +### Login Page Object + +**Use when**: Multiple test files need to log in and you want consistent, maintainable login logic. +**Avoid when**: You use `storageState` everywhere and never navigate through the login UI in tests. + +```typescript +// page-objects/LoginPage.ts +import { type Page, type Locator, expect } from "@playwright/test"; + +export class LoginPage { + readonly page: Page; + readonly usernameInput: Locator; + readonly passwordInput: Locator; + readonly loginButton: Locator; + readonly errorMessage: Locator; + readonly forgotPasswordLink: Locator; + + constructor(page: Page) { + this.page = page; + this.usernameInput = page.getByLabel("Username"); + this.passwordInput = page.getByLabel("Password"); + this.loginButton = page.getByRole("button", { name: "Log in" }); + this.errorMessage = page.getByRole("alert"); + this.forgotPasswordLink = page.getByRole("link", { + name: "Forgot password", + }); + } + + async goto() { + await this.page.goto("/login"); + await expect(this.loginButton).toBeVisible(); + } + + async login(username: string, password: string) { + await this.usernameInput.fill(username); + await this.passwordInput.fill(password); + await this.loginButton.click(); + } + + async loginAndWaitForHome(username: string, password: string) { + await this.login(username, password); + await this.page.waitForURL("/home"); + } + + async expectError(message: string | RegExp) { + await expect(this.errorMessage).toContainText(message); + } + + async expectFieldError(field: "username" | "password", message: string) { + const input = + field === "username" ? this.usernameInput : this.passwordInput; + await expect(input).toHaveAttribute("aria-invalid", "true"); + const errorId = await input.getAttribute("aria-describedby"); + if (errorId) { + await expect(this.page.locator(`#${errorId}`)).toContainText(message); + } + } +} +``` + +```typescript +// tests/login.spec.ts +import { test, expect } from "@playwright/test"; +import { LoginPage } from "../page-objects/LoginPage"; + +test.use({ storageState: { cookies: [], origins: [] } }); + +test.describe("login page", () => { + let loginPage: LoginPage; + + test.beforeEach(async ({ page }) => { + loginPage = new LoginPage(page); + await loginPage.goto(); + }); + + test("successful login redirects to home", async ({ page }) => { + await loginPage.loginAndWaitForHome( + "testuser@example.com", + "secretPass123" + ); + await expect(page.getByRole("heading", { name: "Home" })).toBeVisible(); + }); + + test("wrong password shows error", async () => { + await loginPage.login("testuser@example.com", "wrong-password"); + await loginPage.expectError("Invalid username or password"); + }); + + test("empty fields show validation errors", async () => { + await loginPage.loginButton.click(); + await loginPage.expectFieldError("username", "Username is required"); + }); + + test("forgot password link navigates correctly", async ({ page }) => { + await loginPage.forgotPasswordLink.click(); + await page.waitForURL("/forgot-password"); + await expect( + page.getByRole("heading", { name: "Reset password" }) + ).toBeVisible(); + }); +}); +``` + +### API-Based Login + +**Use when**: You want the fastest possible authentication without any browser interaction. +**Avoid when**: You are specifically testing the login UI. + +API login is typically 5-10x faster than UI login. + +```typescript +// global-setup.ts — API-based login (fastest) +import { request, type FullConfig } from "@playwright/test"; + +async function globalSetup(config: FullConfig) { + const { baseURL } = config.projects[0].use; + + const requestContext = await request.newContext({ baseURL }); + + const response = await requestContext.post("/api/auth/login", { + data: { + email: process.env.TEST_USER_EMAIL!, + password: process.env.TEST_USER_PASSWORD!, + }, + }); + + if (!response.ok()) { + throw new Error( + `API login failed: ${response.status()} ${await response.text()}` + ); + } + + await requestContext.storageState({ path: ".auth/session.json" }); + await requestContext.dispose(); +} + +export default globalSetup; +``` + +```typescript +// fixtures/api-auth.ts — fixture version for per-test authentication +import { test as base } from "@playwright/test"; + +export const test = base.extend({ + authenticatedPage: async ({ browser, playwright }, use) => { + const apiContext = await playwright.request.newContext({ + baseURL: "http://localhost:4000", + }); + + await apiContext.post("/api/auth/login", { + data: { + email: "testuser@example.com", + password: "secretPass123", + }, + }); + + const state = await apiContext.storageState(); + const context = await browser.newContext({ storageState: state }); + const page = await context.newPage(); + + await use(page); + + await context.close(); + await apiContext.dispose(); + }, +}); + +export { expect } from "@playwright/test"; +``` + +### Unauthenticated Tests + +**Use when**: Testing the login page, signup flow, password reset, public pages, or redirect behavior for unauthenticated users. +**Avoid when**: The test requires a logged-in user. + +When your config sets a default `storageState`, you must explicitly clear it for unauthenticated tests. + +```typescript +// tests/public-pages.spec.ts +import { test, expect } from "@playwright/test"; + +test.use({ storageState: { cookies: [], origins: [] } }); + +test.describe("unauthenticated access", () => { + test("homepage is accessible without login", async ({ page }) => { + await page.goto("/"); + await expect(page.getByRole("heading", { name: "Welcome" })).toBeVisible(); + await expect(page.getByRole("link", { name: "Log in" })).toBeVisible(); + }); + + test("protected route redirects to login", async ({ page }) => { + await page.goto("/home"); + await page.waitForURL("**/login**"); + expect(page.url()).toContain("redirect=%2Fhome"); + }); + + test("expired session shows re-login prompt", async ({ page, context }) => { + await page.goto("/home"); + await context.clearCookies(); + + await page.goto("/settings"); + await page.waitForURL("**/login**"); + await expect(page.getByText("Your session has expired")).toBeVisible(); + }); + + test("signup flow creates account", async ({ page }) => { + await page.goto("/signup"); + await page.getByLabel("Name").fill("New User"); + await page.getByLabel("Email").fill(`test-${Date.now()}@example.com`); + await page.getByLabel("Password", { exact: true }).fill("secretPass123"); + await page.getByLabel("Confirm password").fill("secretPass123"); + await page.getByRole("button", { name: "Create account" }).click(); + + await page.waitForURL("/onboarding"); + await expect(page.getByText("Welcome, New User")).toBeVisible(); + }); +}); +``` + +## Decision Guide + +| Scenario | Approach | Speed | Isolation | When to Choose | +| -------------------------------- | ------------------------------ | -------- | -------------- | -------------------------------------------------------------- | +| Most tests need auth | Global setup + `storageState` | Fastest | Shared session | Default for nearly every project | +| Tests modify user state | Per-worker fixture | Fast | Per worker | Tests update profile, change settings, or mutate data | +| Multiple user roles | Per-project `storageState` | Fastest | Per role | App has admin/member/guest roles | +| Testing the login page | No `storageState` | N/A | Full | Use `test.use({ storageState: { cookies: [], origins: [] } })` | +| OAuth/SSO provider | Mock the callback | Fast | Per test | Never hit real OAuth providers in CI | +| MFA is required | TOTP generation or bypass | Moderate | Per test | Generate real TOTP codes or use a test-mode bypass | +| Token expires mid-suite | Session refresh fixture | Fast | Per check | Fixture validates the session before use | +| Single test needs different user | `loginAs(role)` fixture | Moderate | Per call | Rare: prefer per-project roles | +| API-first app (no login UI) | API login via `request.post()` | Fastest | Per test | No browser needed for auth | + +### UI Login vs API Login vs Storage State + +```text +Need to test the login page itself? +├── Yes → UI login with LoginPage POM, no storageState +└── No → Do you have a login API endpoint? + ├── Yes → API login in global setup, save storageState (fastest) + └── No → UI login in global setup, save storageState + └── Tokens expire quickly? + ├── Yes → Add session refresh fixture + └── No → Standard storageState reuse is fine +``` + +## Anti-Patterns + +| Don't Do This | Problem | Do This Instead | +| ------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------- | +| Log in via UI before every test | Adds 2-5 seconds per test | Use `storageState` to skip login entirely | +| Share a single auth state file across parallel workers that mutate state | Race conditions | Use per-worker fixtures with `{ scope: 'worker' }` | +| Hardcode credentials in test files | Security risk | Use environment variables and `.env` files | +| Ignore token expiration | Tests fail intermittently with 401 errors | Add a session validity check in your auth fixture | +| Hit real OAuth providers in CI | Flaky: rate limits, CAPTCHA, network issues | Mock the OAuth callback or use API session injection | +| Use `page.waitForTimeout(2000)` after login | Arbitrary delay | `await page.waitForURL('/home')` or `await expect(heading).toBeVisible()` | +| Store `.auth/*.json` files in git | Tokens in version control | Add `.auth/` to `.gitignore` | +| Create one "god" test account with all permissions | Cannot test role-based access control | Create separate accounts per role | +| Use `browser.newContext()` without `storageState` for authenticated tests | Every context starts unauthenticated | Pass `storageState` when creating the context | +| Test MFA by disabling it everywhere | You never test the MFA flow | Use TOTP generation for at least one test | + +## Troubleshooting + +### Global setup fails with "Target page, context or browser has been closed" + +**Cause**: The login page redirected unexpectedly, or the browser closed before `storageState()` was called. + +**Fix**: + +- Add `await page.waitForURL()` after the login action +- Check that `baseURL` in your config matches the actual server URL and protocol +- Add error handling to global setup: + +```typescript +const response = await page.waitForResponse("**/api/auth/**"); +if (!response.ok()) { + throw new Error( + `Login failed in global setup: ${response.status()} ${await response.text()}` + ); +} +``` + +### Tests fail with 401 Unauthorized after running for a while + +**Cause**: The session token saved in `storageState` has expired. + +**Fix**: + +- Use the session refresh fixture pattern +- Increase token expiry in test environment configuration +- Switch to API-based login in a worker-scoped fixture + +### `storageState` file is empty or contains no cookies + +**Cause**: `storageState()` was called before the login response set cookies. + +**Fix**: + +- Wait for the post-login page to load: `await page.waitForURL('/home')` +- Verify cookies exist before saving: + +```typescript +const cookies = await context.cookies(); +if (cookies.length === 0) { + throw new Error("No cookies found after login"); +} +await context.storageState({ path: ".auth/session.json" }); +``` + +### Different browsers get different cookies + +**Cause**: Some auth flows set cookies with `SameSite=Strict` or use browser-specific cookie behavior. + +**Fix**: + +- Generate separate auth state files per browser project +- Check if your auth uses `SameSite=None; Secure` cookies that require HTTPS: + +```typescript +projects: [ + { + name: 'chromium', + use: { ...devices['Desktop Chrome'], storageState: '.auth/chromium-session.json' }, + }, + { + name: 'firefox', + use: { ...devices['Desktop Firefox'], storageState: '.auth/firefox-session.json' }, + }, +], +``` + +### Parallel tests interfere with each other's sessions + +**Cause**: Multiple workers share the same test account and one worker's actions affect others. + +**Fix**: + +- Use per-worker test accounts: `worker-${test.info().parallelIndex}@example.com` +- Use the per-worker authentication fixture pattern +- Make tests idempotent + +### OAuth mock does not work — still redirects to real provider + +**Cause**: `page.route()` was registered after the navigation that triggers the OAuth redirect. + +**Fix**: + +- Register route handlers before any navigation: call `page.route()` before `page.goto()` +- Log the actual redirect URL to verify the pattern: + +```typescript +page.on("request", (req) => { + if (req.url().includes("oauth") || req.url().includes("accounts.provider")) { + console.log("OAuth request:", req.url()); + } +}); +``` + +## Related + +- [fixtures-hooks.md](../core/fixtures-hooks.md) — custom fixtures for auth setup and teardown +- [configuration.md](../core/configuration.md) — `storageState`, projects, and global setup configuration +- [global-setup.md](../core/global-setup.md) — global setup patterns and project dependencies +- [network-advanced.md](network-advanced.md) — route interception patterns used in OAuth mocking +- [api-testing.md](../testing-patterns/api-testing.md) — API request context used in API-based login +- [flaky-tests.md](../debugging/flaky-tests.md) — diagnosing auth-related flakiness diff --git a/.cursor/skills/playwright-testing/advanced/clock-mocking.md b/.cursor/skills/playwright-testing/advanced/clock-mocking.md new file mode 100644 index 0000000000..073d087055 --- /dev/null +++ b/.cursor/skills/playwright-testing/advanced/clock-mocking.md @@ -0,0 +1,364 @@ +# Date, Time & Clock Mocking + +## Table of Contents + +1. [Clock API Basics](#clock-api-basics) +2. [Fixed Time Testing](#fixed-time-testing) +3. [Time Advancement](#time-advancement) +4. [Timezone Testing](#timezone-testing) +5. [Timer Mocking](#timer-mocking) + +## Clock API Basics + +### Install Clock + +```typescript +test("mock current time", async ({ page }) => { + // Install clock before navigating + await page.clock.install({ time: new Date("2025-01-15T09:00:00") }); + + await page.goto("/dashboard"); + + // Page sees January 15, 2025 as current date + await expect(page.getByText("January 15, 2025")).toBeVisible(); +}); +``` + +### Clock with Fixture + +```typescript +// fixtures/clock.fixture.ts +import { test as base } from "@playwright/test"; + +type ClockFixtures = { + mockTime: (date: Date | string) => Promise; +}; + +export const test = base.extend({ + mockTime: async ({ page }, use) => { + await use(async (date) => { + const time = typeof date === "string" ? new Date(date) : date; + await page.clock.install({ time }); + }); + }, +}); + +// Usage +test("subscription expiry", async ({ page, mockTime }) => { + await mockTime("2025-12-31T23:59:00"); + await page.goto("/subscription"); + + await expect(page.getByText("Expires today")).toBeVisible(); +}); +``` + +## Fixed Time Testing + +### Test Date-Dependent Features + +```typescript +test("show holiday banner in December", async ({ page }) => { + await page.clock.install({ time: new Date("2025-12-20T10:00:00") }); + + await page.goto("/"); + + await expect(page.getByRole("banner", { name: /holiday/i })).toBeVisible(); +}); + +test("no holiday banner in January", async ({ page }) => { + await page.clock.install({ time: new Date("2025-01-15T10:00:00") }); + + await page.goto("/"); + + await expect(page.getByRole("banner", { name: /holiday/i })).toBeHidden(); +}); +``` + +### Test Relative Time Display + +```typescript +test("shows relative time correctly", async ({ page }) => { + // Fix time to control "posted 2 hours ago" text + await page.clock.install({ time: new Date("2025-06-15T14:00:00") }); + + // Mock API to return post with known timestamp + await page.route("**/api/posts/1", (route) => + route.fulfill({ + json: { + id: 1, + title: "Test Post", + createdAt: "2025-06-15T12:00:00Z", // 2 hours before mock time + }, + }), + ); + + await page.goto("/posts/1"); + + await expect(page.getByText("2 hours ago")).toBeVisible(); +}); +``` + +### Test Date Boundaries + +```typescript +test.describe("end of month billing", () => { + test("shows billing on last day of month", async ({ page }) => { + await page.clock.install({ time: new Date("2025-01-31T10:00:00") }); + await page.goto("/billing"); + + await expect(page.getByText("Payment due today")).toBeVisible(); + }); + + test("shows days remaining mid-month", async ({ page }) => { + await page.clock.install({ time: new Date("2025-01-15T10:00:00") }); + await page.goto("/billing"); + + await expect(page.getByText("16 days until payment")).toBeVisible(); + }); +}); +``` + +## Time Advancement + +### Advance Time Manually + +```typescript +test("session timeout warning", async ({ page }) => { + await page.clock.install({ time: new Date("2025-01-15T09:00:00") }); + await page.goto("/dashboard"); + + // Advance 25 minutes (session timeout at 30 min) + await page.clock.fastForward("25:00"); + + await expect(page.getByText("Session expires in 5 minutes")).toBeVisible(); + + // Advance 5 more minutes + await page.clock.fastForward("05:00"); + + await expect(page.getByText("Session expired")).toBeVisible(); +}); +``` + +### Pause and Resume Time + +```typescript +test("countdown timer", async ({ page }) => { + await page.clock.install({ time: new Date("2025-01-15T09:00:00") }); + await page.goto("/sale"); + + // Initial state + await expect(page.getByText("Sale ends in 2:00:00")).toBeVisible(); + + // Advance 1 hour + await page.clock.fastForward("01:00:00"); + + await expect(page.getByText("Sale ends in 1:00:00")).toBeVisible(); + + // Advance past end + await page.clock.fastForward("01:00:01"); + + await expect(page.getByText("Sale ended")).toBeVisible(); +}); +``` + +### Run Pending Timers + +```typescript +test("debounced search", async ({ page }) => { + await page.clock.install({ time: new Date("2025-01-15T09:00:00") }); + await page.goto("/search"); + + await page.getByLabel("Search").fill("playwright"); + + // Search is debounced by 300ms, won't fire yet + await expect(page.getByTestId("search-results")).toBeHidden(); + + // Fast forward past debounce + await page.clock.fastForward(300); + + // Now search should execute + await expect(page.getByTestId("search-results")).toBeVisible(); +}); +``` + +## Timezone Testing + +### Test Different Timezones + +```typescript +test.describe("timezone display", () => { + test("shows correct time in PST", async ({ browser }) => { + const context = await browser.newContext({ + timezoneId: "America/Los_Angeles", + }); + const page = await context.newPage(); + + await page.clock.install({ time: new Date("2025-01-15T17:00:00Z") }); // 5 PM UTC + + await page.goto("/schedule"); + + // Should show 9 AM PST + await expect(page.getByText("9:00 AM")).toBeVisible(); + + await context.close(); + }); + + test("shows correct time in JST", async ({ browser }) => { + const context = await browser.newContext({ + timezoneId: "Asia/Tokyo", + }); + const page = await context.newPage(); + + await page.clock.install({ time: new Date("2025-01-15T17:00:00Z") }); // 5 PM UTC + + await page.goto("/schedule"); + + // Should show 2 AM next day JST + await expect(page.getByText("2:00 AM")).toBeVisible(); + + await context.close(); + }); +}); +``` + +### Timezone Fixture + +```typescript +// fixtures/timezone.fixture.ts +import { test as base } from "@playwright/test"; + +type TimezoneFixtures = { + pageInTimezone: (timezone: string) => Promise; +}; + +export const test = base.extend({ + pageInTimezone: async ({ browser }, use) => { + const pages: Page[] = []; + + await use(async (timezone) => { + const context = await browser.newContext({ timezoneId: timezone }); + const page = await context.newPage(); + pages.push(page); + return page; + }); + + // Cleanup + for (const page of pages) { + await page.context().close(); + } + }, +}); +``` + +## Timer Mocking + +### Mock setInterval + +```typescript +test("auto-refresh data", async ({ page }) => { + await page.clock.install({ time: new Date("2025-01-15T09:00:00") }); + + let apiCalls = 0; + await page.route("**/api/data", (route) => { + apiCalls++; + route.fulfill({ json: { value: apiCalls } }); + }); + + await page.goto("/live-data"); // Sets up 30s refresh interval + + expect(apiCalls).toBe(1); // Initial load + + // Advance 30 seconds + await page.clock.fastForward("00:30"); + expect(apiCalls).toBe(2); // First refresh + + // Advance another 30 seconds + await page.clock.fastForward("00:30"); + expect(apiCalls).toBe(3); // Second refresh +}); +``` + +### Mock setTimeout Chains + +```typescript +test("notification queue", async ({ page }) => { + await page.clock.install({ time: new Date("2025-01-15T09:00:00") }); + await page.goto("/notifications"); + + // Trigger 3 notifications that show sequentially + await page.getByRole("button", { name: "Show All" }).click(); + + // First notification appears immediately + await expect(page.getByText("Notification 1")).toBeVisible(); + + // Second appears after 2 seconds + await page.clock.fastForward("00:02"); + await expect(page.getByText("Notification 2")).toBeVisible(); + + // Third appears after 2 more seconds + await page.clock.fastForward("00:02"); + await expect(page.getByText("Notification 3")).toBeVisible(); +}); +``` + +### Test Animation Frames + +```typescript +test("animation completes", async ({ page }) => { + await page.clock.install({ time: new Date("2025-01-15T09:00:00") }); + await page.goto("/animation-demo"); + + await page.getByRole("button", { name: "Animate" }).click(); + + // Animation runs for 500ms + const element = page.getByTestId("animated-box"); + await expect(element).toHaveCSS("opacity", "0"); + + // Fast forward through animation + await page.clock.fastForward(500); + + await expect(element).toHaveCSS("opacity", "1"); +}); +``` + +## Best Practices + +### Always Install Clock Before Navigation + +```typescript +// Good +test("date test", async ({ page }) => { + await page.clock.install({ time: new Date("2025-01-15") }); + await page.goto("/"); // Page loads with mocked time +}); + +// Bad - time already captured by page +test("date test", async ({ page }) => { + await page.goto("/"); + await page.clock.install({ time: new Date("2025-01-15") }); // Too late! +}); +``` + +### Use ISO Strings for Clarity + +```typescript +// Good - explicit timezone +await page.clock.install({ time: new Date("2025-01-15T09:00:00Z") }); + +// Ambiguous - uses local timezone +await page.clock.install({ time: new Date("2025-01-15T09:00:00") }); +``` + +## Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Solution | +| ---------------------------------------- | ------------------------------- | -------------------------------------- | +| Installing clock after navigation | Page already captured real time | Install clock before `goto()` | +| Hardcoded relative dates | Tests break over time | Use fixed dates with clock mock | +| Not accounting for timezone | Tests fail in different regions | Use explicit UTC times or set timezone | +| Using `waitForTimeout` with mocked clock | Conflicts with mocked timers | Use `fastForward` instead | + +## Related References + +- **Assertions**: See [assertions-waiting.md](../core/assertions-waiting.md) for time-based assertions +- **Fixtures**: See [fixtures-hooks.md](../core/fixtures-hooks.md) for clock fixtures diff --git a/.cursor/skills/playwright-testing/advanced/mobile-testing.md b/.cursor/skills/playwright-testing/advanced/mobile-testing.md new file mode 100644 index 0000000000..e928bdee50 --- /dev/null +++ b/.cursor/skills/playwright-testing/advanced/mobile-testing.md @@ -0,0 +1,409 @@ +# Mobile & Responsive Testing + +## Table of Contents + +1. [Device Emulation](#device-emulation) +2. [Touch Gestures](#touch-gestures) +3. [Viewport Testing](#viewport-testing) +4. [Mobile-Specific UI](#mobile-specific-ui) +5. [Responsive Breakpoints](#responsive-breakpoints) + +## Device Emulation + +### Use Built-in Devices + +```typescript +import { test, devices } from "@playwright/test"; + +// Configure in playwright.config.ts +export default defineConfig({ + projects: [ + { name: "Desktop Chrome", use: { ...devices["Desktop Chrome"] } }, + { name: "Mobile Safari", use: { ...devices["iPhone 14"] } }, + { name: "Mobile Chrome", use: { ...devices["Pixel 7"] } }, + { name: "Tablet", use: { ...devices["iPad Pro 11"] } }, + ], +}); +``` + +### Custom Device Configuration + +```typescript +test.use({ + viewport: { width: 390, height: 844 }, + deviceScaleFactor: 3, + isMobile: true, + hasTouch: true, + userAgent: + "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15", +}); + +test("custom mobile device", async ({ page }) => { + await page.goto("/"); + // Test runs with custom device settings +}); +``` + +### Test Across Multiple Devices + +```typescript +const mobileDevices = ["iPhone 14", "Pixel 7", "Galaxy S21"]; + +for (const deviceName of mobileDevices) { + test(`checkout on ${deviceName}`, async ({ browser }) => { + const device = devices[deviceName]; + const context = await browser.newContext({ ...device }); + const page = await context.newPage(); + + await page.goto("/checkout"); + await expect(page.getByRole("button", { name: "Pay" })).toBeVisible(); + + await context.close(); + }); +} +``` + +## Touch Gestures + +### Tap + +```typescript +test.use({ hasTouch: true }); + +test("tap to interact", async ({ page }) => { + await page.goto("/gallery"); + + // Tap is like click but for touch devices + await page.getByRole("img", { name: "Photo 1" }).tap(); + + await expect(page.getByRole("dialog")).toBeVisible(); +}); +``` + +### Swipe + +```typescript +test("swipe carousel", async ({ page }) => { + await page.goto("/carousel"); + + const carousel = page.getByTestId("carousel"); + const box = await carousel.boundingBox(); + + if (box) { + // Swipe left + await page.touchscreen.tap(box.x + box.width - 50, box.y + box.height / 2); + await page.mouse.move(box.x + 50, box.y + box.height / 2); + + // Or use drag + await carousel.dragTo(carousel, { + sourcePosition: { x: box.width - 50, y: box.height / 2 }, + targetPosition: { x: 50, y: box.height / 2 }, + }); + } + + await expect(page.getByText("Slide 2")).toBeVisible(); +}); +``` + +### Swipe Fixture + +```typescript +// fixtures/touch.fixture.ts +import { test as base, Page } from "@playwright/test"; + +type TouchFixtures = { + swipe: ( + element: Locator, + direction: "left" | "right" | "up" | "down", + ) => Promise; +}; + +export const test = base.extend({ + swipe: async ({ page }, use) => { + await use(async (element, direction) => { + const box = await element.boundingBox(); + if (!box) throw new Error("Element not visible"); + + const centerX = box.x + box.width / 2; + const centerY = box.y + box.height / 2; + const distance = 100; + + const moves = { + left: { + startX: centerX + distance, + endX: centerX - distance, + y: centerY, + }, + right: { + startX: centerX - distance, + endX: centerX + distance, + y: centerY, + }, + up: { + startX: centerX, + endX: centerX, + startY: centerY + distance, + endY: centerY - distance, + }, + down: { + startX: centerX, + endX: centerX, + startY: centerY - distance, + endY: centerY + distance, + }, + }; + + const move = moves[direction]; + await page.touchscreen.tap(move.startX, move.startY ?? move.y); + await page.mouse.move(move.endX, move.endY ?? move.y, { steps: 10 }); + await page.mouse.up(); + }); + }, +}); + +// Usage +test("swipe to delete", async ({ page, swipe }) => { + await page.goto("/inbox"); + + const message = page.getByTestId("message-1"); + await swipe(message, "left"); + + await expect(page.getByRole("button", { name: "Delete" })).toBeVisible(); +}); +``` + +### Long Press + +```typescript +test("long press for context menu", async ({ page }) => { + await page.goto("/files"); + + const file = page.getByText("document.pdf"); + const box = await file.boundingBox(); + + if (box) { + // Touch down + await page.touchscreen.tap(box.x + box.width / 2, box.y + box.height / 2); + + // Hold for 500ms + await page.waitForTimeout(500); + + // Context menu should appear + await expect(page.getByRole("menu")).toBeVisible(); + } +}); +``` + +### Pinch Zoom + +```typescript +test("pinch to zoom image", async ({ page }) => { + await page.goto("/map"); + + // Pinch zoom requires two touch points + // Playwright doesn't have native pinch support, so we simulate via evaluate + await page.evaluate(() => { + const element = document.querySelector("#map"); + if (element) { + // Simulate wheel event as fallback for zoom + element.dispatchEvent( + new WheelEvent("wheel", { + deltaY: -100, // Negative = zoom in + ctrlKey: true, // Ctrl+wheel = pinch on many apps + }), + ); + } + }); + + // Or trigger the app's zoom function directly + await page.evaluate(() => { + (window as any).mapInstance?.setZoom(15); + }); +}); +``` + +## Viewport Testing + +### Test Different Sizes + +```typescript +const viewports = [ + { name: "mobile", width: 375, height: 667 }, + { name: "tablet", width: 768, height: 1024 }, + { name: "desktop", width: 1920, height: 1080 }, +]; + +for (const { name, width, height } of viewports) { + test(`navigation on ${name}`, async ({ page }) => { + await page.setViewportSize({ width, height }); + await page.goto("/"); + + if (width < 768) { + // Mobile: should have hamburger menu + await expect(page.getByRole("button", { name: "Menu" })).toBeVisible(); + } else { + // Desktop: should have visible nav links + await expect(page.getByRole("link", { name: "Products" })).toBeVisible(); + } + }); +} +``` + +### Dynamic Viewport Changes + +```typescript +test("responsive layout change", async ({ page }) => { + await page.setViewportSize({ width: 1200, height: 800 }); + await page.goto("/dashboard"); + + // Desktop: sidebar visible + await expect(page.getByRole("complementary")).toBeVisible(); + + // Resize to mobile + await page.setViewportSize({ width: 375, height: 667 }); + + // Mobile: sidebar hidden, hamburger visible + await expect(page.getByRole("complementary")).toBeHidden(); + await expect(page.getByRole("button", { name: "Menu" })).toBeVisible(); +}); +``` + +## Mobile-Specific UI + +### Hamburger Menu + +```typescript +test("mobile navigation", async ({ page }) => { + await page.setViewportSize({ width: 375, height: 667 }); + await page.goto("/"); + + // Open hamburger menu + await page.getByRole("button", { name: "Menu" }).click(); + + // Navigation drawer should appear + const nav = page.getByRole("navigation"); + await expect(nav).toBeVisible(); + + // Navigate via mobile menu + await nav.getByRole("link", { name: "Products" }).click(); + + await expect(page).toHaveURL("/products"); + // Menu should close after navigation + await expect(nav).toBeHidden(); +}); +``` + +### Bottom Sheet + +```typescript +test("bottom sheet interaction", async ({ page }) => { + await page.setViewportSize({ width: 375, height: 667 }); + await page.goto("/product/123"); + + await page.getByRole("button", { name: "Add to Cart" }).click(); + + // Bottom sheet appears + const sheet = page.getByRole("dialog"); + await expect(sheet).toBeVisible(); + + // Select options + await sheet.getByRole("combobox", { name: "Size" }).selectOption("Large"); + await sheet.getByRole("button", { name: "Confirm" }).click(); + + await expect(page.getByText("Added to cart")).toBeVisible(); +}); +``` + +### Pull to Refresh + +```typescript +test("pull to refresh", async ({ page }) => { + await page.goto("/feed"); + + const feed = page.getByTestId("feed"); + const initialFirstItem = await feed.locator("> *").first().textContent(); + + // Simulate pull down + const box = await feed.boundingBox(); + if (box) { + await page.touchscreen.tap(box.x + box.width / 2, box.y + 50); + await page.mouse.move(box.x + box.width / 2, box.y + 200, { steps: 20 }); + await page.mouse.up(); + } + + // Wait for refresh + await expect(page.getByTestId("loading")).toBeVisible(); + await expect(page.getByTestId("loading")).toBeHidden(); + + // Content should be updated (in a real app) +}); +``` + +## Responsive Breakpoints + +### Test All Breakpoints + +```typescript +const breakpoints = { + xs: 320, + sm: 640, + md: 768, + lg: 1024, + xl: 1280, + "2xl": 1536, +}; + +test.describe("responsive header", () => { + for (const [name, width] of Object.entries(breakpoints)) { + test(`header at ${name} (${width}px)`, async ({ page }) => { + await page.setViewportSize({ width, height: 800 }); + await page.goto("/"); + + if (width < 768) { + await expect(page.getByTestId("mobile-menu-button")).toBeVisible(); + await expect(page.getByTestId("desktop-nav")).toBeHidden(); + } else { + await expect(page.getByTestId("mobile-menu-button")).toBeHidden(); + await expect(page.getByTestId("desktop-nav")).toBeVisible(); + } + }); + } +}); +``` + +### Visual Regression at Breakpoints + +```typescript +test.describe("visual regression", () => { + const sizes = [ + { width: 375, height: 667, name: "mobile" }, + { width: 768, height: 1024, name: "tablet" }, + { width: 1440, height: 900, name: "desktop" }, + ]; + + for (const { width, height, name } of sizes) { + test(`homepage at ${name}`, async ({ page }) => { + await page.setViewportSize({ width, height }); + await page.goto("/"); + + await expect(page).toHaveScreenshot(`homepage-${name}.png`); + }); + } +}); +``` + +## Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Solution | +| --------------------------- | ------------------------- | -------------------------------- | +| Only testing one viewport | Misses responsive bugs | Test multiple breakpoints | +| Ignoring touch events | Features broken on mobile | Test tap, swipe, long press | +| Hardcoded viewport in tests | Can't test multiple sizes | Use `page.setViewportSize()` | +| Not testing orientation | Landscape bugs missed | Test both portrait and landscape | + +## Related References + +- **Visual Testing**: See [test-suite-structure.md](../core/test-suite-structure.md) for screenshot testing +- **Locators**: See [locators.md](../core/locators.md) for mobile-friendly selectors +- **Browser APIs**: See [browser-apis.md](../browser-apis/browser-apis.md) for permissions (camera, geolocation, notifications) +- **Canvas/Touch**: See [canvas-webgl.md](../testing-patterns/canvas-webgl.md) for touch gestures on canvas elements diff --git a/.cursor/skills/playwright-testing/advanced/multi-context.md b/.cursor/skills/playwright-testing/advanced/multi-context.md new file mode 100644 index 0000000000..ed1cf8a07c --- /dev/null +++ b/.cursor/skills/playwright-testing/advanced/multi-context.md @@ -0,0 +1,288 @@ +# Multi-Tab, Window & Popup Testing + +This file covers **single-user scenarios** with multiple browser tabs, windows, and popups. For **multi-user collaboration testing** (multiple users interacting simultaneously), see [multi-user.md](multi-user.md). + +## Table of Contents + +1. [Popup Handling](#popup-handling) +2. [New Tab Navigation](#new-tab-navigation) +3. [OAuth Flows](#oauth-flows) +4. [Multiple Windows](#multiple-windows) +5. [Tab Coordination](#tab-coordination) + +## Popup Handling + +### Basic Popup + +```typescript +test("handle popup window", async ({ page }) => { + await page.goto("/"); + + // Start waiting for popup before triggering it + const popupPromise = page.waitForEvent("popup"); + await page.getByRole("button", { name: "Open Support Chat" }).click(); + const popup = await popupPromise; + + // Wait for popup to load + await popup.waitForLoadState(); + + // Interact with popup + await popup.getByLabel("Message").fill("Need help"); + await popup.getByRole("button", { name: "Send" }).click(); + + await expect(popup.getByText("Message sent")).toBeVisible(); + + // Close popup + await popup.close(); +}); +``` + +### Popup with Authentication + +```typescript +test("popup login flow", async ({ page }) => { + await page.goto("/dashboard"); + + const popupPromise = page.waitForEvent("popup"); + await page.getByRole("button", { name: "Connect Account" }).click(); + const popup = await popupPromise; + + await popup.waitForLoadState(); + + // Complete login in popup + await popup.getByLabel("Email").fill("user@example.com"); + await popup.getByLabel("Password").fill("password123"); + await popup.getByRole("button", { name: "Log In" }).click(); + + // Popup should close automatically after auth + await popup.waitForEvent("close"); + + // Main page should reflect connected state + await expect(page.getByText("Account connected")).toBeVisible(); +}); +``` + +### Handle Blocked Popups + +```typescript +test("handle popup blocker", async ({ page }) => { + await page.goto("/share"); + + // Listen for console messages about blocked popup + page.on("console", (msg) => { + if (msg.text().includes("popup blocked")) { + console.log("Popup was blocked"); + } + }); + + const popupPromise = page.waitForEvent("popup").catch(() => null); + await page.getByRole("button", { name: "Share to Twitter" }).click(); + const popup = await popupPromise; + + if (!popup) { + // Popup blocked - app should show fallback + await expect(page.getByText("Copy share link instead")).toBeVisible(); + } +}); +``` + +## New Tab Navigation + +### Link Opens in New Tab + +```typescript +test("external link opens in new tab", async ({ page, context }) => { + await page.goto("/resources"); + + // Wait for new page in context + const pagePromise = context.waitForEvent("page"); + await page.getByRole("link", { name: "Documentation" }).click(); + const newPage = await pagePromise; + + await newPage.waitForLoadState(); + + expect(newPage.url()).toContain("docs.example.com"); + await expect(newPage.getByRole("heading", { level: 1 })).toBeVisible(); + + // Original page still there + expect(page.url()).toContain("/resources"); + + await newPage.close(); +}); +``` + +### Intercept New Tab + +```typescript +test("prevent new tab for testing", async ({ page }) => { + await page.goto("/links"); + + // Remove target="_blank" to keep navigation in same tab + await page.evaluate(() => { + document.querySelectorAll('a[target="_blank"]').forEach((a) => { + a.removeAttribute("target"); + }); + }); + + // Now link opens in same tab + await page.getByRole("link", { name: "External Site" }).click(); + + // Can test the destination page + await expect(page).toHaveURL(/external-site\.com/); +}); +``` + +## OAuth Flows + +### Google OAuth Popup + +```typescript +test("Google OAuth login", async ({ page }) => { + await page.goto("/login"); + + const popupPromise = page.waitForEvent("popup"); + await page.getByRole("button", { name: "Sign in with Google" }).click(); + const popup = await popupPromise; + + await popup.waitForLoadState(); + + // Handle Google's OAuth flow + await popup.getByLabel("Email or phone").fill("test@gmail.com"); + await popup.getByRole("button", { name: "Next" }).click(); + + await popup.getByLabel("Enter your password").fill("password"); + await popup.getByRole("button", { name: "Next" }).click(); + + // Wait for redirect back and popup close + await popup.waitForEvent("close"); + + // Verify logged in on main page + await expect(page.getByText("Welcome, Test User")).toBeVisible(); +}); +``` + +### Mock OAuth (Recommended) + +```typescript +test("mock OAuth flow", async ({ page, context }) => { + // Mock the OAuth callback instead of real flow + await page.route("**/auth/callback**", async (route) => { + // Simulate successful OAuth + const url = new URL(route.request().url()); + url.searchParams.set("code", "mock-auth-code"); + await route.fulfill({ + status: 302, + headers: { Location: "/dashboard" }, + }); + }); + + // Mock token exchange + await page.route("**/api/auth/token", (route) => + route.fulfill({ + json: { + access_token: "mock-token", + user: { name: "Test User", email: "test@example.com" }, + }, + }), + ); + + await page.goto("/login"); + await page.getByRole("button", { name: "Sign in with Google" }).click(); + + // Should redirect to dashboard without actual OAuth + await expect(page).toHaveURL("/dashboard"); + await expect(page.getByText("Welcome, Test User")).toBeVisible(); +}); +``` + +### OAuth Fixture + +> **For comprehensive OAuth mocking patterns** (fixtures, multiple providers, SAML SSO), see [third-party.md](third-party.md#oauthsso-mocking). This section focuses on popup window handling mechanics for OAuth flows. + +## Multiple Windows + +### Test Across Multiple Windows + +```typescript +test("sync between windows", async ({ context }) => { + // Open two pages + const page1 = await context.newPage(); + const page2 = await context.newPage(); + + await page1.goto("/dashboard"); + await page2.goto("/dashboard"); + + // Make change in first window + await page1.getByRole("button", { name: "Add Item" }).click(); + await page1.getByLabel("Name").fill("New Item"); + await page1.getByRole("button", { name: "Save" }).click(); + + // Should sync to second window (if app supports real-time sync) + await expect(page2.getByText("New Item")).toBeVisible({ timeout: 10000 }); +}); +``` + +### Different Users in Different Windows + +> **For multi-user collaboration patterns** (admin/user interactions, real-time collaboration, role-based testing, concurrent actions), see [multi-user.md](multi-user.md). This file focuses on single-user scenarios with multiple tabs/windows/popups. + +## Tab Coordination + +### Switch Between Tabs + +```typescript +test("manage multiple tabs", async ({ context }) => { + const page1 = await context.newPage(); + await page1.goto("/editor"); + + const page2 = await context.newPage(); + await page2.goto("/preview"); + + // Edit in first tab + await page1.bringToFront(); + await page1.getByLabel("Content").fill("Hello World"); + + // Check preview in second tab + await page2.bringToFront(); + await page2.reload(); // If preview needs refresh + await expect(page2.getByText("Hello World")).toBeVisible(); +}); +``` + +### Close All Tabs Except One + +```typescript +test("cleanup tabs after test", async ({ context }) => { + const mainPage = await context.newPage(); + await mainPage.goto("/"); + + // Open several popups during test + for (let i = 0; i < 3; i++) { + const popup = await context.newPage(); + await popup.goto(`/popup/${i}`); + } + + // Close all except main page + for (const page of context.pages()) { + if (page !== mainPage) { + await page.close(); + } + } + + expect(context.pages()).toHaveLength(1); +}); +``` + +## Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Solution | +| ----------------------- | ------------------------------ | ------------------------------------------ | +| Not waiting for popup | Race condition | Use `waitForEvent("popup")` before trigger | +| Testing real OAuth | Slow, flaky, needs credentials | Mock OAuth endpoints | +| Assuming popup opens | May be blocked | Handle both open and blocked cases | +| Not closing extra pages | Resource leak | Close pages in cleanup | + +## Related References + +- **Authentication**: See [fixtures-hooks.md](../core/fixtures-hooks.md) for auth patterns +- **Network**: See [network-advanced.md](network-advanced.md) for mocking OAuth diff --git a/.cursor/skills/playwright-testing/advanced/multi-user.md b/.cursor/skills/playwright-testing/advanced/multi-user.md new file mode 100644 index 0000000000..301e55c4fe --- /dev/null +++ b/.cursor/skills/playwright-testing/advanced/multi-user.md @@ -0,0 +1,393 @@ +# Multi-User & Collaboration Testing + +## Table of Contents + +1. [Multiple Browser Contexts](#multiple-browser-contexts) +2. [Real-Time Collaboration](#real-time-collaboration) +3. [Role-Based Testing](#role-based-testing) +4. [Concurrent Actions](#concurrent-actions) +5. [Chat & Messaging](#chat--messaging) + +## Multiple Browser Contexts + +### Two Users in Same Test + +```typescript +test("two users see each other's changes", async ({ browser }) => { + // Create two isolated contexts (like two browsers) + const userAContext = await browser.newContext(); + const userBContext = await browser.newContext(); + + const userAPage = await userAContext.newPage(); + const userBPage = await userBContext.newPage(); + + // Both users go to the same document + await userAPage.goto("/doc/shared-123"); + await userBPage.goto("/doc/shared-123"); + + // User A types + await userAPage.getByLabel("Content").fill("Hello from User A"); + + // User B should see the change + await expect(userBPage.getByText("Hello from User A")).toBeVisible(); + + // Cleanup + await userAContext.close(); + await userBContext.close(); +}); +``` + +### Multiple Users with Auth States + +```typescript +test("admin and user interaction", async ({ browser }) => { + // Load different auth states + const adminContext = await browser.newContext({ + storageState: ".auth/admin.json", + }); + const userContext = await browser.newContext({ + storageState: ".auth/user.json", + }); + + const adminPage = await adminContext.newPage(); + const userPage = await userContext.newPage(); + + // User submits request + await userPage.goto("/support"); + await userPage.getByLabel("Message").fill("Need help!"); + await userPage.getByRole("button", { name: "Submit" }).click(); + + // Admin sees and responds + await adminPage.goto("/admin/tickets"); + await expect(adminPage.getByText("Need help!")).toBeVisible(); + await adminPage.getByRole("button", { name: "Reply" }).click(); + await adminPage.getByLabel("Response").fill("How can I help?"); + await adminPage.getByRole("button", { name: "Send" }).click(); + + // User sees response + await expect(userPage.getByText("How can I help?")).toBeVisible(); + + await adminContext.close(); + await userContext.close(); +}); +``` + +### Multi-User Fixture + +```typescript +// fixtures/multi-user.fixture.ts +import { test as base, Browser, BrowserContext, Page } from "@playwright/test"; + +type UserSession = { + context: BrowserContext; + page: Page; +}; + +type MultiUserFixtures = { + createUser: (authState?: string) => Promise; +}; + +export const test = base.extend({ + createUser: async ({ browser }, use) => { + const sessions: UserSession[] = []; + + await use(async (authState) => { + const context = await browser.newContext({ + storageState: authState, + }); + const page = await context.newPage(); + sessions.push({ context, page }); + return { context, page }; + }); + + // Cleanup all sessions + for (const session of sessions) { + await session.context.close(); + } + }, +}); + +// Usage +test("3 users collaborate", async ({ createUser }) => { + const alice = await createUser(".auth/alice.json"); + const bob = await createUser(".auth/bob.json"); + const charlie = await createUser(".auth/charlie.json"); + + // All navigate to same room + await alice.page.goto("/room/123"); + await bob.page.goto("/room/123"); + await charlie.page.goto("/room/123"); + + // Test interactions... +}); +``` + +## Real-Time Collaboration + +### Collaborative Document + +```typescript +test("real-time collaborative editing", async ({ browser }) => { + const user1 = await browser.newContext(); + const user2 = await browser.newContext(); + + const page1 = await user1.newPage(); + const page2 = await user2.newPage(); + + await page1.goto("/docs/shared"); + await page2.goto("/docs/shared"); + + // User 1 types at the beginning + const editor1 = page1.getByRole("textbox"); + await editor1.click(); + await editor1.press("Home"); + await editor1.type("User 1: "); + + // User 2 types at the end + const editor2 = page2.getByRole("textbox"); + await editor2.click(); + await editor2.press("End"); + await editor2.type(" - User 2"); + + // Both should see combined result + await expect(page1.getByRole("textbox")).toContainText("User 1:"); + await expect(page1.getByRole("textbox")).toContainText("- User 2"); + await expect(page2.getByRole("textbox")).toContainText("User 1:"); + await expect(page2.getByRole("textbox")).toContainText("- User 2"); + + await user1.close(); + await user2.close(); +}); +``` + +### Cursor Presence + +```typescript +test("shows other user cursors", async ({ browser }) => { + const ctx1 = await browser.newContext(); + const ctx2 = await browser.newContext(); + + const page1 = await ctx1.newPage(); + const page2 = await ctx2.newPage(); + + // Mock to identify users + await page1.route("**/api/me", (route) => + route.fulfill({ json: { id: "user-1", name: "Alice" } }), + ); + await page2.route("**/api/me", (route) => + route.fulfill({ json: { id: "user-2", name: "Bob" } }), + ); + + await page1.goto("/whiteboard/123"); + await page2.goto("/whiteboard/123"); + + // Move cursor on page1 + await page1.mouse.move(200, 200); + + // Page2 should see Alice's cursor + await expect(page2.getByTestId("cursor-user-1")).toBeVisible(); + await expect(page2.getByText("Alice")).toBeVisible(); + + await ctx1.close(); + await ctx2.close(); +}); +``` + +## Role-Based Testing + +### Test RBAC + +```typescript +const roles = [ + { role: "admin", canDelete: true, canEdit: true, canView: true }, + { role: "editor", canDelete: false, canEdit: true, canView: true }, + { role: "viewer", canDelete: false, canEdit: false, canView: true }, +]; + +for (const { role, canDelete, canEdit, canView } of roles) { + test(`${role} permissions`, async ({ browser }) => { + const context = await browser.newContext({ + storageState: `.auth/${role}.json`, + }); + const page = await context.newPage(); + + await page.goto("/document/123"); + + // Check view permission + if (canView) { + await expect(page.getByTestId("content")).toBeVisible(); + } else { + await expect(page.getByText("Access denied")).toBeVisible(); + } + + // Check edit permission + const editButton = page.getByRole("button", { name: "Edit" }); + if (canEdit) { + await expect(editButton).toBeEnabled(); + } else { + await expect(editButton).toBeDisabled(); + } + + // Check delete permission + const deleteButton = page.getByRole("button", { name: "Delete" }); + if (canDelete) { + await expect(deleteButton).toBeVisible(); + } else { + await expect(deleteButton).toBeHidden(); + } + + await context.close(); + }); +} +``` + +### Permission Escalation Test + +```typescript +test("cannot access admin routes as user", async ({ browser }) => { + const userContext = await browser.newContext({ + storageState: ".auth/user.json", + }); + const page = await userContext.newPage(); + + // Try to access admin page directly + await page.goto("/admin/users"); + + // Should redirect or show error + await expect(page).not.toHaveURL("/admin/users"); + await expect(page.getByText("Access denied")).toBeVisible(); + + await userContext.close(); +}); +``` + +## Concurrent Actions + +### Race Condition Testing + +```typescript +test("handles concurrent edits", async ({ browser }) => { + const ctx1 = await browser.newContext(); + const ctx2 = await browser.newContext(); + + const page1 = await ctx1.newPage(); + const page2 = await ctx2.newPage(); + + await page1.goto("/item/123"); + await page2.goto("/item/123"); + + // Both click edit at the same time + await Promise.all([ + page1.getByRole("button", { name: "Edit" }).click(), + page2.getByRole("button", { name: "Edit" }).click(), + ]); + + // Both try to save different values + await page1.getByLabel("Name").fill("Value from User 1"); + await page2.getByLabel("Name").fill("Value from User 2"); + + await Promise.all([ + page1.getByRole("button", { name: "Save" }).click(), + page2.getByRole("button", { name: "Save" }).click(), + ]); + + // One should succeed, one should get conflict error + const page1HasConflict = await page1.getByText("Conflict").isVisible(); + const page2HasConflict = await page2.getByText("Conflict").isVisible(); + + // Exactly one should have conflict + expect(page1HasConflict || page2HasConflict).toBe(true); + expect(page1HasConflict && page2HasConflict).toBe(false); + + await ctx1.close(); + await ctx2.close(); +}); +``` + +### Optimistic Locking Test + +```typescript +test("optimistic locking prevents overwrites", async ({ browser }) => { + const ctx1 = await browser.newContext(); + const ctx2 = await browser.newContext(); + + const page1 = await ctx1.newPage(); + const page2 = await ctx2.newPage(); + + // Both load the same version + await page1.goto("/record/123"); + await page2.goto("/record/123"); + + // User 1 edits and saves first + await page1.getByRole("button", { name: "Edit" }).click(); + await page1.getByLabel("Value").fill("Updated by User 1"); + await page1.getByRole("button", { name: "Save" }).click(); + await expect(page1.getByText("Saved")).toBeVisible(); + + // User 2 tries to save with stale version + await page2.getByRole("button", { name: "Edit" }).click(); + await page2.getByLabel("Value").fill("Updated by User 2"); + await page2.getByRole("button", { name: "Save" }).click(); + + // Should fail with version conflict + await expect(page2.getByText("Someone else modified this")).toBeVisible(); + await expect(page2.getByRole("button", { name: "Reload" })).toBeVisible(); + + await ctx1.close(); + await ctx2.close(); +}); +``` + +## Chat & Messaging + +### Real-Time Chat + +```typescript +test("chat messages sync between users", async ({ browser }) => { + const aliceCtx = await browser.newContext(); + const bobCtx = await browser.newContext(); + + const alicePage = await aliceCtx.newPage(); + const bobPage = await bobCtx.newPage(); + + // Setup user identities + await alicePage.route("**/api/me", (r) => + r.fulfill({ json: { name: "Alice" } }), + ); + await bobPage.route("**/api/me", (r) => r.fulfill({ json: { name: "Bob" } })); + + await alicePage.goto("/chat/room-1"); + await bobPage.goto("/chat/room-1"); + + // Alice sends message + await alicePage.getByLabel("Message").fill("Hi Bob!"); + await alicePage.getByRole("button", { name: "Send" }).click(); + + // Bob sees it + await expect(bobPage.getByText("Alice: Hi Bob!")).toBeVisible(); + + // Bob replies + await bobPage.getByLabel("Message").fill("Hey Alice!"); + await bobPage.getByRole("button", { name: "Send" }).click(); + + // Alice sees it + await expect(alicePage.getByText("Bob: Hey Alice!")).toBeVisible(); + + await aliceCtx.close(); + await bobCtx.close(); +}); +``` + +## Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Solution | +| ----------------------------- | ----------------------------- | ---------------------------- | +| Sharing context between users | State leaks, not isolated | Create separate contexts | +| Not closing contexts | Memory leak, browser overload | Always close in cleanup | +| Hardcoded timing for sync | Flaky tests | Use `expect().toBeVisible()` | +| Testing only single user | Misses collaboration bugs | Test multi-user scenarios | + +## Related References + +- **Authentication**: See [fixtures-hooks.md](../core/fixtures-hooks.md) for auth setup +- **WebSockets**: See [websockets.md](../browser-apis/websockets.md) for real-time mocking diff --git a/.cursor/skills/playwright-testing/advanced/network-advanced.md b/.cursor/skills/playwright-testing/advanced/network-advanced.md new file mode 100644 index 0000000000..fa017fe53f --- /dev/null +++ b/.cursor/skills/playwright-testing/advanced/network-advanced.md @@ -0,0 +1,452 @@ +# Advanced Network Interception + +## Table of Contents + +1. [Request Modification](#request-modification) +2. [GraphQL Mocking](#graphql-mocking) +3. [HAR Recording & Playback](#har-recording--playback) +4. [Conditional Mocking](#conditional-mocking) +5. [Network Throttling](#network-throttling) + +## Request Modification + +### Modify Request Headers + +```typescript +test("add auth header to requests", async ({ page }) => { + await page.route("**/api/**", (route) => { + const headers = { + ...route.request().headers(), + Authorization: "Bearer test-token", + "X-Test-Header": "test-value", + }; + route.continue({ headers }); + }); + + await page.goto("/dashboard"); +}); +``` + +### Modify Request Body + +```typescript +test("modify POST body", async ({ page }) => { + await page.route("**/api/orders", async (route) => { + if (route.request().method() === "POST") { + const postData = route.request().postDataJSON(); + + // Add test metadata + const modifiedData = { + ...postData, + testMode: true, + testTimestamp: Date.now(), + }; + + await route.continue({ + postData: JSON.stringify(modifiedData), + }); + } else { + await route.continue(); + } + }); + + await page.goto("/checkout"); + await page.getByRole("button", { name: "Place Order" }).click(); +}); +``` + +### Transform Response + +```typescript +test("modify API response", async ({ page }) => { + await page.route("**/api/products", async (route) => { + // Fetch real response + const response = await route.fetch(); + const json = await response.json(); + + // Modify response + const modified = json.map((product: any) => ({ + ...product, + price: product.price * 0.9, // 10% discount + testMode: true, + })); + + await route.fulfill({ + response, + json: modified, + }); + }); + + await page.goto("/products"); +}); +``` + +## GraphQL Mocking + +### Mock by Operation Name + +```typescript +test("mock GraphQL query", async ({ page }) => { + await page.route("**/graphql", async (route) => { + const postData = route.request().postDataJSON(); + + if (postData.operationName === "GetUser") { + return route.fulfill({ + json: { + data: { + user: { + id: "1", + name: "Test User", + email: "test@example.com", + }, + }, + }, + }); + } + + if (postData.operationName === "GetProducts") { + return route.fulfill({ + json: { + data: { + products: [ + { id: "1", name: "Product A", price: 29.99 }, + { id: "2", name: "Product B", price: 49.99 }, + ], + }, + }, + }); + } + + // Pass through unmocked operations + return route.continue(); + }); + + await page.goto("/dashboard"); +}); +``` + +### GraphQL Mock Fixture + +```typescript +// fixtures/graphql.fixture.ts +type GraphQLMock = { + operation: string; + variables?: Record; + response: { data?: any; errors?: any[] }; +}; + +type GraphQLFixtures = { + mockGraphQL: (mocks: GraphQLMock[]) => Promise; +}; + +export const test = base.extend({ + mockGraphQL: async ({ page }, use) => { + await use(async (mocks) => { + await page.route("**/graphql", async (route) => { + const postData = route.request().postDataJSON(); + + const mock = mocks.find((m) => { + if (m.operation !== postData.operationName) return false; + + // Optionally match variables + if (m.variables) { + return ( + JSON.stringify(m.variables) === JSON.stringify(postData.variables) + ); + } + return true; + }); + + if (mock) { + return route.fulfill({ json: mock.response }); + } + + return route.continue(); + }); + }); + }, +}); + +// Usage +test("dashboard with mocked GraphQL", async ({ page, mockGraphQL }) => { + await mockGraphQL([ + { + operation: "GetDashboardStats", + response: { + data: { stats: { users: 100, revenue: 50000 } }, + }, + }, + { + operation: "GetUser", + variables: { id: "1" }, + response: { + data: { user: { id: "1", name: "John" } }, + }, + }, + ]); + + await page.goto("/dashboard"); + await expect(page.getByText("100 users")).toBeVisible(); +}); +``` + +### Mock GraphQL Mutations + +```typescript +test("mock GraphQL mutation", async ({ page }) => { + await page.route("**/graphql", async (route) => { + const postData = route.request().postDataJSON(); + + if (postData.operationName === "CreateOrder") { + const { input } = postData.variables; + + return route.fulfill({ + json: { + data: { + createOrder: { + id: "order-123", + status: "PENDING", + items: input.items, + total: input.items.reduce( + (sum: number, item: any) => sum + item.price * item.quantity, + 0, + ), + }, + }, + }, + }); + } + + return route.continue(); + }); + + await page.goto("/checkout"); + await page.getByRole("button", { name: "Place Order" }).click(); + + await expect(page.getByText("Order #order-123")).toBeVisible(); +}); +``` + +## HAR Recording & Playback + +### Record HAR File + +```typescript +// Record network traffic +test("record HAR", async ({ page, context }) => { + // Start recording + await context.routeFromHAR("./recordings/checkout.har", { + update: true, // Create/update HAR file + url: "**/api/**", + }); + + await page.goto("/checkout"); + await page.getByRole("button", { name: "Place Order" }).click(); + + // HAR file is saved automatically +}); +``` + +### Playback HAR File + +```typescript +// Use recorded HAR for offline testing +test("playback HAR", async ({ page, context }) => { + await context.routeFromHAR("./recordings/checkout.har", { + url: "**/api/**", + update: false, // Don't update, just playback + }); + + await page.goto("/checkout"); + + // All API calls served from HAR file + await expect(page.getByText("Order confirmed")).toBeVisible(); +}); +``` + +### HAR with Fallback + +```typescript +test("HAR with live fallback", async ({ page, context }) => { + await context.routeFromHAR("./recordings/api.har", { + url: "**/api/**", + update: false, + notFound: "fallback", // Use real network if not in HAR + }); + + await page.goto("/dashboard"); +}); +``` + +## Conditional Mocking + +### Mock Based on Request Body + +```typescript +test("conditional mock by body", async ({ page }) => { + await page.route("**/api/search", async (route) => { + const body = route.request().postDataJSON(); + + if (body.query === "error") { + return route.fulfill({ + status: 500, + json: { error: "Search failed" }, + }); + } + + if (body.query === "empty") { + return route.fulfill({ + json: { results: [] }, + }); + } + + // Default response + return route.fulfill({ + json: { + results: [{ id: 1, title: `Result for: ${body.query}` }], + }, + }); + }); + + await page.goto("/search"); + + // Test different scenarios + await page.getByLabel("Search").fill("error"); + await page.getByLabel("Search").press("Enter"); + await expect(page.getByText("Search failed")).toBeVisible(); +}); +``` + +### Mock Nth Request + +```typescript +test("different response on retry", async ({ page }) => { + let callCount = 0; + + await page.route("**/api/status", (route) => { + callCount++; + + if (callCount < 3) { + return route.fulfill({ + status: 503, + json: { error: "Service unavailable" }, + }); + } + + // Succeed on 3rd attempt + return route.fulfill({ + json: { status: "ok" }, + }); + }); + + await page.goto("/dashboard"); + + // App should retry and eventually succeed + await expect(page.getByText("Connected")).toBeVisible(); +}); +``` + +### Mock with Delay + +```typescript +test("slow network simulation", async ({ page }) => { + await page.route("**/api/data", async (route) => { + // Simulate 2 second delay + await new Promise((resolve) => setTimeout(resolve, 2000)); + + return route.fulfill({ + json: { data: "loaded" }, + }); + }); + + await page.goto("/dashboard"); + + // Loading state should appear + await expect(page.getByText("Loading...")).toBeVisible(); + + // Then data appears + await expect(page.getByText("loaded")).toBeVisible(); +}); +``` + +## Network Throttling + +### Slow 3G Simulation + +```typescript +test("slow network experience", async ({ page, context }) => { + // Create CDP session for network throttling + const client = await context.newCDPSession(page); + + await client.send("Network.emulateNetworkConditions", { + offline: false, + downloadThroughput: (500 * 1024) / 8, // 500 Kbps + uploadThroughput: (500 * 1024) / 8, + latency: 400, // 400ms + }); + + await page.goto("/"); + + // Test loading states appear + await expect(page.getByTestId("skeleton-loader")).toBeVisible(); +}); +``` + +### Offline Mode + +Use `context.setOffline(true/false)` to simulate network connectivity changes. + +> **For comprehensive offline testing patterns:** +> +> - **Network failure simulation** (error recovery, graceful degradation): See [error-testing.md](error-testing.md#offline-testing) +> - **Offline-first/PWA testing** (service workers, caching, background sync): See [service-workers.md](service-workers.md#offline-testing) + +### Network Throttling Fixture + +```typescript +// fixtures/network.fixture.ts +type NetworkCondition = "slow3g" | "fast3g" | "offline"; + +const conditions = { + slow3g: { downloadThroughput: 50000, uploadThroughput: 50000, latency: 2000 }, + fast3g: { downloadThroughput: 180000, uploadThroughput: 75000, latency: 150 }, +}; + +type NetworkFixtures = { + setNetworkCondition: (condition: NetworkCondition) => Promise; +}; + +export const test = base.extend({ + setNetworkCondition: async ({ page, context }, use) => { + const client = await context.newCDPSession(page); + + await use(async (condition) => { + if (condition === "offline") { + await context.setOffline(true); + } else { + await client.send("Network.emulateNetworkConditions", { + offline: false, + ...conditions[condition], + }); + } + }); + + // Reset + await context.setOffline(false); + }, +}); +``` + +## Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Solution | +| ------------------------ | ------------------------------ | -------------------------------- | +| Mocking all requests | Tests don't reflect reality | Mock only what's necessary | +| No cleanup of routes | Routes persist across tests | Use fixtures with cleanup | +| Ignoring request method | Mock applies to wrong requests | Check `route.request().method()` | +| Hardcoded mock responses | Brittle, hard to maintain | Use factories for mock data | + +## Related References + +- **Basic Mocking**: See [test-suite-structure.md](../core/test-suite-structure.md) for simple mocking +- **WebSockets**: See [websockets.md](../browser-apis/websockets.md) for real-time mocking diff --git a/.cursor/skills/playwright-testing/advanced/third-party.md b/.cursor/skills/playwright-testing/advanced/third-party.md new file mode 100644 index 0000000000..acf8ab8901 --- /dev/null +++ b/.cursor/skills/playwright-testing/advanced/third-party.md @@ -0,0 +1,464 @@ +# Third-Party Service Mocking + +## Table of Contents + +1. [OAuth/SSO Mocking](#oauthsso-mocking) +2. [Payment Gateway Mocking](#payment-gateway-mocking) +3. [Email Verification](#email-verification) +4. [SMS Verification](#sms-verification) +5. [Analytics & Tracking](#analytics--tracking) + +## OAuth/SSO Mocking + +### Mock Google OAuth + +```typescript +test("Google OAuth login", async ({ page }) => { + // Mock the OAuth callback + await page.route("**/auth/google/callback**", (route) => { + const url = new URL(route.request().url()); + // Simulate successful OAuth by redirecting with token + route.fulfill({ + status: 302, + headers: { + Location: "/dashboard?token=mock-jwt-token", + }, + }); + }); + + // Mock the token verification endpoint + await page.route("**/api/auth/verify", (route) => + route.fulfill({ + json: { + valid: true, + user: { + id: "123", + email: "test@gmail.com", + name: "Test User", + }, + }, + }), + ); + + await page.goto("/login"); + await page.getByRole("button", { name: "Sign in with Google" }).click(); + + await expect(page.getByText("Welcome, Test User")).toBeVisible(); +}); +``` + +### OAuth Fixture + +```typescript +// fixtures/oauth.fixture.ts +type OAuthProvider = "google" | "github" | "microsoft"; + +type OAuthUser = { + id: string; + email: string; + name: string; + avatar?: string; +}; + +type OAuthFixtures = { + mockOAuth: (provider: OAuthProvider, user: OAuthUser) => Promise; +}; + +export const test = base.extend({ + mockOAuth: async ({ page }, use) => { + await use(async (provider, user) => { + // Mock callback redirect + await page.route(`**/auth/${provider}/callback**`, (route) => + route.fulfill({ + status: 302, + headers: { Location: `/auth/success?provider=${provider}` }, + }), + ); + + // Mock session/user endpoint + await page.route("**/api/auth/session", (route) => + route.fulfill({ + json: { user, provider, authenticated: true }, + }), + ); + + // Mock user info endpoint + await page.route("**/api/me", (route) => route.fulfill({ json: user })); + }); + }, +}); + +// Usage +test("login with GitHub", async ({ page, mockOAuth }) => { + await mockOAuth("github", { + id: "gh-123", + email: "dev@github.com", + name: "GitHub User", + }); + + await page.goto("/login"); + await page.getByRole("button", { name: "Sign in with GitHub" }).click(); + + await expect(page.getByText("Welcome, GitHub User")).toBeVisible(); +}); +``` + +### Mock SAML SSO + +```typescript +test("SAML SSO login", async ({ page }) => { + // Mock SAML assertion consumer service + await page.route("**/saml/acs", async (route) => { + route.fulfill({ + status: 302, + headers: { + Location: "/dashboard", + "Set-Cookie": "session=mock-saml-session; Path=/; HttpOnly", + }, + }); + }); + + // Mock session validation + await page.route("**/api/session", (route) => + route.fulfill({ + json: { + user: { email: "user@company.com", name: "SSO User" }, + provider: "saml", + }, + }), + ); + + await page.goto("/login"); + await page.getByRole("button", { name: "SSO Login" }).click(); + + await expect(page).toHaveURL("/dashboard"); +}); +``` + +## Payment Gateway Mocking + +### Mock Stripe + +```typescript +test("Stripe checkout", async ({ page }) => { + // Mock Stripe.js + await page.addInitScript(() => { + (window as any).Stripe = () => ({ + elements: () => ({ + create: () => ({ + mount: () => {}, + on: () => {}, + destroy: () => {}, + }), + }), + confirmCardPayment: async () => ({ + paymentIntent: { status: "succeeded", id: "pi_mock_123" }, + }), + createPaymentMethod: async () => ({ + paymentMethod: { id: "pm_mock_123" }, + }), + }); + }); + + // Mock backend payment endpoint + await page.route("**/api/create-payment-intent", (route) => + route.fulfill({ + json: { clientSecret: "pi_mock_123_secret_mock" }, + }), + ); + + await page.route("**/api/confirm-payment", (route) => + route.fulfill({ + json: { success: true, orderId: "order-123" }, + }), + ); + + await page.goto("/checkout"); + await page.getByRole("button", { name: "Pay $99.99" }).click(); + + await expect(page.getByText("Payment successful")).toBeVisible(); +}); +``` + +### Mock PayPal + +```typescript +test("PayPal checkout", async ({ page }) => { + // Mock PayPal SDK + await page.addInitScript(() => { + (window as any).paypal = { + Buttons: () => ({ + render: () => Promise.resolve(), + isEligible: () => true, + }), + FUNDING: { PAYPAL: "paypal", CARD: "card" }, + }; + }); + + // Mock PayPal order creation + await page.route("**/api/paypal/create-order", (route) => + route.fulfill({ + json: { orderId: "PAYPAL-ORDER-123" }, + }), + ); + + // Mock PayPal capture + await page.route("**/api/paypal/capture", (route) => + route.fulfill({ + json: { success: true, transactionId: "TXN-123" }, + }), + ); + + await page.goto("/checkout"); + + // Simulate PayPal approval callback + await page.evaluate(() => { + (window as any).onPayPalApprove?.({ orderID: "PAYPAL-ORDER-123" }); + }); + + await expect(page.getByText("Order confirmed")).toBeVisible(); +}); +``` + +### Payment Fixture + +```typescript +// fixtures/payment.fixture.ts +type PaymentFixtures = { + mockStripe: (options?: { failPayment?: boolean }) => Promise; +}; + +export const test = base.extend({ + mockStripe: async ({ page }, use) => { + await use(async (options = {}) => { + await page.addInitScript( + ([shouldFail]) => { + (window as any).Stripe = () => ({ + elements: () => ({ + create: () => ({ + mount: () => {}, + on: (event: string, handler: Function) => { + if (event === "ready") setTimeout(handler, 100); + }, + destroy: () => {}, + }), + }), + confirmCardPayment: async () => { + if (shouldFail) { + return { error: { message: "Card declined" } }; + } + return { paymentIntent: { status: "succeeded" } }; + }, + }); + }, + [options.failPayment], + ); + }); + }, +}); + +// Usage +test("handles declined card", async ({ page, mockStripe }) => { + await mockStripe({ failPayment: true }); + + await page.goto("/checkout"); + await page.getByRole("button", { name: "Pay" }).click(); + + await expect(page.getByText("Card declined")).toBeVisible(); +}); +``` + +## Email Verification + +### Mock Email API + +```typescript +test("email verification flow", async ({ page, request }) => { + let verificationToken: string; + + // Capture the verification email + await page.route("**/api/send-verification", async (route) => { + const body = route.request().postDataJSON(); + verificationToken = `mock-token-${Date.now()}`; + + // Don't actually send email, just store token + route.fulfill({ + json: { sent: true, messageId: "msg-123" }, + }); + }); + + // Mock token verification + await page.route("**/api/verify-email**", (route) => { + const url = new URL(route.request().url()); + const token = url.searchParams.get("token"); + + if (token === verificationToken) { + route.fulfill({ json: { verified: true } }); + } else { + route.fulfill({ status: 400, json: { error: "Invalid token" } }); + } + }); + + await page.goto("/signup"); + await page.getByLabel("Email").fill("test@example.com"); + await page.getByRole("button", { name: "Sign Up" }).click(); + + await expect(page.getByText("Check your email")).toBeVisible(); + + // Simulate clicking email link + await page.goto(`/verify?token=${verificationToken}`); + + await expect(page.getByText("Email verified")).toBeVisible(); +}); +``` + +### Use Mailinator/Temp Mail + +```typescript +// fixtures/email.fixture.ts +type EmailFixtures = { + getVerificationEmail: (inbox: string) => Promise<{ link: string }>; +}; + +export const test = base.extend({ + getVerificationEmail: async ({ request }, use) => { + await use(async (inbox) => { + // Poll Mailinator API for new email + const response = await request.get( + `https://api.mailinator.com/v2/domains/public/inboxes/${inbox}`, + { + headers: { + Authorization: `Bearer ${process.env.MAILINATOR_API_KEY}`, + }, + }, + ); + + const messages = await response.json(); + const latest = messages.msgs[0]; + + // Get full message + const msgResponse = await request.get( + `https://api.mailinator.com/v2/domains/public/inboxes/${inbox}/messages/${latest.id}`, + { + headers: { + Authorization: `Bearer ${process.env.MAILINATOR_API_KEY}`, + }, + }, + ); + + const message = await msgResponse.json(); + + // Extract verification link from HTML + const linkMatch = message.parts[0].body.match( + /href="([^"]*verify[^"]*)"/, + ); + return { link: linkMatch?.[1] || "" }; + }); + }, +}); +``` + +## SMS Verification + +### Mock SMS API + +```typescript +test("SMS verification", async ({ page }) => { + let smsCode: string; + + // Capture SMS send + await page.route("**/api/send-sms", (route) => { + smsCode = Math.random().toString().slice(2, 8); // 6-digit code + + route.fulfill({ + json: { sent: true, messageId: "sms-123" }, + }); + }); + + // Mock code verification + await page.route("**/api/verify-sms", (route) => { + const body = route.request().postDataJSON(); + + if (body.code === smsCode) { + route.fulfill({ json: { verified: true } }); + } else { + route.fulfill({ status: 400, json: { error: "Invalid code" } }); + } + }); + + await page.goto("/verify-phone"); + await page.getByLabel("Phone").fill("+1234567890"); + await page.getByRole("button", { name: "Send Code" }).click(); + + // Enter the code + await page.getByLabel("Verification Code").fill(smsCode); + await page.getByRole("button", { name: "Verify" }).click(); + + await expect(page.getByText("Phone verified")).toBeVisible(); +}); +``` + +## Analytics & Tracking + +### Block Analytics in Tests + +```typescript +test.beforeEach(async ({ page }) => { + // Block all analytics/tracking + await page.route( + /google-analytics|googletagmanager|facebook|hotjar|segment|mixpanel|amplitude/, + (route) => route.abort(), + ); +}); +``` + +### Mock Analytics for Verification + +```typescript +test("tracks purchase event", async ({ page }) => { + const analyticsEvents: any[] = []; + + // Capture analytics calls + await page.route("**/api/analytics/**", (route) => { + analyticsEvents.push(route.request().postDataJSON()); + route.fulfill({ status: 200 }); + }); + + // Mock analytics SDK + await page.addInitScript(() => { + (window as any).analytics = { + track: (event: string, props: any) => { + fetch("/api/analytics/track", { + method: "POST", + body: JSON.stringify({ event, props }), + }); + }, + }; + }); + + await page.goto("/checkout"); + await page.getByRole("button", { name: "Complete Purchase" }).click(); + + // Verify analytics event was sent + expect(analyticsEvents).toContainEqual( + expect.objectContaining({ + event: "Purchase Completed", + props: expect.objectContaining({ amount: expect.any(Number) }), + }), + ); +}); +``` + +## Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Solution | +| ------------------------- | ------------------------------ | ----------------------- | +| Using real OAuth in tests | Slow, needs credentials, flaky | Mock OAuth endpoints | +| Real payment processing | Charges real money, slow | Use test mode or mock | +| Waiting for real emails | Very slow, unreliable | Mock email API | +| Not mocking analytics | Pollutes analytics data | Block or mock analytics | + +## Related References + +- **Network Mocking**: See [network-advanced.md](network-advanced.md) for route patterns +- **Authentication**: See [fixtures-hooks.md](../core/fixtures-hooks.md) for auth patterns diff --git a/.cursor/skills/playwright-testing/architecture/pom-vs-fixtures.md b/.cursor/skills/playwright-testing/architecture/pom-vs-fixtures.md new file mode 100644 index 0000000000..eafb06f767 --- /dev/null +++ b/.cursor/skills/playwright-testing/architecture/pom-vs-fixtures.md @@ -0,0 +1,363 @@ +# Organizing Reusable Test Code + +## Table of Contents + +1. [Pattern Comparison](#pattern-comparison) +2. [Selection Flowchart](#selection-flowchart) +3. [Page Objects](#page-objects) +4. [Custom Fixtures](#custom-fixtures) +5. [Helper Functions](#helper-functions) +6. [Combined Project Structure](#combined-project-structure) +7. [Anti-Patterns](#anti-patterns) + +Use all three patterns together. Most projects benefit from a hybrid approach: + +- **Page objects** for UI interaction (pages/components with 5+ interactions) +- **Custom fixtures** for test infrastructure (auth state, database, API clients, anything with lifecycle) +- **Helper functions** for stateless utilities (generate data, format values, simple waits) + +If only using one pattern, choose **custom fixtures** — they handle setup/teardown, compose well, and Playwright is built around them. + +## Pattern Comparison + +| Aspect | Page Objects | Custom Fixtures | Helper Functions | +|---|---|---|---| +| **Purpose** | Encapsulate UI interactions | Provide resources with setup/teardown | Stateless utilities | +| **Lifecycle** | Manual (constructor/methods) | Built-in (`use()` with automatic teardown) | None | +| **Composability** | Constructor injection or fixture wiring | Depend on other fixtures | Call other functions | +| **Best for** | Pages with many reused interactions | Resources needing setup AND teardown | Simple logic with no side effects | + +## Selection Flowchart + +```text +What kind of reusable code? +| ++-- Interacts with browser page/component? +| | +| +-- Has 5+ interactions (fill, click, navigate, assert)? +| | +-- YES: Used in 3+ test files? +| | | +-- YES --> PAGE OBJECT +| | | +-- NO --> Inline or small helper +| | +-- NO --> HELPER FUNCTION +| | +| +-- Needs setup before AND cleanup after test? +| +-- YES --> CUSTOM FIXTURE +| +-- NO --> PAGE OBJECT method or HELPER +| ++-- Manages resource with lifecycle (create/destroy)? +| +-- Examples: auth state, DB connection, API client, test user +| +-- YES --> CUSTOM FIXTURE (always) +| ++-- Stateless utility? (no browser, no side effects) +| +-- Examples: random email, format date, build URL, parse response +| +-- YES --> HELPER FUNCTION +| ++-- Not sure? + +-- Start with HELPER FUNCTION + +-- Promote to PAGE OBJECT when interactions grow + +-- Promote to FIXTURE when lifecycle needed +``` + +## Page Objects + +Best for pages/components with 5+ interactions appearing in 3+ test files. + +```typescript +// page-objects/booking.page.ts +import { type Page, type Locator, expect } from '@playwright/test'; + +export class BookingPage { + readonly page: Page; + readonly dateField: Locator; + readonly guestCount: Locator; + readonly roomType: Locator; + readonly reserveBtn: Locator; + readonly totalPrice: Locator; + + constructor(page: Page) { + this.page = page; + this.dateField = page.getByLabel('Check-in date'); + this.guestCount = page.getByLabel('Guests'); + this.roomType = page.getByLabel('Room type'); + this.reserveBtn = page.getByRole('button', { name: 'Reserve' }); + this.totalPrice = page.getByTestId('total-price'); + } + + async goto() { + await this.page.goto('/booking'); + } + + async fillDetails(opts: { date: string; guests: number; room: string }) { + await this.dateField.fill(opts.date); + await this.guestCount.fill(String(opts.guests)); + await this.roomType.selectOption(opts.room); + } + + async reserve() { + await this.reserveBtn.click(); + await this.page.waitForURL('**/confirmation'); + } + + async expectPrice(amount: string) { + await expect(this.totalPrice).toHaveText(amount); + } +} +``` + +```typescript +// tests/booking/reservation.spec.ts +import { test, expect } from '@playwright/test'; +import { BookingPage } from '../page-objects/booking.page'; + +test('complete reservation with standard room', async ({ page }) => { + const booking = new BookingPage(page); + await booking.goto(); + await booking.fillDetails({ date: '2026-03-15', guests: 2, room: 'standard' }); + await booking.reserve(); + await expect(page.getByText('Reservation confirmed')).toBeVisible(); +}); +``` + +**Page object principles:** +- One class per logical page/component, not per URL +- Constructor takes `Page` +- Locators as `readonly` properties in constructor +- Methods represent user intent (`reserve`, `fillDetails`), not low-level clicks +- Navigation methods (`goto`) belong on the page object + +## Custom Fixtures + +Best for resources needing setup before and teardown after tests — auth state, database connections, API clients, test users. + +```typescript +// fixtures/base.fixture.ts +import { test as base, expect } from '@playwright/test'; +import { BookingPage } from '../page-objects/booking.page'; +import { generateMember } from '../helpers/data'; + +type Fixtures = { + bookingPage: BookingPage; + member: { email: string; password: string; id: string }; + loggedInPage: import('@playwright/test').Page; +}; + +export const test = base.extend({ + bookingPage: async ({ page }, use) => { + await use(new BookingPage(page)); + }, + + member: async ({ request }, use) => { + const data = generateMember(); + const res = await request.post('/api/test/members', { data }); + const member = await res.json(); + await use(member); + await request.delete(`/api/test/members/${member.id}`); + }, + + loggedInPage: async ({ page, member }, use) => { + await page.goto('/login'); + await page.getByLabel('Email').fill(member.email); + await page.getByLabel('Password').fill(member.password); + await page.getByRole('button', { name: 'Sign in' }).click(); + await expect(page).toHaveURL('/dashboard'); + await use(page); + }, +}); + +export { expect } from '@playwright/test'; +``` + +```typescript +// tests/dashboard/overview.spec.ts +import { test, expect } from '../../fixtures/base.fixture'; + +test('member sees dashboard widgets', async ({ loggedInPage }) => { + await expect(loggedInPage.getByRole('heading', { name: 'Dashboard' })).toBeVisible(); + await expect(loggedInPage.getByTestId('stats-widget')).toBeVisible(); +}); + +test('new member sees welcome prompt', async ({ loggedInPage, member }) => { + await expect(loggedInPage.getByText(`Welcome, ${member.email}`)).toBeVisible(); +}); +``` + +**Fixture principles:** +- Use `test.extend()` — never module-level variables +- `use()` callback separates setup from teardown +- Teardown runs even if test fails +- Fixtures compose: one can depend on another +- Fixtures are lazy: created only when requested +- Wrap page objects in fixtures for lifecycle management + +## Helper Functions + +Best for stateless utilities — generating test data, formatting values, building URLs, parsing responses. + +```typescript +// helpers/data.ts +import { randomUUID } from 'node:crypto'; + +export function generateEmail(prefix = 'user'): string { + return `${prefix}-${Date.now()}-${randomUUID().slice(0, 8)}@test.local`; +} + +export function generateMember(overrides: Partial = {}): Member { + return { + email: generateEmail(), + password: 'SecurePass456!', + name: 'Test Member', + ...overrides, + }; +} + +interface Member { + email: string; + password: string; + name: string; +} + +export function formatPrice(cents: number): string { + return `$${(cents / 100).toFixed(2)}`; +} +``` + +```typescript +// helpers/assertions.ts +import { type Page, expect } from '@playwright/test'; + +export async function expectNotification(page: Page, message: string): Promise { + const notification = page.getByRole('alert').filter({ hasText: message }); + await expect(notification).toBeVisible(); + await expect(notification).toBeHidden({ timeout: 10000 }); +} +``` + +```typescript +// tests/settings/account.spec.ts +import { test, expect } from '@playwright/test'; +import { generateEmail } from '../../helpers/data'; +import { expectNotification } from '../../helpers/assertions'; + +test('update account email', async ({ page }) => { + const newEmail = generateEmail('updated'); + await page.goto('/settings/account'); + await page.getByLabel('Email').fill(newEmail); + await page.getByRole('button', { name: 'Save' }).click(); + await expectNotification(page, 'Account updated'); + await expect(page.getByLabel('Email')).toHaveValue(newEmail); +}); +``` + +**Helper principles:** +- Pure functions with no side effects +- No browser state — take `page` as parameter if needed +- Promote to fixture if setup/teardown needed +- Promote to page object if many page interactions grow +- Keep small and focused + +## Combined Project Structure + +```text +tests/ ++-- fixtures/ +| +-- auth.fixture.ts +| +-- db.fixture.ts +| +-- base.fixture.ts ++-- page-objects/ +| +-- login.page.ts +| +-- booking.page.ts +| +-- components/ +| +-- data-table.component.ts ++-- helpers/ +| +-- data.ts +| +-- assertions.ts ++-- e2e/ +| +-- auth/ +| | +-- login.spec.ts +| +-- booking/ +| +-- reservation.spec.ts +playwright.config.ts +``` + +**Layer responsibilities:** + +| Layer | Pattern | Responsibility | +|---|---|---| +| **Test file** | `test()` | Describes behavior, orchestrates layers | +| **Fixtures** | `test.extend()` | Resource lifecycle — setup, provide, teardown | +| **Page objects** | Classes | UI interaction — navigation, actions, locators | +| **Helpers** | Functions | Utilities — data generation, formatting, assertions | + +## Anti-Patterns + +### Page object managing resources + +```typescript +// BAD: page object handling API calls and database +class LoginPage { + async createUser() { /* API call */ } + async deleteUser() { /* API call */ } + async signIn(email: string, password: string) { /* UI */ } +} +``` + +Resource lifecycle belongs in fixtures where teardown is guaranteed. Keep only `signIn` in the page object. + +### Locator-only page objects + +```typescript +// BAD: no methods, just locators +class LoginPage { + emailInput = this.page.getByLabel('Email'); + passwordInput = this.page.getByLabel('Password'); + submitBtn = this.page.getByRole('button', { name: 'Sign in' }); + constructor(private page: Page) {} +} +``` + +Add intent-revealing methods or skip the page object entirely. + +### Monolithic fixtures + +```typescript +// BAD: one fixture doing everything +test.extend({ + everything: async ({ page, request }, use) => { + const user = await createUser(request); + const products = await seedProducts(request, 50); + await setupPayment(request, user.id); + await page.goto('/dashboard'); + await use({ user, products, page }); + // massive teardown... + }, +}); +``` + +Break into small, composable fixtures. Each fixture does one thing. + +### Helpers with side effects + +```typescript +// BAD: module-level state +let createdUserId: string; + +export async function createTestUser(request: APIRequestContext) { + const res = await request.post('/api/users', { data: { email: 'test@example.com' } }); + const user = await res.json(); + createdUserId = user.id; // shared across tests! + return user; +} +``` + +Module-level state leaks between parallel tests. If it has side effects and needs cleanup, make it a fixture. + +### Over-abstracting simple operations + +```typescript +// BAD: helper for one-liner +export async function clickButton(page: Page, name: string) { + await page.getByRole('button', { name }).click(); +} +``` + +Only abstract when there is real duplication (3+ usages) or complexity (5+ interactions). diff --git a/.cursor/skills/playwright-testing/architecture/test-architecture.md b/.cursor/skills/playwright-testing/architecture/test-architecture.md new file mode 100644 index 0000000000..28b6f6c9c5 --- /dev/null +++ b/.cursor/skills/playwright-testing/architecture/test-architecture.md @@ -0,0 +1,369 @@ +# Choosing Test Types: E2E, Component, or API + +## Table of Contents + +1. [Decision Matrix](#decision-matrix) +2. [API Tests](#api-tests) +3. [Component Tests](#component-tests) +4. [E2E Tests](#e2e-tests) +5. [Layering Test Types](#layering-test-types) +6. [Common Mistakes](#common-mistakes) +7. [Related](#related) + +> **When to use**: Deciding which test type to write for a feature. Ask: "What's the cheapest test that gives confidence this works?" + +## Decision Matrix + +| Scenario | Recommended Type | Rationale | +| --------------------------- | ---------------- | --------------------------------------------- | +| Login / auth flow | E2E | Cross-page, cookies, redirects, session state | +| Form submission | Component | Isolated validation logic, error states | +| CRUD operations | API | Data integrity matters more than UI | +| Search with results UI | Component + API | API for query logic; component for rendering | +| Cross-page navigation | E2E | Routing, history, deep linking | +| API error handling | API | Status codes, error shapes, edge cases | +| UI error feedback | Component | Toast, banner, inline error rendering | +| Accessibility | Component | ARIA roles, keyboard nav per-component | +| Responsive layout | Component | Viewport-specific rendering without full app | +| API contract validation | API | Response shapes, headers, auth | +| WebSocket/real-time | E2E | Requires full browser environment | +| Payment / checkout | E2E | Multi-step, third-party iframes | +| Onboarding wizard | E2E | Multi-step, state persists across pages | +| Widget behavior | Component | Toggle, accordion, date picker, modal | +| Permissions / authorization | API | Role-based access is backend logic | + +## API Tests + +**Ideal for**: + +- CRUD operations (create, read, update, delete) +- Input validation and error responses (400, 422) +- Permission and authorization checks +- Data integrity and business rules +- API contract verification +- Edge cases expensive to reproduce through UI +- Test data setup/teardown for E2E tests + +**Avoid for**: + +- Testing how errors display to users +- Browser-specific behavior (cookies, redirects) +- Visual layout or responsive design +- Flows requiring JavaScript execution or DOM interaction +- Third-party iframe interactions + +```typescript +import { test, expect } from "@playwright/test"; + +test.describe("Products API", () => { + let token: string; + + test.beforeAll(async ({ request }) => { + const res = await request.post("/api/auth/token", { + data: { email: "manager@shop.io", password: "mgr-secret" }, + }); + token = (await res.json()).accessToken; + }); + + test("creates product with valid payload", async ({ request }) => { + const res = await request.post("/api/products", { + headers: { Authorization: `Bearer ${token}` }, + data: { name: "Widget Pro", sku: "WGT-100", price: 29.99 }, + }); + + expect(res.status()).toBe(201); + const product = await res.json(); + expect(product).toMatchObject({ name: "Widget Pro", sku: "WGT-100" }); + expect(product).toHaveProperty("id"); + }); + + test("rejects duplicate SKU with 409", async ({ request }) => { + const res = await request.post("/api/products", { + headers: { Authorization: `Bearer ${token}` }, + data: { name: "Duplicate", sku: "WGT-100", price: 19.99 }, + }); + + expect(res.status()).toBe(409); + expect((await res.json()).message).toContain("already exists"); + }); + + test("returns 422 for missing required fields", async ({ request }) => { + const res = await request.post("/api/products", { + headers: { Authorization: `Bearer ${token}` }, + data: { name: "Incomplete" }, + }); + + expect(res.status()).toBe(422); + const err = await res.json(); + expect(err.errors).toContainEqual( + expect.objectContaining({ field: "sku" }) + ); + }); + + test("staff role cannot delete products", async ({ request }) => { + const staffLogin = await request.post("/api/auth/token", { + data: { email: "staff@shop.io", password: "staff-pass" }, + }); + const staffToken = (await staffLogin.json()).accessToken; + + const res = await request.delete("/api/products/123", { + headers: { Authorization: `Bearer ${staffToken}` }, + }); + + expect(res.status()).toBe(403); + }); + + test("lists products with pagination", async ({ request }) => { + const res = await request.get("/api/products", { + headers: { Authorization: `Bearer ${token}` }, + params: { page: "1", limit: "20" }, + }); + + expect(res.status()).toBe(200); + const body = await res.json(); + expect(body.items).toBeInstanceOf(Array); + expect(body.items.length).toBeLessThanOrEqual(20); + expect(body).toHaveProperty("totalCount"); + }); +}); +``` + +## Component Tests + +**Ideal for**: + +- Form validation (required fields, format rules, error messages) +- Interactive widgets (modals, dropdowns, accordions, date pickers) +- Conditional rendering (show/hide, loading states, empty states) +- Accessibility per-component (ARIA attributes, keyboard navigation) +- Responsive layout at different viewports +- Visual states (hover, focus, disabled, selected) + +**Avoid for**: + +- Testing routing or navigation between pages +- Flows requiring real cookies, sessions, or server-side state +- Data persistence or API contract validation +- Third-party iframe interactions +- Anything requiring multiple pages or browser contexts + +```typescript +import { test, expect } from "@playwright/experimental-ct-react"; +import { ContactForm } from "../src/components/ContactForm"; + +test.describe("ContactForm component", () => { + test("displays validation errors on empty submit", async ({ mount }) => { + const component = await mount( {}} />); + + await component.getByRole("button", { name: "Send message" }).click(); + + await expect(component.getByText("Name is required")).toBeVisible(); + await expect(component.getByText("Email is required")).toBeVisible(); + }); + + test("rejects malformed email", async ({ mount }) => { + const component = await mount( {}} />); + + await component.getByLabel("Name").fill("Alex"); + await component.getByLabel("Email").fill("invalid-email"); + await component.getByLabel("Message").fill("Hello"); + await component.getByRole("button", { name: "Send message" }).click(); + + await expect(component.getByText("Enter a valid email")).toBeVisible(); + }); + + test("invokes onSubmit with form data", async ({ mount }) => { + const submissions: Array<{ name: string; email: string; message: string }> = + []; + const component = await mount( + submissions.push(data)} /> + ); + + await component.getByLabel("Name").fill("Alex"); + await component.getByLabel("Email").fill("alex@company.org"); + await component.getByLabel("Message").fill("Inquiry about pricing"); + await component.getByRole("button", { name: "Send message" }).click(); + + expect(submissions).toHaveLength(1); + expect(submissions[0]).toEqual({ + name: "Alex", + email: "alex@company.org", + message: "Inquiry about pricing", + }); + }); + + test("disables button during submission", async ({ mount }) => { + const component = await mount( + {}} submitting={true} /> + ); + + await expect( + component.getByRole("button", { name: "Sending..." }) + ).toBeDisabled(); + }); + + test("associates labels with inputs for accessibility", async ({ mount }) => { + const component = await mount( {}} />); + + await expect( + component.getByRole("textbox", { name: "Name" }) + ).toBeVisible(); + await expect( + component.getByRole("textbox", { name: "Email" }) + ).toBeVisible(); + }); +}); +``` + +## E2E Tests + +**Ideal for**: + +- Critical user flows that generate revenue (checkout, signup) +- Authentication flows (login, SSO, MFA, password reset) +- Multi-page workflows where state carries across navigation +- Flows involving third-party iframes (payment widgets) +- Smoke tests validating the entire stack +- Real-time collaboration requiring multiple browser contexts + +**Avoid for**: + +- Testing every form validation permutation +- CRUD operations where UI is a thin wrapper +- Verifying individual component states +- Testing API response shapes or error codes +- Responsive layout at every breakpoint +- Edge cases that only affect the backend + +```typescript +import { test, expect } from "@playwright/test"; + +test.describe("subscription flow", () => { + test.beforeEach(async ({ page }) => { + await page.request.post("/api/test/seed-account", { + data: { plan: "free", email: "subscriber@demo.io" }, + }); + await page.goto("/account/upgrade"); + }); + + test("upgrades to premium plan", async ({ page }) => { + await test.step("select plan", async () => { + await expect( + page.getByRole("heading", { name: "Choose Your Plan" }) + ).toBeVisible(); + await page.getByRole("button", { name: "Select Premium" }).click(); + }); + + await test.step("enter billing details", async () => { + await page.getByLabel("Cardholder name").fill("Sam Johnson"); + await page.getByLabel("Billing address").fill("456 Oak Ave"); + await page.getByLabel("City").fill("Seattle"); + await page.getByRole("combobox", { name: "State" }).selectOption("WA"); + await page.getByLabel("Postal code").fill("98101"); + await page.getByRole("button", { name: "Continue" }).click(); + }); + + await test.step("complete payment", async () => { + const paymentFrame = page.frameLocator('iframe[title="Secure Payment"]'); + await paymentFrame.getByLabel("Card number").fill("5555555555554444"); + await paymentFrame.getByLabel("Expiry").fill("09/29"); + await paymentFrame.getByLabel("CVV").fill("456"); + await page.getByRole("button", { name: "Subscribe now" }).click(); + }); + + await test.step("verify success", async () => { + await page.waitForURL("**/account/subscription/success**"); + await expect( + page.getByRole("heading", { name: "Welcome to Premium" }) + ).toBeVisible(); + await expect(page.getByText(/Subscription #\d+/)).toBeVisible(); + }); + }); +}); +``` + +## Layering Test Types + +Effective test suites combine all three types. Example for an "inventory management" feature: + +### API Layer (60% of tests) + +Cover every backend logic permutation. Cheap to run and maintain. + +``` +tests/api/inventory.spec.ts + - creates item with valid data (201) + - rejects duplicate SKU (409) + - rejects invalid quantity format (422) + - rejects missing required fields (422) + - warehouse-staff cannot delete items (403) + - unauthenticated request returns 401 + - lists items with pagination + - filters items by category + - updates item stock level + - archives an item + - prevents archiving items with pending orders +``` + +### Component Layer (30% of tests) + +Cover every visual state and interaction. + +``` +tests/components/InventoryForm.spec.tsx + - shows validation errors on empty submit + - shows inline error for invalid SKU format + - disables submit while saving + - calls onSubmit with form data + - resets form after successful save + +tests/components/InventoryTable.spec.tsx + - renders item rows from props + - shows empty state when no items + - handles archive confirmation modal + - sorts by column header click + - shows stock level badges with correct colors +``` + +### E2E Layer (10% of tests) + +Cover only critical paths proving full stack works. + +``` +tests/e2e/inventory.spec.ts + - manager creates item and sees it in list + - manager updates item stock level + - warehouse-staff cannot access admin settings +``` + +### Execution Profile + +For this feature: + +- **11 API tests** — ~2 seconds total, no browser +- **10 component tests** — ~5 seconds total, real browser but no server +- **3 E2E tests** — ~15 seconds total, full stack + +Total: 24 tests, ~22 seconds. API tests catch most regressions. Component tests catch UI bugs. E2E tests prove wiring works. If E2E fails but API and component pass, the problem is in integration (routing, state management, API client). + +## Common Mistakes + +| Anti-Pattern | Problem | Better Approach | +| ----------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------- | +| E2E for every validation rule | 30-second browser test for something API covers in 200ms | API test for validation, one component test for error display | +| No API tests, all E2E | Slow suite, flaky from UI timing, hard to diagnose | API tests for data/logic, E2E for critical paths only | +| Component tests mocking everything | Tests pass but app broken because mocks drift | Mock only external boundaries; API tests verify real contracts | +| Same assertion in API, component, AND E2E | Triple maintenance cost | Each layer tests what it uniquely verifies | +| E2E creating test data via UI | 2-minute test where 90 seconds is setup | Seed via API in `beforeEach`, test actual flow | +| Testing third-party behavior | Testing that Stripe validates cards (Stripe's job) | Mock Stripe; trust their contract | +| Skipping API layer | Can't tell if bug is frontend or backend | API tests isolate backend; component tests isolate frontend | +| One giant E2E for entire feature | 5-minute test failing somewhere with no clear cause | Focused E2E per critical path; use `test.step()` | + +## Related + +- [test-suite-structure.md](../core/test-suite-structure.md) — file structure and naming +- [api-testing.md](../testing-patterns/api-testing.md) — Playwright's `request` API for HTTP testing +- [component-testing.md](../testing-patterns/component-testing.md) — setting up component tests +- [authentication.md](../advanced/authentication.md) — auth flow patterns with `storageState` +- [when-to-mock.md](when-to-mock.md) — when to mock vs hit real services +- [pom-vs-fixtures.md](pom-vs-fixtures.md) — organizing shared test logic diff --git a/.cursor/skills/playwright-testing/architecture/when-to-mock.md b/.cursor/skills/playwright-testing/architecture/when-to-mock.md new file mode 100644 index 0000000000..d5d5705b1f --- /dev/null +++ b/.cursor/skills/playwright-testing/architecture/when-to-mock.md @@ -0,0 +1,383 @@ +# Mocking Strategy: Real vs Mock Services + +## Table of Contents + +1. [Core Principle](#core-principle) +2. [Decision Matrix](#decision-matrix) +3. [Decision Flowchart](#decision-flowchart) +4. [Mocking Techniques](#mocking-techniques) +5. [Real Service Strategies](#real-service-strategies) +6. [Hybrid Approach: Fixture-Based Mock Control](#hybrid-approach-fixture-based-mock-control) +7. [Validating Mock Accuracy](#validating-mock-accuracy) +8. [Anti-Patterns](#anti-patterns) + +> **When to use**: Deciding whether to mock API calls, intercept network requests, or hit real services in Playwright tests. + +## Core Principle + +**Mock at the boundary, test your stack end-to-end.** Mock third-party services you don't own (payment gateways, email providers, OAuth). Never mock your own frontend-to-backend communication. Tests should prove YOUR code works, not that third-party APIs are available. + +## Decision Matrix + +| Scenario | Mock? | Strategy | +| --- | --- | --- | +| Your own REST/GraphQL API | Never | Hit real API against staging or local dev | +| Your database (through your API) | Never | Seed via API or fixtures | +| Authentication (your auth system) | Mostly no | Use `storageState` to skip login in most tests | +| Stripe / payment gateway | Always | `route.fulfill()` with expected responses | +| SendGrid / email service | Always | Mock the API call, verify request payload | +| OAuth providers (Google, GitHub) | Always | Mock token exchange, test your callback handler | +| Analytics (Segment, Mixpanel) | Always | `route.abort()` or `route.fulfill()` | +| Maps / geocoding APIs | Always | Mock with static responses | +| Feature flags (LaunchDarkly) | Usually | Mock to force specific flag states | +| CDN / static assets | Never | Let them load normally | +| Flaky external dependency | CI: mock, local: real | Conditional mocking based on environment | +| Slow external dependency | Dev: mock, nightly: real | Separate test projects in config | + +## Decision Flowchart + +```text +Is this service part of YOUR codebase? +├── YES → Do NOT mock. Test the real integration. +│ ├── Is it slow? → Optimize the service, not the test. +│ └── Is it flaky? → Fix the service. Flaky infra is a bug. +└── NO → It's a third-party service. + ├── Is it paid per call? → ALWAYS mock. + ├── Is it rate-limited? → ALWAYS mock. + ├── Is it slow or unreliable? → ALWAYS mock. + └── Is it a complex multi-step flow? → Mock with HAR recording. +``` + +## Mocking Techniques + +### Blocking Unwanted Requests + +Block third-party scripts that slow tests and add no coverage: + +```typescript +test.beforeEach(async ({ page }) => { + await page.route('**/{analytics,tracking,segment,hotjar}.{com,io}/**', (route) => { + route.abort(); + }); +}); + +test('dashboard renders without tracking scripts', async ({ page }) => { + await page.goto('/dashboard'); + await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible(); +}); +``` + +### Full Mock (route.fulfill) + +Completely replace a third-party API response: + +```typescript +test('order flow with mocked payment service', async ({ page }) => { + await page.route('**/api/charge', (route) => { + route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify({ + transactionId: 'txn_mock_abc', + status: 'completed', + }), + }); + }); + + await page.goto('/order/confirm'); + await page.getByRole('button', { name: 'Complete Purchase' }).click(); + await expect(page.getByText('Order confirmed')).toBeVisible(); +}); + +test('display error on payment decline', async ({ page }) => { + await page.route('**/api/charge', (route) => { + route.fulfill({ + status: 402, + contentType: 'application/json', + body: JSON.stringify({ + error: { code: 'insufficient_funds', message: 'Card declined.' }, + }), + }); + }); + + await page.goto('/order/confirm'); + await page.getByRole('button', { name: 'Complete Purchase' }).click(); + await expect(page.getByRole('alert')).toContainText('Card declined'); +}); +``` + +### Partial Mock (Modify Responses) + +Let the real API call happen but tweak the response: + +```typescript +test('display low inventory warning', async ({ page }) => { + await page.route('**/api/inventory/*', async (route) => { + const response = await route.fetch(); + const data = await response.json(); + + data.quantity = 1; + data.lowStock = true; + + await route.fulfill({ + response, + body: JSON.stringify(data), + }); + }); + + await page.goto('/products/widget-pro'); + await expect(page.getByText('Only 1 remaining')).toBeVisible(); +}); + +test('inject test notification into real response', async ({ page }) => { + await page.route('**/api/alerts', async (route) => { + const response = await route.fetch(); + const data = await response.json(); + + data.items.push({ + id: 'test-alert', + text: 'Report generated', + category: 'info', + }); + + await route.fulfill({ + response, + body: JSON.stringify(data), + }); + }); + + await page.goto('/home'); + await expect(page.getByText('Report generated')).toBeVisible(); +}); +``` + +### Record and Replay (HAR Files) + +For complex API sequences (OAuth flows, multi-step wizards): + +**Recording:** + +```typescript +test('capture API traffic for admin panel', async ({ page }) => { + await page.routeFromHAR('tests/fixtures/admin-panel.har', { + url: '**/api/**', + update: true, + }); + + await page.goto('/admin'); + await page.getByRole('tab', { name: 'Reports' }).click(); + await page.getByRole('tab', { name: 'Settings' }).click(); +}); +``` + +**Replaying:** + +```typescript +test('admin panel loads with recorded data', async ({ page }) => { + await page.routeFromHAR('tests/fixtures/admin-panel.har', { + url: '**/api/**', + update: false, + }); + + await page.goto('/admin'); + await expect(page.getByRole('heading', { name: 'Reports' })).toBeVisible(); +}); +``` + +**HAR maintenance:** + +- Record against a known-good staging environment +- Commit `.har` files to version control +- Re-record when APIs change +- Scope HAR to specific URL patterns + +## Real Service Strategies + +### Local Dev Server + +```typescript +// playwright.config.ts +export default defineConfig({ + webServer: { + command: 'npm run dev', + url: 'http://localhost:3000', + reuseExistingServer: !process.env.CI, + timeout: 30_000, + }, + use: { + baseURL: 'http://localhost:3000', + }, +}); +``` + +### Staging Environment + +```typescript +// playwright.config.ts +export default defineConfig({ + use: { + baseURL: process.env.CI + ? 'https://staging.example.com' + : 'http://localhost:3000', + }, +}); +``` + +### Test Containers + +```typescript +// playwright.config.ts +export default defineConfig({ + webServer: { + command: 'docker compose -f docker-compose.test.yml up --wait', + url: 'http://localhost:3000/health', + reuseExistingServer: !process.env.CI, + timeout: 120_000, + }, + globalTeardown: './tests/global-teardown.ts', +}); +``` + +```typescript +// tests/global-teardown.ts +import { execSync } from 'child_process'; + +export default function globalTeardown() { + if (process.env.CI) { + execSync('docker compose -f docker-compose.test.yml down -v'); + } +} +``` + +## Hybrid Approach: Fixture-Based Mock Control + +Create fixtures that let individual tests opt into mocking specific services: + +```typescript +// tests/fixtures/service-mocks.ts +import { test as base } from '@playwright/test'; + +type MockConfig = { + mockPayments: boolean; + mockNotifications: boolean; + mockAnalytics: boolean; +}; + +export const test = base.extend({ + mockPayments: [true, { option: true }], + mockNotifications: [true, { option: true }], + mockAnalytics: [true, { option: true }], + + page: async ({ page, mockPayments, mockNotifications, mockAnalytics }, use) => { + if (mockPayments) { + await page.route('**/api/billing/**', (route) => { + route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify({ status: 'paid', id: 'inv_mock_789' }), + }); + }); + } + + if (mockNotifications) { + await page.route('**/api/notify', (route) => { + route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify({ delivered: true }), + }); + }); + } + + if (mockAnalytics) { + await page.route('**/{segment,mixpanel,amplitude}.**/**', (route) => { + route.abort(); + }); + } + + await use(page); + }, +}); + +export { expect } from '@playwright/test'; +``` + +```typescript +// tests/billing.spec.ts +import { test, expect } from './fixtures/service-mocks'; + +test('subscription renewal sends notification', async ({ page }) => { + await page.goto('/account/billing'); + await page.getByRole('button', { name: 'Renew Now' }).click(); + await expect(page.getByText('Subscription renewed')).toBeVisible(); +}); + +test.describe('integration suite', () => { + test.use({ mockPayments: false }); + + test('real billing flow against test gateway', async ({ page }) => { + await page.goto('/account/billing'); + await page.getByRole('button', { name: 'Renew Now' }).click(); + await expect(page.getByText('Subscription renewed')).toBeVisible(); + }); +}); +``` + +### Environment-Based Test Projects + +```typescript +// playwright.config.ts +export default defineConfig({ + projects: [ + { + name: 'ci-fast', + testMatch: '**/*.spec.ts', + use: { baseURL: 'http://localhost:3000' }, + }, + { + name: 'nightly-full', + testMatch: '**/*.integration.spec.ts', + use: { baseURL: 'https://staging.example.com' }, + timeout: 120_000, + }, + ], +}); +``` + +## Validating Mock Accuracy + +Guard against mock drift from real APIs: + +```typescript +test.describe('contract validation', () => { + test('billing mock matches real API shape', async ({ request }) => { + const realResponse = await request.post('/api/billing/charge', { + data: { amount: 5000, currency: 'usd' }, + }); + const realBody = await realResponse.json(); + + const mockBody = { + status: 'paid', + id: 'inv_mock_789', + }; + + expect(Object.keys(mockBody).sort()).toEqual(Object.keys(realBody).sort()); + + for (const key of Object.keys(mockBody)) { + expect(typeof mockBody[key]).toBe(typeof realBody[key]); + } + }); +}); +``` + +## Anti-Patterns + +| Don't Do This | Problem | Do This Instead | +| --- | --- | --- | +| Mock your own API | Tests pass, app breaks. Zero integration coverage. | Hit your real API. Mock only third-party services. | +| Mock everything for speed | You test a fiction. Frontend and backend may be incompatible. | Mock only external boundaries. | +| Never mock anything | Tests are slow, flaky, fail when third parties have outages. | Mock third-party services. | +| Use outdated mocks | Mock returns different shape than real API. | Run contract validation tests. Re-record HAR files regularly. | +| Mock with `page.evaluate()` to stub fetch | Fragile, doesn't survive navigation. | Use `page.route()` which intercepts at network layer. | +| Copy-paste mocks across files | One API change requires updating many files. | Centralize mocks in fixtures. | +| Block all network and whitelist | Extremely brittle. Every new endpoint requires update. | Allow all by default. Selectively mock third-party services. | diff --git a/.cursor/skills/playwright-testing/browser-apis/browser-apis.md b/.cursor/skills/playwright-testing/browser-apis/browser-apis.md new file mode 100644 index 0000000000..cc4c269e8f --- /dev/null +++ b/.cursor/skills/playwright-testing/browser-apis/browser-apis.md @@ -0,0 +1,391 @@ +# Browser APIs: Geolocation, Permissions & More + +## Table of Contents + +1. [Geolocation](#geolocation) +2. [Permissions](#permissions) +3. [Clipboard](#clipboard) +4. [Notifications](#notifications) +5. [Camera & Microphone](#camera--microphone) + +## Geolocation + +### Mock Location + +```typescript +test("shows nearby stores", async ({ context }) => { + // Grant permission and set location + await context.grantPermissions(["geolocation"]); + await context.setGeolocation({ latitude: 37.7749, longitude: -122.4194 }); // San Francisco + + const page = await context.newPage(); + await page.goto("/store-finder"); + await page.getByRole("button", { name: "Find Nearby" }).click(); + + await expect(page.getByText("San Francisco")).toBeVisible(); +}); +``` + +### Geolocation Fixture + +```typescript +// fixtures/geolocation.fixture.ts +import { test as base } from "@playwright/test"; + +type Coordinates = { latitude: number; longitude: number; accuracy?: number }; + +type GeoFixtures = { + setLocation: (coords: Coordinates) => Promise; +}; + +export const test = base.extend({ + setLocation: async ({ context }, use) => { + await context.grantPermissions(["geolocation"]); + + await use(async (coords) => { + await context.setGeolocation({ + latitude: coords.latitude, + longitude: coords.longitude, + accuracy: coords.accuracy ?? 100, + }); + }); + }, +}); + +// Usage +test("delivery zone check", async ({ page, setLocation }) => { + await setLocation({ latitude: 40.7128, longitude: -74.006 }); // NYC + + await page.goto("/delivery"); + + await expect(page.getByText("Delivery available")).toBeVisible(); +}); +``` + +### Test Location Changes + +```typescript +test("tracks location updates", async ({ context }) => { + await context.grantPermissions(["geolocation"]); + + const page = await context.newPage(); + await page.goto("/tracking"); + + // Initial location + await context.setGeolocation({ latitude: 37.7749, longitude: -122.4194 }); + await page.getByRole("button", { name: "Start Tracking" }).click(); + + await expect(page.getByTestId("location")).toContainText("37.7749"); + + // Move to new location + await context.setGeolocation({ latitude: 37.8044, longitude: -122.2712 }); + + // Trigger location update + await page.evaluate(() => { + navigator.geolocation.getCurrentPosition(() => {}); + }); + + await expect(page.getByTestId("location")).toContainText("37.8044"); +}); +``` + +### Test Geolocation Denial + +```typescript +test("handles location denied", async ({ browser }) => { + // Create context without geolocation permission + const context = await browser.newContext({ + permissions: [], // No permissions + }); + + const page = await context.newPage(); + await page.goto("/store-finder"); + await page.getByRole("button", { name: "Find Nearby" }).click(); + + await expect(page.getByText("Location access denied")).toBeVisible(); + await expect(page.getByLabel("Enter ZIP code")).toBeVisible(); + + await context.close(); +}); +``` + +## Permissions + +### Grant Permissions + +```typescript +test("notifications with permission", async ({ context }) => { + await context.grantPermissions(["notifications"]); + + const page = await context.newPage(); + await page.goto("/alerts"); + + // Notification API should work + const permission = await page.evaluate(() => Notification.permission); + expect(permission).toBe("granted"); +}); +``` + +### Test Permission Denied + +```typescript +test("handles notification permission denied", async ({ browser }) => { + const context = await browser.newContext({ + permissions: [], // Deny all + }); + + const page = await context.newPage(); + await page.goto("/notifications"); + + await page.getByRole("button", { name: "Enable Notifications" }).click(); + + await expect(page.getByText("Please enable notifications")).toBeVisible(); + + await context.close(); +}); +``` + +### Multiple Permissions + +```typescript +test("video call with permissions", async ({ context }) => { + await context.grantPermissions(["camera", "microphone", "notifications"]); + + const page = await context.newPage(); + await page.goto("/video-call"); + + // All permissions should be granted + const permissions = await page.evaluate(async () => ({ + camera: await navigator.permissions.query({ + name: "camera" as PermissionName, + }), + microphone: await navigator.permissions.query({ + name: "microphone" as PermissionName, + }), + })); + + expect(permissions.camera.state).toBe("granted"); + expect(permissions.microphone.state).toBe("granted"); +}); +``` + +## Clipboard + +### Test Copy to Clipboard + +```typescript +test("copy button works", async ({ page, context }) => { + // Grant clipboard permissions + await context.grantPermissions(["clipboard-read", "clipboard-write"]); + + await page.goto("/share"); + + await page.getByRole("button", { name: "Copy Link" }).click(); + + // Read clipboard content + const clipboardContent = await page.evaluate(() => + navigator.clipboard.readText(), + ); + + expect(clipboardContent).toContain("https://example.com/share/"); +}); +``` + +### Test Paste from Clipboard + +```typescript +test("paste from clipboard", async ({ page, context }) => { + await context.grantPermissions(["clipboard-read", "clipboard-write"]); + + await page.goto("/editor"); + + // Write to clipboard + await page.evaluate(() => navigator.clipboard.writeText("Pasted content")); + + // Trigger paste + await page.getByLabel("Content").focus(); + await page.keyboard.press("Control+V"); + + await expect(page.getByLabel("Content")).toHaveValue("Pasted content"); +}); +``` + +### Clipboard Fixture + +```typescript +// fixtures/clipboard.fixture.ts +import { test as base } from "@playwright/test"; + +type ClipboardFixtures = { + clipboard: { + write: (text: string) => Promise; + read: () => Promise; + }; +}; + +export const test = base.extend({ + clipboard: async ({ page, context }, use) => { + await context.grantPermissions(["clipboard-read", "clipboard-write"]); + + await use({ + write: async (text) => { + await page.evaluate((t) => navigator.clipboard.writeText(t), text); + }, + read: async () => { + return page.evaluate(() => navigator.clipboard.readText()); + }, + }); + }, +}); +``` + +## Notifications + +### Mock Notification API + +```typescript +test("shows browser notification", async ({ page }) => { + const notifications: any[] = []; + + // Mock Notification constructor + await page.addInitScript(() => { + (window as any).__notifications = []; + (window as any).Notification = class { + constructor(title: string, options?: NotificationOptions) { + (window as any).__notifications.push({ title, ...options }); + } + static permission = "granted"; + static requestPermission = async () => "granted"; + }; + }); + + await page.goto("/alerts"); + await page.getByRole("button", { name: "Notify Me" }).click(); + + // Check notification was created + const created = await page.evaluate(() => (window as any).__notifications); + expect(created).toHaveLength(1); + expect(created[0].title).toBe("New Alert"); +}); +``` + +### Test Notification Click + +```typescript +test("notification click handler", async ({ page }) => { + await page.addInitScript(() => { + (window as any).Notification = class { + onclick: (() => void) | null = null; + constructor(title: string) { + // Simulate click after creation + setTimeout(() => this.onclick?.(), 100); + } + static permission = "granted"; + static requestPermission = async () => "granted"; + }; + }); + + await page.goto("/messages"); + await page.evaluate(() => { + new Notification("New Message"); + }); + + // Should navigate to messages when notification clicked + await expect(page).toHaveURL(/\/messages/); +}); +``` + +## Camera & Microphone + +### Mock Media Devices + +```typescript +test("video preview works", async ({ page, context }) => { + await context.grantPermissions(["camera"]); + + // Mock getUserMedia + await page.addInitScript(() => { + navigator.mediaDevices.getUserMedia = async () => { + const canvas = document.createElement("canvas"); + canvas.width = 640; + canvas.height = 480; + return canvas.captureStream(); + }; + }); + + await page.goto("/video-settings"); + await page.getByRole("button", { name: "Start Camera" }).click(); + + await expect(page.getByTestId("video-preview")).toBeVisible(); +}); +``` + +### Test Media Device Selection + +```typescript +test("switch camera", async ({ page }) => { + await page.addInitScript(() => { + navigator.mediaDevices.enumerateDevices = async () => + [ + { + deviceId: "cam1", + kind: "videoinput", + label: "Front Camera", + groupId: "1", + }, + { + deviceId: "cam2", + kind: "videoinput", + label: "Back Camera", + groupId: "2", + }, + ] as MediaDeviceInfo[]; + + navigator.mediaDevices.getUserMedia = async () => { + const canvas = document.createElement("canvas"); + return canvas.captureStream(); + }; + }); + + await page.goto("/camera"); + + // Should show camera options + await expect(page.getByRole("combobox", { name: "Camera" })).toBeVisible(); + await expect(page.getByText("Front Camera")).toBeVisible(); + await expect(page.getByText("Back Camera")).toBeVisible(); +}); +``` + +### Test Media Errors + +```typescript +test("handles camera access error", async ({ page }) => { + await page.addInitScript(() => { + navigator.mediaDevices.getUserMedia = async () => { + throw new DOMException("Permission denied", "NotAllowedError"); + }; + }); + + await page.goto("/video-call"); + await page.getByRole("button", { name: "Join Call" }).click(); + + await expect(page.getByText("Camera access denied")).toBeVisible(); + await expect( + page.getByRole("button", { name: "Join Audio Only" }), + ).toBeVisible(); +}); +``` + +## Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Solution | +| ----------------------------- | --------------------------------- | ----------------------------------- | +| Not granting permissions | Tests fail with permission errors | Use `context.grantPermissions()` | +| Testing real geolocation | Flaky, environment-dependent | Mock with `setGeolocation()` | +| Not testing permission denial | Misses error handling | Test both granted and denied states | +| Using real camera/mic | CI has no devices | Mock `getUserMedia` | + +## Related References + +- **Fixtures**: See [fixtures-hooks.md](../core/fixtures-hooks.md) for context fixtures +- **Mobile**: See [mobile-testing.md](../advanced/mobile-testing.md) for device emulation diff --git a/.cursor/skills/playwright-testing/browser-apis/iframes.md b/.cursor/skills/playwright-testing/browser-apis/iframes.md new file mode 100644 index 0000000000..155cc1c1b4 --- /dev/null +++ b/.cursor/skills/playwright-testing/browser-apis/iframes.md @@ -0,0 +1,403 @@ +# iFrame Testing + +## Table of Contents + +1. [Basic iFrame Access](#basic-iframe-access) +2. [Cross-Origin iFrames](#cross-origin-iframes) +3. [Nested iFrames](#nested-iframes) +4. [Dynamic iFrames](#dynamic-iframes) +5. [iFrame Navigation](#iframe-navigation) +6. [Common Patterns](#common-patterns) + +## Basic iFrame Access + +### Using frameLocator + +```typescript +// Access iframe by selector +const frame = page.frameLocator("iframe#payment"); +await frame.getByRole("button", { name: "Pay" }).click(); + +// Access by name attribute +const namedFrame = page.frameLocator('iframe[name="checkout"]'); +await namedFrame.getByLabel("Card number").fill("4242424242424242"); + +// Access by title +const titledFrame = page.frameLocator('iframe[title="Payment Form"]'); + +// Access by src (partial match) +const srcFrame = page.frameLocator('iframe[src*="stripe.com"]'); +``` + +### Frame vs FrameLocator + +```typescript +// frameLocator - for locator-based operations (recommended) +const frameLocator = page.frameLocator("#my-iframe"); +await frameLocator.getByRole("button").click(); + +// frame() - for Frame object operations (navigation, evaluation) +const frame = page.frame({ name: "my-frame" }); +if (frame) { + await frame.goto("https://example.com"); + const title = await frame.title(); +} + +// Get all frames +const frames = page.frames(); +for (const f of frames) { + console.log("Frame URL:", f.url()); +} +``` + +### Waiting for iFrame Content + +```typescript +// Wait for iframe to load +const frame = page.frameLocator("#dynamic-iframe"); + +// Wait for element inside iframe +await expect(frame.getByRole("heading")).toBeVisible({ timeout: 10000 }); + +// Wait for iframe src to change +await page.waitForFunction(() => { + const iframe = document.querySelector("iframe#my-frame") as HTMLIFrameElement; + return iframe?.src.includes("loaded"); +}); +``` + +## Cross-Origin iFrames + +### Accessing Cross-Origin Content + +```typescript +// Cross-origin iframes work seamlessly with frameLocator +const thirdPartyFrame = page.frameLocator('iframe[src*="third-party.com"]'); + +// Interact with elements inside cross-origin iframe +await thirdPartyFrame.getByRole("textbox").fill("test@example.com"); +await thirdPartyFrame.getByRole("button", { name: "Submit" }).click(); + +// Wait for cross-origin iframe to be ready +await expect(thirdPartyFrame.locator("body")).toBeVisible(); +``` + +### Payment Provider iFrames (Stripe, PayPal) + +```typescript +test("Stripe payment iframe", async ({ page }) => { + await page.goto("/checkout"); + + // Stripe uses multiple iframes for each field + const cardFrame = page + .frameLocator('iframe[name*="__privateStripeFrame"]') + .first(); + + // Wait for Stripe to initialize + await expect(cardFrame.locator('[placeholder="Card number"]')).toBeVisible({ + timeout: 15000, + }); + + // Fill card details + await cardFrame + .locator('[placeholder="Card number"]') + .fill("4242424242424242"); + await cardFrame.locator('[placeholder="MM / YY"]').fill("12/30"); + await cardFrame.locator('[placeholder="CVC"]').fill("123"); +}); +``` + +### Handling OAuth in iFrames + +```typescript +test("OAuth iframe flow", async ({ page }) => { + await page.goto("/login"); + await page.getByRole("button", { name: "Sign in with Google" }).click(); + + // If OAuth opens in iframe instead of popup + const oauthFrame = page.frameLocator('iframe[src*="accounts.google.com"]'); + + // Wait for OAuth form + await expect(oauthFrame.getByLabel("Email")).toBeVisible({ timeout: 10000 }); + await oauthFrame.getByLabel("Email").fill("test@gmail.com"); +}); +``` + +## Nested iFrames + +### Accessing Nested Frames + +```typescript +// Parent iframe contains child iframe +const parentFrame = page.frameLocator("#outer-frame"); +const childFrame = parentFrame.frameLocator("#inner-frame"); + +// Interact with deeply nested content +await childFrame.getByRole("button", { name: "Submit" }).click(); + +// Multiple levels of nesting +const level1 = page.frameLocator("#level1"); +const level2 = level1.frameLocator("#level2"); +const level3 = level2.frameLocator("#level3"); +await level3.getByText("Deep content").click(); +``` + +### Finding Elements Across Frame Hierarchy + +```typescript +// Helper to search all frames for an element +async function findInAnyFrame( + page: Page, + selector: string, +): Promise { + // Check main page first + const mainCount = await page.locator(selector).count(); + if (mainCount > 0) return page.locator(selector); + + // Check all frames + for (const frame of page.frames()) { + const count = await frame.locator(selector).count(); + if (count > 0) { + return frame.locator(selector); + } + } + return null; +} + +test("find element in any frame", async ({ page }) => { + await page.goto("/complex-page"); + const element = await findInAnyFrame(page, '[data-testid="submit-btn"]'); + if (element) await element.click(); +}); +``` + +## Dynamic iFrames + +### iFrames Created at Runtime + +```typescript +test("handle dynamically created iframe", async ({ page }) => { + await page.goto("/dashboard"); + + // Click button that creates iframe + await page.getByRole("button", { name: "Open Widget" }).click(); + + // Wait for iframe to appear in DOM + await page.waitForSelector("iframe#widget-frame"); + + // Now access the frame + const widgetFrame = page.frameLocator("#widget-frame"); + await expect(widgetFrame.getByText("Widget Loaded")).toBeVisible(); +}); +``` + +### iFrames with Changing src + +```typescript +test("iframe src changes", async ({ page }) => { + await page.goto("/multi-step"); + + const frame = page.frameLocator("#step-frame"); + + // Step 1 + await expect(frame.getByText("Step 1")).toBeVisible(); + await frame.getByRole("button", { name: "Next" }).click(); + + // Wait for iframe to reload with new content + await expect(frame.getByText("Step 2")).toBeVisible({ timeout: 10000 }); + await frame.getByRole("button", { name: "Next" }).click(); + + // Step 3 + await expect(frame.getByText("Step 3")).toBeVisible({ timeout: 10000 }); +}); +``` + +### Lazy-Loaded iFrames + +```typescript +test("lazy loaded iframe", async ({ page }) => { + await page.goto("/page-with-lazy-iframe"); + + // Scroll to trigger lazy load + await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight)); + + // Wait for iframe to load + const lazyFrame = page.frameLocator("#lazy-iframe"); + await expect(lazyFrame.locator("body")).not.toBeEmpty({ timeout: 15000 }); + + // Interact with content + await lazyFrame.getByRole("button").click(); +}); +``` + +## iFrame Navigation + +### Navigating Within iFrame + +```typescript +test("iframe internal navigation", async ({ page }) => { + await page.goto("/app"); + + // Get frame object for navigation control + const frame = page.frame({ name: "content-frame" }); + if (!frame) throw new Error("Frame not found"); + + // Navigate within iframe + await frame.goto("https://embedded-app.com/page2"); + + // Wait for navigation + await frame.waitForURL("**/page2"); + + // Verify content + await expect(frame.getByRole("heading")).toHaveText("Page 2"); +}); +``` + +### Handling Frame Navigation Events + +```typescript +test("track iframe navigation", async ({ page }) => { + const navigations: string[] = []; + + // Listen to frame navigation + page.on("framenavigated", (frame) => { + if (frame.parentFrame()) { + // This is an iframe navigation + navigations.push(frame.url()); + } + }); + + await page.goto("/with-iframe"); + await page + .frameLocator("#nav-frame") + .getByRole("link", { name: "Page 2" }) + .click(); + + // Verify navigation occurred + expect(navigations.some((url) => url.includes("page2"))).toBe(true); +}); +``` + +## Common Patterns + +### iFrame Fixture + +```typescript +// fixtures.ts +import { test as base, FrameLocator } from "@playwright/test"; + +export const test = base.extend<{ paymentFrame: FrameLocator }>({ + paymentFrame: async ({ page }, use) => { + await page.goto("/checkout"); + + // Wait for payment iframe to be ready + const frame = page.frameLocator('iframe[src*="payment"]'); + await expect(frame.locator("body")).toBeVisible({ timeout: 15000 }); + + await use(frame); + }, +}); + +// test file +test("complete payment", async ({ paymentFrame }) => { + await paymentFrame.getByLabel("Card").fill("4242424242424242"); + await paymentFrame.getByRole("button", { name: "Pay" }).click(); +}); +``` + +### Debugging iFrame Issues + +```typescript +test("debug iframe content", async ({ page }) => { + await page.goto("/page-with-iframes"); + + // List all frames + console.log("All frames:"); + for (const frame of page.frames()) { + console.log(` - ${frame.name() || "(unnamed)"}: ${frame.url()}`); + } + + // Screenshot specific iframe content + const frame = page.frame({ name: "target-frame" }); + if (frame) { + const body = frame.locator("body"); + await body.screenshot({ path: "iframe-content.png" }); + } + + // Get iframe HTML for debugging + const frameContent = page.frameLocator("#my-frame"); + const html = await frameContent.locator("body").innerHTML(); + console.log("iFrame HTML:", html.substring(0, 500)); +}); +``` + +### Handling iFrame Load Failures + +```typescript +test("handle iframe load failure", async ({ page }) => { + await page.goto("/page-with-unreliable-iframe"); + + const frame = page.frameLocator("#unreliable-frame"); + + try { + // Try to interact with iframe content + await expect(frame.getByRole("button")).toBeVisible({ timeout: 5000 }); + await frame.getByRole("button").click(); + } catch (error) { + // Fallback: refresh iframe + await page.evaluate(() => { + const iframe = document.querySelector( + "#unreliable-frame", + ) as HTMLIFrameElement; + if (iframe) iframe.src = iframe.src; + }); + + // Retry + await expect(frame.getByRole("button")).toBeVisible({ timeout: 10000 }); + await frame.getByRole("button").click(); + } +}); +``` + +### Mocking iFrame Content + +```typescript +test("mock iframe response", async ({ page }) => { + // Intercept iframe src request + await page.route("**/embedded-widget**", (route) => { + route.fulfill({ + contentType: "text/html", + body: ` + + + +

Mocked Widget

+

Mocked widget content

+ + + `, + }); + }); + + await page.goto("/page-with-widget"); + + const frame = page.frameLocator("#widget-frame"); + await expect(frame.getByRole("heading")).toHaveText("Mocked Widget"); +}); +``` + +## Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Solution | +| ------------------------------------- | --------------------------------- | -------------------------------------------------- | +| Using `page.frame()` for interactions | Less reliable than frameLocator | Use `page.frameLocator()` for element interactions | +| Hardcoding iframe index | Fragile if DOM order changes | Use name, id, or src attribute selectors | +| Not waiting for iframe load | Race conditions | Wait for element inside iframe to be visible | +| Assuming same-origin | Cross-origin has different timing | Always wait for iframe content explicitly | +| Ignoring nested iframes | Element not found | Chain frameLocator calls for nested frames | + +## Related References + +- **Locators**: See [locators.md](../core/locators.md) for selector strategies +- **Third-party services**: See [third-party.md](../advanced/third-party.md) for payment iframe patterns +- **Debugging**: See [debugging.md](../debugging/debugging.md) for troubleshooting iframe issues diff --git a/.cursor/skills/playwright-testing/browser-apis/service-workers.md b/.cursor/skills/playwright-testing/browser-apis/service-workers.md new file mode 100644 index 0000000000..7603de322e --- /dev/null +++ b/.cursor/skills/playwright-testing/browser-apis/service-workers.md @@ -0,0 +1,504 @@ +# Service Worker Testing + +## Table of Contents + +1. [Service Worker Basics](#service-worker-basics) +2. [Registration & Lifecycle](#registration--lifecycle) +3. [Cache Testing](#cache-testing) +4. [Offline Testing](#offline-testing) +5. [Push Notifications](#push-notifications) +6. [Background Sync](#background-sync) + +## Service Worker Basics + +### Waiting for Service Worker Registration + +```typescript +test("service worker registers", async ({ page }) => { + await page.goto("/pwa-app"); + + // Wait for SW to register + const swRegistered = await page.evaluate(async () => { + if (!("serviceWorker" in navigator)) return false; + + const registration = await navigator.serviceWorker.ready; + return !!registration.active; + }); + + expect(swRegistered).toBe(true); +}); +``` + +### Getting Service Worker State + +```typescript +test("check SW state", async ({ page }) => { + await page.goto("/"); + + const swState = await page.evaluate(async () => { + const registration = await navigator.serviceWorker.getRegistration(); + if (!registration) return null; + + return { + installing: !!registration.installing, + waiting: !!registration.waiting, + active: !!registration.active, + scope: registration.scope, + }; + }); + + expect(swState?.active).toBe(true); + expect(swState?.scope).toContain(page.url()); +}); +``` + +### Service Worker Context + +```typescript +test("access service worker", async ({ context, page }) => { + await page.goto("/pwa-app"); + + // Get all service workers in context + const workers = context.serviceWorkers(); + + // Wait for service worker if not yet available + if (workers.length === 0) { + await context.waitForEvent("serviceworker"); + } + + const sw = context.serviceWorkers()[0]; + expect(sw.url()).toContain("sw.js"); +}); +``` + +## Registration & Lifecycle + +### Testing SW Update Flow + +```typescript +test("service worker updates", async ({ page }) => { + await page.goto("/pwa-app"); + + // Check for update + const hasUpdate = await page.evaluate(async () => { + const registration = await navigator.serviceWorker.ready; + await registration.update(); + + return new Promise((resolve) => { + if (registration.waiting) { + resolve(true); + } else { + registration.addEventListener("updatefound", () => { + resolve(true); + }); + // Timeout if no update + setTimeout(() => resolve(false), 5000); + } + }); + }); + + // If update found, test skip waiting flow + if (hasUpdate) { + await page.evaluate(async () => { + const registration = await navigator.serviceWorker.ready; + registration.waiting?.postMessage({ type: "SKIP_WAITING" }); + }); + + // Wait for controller change + await page.evaluate(() => { + return new Promise((resolve) => { + navigator.serviceWorker.addEventListener("controllerchange", () => { + resolve(); + }); + }); + }); + } +}); +``` + +### Testing SW Installation + +```typescript +test("verify SW install event", async ({ context, page }) => { + // Listen for service worker before navigating + const swPromise = context.waitForEvent("serviceworker"); + + await page.goto("/pwa-app"); + + const sw = await swPromise; + + // Evaluate in SW context + const swVersion = await sw.evaluate(() => { + // Access SW globals + return (self as any).SW_VERSION || "unknown"; + }); + + expect(swVersion).toBe("1.0.0"); +}); +``` + +### Unregistering Service Workers + +```typescript +test.beforeEach(async ({ page }) => { + await page.goto("/"); + + // Unregister all service workers for clean state + await page.evaluate(async () => { + const registrations = await navigator.serviceWorker.getRegistrations(); + await Promise.all(registrations.map((r) => r.unregister())); + }); + + // Clear caches + await page.evaluate(async () => { + const cacheNames = await caches.keys(); + await Promise.all(cacheNames.map((name) => caches.delete(name))); + }); +}); +``` + +## Cache Testing + +### Verifying Cached Resources + +```typescript +test("assets are cached", async ({ page }) => { + await page.goto("/pwa-app"); + + // Wait for SW to cache assets + await page.evaluate(async () => { + await navigator.serviceWorker.ready; + }); + + // Check cache contents + const cachedUrls = await page.evaluate(async () => { + const cache = await caches.open("app-cache-v1"); + const requests = await cache.keys(); + return requests.map((r) => r.url); + }); + + expect(cachedUrls).toContain(expect.stringContaining("/styles.css")); + expect(cachedUrls).toContain(expect.stringContaining("/app.js")); +}); +``` + +### Testing Cache Strategies + +```typescript +test("cache-first strategy", async ({ page }) => { + await page.goto("/pwa-app"); + + // Wait for initial cache + await page.waitForFunction(async () => { + const cache = await caches.open("app-cache-v1"); + const keys = await cache.keys(); + return keys.length > 0; + }); + + // Block network for cached resources + await page.route("**/styles.css", (route) => route.abort()); + + // Reload - should work from cache + await page.reload(); + + // Verify page still styled (CSS loaded from cache) + const hasStyles = await page.evaluate(() => { + const body = document.body; + const styles = window.getComputedStyle(body); + return styles.fontFamily !== ""; // Has custom font from CSS + }); + + expect(hasStyles).toBe(true); +}); +``` + +### Testing Cache Updates + +```typescript +test("cache updates on new version", async ({ page }) => { + await page.goto("/pwa-app"); + + // Get initial cache + const initialCacheKeys = await page.evaluate(async () => { + const cache = await caches.open("app-cache-v1"); + const keys = await cache.keys(); + return keys.map((r) => r.url); + }); + + // Simulate app update by mocking SW response + await page.route("**/sw.js", (route) => { + route.fulfill({ + contentType: "application/javascript", + body: ` + const VERSION = 'v2'; + self.addEventListener('install', (e) => { + e.waitUntil(caches.open('app-cache-v2')); + self.skipWaiting(); + }); + `, + }); + }); + + // Trigger update + await page.evaluate(async () => { + const reg = await navigator.serviceWorker.ready; + await reg.update(); + }); + + // Verify new cache exists + await page.waitForFunction(async () => { + return await caches.has("app-cache-v2"); + }); +}); +``` + +## Offline Testing + +This section covers **offline-first apps (PWAs)** that are designed to work offline using service workers, caching, and background sync. For testing **unexpected network failures** (error recovery, graceful degradation), see [error-testing.md](error-testing.md#offline-testing). + +### Simulating Offline Mode + +```typescript +test("app works offline", async ({ page, context }) => { + await page.goto("/pwa-app"); + + // Ensure SW is active and content cached + await page.evaluate(async () => { + await navigator.serviceWorker.ready; + }); + await page.waitForTimeout(1000); // Allow caching to complete + + // Go offline + await context.setOffline(true); + + // Navigate to cached page + await page.reload(); + + // Verify content loads + await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible(); + + // Verify offline indicator + await expect(page.locator(".offline-badge")).toBeVisible(); + + // Go back online + await context.setOffline(false); + await expect(page.locator(".offline-badge")).not.toBeVisible(); +}); +``` + +### Testing Offline Fallback + +```typescript +test("shows offline page for uncached routes", async ({ page, context }) => { + await page.goto("/pwa-app"); + await page.evaluate(() => navigator.serviceWorker.ready); + + // Go offline + await context.setOffline(true); + + // Navigate to uncached page + await page.goto("/uncached-page"); + + // Should show offline fallback + await expect(page.getByText("You are offline")).toBeVisible(); + await expect(page.getByRole("button", { name: "Retry" })).toBeVisible(); +}); +``` + +### Testing Offline Form Submission + +```typescript +test("queues form submission offline", async ({ page, context }) => { + await page.goto("/pwa-app/form"); + + // Go offline + await context.setOffline(true); + + // Submit form + await page.getByLabel("Message").fill("Offline message"); + await page.getByRole("button", { name: "Send" }).click(); + + // Should show queued status + await expect(page.getByText("Queued for sync")).toBeVisible(); + + // Go online + await context.setOffline(false); + + // Trigger sync (or wait for automatic) + await page.evaluate(async () => { + const reg = await navigator.serviceWorker.ready; + // Manually trigger sync for testing + await (reg as any).sync?.register("form-sync"); + }); + + // Verify submission completed + await expect(page.getByText("Message sent")).toBeVisible({ timeout: 10000 }); +}); +``` + +## Push Notifications + +### Mocking Push Subscription + +```typescript +test("handles push subscription", async ({ page, context }) => { + // Grant notification permission + await context.grantPermissions(["notifications"]); + + await page.goto("/pwa-app"); + + // Subscribe to push + const subscription = await page.evaluate(async () => { + const reg = await navigator.serviceWorker.ready; + const sub = await reg.pushManager.subscribe({ + userVisibleOnly: true, + applicationServerKey: "test-key", + }); + return sub.toJSON(); + }); + + expect(subscription.endpoint).toBeDefined(); +}); +``` + +### Testing Push Message Handling + +```typescript +test("handles push notification", async ({ context, page }) => { + await context.grantPermissions(["notifications"]); + await page.goto("/pwa-app"); + + // Wait for SW + const swPromise = context.waitForEvent("serviceworker"); + const sw = await swPromise; + + // Simulate push message to service worker + await sw.evaluate(async () => { + // Dispatch push event + const pushEvent = new PushEvent("push", { + data: new PushMessageData( + JSON.stringify({ title: "Test", body: "Push message" }), + ), + }); + self.dispatchEvent(pushEvent); + }); + + // Note: Actual notification display testing is limited in Playwright + // Focus on verifying the SW handles the push correctly +}); +``` + +### Testing Notification Click + +```typescript +test("notification click opens page", async ({ context, page }) => { + await context.grantPermissions(["notifications"]); + await page.goto("/pwa-app"); + + // Store notification URL target + let notificationUrl = ""; + + // Listen for new pages (notification click opens new page) + context.on("page", (newPage) => { + notificationUrl = newPage.url(); + }); + + // Trigger notification via SW + await page.evaluate(async () => { + const reg = await navigator.serviceWorker.ready; + await reg.showNotification("Test", { + body: "Click me", + data: { url: "/notification-target" }, + }); + }); + + // Simulate clicking notification (via SW) + const sw = context.serviceWorkers()[0]; + await sw.evaluate(() => { + self.dispatchEvent( + new NotificationEvent("notificationclick", { + notification: { data: { url: "/notification-target" } } as any, + }), + ); + }); + + // Verify navigation occurred + await page.waitForTimeout(1000); + // Check if new page opened or current page navigated +}); +``` + +## Background Sync + +### Testing Background Sync Registration + +```typescript +test("registers background sync", async ({ page }) => { + await page.goto("/pwa-app"); + + // Register sync + const syncRegistered = await page.evaluate(async () => { + const reg = await navigator.serviceWorker.ready; + if (!("sync" in reg)) return false; + + await (reg as any).sync.register("my-sync"); + return true; + }); + + expect(syncRegistered).toBe(true); +}); +``` + +### Testing Sync Event + +```typescript +test("sync event fires when online", async ({ context, page }) => { + await page.goto("/pwa-app"); + + // Queue data while offline + await context.setOffline(true); + + await page.evaluate(async () => { + // Store data in IndexedDB for sync + const db = await openDB(); + await db.put("sync-queue", { id: 1, data: "test" }); + + // Register sync + const reg = await navigator.serviceWorker.ready; + await (reg as any).sync.register("data-sync"); + }); + + // Track sync completion + await page.evaluate(() => { + window.syncCompleted = false; + navigator.serviceWorker.addEventListener("message", (e) => { + if (e.data.type === "SYNC_COMPLETE") { + window.syncCompleted = true; + } + }); + }); + + // Go online + await context.setOffline(false); + + // Wait for sync to complete + await page.waitForFunction(() => window.syncCompleted, { timeout: 10000 }); +}); +``` + +## Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Solution | +| ------------------------------ | ----------------------- | -------------------------------------------- | +| Not clearing SW between tests | Tests affect each other | Unregister SW in beforeEach | +| Not waiting for SW ready | Race conditions | Always await `navigator.serviceWorker.ready` | +| Testing in isolation only | Misses real SW behavior | Test with actual caching | +| Hardcoded timeouts for caching | Flaky tests | Wait for cache to populate | +| Ignoring SW update cycle | Missing update bugs | Test install, activate, update flows | + +## Related References + +- **Network Failures**: See [error-testing.md](error-testing.md#offline-testing) for unexpected network failure patterns +- **Browser APIs**: See [browser-apis.md](browser-apis.md) for permissions +- **Network Mocking**: See [network-advanced.md](../advanced/network-advanced.md) for network interception +- **Browser Extensions**: See [browser-extensions.md](../testing-patterns/browser-extensions.md) for extension service worker patterns diff --git a/.cursor/skills/playwright-testing/browser-apis/websockets.md b/.cursor/skills/playwright-testing/browser-apis/websockets.md new file mode 100644 index 0000000000..075a997395 --- /dev/null +++ b/.cursor/skills/playwright-testing/browser-apis/websockets.md @@ -0,0 +1,403 @@ +# WebSocket & Real-Time Testing + +## Table of Contents + +1. [WebSocket Basics](#websocket-basics) +2. [Mocking WebSocket Messages](#mocking-websocket-messages) +3. [Testing Real-Time Features](#testing-real-time-features) +4. [Server-Sent Events](#server-sent-events) +5. [Reconnection Testing](#reconnection-testing) + +## WebSocket Basics + +### Wait for WebSocket Connection + +```typescript +test("chat connects via websocket", async ({ page }) => { + // Listen for WebSocket connection + const wsPromise = page.waitForEvent("websocket"); + + await page.goto("/chat"); + + const ws = await wsPromise; + expect(ws.url()).toContain("/ws/chat"); + + // Wait for connection to be established + await ws.waitForEvent("framesent"); +}); +``` + +### Monitor WebSocket Messages + +```typescript +test("receives real-time updates", async ({ page }) => { + const messages: string[] = []; + + // Set up listener before navigation + page.on("websocket", (ws) => { + ws.on("framereceived", (frame) => { + messages.push(frame.payload as string); + }); + }); + + await page.goto("/dashboard"); + + // Wait for some messages + await expect.poll(() => messages.length).toBeGreaterThan(0); + + // Verify message format + const data = JSON.parse(messages[0]); + expect(data).toHaveProperty("type"); +}); +``` + +### Capture Sent Messages + +```typescript +test("sends correct message format", async ({ page }) => { + const sentMessages: string[] = []; + + page.on("websocket", (ws) => { + ws.on("framesent", (frame) => { + sentMessages.push(frame.payload as string); + }); + }); + + await page.goto("/chat"); + await page.getByLabel("Message").fill("Hello!"); + await page.getByRole("button", { name: "Send" }).click(); + + // Verify sent message + await expect.poll(() => sentMessages.length).toBeGreaterThan(0); + + const sent = JSON.parse(sentMessages[sentMessages.length - 1]); + expect(sent).toEqual({ + type: "message", + content: "Hello!", + }); +}); +``` + +## Mocking WebSocket Messages + +### Inject Messages via Page Evaluate + +```typescript +test("displays incoming chat message", async ({ page }) => { + await page.goto("/chat"); + + // Wait for WebSocket to be ready + await page.waitForFunction( + () => (window as any).chatSocket?.readyState === 1, + ); + + // Simulate incoming message + await page.evaluate(() => { + const event = new MessageEvent("message", { + data: JSON.stringify({ + type: "message", + from: "Alice", + content: "Hello there!", + }), + }); + (window as any).chatSocket.dispatchEvent(event); + }); + + await expect(page.getByText("Alice: Hello there!")).toBeVisible(); +}); +``` + +### Mock WebSocket with Route Handler + +```typescript +test("mock websocket entirely", async ({ page, context }) => { + // Intercept the WebSocket upgrade + await context.route("**/ws/**", async (route) => { + // For WebSocket routes, we can't fulfill directly + // Instead, use page.evaluate to mock the client-side + }); + + // Alternative: Mock at application level + await page.addInitScript(() => { + const OriginalWebSocket = window.WebSocket; + (window as any).WebSocket = function (url: string) { + const ws = { + readyState: 1, + send: (data: string) => { + console.log("WS Send:", data); + }, + close: () => {}, + addEventListener: () => {}, + removeEventListener: () => {}, + }; + setTimeout(() => ws.onopen?.(), 100); + return ws; + }; + }); + + await page.goto("/chat"); +}); +``` + +### WebSocket Mock Fixture + +```typescript +// fixtures/websocket.fixture.ts +import { test as base, Page } from "@playwright/test"; + +type WsMessage = { type: string; [key: string]: any }; + +type WebSocketFixtures = { + mockWebSocket: { + injectMessage: (message: WsMessage) => Promise; + getSentMessages: () => Promise; + }; +}; + +export const test = base.extend({ + mockWebSocket: async ({ page }, use) => { + const sentMessages: WsMessage[] = []; + + // Capture sent messages + await page.addInitScript(() => { + (window as any).__wsSent = []; + const OriginalWebSocket = window.WebSocket; + window.WebSocket = function (url: string) { + const ws = new OriginalWebSocket(url); + const originalSend = ws.send.bind(ws); + ws.send = (data: string) => { + (window as any).__wsSent.push(JSON.parse(data)); + originalSend(data); + }; + (window as any).__ws = ws; + return ws; + } as any; + }); + + await use({ + injectMessage: async (message) => { + await page.evaluate((msg) => { + const event = new MessageEvent("message", { + data: JSON.stringify(msg), + }); + (window as any).__ws?.dispatchEvent(event); + }, message); + }, + getSentMessages: async () => { + return page.evaluate(() => (window as any).__wsSent || []); + }, + }); + }, +}); + +// Usage +test("chat with mocked websocket", async ({ page, mockWebSocket }) => { + await page.goto("/chat"); + + // Inject incoming message + await mockWebSocket.injectMessage({ + type: "message", + from: "Bob", + content: "Hi!", + }); + + await expect(page.getByText("Bob: Hi!")).toBeVisible(); + + // Send a reply + await page.getByLabel("Message").fill("Hello Bob!"); + await page.getByRole("button", { name: "Send" }).click(); + + // Verify sent message + const sent = await mockWebSocket.getSentMessages(); + expect(sent).toContainEqual( + expect.objectContaining({ content: "Hello Bob!" }), + ); +}); +``` + +## Testing Real-Time Features + +### Live Notifications + +```typescript +test("displays live notification", async ({ page }) => { + await page.goto("/dashboard"); + + // Simulate notification via WebSocket + await page.evaluate(() => { + const event = new MessageEvent("message", { + data: JSON.stringify({ + type: "notification", + title: "New Order", + message: "Order #123 received", + }), + }); + (window as any).notificationSocket.dispatchEvent(event); + }); + + await expect(page.getByRole("alert")).toContainText("Order #123 received"); +}); +``` + +### Live Data Updates + +```typescript +test("updates stock price in real-time", async ({ page }) => { + await page.goto("/stocks/AAPL"); + + const priceElement = page.getByTestId("stock-price"); + const initialPrice = await priceElement.textContent(); + + // Simulate price update + await page.evaluate(() => { + const event = new MessageEvent("message", { + data: JSON.stringify({ + type: "price_update", + symbol: "AAPL", + price: 150.25, + }), + }); + (window as any).stockSocket.dispatchEvent(event); + }); + + await expect(priceElement).not.toHaveText(initialPrice!); + await expect(priceElement).toContainText("150.25"); +}); +``` + +### Collaborative Editing + +```typescript +test("shows collaborator cursor", async ({ page }) => { + await page.goto("/document/123"); + + // Simulate another user's cursor position + await page.evaluate(() => { + const event = new MessageEvent("message", { + data: JSON.stringify({ + type: "cursor", + userId: "user-456", + userName: "Alice", + position: { x: 100, y: 200 }, + }), + }); + (window as any).docSocket.dispatchEvent(event); + }); + + await expect(page.getByTestId("cursor-user-456")).toBeVisible(); + await expect(page.getByText("Alice")).toBeVisible(); +}); +``` + +## Server-Sent Events + +### Test SSE Updates + +```typescript +test("receives SSE updates", async ({ page }) => { + // Mock SSE endpoint + await page.route("**/api/events", (route) => { + route.fulfill({ + status: 200, + headers: { + "Content-Type": "text/event-stream", + "Cache-Control": "no-cache", + Connection: "keep-alive", + }, + body: `data: {"type":"update","value":42}\n\n`, + }); + }); + + await page.goto("/live-data"); + + await expect(page.getByTestId("value")).toHaveText("42"); +}); +``` + +### Simulate Multiple SSE Events + +```typescript +test("handles multiple SSE events", async ({ page }) => { + await page.route("**/api/events", async (route) => { + const encoder = new TextEncoder(); + const events = [ + `data: {"count":1}\n\n`, + `data: {"count":2}\n\n`, + `data: {"count":3}\n\n`, + ]; + + route.fulfill({ + status: 200, + headers: { "Content-Type": "text/event-stream" }, + body: events.join(""), + }); + }); + + await page.goto("/counter"); + + // Should receive all events + await expect(page.getByTestId("count")).toHaveText("3"); +}); +``` + +## Reconnection Testing + +### Test Connection Loss + +```typescript +test("handles connection loss gracefully", async ({ page }) => { + await page.goto("/chat"); + + // Simulate connection close + await page.evaluate(() => { + (window as any).chatSocket.close(); + }); + + // Should show disconnected state + await expect(page.getByText("Reconnecting...")).toBeVisible(); +}); +``` + +### Test Reconnection + +```typescript +test("reconnects after connection loss", async ({ page }) => { + await page.goto("/chat"); + + // Simulate disconnect + await page.evaluate(() => { + (window as any).chatSocket.close(); + }); + + await expect(page.getByText("Reconnecting...")).toBeVisible(); + + // Simulate reconnection + await page.evaluate(() => { + const event = new Event("open"); + (window as any).chatSocket = { readyState: 1 }; + (window as any).chatSocket.dispatchEvent?.(event); + }); + + // Force component to re-check connection + await page.evaluate(() => { + window.dispatchEvent(new Event("online")); + }); + + await expect(page.getByText("Connected")).toBeVisible(); +}); +``` + +## Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Solution | +| ------------------------------------- | ----------------------------- | ---------------------------------- | +| Not waiting for WebSocket ready | Messages sent too early | Wait for `readyState === 1` | +| Testing against real WebSocket server | Flaky, timing-dependent | Mock WebSocket messages | +| Ignoring connection state | Tests pass but feature broken | Test connected/disconnected states | +| No cleanup of listeners | Memory leaks in tests | Clean up event listeners | + +## Related References + +- **Network**: See [network-advanced.md](../advanced/network-advanced.md) for HTTP mocking patterns +- **Assertions**: See [assertions-waiting.md](../core/assertions-waiting.md) for polling patterns +- **Multi-User**: See [multi-user.md](../advanced/multi-user.md) for real-time collaboration testing with multiple users diff --git a/.cursor/skills/playwright-testing/core/annotations.md b/.cursor/skills/playwright-testing/core/annotations.md new file mode 100644 index 0000000000..ac0f890a5e --- /dev/null +++ b/.cursor/skills/playwright-testing/core/annotations.md @@ -0,0 +1,424 @@ +# Test Annotations & Organization + +## Table of Contents + +1. [Skip Annotations](#skip-annotations) +2. [Fixme & Fail Annotations](#fixme--fail-annotations) +3. [Slow Tests](#slow-tests) +4. [Test Steps](#test-steps) +5. [Custom Annotations](#custom-annotations) +6. [Conditional Annotations](#conditional-annotations) + +## Skip Annotations + +### Basic Skip + +```typescript +// Skip unconditionally +test.skip("feature not implemented", async ({ page }) => { + // This test won't run +}); + +// Skip with reason +test("payment flow", async ({ page }) => { + test.skip(true, "Payment gateway in maintenance"); + // Test body won't execute +}); +``` + +### Conditional Skip + +```typescript +test("webkit-specific feature", async ({ page, browserName }) => { + test.skip(browserName !== "webkit", "This feature only works in WebKit"); + + await page.goto("/webkit-feature"); +}); + +test("production only", async ({ page }) => { + test.skip(process.env.ENV !== "production", "Only runs against production"); + + await page.goto("/prod-feature"); +}); +``` + +### Skip by Platform + +```typescript +test("windows-specific", async ({ page }) => { + test.skip(process.platform !== "win32", "Windows only"); +}); + +test("not on CI", async ({ page }) => { + test.skip(!!process.env.CI, "Skipped in CI environment"); +}); +``` + +### Skip Describe Block + +```typescript +test.describe("Admin features", () => { + test.skip( + ({ browserName }) => browserName === "firefox", + "Firefox admin bug", + ); + + test("admin dashboard", async ({ page }) => { + // Skipped in Firefox + }); + + test("admin settings", async ({ page }) => { + // Skipped in Firefox + }); +}); +``` + +## Fixme & Fail Annotations + +### Fixme - Known Issues + +```typescript +// Mark test as needing fix (skips the test) +test.fixme("broken after refactor", async ({ page }) => { + // Test won't run but is tracked +}); + +// Conditional fixme +test("flaky on CI", async ({ page }) => { + test.fixme(!!process.env.CI, "Investigate CI flakiness - ticket #123"); + + await page.goto("/flaky-feature"); +}); +``` + +### Fail - Expected Failures + +```typescript +// Test is expected to fail (runs but expects failure) +test("known bug", async ({ page }) => { + test.fail(); + + await page.goto("/buggy-page"); + // If this passes, the test fails (bug was fixed!) + await expect(page.getByText("Working")).toBeVisible(); +}); + +// Conditional fail +test("fails on webkit", async ({ page, browserName }) => { + test.fail(browserName === "webkit", "WebKit rendering bug #456"); + + await page.goto("/render-test"); + await expect(page.getByTestId("element")).toHaveCSS("width", "100px"); +}); +``` + +### Difference Between Skip, Fixme, Fail + +| Annotation | Runs? | Use Case | +| -------------- | ----- | -------------------------------- | +| `test.skip()` | No | Feature not applicable | +| `test.fixme()` | No | Known bug, needs investigation | +| `test.fail()` | Yes | Expected to fail, tracking a bug | + +## Slow Tests + +### Mark Slow Tests + +```typescript +// Triple the default timeout +test("large data import", async ({ page }) => { + test.slow(); + + await page.goto("/import"); + await page.setInputFiles("#file", "large-file.csv"); + await page.getByRole("button", { name: "Import" }).click(); + + await expect(page.getByText("Import complete")).toBeVisible(); +}); + +// Conditional slow +test("video processing", async ({ page, browserName }) => { + test.slow(browserName === "webkit", "WebKit video processing is slow"); + + await page.goto("/video-editor"); +}); +``` + +### Custom Timeout + +```typescript +test("very long operation", async ({ page }) => { + // Set specific timeout (in milliseconds) + test.setTimeout(120000); // 2 minutes + + await page.goto("/long-operation"); +}); + +// Timeout for describe block +test.describe("Integration tests", () => { + test.describe.configure({ timeout: 60000 }); + + test("test 1", async ({ page }) => { + // Has 60 second timeout + }); +}); +``` + +## Test Steps + +### Basic Steps + +```typescript +test("checkout flow", async ({ page }) => { + await test.step("Add item to cart", async () => { + await page.goto("/products"); + await page.getByRole("button", { name: "Add to Cart" }).click(); + }); + + await test.step("Go to checkout", async () => { + await page.getByRole("link", { name: "Cart" }).click(); + await page.getByRole("button", { name: "Checkout" }).click(); + }); + + await test.step("Fill shipping info", async () => { + await page.getByLabel("Address").fill("123 Test St"); + await page.getByLabel("City").fill("Test City"); + }); + + await test.step("Complete payment", async () => { + await page.getByLabel("Card").fill("4242424242424242"); + await page.getByRole("button", { name: "Pay" }).click(); + }); + + await expect(page.getByText("Order confirmed")).toBeVisible(); +}); +``` + +### Nested Steps + +```typescript +test("user registration", async ({ page }) => { + await test.step("Fill registration form", async () => { + await page.goto("/register"); + + await test.step("Personal info", async () => { + await page.getByLabel("Name").fill("John Doe"); + await page.getByLabel("Email").fill("john@example.com"); + }); + + await test.step("Security", async () => { + await page.getByLabel("Password").fill("SecurePass123"); + await page.getByLabel("Confirm Password").fill("SecurePass123"); + }); + }); + + await test.step("Submit and verify", async () => { + await page.getByRole("button", { name: "Register" }).click(); + await expect(page.getByText("Welcome")).toBeVisible(); + }); +}); +``` + +### Steps with Return Values + +```typescript +test("verify order", async ({ page }) => { + const orderId = await test.step("Create order", async () => { + await page.goto("/checkout"); + await page.getByRole("button", { name: "Place Order" }).click(); + + // Return value from step + return await page.getByTestId("order-id").textContent(); + }); + + await test.step("Verify order details", async () => { + await page.goto(`/orders/${orderId}`); + await expect(page.getByText(`Order #${orderId}`)).toBeVisible(); + }); +}); +``` + +### Step in Page Object + +```typescript +// pages/checkout.page.ts +export class CheckoutPage { + async fillShippingInfo(address: string, city: string) { + await test.step("Fill shipping information", async () => { + await this.page.getByLabel("Address").fill(address); + await this.page.getByLabel("City").fill(city); + }); + } + + async completePayment(cardNumber: string) { + await test.step("Complete payment", async () => { + await this.page.getByLabel("Card").fill(cardNumber); + await this.page.getByRole("button", { name: "Pay" }).click(); + }); + } +} +``` + +## Custom Annotations + +### Add Annotations + +```typescript +test("important feature", async ({ page }, testInfo) => { + // Add custom annotation + testInfo.annotations.push({ + type: "priority", + description: "high", + }); + + testInfo.annotations.push({ + type: "ticket", + description: "JIRA-123", + }); + + await page.goto("/feature"); +}); +``` + +### Annotation Fixture + +```typescript +// fixtures/annotations.fixture.ts +import { test as base, TestInfo } from "@playwright/test"; + +type AnnotationFixtures = { + annotate: { + ticket: (id: string) => void; + priority: (level: "low" | "medium" | "high") => void; + owner: (name: string) => void; + }; +}; + +export const test = base.extend({ + annotate: async ({}, use, testInfo) => { + await use({ + ticket: (id) => { + testInfo.annotations.push({ type: "ticket", description: id }); + }, + priority: (level) => { + testInfo.annotations.push({ type: "priority", description: level }); + }, + owner: (name) => { + testInfo.annotations.push({ type: "owner", description: name }); + }, + }); + }, +}); + +// Usage +test("critical feature", async ({ page, annotate }) => { + annotate.ticket("JIRA-456"); + annotate.priority("high"); + annotate.owner("Alice"); + + await page.goto("/critical"); +}); +``` + +### Read Annotations in Reporter + +```typescript +// reporters/annotation-reporter.ts +import { Reporter, TestCase, TestResult } from "@playwright/test/reporter"; + +class AnnotationReporter implements Reporter { + onTestEnd(test: TestCase, result: TestResult) { + const ticket = test.annotations.find((a) => a.type === "ticket"); + const priority = test.annotations.find((a) => a.type === "priority"); + + if (ticket) { + console.log(`Test linked to: ${ticket.description}`); + } + + if (priority?.description === "high" && result.status === "failed") { + console.log(`HIGH PRIORITY FAILURE: ${test.title}`); + } + } +} + +export default AnnotationReporter; +``` + +## Conditional Annotations + +### Annotation Helper + +```typescript +// helpers/test-annotations.ts +import { test } from "@playwright/test"; + +export function skipInCI(reason = "Skipped in CI") { + test.skip(!!process.env.CI, reason); +} + +export function skipInBrowser(browser: string, reason: string) { + test.beforeEach(({ browserName }) => { + test.skip(browserName === browser, reason); + }); +} + +export function onlyInEnv(env: string) { + test.skip(process.env.ENV !== env, `Only runs in ${env}`); +} +``` + +```typescript +// tests/feature.spec.ts +import { skipInCI, onlyInEnv } from "../helpers/test-annotations"; + +test("local only feature", async ({ page }) => { + skipInCI("Uses local resources"); + + await page.goto("/local-feature"); +}); + +test("production check", async ({ page }) => { + onlyInEnv("production"); + + await page.goto("/prod-only"); +}); +``` + +### Describe-Level Conditions + +```typescript +test.describe("Mobile features", () => { + test.beforeEach(({ isMobile }) => { + test.skip(!isMobile, "Mobile only tests"); + }); + + test("touch gestures", async ({ page }) => { + // Only runs on mobile + }); +}); + +test.describe("Desktop features", () => { + test.beforeEach(({ isMobile }) => { + test.skip(isMobile, "Desktop only tests"); + }); + + test("hover interactions", async ({ page }) => { + // Only runs on desktop + }); +}); +``` + +## Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Solution | +| --------------------------- | ---------------------- | -------------------------------- | +| Skipping without reason | Hard to track why | Always provide description | +| Too many skipped tests | Test debt accumulates | Review and clean up regularly | +| Using skip instead of fixme | Loses intent | Use fixme for bugs, skip for N/A | +| Not using steps | Hard to debug failures | Group logical actions in steps | + +## Related References + +- **Test Tags**: See [test-tags.md](test-tags.md) for tagging and filtering tests with `--grep` +- **Test Organization**: See [test-suite-structure.md](test-suite-structure.md) for structuring tests +- **Debugging**: See [debugging.md](../debugging/debugging.md) for troubleshooting diff --git a/.cursor/skills/playwright-testing/core/assertions-waiting.md b/.cursor/skills/playwright-testing/core/assertions-waiting.md new file mode 100644 index 0000000000..bd03dd8a4d --- /dev/null +++ b/.cursor/skills/playwright-testing/core/assertions-waiting.md @@ -0,0 +1,361 @@ +# Assertions & Waiting + +## Table of Contents + +1. [Web-First Assertions](#web-first-assertions) +2. [Generic Assertions](#generic-assertions) +3. [Soft Assertions](#soft-assertions) +4. [Waiting Strategies](#waiting-strategies) +5. [Polling & Retrying](#polling--retrying) +6. [Custom Matchers](#custom-matchers) + +## Web-First Assertions + +Auto-retry until condition is met or timeout. Always prefer these over generic assertions. + +### Locator Assertions + +```typescript +import { expect } from "@playwright/test"; + +// Visibility +await expect(page.getByRole("button")).toBeVisible(); +await expect(page.getByRole("button")).toBeHidden(); +await expect(page.getByRole("button")).not.toBeVisible(); + +// Enabled/Disabled +await expect(page.getByRole("button")).toBeEnabled(); +await expect(page.getByRole("button")).toBeDisabled(); + +// Text content +await expect(page.getByRole("heading")).toHaveText("Welcome"); +await expect(page.getByRole("heading")).toHaveText(/welcome/i); +await expect(page.getByRole("heading")).toContainText("Welcome"); + +// Count +await expect(page.getByRole("listitem")).toHaveCount(5); + +// Attributes +await expect(page.getByRole("link")).toHaveAttribute("href", "/home"); +await expect(page.getByRole("img")).toHaveAttribute("alt", /logo/i); + +// CSS +await expect(page.getByRole("button")).toHaveClass(/primary/); +await expect(page.getByRole("button")).toHaveCSS("color", "rgb(0, 0, 255)"); + +// Input values +await expect(page.getByLabel("Email")).toHaveValue("user@example.com"); +await expect(page.getByLabel("Email")).toBeEmpty(); + +// Focus +await expect(page.getByLabel("Email")).toBeFocused(); + +// Checked state +await expect(page.getByRole("checkbox")).toBeChecked(); +await expect(page.getByRole("checkbox")).not.toBeChecked(); + +// Editable state +await expect(page.getByLabel("Name")).toBeEditable(); +``` + +### Page Assertions + +```typescript +// URL +await expect(page).toHaveURL("/dashboard"); +await expect(page).toHaveURL(/\/dashboard/); + +// Title +await expect(page).toHaveTitle("Dashboard - MyApp"); +await expect(page).toHaveTitle(/dashboard/i); +``` + +### Response Assertions + +```typescript +const response = await page.request.get("/api/users"); +await expect(response).toBeOK(); +await expect(response).not.toBeOK(); +``` + +## Generic Assertions + +Use for non-UI values. Do NOT retry - execute immediately. + +```typescript +// Equality +expect(value).toBe(5); +expect(object).toEqual({ name: "Test" }); +expect(array).toContain("item"); + +// Truthiness +expect(value).toBeTruthy(); +expect(value).toBeFalsy(); +expect(value).toBeNull(); +expect(value).toBeUndefined(); +expect(value).toBeDefined(); + +// Numbers +expect(value).toBeGreaterThan(5); +expect(value).toBeLessThanOrEqual(10); +expect(value).toBeCloseTo(5.5, 1); + +// Strings +expect(string).toMatch(/pattern/); +expect(string).toContain("substring"); + +// Arrays/Objects +expect(array).toHaveLength(3); +expect(object).toHaveProperty("key", "value"); + +// Exceptions +expect(() => fn()).toThrow(); +expect(() => fn()).toThrow("error message"); +await expect(asyncFn()).rejects.toThrow(); +``` + +## Soft Assertions + +Continue test execution after failure, report all failures at end. + +```typescript +test("check multiple elements", async ({ page }) => { + await page.goto("/dashboard"); + + // Won't stop on first failure + await expect.soft(page.getByRole("heading")).toHaveText("Dashboard"); + await expect.soft(page.getByRole("button", { name: "Save" })).toBeEnabled(); + await expect.soft(page.getByText("Welcome")).toBeVisible(); + + // Test continues; all failures reported at end +}); +``` + +### Soft Assertions with Early Exit + +```typescript +test("check form", async ({ page }) => { + await expect.soft(page.getByRole("form")).toBeVisible(); + + // Exit early if form not visible (pointless to check fields) + if (expect.soft.hasFailures()) { + return; + } + + await expect.soft(page.getByLabel("Name")).toBeVisible(); + await expect.soft(page.getByLabel("Email")).toBeVisible(); +}); +``` + +## Waiting Strategies + +### Auto-Waiting (Default) + +Actions automatically wait for: + +- Element to be attached to DOM +- Element to be visible +- Element to be stable (no animations) +- Element to be enabled +- Element to receive events + +```typescript +// These auto-wait +await page.click("button"); +await page.fill("input", "text"); +await page.getByRole("button").click(); +``` + +### Wait for Navigation + +```typescript +// Wait for URL change +await page.waitForURL("/dashboard"); +await page.waitForURL(/\/dashboard/); + +// Wait for navigation after action +await Promise.all([ + page.waitForURL("**/dashboard"), + page.click('a[href="/dashboard"]'), +]); + +// Or without Promise.all +const urlPromise = page.waitForURL("**/dashboard"); +await page.click("a"); +await urlPromise; +``` + +### Wait for Network + +```typescript +// Wait for specific response +const responsePromise = page.waitForResponse("**/api/users"); +await page.click("button"); +const response = await responsePromise; +expect(response.status()).toBe(200); + +// Wait for request +const requestPromise = page.waitForRequest("**/api/submit"); +await page.click("button"); +const request = await requestPromise; + +// Wait for no network activity +await page.waitForLoadState("networkidle"); +``` + +### Wait for Element State + +```typescript +// Wait for element to appear +await page.getByRole("dialog").waitFor({ state: "visible" }); + +// Wait for element to disappear +await page.getByText("Loading...").waitFor({ state: "hidden" }); + +// Wait for element to be attached +await page.getByTestId("result").waitFor({ state: "attached" }); + +// Wait for element to be detached +await page.getByTestId("modal").waitFor({ state: "detached" }); +``` + +### Wait for Function + +```typescript +// Wait for arbitrary condition +await page.waitForFunction(() => { + return document.querySelector(".loaded") !== null; +}); + +// With arguments +await page.waitForFunction( + (selector) => document.querySelector(selector)?.textContent === "Ready", + ".status", +); +``` + +## Polling & Retrying + +### toPass() for Polling + +Retry until block passes or times out: + +```typescript +await expect(async () => { + const response = await page.request.get("/api/status"); + expect(response.status()).toBe(200); + + const data = await response.json(); + expect(data.ready).toBe(true); +}).toPass({ + intervals: [1000, 2000, 5000], // Retry intervals + timeout: 30000, +}); +``` + +### expect.poll() + +Poll a function until assertion passes: + +```typescript +// Poll API until condition met +await expect + .poll( + async () => { + const response = await page.request.get("/api/job/123"); + return (await response.json()).status; + }, + { + intervals: [1000, 2000, 5000], + timeout: 30000, + }, + ) + .toBe("completed"); + +// Poll DOM value +await expect.poll(() => page.getByTestId("counter").textContent()).toBe("10"); +``` + +## Custom Matchers + +```typescript +// playwright.config.ts or fixtures +import { expect } from "@playwright/test"; + +expect.extend({ + async toHaveDataLoaded(page: Page) { + const locator = page.getByTestId("data-container"); + let pass = false; + let message = ""; + + try { + await expect(locator).toBeVisible(); + await expect(locator).not.toContainText("Loading"); + pass = true; + } catch (e) { + message = `Expected data to be loaded but found loading state`; + } + + return { pass, message: () => message }; + }, +}); + +// Extend TypeScript types +declare global { + namespace PlaywrightTest { + interface Matchers { + toHaveDataLoaded(): Promise; + } + } +} + +// Usage +await expect(page).toHaveDataLoaded(); +``` + +## Timeouts + +### Configure Timeouts + +```typescript +// playwright.config.ts +export default defineConfig({ + timeout: 30000, // Test timeout + expect: { + timeout: 5000, // Assertion timeout + }, +}); + +// Per-test timeout +test("long test", async ({ page }) => { + test.setTimeout(60000); + // ... +}); + +// Per-assertion timeout +await expect(page.getByRole("button")).toBeVisible({ timeout: 10000 }); +``` + +## Best Practices + +| Do | Don't | +| ------------------------------ | ------------------------------ | +| Use web-first assertions | Use generic assertions for DOM | +| Let auto-waiting work | Add unnecessary explicit waits | +| Use `toPass()` for polling | Write manual retry loops | +| Configure appropriate timeouts | Use `waitForTimeout()` | +| Check specific conditions | Wait for arbitrary time | + +## Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Solution | +| --------------------------------------------------------- | ----------------------------- | -------------------------------------------- | +| `await page.waitForTimeout(5000)` | Slow, flaky, arbitrary timing | Use auto-waiting or `waitForResponse` | +| `await new Promise(resolve => setTimeout(resolve, 1000))` | Same as above | Use `waitForResponse` or element state waits | +| Generic assertions on DOM elements | No auto-retry, flaky | Use web-first assertions with `expect()` | + +## Related References + +- **Debugging timeout issues**: See [debugging.md](../debugging/debugging.md) for troubleshooting +- **Fixing flaky tests**: See [debugging.md](../debugging/debugging.md) for race condition solutions +- **Network interception**: See [test-suite-structure.md](test-suite-structure.md) for API mocking diff --git a/.cursor/skills/playwright-testing/core/configuration.md b/.cursor/skills/playwright-testing/core/configuration.md new file mode 100644 index 0000000000..66b9d33849 --- /dev/null +++ b/.cursor/skills/playwright-testing/core/configuration.md @@ -0,0 +1,452 @@ +# Playwright Configuration + +## Table of Contents + +1. [CLI Quick Reference](#cli-quick-reference) +2. [Decision Guide](#decision-guide) +3. [Production-Ready Config](#production-ready-config) +4. [Patterns](#patterns) +5. [Anti-Patterns](#anti-patterns) +6. [Troubleshooting](#troubleshooting) +7. [Related](#related) + +> **When to use**: Setting up a new project, adjusting timeouts, adding browser targets, configuring CI behavior, or managing environment-specific settings. + +## CLI Quick Reference + +```bash +npx playwright init # scaffold config + first test +npx playwright test --config=custom.config.ts # use alternate config +npx playwright test --project=chromium # run single project +npx playwright test --reporter=html # override reporter +npx playwright test --grep @smoke # run tests tagged @smoke +npx playwright test --grep-invert @slow # exclude @slow tests +npx playwright show-report # open last HTML report +DEBUG=pw:api npx playwright test # verbose logging +``` + +## Decision Guide + +### Timeout Selection + +| Symptom | Setting | Default | Recommended | +|---------|---------|---------|-------------| +| Test takes too long overall | `timeout` | 30s | 30-60s (max 120s) | +| Assertion retries too long/short | `expect.timeout` | 5s | 5-10s | +| `page.goto()` or `waitForURL()` times out | `navigationTimeout` | 30s | 10-30s | +| `click()`, `fill()` time out | `actionTimeout` | 0 (unlimited) | 10-15s | +| Dev server slow to start | `webServer.timeout` | 60s | 60-180s | + +### Server Management + +| Scenario | Approach | +|----------|----------| +| App in same repo | `webServer` with `reuseExistingServer: !process.env.CI` | +| Separate repos | Manual start or Docker Compose | +| Testing deployed environment | No `webServer`; set `baseURL` via env | +| Multiple services | Array of `webServer` entries | + +### Single vs Multi-Project + +| Scenario | Approach | +|----------|----------| +| Early development | Single project (chromium only) | +| Pre-release validation | Multi-project: chromium + firefox + webkit | +| Mobile-responsive app | Add mobile projects alongside desktop | +| Auth + non-auth tests | Setup project with dependencies | +| Tight CI budget | Chromium on PRs; all browsers on main | + +### globalSetup vs Setup Projects vs Fixtures + +| Need | Use | +|------|-----| +| One-time DB seed | `globalSetup` | +| Shared browser auth | Setup project with `dependencies` | +| Per-test isolated state | Custom fixture via `test.extend()` | +| Cleanup after all tests | `globalTeardown` | + +## Production-Ready Config + +```ts +// playwright.config.ts +import { defineConfig, devices } from '@playwright/test'; +import dotenv from 'dotenv'; +import path from 'path'; + +dotenv.config({ path: path.resolve(__dirname, '.env') }); + +export default defineConfig({ + testDir: './e2e', + testMatch: '**/*.spec.ts', + + fullyParallel: true, + forbidOnly: !!process.env.CI, + retries: process.env.CI ? 2 : 0, + workers: process.env.CI ? '50%' : undefined, + + reporter: process.env.CI + ? [['html', { open: 'never' }], ['github']] + : [['html', { open: 'on-failure' }]], + + timeout: 30_000, + expect: { timeout: 5_000 }, + + use: { + baseURL: process.env.BASE_URL || 'http://localhost:4000', + actionTimeout: 10_000, + navigationTimeout: 15_000, + trace: 'on-first-retry', + screenshot: 'only-on-failure', + video: 'retain-on-failure', + locale: 'en-US', + timezoneId: 'America/Los_Angeles', + }, + + projects: [ + { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, + { name: 'firefox', use: { ...devices['Desktop Firefox'] } }, + { name: 'webkit', use: { ...devices['Desktop Safari'] } }, + { name: 'mobile-chrome', use: { ...devices['Pixel 7'] } }, + { name: 'mobile-safari', use: { ...devices['iPhone 14'] } }, + ], + + webServer: { + command: 'npm run start', + url: 'http://localhost:4000', + reuseExistingServer: !process.env.CI, + timeout: 120_000, + stdout: 'pipe', + stderr: 'pipe', + }, +}); +``` + +## Patterns + +### Environment-Specific Configuration + +**Use when**: Tests run against dev, staging, and production environments. + +```ts +// playwright.config.ts +import { defineConfig } from '@playwright/test'; +import dotenv from 'dotenv'; +import path from 'path'; + +const ENV = process.env.TEST_ENV || 'local'; +dotenv.config({ path: path.resolve(__dirname, `.env.${ENV}`) }); + +const envConfig: Record = { + local: { baseURL: 'http://localhost:4000', retries: 0 }, + staging: { baseURL: 'https://staging.myapp.com', retries: 2 }, + prod: { baseURL: 'https://myapp.com', retries: 2 }, +}; + +export default defineConfig({ + testDir: './e2e', + retries: envConfig[ENV].retries, + use: { baseURL: envConfig[ENV].baseURL }, +}); +``` + +```bash +TEST_ENV=staging npx playwright test +TEST_ENV=prod npx playwright test --grep @smoke +``` + +### Setup Project with Dependencies + +**Use when**: Tests need shared authentication state before running. + +```ts +// playwright.config.ts +import { defineConfig, devices } from '@playwright/test'; + +export default defineConfig({ + testDir: './e2e', + projects: [ + { + name: 'setup', + testMatch: /auth\.setup\.ts/, + }, + { + name: 'chromium', + use: { + ...devices['Desktop Chrome'], + storageState: 'playwright/.auth/session.json', + }, + dependencies: ['setup'], + }, + { + name: 'firefox', + use: { + ...devices['Desktop Firefox'], + storageState: 'playwright/.auth/session.json', + }, + dependencies: ['setup'], + }, + ], +}); +``` + +```ts +// e2e/auth.setup.ts +import { test as setup, expect } from '@playwright/test'; + +const authFile = 'playwright/.auth/session.json'; + +setup('authenticate', async ({ page }) => { + await page.goto('/login'); + await page.getByLabel('Username').fill('testuser@example.com'); + await page.getByLabel('Password').fill(process.env.TEST_PASSWORD!); + await page.getByRole('button', { name: 'Log in' }).click(); + await expect(page.getByRole('heading', { name: 'Home' })).toBeVisible(); + await page.context().storageState({ path: authFile }); +}); +``` + +### webServer with Build Step + +**Use when**: Tests need a running application server managed by Playwright. + +```ts +// playwright.config.ts +import { defineConfig } from '@playwright/test'; + +export default defineConfig({ + testDir: './e2e', + use: { baseURL: 'http://localhost:4000' }, + webServer: { + command: process.env.CI + ? 'npm run build && npm run preview' + : 'npm run dev', + url: 'http://localhost:4000', + reuseExistingServer: !process.env.CI, + timeout: 120_000, + env: { + NODE_ENV: 'test', + DB_URL: process.env.DB_URL || 'postgresql://localhost:5432/testdb', + }, + }, +}); +``` + +### globalSetup / globalTeardown + +**Use when**: One-time non-browser work like seeding a database. Runs once per test run. + +```ts +// playwright.config.ts +import { defineConfig } from '@playwright/test'; + +export default defineConfig({ + testDir: './e2e', + globalSetup: './e2e/setup.ts', + globalTeardown: './e2e/teardown.ts', +}); +``` + +```ts +// e2e/setup.ts +import { FullConfig } from '@playwright/test'; + +export default async function globalSetup(config: FullConfig) { + const { execSync } = await import('child_process'); + execSync('npx prisma db seed', { stdio: 'inherit' }); + process.env.TEST_RUN_ID = `run-${Date.now()}`; +} +``` + +```ts +// e2e/teardown.ts +import { FullConfig } from '@playwright/test'; + +export default async function globalTeardown(config: FullConfig) { + const { execSync } = await import('child_process'); + execSync('npx prisma db push --force-reset', { stdio: 'inherit' }); +} +``` + +### Environment Variables with .env + +**Use when**: Managing secrets, URLs, or feature flags without hardcoding. + +```bash +# .env.example (commit this) +BASE_URL=http://localhost:4000 +TEST_PASSWORD= +API_KEY= + +# .env.local (gitignored) +BASE_URL=http://localhost:4000 +TEST_PASSWORD=secret123 +API_KEY=dev-key-abc + +# .env.staging (gitignored) +BASE_URL=https://staging.myapp.com +TEST_PASSWORD=staging-pass +API_KEY=staging-key-xyz +``` + +```bash +# .gitignore +.env +.env.local +.env.staging +.env.production +playwright/.auth/ +``` + +Install dotenv: + +```bash +npm install -D dotenv +``` + +### Tag-Based Test Filtering + +**Use when**: Running subsets of tests in different CI stages (PR vs nightly). + +```ts +// playwright.config.ts +import { defineConfig } from '@playwright/test'; + +export default defineConfig({ + testDir: './e2e', + + // Filter by tags in CI + grep: process.env.CI ? /@smoke|@critical/ : undefined, + grepInvert: process.env.CI ? /@flaky/ : undefined, +}); +``` + +**Project-specific filtering:** + +```ts +// playwright.config.ts +import { defineConfig, devices } from '@playwright/test'; + +export default defineConfig({ + testDir: './e2e', + projects: [ + { + name: 'smoke', + grep: /@smoke/, + use: { ...devices['Desktop Chrome'] }, + }, + { + name: 'regression', + grepInvert: /@smoke/, + use: { ...devices['Desktop Chrome'] }, + }, + { + name: 'critical-only', + grep: /@critical/, + use: { ...devices['Desktop Chrome'] }, + }, + ], +}); +``` + +```bash +# Run specific project +npx playwright test --project=smoke +npx playwright test --project=regression +``` + +### Artifact Collection Strategy + +| Setting | Local | CI | Reason | +|---------|-------|-----|--------| +| `trace` | `'off'` | `'on-first-retry'` | Traces are large; collect on failure only | +| `screenshot` | `'off'` | `'only-on-failure'` | Useful for CI debugging | +| `video` | `'off'` | `'retain-on-failure'` | Recording slows tests | + +```ts +// playwright.config.ts +import { defineConfig } from '@playwright/test'; + +export default defineConfig({ + testDir: './e2e', + use: { + trace: process.env.CI ? 'on-first-retry' : 'off', + screenshot: process.env.CI ? 'only-on-failure' : 'off', + video: process.env.CI ? 'retain-on-failure' : 'off', + }, +}); +``` + +## Anti-Patterns + +| Don't | Problem | Do Instead | +|-------|---------|------------| +| `timeout: 300_000` globally | Masks flaky tests; slow CI | Fix root cause; keep 30s default | +| Hardcoded URLs: `page.goto('http://localhost:4000/login')` | Breaks in other environments | Use `baseURL` + relative paths | +| All browsers on every PR | 3x CI time | Chromium on PRs; all on main | +| `trace: 'on'` always | Huge artifacts, slow uploads | `trace: 'on-first-retry'` | +| `video: 'on'` always | Massive storage; slow tests | `video: 'retain-on-failure'` | +| Config in test files: `test.use({ viewport: {...} })` everywhere | Scattered, inconsistent | Define once in project config | +| `retries: 3` locally | Hides flakiness | `retries: 0` local, `retries: 2` CI | +| No `forbidOnly` in CI | Committed `test.only` runs single test | `forbidOnly: !!process.env.CI` | +| `globalSetup` for browser auth | No browser context available | Use setup project with dependencies | +| Committing `.env` with credentials | Security risk | Commit `.env.example` only | + +## Troubleshooting + +### baseURL Not Working + +**Cause**: Using absolute URL in `page.goto()` ignores `baseURL`. + +```ts +// Wrong - ignores baseURL +await page.goto('http://localhost:4000/dashboard'); + +// Correct - uses baseURL +await page.goto('/dashboard'); +``` + +### webServer Starts But Tests Get Connection Refused + +**Cause**: `webServer.url` doesn't match actual server address or health check returns non-200. + +```ts +webServer: { + command: 'npm run dev', + url: 'http://localhost:4000/api/health', // use real endpoint + reuseExistingServer: !process.env.CI, + timeout: 120_000, +}, +``` + +### Tests Pass Locally But Timeout in CI + +**Cause**: CI machines are slower. Increase timeouts and reduce workers: + +```ts +export default defineConfig({ + workers: process.env.CI ? '50%' : undefined, + use: { + navigationTimeout: process.env.CI ? 30_000 : 15_000, + actionTimeout: process.env.CI ? 15_000 : 10_000, + }, +}); +``` + +### "Target page, context or browser has been closed" + +**Cause**: Test exceeded `timeout` and Playwright tore down browser during action. + +**Fix**: Don't increase global timeout. Find slow step using trace: + +```bash +npx playwright test --trace on +npx playwright show-report +``` + +## Related + +- [test-tags.md](./test-tags.md) - tagging and filtering tests with `--grep` +- [fixtures-hooks.md](./fixtures-hooks.md) - custom fixtures for per-test state +- [test-suite-structure.md](test-suite-structure.md) - file structure and naming +- [authentication.md](../advanced/authentication.md) - setup projects for shared auth +- [projects-dependencies.md](./projects-dependencies.md) - advanced multi-project patterns diff --git a/.cursor/skills/playwright-testing/core/fixtures-hooks.md b/.cursor/skills/playwright-testing/core/fixtures-hooks.md new file mode 100644 index 0000000000..ff9dc93f71 --- /dev/null +++ b/.cursor/skills/playwright-testing/core/fixtures-hooks.md @@ -0,0 +1,417 @@ +# Fixtures & Hooks + +## Table of Contents + +1. [Built-in Fixtures](#built-in-fixtures) +2. [Custom Fixtures](#custom-fixtures) +3. [Fixture Scopes](#fixture-scopes) +4. [Hooks](#hooks) +5. [Authentication Patterns](#authentication-patterns) +6. [Database Fixtures](#database-fixtures) + +## Built-in Fixtures + +### Core Fixtures + +```typescript +test("example", async ({ + page, // Isolated page instance + context, // Browser context (cookies, localStorage) + browser, // Browser instance + browserName, // 'chromium', 'firefox', or 'webkit' + request, // API request context +}) => { + // Each test gets fresh instances +}); +``` + +### Request Fixture + +```typescript +test("API call", async ({ request }) => { + const response = await request.get("/api/users"); + await expect(response).toBeOK(); + + const users = await response.json(); + expect(users).toHaveLength(5); +}); +``` + +## Custom Fixtures + +### Basic Custom Fixture + +```typescript +// fixtures.ts +import { test as base } from "@playwright/test"; + +// Declare fixture types +type MyFixtures = { + todoPage: TodoPage; + apiClient: ApiClient; +}; + +export const test = base.extend({ + // Fixture with setup and teardown + todoPage: async ({ page }, use) => { + const todoPage = new TodoPage(page); + await todoPage.goto(); + + await use(todoPage); // Test runs here + + // Teardown (optional) + await todoPage.clearTodos(); + }, + + // Simple fixture + apiClient: async ({ request }, use) => { + await use(new ApiClient(request)); + }, +}); + +export { expect } from "@playwright/test"; +``` + +### Fixture with Options + +```typescript +type Options = { + defaultUser: { email: string; password: string }; +}; + +type Fixtures = { + authenticatedPage: Page; +}; + +export const test = base.extend({ + // Define option with default + defaultUser: [ + { email: "test@example.com", password: "pass123" }, + { option: true }, + ], + + // Use option in fixture + authenticatedPage: async ({ page, defaultUser }, use) => { + await page.goto("/login"); + await page.getByLabel("Email").fill(defaultUser.email); + await page.getByLabel("Password").fill(defaultUser.password); + await page.getByRole("button", { name: "Sign in" }).click(); + await use(page); + }, +}); + +// Override in config +export default defineConfig({ + use: { + defaultUser: { email: "admin@example.com", password: "admin123" }, + }, +}); +``` + +### Automatic Fixtures + +```typescript +export const test = base.extend<{}, { setupDb: void }>({ + // Auto-fixture runs for every test without explicit usage + setupDb: [ + async ({}, use) => { + await seedDatabase(); + await use(); + await cleanDatabase(); + }, + { auto: true }, + ], +}); +``` + +## Fixture Scopes + +### Test Scope (Default) + +Created fresh for each test: + +```typescript +test.extend({ + page: async ({ browser }, use) => { + const page = await browser.newPage(); + await use(page); + await page.close(); + }, +}); +``` + +### Worker Scope + +Shared across tests in the same worker (each worker gets its own instance; tests in different workers do not share it): + +```typescript +type WorkerFixtures = { + sharedAccount: Account; +}; + +export const test = base.extend<{}, WorkerFixtures>({ + sharedAccount: [ + async ({ browser }, use) => { + // Expensive setup - runs once per worker + const account = await createTestAccount(); + await use(account); + await deleteTestAccount(account); + }, + { scope: "worker" }, + ], +}); +``` + +### Isolate test data between parallel workers + +When tests in different workers touch the same backend or DB (e.g. same user, same tenant), they can collide and cause flaky failures. Use `testInfo.workerIndex` (or `process.env.TEST_WORKER_INDEX`) in a worker-scoped fixture to create unique data per worker: + +```typescript +import { test as baseTest } from "@playwright/test"; + +type WorkerFixtures = { + dbUserName: string; +}; + +export const test = baseTest.extend<{}, WorkerFixtures>({ + dbUserName: [ + async ({}, use, testInfo) => { + const userName = `user-${testInfo.workerIndex}`; + await createUserInTestDatabase(userName); + await use(userName); + await deleteUserFromTestDatabase(userName); + }, + { scope: "worker" }, + ], +}); +``` + +Then each worker uses a distinct user (e.g. `user-1`, `user-2`), so parallel workers do not overwrite each other’s data. + +## Hooks + +### beforeEach / afterEach + +```typescript +test.beforeEach(async ({ page }) => { + // Runs before each test in file + await page.goto("/"); +}); + +test.afterEach(async ({ page }, testInfo) => { + // Runs after each test + if (testInfo.status !== "passed") { + await page.screenshot({ path: `failed-${testInfo.title}.png` }); + } +}); +``` + +### beforeAll / afterAll + +```typescript +test.beforeAll(async ({ browser }) => { + // Runs once before all tests in file + // Note: Cannot use page fixture here +}); + +test.afterAll(async () => { + // Runs once after all tests in file +}); +``` + +### Describe-Level Hooks + +```typescript +test.describe("User Management", () => { + test.beforeEach(async ({ page }) => { + await page.goto("/users"); + }); + + test("can list users", async ({ page }) => { + // Starts at /users + }); + + test("can add user", async ({ page }) => { + // Starts at /users + }); +}); +``` + +## Authentication Patterns + +### Global Setup with Storage State + +```typescript +// auth.setup.ts +import { test as setup, expect } from "@playwright/test"; + +const authFile = ".auth/user.json"; + +setup("authenticate", async ({ page }) => { + await page.goto("/login"); + await page.getByLabel("Email").fill(process.env.TEST_EMAIL!); + await page.getByLabel("Password").fill(process.env.TEST_PASSWORD!); + await page.getByRole("button", { name: "Sign in" }).click(); + + await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible(); + await page.context().storageState({ path: authFile }); +}); +``` + +```typescript +// playwright.config.ts +export default defineConfig({ + projects: [ + { name: "setup", testMatch: /.*\.setup\.ts/ }, + { + name: "chromium", + use: { + ...devices["Desktop Chrome"], + storageState: ".auth/user.json", + }, + dependencies: ["setup"], + }, + ], +}); +``` + +### Multiple Auth States + +```typescript +// auth.setup.ts +setup("admin auth", async ({ page }) => { + await login(page, "admin@example.com", "adminpass"); + await page.context().storageState({ path: ".auth/admin.json" }); +}); + +setup("user auth", async ({ page }) => { + await login(page, "user@example.com", "userpass"); + await page.context().storageState({ path: ".auth/user.json" }); +}); +``` + +```typescript +// playwright.config.ts +projects: [ + { + name: "admin tests", + testMatch: /.*admin.*\.spec\.ts/, + use: { storageState: ".auth/admin.json" }, + dependencies: ["setup"], + }, + { + name: "user tests", + testMatch: /.*user.*\.spec\.ts/, + use: { storageState: ".auth/user.json" }, + dependencies: ["setup"], + }, +]; +``` + +### Auth Fixture + +```typescript +// fixtures/auth.fixture.ts +export const test = base.extend<{ adminPage: Page; userPage: Page }>({ + adminPage: async ({ browser }, use) => { + const context = await browser.newContext({ + storageState: ".auth/admin.json", + }); + const page = await context.newPage(); + await use(page); + await context.close(); + }, + + userPage: async ({ browser }, use) => { + const context = await browser.newContext({ + storageState: ".auth/user.json", + }); + const page = await context.newPage(); + await use(page); + await context.close(); + }, +}); +``` + +## Database Fixtures + +This section covers **per-test database fixtures** (isolation, transaction rollback). For related topics: + +- **Test data factories** (builders, Faker): See [test-data.md](test-data.md) +- **One-time database setup** (migrations, snapshots): See [global-setup.md](global-setup.md#database-patterns) + +### Transaction Rollback Pattern + +```typescript +import { test as base } from "@playwright/test"; +import { db } from "../db"; + +export const test = base.extend<{ dbTransaction: Transaction }>({ + dbTransaction: async ({}, use) => { + const transaction = await db.beginTransaction(); + + await use(transaction); + + await transaction.rollback(); // Clean slate for next test + }, +}); +``` + +### Seed Data Fixture + +```typescript +type TestData = { + testUser: User; + testProducts: Product[]; +}; + +export const test = base.extend({ + testUser: async ({}, use) => { + const user = await db.users.create({ + email: `test-${Date.now()}@example.com`, + name: "Test User", + }); + + await use(user); + + await db.users.delete(user.id); + }, + + testProducts: async ({ testUser }, use) => { + const products = await db.products.createMany([ + { name: "Product A", ownerId: testUser.id }, + { name: "Product B", ownerId: testUser.id }, + ]); + + await use(products); + + await db.products.deleteMany(products.map((p) => p.id)); + }, +}); +``` + +## Fixture Tips + +| Tip | Explanation | +| ------------------ | ------------------------------------------- | +| Fixtures are lazy | Only created when used | +| Compose fixtures | Use other fixtures as dependencies | +| Keep setup minimal | Do heavy lifting in worker-scoped fixtures | +| Clean up resources | Use teardown in fixtures, not afterEach | +| Avoid shared state | Each fixture instance should be independent | + +## Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Solution | +| ----------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Shared mutable state between tests | Race conditions, order dependencies | Use fixtures for isolation | +| Global variables in tests | Tests depend on execution order | Use fixtures or beforeEach for setup | +| Not cleaning up test data | Tests interfere with each other | Use fixtures with teardown or database transactions | +| Shared `page` or `context` in `beforeAll` | State leak between tests; flaky when tests run in parallel | Use default one-context-per-test, or `beforeEach` + fresh page; if serial is required, prefer `test.describe.configure({ mode: 'serial' })` and document that isolation is sacrificed | +| Backend/DB state shared across workers | Tests in different workers collide on same data | Use worker-scoped fixture with `testInfo.workerIndex` to create unique data per worker | + +## Related References + +- **Page Objects with fixtures**: See [page-object-model.md](page-object-model.md) for POM patterns +- **Test organization**: See [test-suite-structure.md](test-suite-structure.md) for test structure +- **Debugging fixture issues**: See [debugging.md](../debugging/debugging.md) for troubleshooting diff --git a/.cursor/skills/playwright-testing/core/global-setup.md b/.cursor/skills/playwright-testing/core/global-setup.md new file mode 100644 index 0000000000..a0335226e7 --- /dev/null +++ b/.cursor/skills/playwright-testing/core/global-setup.md @@ -0,0 +1,434 @@ +# Global Setup & Teardown + +## Table of Contents + +1. [Global Setup](#global-setup) +2. [Global Teardown](#global-teardown) +3. [Database Patterns](#database-patterns) +4. [Environment Provisioning](#environment-provisioning) +5. [Setup Projects vs Global Setup](#setup-projects-vs-global-setup) +6. [Parallel Execution Caveats](#parallel-execution-caveats) + +## Global Setup + +### Basic Global Setup + +```typescript +// global-setup.ts +import { FullConfig } from "@playwright/test"; + +async function globalSetup(config: FullConfig) { + console.log("Running global setup..."); + // Perform one-time setup: start services, run migrations, etc. +} + +export default globalSetup; +``` + +### Configure Global Setup + +```typescript +// playwright.config.ts +import { defineConfig } from "@playwright/test"; + +export default defineConfig({ + globalSetup: require.resolve("./global-setup"), + globalTeardown: require.resolve("./global-teardown"), +}); +``` + +> **Authentication in Global Setup**: For authentication patterns using storage state in global setup, see [fixtures-hooks.md](fixtures-hooks.md#authentication-patterns). Setup projects are generally preferred for authentication as they provide access to Playwright fixtures. + +### Global Setup with Return Value + +```typescript +// global-setup.ts +async function globalSetup(config: FullConfig): Promise<() => Promise> { + const server = await startTestServer(); + + // Return cleanup function (alternative to globalTeardown) + return async () => { + await server.stop(); + }; +} + +export default globalSetup; +``` + +### Access Config in Global Setup + +```typescript +// global-setup.ts +import { FullConfig } from "@playwright/test"; + +async function globalSetup(config: FullConfig) { + const { baseURL } = config.projects[0].use; + console.log(`Setting up for ${baseURL}`); + + // Access custom config + const workers = config.workers; + const timeout = config.timeout; + + // Access environment + const isCI = !!process.env.CI; +} + +export default globalSetup; +``` + +## Global Teardown + +### Basic Global Teardown + +```typescript +// global-teardown.ts +import { FullConfig } from "@playwright/test"; +import fs from "fs"; + +async function globalTeardown(config: FullConfig) { + console.log("Running global teardown..."); + + // Clean up auth files + if (fs.existsSync(".auth")) { + fs.rmSync(".auth", { recursive: true }); + } + + // Clean up test data + await cleanupTestDatabase(); + + // Stop services + await stopTestServices(); +} + +export default globalTeardown; +``` + +### Conditional Teardown + +```typescript +// global-teardown.ts +async function globalTeardown(config: FullConfig) { + // Skip cleanup in CI (containers are discarded anyway) + if (process.env.CI) { + console.log("Skipping teardown in CI"); + return; + } + + // Local cleanup + await cleanupLocalTestData(); +} + +export default globalTeardown; +``` + +## Database Patterns + +This section covers **one-time database setup** (migrations, snapshots, per-worker databases). For related topics: + +- **Per-test database fixtures** (isolation, transaction rollback): See [fixtures-hooks.md](fixtures-hooks.md#database-fixtures) +- **Test data factories** (builders, Faker): See [test-data.md](test-data.md) + +### Database Migration in Setup + +```typescript +// global-setup.ts +import { execSync } from "child_process"; + +async function globalSetup() { + console.log("Running database migrations..."); + + // Run migrations + execSync("npx prisma migrate deploy", { stdio: "inherit" }); + + // Seed test data + execSync("npx prisma db seed", { stdio: "inherit" }); +} + +export default globalSetup; +``` + +### Database Snapshot Pattern + +```typescript +// global-setup.ts +import { execSync } from "child_process"; +import fs from "fs"; + +const SNAPSHOT_PATH = "./test-db-snapshot.sql"; + +async function globalSetup() { + // Check if snapshot exists + if (fs.existsSync(SNAPSHOT_PATH)) { + console.log("Restoring database from snapshot..."); + execSync(`psql $DATABASE_URL < ${SNAPSHOT_PATH}`, { stdio: "inherit" }); + return; + } + + // First run: migrate and create snapshot + console.log("Creating database snapshot..."); + execSync("npx prisma migrate deploy", { stdio: "inherit" }); + execSync("npx prisma db seed", { stdio: "inherit" }); + execSync(`pg_dump $DATABASE_URL > ${SNAPSHOT_PATH}`, { stdio: "inherit" }); +} + +export default globalSetup; +``` + +### Test Database per Worker + +```typescript +// global-setup.ts +async function globalSetup(config: FullConfig) { + const workerCount = config.workers || 1; + + // Create a database for each worker + for (let i = 0; i < workerCount; i++) { + const dbName = `test_db_worker_${i}`; + await createDatabase(dbName); + await runMigrations(dbName); + await seedDatabase(dbName); + } +} + +// global-teardown.ts +async function globalTeardown(config: FullConfig) { + const workerCount = config.workers || 1; + + for (let i = 0; i < workerCount; i++) { + await dropDatabase(`test_db_worker_${i}`); + } +} +``` + +## Environment Provisioning + +### Start Services in Setup + +```typescript +// global-setup.ts +import { execSync, spawn } from "child_process"; + +let serverProcess: any; + +async function globalSetup() { + // Start backend server + serverProcess = spawn("npm", ["run", "start:test"], { + stdio: "pipe", + detached: true, + }); + + // Wait for server to be ready + await waitForServer("http://localhost:3000/health", 30000); + + // Store PID for teardown + process.env.SERVER_PID = serverProcess.pid.toString(); +} + +async function waitForServer(url: string, timeout: number) { + const start = Date.now(); + + while (Date.now() - start < timeout) { + try { + const response = await fetch(url); + if (response.ok) return; + } catch { + // Server not ready yet + } + await new Promise((r) => setTimeout(r, 1000)); + } + + throw new Error(`Server did not start within ${timeout}ms`); +} + +export default globalSetup; +``` + +### Docker Compose Setup + +```typescript +// global-setup.ts +import { execSync } from "child_process"; + +async function globalSetup() { + console.log("Starting Docker services..."); + + execSync("docker-compose -f docker-compose.test.yml up -d", { + stdio: "inherit", + }); + + // Wait for services to be healthy + execSync("docker-compose -f docker-compose.test.yml exec -T db pg_isready", { + stdio: "inherit", + }); +} + +export default globalSetup; +``` + +```typescript +// global-teardown.ts +import { execSync } from "child_process"; + +async function globalTeardown() { + console.log("Stopping Docker services..."); + + execSync("docker-compose -f docker-compose.test.yml down -v", { + stdio: "inherit", + }); +} + +export default globalTeardown; +``` + +### Environment Variables Setup + +```typescript +// global-setup.ts +import dotenv from "dotenv"; +import path from "path"; + +async function globalSetup() { + // Load test-specific environment + const envFile = process.env.CI ? ".env.ci" : ".env.test"; + dotenv.config({ path: path.resolve(process.cwd(), envFile) }); + + // Validate required variables + const required = ["DATABASE_URL", "API_KEY", "TEST_EMAIL"]; + for (const key of required) { + if (!process.env[key]) { + throw new Error(`Missing required environment variable: ${key}`); + } + } +} + +export default globalSetup; +``` + +## Setup Projects vs Global Setup + +### When to Use Each + +| Use Global Setup | Use Setup Projects | +| ------------------------------------- | ---------------------------------------- | +| One-time setup (migrations, services) | Per-project setup (auth states) | +| No access to Playwright fixtures | Need page, request fixtures | +| Runs once before all projects | Can run per-project or have dependencies | +| Shared across all workers | Can be parallelized | + +### Setup Project Pattern + +```typescript +// playwright.config.ts +export default defineConfig({ + projects: [ + // Setup project + { + name: "setup", + testMatch: /.*\.setup\.ts/, + }, + // Test projects depend on setup + { + name: "chromium", + use: { ...devices["Desktop Chrome"] }, + dependencies: ["setup"], + }, + { + name: "firefox", + use: { ...devices["Desktop Firefox"] }, + dependencies: ["setup"], + }, + ], +}); +``` + +> **For complete authentication setup patterns**, see [fixtures-hooks.md](fixtures-hooks.md#authentication-patterns). + +### Combining Both + +```typescript +// playwright.config.ts +export default defineConfig({ + // Global: Start services, run migrations + globalSetup: require.resolve("./global-setup"), + globalTeardown: require.resolve("./global-teardown"), + + projects: [ + // Setup project: Create auth states + { name: "setup", testMatch: /.*\.setup\.ts/ }, + { + name: "chromium", + use: { + ...devices["Desktop Chrome"], + storageState: ".auth/user.json", + }, + dependencies: ["setup"], + }, + ], +}); +``` + +## Parallel Execution Caveats + +### Understanding Global Setup Execution + +``` +┌─────────────────────────────────────────────────────────────┐ +│ globalSetup runs ONCE │ +│ ↓ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ Worker 1│ │ Worker 2│ │ Worker 3│ │ Worker 4│ │ +│ │ tests │ │ tests │ │ tests │ │ tests │ │ +│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ +│ ↓ │ +│ globalTeardown runs ONCE │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Key implications:** + +- Global setup has **no access** to Playwright fixtures (`page`, `request`, `context`) +- State created in global setup is **shared** across all workers +- If tests **modify** shared state, they may conflict with parallel workers +- Global setup **cannot** react to individual test needs + +### When to Prefer Worker-Scoped Fixtures + +Use **worker-scoped fixtures** instead of globalSetup when: + +| Scenario | Why Fixtures Are Better | +| ------------------------------------ | ---------------------------------------------------- | +| Each worker needs isolated resources | Fixtures can create per-worker databases, servers | +| Setup needs Playwright APIs | Fixtures have access to `page`, `request`, `browser` | +| Setup depends on test configuration | Fixtures receive test context and options | +| Resources need cleanup per worker | Worker fixtures auto-cleanup when worker exits | + +### Common Parallel Pitfall + +```typescript +// ❌ BAD: Global setup creates ONE user, all workers fight over it +async function globalSetup() { + await createUser({ email: "test@example.com" }); // Shared! +} + +// ✅ GOOD: Each worker gets its own user via worker-scoped fixture +// Uses workerInfo.workerIndex to create unique data per worker +``` + +> **For worker-scoped fixture patterns** (per-worker databases, unique test data, `workerIndex` isolation), see [fixtures-hooks.md](fixtures-hooks.md#isolate-test-data-between-parallel-workers). + +## Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Solution | +| ------------------------------ | -------------------------------- | ------------------------------------------ | +| Heavy setup in globalSetup | Slow test startup | Use setup projects for parallelizable work | +| Not cleaning up in teardown | Leaks resources, flaky CI | Always clean up or use containers | +| Hardcoded URLs in setup | Breaks in different environments | Use config.projects[0].use.baseURL | +| No timeout on service wait | Hangs forever if service fails | Add timeout with clear error | +| Shared mutable state | Race conditions in parallel | Use worker-scoped fixtures for isolation | +| Global setup for per-test data | Tests conflict | Use test-scoped fixtures | + +## Related References + +- **Fixtures & Auth**: See [fixtures-hooks.md](fixtures-hooks.md) for worker-scoped fixtures and auth patterns +- **CI/CD**: See [ci-cd.md](../infrastructure-ci-cd/ci-cd.md) for CI setup patterns +- **Projects**: See [projects-dependencies.md](projects-dependencies.md) for project configuration diff --git a/.cursor/skills/playwright-testing/core/locators.md b/.cursor/skills/playwright-testing/core/locators.md new file mode 100644 index 0000000000..afe3af3616 --- /dev/null +++ b/.cursor/skills/playwright-testing/core/locators.md @@ -0,0 +1,242 @@ +# Locator Strategies + +## Table of Contents + +1. [Priority Order](#priority-order) +2. [User-Facing Locators](#user-facing-locators) +3. [Filtering & Chaining](#filtering--chaining) +4. [Dynamic Content](#dynamic-content) +5. [Shadow DOM](#shadow-dom) +6. [Iframes](#iframes) + +## Priority Order + +Use locators in this order of preference: + +1. **Role-based** (most resilient): `getByRole` +2. **Label-based**: `getByLabel`, `getByPlaceholder` +3. **Text-based**: `getByText`, `getByTitle` +4. **Test IDs** (when semantic locators aren't possible): `getByTestId` +5. **CSS/XPath** (last resort): `locator('css=...')`, `locator('xpath=...')` + +## User-Facing Locators + +### getByRole + +Most robust approach - matches how users and assistive technology perceive the page. + +```typescript +// Buttons +page.getByRole("button", { name: "Submit", exact: true }); // exact accessible name +page.getByRole("button", { name: /submit/i }); // flexible case-insensitive match + +// Links +page.getByRole("link", { name: "Home" }); + +// Form elements +page.getByRole("textbox", { name: "Email" }); +page.getByRole("checkbox", { name: "Remember me" }); +page.getByRole("combobox", { name: "Country" }); +page.getByRole("radio", { name: "Option A" }); + +// Headings +page.getByRole("heading", { name: "Welcome", level: 1 }); + +// Lists & items +page.getByRole("list").getByRole("listitem"); + +// Navigation & regions +page.getByRole("navigation"); +page.getByRole("main"); +page.getByRole("dialog"); +page.getByRole("alert"); +``` + +### getByLabel + +For form elements with associated labels. + +```typescript +// Input with