apunkt/SurfSense
1
0
Fork 0
mirror of https://github.com/MODSetter/SurfSense.git synced 2026-04-25 00:36:31 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Merge remote-tracking branch 'upstream/dev' into fix/sensitive-actions

Browse source
This commit is contained in:
Anish Sarkar 2026-04-14 04:10:00 +05:30
commit 136901276a
126 changed files with 26088 additions and 380 deletions
Download patch file Download diff file Expand all files Collapse all files

337
.cursor/skills/alert-manager/SKILL.md Normal file
View file

@ -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: "<domain> [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-<topic>.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.

293
.cursor/skills/alert-manager/references/alert-configuration-templates.md Normal file
View file

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

377
.cursor/skills/alert-manager/references/alert-threshold-guide.md Normal file
View file

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

301
.cursor/skills/backlink-analyzer/SKILL.md Normal file
View file

@ -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: "<domain or URL>"
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-<topic>.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.

354
.cursor/skills/backlink-analyzer/references/analysis-templates.md Normal file
View file

@ -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% |
```

292
.cursor/skills/backlink-analyzer/references/link-quality-rubric.md Normal file
View file

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

578
.cursor/skills/backlink-analyzer/references/outreach-templates.md Normal file
View file

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

309
.cursor/skills/competitor-analysis/SKILL.md Normal file
View file

@ -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: "<competitor URL or domain>"
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-<topic>.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.

285
.cursor/skills/competitor-analysis/references/analysis-templates.md Normal file
View file

@ -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]
```

256
.cursor/skills/competitor-analysis/references/battlecard-template.md Normal file
View file

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

75
.cursor/skills/competitor-analysis/references/example-report.md Normal file
View file

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

320
.cursor/skills/competitor-analysis/references/positioning-frameworks.md Normal file
View file

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

287
.cursor/skills/content-gap-analysis/SKILL.md Normal file
View file

@ -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: "<your domain> <competitor domain>"
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-<topic>.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.

335
.cursor/skills/content-gap-analysis/references/analysis-templates.md Normal file
View file

@ -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] |
```

47
.cursor/skills/content-gap-analysis/references/example-report.md Normal file
View file

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

318
.cursor/skills/content-gap-analysis/references/gap-analysis-frameworks.md Normal file
View file

@ -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 | <your domain's competitive range | Ensure you can rank |
| Business relevance | Must relate to your product/service | Ensure strategic fit |
| Intent match | Must match content types you can create | Ensure execution capability |
**After filtering, categorize remaining gaps:**
| Category | Description | Example |
|----------|-----------|---------|
| Topic gaps | Entire topics you haven't covered | Competitor has 10 articles on "technical SEO"; you have zero |
| Depth gaps | You cover the topic but competitor goes deeper | You have 1 blog post; competitor has a pillar page + 8 cluster articles |
| Angle gaps | Same topic but different perspective or audience | Competitor targets enterprise; you could target SMB |
| Format gaps | Same keyword but different content format | Competitor has a video tutorial; you only have text |
| Freshness gaps | Same topic but their content is more current | Competitor updated in 2026; yours is from 2024 |
#### Step 5: Prioritize Gaps
Use the scoring model from Section 4 below.
---
## 2. Content Format Gap Analysis
### Format Audit Methodology
#### Step 1: Inventory Your Content Formats
Categorize all your published content:
| Format | Count | % of Total | Avg. Traffic/Page | Top Performer |
|--------|-------|-----------|-------------------|--------------|
| Blog posts (text) | [X] | [X]% | [X] | [URL] |
| Long-form guides | [X] | [X]% | [X] | [URL] |
| How-to tutorials | [X] | [X]% | [X] | [URL] |
| Comparison/vs pages | [X] | [X]% | [X] | [URL] |
| Case studies | [X] | [X]% | [X] | [URL] |
| Templates/downloads | [X] | [X]% | [X] | [URL] |
| Interactive tools | [X] | [X]% | [X] | [URL] |
| Video content | [X] | [X]% | [X] | [URL] |
| Infographics | [X] | [X]% | [X] | [URL] |
| Original research/data | [X] | [X]% | [X] | [URL] |
| Glossary/definitions | [X] | [X]% | [X] | [URL] |
| Webinars/recordings | [X] | [X]% | [X] | [URL] |
| Podcasts/audio | [X] | [X]% | [X] | [URL] |
#### Step 2: Benchmark Against Competitors
| Format | You | Comp A | Comp B | Comp C | Industry Benchmark |
|--------|-----|--------|--------|--------|-------------------|
| Blog posts | [X] | [X] | [X] | [X] | Table stakes |
| Long-form guides | [X] | [X] | [X] | [X] | Expected for authority |
| How-to tutorials | [X] | [X] | [X] | [X] | Expected for SEO |
| Comparison pages | [X] | [X] | [X] | [X] | Required for commercial |
| Case studies | [X] | [X] | [X] | [X] | Expected for B2B |
| Templates | [X] | [X] | [X] | [X] | Lead gen standard |
| Interactive tools | [X] | [X] | [X] | [X] | Differentiator |
| Video | [X] | [X] | [X] | [X] | Growing expectation |
| Original research | [X] | [X] | [X] | [X] | Linkbait standard |
| Glossary | [X] | [X] | [X] | [X] | GEO opportunity |
#### Step 3: Identify Format Gaps
For each format you are missing or underrepresenting:
| Missing Format | Competitor Proof | Estimated Effort | Expected Impact | Priority |
|---------------|-----------------|-----------------|----------------|---------|
| [Format 1] | [Which competitor succeeds + traffic est.] | [Low/Med/High] | [Low/Med/High] | [P0-P3] |
| [Format 2] | [Evidence] | [Effort] | [Impact] | [Priority] |
#### Step 4: Format-SERP Feature Alignment
Certain formats unlock specific SERP features:
| Content Format | Unlocks SERP Feature | Schema Required |
|---------------|---------------------|----------------|
| FAQ sections | FAQ rich results, PAA eligibility | FAQPage |
| Step-by-step tutorials | How-To rich results, Featured Snippet (list) | HowTo |
| Review/comparison content | Review stars, AI Overview citations | Review, AggregateRating |
| Video content | Video carousel, Video rich result | VideoObject |
| Product pages | Shopping results, Product rich results | Product |
| Event pages | Event rich results | Event |
| Glossary/definitions | Featured Snippet (paragraph), AI Overview | DefinedTerm (optional) |
| Data tables | Featured Snippet (table), AI Overview | Table (optional) |
---
## 3. Funnel Stage Gap Identification
### Funnel Coverage Mapping
#### Step 1: Define Funnel Stages and Content Expectations
| Funnel Stage | User Mindset | Content Need | Expected Formats | Typical Keywords |
|-------------|-------------|-------------|-----------------|-----------------|
| **Awareness** | "I have a problem/question" | Educational content | Blog posts, infographics, social content | "what is", "how to", "why does" |
| **Interest** | "I want to learn more" | Deeper educational content | Guides, webinars, email courses | "guide to", "tutorial", "examples" |
| **Consideration** | "What are my options?" | Comparison and evaluation | Comparison posts, reviews, case studies | "best", "vs", "review", "alternatives" |
| **Intent** | "I'm narrowing my choices" | Decision-support content | Demos, free trials, pricing pages, ROI calculators | "pricing", "demo", "free trial" |
| **Purchase** | "I'm ready to act" | Conversion content | Product pages, checkout, signup forms | "buy", "sign up", "get started" |
| **Retention** | "I need help/value" | Support and engagement | Help docs, tutorials, community, newsletters | "[product] how to", "support" |
| **Advocacy** | "I want to share/recommend" | Shareable and referral content | Case studies, review programs, referral incentives | "[product] review", "recommend" |
#### Step 2: Audit Content by Funnel Stage
For each stage, count your content and compare to competitors:
| Funnel Stage | Your Content Count | Comp A | Comp B | Gap Size | Gap Severity |
|-------------|-------------------|--------|--------|----------|-------------|
| Awareness | [X] | [X] | [X] | [+/- X] | [Low/Med/High/Critical] |
| Interest | [X] | [X] | [X] | [+/- X] | [Low/Med/High/Critical] |
| Consideration | [X] | [X] | [X] | [+/- X] | [Low/Med/High/Critical] |
| Intent | [X] | [X] | [X] | [+/- X] | [Low/Med/High/Critical] |
| Purchase | [X] | [X] | [X] | [+/- X] | [Low/Med/High/Critical] |
| Retention | [X] | [X] | [X] | [+/- X] | [Low/Med/High/Critical] |
| Advocacy | [X] | [X] | [X] | [+/- X] | [Low/Med/High/Critical] |
**Gap Severity Criteria:**
| Severity | Definition |
|----------|-----------|
| Critical | Zero content at this stage; users drop off here |
| High | Significantly less content than competitors; measurable conversion drop |
| Medium | Somewhat less content; competitors have advantage but you are present |
| Low | Roughly on par; minor opportunities for improvement |
#### Step 3: Identify Drop-Off Points
Map your analytics data to funnel stages to find where users leave:
| Transition | Metric to Check | Drop-Off Signal | Content Gap Likely |
|-----------|----------------|----------------|-------------------|
| Awareness → Interest | Bounce rate on blog posts | >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 |

403
.cursor/skills/content-quality-auditor/SKILL.md Normal file
View file

@ -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: "<URL or paste content> [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-<topic>.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.

99
.cursor/skills/content-quality-auditor/references/item-reference.md Normal file
View file

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

396
.cursor/skills/content-refresher/SKILL.md Normal file
View file

@ -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: "<URL of outdated content>"
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-<topic>.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.

404
.cursor/skills/content-refresher/references/content-decay-signals.md Normal file
View file

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

143
.cursor/skills/content-refresher/references/refresh-example.md Normal file
View file

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

253
.cursor/skills/content-refresher/references/refresh-templates.md Normal file
View file

@ -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]
```

394
.cursor/skills/domain-authority-auditor/SKILL.md Normal file
View file

@ -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: "<domain>"
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-<topic>.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.

99
.cursor/skills/domain-authority-auditor/references/example-report.md Normal file
View file

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

376
.cursor/skills/entity-optimizer/SKILL.md Normal file
View file

@ -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: "<entity name or brand>"
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/<name>.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-<topic>.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.

137
.cursor/skills/entity-optimizer/references/entity-signal-checklist.md Normal file
View file

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

24
.cursor/skills/entity-optimizer/references/entity-type-reference.md Normal file
View file

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

59
.cursor/skills/entity-optimizer/references/example-audit-report.md Normal file
View file

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

399
.cursor/skills/entity-optimizer/references/knowledge-graph-guide.md Normal file
View file

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

81
.cursor/skills/entity-optimizer/references/knowledge-panel-wikidata-guide.md Normal file
View file

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

420
.cursor/skills/geo-content-optimizer/SKILL.md Normal file
View file

@ -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: "<content URL or text> [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-<topic>.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.

504
.cursor/skills/geo-content-optimizer/references/ai-citation-patterns.md Normal file
View file

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

235
.cursor/skills/geo-content-optimizer/references/geo-optimization-techniques.md Normal file
View file

@ -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
<h2>What is [Topic]?</h2>
<p>[Direct answer in 40-60 words]</p>
<h2>How does [Topic] work?</h2>
<p>[Clear explanation with steps if applicable]</p>
<h2>Why is [Topic] important?</h2>
<p>[Specific reasons with evidence]</p>
```
**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

484
.cursor/skills/geo-content-optimizer/references/quotable-content-examples.md Normal file
View file

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

351
.cursor/skills/internal-linking-optimizer/SKILL.md Normal file
View file

@ -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: "<URL or sitemap>"
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-<topic>.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.

362
.cursor/skills/internal-linking-optimizer/references/link-architecture-patterns.md Normal file
View file

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

42
.cursor/skills/internal-linking-optimizer/references/linking-example.md Normal file
View file

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

219
.cursor/skills/internal-linking-optimizer/references/linking-templates.md Normal file
View file

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

435
.cursor/skills/keyword-research/SKILL.md Normal file
View file

@ -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: "<topic or seed keyword> [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-<topic>.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.

96
.cursor/skills/keyword-research/references/example-report.md Normal file
View file

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

324
.cursor/skills/keyword-research/references/keyword-intent-taxonomy.md Normal file
View file

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

41
.cursor/skills/keyword-research/references/keyword-prioritization-framework.md Normal file
View file

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

286
.cursor/skills/keyword-research/references/topic-cluster-templates.md Normal file
View file

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

342
.cursor/skills/memory-management/SKILL.md Normal file
View file

@ -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/<project>/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/<project>/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-<topic>.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.

138
.cursor/skills/memory-management/references/examples.md Normal file
View file

@ -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"
```

64
.cursor/skills/memory-management/references/glossary-template.md Normal file
View file

@ -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._
```

96
.cursor/skills/memory-management/references/hot-cache-template.md Normal file
View file

@ -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_
```

58
.cursor/skills/memory-management/references/promotion-demotion-rules.md Normal file
View file

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

102
.cursor/skills/memory-management/references/update-triggers-integration.md Normal file
View file

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

417
.cursor/skills/meta-tags-optimizer/SKILL.md Normal file
View file

@ -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: "<page URL or content>"
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
<title>[Selected Title]</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
<meta name="description" content="[Selected Description]">
```
```
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
<title>How to Start a Podcast in [current year]: Complete Beginner's Guide</title>
```
**Length**: ~55 characters ✅
**Keyword**: "how to start a podcast" at front ✅
**Power Words**: "Complete", "Beginner's" ✅
### Meta Description
```html
<meta name="description" content="Learn how to start a podcast in [current year] with our step-by-step guide. Covers equipment, hosting, recording, and launching your first episode. Start podcasting today!">
```
**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-<topic>.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.

149
.cursor/skills/meta-tags-optimizer/references/ctr-and-social-reference.md Normal file
View file

@ -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
<title>[Brand Name] - [Primary Value Proposition]</title>
<meta name="description" content="[Brand] helps [audience] [achieve goal]. [Key feature/benefit]. [CTA]">
```
### Product Page
```html
<title>[Product Name] - [Key Benefit] | [Brand]</title>
<meta name="description" content="[Product] [key features]. [Price/offer if applicable]. [Social proof]. [CTA]">
```
### Blog Post
```html
<title>[How to/What is/Number] [Keyword] [Benefit/Year]</title>
<meta name="description" content="[What they'll learn]. [Key points covered]. [CTA]">
```
### Service Page
```html
<title>[Service] in [Location] - [Brand] | [Differentiator]</title>
<meta name="description" content="[Service description]. [Experience/credentials]. [Key benefit]. [CTA]">
```
---
## 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 |

153
.cursor/skills/meta-tags-optimizer/references/meta-tag-code-templates.md Normal file
View file

@ -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
<!-- Primary Open Graph Tags -->
<meta property="og:type" content="[article/website/product]">
<meta property="og:url" content="[Full canonical URL]">
<meta property="og:title" content="[OG-optimized title - up to 60 chars]">
<meta property="og:description" content="[OG description - up to 200 chars]">
<meta property="og:image" content="[Image URL - 1200x630px recommended]">
<!-- Optional but Recommended -->
<meta property="og:site_name" content="[Website Name]">
<meta property="og:locale" content="en_US">
```
**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 Card Tags -->
<meta name="twitter:card" content="[summary_large_image/summary]">
<meta name="twitter:site" content="@[YourTwitterHandle]">
<meta name="twitter:creator" content="@[AuthorTwitterHandle]">
<meta name="twitter:title" content="[Title - 70 chars max]">
<meta name="twitter:description" content="[Description - 200 chars max]">
<meta name="twitter:image" content="[Image URL]">
<meta name="twitter:image:alt" content="[Image description for accessibility]">
```
**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
<link rel="canonical" href="[Preferred URL]">
```
**Robots Tag** (Indexing control):
```html
<meta name="robots" content="index, follow">
```
**Viewport** (Mobile optimization):
```html
<meta name="viewport" content="width=device-width, initial-scale=1">
```
**Author** (For articles):
```html
<meta name="author" content="[Author Name]">
```
**Language**:
```html
<html lang="en">
```
**Article-Specific** (For blog posts):
```html
<meta property="article:published_time" content="[ISO 8601 date]">
<meta property="article:modified_time" content="[ISO 8601 date]">
<meta property="article:author" content="[Author URL]">
<meta property="article:section" content="[Category]">
<meta property="article:tag" content="[Tag 1]">
```
---
## Complete Meta Tag Block Template
Copy and paste this complete meta tag block:
```html
<!-- Primary Meta Tags -->
<title>[Optimized Title]</title>
<meta name="title" content="[Optimized Title]">
<meta name="description" content="[Optimized Description]">
<link rel="canonical" href="[Canonical URL]">
<!-- Open Graph / Facebook -->
<meta property="og:type" content="[type]">
<meta property="og:url" content="[URL]">
<meta property="og:title" content="[OG Title]">
<meta property="og:description" content="[OG Description]">
<meta property="og:image" content="[Image URL]">
<meta property="og:site_name" content="[Site Name]">
<!-- Twitter -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:url" content="[URL]">
<meta name="twitter:title" content="[Twitter Title]">
<meta name="twitter:description" content="[Twitter Description]">
<meta name="twitter:image" content="[Image URL]">
<!-- Additional -->
<meta name="robots" content="index, follow">
<meta name="author" content="[Author]">
```

355
.cursor/skills/meta-tags-optimizer/references/meta-tag-formulas.md Normal file
View file

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

364
.cursor/skills/on-page-seo-auditor/SKILL.md Normal file
View file

@ -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: "<URL> [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-<topic>.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.

109
.cursor/skills/on-page-seo-auditor/references/audit-example.md Normal file
View file

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

315
.cursor/skills/on-page-seo-auditor/references/audit-templates.md Normal file
View file

@ -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]%
```

496
.cursor/skills/on-page-seo-auditor/references/scoring-rubric.md Normal file
View file

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

263
.cursor/skills/performance-reporter/SKILL.md Normal file
View file

@ -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: "<domain> [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-<topic>.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.

524
.cursor/skills/performance-reporter/references/kpi-definitions.md Normal file
View file

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

417
.cursor/skills/performance-reporter/references/report-output-templates.md Normal file
View file

@ -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]
```

383
.cursor/skills/performance-reporter/references/report-templates.md Normal file
View file

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

275
.cursor/skills/rank-tracker/SKILL.md Normal file
View file

@ -0,0 +1,275 @@
---
name: rank-tracker
description: 'Track keyword rankings and SERP feature changes in traditional search and AI responses over time. 排名追踪/SERP监控'
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 tracking keyword rankings, monitoring position changes, comparing ranking snapshots, or detecting ranking drops."
argument-hint: "<domain> [keyword list]"
metadata:
author: aaron-he-zhu
version: "6.0.0"
geo-relevance: "medium"
tags:
- seo
- geo
- rank-tracking
- keyword-rankings
- serp-positions
- ranking-changes
- position-tracking
- 排名追踪
- ランキング追跡
- 순위추적
- seguimiento-rankings
triggers:
# EN-formal
- "track rankings"
- "check keyword positions"
- "ranking changes"
- "monitor SERP positions"
- "keyword tracking"
- "position monitoring"
# EN-casual
- "how am I ranking"
- "where do I rank for this keyword"
- "did my rankings change"
- "where do I rank now"
- "check my positions"
# EN-question
- "what position am I ranking at"
- "how are my rankings doing"
# ZH-pro
- "排名追踪"
- "关键词排名"
- "SERP位置监控"
- "排名变化"
# ZH-casual
- "查排名"
- "排名变了吗"
- "我排第几"
# JA
- "ランキング追跡"
- "検索順位チェック"
- "順位変動"
- "キーワード順位確認"
# KO
- "순위 추적"
- "키워드 순위"
- "순위 확인"
- "내 순위 어떻게 됐어?"
# ES
- "seguimiento de rankings"
- "posición en buscadores"
- "posicionamiento SEO"
- "en qué posición estoy"
# PT
- "rastreamento de rankings"
- "monitoramento de posições"
- "posição no Google"
# Misspellings
- "rank trackng"
---
# Rank Tracker
> **[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).
Tracks, analyzes, and reports on keyword ranking positions over time. Monitors both traditional SERP rankings and AI/GEO visibility to provide comprehensive search performance insights.
**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 ranking tracking for new campaigns
- Monitoring keyword position changes
- Analyzing ranking trends over time
- Comparing rankings against competitors
- Tracking SERP feature appearances
- Monitoring AI Overview inclusions
- Creating ranking reports for stakeholders
## What This Skill Does
1. **Position Tracking**: Records and tracks keyword rankings
2. **Trend Analysis**: Identifies ranking patterns over time
3. **Movement Detection**: Flags significant position changes
4. **Competitor Comparison**: Benchmarks against competitors
5. **SERP Feature Tracking**: Monitors featured snippets, PAA
6. **GEO Visibility Tracking**: Tracks AI citation appearances
7. **Report Generation**: Creates ranking performance reports
## 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 Tracking
```
Set up rank tracking for [domain] targeting these keywords: [keyword list]
```
### Analyze Rankings
```
Analyze ranking changes for [domain] over the past [time period]
```
### Compare to Competitors
```
Compare my rankings to [competitor] for [keywords]
```
### Generate Reports
```
Create a ranking report for [domain/campaign]
```
## 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 + ~~analytics + ~~AI monitor connected:**
Automatically pull ranking positions from ~~SEO tool, search impressions/clicks from ~~search console, traffic data from ~~analytics, and AI Overview citation tracking from ~~AI monitor. Daily automated rank checks with historical trend data.
**With manual data only:**
Ask the user to provide:
1. Keyword ranking positions (current and historical if available)
2. Target keyword list with search volumes
3. Competitor domains and their ranking positions for key terms
4. SERP feature status (featured snippets, PAA appearances)
5. AI Overview 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 rank tracking or analysis:
1. **Set Up Keyword Tracking** -- Configure domain, location, device, language, update frequency. Add keywords with volume, current rank, type, and priority. Set up competitor tracking and keyword categories (brand/product/informational/commercial).
2. **Record Current Rankings** -- Ranking overview by position range (#1, #2-3, #4-10, #11-20, etc.), position distribution visualization, detailed rankings with URL, SERP features, and change.
3. **Analyze Ranking Changes** -- Overall movement metrics, biggest improvements and declines with hypothesized causes, recommended recovery actions, stable keywords, new rankings, lost rankings.
4. **Track SERP Features** -- Feature ownership comparison vs competitors (snippets, PAA, image/video pack, local pack), featured snippet status, PAA appearances.
5. **Track GEO/AI Visibility** -- AI Overview presence per keyword, citation rate and position, GEO performance trend over time, improvement opportunities.
6. **Compare Against Competitors** -- Share of voice table, head-to-head comparison per keyword, competitor movement alerts with threat level.
7. **Generate Ranking Report** -- Executive summary with overall trend, position distribution, key highlights (wins/concerns/opportunities), detailed analysis, SERP feature report, GEO visibility, competitive position, recommendations.
> **Reference**: See [references/ranking-analysis-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/rank-tracker/references/ranking-analysis-templates.md) for complete output templates for all 7 steps.
## Validation Checkpoints
### Input Validation
- [ ] Keywords list is complete with search volumes
- [ ] Target domain and tracking location are specified
- [ ] Competitor domains identified for comparison
- [ ] Historical baseline data available or initial tracking period set
### Output Validation
- [ ] Every metric cites its data source and collection date
- [ ] Ranking changes include context (vs. previous period)
- [ ] Significant movements have explanations or investigation notes
- [ ] Source of each data point clearly stated (~~SEO tool data, ~~search console data, user-provided, or estimated)
## Example
**User**: "Analyze my ranking changes for the past month"
**Output**:
```markdown
# Ranking Analysis: [current month, year]
## Summary
Your average position improved from 15.3 to 12.8 (-2.5 positions = better)
Keywords in top 10 increased from 12 to 17 (+5)
## Biggest Wins
| Keyword | Old | New | Change | Possible Cause |
|---------|-----|-----|--------|----------------|
| email marketing tips | 18 | 5 | +13 | Likely driven by content refresh |
| best crm software | 24 | 11 | +13 | Correlates with new backlinks acquired |
| sales automation | 15 | 7 | +8 | Correlates with schema markup addition |
## Needs Attention
| Keyword | Old | New | Change | Action |
|---------|-----|-----|--------|--------|
| marketing automation | 4 | 12 | -8 | Likely displaced by new HubSpot guide |
**Recommended**: Update your marketing automation guide with [current year] statistics and examples.
```
## Tips for Success
1. **Track consistently** - Same time, same device, same location
2. **Include enough keywords** - 50-200 for meaningful data
3. **Segment by intent** - Track brand, commercial, informational separately
4. **Monitor competitors** - Context makes your data meaningful
5. **Track SERP features** - Position 1 without snippet may lose to position 4 with snippet
6. **Include GEO metrics** - AI visibility increasingly important
## Rank Change Quick Reference
### Response Protocol
| Change | Timeframe | Action |
|--------|-----------|--------|
| Drop 1-3 positions | Wait 1-2 weeks | Monitor -- may be normal fluctuation |
| Drop 3-5 positions | Investigate within 1 week | Check for technical issues, competitor changes |
| Drop 5-10 positions | Investigate immediately | Full diagnostic: technical, content, links |
| Drop off page 1 | Emergency response | Comprehensive audit + recovery plan |
| Position gained | Document and learn | What worked? Can you replicate? |
> **Reference**: See [references/tracking-setup-guide.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/rank-tracker/references/tracking-setup-guide.md) for root cause taxonomy, CTR benchmarks by position, SERP feature CTR impact, algorithm update assessment, tracking configuration best practices, keyword selection and grouping strategies, and data interpretation guidelines.
### 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-<topic>.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
- [Tracking Setup Guide](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/rank-tracker/references/tracking-setup-guide.md) — Configuration best practices, device/location settings, and SERP feature tracking setup
## Next Best Skill
- **Primary**: [alert-manager](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/monitor/alert-manager/SKILL.md) — operationalize rank changes into thresholds and follow-ups.

308
.cursor/skills/rank-tracker/references/ranking-analysis-templates.md Normal file
View file

@ -0,0 +1,308 @@
# Ranking Analysis Output Templates
Detailed output templates for each step of the rank tracking workflow. Use these templates when setting up tracking, recording snapshots, and generating reports.
---
## 1. Rank Tracking Setup Template
```markdown
## Rank Tracking Setup
### Tracking Configuration
**Domain**: [domain]
**Tracking Location**: [country/city]
**Device**: [Mobile/Desktop/Both]
**Language**: [language]
**Update Frequency**: [Daily/Weekly/Monthly]
### Keywords to Track
| Keyword | Volume | Current Rank | Type | Priority |
|---------|--------|--------------|------|----------|
| [keyword 1] | [vol] | [rank] | Primary | High |
| [keyword 2] | [vol] | [rank] | Primary | High |
| [keyword 3] | [vol] | [rank] | Secondary | Medium |
| [keyword 4] | [vol] | [rank] | Long-tail | Medium |
| [keyword 5] | [vol] | [rank] | Brand | High |
### Competitor Tracking
Track these competitors for benchmark:
1. [Competitor 1] - [domain]
2. [Competitor 2] - [domain]
3. [Competitor 3] - [domain]
### Tracking Categories
| Category | Keywords | Description |
|----------|----------|-------------|
| Brand | [X] | Brand name variations |
| Product | [X] | Product-related terms |
| Informational | [X] | Educational queries |
| Commercial | [X] | Buying intent terms |
```
---
## 2. Current Ranking Snapshot Template
```markdown
## Current Ranking Snapshot
**Date**: [date]
**Domain**: [domain]
### Ranking Overview
| Position Range | Keyword Count | % of Total |
|----------------|---------------|------------|
| #1 | [X] | [X]% |
| #2-3 | [X] | [X]% |
| #4-10 | [X] | [X]% |
| #11-20 | [X] | [X]% |
| #21-50 | [X] | [X]% |
| #51-100 | [X] | [X]% |
| Not ranking | [X] | [X]% |
### Position Distribution
```
Position 1: [X] keywords
Position 2-3: [X] keywords
Position 4-10: [X] keywords
Position 11-20: [X] keywords
Position 21+: [X] keywords
```
### Detailed Rankings
| Keyword | Position | URL | SERP Features | Change |
|---------|----------|-----|---------------|--------|
| [kw 1] | 3 | [url] | Featured Snippet | +2 |
| [kw 2] | 7 | [url] | PAA | -1 |
| [kw 3] | 12 | [url] | None | New |
| [kw 4] | 1 | [url] | Featured Snippet | Stable |
```
---
## 3. Ranking Change Analysis Template
```markdown
## Ranking Change Analysis
**Period**: [start date] to [end date]
### Overall Movement
| Metric | Start | End | Change |
|--------|-------|-----|--------|
| Avg Position | [X] | [Y] | [+/-Z] |
| Keywords in Top 10 | [X] | [Y] | [+/-Z] |
| Keywords in Top 3 | [X] | [Y] | [+/-Z] |
| Keywords #1 | [X] | [Y] | [+/-Z] |
### Biggest Improvements
| Keyword | Old Rank | New Rank | Change | Est. Traffic Impact |
|---------|----------|----------|--------|---------------------|
| [kw 1] | 15 | 4 | +11 | +[X] visits/mo |
| [kw 2] | 25 | 9 | +16 | +[X] visits/mo |
**Possible causes**:
- [kw 1]: [hypothesis - e.g., content refresh may have improved relevance]
### Biggest Declines
| Keyword | Old Rank | New Rank | Change | Est. Traffic Impact |
|---------|----------|----------|--------|---------------------|
| [kw 1] | 3 | 12 | -9 | -[X] visits/mo |
**Likely factors**:
- [kw 1]: [hypothesis - e.g., competitor may have published updated guide]
> These are hypotheses based on available signals, not confirmed causes. Investigate each with the relevant skill to confirm.
**Recommended actions**:
- [kw 1]: [action to recover]
### Stable Keywords
[X] keywords remained within +/-3 positions (stable)
### New Rankings
| Keyword | Position | URL | Notes |
|---------|----------|-----|-------|
| [kw 1] | [pos] | [url] | [notes] |
### Lost Rankings
| Keyword | Last Position | URL | Action |
|---------|---------------|-----|--------|
| [kw 1] | [pos] | [url] | [investigate/refresh] |
```
---
## 4. SERP Feature Tracking Template
```markdown
## SERP Feature Tracking
### Feature Ownership
| Feature | Your Count | Competitor Avg | Opportunity |
|---------|------------|----------------|-------------|
| Featured Snippets | [X] | [Y] | [+/-Z] |
| People Also Ask | [X] | [Y] | [+/-Z] |
| Image Pack | [X] | [Y] | [+/-Z] |
| Video Results | [X] | [Y] | [+/-Z] |
| Local Pack | [X] | [Y] | [+/-Z] |
### Featured Snippet Status
| Keyword | You Own? | Current Owner | Winnable? |
|---------|----------|---------------|-----------|
| [kw 1] | Yes | You | Maintain |
| [kw 2] | No | [Competitor] | High |
### PAA Appearances
| Question | Your Answer? | Position | Action |
|----------|--------------|----------|--------|
| [Question 1] | Yes/No | [pos] | [action] |
```
---
## 5. GEO/AI Visibility Tracking Template
```markdown
## AI/GEO Visibility Tracking
### AI Overview Presence
| Keyword | AI Overview | You Cited? | Citation Position |
|---------|-------------|------------|-------------------|
| [kw 1] | Yes | Yes | 1st source |
| [kw 2] | Yes | Yes | 3rd source |
| [kw 3] | Yes | No | Not cited |
| [kw 4] | No | N/A | N/A |
### AI Citation Rate
| Metric | Value |
|--------|-------|
| Keywords with AI Overview | [X]/[Total] ([Y]%) |
| Your citations in AI Overview | [X]/[Y] ([Z]%) |
| Avg citation position | [X] |
### GEO Performance Trend
| Period | AI Overviews Tracked | Your Citations | Rate |
|--------|---------------------|----------------|------|
| Last week | [X] | [Y] | [Z]% |
| 2 weeks ago | [X] | [Y] | [Z]% |
| Month ago | [X] | [Y] | [Z]% |
### GEO Improvement Opportunities
| Keyword | Has AI Overview | You Cited? | Content Gap |
|---------|-----------------|------------|-------------|
| [kw 1] | Yes | No | Need clearer definition |
| [kw 2] | Yes | No | Missing quotable stats |
```
---
## 6. Competitor Ranking Comparison Template
```markdown
## Competitor Ranking Comparison
### Share of Voice
| Domain | Keywords Ranked | Avg Position | Visibility |
|--------|-----------------|--------------|------------|
| [Your site] | [X] | [Y] | [Z]% |
| [Competitor 1] | [X] | [Y] | [Z]% |
| [Competitor 2] | [X] | [Y] | [Z]% |
### Head-to-Head Comparison
**You vs [Competitor 1]**:
| Keyword | Your Rank | Their Rank | Winner |
|---------|-----------|------------|--------|
| [kw 1] | 3 | 7 | You |
| [kw 2] | 12 | 5 | Them |
**Summary**: You win [X]/[Y] keywords vs [Competitor 1]
### Competitor Movement Alerts
| Competitor | Keyword | Their Change | Threat Level |
|------------|---------|--------------|--------------|
| [Comp 1] | [kw] | +15 positions | High |
| [Comp 2] | [kw] | +8 positions | Medium |
```
---
## 7. Ranking Performance Report Template
```markdown
# Ranking Performance Report
**Domain**: [domain]
**Report Period**: [start] to [end]
**Generated**: [date]
## Executive Summary
**Overall Trend**: [Improving/Stable/Declining]
| Metric | Value | vs Last Period | Status |
|--------|-------|----------------|--------|
| Total keywords tracked | [X] | [+/-Y] | [status] |
| Keywords in top 10 | [X] | [+/-Y] | [status] |
| Keywords in top 3 | [X] | [+/-Y] | [status] |
| Average position | [X] | [+/-Y] | [status] |
| Estimated traffic | [X] | [+/-Y]% | [status] |
## Key Highlights
### Wins
- [Achievement 1]
- [Achievement 2]
### Concerns
- [Issue 1]
- [Issue 2]
### Opportunities
- [Opportunity 1]
## Detailed Analysis
[Include top performing keywords, keywords needing attention, SERP features, GEO visibility, competitive position]
## Recommendations
### Immediate Actions
1. [Action] for [keyword] - [expected impact]
### This Month
1. [Action]
### Next Quarter
1. [Strategic action]
## Next Report
Scheduled: [date]
Focus areas: [areas to monitor]
```

329
.cursor/skills/rank-tracker/references/tracking-setup-guide.md Normal file
View file

@ -0,0 +1,329 @@
# Rank Tracking Setup Guide
Comprehensive reference for configuring rank tracking systems. Covers tool configuration, keyword selection, grouping strategies, alert thresholds, reporting cadences, and data interpretation.
---
## 1. Tracking Tool Configuration
### Initial Setup Checklist
| Step | Action | Notes |
|------|--------|-------|
| 1 | Select tracking tool | ~~SEO tool with rank tracking capability |
| 2 | Add target domain | Primary domain + any subdomains |
| 3 | Set tracking location | Country, state/region, or city level |
| 4 | Configure device settings | Mobile, desktop, or both (recommended: both) |
| 5 | Set search engine | Google (primary), Bing (optional), local engines |
| 6 | Set language | Match target audience language |
| 7 | Configure update frequency | Daily for priority keywords, weekly for long-tail |
| 8 | Add competitor domains | 3-5 direct competitors |
| 9 | Import keyword list | From keyword research or existing tracking |
| 10 | Verify initial data pull | Confirm positions match manual spot checks |
### Location Configuration
Rank tracking results vary dramatically by location. Configure tracking to match your actual target market.
| Scenario | Location Setting | Example |
|----------|-----------------|---------|
| National business | Country level | United States |
| Regional business | State/region level | California, US |
| Local business | City level | San Francisco, CA, US |
| Multi-location | Separate project per location | NYC + LA + Chicago |
| International | Separate project per country | US + UK + Canada |
**Common mistake**: Tracking from a single location when your audience is distributed. If you serve multiple cities, track key terms in each city separately.
### Device Configuration
| Device | When to Track | Why |
|--------|--------------|-----|
| Desktop | Always | Baseline reference, still significant traffic |
| Mobile | Always | 60%+ of searches are mobile; rankings differ from desktop |
| Both separately | Recommended | Identify device-specific ranking issues |
| Tablet | Optional | Usually mirrors desktop closely |
### Update Frequency Recommendations
| Keyword Tier | Frequency | Rationale |
|-------------|-----------|-----------|
| Top 20 revenue keywords | Daily | Catch drops immediately |
| Brand keywords | Daily | Protect brand presence |
| Page 1 keywords (21-50) | 2-3x per week | Monitor competitive positions |
| Page 2 keywords (51-100) | Weekly | Track progress without excessive API usage |
| Long-tail / monitoring (100+) | Weekly | Cost-efficient tracking |
| New/experimental keywords | Daily for first 30 days, then adjust | Establish baseline quickly |
---
## 2. Keyword Selection for Tracking
### How Many Keywords to Track
| Site Size | Recommended Keywords | Breakdown |
|-----------|---------------------|-----------|
| Small (< 50 pages) | 50-100 | 10 brand + 20 primary + 20 secondary + rest long-tail |
| Medium (50-500 pages) | 100-500 | 20 brand + 50 primary + 100 secondary + rest long-tail |
| Large (500+ pages) | 500-2000+ | Scale proportionally; focus on revenue pages |
| Enterprise | 2000-10000+ | Comprehensive coverage with automated management |
### Keyword Selection Criteria
Select keywords for tracking based on these factors:
| Factor | Weight | Selection Rule |
|--------|--------|---------------|
| Revenue impact | High | Always track keywords that drive conversions |
| Search volume | Medium | Track keywords with meaningful volume for your niche |
| Current ranking | Medium | Track keywords where you rank (pages 1-3) plus targets |
| Competitive value | Medium | Track keywords your competitors target |
| Strategic importance | High | Track keywords aligned with business goals |
| Content investment | Medium | Track keywords for pages you invested in creating |
### Keyword Types to Include
| Type | % of Tracked Keywords | Examples |
|------|----------------------|---------|
| Brand keywords | 5-10% | "[brand name]", "[brand] + product", "[brand] reviews" |
| Primary commercial | 15-25% | "[product category]", "best [product]", "buy [product]" |
| Secondary commercial | 15-25% | "[product] for [use case]", "[product] vs [competitor]" |
| Informational | 20-30% | "how to [topic]", "what is [concept]", "[topic] guide" |
| Long-tail | 15-25% | Specific queries with 3+ words, lower volume |
| Local (if applicable) | 5-10% | "[service] near me", "[service] in [city]" |
### Keywords You Should NOT Track
| Skip These | Why |
|-----------|-----|
| Zero-volume keywords (unless strategic) | No measurable impact |
| Keywords you have no content for | Track only when you create targeting content |
| Extremely broad single-word terms | Too volatile, hard to rank, misleading data |
| Misspellings (unless significant volume) | Clutters reporting |
---
## 3. Keyword Grouping Strategies
Effective grouping transforms raw keyword data into strategic insights.
### Grouping Dimensions
| Dimension | Examples | Insight Gained |
|-----------|---------|----------------|
| **Topic cluster** | "email marketing", "email automation", "email templates" | Content hub performance |
| **Search intent** | Informational, commercial, transactional, navigational | Funnel stage performance |
| **Funnel stage** | Awareness, consideration, decision, retention | Buyer journey alignment |
| **Product/service** | Product A, Product B, Service C | Product line performance |
| **Content type** | Blog, landing page, product page, guide | Format effectiveness |
| **Priority tier** | Tier 1 (revenue), Tier 2 (growth), Tier 3 (monitor) | Resource allocation |
| **Page** | URL-level grouping | Page-specific performance |
| **Competitor overlap** | Keywords where you compete with specific rivals | Competitive intelligence |
### Recommended Group Hierarchy
```
Level 1: Business Unit / Product Line
└── Level 2: Topic Cluster / Category
└── Level 3: Search Intent
└── Level 4: Priority Tier
```
**Example:**
```
SaaS Product
└── Project Management
└── Commercial Intent
└── Tier 1: "project management software", "best PM tools"
└── Tier 2: "PM software for small teams", "agile PM tools"
└── Informational Intent
└── Tier 1: "what is project management", "PM methodologies"
└── Collaboration
└── Commercial Intent
└── Tier 1: "team collaboration software", "best collab tools"
```
### Group Naming Conventions
Use consistent, descriptive names:
| Pattern | Example | Benefit |
|---------|---------|---------|
| `[Category] - [Intent]` | "Email Marketing - Commercial" | Clear context |
| `[Product] / [Feature]` | "CRM / Lead Scoring" | Product-line clarity |
| `T1: [Topic]` | "T1: Core Product Terms" | Priority at a glance |
---
## 4. Alert Threshold Configuration
### Setting Baseline Thresholds
Before setting alerts, establish a baseline by tracking for 2-4 weeks without alerts to understand normal fluctuation ranges.
| Metric | Baseline Period | Normal Fluctuation | Alert When |
|--------|----------------|-------------------|------------|
| Individual keyword position | 2-4 weeks | +/- 2-3 positions | Exceeds normal range |
| Average position (all keywords) | 4 weeks | +/- 1-2 positions | Exceeds normal range |
| Keywords in top 10 | 4 weeks | +/- 5% | Drops >10% |
| Keywords in top 3 | 4 weeks | +/- 3% | Drops >5% |
### Alert Configuration by Keyword Tier
| Keyword Tier | Drop Alert | Gain Alert | Competitor Alert |
|-------------|-----------|-----------|-----------------|
| Tier 1 (revenue) | Drop >= 3 positions | Gain >= 3 positions | Competitor enters top 5 |
| Tier 2 (growth) | Drop >= 5 positions | Enters top 10 | Competitor overtakes you |
| Tier 3 (monitor) | Drop >= 10 positions | Enters top 20 | None |
| Brand | Any drop from #1 | N/A | Competitor ranks for your brand |
### Alert Delivery Preferences
| Alert Type | Channel | Frequency |
|-----------|---------|-----------|
| Critical drops (Tier 1) | Email + Slack | Immediate |
| Significant changes | Email | Daily digest |
| Weekly summary | Email | Every Monday |
| Monthly report | Email + dashboard | 1st of month |
---
## 5. Reporting Cadences
### Recommended Report Schedule
| Report Type | Audience | Frequency | Key Metrics |
|------------|----------|-----------|-------------|
| Quick pulse | SEO team | Daily | Major movements, alerts fired |
| Weekly summary | Marketing team | Weekly | Position changes, trends, actions taken |
| Monthly report | Stakeholders | Monthly | Full performance analysis, MoM comparisons |
| Quarterly review | Leadership | Quarterly | Strategic trends, ROI, competitive position |
| Annual review | Executive | Annually | YoY growth, strategic recommendations |
### Report Content by Cadence
**Daily Pulse (1-2 minutes to review):**
- Keywords with biggest position changes
- Alerts triggered
- Competitor movements
**Weekly Summary (5-10 minutes to review):**
- Position distribution changes
- Top 5 improvements and declines
- SERP feature wins/losses
- AI citation changes
- Week-over-week trend
**Monthly Report (15-30 minutes to review):**
- Full position distribution analysis
- Month-over-month trends
- Competitor share of voice
- SERP feature ownership
- GEO visibility trends
- Content performance by keyword group
- Recommendations for next month
**Quarterly Review (30-60 minutes to review):**
- Quarter-over-quarter trends
- Progress against annual goals
- Competitive landscape shifts
- Strategic keyword opportunities
- Budget and resource recommendations
---
## 6. Data Interpretation Guidelines
### Understanding Rank Fluctuations
| Pattern | Meaning | Action |
|---------|---------|--------|
| Daily +/- 1-2 positions | Normal fluctuation | Ignore; track weekly trend |
| Sudden drop 5+ positions, recovers in 2-3 days | Google testing / data center variation | Monitor, no action needed |
| Steady decline over 2+ weeks | Real ranking loss | Investigate cause (see Root Cause Taxonomy) |
| Sudden drop affecting many keywords | Algorithm update or technical issue | Check Search Status Dashboard + technical health |
| One keyword drops, others stable | Page-specific or competitor-specific issue | Analyze that specific SERP |
| All keywords for one URL drop | Page-level issue (noindex, 404, slow) | Check page technical health |
| Gradual improvement over weeks | SEO efforts working | Document what worked, continue strategy |
### Position vs. Traffic Relationship
Position changes do not translate linearly to traffic changes.
| Position Change | Estimated Traffic Impact |
|----------------|------------------------|
| #1 to #2 | -50% to -60% click loss |
| #2 to #3 | -25% to -30% click loss |
| #3 to #5 | -30% to -40% click loss |
| #5 to #10 | -50% to -60% click loss |
| #10 to #11 | -60% to -80% click loss (page 2 cliff) |
| #11 to #20 | Minimal additional loss (already low) |
**Key insight**: Moving from position #10 to #11 (page 1 to page 2) has a far greater impact than moving from #20 to #30. Prioritize keeping keywords on page 1.
### Interpreting Visibility Score
Visibility score combines position and search volume into a single metric.
| Visibility Change | Interpretation |
|-------------------|---------------|
| Increasing visibility, stable positions | Seasonal search volume increase |
| Decreasing visibility, stable positions | Seasonal search volume decrease |
| Increasing visibility, improving positions | SEO strategy is working |
| Decreasing visibility, declining positions | Ranking loss causing traffic decline |
| Stable visibility, mixed position changes | Gains offsetting losses |
### Comparing Against Competitors
| Competitive Signal | Meaning | Response |
|-------------------|---------|----------|
| Competitor visibility rising, yours stable | They are gaining, you may lose ground | Analyze their strategy, accelerate efforts |
| Your visibility rising faster than competitors | You are winning share of voice | Continue strategy, identify what is working |
| All competitors dropping simultaneously | Algorithm update affecting the niche | Focus on quality, wait for dust to settle |
| One competitor surging | They made a significant change | Analyze what they did (content? links? technical?) |
### Data Quality Checks
Always verify your tracking data quality.
| Check | How | Frequency |
|-------|-----|-----------|
| Spot-check positions manually | Incognito search for 5-10 keywords | Weekly |
| Compare with Search Console | Match tracked positions with GSC average position | Monthly |
| Check for tracking errors | Look for keywords showing "not found" or position 0 | Weekly |
| Verify competitor data | Spot-check competitor rankings manually | Monthly |
| Confirm location accuracy | Search from target location (VPN if needed) | Quarterly |
---
## 7. Common Pitfalls and How to Avoid Them
| Pitfall | Problem | Solution |
|---------|---------|----------|
| Tracking too many keywords | Dilutes focus, increases cost | Focus on keywords with business impact |
| Checking rankings too frequently | Obsessing over daily noise | Focus on weekly and monthly trends |
| Not segmenting data | Averages hide important patterns | Group by intent, topic, priority |
| Ignoring SERP features | Position alone does not tell the whole story | Track featured snippets, AI Overviews, PAA |
| Not tracking competitors | Your data lacks context | Always track 3-5 competitors |
| Single location tracking | Misses local variations | Track each target market separately |
| Forgetting mobile | Mobile and desktop rankings differ | Always track both devices |
| Not documenting changes | Cannot correlate changes to actions | Log all content updates, technical changes, link building |
---
## 8. Migration and Tool Switching
If you need to switch rank tracking tools, follow this process to preserve data continuity.
| Step | Action |
|------|--------|
| 1 | Export all historical data from current tool |
| 2 | Run both tools in parallel for 2-4 weeks |
| 3 | Compare data between tools to understand differences |
| 4 | Document any systematic position differences |
| 5 | Import historical data into new tool if supported |
| 6 | Reconfigure all alerts and reports in new tool |
| 7 | Decommission old tool after confidence in new data |
**Important**: Different tools may report slightly different positions due to data center sampling, timing, and methodology. A 1-2 position variance between tools is normal.

402
.cursor/skills/schema-markup-generator/SKILL.md Normal file
View file

@ -0,0 +1,402 @@
---
name: schema-markup-generator
description: 'Generate JSON-LD structured data for FAQ, HowTo, Article, Product, LocalBusiness rich results. Schema标记/结构化数据'
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 JSON-LD structured data, Schema.org markup, or rich snippet markup for a page."
argument-hint: "<page URL or content type>"
allowed-tools: WebFetch
metadata:
author: aaron-he-zhu
version: "6.0.0"
geo-relevance: "medium"
tags:
- seo
- structured-data
- json-ld
- rich-results
- faq-schema
- howto-schema
- product-schema
- article-schema
- schema-org
- 结构化数据
- 構造化データ
- 스키마마크업
- datos-estructurados
triggers:
# EN-formal
- "add schema markup"
- "generate structured data"
- "JSON-LD"
- "rich snippets"
- "FAQ schema"
- "schema.org"
- "structured data markup"
# EN-casual
- "add FAQ rich results"
- "I want star ratings in Google"
- "product markup"
- "recipe schema"
- "add structured data to my page"
# EN-question
- "how to add schema markup"
- "how to get rich snippets"
# ZH-pro
- "结构化数据"
- "Schema标记"
- "JSON-LD生成"
- "富摘要"
# ZH-casual
- "添加结构化数据"
- "要星级评分"
- "搜索结果要好看"
# JA
- "構造化データ"
- "スキーママークアップ"
- "リッチリザルト"
# KO
- "스키마 마크업"
- "구조화 데이터"
# ES
- "datos estructurados"
- "marcado schema"
# PT
- "dados estruturados"
# Misspellings
- "shema markup"
- "structred data"
---
# Schema Markup Generator
> **[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 Schema.org structured data markup in JSON-LD format to help search engines understand your content and enable rich results in SERPs.
**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.
- Adding FAQ schema for expanded SERP presence
- Creating How-To schema for step-by-step content
- Adding Product schema for e-commerce pages
- Implementing Article schema for blog posts
- Adding Local Business schema for location pages
- Creating Review/Rating schema
- Implementing Organization schema for brand presence
- Any page where rich results would improve visibility
## What This Skill Does
1. **Schema Type Selection**: Recommends appropriate schema types
2. **JSON-LD Generation**: Creates valid structured data markup
3. **Property Mapping**: Maps your content to schema properties
4. **Validation Guidance**: Ensures schema meets requirements
5. **Nested Schema**: Handles complex, multi-type schemas
6. **Rich Result Eligibility**: Identifies which rich results you can target
## 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 Schema for Content
```
Generate schema markup for this [content type]: [content/URL]
```
```
Create FAQ schema for these questions and answers: [Q&A list]
```
### Specific Schema Types
```
Create Product schema for [product name] with [details]
```
```
Generate LocalBusiness schema for [business name and details]
```
### Audit Existing Schema
```
Review and improve this schema markup: [existing schema]
```
## 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 ~~web crawler connected:**
Automatically crawl and extract page content (visible text, headings, lists, tables), existing schema markup, page metadata, and structured content elements that map to schema properties.
**With manual data only:**
Ask the user to provide:
1. Page URL or full HTML content
2. Page type (article, product, FAQ, how-to, local business, etc.)
3. Specific data needed for schema (prices, dates, author info, Q&A pairs, etc.)
4. Current schema markup (if optimizing existing)
Proceed with the full workflow using provided data. Note in the output which data is from automated extraction vs. user-provided data.
## Instructions
When a user requests schema markup:
1. **Identify Content Type and Rich Result Opportunity**
Reference the [CORE-EEAT Benchmark](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/core-eeat-benchmark.md) item **O05 (Schema Markup)** for content-type to schema mapping:
```markdown
### CORE-EEAT Schema Mapping (O05)
| Content Type | Required Schema | Conditional Schema |
|-------------|----------------|--------------------|
| Blog (guides) | Article, Breadcrumb | FAQ, HowTo |
| Blog (tools) | Article, Breadcrumb | FAQ, Review |
| Blog (insights) | Article, Breadcrumb | FAQ |
| Alternative | Comparison*, Breadcrumb, FAQ | AggregateRating |
| Best-of | ItemList, Breadcrumb, FAQ | AggregateRating per tool |
| Use-case | WebPage, Breadcrumb, FAQ | — |
| FAQ | FAQPage, Breadcrumb | — |
| Landing | SoftwareApplication, Breadcrumb, FAQ | WebPage |
| Testimonial | Review, Breadcrumb | FAQ, Person |
*Use the mapping above to ensure schema type matches content type (CORE-EEAT O05: Pass criteria).*
```
```markdown
### Schema Analysis
**Content Type**: [blog/product/FAQ/how-to/local business/etc.]
**Page URL**: [URL]
**Eligible Rich Results**:
| Rich Result Type | Eligibility | Impact |
|------------------|-------------|--------|
| FAQ | ✅/❌ | High - Expands SERP presence |
| How-To | ✅/❌ | Medium - Shows steps in SERP |
| Product | ✅/❌ | High - Shows price, availability |
| Review | ✅/❌ | High - Shows star ratings |
| Article | ✅/❌ | Medium - Shows publish date, author |
| Breadcrumb | ✅/❌ | Medium - Shows navigation path |
| Video | ✅/❌ | High - Shows video thumbnail |
**Recommended Schema Types**:
1. [Primary schema type] - [reason]
2. [Secondary schema type] - [reason]
```
2. **Generate Schema Markup**
Based on the identified content type, generate the appropriate JSON-LD schema. Supported types: FAQPage, HowTo, Article/BlogPosting/NewsArticle, Product, LocalBusiness, Organization, BreadcrumbList, Event, Recipe, and combined multi-type schemas.
> **Reference**: See [references/schema-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/schema-markup-generator/references/schema-templates.md) for complete, copy-ready JSON-LD templates for all schema types with required and optional properties.
For each schema generated, include:
- All required properties for the chosen type
- Rich result preview showing expected SERP appearance
- Notes on which properties are required vs. optional
When combining multiple schema types on one page, wrap them in a JSON array inside a single `<script type="application/ld+json">` tag.
3. **Provide Implementation and Validation**
```markdown
## Implementation Guide
### Adding Schema to Your Page
**Option 1: In HTML <head>**
```html
<head>
<script type="application/ld+json">
[Your JSON-LD schema here]
</script>
</head>
```
**Option 2: Before closing </body>**
```html
<script type="application/ld+json">
[Your JSON-LD schema here]
</script>
</body>
```
### Validation Steps
1. **~~schema validator**
- Test your live URL or paste code
- Check for errors and warnings
2. **Schema.org Validator**
- URL: https://validator.schema.org/
- Validates against Schema.org spec
3. **~~search console**
- Monitor rich results in ~~search console
- Check Enhancements reports for issues
### Validation Checklist
- [ ] JSON syntax is valid (no trailing commas)
- [ ] All required properties present
- [ ] URLs are absolute, not relative
- [ ] Dates are in ISO 8601 format
- [ ] Content matches visible page content
- [ ] No policy violations
```
## Validation Checkpoints
### Input Validation
- [ ] Page URL or content provided
- [ ] Schema type appropriate for content (Article for blog, Product for e-commerce, etc.)
- [ ] All required data available (author, dates, prices, etc. depending on schema type)
- [ ] Content eligibility for rich results confirmed
### Output Validation
- [ ] JSON syntax validates (no trailing commas, proper quotes)
- [ ] All required properties present for chosen schema type
- [ ] URLs are absolute, not relative
- [ ] Dates in ISO 8601 format (YYYY-MM-DDTHH:MM:SS+00:00)
- [ ] Schema content matches visible page content exactly
- [ ] Passes ~~schema validator with no errors
- [ ] Source of each data point clearly stated (~~web crawler extraction, user-provided, or manual entry)
## Example
**User**: "Generate FAQ schema for a page about SEO with 3 questions"
**Output**:
```markdown
## FAQ Schema for SEO Page
### Schema Markup
```json
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "What is SEO?",
"acceptedAnswer": {
"@type": "Answer",
"text": "SEO (Search Engine Optimization) is the practice of optimizing websites and content to rank higher in search engine results pages (SERPs). It involves technical optimizations, content creation, and link building to increase organic visibility and drive qualified traffic to your website."
}
},
{
"@type": "Question",
"name": "How long does SEO take to work?",
"acceptedAnswer": {
"@type": "Answer",
"text": "SEO typically takes 3-6 months to show significant results, though this varies based on competition, domain authority, and effort invested. New websites may take 6-12 months, while established sites with existing authority can see improvements in 1-3 months for less competitive keywords."
}
},
{
"@type": "Question",
"name": "Is SEO better than paid advertising?",
"acceptedAnswer": {
"@type": "Answer",
"text": "SEO and paid advertising serve different purposes. SEO provides sustainable, long-term traffic without per-click costs but takes time to build. Paid advertising delivers immediate results but stops when you stop paying. Most successful businesses use both: paid ads for immediate leads and SEO for long-term growth."
}
}
]
}
```
_Implementation: Wrap the above JSON-LD in `<script type="application/ld+json">...</script>` and place in `<head>` or before `</body>`. Test with ~~schema validator._
### SERP Preview
```
SEO Guide: Complete Beginner's Tutorial
yoursite.com/seo-guide/
Learn SEO from scratch with our comprehensive guide...
▼ What is SEO?
SEO (Search Engine Optimization) is the practice of optimizing...
▼ How long does SEO take to work?
SEO typically takes 3-6 months to show significant results...
▼ Is SEO better than paid advertising?
SEO and paid advertising serve different purposes...
```
```
## Schema Type Quick Reference
| Content Type | Schema Type | Key Properties |
|--------------|-------------|----------------|
| Blog Post | BlogPosting/Article | headline, datePublished, author |
| Product | Product | name, price, availability |
| FAQ | FAQPage | Question, Answer |
| How-To | HowTo | step, totalTime |
| Local Business | LocalBusiness | address, geo, openingHours |
| Recipe | Recipe | ingredients, cookTime |
| Event | Event | startDate, location |
| Video | VideoObject | uploadDate, duration |
| Course | Course | provider, name |
| Review | Review | itemReviewed, ratingValue |
## Tips for Success
1. **Match visible content** - Schema must reflect what users see
2. **Don't spam** - Only add schema for relevant content
3. **Keep updated** - Update dates and prices when they change
4. **Test thoroughly** - Validate before deploying
5. **Monitor Search Console** - Watch for errors and warnings
## Schema Type Decision Tree
> **Reference**: See [references/schema-decision-tree.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/schema-markup-generator/references/schema-decision-tree.md) for the full decision tree (content-to-schema mapping), industry-specific recommendations, implementation priority tiers (P0-P4), and validation quick reference.
### 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-<topic>.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
- [Schema Templates](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/schema-markup-generator/references/schema-templates.md) - Copy-ready JSON-LD templates for all schema types
- [Validation Guide](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/schema-markup-generator/references/validation-guide.md) - Common errors, required properties, testing workflow
## Next Best Skill
- **Primary**: [technical-seo-checker](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/SKILL.md) — verify implementation quality and deployment readiness.

65
.cursor/skills/schema-markup-generator/references/schema-decision-tree.md Normal file
View file

@ -0,0 +1,65 @@
# Schema Type Decision Tree
Guidelines for selecting the right schema types based on content, industry, and implementation priority.
---
## When to Use Which Schema
| Your Content | Primary Schema | Add If Applicable | Rich Result Eligibility |
|-------------|---------------|-------------------|----------------------|
| Blog post / article | Article | FAQ, HowTo, Speakable | Article carousel, FAQ rich result |
| Product page | Product | Review, Offer, AggregateRating | Product snippet with price/rating |
| Service page | Service | FAQ, LocalBusiness | Service snippet |
| How-to guide | HowTo | Article, FAQ | How-to rich result with steps |
| FAQ page | FAQPage | Article | FAQ accordion in SERP |
| Recipe | Recipe | Video, AggregateRating | Recipe carousel |
| Event | Event | Offer, Organization | Event snippet with date/location |
| Video | VideoObject | Article | Video carousel, key moments |
| Local business | LocalBusiness | Review, OpeningHoursSpecification | Local pack, knowledge panel |
| Person/author | Person | Organization | Knowledge panel |
| Organization | Organization | ContactPoint, Logo | Knowledge panel |
| Course | Course | Organization | Course rich result |
| Job posting | JobPosting | Organization | Google for Jobs listing |
| Breadcrumb | BreadcrumbList | (Always add alongside other schema) | Breadcrumb trail in SERP |
| Software/App | SoftwareApplication | Review, Offer | App snippet |
---
## Industry-Specific Schema Recommendations
| Industry | Essential Schema | High-Value Additions |
|----------|-----------------|---------------------|
| E-commerce | Product, BreadcrumbList, Organization | AggregateRating, FAQ, Review |
| SaaS | SoftwareApplication, FAQPage, Organization | HowTo, VideoObject, Review |
| Local Services | LocalBusiness, Service | FAQ, Review, Event |
| Publishing/Media | Article, Person, Organization | FAQ, Speakable, VideoObject |
| Education | Course, Organization | FAQ, HowTo, Event |
| Healthcare | MedicalWebPage, Organization | FAQ, Physician, MedicalClinic |
| Real Estate | RealEstateListing, Organization | LocalBusiness, FAQ |
| Restaurants | Restaurant, Menu | Review, Event, FAQ |
---
## Schema Implementation Priority
| Priority | Schema Types | Why |
|----------|-------------|-----|
| P0 -- Always | Organization, BreadcrumbList, WebSite (SearchAction) | Foundation for all sites |
| P1 -- Content | Article, FAQPage, HowTo | Direct rich result eligibility |
| P2 -- Commercial | Product, Review, AggregateRating, Offer | Revenue-impacting rich results |
| P3 -- Authority | Person, SameAs, Speakable | E-E-A-T signals, AI citation |
| P4 -- Specialized | Industry-specific types | Niche rich results |
---
## Schema Validation Quick Reference
| Issue | Impact | Fix |
|-------|--------|-----|
| Missing required property | Schema ignored by Google | Add all required fields (check schema.org) |
| Invalid date format | Warning, may lose rich result | Use ISO 8601: "2026-02-11" |
| Incorrect @type | Schema misinterpreted | Match @type exactly to schema.org |
| Self-referencing sameAs | Warning | sameAs should link to EXTERNAL profiles |
| Missing image for Article | Loses article rich result | Add image property with valid URL |
| Review without itemReviewed | Review not connected | Nest review inside Product/Service/etc. |

631
.cursor/skills/schema-markup-generator/references/schema-templates.md Normal file
View file

@ -0,0 +1,631 @@
# Schema.org JSON-LD Templates
Complete, copy-ready structured data templates for all major schema types. Customize the bracketed values to match your content.
## FAQPage Schema
For pages with frequently asked questions. Minimum 2 Q&A pairs required.
```json
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "[Question text - exactly as shown on page]",
"acceptedAnswer": {
"@type": "Answer",
"text": "[Complete answer text - must match visible content]"
}
},
{
"@type": "Question",
"name": "[Question 2]",
"acceptedAnswer": {
"@type": "Answer",
"text": "[Answer 2]"
}
},
{
"@type": "Question",
"name": "[Question 3]",
"acceptedAnswer": {
"@type": "Answer",
"text": "[Answer 3]"
}
}
]
}
```
**Requirements**: Questions must be complete questions, answers must be comprehensive, content must match visible page content.
---
## HowTo Schema
For step-by-step instructional content.
```json
{
"@context": "https://schema.org",
"@type": "HowTo",
"name": "[How-to title - what will users learn]",
"description": "[Brief description of what this tutorial teaches]",
"image": {
"@type": "ImageObject",
"url": "[Main image URL]",
"height": "[height in pixels]",
"width": "[width in pixels]"
},
"totalTime": "PT[X]H[Y]M",
"estimatedCost": {
"@type": "MonetaryAmount",
"currency": "USD",
"value": "[estimated cost or 0]"
},
"supply": [
{
"@type": "HowToSupply",
"name": "[Supply item 1]"
},
{
"@type": "HowToSupply",
"name": "[Supply item 2]"
}
],
"tool": [
{
"@type": "HowToTool",
"name": "[Tool 1]"
},
{
"@type": "HowToTool",
"name": "[Tool 2]"
}
],
"step": [
{
"@type": "HowToStep",
"position": 1,
"name": "[Step 1 title]",
"text": "[Step 1 detailed instructions]",
"url": "[Page URL]#step1",
"image": "[Step 1 image URL - optional]"
},
{
"@type": "HowToStep",
"position": 2,
"name": "[Step 2 title]",
"text": "[Step 2 detailed instructions]",
"url": "[Page URL]#step2",
"image": "[Step 2 image URL - optional]"
},
{
"@type": "HowToStep",
"position": 3,
"name": "[Step 3 title]",
"text": "[Step 3 detailed instructions]",
"url": "[Page URL]#step3",
"image": "[Step 3 image URL - optional]"
}
]
}
```
**Time format**: PT[X]H[Y]M where X = hours, Y = minutes. Example: PT1H30M = 1 hour 30 minutes.
---
## Article / BlogPosting / NewsArticle Schema
For blog posts, articles, and news content.
```json
{
"@context": "https://schema.org",
"@type": "BlogPosting",
"headline": "[Article title - max 110 characters for best display]",
"description": "[Article summary or excerpt]",
"image": [
"[Featured image URL - 1200px wide recommended]",
"[Alternative image URL - 4:3 ratio]",
"[Alternative image URL - 16:9 ratio]"
],
"datePublished": "[ISO 8601 date: 2024-01-15T08:00:00+00:00]",
"dateModified": "[ISO 8601 date - same as published if never modified]",
"author": {
"@type": "Person",
"name": "[Author Full Name]",
"url": "[Author profile URL]",
"jobTitle": "[Author job title - optional]"
},
"publisher": {
"@type": "Organization",
"name": "[Publisher/Company Name]",
"logo": {
"@type": "ImageObject",
"url": "[Publisher logo URL - max 600px wide, 60px high]",
"width": "[width]",
"height": "[height]"
}
},
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "[Canonical URL of this article]"
},
"articleBody": "[Full article text - optional but recommended]",
"wordCount": "[word count - optional]"
}
```
**Type variants**: Use `Article` for general articles, `BlogPosting` for blog posts, `NewsArticle` for news content, `TechArticle` for technical documentation.
---
## Product Schema
For e-commerce product pages.
```json
{
"@context": "https://schema.org",
"@type": "Product",
"name": "[Product Name]",
"image": [
"[Product image URL 1]",
"[Product image URL 2]",
"[Product image URL 3]"
],
"description": "[Product description]",
"sku": "[SKU code]",
"mpn": "[Manufacturer Part Number - optional]",
"brand": {
"@type": "Brand",
"name": "[Brand Name]"
},
"offers": {
"@type": "Offer",
"url": "[Product page URL]",
"priceCurrency": "USD",
"price": "[Price as number: 29.99]",
"priceValidUntil": "[Date price is valid until: 2024-12-31]",
"availability": "https://schema.org/InStock",
"seller": {
"@type": "Organization",
"name": "[Seller/Store Name]"
},
"shippingDetails": {
"@type": "OfferShippingDetails",
"shippingRate": {
"@type": "MonetaryAmount",
"value": "[shipping cost]",
"currency": "USD"
},
"shippingDestination": {
"@type": "DefinedRegion",
"addressCountry": "US"
}
}
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "[4.5]",
"reviewCount": "[89]",
"bestRating": "5",
"worstRating": "1"
},
"review": [
{
"@type": "Review",
"reviewRating": {
"@type": "Rating",
"ratingValue": "[5]",
"bestRating": "5"
},
"author": {
"@type": "Person",
"name": "[Reviewer Name]"
},
"reviewBody": "[Review text]",
"datePublished": "[Review date: 2024-01-15]"
}
]
}
```
**Availability options**: `InStock`, `OutOfStock`, `PreOrder`, `Discontinued`, `LimitedAvailability`, `OnlineOnly`, `InStoreOnly`, `SoldOut`
---
## LocalBusiness Schema
For local business pages with physical locations.
```json
{
"@context": "https://schema.org",
"@type": "LocalBusiness",
"name": "[Business Name]",
"image": "[Business image or logo URL]",
"@id": "[Business page URL]",
"url": "[Website URL]",
"telephone": "[Phone number: +1-555-555-5555]",
"priceRange": "[$$$ or price range like $10-$50]",
"address": {
"@type": "PostalAddress",
"streetAddress": "[Street address]",
"addressLocality": "[City]",
"addressRegion": "[State/Province]",
"postalCode": "[ZIP/Postal code]",
"addressCountry": "US"
},
"geo": {
"@type": "GeoCoordinates",
"latitude": "[latitude as number: 40.7128]",
"longitude": "[longitude as number: -74.0060]"
},
"openingHoursSpecification": [
{
"@type": "OpeningHoursSpecification",
"dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
"opens": "09:00",
"closes": "17:00"
},
{
"@type": "OpeningHoursSpecification",
"dayOfWeek": "Saturday",
"opens": "10:00",
"closes": "15:00"
}
],
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "[4.5]",
"reviewCount": "[123]"
},
"servesCuisine": "[Cuisine type - for restaurants only]"
}
```
**Type variants**: Use more specific types when applicable: `Restaurant`, `Store`, `AutoRepair`, `HealthAndBeautyBusiness`, `LegalService`, etc.
---
## Organization Schema
For brand/company homepage.
```json
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "[Organization Name]",
"url": "[Website URL]",
"logo": "[Logo URL - recommended 112x112px or larger]",
"description": "[Company description]",
"sameAs": [
"[Facebook URL]",
"[Twitter URL]",
"[LinkedIn URL]",
"[Instagram URL]",
"[YouTube URL]"
],
"contactPoint": {
"@type": "ContactPoint",
"telephone": "[Phone number]",
"contactType": "customer service",
"email": "[Email address]",
"availableLanguage": ["English", "Spanish"],
"areaServed": "US"
},
"founder": {
"@type": "Person",
"name": "[Founder name - optional]"
},
"foundingDate": "[YYYY-MM-DD - optional]",
"address": {
"@type": "PostalAddress",
"streetAddress": "[Street address]",
"addressLocality": "[City]",
"addressRegion": "[State]",
"postalCode": "[ZIP]",
"addressCountry": "US"
}
}
```
---
## BreadcrumbList Schema
For navigation breadcrumbs.
```json
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "[Homepage URL]"
},
{
"@type": "ListItem",
"position": 2,
"name": "[Category Name]",
"item": "[Category URL]"
},
{
"@type": "ListItem",
"position": 3,
"name": "[Subcategory Name]",
"item": "[Subcategory URL]"
},
{
"@type": "ListItem",
"position": 4,
"name": "[Current Page Name]",
"item": "[Current Page URL]"
}
]
}
```
**Important**: Position numbers must be sequential starting from 1. Last item should be the current page.
---
## VideoObject Schema
For video content.
```json
{
"@context": "https://schema.org",
"@type": "VideoObject",
"name": "[Video title]",
"description": "[Video description]",
"thumbnailUrl": "[Video thumbnail URL - minimum 160x90px]",
"uploadDate": "[ISO 8601 date: 2024-01-15T08:00:00+00:00]",
"duration": "PT[X]M[Y]S",
"contentUrl": "[Video file URL]",
"embedUrl": "[Video embed URL]",
"interactionStatistic": {
"@type": "InteractionCounter",
"interactionType": { "@type": "WatchAction" },
"userInteractionCount": "[view count]"
}
}
```
**Duration format**: PT[X]M[Y]S where X = minutes, Y = seconds. Example: PT5M30S = 5 minutes 30 seconds.
---
## Event Schema
For events, conferences, concerts, etc.
```json
{
"@context": "https://schema.org",
"@type": "Event",
"name": "[Event Name]",
"description": "[Event description]",
"image": "[Event image URL]",
"startDate": "[ISO 8601 date: 2024-06-15T19:00:00-05:00]",
"endDate": "[ISO 8601 date: 2024-06-15T22:00:00-05:00]",
"eventStatus": "https://schema.org/EventScheduled",
"eventAttendanceMode": "https://schema.org/OfflineEventAttendanceMode",
"location": {
"@type": "Place",
"name": "[Venue Name]",
"address": {
"@type": "PostalAddress",
"streetAddress": "[Street address]",
"addressLocality": "[City]",
"addressRegion": "[State]",
"postalCode": "[ZIP]",
"addressCountry": "US"
}
},
"offers": {
"@type": "Offer",
"url": "[Ticket purchase URL]",
"price": "[ticket price]",
"priceCurrency": "USD",
"availability": "https://schema.org/InStock",
"validFrom": "[Sale start date]"
},
"organizer": {
"@type": "Organization",
"name": "[Organizer name]",
"url": "[Organizer website]"
}
}
```
**Event status options**: `EventScheduled`, `EventCancelled`, `EventPostponed`, `EventRescheduled`, `EventMovedOnline`
**Attendance mode**: `OfflineEventAttendanceMode`, `OnlineEventAttendanceMode`, `MixedEventAttendanceMode`
---
## Course Schema
For online courses and educational content.
```json
{
"@context": "https://schema.org",
"@type": "Course",
"name": "[Course Name]",
"description": "[Course description]",
"provider": {
"@type": "Organization",
"name": "[Provider name]",
"sameAs": "[Provider URL]"
},
"offers": {
"@type": "Offer",
"category": "Paid",
"price": "[price]",
"priceCurrency": "USD"
},
"hasCourseInstance": {
"@type": "CourseInstance",
"courseMode": "online",
"courseWorkload": "PT[X]H",
"instructor": {
"@type": "Person",
"name": "[Instructor name]"
}
}
}
```
---
## Recipe Schema
For cooking recipes.
```json
{
"@context": "https://schema.org",
"@type": "Recipe",
"name": "[Recipe name]",
"image": "[Recipe image URL]",
"author": {
"@type": "Person",
"name": "[Author name]"
},
"datePublished": "[ISO 8601 date]",
"description": "[Recipe description]",
"prepTime": "PT[X]M",
"cookTime": "PT[X]M",
"totalTime": "PT[X]M",
"recipeYield": "[Servings: e.g., '4 servings']",
"recipeCategory": "[Category: e.g., 'Dinner']",
"recipeCuisine": "[Cuisine: e.g., 'Italian']",
"keywords": "[comma, separated, keywords]",
"nutrition": {
"@type": "NutritionInformation",
"calories": "[calories per serving]"
},
"recipeIngredient": [
"[Ingredient 1 with quantity]",
"[Ingredient 2 with quantity]",
"[Ingredient 3 with quantity]"
],
"recipeInstructions": [
{
"@type": "HowToStep",
"text": "[Step 1 instructions]"
},
{
"@type": "HowToStep",
"text": "[Step 2 instructions]"
}
],
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "[4.5]",
"reviewCount": "[number of reviews]"
}
}
```
---
## SoftwareApplication Schema
For software, apps, and tools.
```json
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "[Software name]",
"operatingSystem": "[Windows, macOS, iOS, Android, Web]",
"applicationCategory": "BusinessApplication",
"offers": {
"@type": "Offer",
"price": "[price or 0 for free]",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "[4.5]",
"reviewCount": "[number of reviews]"
},
"screenshot": "[Screenshot URL - optional]",
"softwareVersion": "[version number]",
"fileSize": "[file size with units: e.g., '50MB']",
"datePublished": "[Release date]",
"downloadUrl": "[Download URL - optional]"
}
```
---
## Multiple Schema Types (Combined Array)
To include multiple schema types on one page, wrap them in an array:
```html
<script type="application/ld+json">
[
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "[Article title]",
"author": {
"@type": "Person",
"name": "[Author]"
}
},
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "[Question]",
"acceptedAnswer": {
"@type": "Answer",
"text": "[Answer]"
}
}
]
},
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "[URL]"
}
]
}
]
</script>
```
---
## Implementation Notes
- Always validate schema at https://validator.schema.org/ and https://search.google.com/test/rich-results
- Remove bracketed placeholders and replace with actual content
- Use absolute URLs, not relative paths
- Dates must be in ISO 8601 format
- Schema must match visible page content (Google policy requirement)
- No trailing commas in JSON (invalid syntax)

444
.cursor/skills/schema-markup-generator/references/validation-guide.md Normal file
View file

@ -0,0 +1,444 @@
# Schema Markup Validation Guide
Complete reference for validating, testing, and troubleshooting structured data.
## Validation Tools
### Google Rich Results Test
- **URL**: https://search.google.com/test/rich-results
- **Purpose**: Check if your schema is eligible for Google rich results
- **Tests**: Live URL or code snippet
- **Output**: Errors, warnings, eligible rich result types
### Schema.org Validator
- **URL**: https://validator.schema.org/
- **Purpose**: Validate against official Schema.org specification
- **Tests**: URL, code snippet, or microdata
- **Output**: Technical validation errors
### Google Search Console
- **Location**: Search Console → Enhancements section
- **Purpose**: Monitor rich results performance and errors at scale
- **Reports**: Rich results status, coverage, issues over time
---
## Common JSON-LD Syntax Errors
### Trailing Commas
**Error**: Invalid JSON syntax
```json
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "Title", ← Trailing comma here
}
```
**Fix**: Remove the comma after the last property
```json
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "Title"
}
```
### Missing Required Quotes
**Error**: Property names must be quoted
```json
{
@context: "https://schema.org"
}
```
**Fix**: Quote all property names
```json
{
"@context": "https://schema.org"
}
```
### Incorrect Date Format
**Error**: Invalid date format
```json
{
"datePublished": "01/15/2024"
}
```
**Fix**: Use ISO 8601 format
```json
{
"datePublished": "2024-01-15T08:00:00+00:00"
}
```
### Relative URLs Instead of Absolute
**Error**: Relative URLs are not allowed
```json
{
"image": "/images/photo.jpg"
}
```
**Fix**: Use absolute URLs
```json
{
"image": "https://example.com/images/photo.jpg"
}
```
### Incorrect Array Syntax
**Error**: Multiple values not in array
```json
{
"image": "url1.jpg", "url2.jpg"
}
```
**Fix**: Use array brackets for multiple values
```json
{
"image": ["url1.jpg", "url2.jpg"]
}
```
---
## Required vs Recommended Properties
### FAQPage Schema
| Property | Status | Notes |
|----------|--------|-------|
| @type | Required | Must be "FAQPage" |
| mainEntity | Required | Array of Question objects |
| Question.name | Required | The question text |
| Answer.text | Required | The answer text |
**Minimum**: 2 Q&A pairs
### HowTo Schema
| Property | Status | Notes |
|----------|--------|-------|
| @type | Required | Must be "HowTo" |
| name | Required | Title of the how-to |
| step | Required | Array of HowToStep objects |
| step.text | Required | Step instructions |
| image | Recommended | Improves visibility |
| totalTime | Recommended | Shows duration in results |
| supply | Recommended | Lists materials needed |
| tool | Recommended | Lists tools needed |
**Minimum**: 2 steps with text
### Article Schema
| Property | Status | Notes |
|----------|--------|-------|
| @type | Required | Article/BlogPosting/NewsArticle |
| headline | Required | Max 110 characters |
| image | Required | Minimum 1200px wide |
| datePublished | Required | ISO 8601 format |
| author | Required | Person or Organization |
| publisher | Required | Organization with logo |
| publisher.logo | Required | Max 600px wide, 60px high |
| dateModified | Recommended | Update when content changes |
| description | Recommended | Improves display |
### Product Schema
| Property | Status | Notes |
|----------|--------|-------|
| @type | Required | Must be "Product" |
| name | Required | Product name |
| image | Required | Product images |
| description | Recommended | Product description |
| offers | Recommended | Required for price display |
| offers.price | Recommended | Required for price display |
| offers.priceCurrency | Recommended | Required for price display |
| offers.availability | Recommended | Stock status |
| aggregateRating | Recommended | Required for star ratings |
| review | Recommended | Individual reviews |
| sku | Recommended | Product identifier |
| brand | Recommended | Brand information |
### LocalBusiness Schema
| Property | Status | Notes |
|----------|--------|-------|
| @type | Required | LocalBusiness or subtype |
| name | Required | Business name |
| address | Required | PostalAddress object |
| address.streetAddress | Required | Street address |
| address.addressLocality | Required | City |
| address.addressRegion | Required | State/province |
| address.postalCode | Required | ZIP/postal code |
| address.addressCountry | Required | Country code |
| geo | Recommended | Latitude/longitude |
| telephone | Recommended | Phone number |
| openingHoursSpecification | Recommended | Business hours |
| priceRange | Recommended | Price range indicator |
| aggregateRating | Recommended | Customer ratings |
### Organization Schema
| Property | Status | Notes |
|----------|--------|-------|
| @type | Required | Must be "Organization" |
| name | Required | Organization name |
| url | Required | Website URL |
| logo | Recommended | Brand logo |
| sameAs | Recommended | Social media profiles |
| contactPoint | Recommended | Contact information |
---
## Google Rich Result Eligibility Requirements
### FAQ Rich Results
**Eligibility checklist**:
- [ ] Minimum 2 Q&A pairs
- [ ] Questions are actual questions (contain "?")
- [ ] Answers are complete and comprehensive
- [ ] Content matches visible page content exactly
- [ ] Not a forum or Q&A page where users can submit answers
- [ ] Not advertising or promotional in nature
- [ ] Not for medical, legal, or financial advice without proper E-E-A-T
**Ineligible content**:
- Medical advice without credentials
- Legal advice
- Product/service comparisons that are promotional
- User-generated Q&A (use QAPage instead)
### How-To Rich Results
**Eligibility checklist**:
- [ ] Minimum 2 steps with clear instructions
- [ ] Complete process from start to finish
- [ ] Each step has meaningful text (not just a title)
- [ ] Not advertising or promotional
- [ ] Not harmful or dangerous content
- [ ] Steps are actionable and practical
**Ineligible content**:
- Single-step processes
- Recipes (use Recipe schema instead)
- Promotional tutorials
### Product Rich Results
**For price display**:
- [ ] Valid Product schema
- [ ] `offers` with `price` property
- [ ] `priceCurrency` specified
- [ ] `availability` status
**For review stars**:
- [ ] Valid `aggregateRating` OR individual `review`
- [ ] Minimum 1 review for individual review display
- [ ] Honest, unbiased reviews (not paid/incentivized)
**For product markup**:
- [ ] `name` property present
- [ ] At least one `image`
- [ ] Valid product type (not person, organization, etc.)
### Article Rich Results
**Eligibility checklist**:
- [ ] Valid Article/BlogPosting/NewsArticle schema
- [ ] High-quality, original content
- [ ] Proper `publisher` with valid logo
- [ ] Valid `author` information
- [ ] Images meet size requirements (1200px wide)
- [ ] Not short-form content (minimum ~300 words)
---
## Testing Workflow
### Initial Implementation
1. **Add schema to development/staging environment**
2. **Validate syntax at validator.schema.org**
- Paste code or test URL
- Fix all errors before proceeding
3. **Test at Google Rich Results Test**
- Check for Google-specific issues
- Verify eligible rich result types
4. **Visual inspection**
- View page source to confirm schema is present
- Check JSON formatting in browser
### Pre-Launch Testing
1. **Test on staging URL with Rich Results Test**
2. **Verify all required properties present**
3. **Confirm content matches visible page content**
4. **Check for policy violations**
5. **Test multiple schema types if combining**
6. **Validate images are accessible and meet size requirements**
### Post-Launch Monitoring
1. **Submit sitemap to Google Search Console**
2. **Monitor Enhancements reports**
- Check for validation errors
- Watch for policy violations
- Track rich result impressions
3. **Re-test pages if content changes**
4. **Update `dateModified` when updating content**
5. **Fix errors within 30 days to avoid rich result removal**
---
## Common Policy Violations
### Content Mismatch
**Violation**: Schema content doesn't match visible page content
**Example**: FAQ schema includes Q&A pairs not visible on page
**Fix**: Ensure all structured data reflects actual page content exactly
### Deceptive Content
**Violation**: Schema contains misleading information
**Example**: Product reviews that are fake or incentivized
**Fix**: Only include genuine, verifiable information
### Spammy Markup
**Violation**: Excessive or irrelevant schema
**Example**: Adding Product schema to every blog post
**Fix**: Only use schema types relevant to page content
### Hidden Content
**Violation**: Schema references content hidden from users
**Example**: FAQ answers only in schema, not visible on page
**Fix**: Make all schema content visible to users
### Promotional Content in FAQ
**Violation**: Using FAQ schema for promotional purposes
**Example**: Questions like "Why is [Brand] the best?"
**Fix**: Use neutral, informational questions
---
## Debugging Common Issues
### Schema Not Appearing in Rich Results Test
**Possible causes**:
- JSON syntax error (validate at validator.schema.org)
- Schema in incorrect location (should be in `<head>` or `<body>`)
- Script tag missing `type="application/ld+json"`
- Content served dynamically after page load (bot can't see it)
**Debug steps**:
1. View page source (not inspect element)
2. Search for `"@type"`
3. Copy JSON to validator.schema.org
4. Fix syntax errors
### Rich Results Not Showing in Search
**Possible causes**:
- Schema is new (can take days/weeks to appear)
- Page not indexed by Google
- Schema has errors in Search Console
- Content doesn't meet quality guidelines
- Competition for rich results is high
**Debug steps**:
1. Check Search Console → Enhancements
2. Use URL Inspection tool to request indexing
3. Verify schema passes Rich Results Test
4. Check for manual actions
### Warnings vs Errors
**Errors** (must fix):
- Invalid syntax
- Missing required properties
- Invalid property values
- Schema type doesn't exist
**Warnings** (should fix when possible):
- Missing recommended properties
- Suboptimal property values
- Non-standard extensions
- Property not recognized for this type
---
## Schema Maintenance Checklist
### Monthly
- [ ] Check Search Console for new errors
- [ ] Verify rich results are still appearing
- [ ] Update `dateModified` on changed content
### Quarterly
- [ ] Audit all schema implementations
- [ ] Test key pages with Rich Results Test
- [ ] Update any outdated information (prices, dates, etc.)
- [ ] Check for new schema types relevant to your content
### After Content Changes
- [ ] Update schema to match new content
- [ ] Update `dateModified` timestamp
- [ ] Re-validate with Rich Results Test
- [ ] Request re-indexing in Search Console if major changes
### After Site Migration
- [ ] Verify schema preserved on new URLs
- [ ] Update all absolute URLs in schema
- [ ] Submit new sitemap
- [ ] Monitor for errors in new domain's Search Console
---
## Quick Reference: Error Messages and Fixes
| Error Message | Cause | Fix |
|---------------|-------|-----|
| "Missing required field" | Required property not included | Add the required property |
| "Invalid date format" | Date not in ISO 8601 | Use format: 2024-01-15T08:00:00+00:00 |
| "URL is not absolute" | Relative URL used | Add full URL with https:// |
| "Unexpected token" | JSON syntax error | Check for missing quotes, brackets, commas |
| "This markup is not eligible for rich results" | Schema type or content doesn't qualify | Review eligibility requirements |
| "Image too small" | Image doesn't meet size requirements | Use image at least 1200px wide |
| "The attribute price is required" | Product missing price | Add offers.price property |
| "Logo must be 600x60 or smaller" | Publisher logo too large | Resize logo to meet requirements |
---
## Resources
- **Schema.org Documentation**: https://schema.org/
- **Google Search Central**: https://developers.google.com/search/docs/appearance/structured-data
- **Rich Results Test**: https://search.google.com/test/rich-results
- **Schema Validator**: https://validator.schema.org/
- **JSON-LD Playground**: https://json-ld.org/playground/

456
.cursor/skills/seo-content-writer/SKILL.md Normal file
View file

@ -0,0 +1,456 @@
---
name: seo-content-writer
description: 'Write SEO blog posts, articles, landing pages with keyword integration, header optimization, and snippet targeting. 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 writing SEO-optimized articles, blog posts, landing pages, or product descriptions. Also when the user asks to create content targeting a specific keyword."
argument-hint: "<topic> <target keyword>"
metadata:
author: aaron-he-zhu
version: "6.0.0"
geo-relevance: "medium"
tags:
- seo
- content-writing
- blog-writing
- seo-copywriting
- content-creation
- featured-snippet-optimization
- article-writing
- landing-page
- surferSEO-alternative
- clearscope-alternative
- SEO文章
- 博客写作
- SEOライティング
- SEO글쓰기
- redaccion-seo
triggers:
# EN-formal
- "write SEO content"
- "create blog post"
- "write an article"
- "content writing"
- "draft optimized content"
- "write for SEO"
- "SEO copywriting"
- "blog writing"
# EN-casual
- "write me a blog post"
- "write me an article"
- "help me write about"
- "draft an article about"
- "I need a blog post"
- "create content for my site"
# EN-question
- "how do I write content that ranks"
- "how to write SEO friendly content"
- "what makes content rank well"
# EN-competitor
- "SurferSEO alternative"
- "Clearscope alternative"
- "Jasper AI alternative for SEO"
# ZH-pro
- "SEO文章写作"
- "SEO内容创作"
- "博客写作"
- "内容优化"
- "内容创作"
# ZH-casual
- "帮我写文章"
- "写一篇博客"
- "排名上不去"
- "帮我写SEO文章"
- "写一篇SEO文章"
# JA
- "SEOライティング"
- "SEO記事作成"
- "ブログ記事作成"
- "SEOコンテンツ"
# KO
- "SEO 글쓰기"
- "블로그 작성"
- "SEO 콘텐츠 작성"
- "블로그 글 작성해줘"
- "이 주제로 글 써봐"
# ES
- "redacción SEO"
- "escribir artículo SEO"
- "contenido optimizado"
# PT
- "redação SEO"
- "escrever artigo SEO"
# Misspellings
- "SEO copywritting"
- "writting SEO content"
---
# SEO Content Writer
> **[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 search-engine-optimized content that ranks well while providing genuine value to readers. It applies proven SEO copywriting techniques, proper keyword integration, and optimal content structure.
**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.
- Writing blog posts targeting specific keywords
- Creating landing pages optimized for search
- Developing pillar content for topic clusters
- Writing product descriptions for e-commerce
- Creating service pages for local SEO
- Producing how-to guides and tutorials
- Writing comparison and review articles
## What This Skill Does
1. **Keyword Integration**: Naturally incorporates target and related keywords
2. **Structure Optimization**: Creates scannable, well-organized content
3. **Title & Meta Creation**: Writes compelling, click-worthy titles
4. **Header Optimization**: Uses strategic H1-H6 hierarchy
5. **Internal Linking**: Suggests relevant internal link opportunities
6. **Readability Enhancement**: Ensures content is accessible and engaging
7. **Featured Snippet Optimization**: Formats for SERP feature opportunities
## 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 Content Creation
```
Write an SEO-optimized article about [topic] targeting the keyword [keyword]
```
```
Create a blog post for [topic] with these keywords: [keyword list]
```
### With Specific Requirements
```
Write a 2,000-word guide about [topic] targeting [keyword],
include FAQ section for featured snippets
```
### Content Briefs
```
Here's my content brief: [brief]. Write SEO-optimized content following this outline.
```
## 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 ~~SEO tool + ~~search console connected:**
Automatically pull keyword metrics (search volume, difficulty, CPC), competitor content analysis (top-ranking pages, content length, common topics), SERP features (featured snippets, PAA questions), and keyword opportunities (related keywords, question-based queries).
**With manual data only:**
Ask the user to provide:
1. Target primary keyword and 3-5 secondary keywords
2. Target audience and search intent (informational/commercial/transactional)
3. Target word count and desired tone
4. Any competitor URLs or content examples to reference
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 SEO content:
1. **Gather Requirements**
Confirm or ask for:
```markdown
### Content Requirements
**Primary Keyword**: [main keyword]
**Secondary Keywords**: [2-5 related keywords]
**Target Word Count**: [length]
**Content Type**: [blog/guide/landing page/etc.]
**Target Audience**: [who is this for]
**Search Intent**: [informational/commercial/transactional]
**Tone**: [professional/casual/technical/friendly]
**CTA Goal**: [what action should readers take]
**Competitor URLs**: [top ranking content to beat]
```
2. **Load CORE-EEAT Quality Constraints**
Before writing, load content quality standards 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 Pre-Write Checklist
**Content Type**: [identified from requirements above]
**Loaded Constraints** (high-weight items for this content type):
Apply these standards while writing:
| ID | Standard | How to Apply |
|----|----------|-------------|
| C01 | Intent Alignment | Title promise must match content delivery |
| C02 | Direct Answer | Core answer in first 150 words |
| C06 | Audience Targeting | State "this article is for..." |
| C10 | Semantic Closure | Conclusion answers opening question + next steps |
| O01 | Heading Hierarchy | H1→H2→H3, no level skipping |
| O02 | Summary Box | Include TL;DR or Key Takeaways |
| O06 | Section Chunking | Each section single topic; paragraphs 3–5 sentences |
| O09 | Information Density | No filler; consistent terminology |
| R01 | Data Precision | ≥5 precise numbers with units |
| R02 | Citation Density | ≥1 external citation per 500 words |
| R04 | Evidence-Claim Mapping | Every claim backed by evidence |
| R07 | Entity Precision | Full names for people/orgs/products |
| C03 | Query Coverage | Cover ≥3 query variants (synonyms, long-tail) |
| O08 | Anchor Navigation | Table of contents with jump links |
| O10 | Multimedia Structure | Images/videos have captions and carry information |
| E07 | Practical Tools | Include downloadable templates, checklists, or calculators |
_These 16 items apply across all content types. For content-type-specific dimension weights, see the Content-Type Weight Table in [core-eeat-benchmark.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/core-eeat-benchmark.md)._
_Full 80-item benchmark: [references/core-eeat-benchmark.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/core-eeat-benchmark.md)_
_For complete content quality audit: use [content-quality-auditor](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/content-quality-auditor/SKILL.md)_
```
3. **Research and Plan**
Before writing:
```markdown
### Content Research
**SERP Analysis**:
- Top results format: [what's ranking]
- Average word count: [X] words
- Common sections: [list]
- SERP features: [snippets, PAA, etc.]
**Keyword Map**:
- Primary: [keyword] - use in title, H1, intro, conclusion
- Secondary: [keywords] - use in H2s, body paragraphs
- LSI/Related: [terms] - sprinkle naturally throughout
- Questions: [PAA questions] - use as H2/H3s or FAQ
**Content Angle**:
[What unique perspective or value will this content provide?]
```
4. **Create Optimized Title**
```markdown
### Title Optimization
**Requirements**:
- Include primary keyword (preferably at start)
- Under 60 characters for full SERP display
- Compelling and click-worthy
- Match search intent
**Title Options**:
1. [Title option 1] ([X] chars)
- Keyword position: [front/middle]
- Power words: [list]
2. [Title option 2] ([X] chars)
- Keyword position: [front/middle]
- Power words: [list]
**Recommended**: [Best option with reasoning]
```
5. **Write Meta Description**
```markdown
### Meta Description
**Requirements**:
- 150-160 characters
- Include primary keyword naturally
- Include call-to-action
- Compelling and specific
**Meta Description**:
"[Description text]" ([X] characters)
**Elements included**:
- ✅ Primary keyword
- ✅ Value proposition
- ✅ CTA or curiosity hook
```
6. **Structure Content and Write**
Structure: H1 (primary keyword, one per page) > Introduction (100-150 words, hook + promise + keyword in first 100 words) > H2 sections (secondary keywords/questions) > H3 sub-topics > FAQ section > Conclusion (summary + keyword + CTA).
7. **Apply On-Page SEO Best Practices**
Follow the on-page SEO checklist (keyword placement, content quality, readability, technical elements) and the content writing template (H1 with keyword, hook, sections with H2/H3, FAQ, conclusion with CTA).
> **Reference**: See [references/seo-writing-checklist.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/seo-content-writer/references/seo-writing-checklist.md) for the full on-page SEO checklist, content writing template, and featured snippet optimization patterns.
Key requirements while writing:
- Primary keyword in title, H1, first 100 words, at least one H2, and conclusion
- Paragraphs of 3-5 sentences; varied sentence length; bullet points and bold key phrases
- Internal links (2-5) and external authoritative links (2-3)
- FAQ section with 40-60 word answers for featured snippet opportunity
- Optimize for definition, list, table, and how-to snippets where applicable
8. **Add Internal/External Links**
```markdown
### Link Recommendations
**Internal Links** (include 2-5):
1. "[anchor text]" → [/your-page-url] (relevant because: [reason])
2. "[anchor text]" → [/your-page-url] (relevant because: [reason])
**External Links** (include 2-3 authoritative sources):
1. "[anchor text]" → [authoritative-source.com] (supports: [claim])
2. "[anchor text]" → [authoritative-source.com] (supports: [claim])
```
9. **Final SEO Review and CORE-EEAT Self-Check**
Score content across 10 SEO factors (title, meta description, H1, keyword placement, H2s, internal links, external links, FAQ, readability, word count) and produce an Overall SEO Score out of 10.
Then verify the 16 CORE-EEAT pre-write constraints (C01, C02, C06, C10, O01, O02, O06, O09, R01, R02, R04, R07, C03, O08, O10, E07) with pass/warning/fail status. List items needing attention.
_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)_
#### Issue Classification
When the self-check reveals issues, classify and handle them:
**Auto-correct (fix silently, then document in a `### Changes Made` block after the final content):**
- Meta description exceeds 160 characters → rewrite to fit while preserving primary keyword and CTA
- Title tag exceeds 60 characters → shorten while preserving primary keyword
- Missing alt text on images → generate descriptive alt text
- Duplicate H2 headings → differentiate with modifiers
- Keyword density above 2% → replace some instances with semantic variants
- Missing table of contents → generate TOC with anchor links for articles with 3+ H2 sections
- Paragraphs exceeding 5 sentences → split at the most natural break point
Use this format for the Changes Made block:
```markdown
### Changes Made During Self-Check
| Item | Original | Fixed |
|------|----------|-------|
| Meta description | 185 chars | 158 chars — removed non-essential qualifier |
| Keyword density | 2.4% | 1.8% — replaced 3 instances with semantic variants |
```
**Needs your decision (ask before changing):**
- H1 wording changes (may affect brand voice)
- Keyword density below 0.5% (may need structural rewrite)
- Tone adjustments (formal ↔ casual)
- Claim strength (e.g., "best" → "top-rated" for compliance)
- Content length significantly above/below target (±30%)
- Removing/replacing external links
- Statistics or data claims that cannot be verified against the cited source
## Validation Checkpoints
### Input Validation
- [ ] Primary keyword confirmed and matches search intent
- [ ] Target word count specified (minimum 800 words for substantive content)
- [ ] Content type and audience clearly defined
- [ ] Competitor URLs reviewed or target SERP features identified
### Output Validation
- [ ] Keyword density within 1-2% for primary keyword (Note: Keyword density is a guideline, not a hard rule. Modern search engines prioritize semantic relevance and natural language over exact density targets. Focus on covering the topic comprehensively with semantic variants rather than hitting a specific percentage.)
- [ ] All sections from outline covered completely
- [ ] Internal links included (2-5 relevant links)
- [ ] FAQ section present with at least 3 questions
- [ ] Readability score appropriate for target audience
- [ ] Source of each data point clearly stated (~~SEO tool data, user-provided, or estimated)
## Example
**User**: "Write an SEO-optimized article about 'email marketing best practices' targeting small businesses"
> **Reference**: See [references/seo-writing-checklist.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/seo-content-writer/references/seo-writing-checklist.md) for the full example output demonstrating a complete SEO article with meta description, H1/H2/H3 hierarchy, statistics with citations, comparison tables, FAQ section, and conclusion with CTA.
The example output demonstrates: keyword in H1 and first 100 words, statistics with sources (DMA, Emarsys), comparison tables, bullet-point lists, pro tips, FAQ section with 40-60 word answers, and a clear CTA in the conclusion.
## Content Type Templates
### How-To Guide
```
Write a how-to guide for [task] targeting [keyword]
```
### Comparison Article
```
Write a comparison article: [Option A] vs [Option B] for [keyword]
```
### Listicle
```
Write a list post: "X Best [Items] for [Audience/Purpose]" targeting [keyword]
```
### Ultimate Guide
```
Write an ultimate guide about [topic] (3,000+ words) targeting [keyword]
```
## Tips for Success
1. **Match search intent** - Informational queries need guides, not sales pages
2. **Front-load value** - Put key information early for readers and snippets
3. **Use data and examples** - Specific beats generic every time
4. **Write for humans first** - SEO optimization should feel natural
5. **Include visual elements** - Break up text with images, tables, lists
6. **Update regularly** - Fresh content signals to search engines
### 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-<topic>.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
- [Title Formulas](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/seo-content-writer/references/title-formulas.md) - Proven headline formulas, power words, CTR patterns
- [Content Structure Templates](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/build/seo-content-writer/references/content-structure-templates.md) - Templates for blog posts, comparisons, listicles, how-tos, pillar pages
## 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) — gate the draft before publishing or handing it off.

875
.cursor/skills/seo-content-writer/references/content-structure-templates.md Normal file
View file

@ -0,0 +1,875 @@
# Content Structure Templates
Markdown templates for common SEO content types. Customize section headings and content while maintaining the structural framework.
## Blog Post (Informational)
**Target word count**: 1,200-1,800 words
**Primary goal**: Educate and inform, build authority, rank for informational queries
```markdown
# [Primary Keyword in H1] - [Benefit or Hook]
[Opening hook - 1 compelling sentence that grabs attention]
[Problem statement - describe the pain point or challenge your reader faces]
[Promise - explain what readers will learn or gain from this post]
In this guide, you'll discover:
- [Key takeaway 1]
- [Key takeaway 2]
- [Key takeaway 3]
## What Is [Topic]?
[Clear definition in 40-60 words - GEO-optimized]
[Expanded explanation with context]
[Why this matters - relevance to reader]
## Why [Topic] Matters
[Benefit 1 with supporting evidence]
[Benefit 2 with supporting evidence]
[Benefit 3 with supporting evidence]
> **Key Insight**: [Highlighted important point or statistic]
## [Secondary Keyword or Main Section 1]
[Introduction to this section]
### [Sub-topic 1]
[Detailed explanation]
**Key points**:
- Point 1
- Point 2
- Point 3
### [Sub-topic 2]
[Detailed explanation]
[Example or case study]
## [Secondary Keyword or Main Section 2]
[Section introduction]
| Factor | Description | Impact |
|--------|-------------|--------|
| [Factor 1] | [Description] | High/Medium/Low |
| [Factor 2] | [Description] | High/Medium/Low |
| [Factor 3] | [Description] | High/Medium/Low |
[Additional explanation]
## [Secondary Keyword or Main Section 3]
[Content for this section]
**Best practices**:
1. [Practice 1 with explanation]
2. [Practice 2 with explanation]
3. [Practice 3 with explanation]
## Common Mistakes to Avoid
### [Mistake 1]
[Why this is a mistake]
[How to avoid it]
### [Mistake 2]
[Why this is a mistake]
[How to avoid it]
### [Mistake 3]
[Why this is a mistake]
[How to avoid it]
## Frequently Asked Questions
### [Question from PAA or common query]?
[Direct answer in 40-60 words]
[Optional: Additional context]
### [Question 2]?
[Direct answer]
### [Question 3]?
[Direct answer]
## Conclusion
[Recap key points - include primary keyword]
[Final insight or takeaway]
[Clear call-to-action: next step for reader]
---
**Related reading**: [Internal link 1] | [Internal link 2] | [Internal link 3]
```
**Internal links**: 3-5 contextual links to related content
**External links**: 2-3 links to authoritative sources
**Keywords**: Primary in H1, first 100 words, conclusion; secondary in H2s
**GEO-optimization**: Definition block, FAQ section, quotable statistics
---
## Comparison Article ("[A] vs [B]")
**Target word count**: 1,500-2,500 words
**Primary goal**: Help readers choose between options, rank for comparison queries
```markdown
# [Option A] vs [Option B]: Which Is Better for [Use Case]?
[Hook - present the comparison dilemma]
[Context - why this comparison matters]
[Promise - what readers will understand after reading]
**Quick answer**: [Brief verdict for those who want immediate answer]
## [Option A] vs [Option B]: Quick Comparison
| Feature | [Option A] | [Option B] |
|---------|-----------|-----------|
| [Feature 1] | [Details] | [Details] |
| [Feature 2] | [Details] | [Details] |
| [Feature 3] | [Details] | [Details] |
| [Feature 4] | [Details] | [Details] |
| **Best for** | [Use case] | [Use case] |
| **Starting price** | [Price] | [Price] |
## What Is [Option A]?
[Clear definition]
[Key features and capabilities]
**Pros**:
- [Advantage 1]
- [Advantage 2]
- [Advantage 3]
**Cons**:
- [Disadvantage 1]
- [Disadvantage 2]
## What Is [Option B]?
[Clear definition]
[Key features and capabilities]
**Pros**:
- [Advantage 1]
- [Advantage 2]
- [Advantage 3]
**Cons**:
- [Disadvantage 1]
- [Disadvantage 2]
## [Option A] vs [Option B]: Detailed Comparison
### [Feature Category 1]
**[Option A]**: [Detailed explanation with examples]
**[Option B]**: [Detailed explanation with examples]
**Winner**: [A/B/Tie] - [Brief reasoning]
### [Feature Category 2]
**[Option A]**: [Details]
**[Option B]**: [Details]
**Winner**: [A/B/Tie] - [Brief reasoning]
### [Feature Category 3]
[Continue pattern for key comparison points]
## Pricing: [Option A] vs [Option B]
### [Option A] Pricing
- [Tier 1]: $[X]/month - [What's included]
- [Tier 2]: $[X]/month - [What's included]
- [Tier 3]: $[X]/month - [What's included]
### [Option B] Pricing
- [Tier 1]: $[X]/month - [What's included]
- [Tier 2]: $[X]/month - [What's included]
- [Tier 3]: $[X]/month - [What's included]
**Value winner**: [Which offers better value and why]
## Which Should You Choose?
### Choose [Option A] if:
- [Criteria 1]
- [Criteria 2]
- [Criteria 3]
### Choose [Option B] if:
- [Criteria 1]
- [Criteria 2]
- [Criteria 3]
## Frequently Asked Questions
### Is [Option A] better than [Option B]?
[Nuanced answer - depends on use case]
### Can you use [Option A] and [Option B] together?
[Answer with explanation]
### Which is easier for beginners: [Option A] or [Option B]?
[Answer with reasoning]
## Final Verdict: [Option A] vs [Option B]
[Balanced conclusion]
[Recommendation based on different use cases]
[Clear call-to-action]
```
**Internal links**: Links to detailed reviews of each option, related comparisons
**External links**: Official websites of both options, third-party reviews
**Keywords**: Both options mentioned throughout, comparison keywords in H2s
---
## Listicle ("Top N [Items]")
**Target word count**: 1,500-2,500 words (depending on list length)
**Primary goal**: Provide curated recommendations, rank for "best [topic]" queries
```markdown
# [Number] Best [Items] for [Audience/Purpose] ([Year])
[Hook - establish why this list matters]
[Context - what makes these the "best"]
[Promise - what readers will gain]
After testing [X] different [items], we've identified the [number] that deliver the best results for [audience/purpose].
## Quick Summary: Top [Number] [Items]
| Rank | [Item] | Best For | Price |
|------|--------|----------|-------|
| 1 | [Item 1] | [Use case] | [Price] |
| 2 | [Item 2] | [Use case] | [Price] |
| 3 | [Item 3] | [Use case] | [Price] |
## How We Chose These [Items]
Our selection criteria:
- [Criterion 1] - [Why it matters]
- [Criterion 2] - [Why it matters]
- [Criterion 3] - [Why it matters]
## 1. [Item Name] - Best for [Specific Use Case]
![Alt text: [Item name] screenshot/image]
**What it is**: [Brief description]
**Why we love it**: [Key benefits and features]
**Key features**:
- [Feature 1]
- [Feature 2]
- [Feature 3]
**Pricing**: [Price details]
**Pros**:
- [Pro 1]
- [Pro 2]
**Cons**:
- [Con 1]
- [Con 2]
**Best for**: [Ideal user or use case]
[Link to item]
---
## 2. [Item Name] - Best for [Specific Use Case]
[Follow same structure as #1]
---
## 3. [Item Name] - Best for [Specific Use Case]
[Continue pattern for all items in list]
---
## Comparison: Which [Item] Is Right for You?
| Feature | [Item 1] | [Item 2] | [Item 3] |
|---------|----------|----------|----------|
| [Feature 1] | ✓/✗ | ✓/✗ | ✓/✗ |
| [Feature 2] | ✓/✗ | ✓/✗ | ✓/✗ |
| [Feature 3] | ✓/✗ | ✓/✗ | ✓/✗ |
## How to Choose the Best [Item] for Your Needs
### Consider [Factor 1]
[Explanation of how this factor affects choice]
### Consider [Factor 2]
[Explanation]
### Consider [Factor 3]
[Explanation]
## Frequently Asked Questions
### What is the best [item] for beginners?
[Answer with specific recommendation]
### Which [item] offers the best value?
[Answer with reasoning]
### Are paid [items] better than free ones?
[Balanced answer]
## Conclusion: Our Top Pick
[Restate #1 recommendation]
[Why it's the best overall choice]
[Call-to-action]
```
**Internal links**: Related guides, comparison articles, category pages
**External links**: Links to each recommended item, review sources
**Keywords**: "Best [topic]", individual item names, use case keywords
---
## How-To Guide (Step-by-Step)
**Target word count**: 1,200-2,000 words
**Primary goal**: Teach a specific process, rank for "how to [task]" queries
```markdown
# How to [Achieve Goal]: [Number]-Step Guide [for Audience]
[Hook - present the outcome readers want]
[Current problem - why this is challenging]
[Promise - what readers will accomplish]
By following this step-by-step guide, you'll be able to [specific outcome] in [timeframe].
## What You'll Need
**Tools**:
- [Tool 1]
- [Tool 2]
- [Tool 3]
**Time required**: [Estimated time]
**Skill level**: [Beginner/Intermediate/Advanced]
## Why [Task] Matters
[Explain the benefits of completing this task]
[Provide context and importance]
## Step 1: [Action Title]
![Alt text: Screenshot showing step 1]
[Clear instruction for this step]
[Why this step is important]
**How to do it**:
1. [Sub-step 1]
2. [Sub-step 2]
3. [Sub-step 3]
> **Pro Tip**: [Helpful tip to make this step easier]
**Common mistakes**:
- [Mistake to avoid]
- [Another mistake]
---
## Step 2: [Action Title]
![Alt text: Screenshot showing step 2]
[Instruction for this step]
[Additional context or explanation]
**Example**: [Concrete example showing this step]
---
## Step 3: [Action Title]
[Continue pattern for all steps]
---
## Step [Final Number]: [Action Title]
[Final step instruction]
[What success looks like]
**You'll know it's working when**: [Success indicators]
---
## What to Do If [Common Problem]
### Problem: [Issue 1]
**Solution**: [How to fix it]
### Problem: [Issue 2]
**Solution**: [How to fix it]
## Advanced Tips
Once you've mastered the basics:
1. **[Advanced tip 1]** - [Explanation]
2. **[Advanced tip 2]** - [Explanation]
3. **[Advanced tip 3]** - [Explanation]
## Frequently Asked Questions
### How long does it take to [complete task]?
[Realistic timeframe with variables]
### Do I need [specific tool/skill] to [complete task]?
[Answer with alternatives if applicable]
### What if [specific concern]?
[Address concern with solution]
## Conclusion
[Recap the process]
[Encourage reader to take action]
[Clear next step or CTA]
**Next steps**: [Link to related guide or advanced tutorial]
```
**Internal links**: Links to tool reviews, prerequisite guides, related tutorials
**External links**: Tool documentation, additional resources
**Keywords**: "How to [task]", action words in each step heading
---
## Product Review
**Target word count**: 1,500-2,000 words
**Primary goal**: Help buyers make informed decisions, rank for "[product] review" queries
```markdown
# [Product Name] Review: Is It Worth It in [Year]?
[Hook - establish the product's promise or popularity]
[Context - who this review is for]
After using [Product] for [timeframe], here's my honest assessment of whether it lives up to the hype.
## [Product Name] Overview
**What it is**: [Clear description]
**Price**: [Pricing details]
**Best for**: [Ideal user or use case]
**Rating**: ★★★★☆ (4/5)
## Pros and Cons at a Glance
### Pros
- [Major advantage 1]
- [Major advantage 2]
- [Major advantage 3]
### Cons
- [Main limitation 1]
- [Main limitation 2]
## What Is [Product Name]?
[Detailed product description]
[Who makes it and company background]
[Product positioning and target market]
## Key Features
### [Feature 1]
[Detailed explanation of feature]
[How it works in practice]
[Our experience with this feature]
### [Feature 2]
[Continue pattern for main features]
## Performance Testing
### [Test Category 1]
**What we tested**: [Testing methodology]
**Results**: [Specific results with data]
**Verdict**: [Assessment]
### [Test Category 2]
[Continue testing pattern]
## Pricing and Plans
| Plan | Price | What's Included |
|------|-------|-----------------|
| [Tier 1] | $[X]/month | [Features] |
| [Tier 2] | $[X]/month | [Features] |
| [Tier 3] | $[X]/month | [Features] |
**Value assessment**: [Whether pricing is justified]
## [Product] vs Competitors
| Feature | [Product] | [Competitor 1] | [Competitor 2] |
|---------|-----------|----------------|----------------|
| [Feature 1] | [Details] | [Details] | [Details] |
| [Feature 2] | [Details] | [Details] | [Details] |
| [Feature 3] | [Details] | [Details] | [Details] |
## Who Should Buy [Product]?
### Perfect for:
- [User type 1] because [reason]
- [User type 2] because [reason]
### Not ideal for:
- [User type] because [reason]
- [User type] because [reason]
## Frequently Asked Questions
### Is [Product] worth the price?
[Honest assessment with context]
### How does [Product] compare to [main competitor]?
[Balanced comparison]
### What's the learning curve like?
[Assessment with timeframe]
## Final Verdict: Should You Buy [Product]?
[Balanced conclusion]
[Specific recommendation based on use case]
**Our rating**: ★★★★☆ (4/5)
[Link to product with disclosure if affiliate]
```
**Disclosure**: Include affiliate disclosure if applicable
**Internal links**: Related product reviews, comparison articles, category pages
**External links**: Product website, official documentation
---
## Pillar Page (Comprehensive Guide)
**Target word count**: 3,000-5,000+ words
**Primary goal**: Become definitive resource, rank for head terms, support topic cluster
```markdown
# [Topic]: The Complete Guide [for Audience] ([Year])
[Compelling hook - establish the importance of this topic]
[Problem - what challenges exist in this space]
[Promise - what this comprehensive guide delivers]
This is the most comprehensive guide to [topic] on the web. You'll learn everything from fundamentals to advanced strategies.
## Table of Contents
- [Chapter 1]
- [Chapter 2]
- [Chapter 3]
- [Chapter 4]
- [Chapter 5]
## Chapter 1: [Topic] Fundamentals
### What Is [Topic]?
[Comprehensive definition - GEO-optimized]
[History and evolution]
[Current state and importance]
### Why [Topic] Matters
[Multiple benefits with evidence]
[Industry statistics and trends]
### Key Concepts and Terminology
| Term | Definition |
|------|------------|
| [Term 1] | [Definition] |
| [Term 2] | [Definition] |
| [Term 3] | [Definition] |
## Chapter 2: [Major Sub-Topic]
[Comprehensive section on major aspect]
[Multiple sub-sections with H3 headings]
[Examples, case studies, data]
[Internal links to detailed cluster content]
> **Deep dive**: For more on [sub-topic], see our complete guide: [link]
## Chapter 3: [Major Sub-Topic]
[Continue pattern with substantial content sections]
## Chapter 4: [Advanced/Tactical Section]
[Strategic or tactical content]
[Actionable frameworks and processes]
## Chapter 5: [Implementation/Case Studies]
[Real-world applications]
[Success stories]
[Implementation roadmap]
## Frequently Asked Questions
[Comprehensive FAQ section with 8-10 questions]
## Key Takeaways
[Summarize main points from each chapter]
## What's Next?
[Recommend next steps]
[Links to related cluster content]
## Resources
**Recommended tools**:
- [Tool 1] - [Use case]
- [Tool 2] - [Use case]
**Further reading**:
- [Internal link to cluster content]
- [Internal link to cluster content]
- [External resource]
```
**Internal links**: 8-15 links to related cluster content
**External links**: 5-10 authoritative sources
**Update frequency**: Quarterly for pillar pages
---
## FAQ Page
**Target word count**: 1,000-1,500 words
**Primary goal**: Answer common questions, rank for question queries, enable FAQ rich results
```markdown
# [Topic]: Frequently Asked Questions
[Introduction explaining what questions this page answers]
[Who this FAQ is for]
## General Questions
### What is [topic]?
[Comprehensive answer with definition]
### How does [topic] work?
[Clear explanation with steps if applicable]
### Why is [topic] important?
[Benefits and context]
## Getting Started
### How do I get started with [topic]?
[Step-by-step guidance]
### What do I need to [accomplish goal]?
[Requirements and prerequisites]
### How long does it take to [achieve result]?
[Realistic timeframe]
## Common Problems
### Why isn't [expected result] happening?
[Troubleshooting guidance]
### What should I do if [problem occurs]?
[Solution with steps]
### How do I fix [specific error]?
[Fix instructions]
## Comparison Questions
### [Option A] vs [Option B]: which is better?
[Balanced comparison answer]
### Should I [action 1] or [action 2]?
[Guidance based on scenarios]
## Pricing and Plans
### How much does [topic] cost?
[Pricing information with context]
### Is there a free version?
[Information about free options]
## Advanced Questions
### Can I [advanced action]?
[Answer with technical details]
### How do I [complex task]?
[Guidance with link to detailed guide]
## Still Have Questions?
[Call-to-action for additional support]
[Contact information or link to contact page]
```
**Schema markup**: Add FAQPage schema to enable rich results
**Internal links**: Link to detailed guides for complex answers
**Keywords**: Include question keywords naturally
---
## Implementation Checklist
For any template:
- [ ] Customize all [bracketed placeholders]
- [ ] Include primary keyword in H1 and first 100 words
- [ ] Place secondary keywords in H2/H3 headings
- [ ] Add 3-5 internal links to related content
- [ ] Include 2-3 external links to authoritative sources
- [ ] Create GEO-optimized definition blocks
- [ ] Add FAQ section for featured snippet opportunities
- [ ] Include relevant images with descriptive alt text
- [ ] Write compelling meta description (150-160 chars)
- [ ] Optimize title tag (50-60 chars with primary keyword)

250
.cursor/skills/seo-content-writer/references/seo-writing-checklist.md Normal file
View file

@ -0,0 +1,250 @@
# SEO Writing Checklist and Content Template
On-page SEO checklist, content writing template, and featured snippet optimization patterns.
---
## On-Page SEO Checklist
**Keyword Placement**:
- [ ] Primary keyword in title
- [ ] Primary keyword in H1
- [ ] Primary keyword in first 100 words
- [ ] Primary keyword in at least one H2
- [ ] Primary keyword in conclusion
- [ ] Primary keyword in meta description
- [ ] Secondary keywords in H2s/H3s
- [ ] Related terms throughout body
**Content Quality**:
- [ ] Comprehensive coverage of topic
- [ ] Original insights or data
- [ ] Actionable takeaways
- [ ] Examples and illustrations
- [ ] Expert quotes or citations (for E-E-A-T)
**Readability**:
- [ ] Paragraphs of 3-5 sentences (per CORE-EEAT O06 Section Chunking standard)
- [ ] Varied sentence length
- [ ] Bullet points and lists
- [ ] Bold key phrases
- [ ] Table of contents for long content
**Technical**:
- [ ] Internal links to relevant pages (2-5)
- [ ] External links to authoritative sources (2-3)
- [ ] Image alt text with keywords
- [ ] URL slug includes keyword
---
## Content Writing Template
```markdown
# [H1 with Primary Keyword]
[Hook sentence that grabs attention]
[Problem statement or context - why this matters]
[Promise - what the reader will learn/gain] [Include primary keyword naturally]
[Brief overview of what's covered - can be bullet points for scanability]
## [H2 - First Main Section with Secondary Keyword]
[Introduction to section - 1-2 sentences]
[Main content with valuable information]
[Examples, data, or evidence to support points]
[Transition to next section]
### [H3 - Sub-section if needed]
[Detailed content]
[Key points in bullet format]:
- Point 1
- Point 2
- Point 3
## [H2 - Second Main Section]
[Continue with valuable content...]
> **Pro Tip**: [Highlighted tip or key insight]
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data | Data | Data |
## [H2 - Additional Sections as Needed]
[Content...]
## Frequently Asked Questions
### [Question from PAA or common query]?
[Direct, concise answer in 40-60 words for featured snippet opportunity]
### [Question 2]?
[Answer]
### [Question 3]?
[Answer]
## Conclusion
[Summary of key points - include primary keyword]
[Final thought or insight]
[Clear call-to-action: what should reader do next?]
```
---
## Featured Snippet Optimization
**For Definition Snippets**:
"[Term] is [clear, concise definition in 40-60 words]"
**For List Snippets**:
Create clear, numbered or bulleted lists under H2s
**For Table Snippets**:
Use comparison tables with clear headers
**For How-To Snippets**:
Number each step clearly: "Step 1:", "Step 2:", etc.
---
## Example: Full SEO Article
**User**: "Write an SEO-optimized article about 'email marketing best practices' targeting small businesses"
**Output**:
```markdown
# Email Marketing Best Practices: A Complete Guide for Small Businesses
**Meta Description**: Discover proven email marketing best practices that help small businesses increase open rates, boost engagement, and drive sales. Start improving your campaigns today. (158 chars)
---
Want to know the secret behind small businesses that consistently turn subscribers into loyal customers? It's not luck---it's strategic email marketing.
Email marketing remains one of the most effective channels for small businesses, delivering an average ROI of $42 for every $1 spent. But with inboxes more crowded than ever, following email marketing best practices isn't optional---it's essential for survival.
In this guide, you'll learn:
- How to build a quality email list that converts
- Proven strategies to increase open and click rates
- Advanced personalization techniques that drive results
- Common mistakes that kill email performance
Let's dive into the strategies that will transform your email marketing.
## Why Email Marketing Matters for Small Businesses
Before we explore the best practices, let's understand why email deserves your attention.
Unlike social media where algorithms control who sees your content, email gives you direct access to your audience. You own your email list---no platform can take it away.
**Key email marketing statistics for small businesses**:
- 81% of SMBs rely on email as their primary customer acquisition channel
- Email subscribers are 3x more likely to share content on social media
- Personalized emails generate 6x higher transaction rates
## Building a High-Quality Email List
### Use Strategic Opt-in Incentives
The foundation of effective email marketing is a quality list. Here's how to grow yours:
**Lead magnets that convert**:
- Industry-specific templates
- Exclusive discounts or early access
- Free tools or calculators
- Educational email courses
> **Pro Tip**: The best lead magnets solve a specific, immediate problem for your target audience.
### Implement Double Opt-in
Double opt-in confirms subscriber intent and improves deliverability. Yes, you'll have fewer subscribers, but they'll be more engaged.
| Single Opt-in | Double Opt-in |
|---------------|---------------|
| More subscribers | Fewer subscribers |
| Higher bounce rates | Lower bounce rates |
| Lower engagement | Higher engagement |
| Spam risk | Better deliverability |
## Crafting Emails That Get Opened
### Write Compelling Subject Lines
Your subject line determines whether emails get opened or ignored.
**Subject line best practices**:
1. Keep it under 50 characters
2. Create urgency without being spammy
3. Use numbers and specifics
4. Personalize when possible
5. A/B test consistently
### Optimize Preview Text
The preview text (preheader) is your second chance to convince someone to open. Use it to expand on your subject line, not repeat it.
## Personalization Strategies That Work
Generic emails perform poorly. Here's how to personalize effectively:
### Segment Your Email List
Divide your list based on:
- Purchase history
- Engagement level
- Demographics
- Interests or preferences
- Customer lifecycle stage
### Use Dynamic Content
Send the same email but show different content blocks based on subscriber data.
## Frequently Asked Questions
### How often should small businesses send marketing emails?
For most small businesses, sending 1-2 emails per week strikes the right balance. This keeps you top-of-mind without overwhelming subscribers. Monitor your unsubscribe rates---if they spike after increasing frequency, scale back.
### What is a good email open rate for small businesses?
A good email open rate for small businesses is 20-25%. However, this varies by industry. E-commerce averages 15-20%, while B2B services often see 25-30%. Focus on improving your own benchmarks rather than industry averages.
### Should I buy email lists to grow faster?
Never buy email lists. Purchased lists violate GDPR and CAN-SPAM regulations, damage your sender reputation, and result in poor engagement. Organic list growth, while slower, produces much better results.
## Conclusion
Implementing these email marketing best practices will help your small business build stronger customer relationships and drive consistent revenue. Remember: quality always beats quantity in email marketing.
Start with one improvement today. Whether it's segmenting your list, testing subject lines, or cleaning inactive subscribers, small changes compound into significant results.
**Ready to level up your email marketing?** Download our free Email Marketing Checklist to ensure every campaign you send follows these best practices.
---
*Further reading: [Internal link: "How to Write Email Copy That Converts"]*
*Sources: [Litmus Email Marketing Statistics](https://litmus.com), [Campaign Monitor Email Benchmarks](https://campaignmonitor.com)*
```

339
.cursor/skills/seo-content-writer/references/title-formulas.md Normal file
View file

@ -0,0 +1,339 @@
# Title and Headline Formulas
Proven title structures that drive clicks and rankings. All formulas target 50-60 characters for optimal SERP display.
## Numbered List Formulas
**Pattern**: [Number] [Adjective] [Topic] [Qualifier/Benefit]
### Examples
- "7 Ways to Improve Your SEO Rankings in 2024"
- "15 Content Marketing Strategies That Actually Work"
- "10 Free Tools for Keyword Research (Beginner-Friendly)"
- "21 Email Marketing Tips from Industry Experts"
- "5 Quick Wins for Better Site Performance"
**Why it works**: Numbers promise specific value, create curiosity, set clear expectations.
**Best practices**:
- Odd numbers (7, 9, 15) often outperform even numbers
- Use specific numbers (13 vs "over 10")
- Keep total under 30 for credibility
- Match number to actual content sections
---
## How-To Formulas
**Pattern 1**: How to [Achieve Goal] in [Timeframe]
- "How to Rank on Google in 30 Days"
- "How to Write SEO Content in Under 2 Hours"
- "How to Build Backlinks in 2024"
**Pattern 2**: How to [Achieve Goal] Without [Common Objection]
- "How to Learn SEO Without Spending Money"
- "How to Increase Traffic Without Paid Ads"
- "How to Write Blog Posts Without Writer's Block"
**Pattern 3**: How to [Achieve Goal] (Even If [Limitation])
- "How to Rank #1 (Even If You're a New Website)"
- "How to Get Backlinks (Even With Zero Audience)"
- "How to Write SEO Content (Even If You Hate Writing)"
**Pattern 4**: How to [Achieve Goal] Like [Authority/Expert]
- "How to Write Email Copy Like a Professional Copywriter"
- "How to Do Keyword Research Like an SEO Pro"
- "How to Create Content Like Top Marketing Agencies"
---
## Question Formulas
**Pattern 1**: What Is [Topic]? [Benefit/Hook]
- "What Is Technical SEO? A Complete Guide"
- "What Is GEO? Everything You Need to Know"
- "What Is Content Marketing? (And Why It Matters)"
**Pattern 2**: Why [Action] [Result]
- "Why Most Content Marketing Strategies Fail"
- "Why Your Website Isn't Ranking"
- "Why Email Still Beats Social Media for ROI"
**Pattern 3**: Should You [Action]? [Quick Answer]
- "Should You Buy Backlinks? (Spoiler: No)"
- "Should You Hire an SEO Agency? A Cost-Benefit Analysis"
- "Should You Rewrite Old Content? When It Makes Sense"
**Pattern 4**: When Should You [Action]
- "When Should You Publish Blog Posts for Maximum Traffic"
- "When Should You Update Your SEO Strategy"
- "When Should You Remove Content from Your Website"
---
## Comparison Formulas
**Pattern 1**: [Option A] vs [Option B]: Which Is Better?
- "WordPress vs Webflow: Which Is Better for SEO?"
- "Ahrefs vs SEMrush: Complete Comparison 2024"
- "In-House SEO vs Agency: Which Should You Choose?"
**Pattern 2**: [Option A] vs [Option B] (and the Winner Is...)
- "Free Tools vs Paid SEO Software (and the Winner Is...)"
- "Long-Form vs Short-Form Content (and the Winner Is...)"
**Pattern 3**: [Option A] or [Option B] for [Audience/Goal]
- "Shopify or WooCommerce for Small Business SEO"
- "YouTube or TikTok for B2B Marketing"
---
## Ultimate Guide Formulas
**Pattern 1**: The [Complete/Definitive] Guide to [Topic]
- "The Complete Guide to Technical SEO"
- "The Definitive Guide to Link Building in 2024"
**Pattern 2**: [Topic]: The Ultimate Guide for [Audience]
- "Content Marketing: The Ultimate Guide for Beginners"
- "Local SEO: The Ultimate Guide for Small Businesses"
**Pattern 3**: Everything You Need to Know About [Topic]
- "Everything You Need to Know About Core Web Vitals"
- "Everything You Need to Know About Schema Markup"
---
## Power Word Formulas
**Pattern**: [Power Word] [Topic] [Qualifier]
### Power Word Categories
**Authority words**:
- Proven, Tested, Verified, Certified, Official
- Example: "Proven Strategies to Double Your Organic Traffic"
**Urgency words**:
- Now, Today, Fast, Quick, Instantly, Immediately
- Example: "Quick Wins: Improve SEO Performance Today"
**Value words**:
- Free, Complete, Essential, Ultimate, Comprehensive
- Example: "The Essential SEO Checklist for 2024"
**Exclusivity words**:
- Secret, Hidden, Little-Known, Insider, Exclusive
- Example: "7 Little-Known SEO Tactics That Actually Work"
**Emotional words**:
- Amazing, Powerful, Effortless, Simple, Easy
- Example: "Simple SEO Strategies for Busy Entrepreneurs"
---
## Before/After Formulas
**Pattern 1**: From [Bad State] to [Good State]
- "From Zero to 10K Monthly Visitors: A Case Study"
- "From Page 5 to Position 1: How We Ranked a Competitive Keyword"
**Pattern 2**: How I/We [Achieved Result] in [Timeframe]
- "How I Increased Organic Traffic by 300% in 6 Months"
- "How We Built 100 Backlinks in 30 Days"
**Pattern 3**: [Bad State] → [Good State]: [Method]
- "500 Visitors → 50K: Our Content Strategy Revealed"
- "Struggling → Thriving: SEO Transformation Story"
---
## Mistake/Problem Formulas
**Pattern 1**: [Number] [Topic] Mistakes [Qualifier]
- "5 SEO Mistakes Killing Your Rankings"
- "10 Content Marketing Mistakes to Avoid in 2024"
- "3 Technical SEO Mistakes Even Pros Make"
**Pattern 2**: Stop [Wrong Action]. Do [Right Action] Instead
- "Stop Keyword Stuffing. Do This Instead"
- "Stop Buying Backlinks. Try These 7 Tactics Instead"
**Pattern 3**: Why Your [Topic] Isn't Working (And How to Fix It)
- "Why Your Content Isn't Ranking (And How to Fix It)"
- "Why Your SEO Strategy Isn't Working (And How to Fix It)"
---
## Checklist Formulas
**Pattern 1**: [Topic] Checklist: [Number] Must-Have [Items]
- "Technical SEO Checklist: 23 Must-Check Items"
- "Blog Post Checklist: 15 Things to Check Before Publishing"
**Pattern 2**: The [Timeframe] [Topic] Checklist
- "The 2024 SEO Audit Checklist"
- "The Pre-Launch Website Checklist"
---
## Curiosity Gap Formulas
**Pattern 1**: The [Adjective] Reason [Unexpected Fact]
- "The Surprising Reason Long Content Ranks Better"
- "The Real Reason Your Blog Posts Aren't Getting Traffic"
**Pattern 2**: [Number] Things About [Topic] That [Surprising Fact]
- "7 Things About SEO That Google Doesn't Tell You"
- "5 Things About Content Marketing That Changed in 2024"
**Pattern 3**: What [Expert/Group] Know About [Topic] (That You Don't)
- "What Top SEO Agencies Know About Link Building (That You Don't)"
- "What Professional Copywriters Know About Headlines"
---
## Benefit-Driven Formulas
**Pattern 1**: [Action] to [Specific Benefit]
- "Optimize Your Title Tags to Double Your CTR"
- "Write Better Meta Descriptions to Increase Organic Traffic"
**Pattern 2**: [Action] for [Outcome] Without [Objection]
- "Scale Content Production for Better Rankings Without Hiring Writers"
- "Improve Site Speed for Higher Rankings Without Technical Skills"
---
## Authority/Credibility Formulas
**Pattern 1**: [Expert/Authority] Says [Action/Tip]
- "Google's John Mueller Says Internal Linking Is Underrated"
- "SEO Experts Reveal Their Top Ranking Factor for 2024"
**Pattern 2**: [Number] [Experts/Companies] Share [Topic]
- "50 SEO Experts Share Their #1 Ranking Tip"
- "10 Successful Brands Share Their Content Strategy"
---
## CTR Optimization Patterns
### Elements That Increase CTR
**Year/Timeframe** (signals freshness):
- "SEO Trends for 2024"
- "Best Practices [Updated January 2024]"
**Brackets/Parentheticals** (adds extra context):
- "Email Marketing Tips (That Actually Work)"
- "SEO Tools [Free & Paid Options]"
**Numbers** (promise specific value):
- "7 Ways...", "15 Tools...", "3 Reasons..."
**Power words** (emotional trigger):
- Ultimate, Essential, Complete, Proven, Secret
**Target audience** (relevance signal):
- "...for Beginners", "...for Small Businesses", "...for B2B"
### Elements That Decrease CTR
- All caps (looks spammy)
- Excessive punctuation (!!!, ???)
- Clickbait without substance
- Misleading promises
- Generic titles ("SEO Tips", "Marketing Guide")
---
## Title Length Guidelines
### Google SERP
- **Optimal**: 50-60 characters
- **Maximum**: ~70 characters before truncation
- **Mobile**: ~55 characters (truncates earlier)
### Social Media
- **Twitter/X**: 70-100 characters for best engagement
- **Facebook**: 40-50 characters (shorter performs better)
- **LinkedIn**: 70-100 characters
- **Pinterest**: 40-60 characters
### Email Subject Lines
- **Optimal**: 40-50 characters
- **Mobile**: 30-40 characters (truncates earlier)
- **Desktop**: Up to 60 characters
---
## Before/After Title Examples
### Generic → Optimized
**Before**: "SEO Tips"
**After**: "7 SEO Tips That Increased Our Traffic by 300%"
- Added: Number, specificity, proof
**Before**: "How to Do Keyword Research"
**After**: "How to Do Keyword Research (Free Tools & 5-Step Process)"
- Added: Benefit, specificity, process indicator
**Before**: "Content Marketing Guide"
**After**: "The Complete Content Marketing Guide for Small Businesses [2024]"
- Added: Completeness indicator, target audience, year
**Before**: "What Is Technical SEO"
**After**: "What Is Technical SEO? A Beginner's Guide to Better Rankings"
- Added: Audience level, benefit
**Before**: "WordPress vs Shopify"
**After**: "WordPress vs Shopify: Which Is Better for SEO? (2024 Comparison)"
- Added: Specific comparison angle, year
**Before**: "Link Building Strategies"
**After**: "15 White-Hat Link Building Strategies That Still Work in 2024"
- Added: Number, quality signal, time relevance
---
## Title Writing Checklist
Before finalizing any title, check:
- [ ] Includes primary keyword naturally
- [ ] Length is 50-60 characters
- [ ] Matches search intent (informational/transactional/navigational)
- [ ] Contains power word or emotional trigger
- [ ] Specific and concrete (not vague)
- [ ] Promises clear value or benefit
- [ ] Accurate representation of content
- [ ] No clickbait or misleading claims
- [ ] Unique compared to competitors
- [ ] Works when truncated on mobile
---
## Testing and Optimization
### A/B Test These Variables
- Number variations (7 vs 10 vs 15)
- Power word placement (beginning vs end)
- Question vs statement format
- With/without year
- With/without brackets
- Different benefit framing
### Track These Metrics
- Click-through rate (CTR) in Search Console
- Average position in SERPs
- Time on page (engagement indicator)
- Bounce rate (relevance indicator)
### When to Rewrite Titles
- CTR below 2% for top 3 positions
- CTR below 5% for positions 4-10
- Content is updated (add [Updated 2024])
- Competitors have better titles
- Ranking but not getting clicks

284
.cursor/skills/serp-analysis/SKILL.md Normal file
View file

@ -0,0 +1,284 @@
---
name: serp-analysis
description: 'Analyze SERPs: ranking factors, features, intent patterns, AI overviews, featured snippets. SERP分析/搜索结果'
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."
allowed-tools: WebFetch
homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills"
when_to_use: "Use when analyzing search engine results pages, SERP features, featured snippets, People Also Ask, or understanding ranking patterns for a query."
argument-hint: "<keyword or query>"
metadata:
author: aaron-he-zhu
version: "6.0.0"
geo-relevance: "high"
tags:
- seo
- geo
- serp-analysis
- serp-features
- featured-snippet
- ai-overview
- people-also-ask
- search-intent
- SERP分析
- 検索結果分析
- 검색결과
- analisis-serp
triggers:
# EN-formal
- "analyze search results"
- "SERP analysis"
- "what ranks for"
- "SERP features"
- "why does this page rank"
- "featured snippets"
- "AI overviews"
# EN-casual
- "what's on page one for this query"
- "who ranks for this keyword"
- "what does Google show for"
- "what shows up for this search"
- "who is on page one"
# EN-question
- "why does this page rank first"
- "what SERP features appear for"
# ZH-pro
- "SERP分析"
- "搜索结果分析"
- "精选摘要"
- "AI概览"
# ZH-casual
- "谁排第一"
- "搜索结果长什么样"
- "谁排在前面"
# JA
- "検索結果ページ分析"
- "検索結果分析"
- "強調スニペット"
# KO
- "검색 결과 분석"
- "SERP 분석"
# ES
- "análisis SERP"
- "análisis de resultados de búsqueda"
# PT
- "análise de SERP"
# Misspellings
- "serp anaylsis"
---
# SERP 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 analyzes Search Engine Results Pages to reveal what's working for ranking content, which SERP features appear, and what triggers AI-generated answers. Understand the battlefield before creating content.
**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.
- Before creating content for a target keyword
- Understanding why certain pages rank #1
- Identifying SERP feature opportunities (featured snippets, PAA)
- Analyzing AI Overview/SGE patterns
- Evaluating keyword difficulty more accurately
- Planning content format based on what ranks
- Identifying ranking factors for specific queries
## What This Skill Does
1. **SERP Composition Analysis**: Maps what appears on the results page
2. **Ranking Factor Identification**: Reveals why top results rank
3. **SERP Feature Mapping**: Identifies featured snippets, PAA, knowledge panels
4. **AI Overview Analysis**: Examines when and how AI answers appear
5. **Intent Signal Detection**: Confirms user intent from SERP composition
6. **Content Format Recommendations**: Suggests optimal format based on SERP
7. **Difficulty Assessment**: Evaluates realistic ranking potential
## 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 SERP Analysis
```
Analyze the SERP for [keyword]
```
```
What does it take to rank for [keyword]?
```
### Feature-Specific Analysis
```
Analyze featured snippet opportunities for [keyword list]
```
```
Which of these keywords trigger AI Overviews? [keyword list]
```
### Competitive SERP Analysis
```
Why does [URL] rank #1 for [keyword]?
```
## 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 + ~~AI monitor connected:**
Automatically fetch SERP snapshots for target keywords, extract ranking page metrics (domain authority, backlinks, content length), pull SERP feature data, and check AI Overview presence using ~~AI monitor. Historical SERP change data and mobile vs. desktop variations can be retrieved automatically.
**With manual data only:**
Ask the user to provide:
1. Target keyword(s) to analyze
2. SERP screenshots or detailed descriptions of search results
3. URLs of top 10 ranking pages
4. Search location and device type (mobile/desktop)
5. Any observations about SERP features (featured snippets, PAA, AI Overviews)
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 SERP analysis:
1. **Understand the Query**
Clarify if needed:
- Target keyword(s) to analyze
- Search location/language
- Device type (mobile/desktop)
- Specific questions about the SERP
2. **Map SERP Composition**
Document all elements appearing on the results page: AI Overview, ads, featured snippet, organic results, PAA, knowledge panel, image pack, video results, local pack, shopping results, news results, sitelinks, and related searches.
3. **Analyze Top Ranking Pages**
For each of the top 10 results, document: URL, domain, domain authority, content type, word count, publish/update dates, on-page factors (title, meta description, H1, URL structure), content structure (headings, media, tables, FAQ), estimated metrics (backlinks, referring domains), and why it ranks.
4. **Identify Ranking Patterns**
Analyze common characteristics across top 5 results: word count, domain authority, backlinks, content freshness, HTTPS, mobile optimization. Document content format distribution, domain type distribution, and key success factors.
5. **Analyze SERP Features**
For each present SERP feature: analyze the current holder, content format, and strategy to win. Cover Featured Snippet (type, content, winning strategy), PAA (questions, current answers, optimization approach), and AI Overview (sources cited, content patterns, citation strategy).
6. **Determine Search Intent**
Confirm primary intent from SERP composition. Document evidence, intent breakdown percentages, and content format implications (format, tone, CTA).
7. **Calculate True Difficulty**
Score overall difficulty (1-100) based on: top 10 domain authority, page authority, backlinks required, content quality bar, and SERP stability. Provide realistic assessments for new, growing, and established sites, plus easier alternatives.
8. **Generate Recommendations**
Produce a summary with: Key Findings, Content Requirements to Rank (minimum requirements + differentiators), SERP Feature Strategy, Recommended Content Outline, and Next Steps.
> **Reference**: See [references/analysis-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/serp-analysis/references/analysis-templates.md) for detailed templates for each step.
## Validation Checkpoints
### Input Validation
- [ ] Target keyword(s) clearly specified
- [ ] Search location and device type confirmed
- [ ] SERP data is current (date confirmed)
- [ ] Top 10 ranking URLs identified or provided
### Output Validation
- [ ] Every recommendation cites specific data points (not generic advice)
- [ ] SERP composition mapped with all features documented
- [ ] Ranking factors identified from actual top 10 analysis (not assumptions)
- [ ] Content requirements based on observed patterns in current SERP
- [ ] Source of each data point clearly stated (~~SEO tool data, ~~AI monitor data, user-provided, or manual observation)
## Example
> **Reference**: See [references/example-report.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/serp-analysis/references/example-report.md) for a complete example analyzing the SERP for "how to start a podcast".
## Advanced Analysis
### Multi-Keyword SERP Comparison
```
Compare SERPs for [keyword 1], [keyword 2], [keyword 3]
```
### Historical SERP Changes
```
How has the SERP for [keyword] changed over time?
```
### Local SERP Variations
```
Compare SERP for [keyword] in [location 1] vs [location 2]
```
### Mobile vs Desktop SERP
```
Analyze mobile vs desktop SERP differences for [keyword]
```
## Tips for Success
1. **Always check SERP before writing** - Don't assume, verify
2. **Match content format to SERP** - If lists rank, write lists
3. **Identify SERP feature opportunities** - Lower competition than #1
4. **Note SERP volatility** - Stable SERPs are harder to break into
5. **Study the outliers** - Why does a weaker site rank? Opportunity!
6. **Consider AI Overview optimization** - Growing importance
### Save Results
After delivering findings to the user, ask:
> "Save these results for future sessions?"
If yes, write a dated summary to `memory/research/serp-analysis/YYYY-MM-DD-<topic>.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/serp-analysis/references/analysis-templates.md) — Detailed templates for each analysis step (SERP composition, top results, ranking patterns, features, intent, difficulty, recommendations)
- [SERP Feature Taxonomy](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/serp-analysis/references/serp-feature-taxonomy.md) — Complete taxonomy of SERP features with trigger conditions, AI overview framework, intent signals, and volatility assessment
- [Example Report](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/research/serp-analysis/references/example-report.md) — Complete example analyzing the SERP for "how to start a podcast"
## 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 SERP patterns into a content brief or page structure.

297
.cursor/skills/serp-analysis/references/analysis-templates.md Normal file
View file

@ -0,0 +1,297 @@
# SERP Analysis — Analysis Templates
Templates for each step of the SERP analysis workflow. Use these to structure your output.
## SERP Composition Template
```markdown
## SERP Analysis: "[keyword]"
**Search Details**
- Keyword: [keyword]
- Location: [location]
- Device: [mobile/desktop]
- Date: [date]
### SERP Layout Overview
```
┌─────────────────────────────────────────┐
│ [AI Overview / SGE] (if present) │
├─────────────────────────────────────────┤
│ [Ads] - [X] ads above fold │
├─────────────────────────────────────────┤
│ [Featured Snippet] (if present) │
├─────────────────────────────────────────┤
│ [Organic Result #1] │
│ [Organic Result #2] │
│ [People Also Ask] (if present) │
│ [Organic Result #3] │
│ ... │
├─────────────────────────────────────────┤
│ [Related Searches] │
└─────────────────────────────────────────┘
```
### SERP Features Present
| Feature | Present | Position | Opportunity |
|---------|---------|----------|-------------|
| AI Overview | Yes/No | Top | [analysis] |
| Featured Snippet | Yes/No | [pos] | [analysis] |
| People Also Ask | Yes/No | [pos] | [analysis] |
| Knowledge Panel | Yes/No | Right | [analysis] |
| Image Pack | Yes/No | [pos] | [analysis] |
| Video Results | Yes/No | [pos] | [analysis] |
| Local Pack | Yes/No | [pos] | [analysis] |
| Shopping Results | Yes/No | [pos] | [analysis] |
| News Results | Yes/No | [pos] | [analysis] |
| Sitelinks | Yes/No | [pos] | [analysis] |
```
## Top Results Analysis Template
```markdown
### Top 10 Organic Results Analysis
#### Position #1: [Title]
**URL**: [url]
**Domain**: [domain]
**Domain Authority**: [DA]
**Content Analysis**:
- Type: [Blog/Product/Guide/etc.]
- Word Count: [X] words
- Publish Date: [date]
- Last Updated: [date]
**On-Page Factors**:
- Title: [exact title]
- Title contains keyword: Yes/No
- Meta description: [description]
- H1: [heading]
- URL structure: [clean/keyword-rich/etc.]
**Content Structure**:
- Headings (H2s): [list key sections]
- Media: [X] images, [X] videos
- Tables/Lists: Yes/No
- FAQ section: Yes/No
**Estimated Metrics**:
- Page backlinks: [X]
- Referring domains: [X]
- Social shares: [X]
**Why It Ranks #1**:
1. [Factor 1]
2. [Factor 2]
3. [Factor 3]
[Repeat for positions #2-10]
```
## Ranking Patterns Template
```markdown
### Ranking Patterns Analysis
**Common Characteristics of Top 5 Results**:
| Factor | Avg/Common Value | Importance |
|--------|-----------------|------------|
| Word Count | [X] words | High/Med/Low |
| Domain Authority | [X] | High/Med/Low |
| Page Backlinks | [X] | High/Med/Low |
| Content Freshness | [timeframe] | High/Med/Low |
| HTTPS | [X]% | High/Med/Low |
| Mobile Optimized | [X]% | High/Med/Low |
**Content Format Distribution**:
- How-to guides: [X]/10
- Listicles: [X]/10
- In-depth articles: [X]/10
- Product pages: [X]/10
- Other: [X]/10
**Domain Type Distribution**:
- Brand/Company sites: [X]/10
- Media/News sites: [X]/10
- Niche blogs: [X]/10
- Aggregators: [X]/10
**Key Success Factors Identified**:
1. **[Factor 1]**: [Explanation + evidence]
2. **[Factor 2]**: [Explanation + evidence]
3. **[Factor 3]**: [Explanation + evidence]
```
## SERP Features Analysis Template
```markdown
### Featured Snippet Analysis
**Current Snippet Holder**: [URL]
**Snippet Type**: [Paragraph/List/Table/Video]
**Snippet Content**:
> [Exact text/description of snippet]
**How to Win This Snippet**:
1. [Strategy based on current snippet]
2. [Content format recommendation]
3. [Structure recommendation]
---
### People Also Ask (PAA) Analysis
**Questions Appearing**:
1. [Question 1] → Currently answered by: [URL]
2. [Question 2] → Currently answered by: [URL]
3. [Question 3] → Currently answered by: [URL]
4. [Question 4] → Currently answered by: [URL]
**PAA Optimization Strategy**:
- Include these questions as H2/H3 headings
- Provide direct, concise answers (40-60 words)
- Use FAQ schema markup
---
### AI Overview Analysis
**AI Overview Present**: Yes/No
**AI Overview Type**: [Summary/List/Comparison/etc.]
**Sources Cited in AI Overview**:
1. [Source 1] - [Why cited]
2. [Source 2] - [Why cited]
3. [Source 3] - [Why cited]
**AI Overview Content Patterns**:
- Pulls definitions from: [source type]
- Lists information as: [format]
- Cites statistics from: [source type]
**How to Get Cited in AI Overview**:
1. [Specific recommendation]
2. [Specific recommendation]
3. [Specific recommendation]
```
## Search Intent Template
```markdown
### Search Intent Analysis
**Primary Intent**: [Informational/Commercial/Transactional/Navigational]
**Evidence**:
- SERP features suggest: [analysis]
- Top results are: [content types]
- User likely wants: [description]
**Intent Breakdown**:
- Informational signals: [X]%
- Commercial signals: [X]%
- Transactional signals: [X]%
**Content Format Implication**:
Based on intent, your content should:
- Format: [recommendation]
- Tone: [recommendation]
- CTA: [recommendation]
```
## Difficulty Assessment Template
```markdown
### Difficulty Assessment
**Overall Difficulty Score**: [X]/100
**Difficulty Factors**:
| Factor | Score | Weight | Impact |
|--------|-------|--------|--------|
| Top 10 Domain Authority | [avg] | 25% | [High/Med/Low] |
| Top 10 Page Authority | [avg] | 20% | [High/Med/Low] |
| Backlinks Required | [est.] | 20% | [High/Med/Low] |
| Content Quality Bar | [rating] | 20% | [High/Med/Low] |
| SERP Stability | [rating] | 15% | [High/Med/Low] |
**Realistic Assessment**:
- **New site (DA <20)**: [Can rank?] [Timeframe]
- **Growing site (DA 20-40)**: [Can rank?] [Timeframe]
- **Established site (DA 40+)**: [Can rank?] [Timeframe]
**Easier Alternatives**:
If too difficult, consider:
- [Alternative keyword 1] - Difficulty: [X]
- [Alternative keyword 2] - Difficulty: [X]
```
## Recommendations Template
```markdown
## SERP Analysis Summary & Recommendations
### Key Findings
1. [Most important finding]
2. [Second important finding]
3. [Third important finding]
### Content Requirements to Rank
To compete for "[keyword]", you need:
**Minimum Requirements**:
- [ ] Word count: [X]+ words
- [ ] Backlinks: [X]+ referring domains
- [ ] Domain Authority: [X]+
- [ ] Content format: [type]
- [ ] Include: [specific elements]
**Differentiators to Win**:
- [ ] [Unique angle from analysis]
- [ ] [Missing element in current results]
- [ ] [SERP feature opportunity]
### SERP Feature Strategy
| Feature | Winnable? | Strategy |
|---------|-----------|----------|
| Featured Snippet | Yes/No | [strategy] |
| PAA | Yes/No | [strategy] |
| AI Overview | Yes/No | [strategy] |
### Recommended Content Outline
Based on SERP analysis:
```
Title: [Optimized title]
H1: [Main heading]
[Introduction - address intent immediately]
H2: [Section based on PAA/top results]
H2: [Section based on PAA/top results]
H2: [Section based on PAA/top results]
[FAQ section for PAA optimization]
[Conclusion with CTA]
```
### Next Steps
1. [Immediate action]
2. [Content creation action]
3. [Optimization action]
```

85
.cursor/skills/serp-analysis/references/example-report.md Normal file
View file

@ -0,0 +1,85 @@
# SERP Analysis — Example Report
This is a complete example output showing the expected format for SERP analysis deliverables.
## Prompt
**User**: "Analyze the SERP for 'how to start a podcast'"
## Example Output
```markdown
# SERP Analysis: "how to start a podcast"
## SERP Overview
**Intent**: Informational (100%)
**Difficulty**: 72/100 (High)
**AI Overview**: Yes - comprehensive guide format
### SERP Features Present
| Feature | Present | Analysis |
|---------|---------|----------|
| AI Overview | ✅ | Lists steps, cites 3 sources |
| Featured Snippet | ✅ | Step-by-step list from Buzzsprout |
| People Also Ask | ✅ | 4 questions visible, expandable |
| Video Results | ✅ | 3 YouTube videos mid-page |
| Image Pack | ❌ | |
### Top 5 Results Analysis
| Pos | Domain | DA | Word Count | Format | Backlinks |
|-----|--------|-----|------------|--------|-----------|
| 1 | Buzzsprout | 71 | 8,500 | Ultimate Guide | 2,400 |
| 2 | Spotify | 93 | 3,200 | How-to Guide | 890 |
| 3 | Podcastinsights | 58 | 12,000 | Mega Guide | 1,800 |
| 4 | Transistor | 62 | 5,500 | Tutorial | 720 |
| 5 | HubSpot | 91 | 6,200 | Complete Guide | 1,100 |
### Why #1 Ranks First
Buzzsprout's guide succeeds because:
1. **Comprehensive** - Covers every step in detail
2. **Updated** - Current year in title, recent updates
3. **Structured** - Clear numbered steps (owns featured snippet)
4. **Authoritative** - Podcast hosting company (topical authority)
5. **Supporting content** - Links to detailed sub-guides
### Featured Snippet Opportunity
**Current format**: Ordered list (steps)
**Current holder**: Buzzsprout
**To win snippet**:
- Create cleaner, more scannable list format
- Keep steps to 8-10 items max
- Start each step with action verb
- Include "how to start a podcast" in H2
### AI Overview Analysis
**Sources cited**:
1. Buzzsprout - "Choose your podcast topic"
2. Spotify for Podcasters - "Record and edit"
3. Wikipedia - Definition of podcasting
**Pattern**: AI pulls step-by-step instructions from guides with clear structure
### Content Requirements
To rank on page 1:
- **Word count**: 5,000+ words minimum
- **Format**: Step-by-step ultimate guide
- **Backlinks**: 500+ from relevant domains
- **Updates**: Must show current year
- **Unique angle**: Equipment comparisons, cost breakdowns, or specific niche focus
### Recommended Strategy
Given high difficulty, consider:
1. Target long-tail: "how to start a podcast for free" (Difficulty: 45)
2. Target niche: "how to start a podcast about [topic]" (Difficulty: 30)
3. Create supporting video content for video carousel
4. Focus on PAA optimization for quick wins
```

404
.cursor/skills/serp-analysis/references/serp-feature-taxonomy.md Normal file
View file

@ -0,0 +1,404 @@
# SERP Feature Taxonomy
A comprehensive reference covering every SERP feature type, trigger conditions, optimization techniques, monitoring approaches, and AI Overview patterns. Use this to plan which SERP features to target and how to win them.
## Overview
Modern Search Engine Results Pages are far more than ten blue links. Google displays 20+ distinct feature types that can dramatically affect click-through rates, visibility, and traffic. Understanding which features appear for your target keywords -- and how to optimize for them -- is essential to any SEO or GEO strategy.
---
## SERP Feature Categories
SERP features fall into five broad categories:
| Category | Features | Controlled By |
|----------|---------|--------------|
| **Knowledge Features** | Knowledge Panel, AI Overview, Featured Snippet | Content quality + structured data |
| **Engagement Features** | People Also Ask, Related Searches, Things to Know | Content relevance + question coverage |
| **Rich Results** | FAQ, How-To, Review Stars, Recipe, Event, Product | Schema markup + content format |
| **Media Features** | Image Pack, Video Carousel, Web Stories | Media optimization + hosting platform |
| **Commerce Features** | Shopping Results, Local Pack, Ads | Merchant feeds + Google Business Profile + ad spend |
---
## Complete Feature Reference
### 1. Featured Snippet
**What it is:** An extracted answer displayed at Position 0 (above organic results) in a box.
**Sub-types:**
| Sub-type | Format | Typical Trigger | Example Query |
|---------|--------|----------------|---------------|
| Paragraph | 40-60 word text block | "What is", "Why is", definitions | "what is domain authority" |
| Ordered List | Numbered steps | "How to", process queries | "how to submit a sitemap" |
| Unordered List | Bulleted list | "Types of", "best", collections | "types of schema markup" |
| Table | Data in rows/columns | Comparison, data, pricing | "HTTP status codes list" |
| Video | YouTube clip with timestamp | "How to" with visual component | "how to use Google Search Console" |
**Optimization Playbook:**
1. **Identify snippet-eligible keywords** -- Check if a snippet already exists for your target keyword
2. **Match the existing format** -- If current snippet is a list, create a list; if paragraph, write a concise paragraph
3. **Place the answer immediately after the triggering heading** -- Use H2/H3 with the target question, then answer directly below
4. **Keep paragraph snippets to 40-60 words** -- Concise, complete answers win
5. **Use proper HTML structure** -- Ordered lists use `<ol>`, tables use `<table>`, not just visual formatting
6. **Include the target query in the heading** -- The H2/H3 should closely match the search query
7. **Provide context after the snippet answer** -- Elaborate below to demonstrate depth
**Monitoring:**
- Track featured snippet ownership weekly for target keywords
- Monitor snippet format changes (Google may switch from paragraph to list)
- Watch for snippet loss after content updates
---
### 2. People Also Ask (PAA)
**What it is:** An expandable accordion of related questions with brief answers pulled from web pages.
**Trigger conditions:**
- Almost all informational queries
- Many commercial investigation queries
- Questions beget more questions -- clicking one PAA reveals additional questions
**Optimization Playbook:**
1. **Mine PAA questions for content ideas** -- Each PAA question is a validated search query
2. **Answer PAA questions within your content** -- Use the exact question as an H2 or H3
3. **Keep answers concise (40-60 words)** -- PAA answers are short excerpts
4. **Use FAQ schema markup** -- Increases eligibility for PAA and FAQ rich results
5. **Create dedicated FAQ sections** -- Group 5-10 related questions at the end of articles
6. **Target the cascade** -- When users click one PAA, new questions appear; cover those too
**PAA Mining Workflow:**
1. Search your target keyword
2. Note all visible PAA questions (4 initially)
3. Click each one to reveal 2-4 more
4. Repeat to collect 15-20 related questions
5. Group questions by subtopic
6. Create content addressing each cluster
---
### 3. AI Overview (formerly SGE)
**What it is:** An AI-generated summary at the top of the SERP that synthesizes information from multiple sources, with cited links.
**Trigger conditions:**
- Informational queries (highest trigger rate)
- Some commercial investigation queries
- Question-format queries
- Definitional and explanatory queries
- Lower trigger rate for navigational and transactional queries
**AI Overview Formats:**
| Format | Description | Trigger Pattern |
|--------|-----------|----------------|
| Summary paragraph | Synthesized text answer | Definitional and explanatory queries |
| Bulleted list | Key points extracted from sources | "Benefits of", "reasons for", multi-factor answers |
| Step-by-step | Ordered process | "How to" queries |
| Comparison | Side-by-side analysis | "X vs Y", "difference between" |
| Table | Structured data comparison | Data comparison, pricing, specifications |
**Optimization Playbook:**
1. **Write clear, citable sentences** -- AI systems extract well-formed statements of fact
2. **Front-load key information** -- Place the most important answer in the first 1-2 sentences of each section
3. **Use structured data** -- Schema markup helps AI systems understand your content
4. **Establish topical authority** -- AI overviews prefer citing authoritative sources on a topic
5. **Include original data and statistics** -- Unique data points are highly citable
6. **Create comparison content** -- AI loves to cite well-structured comparison tables
7. **Update content regularly** -- Recency signals influence AI source selection
8. **Use clear section headings** -- AI systems use headings to understand content structure
**Source Citation Patterns:**
| What Gets Cited | Why | How to Optimize |
|----------------|-----|----------------|
| Definitions | AI needs authoritative definitions | Write clear, complete definitions in first paragraph |
| Statistics | AI cites specific data points | Include original research, cite sources |
| Step-by-step processes | AI extracts structured sequences | Use numbered lists with clear step headers |
| Comparison data | AI synthesizes multi-source comparisons | Create comparison tables with clear labels |
| Expert quotes | AI values authoritative voices | Include expert attribution with credentials |
---
### 4. Knowledge Panel
**What it is:** A large information box (typically right sidebar on desktop) showing structured entity information from Google's Knowledge Graph.
**Trigger conditions:**
- Brand/entity queries
- Notable person queries
- Place/organization queries
- Product/service entities
**Optimization Playbook:**
1. **Establish a Google Knowledge Graph entity** -- Ensure your brand exists as a recognized entity
2. **Claim and verify your Knowledge Panel** -- Use the "Claim this knowledge panel" option
3. **Maintain consistent NAP** -- Name, Address, Phone across all web properties
4. **Build Wikipedia presence** -- Knowledge Panels pull heavily from Wikipedia/Wikidata
5. **Use Organization schema markup** -- Help Google understand your entity
6. **Maintain active social profiles** -- Connected social accounts appear in Knowledge Panel
7. **Get featured in authoritative sources** -- Mentions in news, industry publications, and databases
---
### 5. Image Pack
**What it is:** A row of image thumbnails within organic results, linking to Google Images.
**Trigger conditions:**
- Visual queries ("what does X look like")
- Product queries
- Design/inspiration queries
- Some informational queries with visual components
**Optimization Playbook:**
1. **Use descriptive file names** -- `seo-audit-checklist-template.png` not `IMG_4523.png`
2. **Write complete alt text** -- Describe the image content and context accurately
3. **Optimize image file size** -- Compress without losing quality (WebP format preferred)
4. **Use original images** -- Stock photos rarely rank; original screenshots, diagrams, and photos perform better
5. **Add image structured data** -- ImageObject schema when applicable
6. **Place images near relevant text** -- Context from surrounding content helps ranking
7. **Create image sitemaps** -- Help Google discover all your images
8. **Use responsive images** -- Serve appropriate sizes for different devices
---
### 6. Video Carousel / Video Results
**What it is:** A horizontal carousel of video thumbnails, typically from YouTube, or individual video results with thumbnails in organic listings.
**Trigger conditions:**
- "How to" queries
- Tutorial and instructional queries
- Entertainment queries
- Review queries
- Any query where video content provides superior user experience
**Optimization Playbook:**
1. **Host on YouTube** -- YouTube videos dominate video carousels
2. **Optimize video title** -- Include target keyword naturally
3. **Write detailed descriptions** -- First 2-3 lines appear in search; include keywords and summary
4. **Add chapters/timestamps** -- Key Moments markup helps Google surface specific sections
5. **Create transcripts** -- Closed captions and transcripts provide indexable text
6. **Use VideoObject schema** -- On your own site pages embedding video
7. **Design compelling thumbnails** -- Higher CTR from search results
8. **Target video-intent keywords** -- "How to" and tutorial queries have highest video potential
---
### 7. Local Pack (Map Pack)
**What it is:** A map with 3 local business listings showing name, rating, address, and hours.
**Trigger conditions:**
- "[service] near me" queries
- "[service] in [location]" queries
- Queries with implicit local intent
- Service-based business queries
**Optimization Playbook:**
1. **Claim and optimize Google Business Profile** -- Complete every field
2. **Build consistent local citations** -- NAP consistency across directories
3. **Collect and respond to reviews** -- Volume and recency of reviews matter
4. **Add photos regularly** -- Active profiles rank higher
5. **Use local business schema** -- LocalBusiness structured data on website
6. **Create location-specific pages** -- If multiple locations, each needs its own page
7. **Build local backlinks** -- Local news, chambers of commerce, community sites
8. **Post Google Business updates** -- Regular posts signal activity
---
### 8. Shopping Results
**What it is:** Product listing ads and free product listings with images, prices, and store names.
**Trigger conditions:**
- Product purchase queries
- Product name queries
- "Buy [product]" queries
- Price comparison queries
**Optimization Playbook:**
1. **Submit product feed to Google Merchant Center** -- Required for shopping results
2. **Optimize product titles** -- Include key attributes (brand, color, size, model)
3. **Use high-quality product images** -- White background, multiple angles
4. **Implement Product schema** -- Structured data for price, availability, reviews
5. **Keep pricing accurate** -- Mismatches between feed and landing page cause disapproval
6. **Collect product reviews** -- Aggregate ratings appear in shopping results
7. **Optimize landing pages** -- Fast, mobile-friendly, clear purchase path
---
### 9. Sitelinks
**What it is:** Additional links beneath a search result that point to specific pages within the same domain.
**Sub-types:**
| Sub-type | Appearance | Trigger |
|---------|-----------|---------|
| Full sitelinks | 4-6 two-column links with descriptions | Brand/navigational queries for authoritative sites |
| Inline sitelinks | 2-4 single-line links | Semi-navigational queries |
| Search box sitelinks | Site-specific search box | Large, well-structured sites |
**Optimization Playbook:**
1. **Build clear site architecture** -- Logical hierarchy with descriptive navigation
2. **Use descriptive page titles** -- Each page should have a unique, clear title
3. **Implement breadcrumb schema** -- Helps Google understand site structure
4. **Create a comprehensive sitemap** -- XML sitemap submitted to Search Console
5. **Build internal links** -- Strong internal linking reinforces page importance
6. **Use SearchAction schema** -- Enables the sitelinks search box
---
### 10. Rich Results (Schema-Dependent)
These features depend on specific structured data markup:
| Rich Result | Schema Required | Content Type | Visual Impact |
|------------|----------------|-------------|--------------|
| FAQ | FAQPage | FAQ sections on any page | Expandable Q&A below listing |
| How-To | HowTo | Step-by-step instructions | Steps with optional images |
| Review Stars | Review / AggregateRating | Product/service reviews | Star rating in snippet |
| Recipe | Recipe | Food/cooking content | Image, cook time, calories |
| Event | Event | Event listings | Date, location, price |
| Job Posting | JobPosting | Job listings | Salary, location, company |
| Course | Course | Educational content | Provider, description, rating |
| Breadcrumb | BreadcrumbList | Any page with hierarchy | Path display replacing URL |
**General Rich Result Optimization:**
1. **Validate with Rich Results Test** -- Test every page before publishing
2. **Follow Google's structured data guidelines** -- No cloaking or misleading markup
3. **Keep markup accurate** -- Schema content must match visible page content
4. **Monitor in Search Console** -- Check Enhancement reports for errors
5. **Don't over-mark** -- Only add schema for content types genuinely on the page
---
### 11. Related Searches / People Also Search For
**What it is:** Related query suggestions at the bottom of the SERP ("Related searches") or shown after a user clicks a result and returns ("People also search for").
**Value for SEO:**
- Keyword discovery -- reveals semantically related queries
- Content gap identification -- topics users explore after your target query
- Topic cluster planning -- natural subtopics to cover
**How to Use:**
1. Mine related searches for content ideas and internal linking opportunities
2. Cover related topics within your content to demonstrate comprehensiveness
3. Use related search terms as H2/H3 headings in long-form content
---
### 12. "Things to Know" / Key Moments
**What it is:** Carousel cards showing key aspects of a topic, or key moments within a video.
**Trigger conditions:**
- Broad informational queries
- Multi-faceted topics
- Video content with chapters
**Optimization:**
- Cover multiple aspects of a topic comprehensively
- Use clear section headings that match common subtopics
- For video: add chapter markers with timestamps
---
## SERP Feature Prioritization Matrix
Not all SERP features deserve equal attention. Prioritize based on your content type and goals:
| SERP Feature | Traffic Impact | Effort to Win | Best For |
|-------------|---------------|--------------|---------|
| Featured Snippet | Very High | Medium | Informational content sites |
| AI Overview citation | High (growing) | Medium-High | Authority/expertise sites |
| People Also Ask | Medium-High | Low-Medium | FAQ-rich content |
| Video Carousel | High | High (video production) | Tutorial/how-to content |
| Local Pack | Very High (local) | Medium | Local businesses |
| Rich Results (FAQ) | Medium | Low | Any content with Q&A |
| Rich Results (Review) | Medium-High | Low-Medium | Product/service reviews |
| Image Pack | Medium | Low-Medium | Visual content creators |
| Shopping Results | Very High (ecommerce) | Medium | Product sellers |
| Knowledge Panel | Medium (brand) | High (long-term) | Established brands |
| Sitelinks | Low (brand already ranking) | Low (structural) | Large, structured sites |
---
## SERP Feature Monitoring Framework
### What to Track
| Metric | Frequency | Tool Category | Action Threshold |
|--------|-----------|--------------|-----------------|
| Featured snippet ownership | Weekly | ~~SEO tool | Lost snippet → investigate within 48 hours |
| AI Overview citation rate | Weekly | ~~AI monitor | Citation loss → review content freshness |
| PAA presence for target keywords | Monthly | ~~SEO tool | New PAA questions → create content |
| SERP feature composition changes | Monthly | ~~SEO tool | New feature appearing → optimize for it |
| Rich result errors | Weekly | Search Console | Any error → fix immediately |
| Local Pack ranking | Weekly | ~~SEO tool | Drop below position 3 → investigate |
### SERP Feature Change Analysis
When SERP features change for your target keywords, investigate:
| Change | Possible Causes | Recommended Action |
|--------|----------------|-------------------|
| Featured snippet disappeared | Google removed snippet for this query; competitor won it | Check if snippet still exists; create better snippet-targeted content |
| AI Overview appeared (new) | Google expanded AI Overviews to this query type | Optimize content for AI citation |
| AI Overview disappeared | Query type removed from AI Overview program | Refocus on traditional SERP features |
| Video carousel appeared | Google detected video intent for this query | Create video content for the keyword |
| Local Pack appeared | Google detected local intent shift | Consider local SEO if relevant |
| Shopping results appeared | Google detected commercial intent shift | Consider product markup or adjust content angle |
---
## SERP Feature Combination Patterns
Certain SERP feature combinations indicate specific opportunities:
| SERP Combination | What It Signals | Opportunity |
|-----------------|----------------|-------------|
| AI Overview + Featured Snippet | Google sees this as high-information query | Optimize for both -- structured content with clear answers |
| Video + PAA + Featured Snippet | Multi-format informational query | Create comprehensive guide with video and FAQ |
| Shopping + Ads + Reviews | Strong commercial intent | Product optimization, review content |
| Local Pack + Ads | Local commercial intent | Google Business Profile optimization |
| No features (just blue links) | Low-feature query (or very new topic) | Potential early-mover advantage for rich results |
| PAA only (no snippet) | Snippet opportunity not yet captured | Create snippet-optimized content |
---
## AI Overview vs. Traditional SERP Feature Strategy
The rise of AI Overviews changes how to prioritize SERP features:
| Scenario | Traditional Strategy | AI-Era Strategy |
|---------|---------------------|----------------|
| Informational query | Win featured snippet | Win AI Overview citation AND featured snippet |
| Comparison query | Create comparison content | Create structured comparison tables (AI prefers these) |
| Definition query | Write clear definition for snippet | Write authoritative, citable definition with evidence |
| How-to query | Create step-by-step list | Create steps with unique insights AI can synthesize |
| List query | Create comprehensive ranked list | Create list with original data/reasoning AI can cite |
### Key Difference
- **Traditional SERP features** reward **format optimization** (structure your content to match the feature)
- **AI Overviews** reward **authority and uniqueness** (be the source AI trusts for accurate, original information)
Optimizing for both requires content that is both structurally sound AND substantively authoritative.

397
.cursor/skills/technical-seo-checker/SKILL.md Normal file
View file

@ -0,0 +1,397 @@
---
name: technical-seo-checker
description: 'Technical SEO audit: Core Web Vitals, crawl, indexing, mobile, speed, architecture, redirects. 技术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 checking technical SEO health: site speed, Core Web Vitals, indexing, crawlability, robots.txt, sitemaps, or canonical tags."
argument-hint: "<URL or domain>"
allowed-tools: WebFetch
metadata:
author: aaron-he-zhu
version: "6.0.0"
geo-relevance: "low"
tags:
- seo
- technical-seo
- core-web-vitals
- page-speed
- crawlability
- indexability
- mobile-seo
- site-health
- lcp
- cls
- inp
- robots-txt
- xml-sitemap
- 技术SEO
- 网站速度
- テクニカルSEO
- 기술SEO
- seo-tecnico
triggers:
# EN-formal
- "technical SEO audit"
- "check page speed"
- "Core Web Vitals"
- "crawl issues"
- "site indexing problems"
- "canonical tag issues"
- "duplicate content"
- "mobile-friendly check"
- "site speed"
- "site health check"
# EN-casual
- "my site is slow"
- "Google can't crawl my site"
- "Google can't find my pages"
- "mobile issues"
- "indexing problems"
- "why is my site slow"
# EN-question
- "how do I fix my page speed"
- "why is my site not indexed"
- "how to improve Core Web Vitals"
- "why did my site disappear from Google"
# EN-competitor
- "PageSpeed Insights alternative"
- "GTmetrix alternative"
- "Sitebulb alternative"
# ZH-pro
- "技术SEO检查"
- "网站速度优化"
- "核心网页指标"
- "爬虫问题"
- "索引问题"
- "网站收录"
- "sitemap提交"
- "robots设置"
# ZH-casual
- "网站加载太慢"
- "网站太慢了"
- "Google找不到我的页面"
- "手机端有问题"
- "收录不了"
- "Google收录少"
# JA
- "テクニカルSEO"
- "サイト速度"
- "コアウェブバイタル"
- "クロール問題"
- "インデックス登録"
- "モバイル最適化"
# KO
- "기술 SEO"
- "사이트 속도"
- "코어 웹 바이탈"
- "크롤링 문제"
- "사이트 왜 이렇게 느려?"
# ES
- "auditoría SEO técnica"
- "velocidad del sitio"
- "problemas de indexación"
- "mi sitio no aparece en Google"
- "velocidad de carga"
# PT
- "auditoria SEO técnica"
- "meu site não aparece no Google"
- "velocidade de carregamento"
# Misspellings
- "techincal SEO"
- "core web vitalls"
---
# Technical SEO Checker
> **[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 comprehensive technical SEO audits to identify issues that may prevent search engines from properly crawling, indexing, and ranking your site.
**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.
- Launching a new website
- Diagnosing ranking drops
- Pre-migration SEO audits
- Regular technical health checks
- Identifying crawl and index issues
- Improving site performance
- Fixing Core Web Vitals issues
## What This Skill Does
1. **Crawlability Audit**: Checks robots.txt, sitemaps, crawl issues
2. **Indexability Review**: Analyzes index status and blockers
3. **Site Speed Analysis**: Evaluates Core Web Vitals and performance
4. **Mobile-Friendliness**: Checks mobile optimization
5. **Security Check**: Reviews HTTPS and security headers
6. **Structured Data Audit**: Validates schema markup
7. **URL Structure Analysis**: Reviews URL patterns and redirects
8. **International SEO**: Checks hreflang and localization
## 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).
### Full Technical Audit
```
Perform a technical SEO audit for [URL/domain]
```
### Specific Issue Check
```
Check Core Web Vitals for [URL]
```
```
Audit crawlability and indexability for [domain]
```
### Pre-Migration Audit
```
Technical SEO checklist for migrating [old domain] to [new domain]
```
## 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 ~~web crawler + ~~page speed tool + ~~CDN connected:**
Claude can automatically crawl the entire site structure via ~~web crawler, pull Core Web Vitals and performance metrics from ~~page speed tool, analyze caching headers from ~~CDN, and fetch mobile-friendliness data. This enables comprehensive automated technical audits.
**With manual data only:**
Ask the user to provide:
1. Site URL(s) to audit
2. PageSpeed Insights screenshots or reports
3. robots.txt file content
4. sitemap.xml URL or file
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 a technical SEO audit:
1. **Audit Crawlability**
```markdown
## Crawlability Analysis
### Robots.txt Review
**URL**: [domain]/robots.txt
**Status**: [Found/Not Found/Error]
**Current Content**:
```
[robots.txt content]
```
| Check | Status | Notes |
|-------|--------|-------|
| File exists | ✅/❌ | [notes] |
| Valid syntax | ✅/⚠️/❌ | [errors found] |
| Sitemap declared | ✅/❌ | [sitemap URL] |
| Important pages blocked | ✅/⚠️/❌ | [blocked paths] |
| Assets blocked | ✅/⚠️/❌ | [CSS/JS blocked?] |
| Correct user-agents | ✅/⚠️/❌ | [notes] |
**Issues Found**:
- [Issue 1]
- [Issue 2]
**Recommended robots.txt**:
```
User-agent: *
Allow: /
Disallow: /admin/
Disallow: /private/
Sitemap: https://example.com/sitemap.xml
```
---
### XML Sitemap Review
**Sitemap URL**: [URL]
**Status**: [Found/Not Found/Error]
| Check | Status | Notes |
|-------|--------|-------|
| Sitemap exists | ✅/❌ | [notes] |
| Valid XML format | ✅/⚠️/❌ | [errors] |
| In robots.txt | ✅/❌ | [notes] |
| Submitted to ~~search console | ✅/⚠️/❌ | [notes] |
| URLs count | [X] | [appropriate?] |
| Only indexable URLs | ✅/⚠️/❌ | [notes] |
| Includes priority | ✅/⚠️ | [notes] |
| Includes lastmod | ✅/⚠️ | [accurate?] |
**Issues Found**:
- [Issue 1]
---
### Crawl Budget Analysis
| Factor | Status | Impact |
|--------|--------|--------|
| Crawl errors | [X] errors | [Low/Med/High] |
| Duplicate content | [X] pages | [Low/Med/High] |
| Thin content | [X] pages | [Low/Med/High] |
| Redirect chains | [X] found | [Low/Med/High] |
| Orphan pages | [X] found | [Low/Med/High] |
**Crawlability Score**: [X]/10
```
2. **Audit Indexability**
```markdown
## Indexability Analysis
### Index Status Overview
| Metric | Count | Notes |
|--------|-------|-------|
| Pages in sitemap | [X] | |
| Pages indexed | [X] | [source: site: search] |
| Index coverage ratio | [X]% | [good if >90%] |
### Index Blockers Check
| Blocker Type | Found | Pages Affected |
|--------------|-------|----------------|
| noindex meta tag | [X] | [list or "none"] |
| noindex X-Robots | [X] | [list or "none"] |
| Robots.txt blocked | [X] | [list or "none"] |
| Canonical to other | [X] | [list or "none"] |
| 4xx/5xx errors | [X] | [list or "none"] |
| Redirect loops | [X] | [list or "none"] |
### Canonical Tags Audit
| Check | Status | Notes |
|-------|--------|-------|
| Canonicals present | ✅/⚠️/❌ | [X]% of pages |
| Self-referencing | ✅/⚠️/❌ | [notes] |
| Consistent (HTTP/HTTPS) | ✅/⚠️/❌ | [notes] |
| Consistent (www/non-www) | ✅/⚠️/❌ | [notes] |
| No conflicting signals | ✅/⚠️/❌ | [notes] |
### Duplicate Content Issues
| Issue Type | Count | Examples |
|------------|-------|----------|
| Exact duplicates | [X] | [URLs] |
| Near duplicates | [X] | [URLs] |
| Parameter duplicates | [X] | [URLs] |
| WWW/non-WWW | [X] | [notes] |
| HTTP/HTTPS | [X] | [notes] |
**Indexability Score**: [X]/10
```
3. **Audit Site Speed & Core Web Vitals** — CWV metrics (LCP/FID/CLS/INP), additional performance metrics (TTFB/FCP/Speed Index/TBT), resource loading breakdown, optimization recommendations
> **Reference**: See [references/technical-audit-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/references/technical-audit-templates.md) for the performance analysis template (Step 3).
4. **Audit Mobile-Friendliness** — Mobile-friendly test, responsive design check, mobile-first indexing verification
> **Reference**: See [references/technical-audit-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/references/technical-audit-templates.md) for the mobile optimization template (Step 4).
5. **Audit Security & HTTPS** — SSL certificate, HTTPS enforcement, mixed content, HSTS, security headers (CSP, X-Frame-Options, etc.)
> **Reference**: See [references/technical-audit-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/references/technical-audit-templates.md) for the security analysis template (Step 5).
6. **Audit URL Structure** — URL patterns, issues (dynamic params, session IDs, uppercase), redirect analysis (chains, loops, 302s)
> **Reference**: See [references/technical-audit-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/references/technical-audit-templates.md) for the URL structure template (Step 6).
7. **Audit Structured Data** — Schema markup validation, missing schema opportunities. CORE-EEAT alignment: maps to O05.
> **Reference**: See [references/technical-audit-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/references/technical-audit-templates.md) for the structured data template (Step 7).
8. **Audit International SEO (if applicable)** — Hreflang implementation, language/region targeting
> **Reference**: See [references/technical-audit-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/references/technical-audit-templates.md) for the international SEO template (Step 8).
9. **Generate Technical Audit Summary** — Overall health score with visual breakdown, critical/high/medium issues, quick wins, implementation roadmap (weeks 1-4+), monitoring recommendations
> **Reference**: See [references/technical-audit-templates.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/references/technical-audit-templates.md) for the audit summary template (Step 9).
## Validation Checkpoints
### Input Validation
- [ ] Site URL or domain clearly specified
- [ ] Access to technical data (robots.txt, sitemap, or crawl results)
- [ ] Performance metrics available (via ~~page speed tool or screenshots)
### Output Validation
- [ ] Every recommendation cites specific data points (not generic advice)
- [ ] All issues include affected URLs or page counts
- [ ] Performance metrics include actual numbers with units (seconds, KB, etc.)
- [ ] Source of each data point clearly stated (~~web crawler data, ~~page speed tool, user-provided, or estimated)
## Example
> **Reference**: See [references/technical-audit-example.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/references/technical-audit-example.md) for a full worked example (cloudhosting.com technical audit) and the comprehensive technical SEO checklist.
## Tips for Success
1. **Prioritize by impact** - Fix critical issues first
2. **Monitor continuously** - Use ~~search console alerts
3. **Test changes** - Verify fixes work before deploying widely
4. **Document everything** - Track changes for troubleshooting
5. **Regular audits** - Schedule quarterly technical reviews
> **Technical reference**: For issue severity framework, prioritization matrix, and Core Web Vitals optimization quick reference, see [references/http-status-codes.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/references/http-status-codes.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/technical-seo-checker/YYYY-MM-DD-<topic>.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
- [robots.txt Reference](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/references/robots-txt-reference.md) — Syntax guide, templates, common configurations
- [HTTP Status Codes](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/references/http-status-codes.md) — SEO impact of each status code, redirect best practices
- [Technical Audit Templates](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/references/technical-audit-templates.md) — Detailed output templates for steps 3-9 (CWV, mobile, security, URL structure, structured data, international, audit summary)
- [Technical Audit Example & Checklist](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/references/technical-audit-example.md) — Full worked example and comprehensive technical SEO checklist
## 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) — continue from infrastructure issues into page-level remediation.

705
.cursor/skills/technical-seo-checker/references/http-status-codes.md Normal file
View file

@ -0,0 +1,705 @@
# HTTP Status Codes for SEO
SEO-relevant HTTP status codes, their implications, and how to diagnose and fix issues.
## Status Code Categories
- **2xx**: Success - Request succeeded
- **3xx**: Redirection - Further action needed
- **4xx**: Client Error - Problem with the request
- **5xx**: Server Error - Server failed to fulfill request
---
## 2xx Success Codes
### 200 OK
**What it means**: Request succeeded, content returned normally.
**SEO impact**: Positive - page is accessible and indexable.
**When to use**: Standard response for all working pages.
**When it's a problem**: When different URLs return 200 for same content (should use 301 redirect).
---
### 204 No Content
**What it means**: Request succeeded but no content to return.
**SEO impact**: Neutral - rarely used for pages meant to be indexed.
**Common use**: API responses, AJAX requests.
---
## 3xx Redirection Codes
### 301 Moved Permanently
**What it means**: Resource permanently moved to new URL. All link equity transfers.
**SEO impact**: Positive when used correctly - passes 90-99% of link equity.
**When to use**:
- Permanently changing URL structure
- Consolidating duplicate content
- Moving to new domain
- Changing HTTP to HTTPS
- Changing www to non-www (or vice versa)
**Example header**:
```
HTTP/1.1 301 Moved Permanently
Location: https://example.com/new-page
```
**Common mistakes**:
- Using 302 instead of 301 for permanent changes
- Creating redirect chains (A→B→C)
- Redirecting to irrelevant pages
- Not redirecting HTTP to HTTPS
**How to implement**:
- **.htaccess** (Apache): `Redirect 301 /old-page /new-page`
- **nginx**: `rewrite ^/old-page$ /new-page permanent;`
- **Server-side**: Set Location header with 301 status
---
### 302 Found (Temporary Redirect)
**What it means**: Resource temporarily at different URL. Original URL should still be used.
**SEO impact**: Neutral to negative - does NOT pass full link equity. Search engines keep indexing original URL.
**When to use**:
- A/B testing
- Temporary promotions
- Maintenance redirects
- Geolocation redirects (sometimes)
**When NOT to use**: Permanent URL changes (use 301).
**Warning**: Google may treat long-standing 302s as 301s, but better to be explicit.
---
### 303 See Other
**What it means**: Response can be found at another URI using GET.
**SEO impact**: Minimal - rarely used for SEO purposes.
**Common use**: After form submissions, redirect to results page.
---
### 307 Temporary Redirect
**What it means**: Temporary redirect that preserves request method (POST stays POST).
**SEO impact**: Similar to 302 - temporary, doesn't pass full link equity.
**Difference from 302**: Guarantees request method won't change (more precise than 302).
**When to use**: Temporary redirects where HTTP method preservation matters.
---
### 308 Permanent Redirect
**What it means**: Permanent redirect that preserves request method.
**SEO impact**: Similar to 301 - passes link equity.
**Difference from 301**: Guarantees request method won't change (POST stays POST).
**When to use**: Permanent redirects where method preservation matters (rare for SEO).
---
### Redirect Chain Issues
**Problem**: Multiple redirects before reaching final destination.
**Example chain**:
```
http://example.com/page
→ https://example.com/page (redirect 1)
→ https://www.example.com/page (redirect 2)
→ https://www.example.com/new-page (redirect 3)
```
**SEO impact**:
- Slows page load (each redirect = new HTTP request)
- Dilutes link equity with each hop
- Wastes crawl budget
- Poor user experience
**How to fix**: Redirect directly from original URL to final destination.
**Fixed version**:
```
http://example.com/page
→ https://www.example.com/new-page (single redirect)
```
---
### Redirect Loops
**Problem**: Redirects create infinite loop.
**Example**:
```
/page-a → /page-b
/page-b → /page-a
```
**SEO impact**: Severe - page completely inaccessible.
**Symptoms**:
- Browser shows "Too many redirects" error
- Page never loads
- Search Console shows crawl errors
**How to diagnose**:
1. Use redirect checker tool
2. Check .htaccess or nginx config for conflicting rules
3. Review server-side redirect logic
**How to fix**:
1. Identify conflicting redirect rules
2. Remove or correct the loop
3. Test thoroughly
4. Request recrawl in Search Console
---
## 4xx Client Error Codes
### 404 Not Found
**What it means**: Requested resource doesn't exist.
**SEO impact**: Neutral to negative depending on context.
**When 404s are OK**:
- Legitimately deleted pages with no equivalent
- Never-existed URLs from typos
- Temporary content that expired (old promotions)
- Intentionally removed low-quality content
**When 404s are problems**:
- Pages that should exist are returning 404
- Previously working pages now broken
- Important pages missing from navigation
- High-traffic pages deleted without redirect
**How to fix**:
1. **If content moved**: Set up 301 redirect to new location
2. **If content deleted**: Either keep 404 or redirect to relevant category
3. **If never existed**: Leave as 404
4. **If important**: Restore the page
**Monitoring 404s**:
- Check Search Console → Coverage → Not found (404)
- Review referrer data to see what's linking to 404s
- Fix high-value 404s first (most traffic/backlinks)
**Soft 404s** (BAD):
- Page returns 200 but shows "not found" message
- Search engines may keep page indexed
- Creates duplicate content issues
- Fix: Return proper 404 status code
---
### 410 Gone
**What it means**: Resource permanently deleted, never coming back.
**SEO impact**: Stronger signal than 404 - tells search engines not to return.
**When to use**:
- Discontinued products
- Expired promotions
- Permanently removed content
- Outdated information
**Difference from 404**:
- 404: "Not found" (might exist at another URL)
- 410: "Gone forever" (don't look for it)
**When to use 410 vs 301**:
- Use 410: No equivalent replacement exists
- Use 301: Relevant alternative exists
**How search engines respond**:
- Faster de-indexing than 404
- Stop crawling sooner
- Better for crawl budget
---
### 403 Forbidden
**What it means**: Server understood request but refuses to authorize it.
**SEO impact**: Negative - page inaccessible and won't be indexed.
**Common causes**:
- Permission restrictions
- IP blocking
- .htaccess restrictions
- File permissions (chmod)
- Authentication required
**When it's intentional**:
- Admin areas
- Member-only content
- Geographic restrictions
**When it's a problem**:
- Public pages returning 403
- Search engine bots blocked
- Accidental permission changes
**How to diagnose**:
1. Check .htaccess for IP restrictions
2. Verify file permissions (should be 644 for files, 755 for directories)
3. Check server-level access rules
4. Test with different IPs/user-agents
**How to fix**:
1. Adjust file permissions: `chmod 644 filename`
2. Remove blocking rules from .htaccess
3. Whitelist search engine bots
4. Review server firewall rules
---
### 401 Unauthorized
**What it means**: Authentication required but not provided or failed.
**SEO impact**: Negative - page won't be indexed.
**Common causes**:
- Password-protected pages
- HTTP Basic Authentication
- Expired sessions
- Missing credentials
**When it's intentional**: Member areas, staging sites, admin panels.
**How to handle for SEO**:
- Don't password-protect pages you want indexed
- Use separate staging domain with 401
- For members-only content, show teaser with meta robots noindex
---
### 429 Too Many Requests
**What it means**: User/bot sent too many requests in given timeframe (rate limiting).
**SEO impact**: Negative if search engines can't crawl.
**Common causes**:
- Aggressive crawling
- DDoS protection triggered
- API rate limits
- Server throttling
**How to handle**:
1. Check Googlebot isn't being rate-limited (use Search Console)
2. Whitelist verified search engine bots
3. Configure rate limits appropriately
4. Monitor crawl rate in Search Console
---
## 5xx Server Error Codes
### 500 Internal Server Error
**What it means**: Generic server error, something went wrong.
**SEO impact**: Very negative if persistent - prevents indexing and ranking.
**Common causes**:
- PHP/code errors
- Database connection issues
- .htaccess syntax errors
- Resource limits exceeded
- Plugin/theme conflicts (WordPress)
**How to diagnose**:
1. Check server error logs
2. Review recent code/config changes
3. Test locally or on staging
4. Disable plugins one by one (if CMS)
5. Check .htaccess syntax
**How to fix**:
1. Review error logs for specific error
2. Roll back recent changes
3. Fix code errors
4. Increase resource limits if needed
5. Test thoroughly before re-deploying
**Monitoring**: Set up alerts for 500 errors (sudden spike = problem).
---
### 502 Bad Gateway
**What it means**: Server received invalid response from upstream server.
**SEO impact**: Negative if persistent - prevents crawling/indexing.
**Common causes**:
- Proxy/load balancer issues
- Upstream server down
- Timeout issues
- Firewall blocking
**Common scenarios**:
- CDN can't reach origin server
- Application server crashed
- Database server unresponsive
**How to fix**:
1. Check upstream server status
2. Verify firewall rules
3. Check timeout settings
4. Restart proxy/load balancer if needed
5. Review CDN configuration
---
### 503 Service Unavailable
**What it means**: Server temporarily unable to handle request.
**SEO impact**: Neutral if truly temporary with Retry-After header. Negative if prolonged.
**Common causes**:
- Maintenance mode
- Server overload
- Database down
- Resource exhaustion
**Proper use for maintenance**:
```
HTTP/1.1 503 Service Unavailable
Retry-After: 3600
```
**Best practices for maintenance**:
1. Use 503 (not 404 or 500)
2. Include Retry-After header
3. Keep maintenance brief (<24 hours)
4. Schedule during low-traffic times
5. Inform users with clear message
**How search engines handle 503**:
- Short-term (hours): Will retry, no ranking impact
- Long-term (days+): May drop rankings, de-index pages
---
### 504 Gateway Timeout
**What it means**: Server didn't receive timely response from upstream server.
**SEO impact**: Negative - prevents crawling.
**Common causes**:
- Slow database queries
- External API timeouts
- Insufficient server resources
- Network issues
**How to fix**:
1. Optimize slow queries
2. Increase timeout limits
3. Add caching
4. Scale server resources
5. Review external dependencies
---
## Status Code Decision Flowchart
### Content Moved Permanently?
→ YES: Use **301 redirect**
→ NO: Continue
### Content Moved Temporarily?
→ YES: Use **302 redirect**
→ NO: Continue
### Content Deleted with No Replacement?
→ YES: Use **404** (or **410** if permanently gone)
→ NO: Continue
### Content Exists at This URL?
→ YES: Use **200 OK**
→ NO: Use **404**
### Need Authentication?
→ YES: Use **401**
→ NO: Continue
### Access Forbidden?
→ YES: Use **403**
→ NO: Continue
### Server Error?
→ YES: Use **500**, **502**, **503**, or **504** depending on cause
→ NO: Use **200 OK**
---
## Diagnosing Status Code Issues
### Tools
**Browser DevTools**:
1. Open DevTools (F12)
2. Go to Network tab
3. Reload page
4. Check status code in first request
**cURL command**:
```bash
curl -I https://example.com/page
```
**Online checkers**:
- httpstatus.io
- redirect-checker.org
- websiteplanet.com/webtools/redirects/
**Google Search Console**:
- Coverage report → Error/Excluded sections
- URL Inspection tool → Check specific URLs
---
### Common Diagnostic Scenarios
### "Page Won't Index"
**Check**:
1. Status code (should be 200)
2. Redirects (shouldn't redirect away)
3. 4xx/5xx errors
4. robots.txt blocking
5. noindex meta tag
### "Page Disappeared from Results"
**Check**:
1. Returns 404/410/5xx
2. Redirecting elsewhere (301/302)
3. Changed to 403/401
4. Server timing out (504)
### "Traffic Dropped After Migration"
**Check**:
1. Old URLs return 404 (should be 301)
2. Redirect chains (should be direct)
3. Redirect loops
4. Wrong redirect type (302 vs 301)
5. Incorrect redirect targets
---
## Status Codes and Crawl Budget
### Impact on Crawl Budget
**Efficient (minimal impact)**:
- 200 OK
- 301 redirects (if minimal chains)
- 410 Gone (removes from crawl queue)
**Moderate impact**:
- 302 redirects (search engine may keep checking)
- 404 errors (search engines periodically recheck)
- Redirect chains (multiple requests per URL)
**High impact (wasteful)**:
- 5xx errors (search engines retry frequently)
- Redirect loops (waste crawl budget)
- Soft 404s (search engine confused, keeps crawling)
- 429 rate limiting (prevents efficient crawling)
---
## SEO Status Code Best Practices
### For Migrations
- [ ] Use 301 redirects for all permanently moved pages
- [ ] Redirect directly to final destination (no chains)
- [ ] Test all redirects before launching
- [ ] Keep redirects in place for at least 1 year
- [ ] Monitor 404 errors in Search Console post-launch
- [ ] Map 1:1 where possible (old URL → equivalent new URL)
### For Deleted Content
- [ ] Use 301 if relevant replacement exists
- [ ] Use 404 if no replacement and might return
- [ ] Use 410 if permanently gone, never returning
- [ ] Don't redirect to irrelevant pages (creates soft 404)
- [ ] Create custom 404 page with search and navigation
### For Maintenance
- [ ] Use 503 with Retry-After header
- [ ] Keep maintenance window brief (<24 hours)
- [ ] Create user-friendly maintenance page
- [ ] Inform users of expected downtime
- [ ] Monitor Search Console for crawl issues
### For Performance
- [ ] Minimize redirect chains
- [ ] Fix redirect loops immediately
- [ ] Monitor 5xx errors closely
- [ ] Set up alerts for sudden status code changes
- [ ] Optimize to reduce 504 timeouts
---
## Status Code Monitoring
### Key Metrics to Track
**In Search Console**:
- Crawl errors by type
- Server errors (5xx) trend
- Not found (404) trend
- Redirect errors
**In analytics**:
- 404 page views
- Entry pages with high exit rate (might be errors)
- Sudden traffic drops (could indicate status code issues)
**Server logs**:
- Status code distribution
- 5xx error frequency
- Unusual patterns
### Setting Up Alerts
**Alert on**:
- Sudden increase in 5xx errors
- Increase in 404 errors
- New redirect chains
- Crawl error spikes in Search Console
**Tools**:
- Google Search Console email alerts
- Server monitoring (UptimeRobot, Pingdom)
- Log analysis tools
- Custom scripts for log monitoring
---
## Quick Reference Table
| Code | Name | SEO Impact | Use When | Passes Link Equity? |
|------|------|------------|----------|---------------------|
| 200 | OK | ✅ Positive | Page works normally | N/A (original URL) |
| 301 | Moved Permanently | ✅ Positive | Permanent URL change | ✅ Yes (~90-99%) |
| 302 | Found | ⚠️ Neutral | Temporary redirect | ❌ No |
| 307 | Temporary Redirect | ⚠️ Neutral | Temporary (method preserved) | ❌ No |
| 308 | Permanent Redirect | ✅ Positive | Permanent (method preserved) | ✅ Yes |
| 404 | Not Found | ⚠️ Neutral | Content doesn't exist | N/A |
| 410 | Gone | ⚠️ Neutral | Permanent deletion | N/A |
| 403 | Forbidden | ❌ Negative | Access denied | N/A |
| 401 | Unauthorized | ❌ Negative | Auth required | N/A |
| 500 | Internal Server Error | ❌ Negative | Server error | N/A |
| 502 | Bad Gateway | ❌ Negative | Upstream error | N/A |
| 503 | Service Unavailable | ⚠️ Neutral | Temporary downtime | N/A |
| 504 | Gateway Timeout | ❌ Negative | Timeout error | N/A |
---
## Status Code Testing Checklist
Before launching site changes:
- [ ] Test all redirects return correct status codes
- [ ] Verify no redirect chains exist
- [ ] Check no redirect loops present
- [ ] Confirm important pages return 200
- [ ] Ensure deleted pages return 404/410 (not 200)
- [ ] Verify 301s point to correct destinations
- [ ] Test with multiple user-agents
- [ ] Check status codes in Search Console
- [ ] Monitor server logs for unusual patterns
- [ ] Set up alerts for error spikes
---
## Technical SEO Severity Framework
### Issue Classification
| Severity | Impact Description | Examples | Response Time |
|----------|-------------------|---------|---------------|
| **Critical** | Prevents indexation or causes site-wide issues | Robots.txt blocking site, noindex on key pages, site-wide 500 errors | Same day |
| **High** | Significantly impacts rankings or user experience | Slow page speed, missing hreflang, duplicate content, redirect chains | Within 1 week |
| **Medium** | Affects specific pages or has moderate impact | Missing schema, suboptimal canonicals, thin content pages | Within 1 month |
| **Low** | Minor optimization opportunities | Image compression, minor CLS issues, non-essential schema missing | Next quarter |
### Technical Debt Prioritization Matrix
| Factor | Weight | Assessment |
|--------|--------|-----------|
| Pages affected | 30% | Site-wide > Section > Single page |
| Revenue impact | 25% | Revenue pages > Blog > Utility pages |
| Fix difficulty | 20% | Config change < Template change < Code rewrite |
| Competitive impact | 15% | Competitors passing you > parity > you ahead |
| Crawl budget waste | 10% | High waste > Moderate > Minimal |
## Core Web Vitals Optimization Quick Reference
### LCP (Largest Contentful Paint) Optimization
| Root Cause | Detection | Fix |
|-----------|-----------|-----|
| Large hero image | PageSpeed Insights | Serve WebP, resize to container, add loading="lazy" |
| Render-blocking CSS/JS | DevTools Coverage | Defer non-critical, inline critical CSS |
| Slow server response | TTFB >800ms | CDN, server-side caching, upgrade hosting |
| Third-party scripts | DevTools Network | Defer/async, use facade pattern |
### CLS (Cumulative Layout Shift) Optimization
| Root Cause | Detection | Fix |
|-----------|-----------|-----|
| Images without dimensions | DevTools | Add explicit width/height attributes |
| Ads/embeds without reserved space | Visual inspection | Set min-height on containers |
| Web fonts causing FOUT | DevTools | font-display: swap + preload fonts |
| Dynamic content injection | Visual inspection | Reserve space with CSS |
### INP (Interaction to Next Paint) Optimization
| Root Cause | Detection | Fix |
|-----------|-----------|-----|
| Long JavaScript tasks | DevTools Performance | Break into smaller tasks, use requestIdleCallback |
| Heavy event handlers | DevTools | Debounce/throttle, use passive listeners |
| Main thread blocking | DevTools | Web workers for heavy computation |

717
.cursor/skills/technical-seo-checker/references/robots-txt-reference.md Normal file
View file

@ -0,0 +1,717 @@
# Robots.txt Reference Guide
Complete reference for creating, testing, and troubleshooting robots.txt files.
## Syntax Guide
### Basic Structure
```
User-agent: [bot name]
Disallow: [path to block]
Allow: [path to allow]
Sitemap: [sitemap URL]
Crawl-delay: [seconds]
```
---
## Core Directives
### User-agent
Specifies which bot the rules apply to.
**Syntax**: `User-agent: [bot-name]`
**Common user-agents**:
```
User-agent: * # All bots
User-agent: Googlebot # Google's crawler
User-agent: Bingbot # Bing's crawler
User-agent: GPTBot # OpenAI's crawler
User-agent: CCBot # Common Crawl bot
User-agent: anthropic-ai # Anthropic's crawler
User-agent: PerplexityBot # Perplexity AI crawler
User-agent: ClaudeBot # Claude's web crawler
```
**Multiple user-agents**: Group rules by leaving no blank lines between user-agent declarations.
```
User-agent: Googlebot
User-agent: Bingbot
Disallow: /admin/
```
---
### Disallow
Blocks bots from crawling specified paths.
**Syntax**: `Disallow: [path]`
**Examples**:
```
Disallow: / # Block entire site
Disallow: /admin/ # Block admin directory
Disallow: /private # Block private directory (and subdirectories)
Disallow: /*.pdf$ # Block all PDF files
Disallow: /*? # Block all URLs with parameters
Disallow: # Allow everything (empty disallow)
```
**Path matching**:
- `/` at end = block directory and all subdirectories
- Without `/` at end = block all paths starting with string
- `*` = wildcard, matches any sequence
- `$` = end of URL
---
### Allow
Explicitly allows crawling (overrides Disallow).
**Syntax**: `Allow: [path]`
**Common use**: Allow specific subdirectories within blocked parent.
```
User-agent: *
Disallow: /admin/
Allow: /admin/public/
```
**Note**: Allow is not standard but supported by Google, Bing, and most major crawlers.
---
### Sitemap
Specifies location of XML sitemap.
**Syntax**: `Sitemap: [absolute URL]`
**Examples**:
```
Sitemap: https://example.com/sitemap.xml
Sitemap: https://example.com/sitemap_index.xml
Sitemap: https://example.com/blog/sitemap.xml
```
**Best practices**:
- Use absolute URLs (not relative)
- Can include multiple Sitemap directives
- Place at end of file
- Submit same sitemap(s) to Google Search Console
---
### Crawl-delay
Adds delay between requests (seconds).
**Syntax**: `Crawl-delay: [seconds]`
**Example**:
```
User-agent: *
Crawl-delay: 10
```
**Warning**: Not supported by Googlebot (use Search Console rate limiting instead). Supported by Bing, Yandex, and others.
---
## Common Configurations
### 1. Allow All Bots (Default)
```
User-agent: *
Disallow:
Sitemap: https://example.com/sitemap.xml
```
Use when you want all bots to crawl entire site.
---
### 2. Block All Bots
```
User-agent: *
Disallow: /
```
Use for development/staging sites or private content.
---
### 3. Block Specific Directories
```
User-agent: *
Disallow: /admin/
Disallow: /private/
Disallow: /temp/
Disallow: /cgi-bin/
Sitemap: https://example.com/sitemap.xml
```
Standard configuration blocking admin and utility directories.
---
### 4. Block All AI Crawlers
```
# Block OpenAI
User-agent: GPTBot
Disallow: /
# Block Anthropic
User-agent: anthropic-ai
User-agent: ClaudeBot
Disallow: /
# Block Common Crawl
User-agent: CCBot
Disallow: /
# Block Perplexity
User-agent: PerplexityBot
Disallow: /
# Block Google-Extended (Bard training)
User-agent: Google-Extended
Disallow: /
# Allow search engines
User-agent: Googlebot
Disallow:
User-agent: Bingbot
Disallow:
Sitemap: https://example.com/sitemap.xml
```
Use when you want search indexing but not AI training.
---
### 5. Allow Search Engines, Block Everything Else
```
# Block all by default
User-agent: *
Disallow: /
# Allow Google
User-agent: Googlebot
Disallow:
# Allow Bing
User-agent: Bingbot
Disallow:
# Allow DuckDuckGo
User-agent: DuckDuckBot
Disallow:
Sitemap: https://example.com/sitemap.xml
```
---
### 6. Block URL Parameters
```
User-agent: *
Disallow: /*? # Block all URLs with parameters
Allow: /? # Allow homepage with parameters
Sitemap: https://example.com/sitemap.xml
```
Prevents duplicate content from parameter variations.
---
### 7. Block File Types
```
User-agent: *
Disallow: /*.pdf$
Disallow: /*.doc$
Disallow: /*.xls$
Disallow: /*.zip$
Sitemap: https://example.com/sitemap.xml
```
---
### 8. E-commerce Configuration
```
User-agent: *
# Block search/filter pages
Disallow: /*?q=
Disallow: /*?sort=
Disallow: /*?filter=
# Block account pages
Disallow: /account/
Disallow: /cart/
Disallow: /checkout/
# Block admin
Disallow: /admin/
# Allow product pages
Allow: /products/
Sitemap: https://example.com/sitemap.xml
```
---
### 9. WordPress Configuration
```
User-agent: *
# WordPress core
Disallow: /wp-admin/
Allow: /wp-admin/admin-ajax.php
# WordPress directories
Disallow: /wp-includes/
Disallow: /wp-content/plugins/
Disallow: /wp-content/themes/
# Allow uploads
Allow: /wp-content/uploads/
# Block parameter pages
Disallow: /?s=
Disallow: /feed/
Disallow: /trackback/
Sitemap: https://example.com/sitemap_index.xml
```
---
### 10. Shopify Configuration
```
User-agent: *
# Block admin and account
Disallow: /admin
Disallow: /account
Disallow: /cart
Disallow: /checkout
# Block search
Disallow: /search
# Block collections with filters
Disallow: /collections/*+*
Disallow: /collections/*?*
Sitemap: https://example.com/sitemap.xml
```
---
## Platform-Specific Templates
### Wix
```
User-agent: *
Disallow: /_api/
Disallow: /_partials/
Sitemap: https://example.com/sitemap.xml
```
### Squarespace
```
User-agent: *
Disallow: /config/
Disallow: /search
Sitemap: https://example.com/sitemap.xml
```
### Webflow
```
User-agent: *
Allow: /
Sitemap: https://example.com/sitemap.xml
```
### Drupal
```
User-agent: *
Disallow: /admin/
Disallow: /user/
Disallow: /node/add/
Disallow: /?q=
Sitemap: https://example.com/sitemap.xml
```
---
## Testing and Validation
### Google Search Console Robots.txt Tester
1. Go to: Search Console → Settings → robots.txt
2. View current robots.txt
3. Test specific URLs
4. See which user-agents are affected
### Manual Testing
Test URL pattern: `https://example.com/robots.txt`
Check file is:
- Accessible (returns 200 status)
- Plain text format
- UTF-8 encoded
- Located at root domain
- No more than 500KB (Google limit)
### Common Testing Scenarios
Test these URLs in tester:
- Homepage: `/`
- Product page: `/products/example`
- Admin page: `/admin/`
- Parameter page: `/search?q=test`
- File: `/document.pdf`
---
## Common Mistakes and Fixes
### Mistake 1: Blocking CSS/JS Files
**Wrong**:
```
User-agent: *
Disallow: /css/
Disallow: /js/
```
**Why it's wrong**: Google needs CSS/JS to render pages properly.
**Fix**:
```
User-agent: *
Allow: /css/
Allow: /js/
```
---
### Mistake 2: Using Relative URLs for Sitemap
**Wrong**:
```
Sitemap: /sitemap.xml
```
**Fix**:
```
Sitemap: https://example.com/sitemap.xml
```
---
### Mistake 3: Spaces in Directives
**Wrong**:
```
User-agent : Googlebot
Disallow : /admin/
```
**Fix** (no spaces before colons):
```
User-agent: Googlebot
Disallow: /admin/
```
---
### Mistake 4: Forgetting Trailing Slash
**Intention**: Block /admin directory
**Wrong**:
```
Disallow: /admin
```
**Result**: Also blocks /admin-panel, /administrator, etc.
**Fix**:
```
Disallow: /admin/
```
---
### Mistake 5: Blocking Entire Site Accidentally
**Wrong**:
```
User-agent: *
Disallow: /
Allow: /blog/
```
**Why it's wrong**: Many bots don't support Allow directive.
**Fix**: Use noindex meta tags for pages you don't want indexed, not robots.txt.
---
### Mistake 6: Not Blocking Development Environments
**Wrong**: No robots.txt on staging.example.com
**Result**: Staging site gets indexed.
**Fix**:
```
User-agent: *
Disallow: /
```
On all non-production environments.
---
### Mistake 7: Case Sensitivity Errors
**Note**: Directives are case-insensitive, but paths are case-sensitive.
**Example**:
```
Disallow: /Admin/ # Blocks /Admin/ but not /admin/
```
**Fix**: Block both if needed:
```
Disallow: /admin/
Disallow: /Admin/
```
---
## Advanced Patterns
### Wildcard Examples
```
# Block all PDFs
Disallow: /*.pdf$
# Block all URLs with parameters
Disallow: /*?
# Block all URLs ending in .php
Disallow: /*.php$
# Block all admin paths regardless of location
Disallow: /*/admin/
```
### Multiple Sitemaps
```
Sitemap: https://example.com/sitemap-pages.xml
Sitemap: https://example.com/sitemap-posts.xml
Sitemap: https://example.com/sitemap-products.xml
```
### Bot-Specific Rules
```
# Aggressive bot - slow it down
User-agent: BadBot
Crawl-delay: 60
Disallow: /
# Good bots - full access
User-agent: Googlebot
User-agent: Bingbot
Disallow:
# Default for others
User-agent: *
Crawl-delay: 10
Disallow: /admin/
```
---
## Robots.txt vs Meta Robots vs X-Robots-Tag
### When to use each:
**Robots.txt**:
- Block crawling of entire directories
- Reduce crawl budget waste
- Block parameter variations
- Does NOT prevent indexing if page is linked from elsewhere
**Meta robots tag**:
- Prevent specific pages from being indexed
- Control snippet display
- Control following links
- Example: `<meta name="robots" content="noindex,follow">`
**X-Robots-Tag HTTP header**:
- Control non-HTML files (PDFs, images)
- Server-level control
- Example: `X-Robots-Tag: noindex`
**Important**: If you don't want a page indexed, use noindex (meta tag or header), NOT robots.txt.
---
## Monitoring and Maintenance
### Regular Checks
**Monthly**:
- [ ] Verify robots.txt is accessible
- [ ] Check Search Console for blocked URLs
- [ ] Review crawl stats for blocked resources
**Quarterly**:
- [ ] Audit blocked paths - still relevant?
- [ ] Check for new admin/private sections to block
- [ ] Review AI crawler landscape (new bots?)
**After site changes**:
- [ ] Update robots.txt if URL structure changed
- [ ] Test new sections (should they be blocked?)
- [ ] Verify sitemaps still referenced
### Search Console Monitoring
Check these reports:
- **Coverage** → Excluded by robots.txt
- **Settings** → Crawl stats
- **URL Inspection** → Test specific URLs
---
## Robots.txt Checklist
Before deploying:
- [ ] File is named exactly `robots.txt` (lowercase)
- [ ] Located at root domain (`example.com/robots.txt`)
- [ ] Plain text format (not HTML or PDF)
- [ ] UTF-8 encoding
- [ ] No HTML tags in file
- [ ] All paths start with `/`
- [ ] Sitemap URLs are absolute
- [ ] No spaces before colons
- [ ] Tested in Search Console robots.txt tester
- [ ] Not blocking important CSS/JS/images
- [ ] Not blocking content you want indexed
- [ ] Trailing slashes used correctly for directories
- [ ] Wildcard patterns tested
- [ ] File size under 500KB
---
## Emergency Fixes
### Accidentally Blocked Entire Site
**Symptom**: All pages blocked in Search Console
**Fix**:
1. Edit robots.txt to:
```
User-agent: *
Disallow:
Sitemap: https://example.com/sitemap.xml
```
2. Test in Search Console
3. Request urgent recrawl for key pages
4. Monitor Coverage report for recovery
**Recovery time**: 1-7 days
---
### Blocked CSS/JS Files
**Symptom**: "Blocked by robots.txt" in Mobile-Friendly Test
**Fix**:
1. Add Allow directives:
```
User-agent: *
Allow: /css/
Allow: /js/
Allow: /wp-content/uploads/
```
2. Test in robots.txt tester
3. Request re-render in URL Inspection tool
---
### Staging Site Indexed
**Symptom**: staging.example.com appears in search results
**Fix**:
1. Add to staging robots.txt:
```
User-agent: *
Disallow: /
```
2. Add noindex meta tag to all staging pages
3. Remove staging URLs in Search Console (Removals tool)
---
## Resources and Tools
**Testing**:
- Google Search Console robots.txt tester
- Bing Webmaster Tools robots.txt analyzer
- Technical SEO browser extensions
**Validation**:
- https://www.google.com/webmasters/tools/robots-testing-tool
- https://en.ryte.com/free-tools/robots-txt/
- https://technicalseo.com/tools/robots-txt/
**Documentation**:
- Google: https://developers.google.com/search/docs/crawling-indexing/robots/intro
- Bing: https://www.bing.com/webmasters/help/robots-txt-validation
- Robots.txt spec: https://www.robotstxt.org/

169
.cursor/skills/technical-seo-checker/references/technical-audit-example.md Normal file
View file

@ -0,0 +1,169 @@
# Technical SEO Checker — Worked Example & Checklist
Referenced from [SKILL.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/SKILL.md).
---
## Worked Example
**User**: "Check the technical SEO of cloudhosting.com"
**Output**:
```markdown
# Technical SEO Audit Report
**Domain**: cloudhosting.com
**Audit Date**: 2024-09-15
**Pages Analyzed**: 312
## Crawlability Analysis
### Robots.txt Review
**URL**: cloudhosting.com/robots.txt
**Status**: Found
| Check | Status | Notes |
|-------|--------|-------|
| File exists | ✅ | 200 response |
| Valid syntax | ⚠️ | Wildcard pattern `Disallow: /*?` too aggressive — blocks faceted pages |
| Sitemap declared | ❌ | No Sitemap directive in robots.txt |
| Important pages blocked | ⚠️ | /pricing/ blocked by `Disallow: /pricing` rule |
| Assets blocked | ✅ | CSS/JS accessible |
**Issues Found**:
- Sitemap URL not declared in robots.txt
- `/pricing/` inadvertently blocked — high-value commercial page
### XML Sitemap Review
**Sitemap URL**: cloudhosting.com/sitemap.xml
**Status**: Found (not referenced in robots.txt)
| Check | Status | Notes |
|-------|--------|-------|
| Sitemap exists | ✅ | Valid XML, 287 URLs |
| Only indexable URLs | ❌ | 23 noindex URLs included |
| Includes lastmod | ⚠️ | All dates set to 2023-01-01 — not accurate |
**Crawlability Score**: 5/10
## Performance Analysis
### Core Web Vitals
| Metric | Mobile | Desktop | Target | Status |
|--------|--------|---------|--------|--------|
| LCP (Largest Contentful Paint) | 4.8s | 2.1s | <2.5s | ❌ Mobile / ✅ Desktop |
| FID (First Input Delay) | 45ms | 12ms | <100ms | ✅ / ✅ |
| CLS (Cumulative Layout Shift) | 0.24 | 0.08 | <0.1 | ❌ Mobile / ✅ Desktop |
| INP (Interaction to Next Paint) | 380ms | 140ms | <200ms | ❌ Mobile / ✅ Desktop |
### Additional Performance Metrics
| Metric | Value | Status |
|--------|-------|--------|
| Time to First Byte (TTFB) | 1,240ms | ❌ |
| Page Size | 3.8MB | ❌ |
| Requests | 94 | ⚠️ |
**LCP Issues**:
- Uncompressed hero image (2.4MB PNG): Convert to WebP, est. save 1.9MB
- No CDN detected: TTFB 1,240ms from origin server
**CLS Issues**:
- Ad banner at top of page injects without reserved height (0.18 shift contribution)
**Performance Score**: 3/10
## Security Analysis
### HTTPS Status
| Check | Status | Notes |
|-------|--------|-------|
| SSL certificate valid | ✅ | Expires: 2025-03-22 |
| HTTPS enforced | ⚠️ | http://cloudhosting.com returns 200 instead of 301 redirect |
| Mixed content | ❌ | 7 images loaded over HTTP on /features/ page |
| HSTS enabled | ❌ | Header not present |
**Security Score**: 5/10
## Structured Data Analysis
### Schema Markup Found
| Schema Type | Pages | Valid | Errors |
|-------------|-------|-------|--------|
| Organization | 1 (homepage) | ✅ | None |
| Article | 0 | — | Missing on 48 blog posts |
| Product | 0 | — | Missing on 5 plan pages |
| FAQ | 0 | — | Missing on 12 pages with FAQ content |
**Structured Data Score**: 3/10
## Overall Technical Health: 42/100
```
Score Breakdown:
█████░░░░░ Crawlability: 5/10
██████░░░░ Indexability: 6/10
███░░░░░░░ Performance: 3/10
██████░░░░ Mobile: 6/10
█████░░░░░ Security: 5/10
██████░░░░ URL Structure: 6/10
███░░░░░░░ Structured Data: 3/10
```
## Priority Issues
### 🔴 Critical (Fix Immediately)
1. **Mobile LCP 4.8s (target <2.5s)** — Compress hero image to WebP (est. save 1.9MB) and implement a CDN to reduce TTFB from 1,240ms to <400ms.
### 🟡 Important (Fix Soon)
2. **HTTP not redirecting to HTTPS** — Add 301 redirect from http:// to https:// and enable HSTS header. 7 mixed-content images on /features/ need URL updates.
### 🟢 Minor (Optimize)
3. **No Article/FAQ schema on blog posts** — Add Article schema to 48 blog posts and FAQ schema to 12 FAQ pages for rich result eligibility.
```
---
## Technical SEO Checklist
```markdown
### Crawlability
- [ ] robots.txt is valid and not blocking important content
- [ ] XML sitemap exists and is submitted to ~~search console
- [ ] No crawl errors in ~~search console
- [ ] No redirect chains or loops
### Indexability
- [ ] Important pages are indexable
- [ ] Canonical tags are correct
- [ ] No duplicate content issues
- [ ] Pagination is handled correctly
### Performance
- [ ] Core Web Vitals pass
- [ ] Page speed under 3 seconds
- [ ] Images are optimized
- [ ] JS/CSS are minified
### Mobile
- [ ] Mobile-friendly test passes
- [ ] Viewport is configured
- [ ] Touch elements are properly sized
### Security
- [ ] HTTPS is enforced
- [ ] SSL certificate is valid
- [ ] No mixed content
- [ ] Security headers present
### Structure
- [ ] URLs are clean and descriptive
- [ ] Site architecture is logical
- [ ] Internal linking is strong
```

311
.cursor/skills/technical-seo-checker/references/technical-audit-templates.md Normal file
View file

@ -0,0 +1,311 @@
# Technical SEO Checker — Output Templates
Detailed output templates for technical-seo-checker steps 3-9. Referenced from [SKILL.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/technical-seo-checker/SKILL.md).
---
## Step 3: Audit Site Speed & Core Web Vitals
```markdown
## Performance Analysis
### Core Web Vitals
| Metric | Mobile | Desktop | Target | Status |
|--------|--------|---------|--------|--------|
| LCP (Largest Contentful Paint) | [X]s | [X]s | <2.5s | ✅/⚠️/❌ |
| FID (First Input Delay) | [X]ms | [X]ms | <100ms | ✅/⚠️/❌ |
| CLS (Cumulative Layout Shift) | [X] | [X] | <0.1 | ✅/⚠️/❌ |
| INP (Interaction to Next Paint) | [X]ms | [X]ms | <200ms | ✅/⚠️/❌ |
### Additional Performance Metrics
| Metric | Value | Status |
|--------|-------|--------|
| Time to First Byte (TTFB) | [X]ms | ✅/⚠️/❌ |
| First Contentful Paint (FCP) | [X]s | ✅/⚠️/❌ |
| Speed Index | [X] | ✅/⚠️/❌ |
| Total Blocking Time | [X]ms | ✅/⚠️/❌ |
| Page Size | [X]MB | ✅/⚠️/❌ |
| Requests | [X] | ✅/⚠️/❌ |
### Performance Issues
**LCP Issues**:
- [Issue]: [Impact] - [Solution]
- [Issue]: [Impact] - [Solution]
**CLS Issues**:
- [Issue]: [Impact] - [Solution]
**Resource Loading**:
| Resource Type | Count | Size | Issues |
|---------------|-------|------|--------|
| Images | [X] | [X]MB | [notes] |
| JavaScript | [X] | [X]MB | [notes] |
| CSS | [X] | [X]KB | [notes] |
| Fonts | [X] | [X]KB | [notes] |
### Optimization Recommendations
**High Impact**:
1. [Recommendation] - Est. improvement: [X]s
2. [Recommendation] - Est. improvement: [X]s
**Medium Impact**:
1. [Recommendation]
2. [Recommendation]
**Performance Score**: [X]/10
```
---
## Step 4: Audit Mobile-Friendliness
```markdown
## Mobile Optimization Analysis
### Mobile-Friendly Test
| Check | Status | Notes |
|-------|--------|-------|
| Mobile-friendly overall | ✅/❌ | [notes] |
| Viewport configured | ✅/❌ | [viewport tag] |
| Text readable | ✅/⚠️/❌ | Font size: [X]px |
| Tap targets sized | ✅/⚠️/❌ | [notes] |
| Content fits viewport | ✅/❌ | [notes] |
| No horizontal scroll | ✅/❌ | [notes] |
### Responsive Design Check
| Element | Desktop | Mobile | Issues |
|---------|---------|--------|--------|
| Navigation | [status] | [status] | [notes] |
| Images | [status] | [status] | [notes] |
| Forms | [status] | [status] | [notes] |
| Tables | [status] | [status] | [notes] |
| Videos | [status] | [status] | [notes] |
### Mobile-First Indexing
| Check | Status | Notes |
|-------|--------|-------|
| Mobile version has all content | ✅/⚠️/❌ | [notes] |
| Mobile has same structured data | ✅/⚠️/❌ | [notes] |
| Mobile has same meta tags | ✅/⚠️/❌ | [notes] |
| Mobile images have alt text | ✅/⚠️/❌ | [notes] |
**Mobile Score**: [X]/10
```
---
## Step 5: Audit Security & HTTPS
```markdown
## Security Analysis
### HTTPS Status
| Check | Status | Notes |
|-------|--------|-------|
| SSL certificate valid | ✅/❌ | Expires: [date] |
| HTTPS enforced | ✅/❌ | [redirects properly?] |
| Mixed content | ✅/⚠️/❌ | [X] issues |
| HSTS enabled | ✅/⚠️ | [notes] |
| Certificate chain | ✅/⚠️/❌ | [notes] |
### Security Headers
| Header | Present | Value | Recommended |
|--------|---------|-------|-------------|
| Content-Security-Policy | ✅/❌ | [value] | [recommendation] |
| X-Frame-Options | ✅/❌ | [value] | DENY or SAMEORIGIN |
| X-Content-Type-Options | ✅/❌ | [value] | nosniff |
| X-XSS-Protection | ✅/❌ | [value] | 1; mode=block |
| Referrer-Policy | ✅/❌ | [value] | [recommendation] |
**Security Score**: [X]/10
```
---
## Step 6: Audit URL Structure
```markdown
## URL Structure Analysis
### URL Pattern Review
| Check | Status | Notes |
|-------|--------|-------|
| HTTPS URLs | ✅/⚠️/❌ | [X]% HTTPS |
| Lowercase URLs | ✅/⚠️/❌ | [notes] |
| No special characters | ✅/⚠️/❌ | [notes] |
| Readable/descriptive | ✅/⚠️/❌ | [notes] |
| Appropriate length | ✅/⚠️/❌ | Avg: [X] chars |
| Keywords in URLs | ✅/⚠️/❌ | [notes] |
| Consistent structure | ✅/⚠️/❌ | [notes] |
### URL Issues Found
| Issue Type | Count | Examples |
|------------|-------|----------|
| Dynamic parameters | [X] | [URLs] |
| Session IDs in URLs | [X] | [URLs] |
| Uppercase characters | [X] | [URLs] |
| Special characters | [X] | [URLs] |
| Very long URLs (>100) | [X] | [URLs] |
### Redirect Analysis
| Check | Status | Notes |
|-------|--------|-------|
| Redirect chains | [X] found | [max chain length] |
| Redirect loops | [X] found | [URLs] |
| 302 → 301 needed | [X] found | [URLs] |
| Broken redirects | [X] found | [URLs] |
**URL Score**: [X]/10
```
---
## Step 7: Audit Structured Data
> **CORE-EEAT alignment**: Schema markup quality maps to O05 (Schema Markup) in the CORE-EEAT benchmark. 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 content quality audit.
```markdown
## Structured Data Analysis
### Schema Markup Found
| Schema Type | Pages | Valid | Errors |
|-------------|-------|-------|--------|
| [Type 1] | [X] | ✅/❌ | [errors] |
| [Type 2] | [X] | ✅/❌ | [errors] |
### Validation Results
**Errors**:
- [Error 1]: [affected pages] - [solution]
- [Error 2]: [affected pages] - [solution]
**Warnings**:
- [Warning 1]: [notes]
### Missing Schema Opportunities
| Page Type | Current Schema | Recommended |
|-----------|----------------|-------------|
| Blog posts | [current] | Article + FAQ |
| Products | [current] | Product + Review |
| Homepage | [current] | Organization |
**Structured Data Score**: [X]/10
```
---
## Step 8: Audit International SEO (if applicable)
```markdown
## International SEO Analysis
### Hreflang Implementation
| Check | Status | Notes |
|-------|--------|-------|
| Hreflang tags present | ✅/❌ | [notes] |
| Self-referencing | ✅/⚠️/❌ | [notes] |
| Return tags present | ✅/⚠️/❌ | [notes] |
| Valid language codes | ✅/⚠️/❌ | [notes] |
| x-default tag | ✅/⚠️ | [notes] |
### Language/Region Targeting
| Language | URL | Hreflang | Status |
|----------|-----|----------|--------|
| [en-US] | [URL] | [tag] | ✅/⚠️/❌ |
| [es-ES] | [URL] | [tag] | ✅/⚠️/❌ |
**International Score**: [X]/10
```
---
## Step 9: Generate Technical Audit Summary
```markdown
# Technical SEO Audit Report
**Domain**: [domain]
**Audit Date**: [date]
**Pages Analyzed**: [X]
## Overall Technical Health: [X]/100
```
Score Breakdown:
████████░░ Crawlability: 8/10
███████░░░ Indexability: 7/10
█████░░░░░ Performance: 5/10
████████░░ Mobile: 8/10
█████████░ Security: 9/10
██████░░░░ URL Structure: 6/10
█████░░░░░ Structured Data: 5/10
```
## Critical Issues (Fix Immediately)
1. **[Issue]**: [Impact]
- Affected: [pages/scope]
- Solution: [specific fix]
- Priority: 🔴 Critical
2. **[Issue]**: [Impact]
- Affected: [pages/scope]
- Solution: [specific fix]
- Priority: 🔴 Critical
## High Priority Issues
1. **[Issue]**: [Solution]
2. **[Issue]**: [Solution]
## Medium Priority Issues
1. **[Issue]**: [Solution]
2. **[Issue]**: [Solution]
## Quick Wins
These can be fixed quickly for immediate improvement:
1. [Quick fix 1]
2. [Quick fix 2]
3. [Quick fix 3]
## Implementation Roadmap
### Week 1: Critical Fixes
- [ ] [Task 1]
- [ ] [Task 2]
### Week 2-3: High Priority
- [ ] [Task 1]
- [ ] [Task 2]
### Week 4+: Optimization
- [ ] [Task 1]
- [ ] [Task 2]
## Monitoring Recommendations
Set up alerts for:
- Core Web Vitals drops
- Crawl error spikes
- Index coverage changes
- Security issues
```

10
.cursor/skills/ugc-brief/.skillfish.json Normal file
View file

@ -0,0 +1,10 @@
{
"version": 2,
"name": "ugc-brief",
"owner": "walkerhi11",
"repo": "mediabuy-plugins",
"path": ".claude/skills/ugc-brief",
"branch": "main",
"sha": "98bdcf49353c883665432be36f81b94aee6f188d",
"source": "manual"
}

260
.cursor/skills/ugc-brief/SKILL.md Normal file
View file

@ -0,0 +1,260 @@
---
name: ugc-brief
description: Create briefs for UGC creators including product info, hook requirements, talking points, and authenticity guidelines. Use when working with UGC creators, preparing creator packages, or scaling content production with external talent.
---
# UGC Brief Generator
Create creator-ready briefs for authentic UGC content.
## Process
### Step 1: Define Product & Key Messages
**Product Overview:**
- Product name and category
- Key benefits (top 3)
- Unique mechanism
- Price point/offer
- Target customer
**Core Messages:**
- Primary claim/promise
- Secondary proof points
- Must-mention features
- Compliance requirements
### Step 2: Specify Hook Requirements
**Hook Type Needed:**
- [ ] Greed (savings, value)
- [ ] Relevancy (timely, seasonal)
- [ ] Emotion (reaction, story)
- [ ] Demographic (call out audience)
- [ ] Cliffhanger (curiosity gap)
**Hook Examples to Reference:**
- "[Winning hook from brand]"
- "[Competitor hook working well]"
**Hook Don'ts:**
- No scripted openings
- No "Hey guys" generic starts
- No product name in first 3 seconds
### Step 3: List Talking Points
**Required Elements:**
1. Problem acknowledgment
2. Discovery story or proof
3. Product solution
4. Specific benefit/result
5. Call to action
**Proof Points to Include:**
- [ ] Personal result/experience
- [ ] Specific numbers if applicable
- [ ] Before/after if relevant
- [ ] Endorsement of mechanism
**Optional Elements:**
- Unboxing moment
- Application/usage demo
- Comparison to alternative
- Response to objection
### Step 4: Include Authenticity Guidelines
**DO:**
- Speak naturally, not scripted
- Use your own words
- Show genuine reactions
- Include imperfections
- Film in natural lighting
- Use phone (not professional camera)
- Look at camera like talking to friend
**DON'T:**
- Read from script (bullet points OK)
- Over-polish or heavily edit
- Use professional lighting/studio
- Add music or effects
- Sound like a commercial
- Fake enthusiasm
- Use brand jargon unnaturally
**Authenticity Test:**
"Would you actually send this video to a friend recommending the product?"
### Step 5: Output Creator Brief
```
## UGC BRIEF: [Product Name]
### CREATOR DETAILS
- Creator name: [If assigned]
- Platform: [TikTok/IG/FB]
- Format: [Vertical 9:16]
- Length: [15-60 seconds]
- Deliverable: [Raw footage / Edited]
---
### PRODUCT INFO
**Product:** [Name]
**What it does:** [One sentence]
**Key benefit:** [Primary promise]
**Price/Offer:** [Current deal]
**Website:** [URL]
**Unique selling point:**
[What makes this different]
---
### YOUR ANGLE
**You are:** [Avatar description]
- Age range: [X-X]
- Situation: [Context]
- Problem you had: [Pain point]
- How you found product: [Discovery]
---
### HOOK (First 3 seconds)
**Type:** [Hook category]
**Examples to inspire (don't copy exactly):**
- "[Example hook 1]"
- "[Example hook 2]"
**Requirements:**
- Stop the scroll immediately
- Don't mention product name yet
- Create curiosity or relate to problem
---
### TALKING POINTS (Middle)
Cover these in your own words:
1. **Problem:** [Describe the struggle]
- Your words: _______________
2. **Discovery:** [How you found it]
- Your words: _______________
3. **Experience:** [What happened when you tried it]
- Your words: _______________
4. **Proof:** [Specific result or benefit]
- Your words: _______________
**Must mention:**
- [ ] [Required element 1]
- [ ] [Required element 2]
**Nice to include:**
- [ ] [Optional element]
---
### CALL TO ACTION (Last 5 seconds)
**Say something like:**
- "Link is in my bio"
- "Tap the link to try it"
- "I put the link below"
**Add urgency if natural:**
- "They're running a sale right now"
- "I heard they sell out fast"
---
### FILMING GUIDELINES
**Setting:**
- [ ] Natural environment (home, outside)
- [ ] Good natural lighting (face a window)
- [ ] Clean but not perfect background
- [ ] Vertical format (phone camera)
**Style:**
- [ ] Talking to a friend, not performing
- [ ] Eye contact with camera
- [ ] Natural energy (match your personality)
- [ ] OK to have mistakes/restarts in raw footage
**Technical:**
- [ ] Film in 1080p or 4K
- [ ] Clear audio (quiet space)
- [ ] Multiple takes encouraged
- [ ] Send raw footage (we'll edit)
---
### DO NOT
- Script word-for-word
- Use professional equipment
- Add filters or effects
- Sound like an infomercial
- Make claims we can't substantiate
- Mention competitors by name
---
### DELIVERABLES
**Send:**
- [ ] Raw video file(s)
- [ ] Multiple takes if available
- [ ] Any B-roll of product
**Format:** [MP4/MOV]
**Due:** [Date]
**Send to:** [Email/Platform]
---
### PAYMENT & RIGHTS
**Compensation:** [Amount/Terms]
**Usage rights:** [Perpetual/Limited]
**Exclusivity:** [Yes/No/Terms]
---
### REFERENCE VIDEOS
[Links to examples of style wanted]
### QUESTIONS?
Contact: [Name/Email]
```
## UGC Best Practices (LeadsIcon/Kamal)
**Why Native Beats Polish:**
- Audiences smell BS instantly
- Platform algorithms favor native content
- Trust comes from relatability
- Perfect = ad = skip
**Creator Selection:**
- Match target demographic
- Natural on-camera presence
- Actually would use product
- Not over-produced style
**Volume Strategy:**
- Multiple creators same brief
- Each brings unique delivery
- Mix and match best clips
- Keep testing new faces
Source: LeadsIcon, Kamal FounderAds

100
skills-lock.json
View file

@ -1,11 +1,111 @@
{
"version": 1,
"skills": {
"alert-manager": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "f96aa6f7d8dd982a866ac090c1770e39cd0a01c63c9bc315895d3c210f80b393"
},
"backlink-analyzer": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "25556853b9cd6434bbb1bcf6cd6794d84c05214c1f8564a85db46f73e5c438e7"
},
"competitor-analysis": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "ecee4d821c68ae0cdce088da9f688f2a1ed724ddad01854cceaac9e85109c6f1"
},
"content-gap-analysis": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "9979051baf6210013ba7c6df0229081c93882efe5791dfae9c0ede93349c2537"
},
"content-quality-auditor": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "02de7d19e7b4611bdb2f10a386ce7a6b9799a47bce3e964bd33b8f9f3e4599f4"
},
"content-refresher": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "282ee22b8cac4bc4ad369f9bbf581cef9770a5dfabadf0581f36c674973261ce"
},
"domain-authority-auditor": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "e97547ac36ea8e59a65bdfdda25b8d130cb7f5e2cf13dac56fd01f24e74718a5"
},
"entity-optimizer": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "58704efa3ce530dc504e5942e740339ec03d4f3f2419f9f6812c4eee73accb73"
},
"geo-content-optimizer": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "ddd61f32254be1303ce4b7be5d507c932de4af53489a0ebb1309bf61de99018c"
},
"internal-linking-optimizer": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "10c54a570eacd569bde0ff55d0cb9ecb89658ba92afceb264da59dd7f600801c"
},
"keyword-research": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "921a7e6e7ab45d1dfb4534d4ca445a94a95e7e01022b5f171690da2e40caf55f"
},
"memory-management": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "df7a35f2479812e4bf452e2c2bbb942c9ef163f8d7bd281a0e38765aa33ecff7"
},
"meta-tags-optimizer": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "4d88aa5adc17c1802f21c04162bbab6bd8c5965c35362a502ee6ccab76777a54"
},
"on-page-seo-auditor": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "12714ad503f3493a977f101d26d2b5f43991ef41f148332c22c9b29e9b7c9f23"
},
"performance-reporter": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "fb6454815439e5b9993d18aae71a92928ef36814f550a16f9ce8a8d8ac6901d3"
},
"rank-tracker": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "2d4c9a44056713d946481031cc00b3113b6055af6f4bea0cfd8dcb8a9d5abbf9"
},
"schema-markup-generator": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "8587b6f64de8274895fb97b94089ca48685e55694828e67f4a2cf2937d5d9e5d"
},
"seo-content-writer": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "0ac426e7f412aca94496e8dcc599ac11f15e04043605968a7c146293ecac54ca"
},
"serp-analysis": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "e3d18f4f1514bb1537e8429f7fe011c9f3e666e5a3dcbc1623d9f83e47de59a2"
},
"shadcn": {
"source": "shadcn/ui",
"sourceType": "github",
"computedHash": "b1cc1defe03f0e8f78652b7d20e4d4e6421babc2b45835d4f361afe684dc47a2"
},
"technical-seo-checker": {
"source": "aaron-he-zhu/seo-geo-claude-skills",
"sourceType": "github",
"computedHash": "a9bf73872ed4ec682f7d91d0a6528bdc91806571d3c47b3c8046eee5106dc791"
},
"vercel-react-best-practices": {
"source": "vercel-labs/agent-skills",
"sourceType": "github",

7
surfsense_backend/.env.example
View file

@ -197,6 +197,13 @@ LLAMA_CLOUD_API_KEY=llx-nnn
# AZURE_DI_ENDPOINT=https://your-resource.cognitiveservices.azure.com/
# AZURE_DI_KEY=your-key
# Daytona Sandbox (isolated code execution)
# DAYTONA_SANDBOX_ENABLED=FALSE
# DAYTONA_API_KEY=your-daytona-api-key
# DAYTONA_API_URL=https://app.daytona.io/api
# DAYTONA_TARGET=us
# DAYTONA_SNAPSHOT_ID=
# OPTIONAL: Add these for LangSmith Observability
LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com

2
surfsense_backend/app/agents/new_chat/chat_deepagent.py
View file

@ -439,6 +439,7 @@ async def create_surfsense_deep_agent(
SurfSenseFilesystemMiddleware(
search_space_id=search_space_id,
created_by_id=user_id,
thread_id=thread_id,
),
create_summarization_middleware(llm, StateBackend),
PatchToolCallsMiddleware(),
@ -466,6 +467,7 @@ async def create_surfsense_deep_agent(
SurfSenseFilesystemMiddleware(
search_space_id=search_space_id,
created_by_id=user_id,
thread_id=thread_id,
),
SubAgentMiddleware(backend=StateBackend, subagents=[general_purpose_spec]),
create_summarization_middleware(llm, StateBackend),

156
surfsense_backend/app/agents/new_chat/middleware/filesystem.py
View file

@ -7,10 +7,12 @@ This middleware customizes prompts and persists write/edit operations for
from __future__ import annotations
import asyncio
import logging
import re
from datetime import UTC, datetime
from typing import Annotated, Any
from daytona.common.errors import DaytonaError
from deepagents import FilesystemMiddleware
from deepagents.backends.protocol import EditResult, WriteResult
from deepagents.backends.utils import validate_path
@ -23,6 +25,11 @@ from langchain_core.tools import BaseTool, StructuredTool
from langgraph.types import Command
from sqlalchemy import delete, select
from app.agents.new_chat.sandbox import (
_evict_sandbox_cache,
get_or_create_sandbox,
is_sandbox_enabled,
)
from app.db import Chunk, Document, DocumentType, Folder, shielded_async_session
from app.indexing_pipeline.document_chunker import chunk_text
from app.utils.document_converters import (
@ -31,6 +38,8 @@ from app.utils.document_converters import (
generate_unique_identifier_hash,
)
logger = logging.getLogger(__name__)
# =============================================================================
# System Prompt (injected into every model call by wrap_model_call)
# =============================================================================
@ -40,7 +49,7 @@ SURFSENSE_FILESYSTEM_SYSTEM_PROMPT = """## Following Conventions
- Read files before editing — understand existing content before making changes.
- Mimic existing style, naming conventions, and patterns.
## Filesystem Tools `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `save_document`
## Filesystem Tools
All file paths must start with a `/`.
- ls: list files and directories at a given path.
@ -128,6 +137,24 @@ SURFSENSE_GREP_TOOL_DESCRIPTION = """Search for a literal text pattern across fi
Use this to locate relevant document files/chunks before reading full files.
"""
SURFSENSE_EXECUTE_CODE_TOOL_DESCRIPTION = """Executes Python code in an isolated sandbox environment.
Common data-science packages are pre-installed (pandas, numpy, matplotlib,
scipy, scikit-learn).
When to use this tool: use execute_code for numerical computation, data
analysis, statistics, and any task that benefits from running Python code.
Never perform arithmetic manually when this tool is available.
Usage notes:
- No outbound network access.
- Returns combined stdout/stderr with exit code.
- Use print() to produce output.
- You can create files, run shell commands via subprocess or os.system(),
and use any standard library module.
- Use the optional timeout parameter to override the default timeout.
"""
SURFSENSE_SAVE_DOCUMENT_TOOL_DESCRIPTION = """Permanently saves a document to the user's knowledge base.
This is an expensive operation — it creates a new Document record in the
@ -148,17 +175,36 @@ Args:
class SurfSenseFilesystemMiddleware(FilesystemMiddleware):
"""SurfSense-specific filesystem middleware with DB persistence for docs."""
_MAX_EXECUTE_TIMEOUT = 300
def __init__(
self,
*,
search_space_id: int | None = None,
created_by_id: str | None = None,
thread_id: int | str | None = None,
tool_token_limit_before_evict: int | None = 20000,
) -> None:
self._search_space_id = search_space_id
self._created_by_id = created_by_id
self._thread_id = thread_id
self._sandbox_available = is_sandbox_enabled() and thread_id is not None
system_prompt = SURFSENSE_FILESYSTEM_SYSTEM_PROMPT
if self._sandbox_available:
system_prompt += (
"\n- execute_code: run Python code in an isolated sandbox."
"\n\n## Code Execution"
"\n\nUse execute_code whenever a task benefits from running code."
" Never perform arithmetic manually."
"\n\nDocuments here are XML-wrapped markdown, not raw data files."
" To work with them programmatically, read the document first,"
" extract the data, write it as a clean file (CSV, JSON, etc.),"
" and then run your code against it."
)
super().__init__(
system_prompt=SURFSENSE_FILESYSTEM_SYSTEM_PROMPT,
system_prompt=system_prompt,
custom_tool_descriptions={
"ls": SURFSENSE_LIST_FILES_TOOL_DESCRIPTION,
"read_file": SURFSENSE_READ_FILE_TOOL_DESCRIPTION,
@ -168,10 +214,12 @@ class SurfSenseFilesystemMiddleware(FilesystemMiddleware):
"grep": SURFSENSE_GREP_TOOL_DESCRIPTION,
},
tool_token_limit_before_evict=tool_token_limit_before_evict,
max_execute_timeout=self._MAX_EXECUTE_TIMEOUT,
)
# Remove the execute tool (no sandbox backend)
self.tools = [t for t in self.tools if t.name != "execute"]
self.tools.append(self._create_save_document_tool())
if self._sandbox_available:
self.tools.append(self._create_execute_code_tool())
@staticmethod
def _run_async_blocking(coro: Any) -> Any:
@ -455,6 +503,108 @@ class SurfSenseFilesystemMiddleware(FilesystemMiddleware):
coroutine=async_save_document,
)
def _create_execute_code_tool(self) -> BaseTool:
"""Create execute_code tool backed by a Daytona sandbox."""
def sync_execute_code(
command: Annotated[
str, "Python code to execute. Use print() to see output."
],
runtime: ToolRuntime[None, FilesystemState],
timeout: Annotated[
int | None,
"Optional timeout in seconds.",
] = None,
) -> str:
if timeout is not None:
if timeout < 0:
return f"Error: timeout must be non-negative, got {timeout}."
if timeout > self._MAX_EXECUTE_TIMEOUT:
return f"Error: timeout {timeout}s exceeds maximum ({self._MAX_EXECUTE_TIMEOUT}s)."
return self._run_async_blocking(
self._execute_in_sandbox(command, runtime, timeout)
)
async def async_execute_code(
command: Annotated[
str, "Python code to execute. Use print() to see output."
],
runtime: ToolRuntime[None, FilesystemState],
timeout: Annotated[
int | None,
"Optional timeout in seconds.",
] = None,
) -> str:
if timeout is not None:
if timeout < 0:
return f"Error: timeout must be non-negative, got {timeout}."
if timeout > self._MAX_EXECUTE_TIMEOUT:
return f"Error: timeout {timeout}s exceeds maximum ({self._MAX_EXECUTE_TIMEOUT}s)."
return await self._execute_in_sandbox(command, runtime, timeout)
return StructuredTool.from_function(
name="execute_code",
description=SURFSENSE_EXECUTE_CODE_TOOL_DESCRIPTION,
func=sync_execute_code,
coroutine=async_execute_code,
)
@staticmethod
def _wrap_as_python(code: str) -> str:
"""Wrap Python code in a shell invocation for the sandbox."""
return f"python3 << 'PYEOF'\n{code}\nPYEOF"
async def _execute_in_sandbox(
self,
command: str,
runtime: ToolRuntime[None, FilesystemState],
timeout: int | None,
) -> str:
"""Core logic: get sandbox, sync files, run command, handle retries."""
assert self._thread_id is not None
command = self._wrap_as_python(command)
try:
return await self._try_sandbox_execute(command, runtime, timeout)
except (DaytonaError, Exception) as first_err:
logger.warning(
"Sandbox execute failed for thread %s, retrying: %s",
self._thread_id,
first_err,
)
_evict_sandbox_cache(self._thread_id)
try:
return await self._try_sandbox_execute(command, runtime, timeout)
except Exception:
logger.exception(
"Sandbox retry also failed for thread %s", self._thread_id
)
return "Error: Code execution is temporarily unavailable. Please try again."
async def _try_sandbox_execute(
self,
command: str,
runtime: ToolRuntime[None, FilesystemState],
timeout: int | None,
) -> str:
sandbox, is_new = await get_or_create_sandbox(self._thread_id)
# files = runtime.state.get("files") or {}
# await sync_files_to_sandbox(self._thread_id, files, sandbox, is_new)
result = await sandbox.aexecute(command, timeout=timeout)
output = (result.output or "").strip()
if not output and result.exit_code == 0:
return (
"[Code executed successfully but produced no output. "
"Use print() to display results, then try again.]"
)
parts = [result.output]
if result.exit_code is not None:
status = "succeeded" if result.exit_code == 0 else "failed"
parts.append(f"\n[Command {status} with exit code {result.exit_code}]")
if result.truncated:
parts.append("\n[Output was truncated due to size limits]")
return "".join(parts)
def _create_write_file_tool(self) -> BaseTool:
"""Create write_file — ephemeral for /documents/*, persisted otherwise."""
tool_description = (

11
surfsense_backend/app/agents/new_chat/middleware/knowledge_search.py
View file

@ -774,11 +774,16 @@ class KnowledgeBaseSearchMiddleware(AgentMiddleware): # type: ignore[type-arg]
messages = state.get("messages") or []
if not messages:
return None
last_message = messages[-1]
if not isinstance(last_message, HumanMessage):
last_human = None
for msg in reversed(messages):
if isinstance(msg, HumanMessage):
last_human = msg
break
if last_human is None:
return None
user_text = _extract_text_from_message(last_message).strip()
user_text = _extract_text_from_message(last_human).strip()
if not user_text:
return None

115
surfsense_backend/app/agents/new_chat/sandbox.py
View file

@ -42,7 +42,7 @@ class _TimeoutAwareSandbox(DaytonaSandbox):
"""
def execute(self, command: str, *, timeout: int | None = None) -> ExecuteResponse:
t = timeout if timeout is not None else self._timeout
t = timeout if timeout is not None else self._default_timeout
result = self._sandbox.process.exec(command, timeout=t)
return ExecuteResponse(
output=result.result,
@ -58,8 +58,10 @@ class _TimeoutAwareSandbox(DaytonaSandbox):
_daytona_client: Daytona | None = None
_sandbox_cache: dict[str, _TimeoutAwareSandbox] = {}
_seeded_files: dict[str, dict[str, str]] = {}
_SANDBOX_CACHE_MAX_SIZE = 20
THREAD_LABEL_KEY = "surfsense_thread"
SANDBOX_DOCUMENTS_ROOT = "/home/daytona/documents"
def is_sandbox_enabled() -> bool:
@ -78,14 +80,29 @@ def _get_client() -> Daytona:
return _daytona_client
def _find_or_create(thread_id: str) -> _TimeoutAwareSandbox:
def _sandbox_create_params(
labels: dict[str, str],
) -> CreateSandboxFromSnapshotParams:
snapshot_id = os.environ.get("DAYTONA_SNAPSHOT_ID") or None
return CreateSandboxFromSnapshotParams(
language="python",
labels=labels,
snapshot=snapshot_id,
network_block_all=True,
auto_stop_interval=10,
auto_delete_interval=60,
)
def _find_or_create(thread_id: str) -> tuple[_TimeoutAwareSandbox, bool]:
"""Find an existing sandbox for *thread_id*, or create a new one.
If an existing sandbox is found but is stopped/archived, it will be
restarted automatically before returning.
Returns a tuple of (sandbox, is_new) where *is_new* is True when a
fresh sandbox was created (first time or replacement after failure).
"""
client = _get_client()
labels = {THREAD_LABEL_KEY: thread_id}
is_new = False
try:
sandbox = client.find_one(labels=labels)
@ -109,41 +126,43 @@ def _find_or_create(thread_id: str) -> _TimeoutAwareSandbox:
sandbox.id,
sandbox.state,
)
sandbox = client.create(
CreateSandboxFromSnapshotParams(language="python", labels=labels)
)
try:
client.delete(sandbox)
except Exception:
logger.debug("Could not delete broken sandbox %s", sandbox.id, exc_info=True)
sandbox = client.create(_sandbox_create_params(labels))
is_new = True
logger.info("Created replacement sandbox: %s", sandbox.id)
elif sandbox.state != SandboxState.STARTED:
sandbox.wait_for_sandbox_start(timeout=60)
except Exception:
logger.info("No existing sandbox for thread %s — creating one", thread_id)
sandbox = client.create(
CreateSandboxFromSnapshotParams(language="python", labels=labels)
)
sandbox = client.create(_sandbox_create_params(labels))
is_new = True
logger.info("Created new sandbox: %s", sandbox.id)
return _TimeoutAwareSandbox(sandbox=sandbox)
return _TimeoutAwareSandbox(sandbox=sandbox), is_new
async def get_or_create_sandbox(thread_id: int | str) -> _TimeoutAwareSandbox:
async def get_or_create_sandbox(
thread_id: int | str,
) -> tuple[_TimeoutAwareSandbox, bool]:
"""Get or create a sandbox for a conversation thread.
Uses an in-process cache keyed by thread_id so subsequent messages
in the same conversation reuse the sandbox object without an API call.
Args:
thread_id: The conversation thread identifier.
Returns:
DaytonaSandbox connected to the sandbox.
Tuple of (sandbox, is_new). *is_new* is True when a fresh sandbox
was created, signalling that file tracking should be reset.
"""
key = str(thread_id)
cached = _sandbox_cache.get(key)
if cached is not None:
logger.info("Reusing cached sandbox for thread %s", key)
return cached
sandbox = await asyncio.to_thread(_find_or_create, key)
return cached, False
sandbox, is_new = await asyncio.to_thread(_find_or_create, key)
_sandbox_cache[key] = sandbox
if len(_sandbox_cache) > _SANDBOX_CACHE_MAX_SIZE:
@ -151,12 +170,60 @@ async def get_or_create_sandbox(thread_id: int | str) -> _TimeoutAwareSandbox:
_sandbox_cache.pop(oldest_key, None)
logger.debug("Evicted oldest sandbox cache entry: %s", oldest_key)
return sandbox
return sandbox, is_new
async def sync_files_to_sandbox(
thread_id: int | str,
files: dict[str, dict],
sandbox: _TimeoutAwareSandbox,
is_new: bool,
) -> None:
"""Upload new or changed virtual-filesystem files to the sandbox.
Compares *files* (from ``state["files"]``) against the ``_seeded_files``
tracking dict and uploads only what has changed. When *is_new* is True
the tracking is reset so every file is re-uploaded.
"""
key = str(thread_id)
if is_new:
_seeded_files.pop(key, None)
tracked = _seeded_files.get(key, {})
to_upload: list[tuple[str, bytes]] = []
for vpath, fdata in files.items():
modified_at = fdata.get("modified_at", "")
if tracked.get(vpath) == modified_at:
continue
content = "\n".join(fdata.get("content", []))
sandbox_path = f"{SANDBOX_DOCUMENTS_ROOT}{vpath}"
to_upload.append((sandbox_path, content.encode("utf-8")))
if not to_upload:
return
def _upload() -> None:
sandbox.upload_files(to_upload)
await asyncio.to_thread(_upload)
new_tracked = dict(tracked)
for vpath, fdata in files.items():
new_tracked[vpath] = fdata.get("modified_at", "")
_seeded_files[key] = new_tracked
logger.info("Synced %d file(s) to sandbox for thread %s", len(to_upload), key)
def _evict_sandbox_cache(thread_id: int | str) -> None:
key = str(thread_id)
_sandbox_cache.pop(key, None)
_seeded_files.pop(key, None)
async def delete_sandbox(thread_id: int | str) -> None:
"""Delete the sandbox for a conversation thread."""
_sandbox_cache.pop(str(thread_id), None)
_evict_sandbox_cache(thread_id)
def _delete() -> None:
client = _get_client()
@ -193,7 +260,11 @@ def _get_sandbox_files_dir() -> Path:
def _local_path_for(thread_id: int | str, sandbox_path: str) -> Path:
"""Map a sandbox-internal absolute path to a local filesystem path."""
relative = sandbox_path.lstrip("/")
return _get_sandbox_files_dir() / str(thread_id) / relative
base = (_get_sandbox_files_dir() / str(thread_id)).resolve()
target = (base / relative).resolve()
if not target.is_relative_to(base):
raise ValueError(f"Path traversal blocked: {sandbox_path}")
return target
def get_local_sandbox_file(thread_id: int | str, sandbox_path: str) -> bytes | None:
@ -226,7 +297,7 @@ async def persist_and_delete_sandbox(
Per-file errors are logged but do **not** prevent the sandbox from
being deleted — freeing Daytona storage is the priority.
"""
_sandbox_cache.pop(str(thread_id), None)
_evict_sandbox_cache(thread_id)
def _persist_and_delete() -> None:
client = _get_client()

96
surfsense_backend/scripts/create_sandbox_snapshot.py Normal file
View file

@ -0,0 +1,96 @@
"""Create the Daytona snapshot used by SurfSense code-execution sandboxes.
Run from the backend directory:
cd surfsense_backend
uv run python scripts/create_sandbox_snapshot.py
Prerequisites:
- DAYTONA_API_KEY set in surfsense_backend/.env (or exported in shell)
- DAYTONA_API_URL=https://app.daytona.io/api
- DAYTONA_TARGET=us (or eu)
After this script succeeds, add to surfsense_backend/.env:
DAYTONA_SNAPSHOT_ID=surfsense-sandbox
"""
import os
import sys
import time
from pathlib import Path
from dotenv import load_dotenv
_here = Path(__file__).parent
for candidate in [_here / "../surfsense_backend/.env", _here / ".env", _here / "../.env"]:
if candidate.exists():
load_dotenv(candidate)
break
from daytona import CreateSnapshotParams, Daytona, Image # noqa: E402
SNAPSHOT_NAME = "surfsense-sandbox"
PACKAGES = [
"pandas",
"numpy",
"matplotlib",
"scipy",
"scikit-learn",
]
def build_image() -> Image:
"""Build the sandbox image with data-science packages and a /documents symlink."""
return (
Image.debian_slim("3.12")
.pip_install(*PACKAGES)
# Symlink /documents → /home/daytona/documents so the LLM can use
# the same /documents/ path it sees in the virtual filesystem.
.run_commands(
"mkdir -p /home/daytona/documents",
"ln -sfn /home/daytona/documents /documents",
)
)
def main() -> None:
api_key = os.environ.get("DAYTONA_API_KEY")
if not api_key:
print("ERROR: DAYTONA_API_KEY is not set.", file=sys.stderr)
print("Add it to surfsense_backend/.env or export it in your shell.", file=sys.stderr)
sys.exit(1)
daytona = Daytona()
try:
existing = daytona.snapshot.get(SNAPSHOT_NAME)
print(f"Deleting existing snapshot '{SNAPSHOT_NAME}' …")
daytona.snapshot.delete(existing)
print(f"Deleted '{SNAPSHOT_NAME}'. Waiting for removal to propagate …")
for attempt in range(30):
time.sleep(2)
try:
daytona.snapshot.get(SNAPSHOT_NAME)
except Exception:
print(f"Confirmed '{SNAPSHOT_NAME}' is gone.\n")
break
else:
print(f"WARNING: '{SNAPSHOT_NAME}' may still exist after 60s. Proceeding anyway.\n")
except Exception:
pass
print(f"Building snapshot '{SNAPSHOT_NAME}' …")
print(f"Packages: {', '.join(PACKAGES)}\n")
daytona.snapshot.create(
CreateSnapshotParams(name=SNAPSHOT_NAME, image=build_image()),
on_logs=lambda chunk: print(chunk, end="", flush=True),
)
print(f"\n\nSnapshot '{SNAPSHOT_NAME}' is ready.")
print("\nAdd this to surfsense_backend/.env:")
print(f" DAYTONA_SNAPSHOT_ID={SNAPSHOT_NAME}")
if __name__ == "__main__":
main()

163
surfsense_web/app/(home)/blog/[slug]/page.tsx Normal file
View file

@ -0,0 +1,163 @@
import { loader } from "fumadocs-core/source";
import type { Metadata } from "next";
import Image from "next/image";
import { notFound } from "next/navigation";
import { blog } from "@/.source/server";
import { BreadcrumbNav } from "@/components/seo/breadcrumb-nav";
import { ArticleJsonLd } from "@/components/seo/json-ld";
import { formatDate } from "@/lib/utils";
import { getMDXComponents } from "@/mdx-components";
const source = loader({
baseUrl: "/blog",
source: blog.toFumadocsSource(),
});
interface BlogData {
title: string;
description: string;
date: string;
image?: string;
author?: string;
authorAvatar?: string;
tags?: string[];
body: React.ComponentType<{
components?: Record<string, React.ComponentType>;
}>;
}
interface BlogPageItem {
url: string;
slugs: string[];
data: BlogData;
}
export async function generateStaticParams() {
return source.getPages().map((page) => ({
slug: (page as BlogPageItem).slugs.join("/"),
}));
}
export async function generateMetadata(props: {
params: Promise<{ slug: string }>;
}): Promise<Metadata> {
const { slug } = await props.params;
const page = (source.getPages() as BlogPageItem[]).find(
(p) => p.slugs.join("/") === slug,
);
if (!page) return {};
return {
title: `${page.data.title} | SurfSense Blog`,
description: page.data.description,
alternates: {
canonical: `https://surfsense.com/blog/${slug}`,
},
openGraph: {
title: page.data.title,
description: page.data.description,
type: "article",
publishedTime: page.data.date,
authors: [page.data.author ?? "SurfSense Team"],
tags: page.data.tags,
images: page.data.image ? [{ url: page.data.image }] : [{ url: "/og-image.png" }],
},
twitter: {
card: "summary_large_image",
title: page.data.title,
description: page.data.description,
images: page.data.image ? [page.data.image] : ["/og-image.png"],
},
};
}
export default async function BlogPostPage(props: {
params: Promise<{ slug: string }>;
}) {
const { slug } = await props.params;
const page = (source.getPages() as BlogPageItem[]).find(
(p) => p.slugs.join("/") === slug,
);
if (!page) notFound();
const MDX = page.data.body;
const date = new Date(page.data.date);
return (
<div className="min-h-screen relative pt-20">
<ArticleJsonLd
title={page.data.title}
description={page.data.description}
url={`https://surfsense.com/blog/${slug}`}
datePublished={page.data.date}
author={page.data.author ?? "SurfSense Team"}
image={page.data.image ? `https://surfsense.com${page.data.image}` : undefined}
/>
<div className="max-w-3xl mx-auto px-6 lg:px-10 pt-10 pb-20">
<BreadcrumbNav
items={[
{ name: "Home", href: "/" },
{ name: "Blog", href: "/blog" },
{ name: page.data.title, href: `/blog/${slug}` },
]}
className="mb-8"
/>
{page.data.image && (
<div className="relative aspect-2/1 overflow-hidden rounded-2xl mb-8">
<Image
src={page.data.image}
alt={page.data.title}
fill
className="object-cover"
priority
sizes="(max-width: 768px) 100vw, 768px"
/>
</div>
)}
<div className="space-y-4 mb-10">
<h1 className="text-3xl md:text-4xl font-bold tracking-tight text-balance">
{page.data.title}
</h1>
{page.data.tags && page.data.tags.length > 0 && (
<div className="flex flex-wrap gap-2">
{page.data.tags.map((tag: string) => (
<span
key={tag}
className="h-6 w-fit px-2.5 text-xs font-medium bg-muted text-muted-foreground rounded-full border flex items-center justify-center"
>
{tag}
</span>
))}
</div>
)}
<div className="flex items-center gap-3 text-sm text-muted-foreground">
{page.data.authorAvatar && (
<Image
src={page.data.authorAvatar}
alt={page.data.author ?? "SurfSense Team"}
width={32}
height={32}
className="h-8 w-8 rounded-full object-cover"
/>
)}
<span className="font-medium text-foreground">
{page.data.author ?? "SurfSense Team"}
</span>
<span>·</span>
<time dateTime={page.data.date}>{formatDate(date)}</time>
</div>
</div>
<div className="prose dark:prose-invert max-w-none prose-headings:scroll-mt-8 prose-headings:font-semibold prose-a:no-underline prose-headings:tracking-tight prose-headings:text-balance prose-p:tracking-tight prose-p:text-balance prose-img:rounded-xl prose-img:shadow-lg">
<MDX components={getMDXComponents()} />
</div>
</div>
</div>
);
}

228
surfsense_web/app/(home)/blog/blog-magazine.tsx Normal file
View file

@ -0,0 +1,228 @@
"use client";
import { Container } from "@/components/container";
import { format } from "date-fns";
import Link from "next/link";
import { useEffect, useMemo, useState } from "react";
import FuzzySearch from "fuzzy-search";
import type { BlogEntry } from "./page";
function truncate(text: string, length: number) {
return text.length > length ? `${text.slice(0, length)}…` : text;
}
function SearchIcon({ className }: { className?: string }) {
return (
<svg
className={className}
xmlns="http://www.w3.org/2000/svg"
width="20"
height="20"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
strokeWidth="2"
strokeLinecap="round"
strokeLinejoin="round"
aria-hidden
>
<circle cx="11" cy="11" r="8" />
<path d="m21 21-4.3-4.3" />
</svg>
);
}
export function BlogWithSearchMagazine({ blogs }: { blogs: BlogEntry[] }) {
const featured = blogs[0];
if (!featured) {
return (
<div className="relative overflow-hidden bg-neutral-50 px-4 md:px-8 dark:bg-neutral-950">
<Container className="relative pt-12 pb-24 md:pt-20">
<p className="text-center text-neutral-500">No blog posts yet.</p>
</Container>
</div>
);
}
return (
<div className="relative overflow-hidden bg-neutral-50 px-4 pt-20 md:px-8 dark:bg-neutral-950">
<div className="pointer-events-none absolute inset-0 bg-[radial-gradient(ellipse_80%_50%_at_50%_-20%,rgba(120,119,198,0.15),transparent)] dark:bg-[radial-gradient(ellipse_80%_50%_at_50%_-20%,rgba(120,119,198,0.12),transparent)]" />
<Container className="relative pt-12 pb-24 md:pt-20">
<header className="mb-10 md:mb-14">
<h1 className="text-4xl font-bold tracking-tight text-neutral-900 md:text-5xl dark:text-neutral-50">
Blog
</h1>
</header>
<MagazineFeatured blog={featured} />
<MagazineSearchGrid blogs={blogs} featuredSlug={featured.slug} />
</Container>
</div>
);
}
function MagazineFeatured({ blog }: { blog: BlogEntry }) {
return (
<Link
href={blog.url}
className="group/cover relative mb-14 block overflow-hidden rounded-3xl border border-neutral-200/80 bg-neutral-900 shadow-sm dark:border-neutral-800 dark:shadow-none"
>
<div className="md:aspect-[2.4/1] relative aspect-21/9 min-h-[220px]">
{blog.image ? (
<img
src={blog.image}
alt={blog.title}
className="h-full w-full object-cover transition duration-500 group-hover/cover:scale-[1.03]"
/>
) : null}
<div className="absolute inset-0 bg-linear-to-t from-black/85 via-black/35 to-transparent" />
<div className="absolute inset-0 flex flex-col justify-end p-6 md:p-10">
<span className="mb-2 inline-flex w-fit rounded-full bg-white/15 px-3 py-1 text-xs font-medium text-white backdrop-blur-sm">
Cover story
</span>
<h2 className="max-w-3xl font-serif text-2xl leading-tight font-medium text-white md:text-4xl">
{blog.title}
</h2>
<p className="mt-3 max-w-2xl text-sm text-white/85 md:text-base">
{truncate(blog.description, 160)}
</p>
<div className="mt-5 flex flex-wrap items-center gap-3 text-sm text-white/90">
<span className="flex items-center gap-2">
<img
src={blog.authorAvatar}
alt={blog.author}
width={28}
height={28}
className="h-7 w-7 rounded-full ring-2 ring-white/30"
/>
{blog.author}
</span>
<span className="text-white/50">·</span>
<time dateTime={blog.date}>
{format(new Date(blog.date), "MMMM d, yyyy")}
</time>
</div>
</div>
</div>
</Link>
);
}
function MagazineSearchGrid({
blogs: allBlogs,
featuredSlug,
}: {
blogs: BlogEntry[];
featuredSlug: string;
}) {
const [search, setSearch] = useState("");
const searcher = useMemo(
() =>
new FuzzySearch(allBlogs, ["title", "description"], {
caseSensitive: false,
}),
[allBlogs],
);
const [results, setResults] = useState(allBlogs);
useEffect(() => {
setResults(searcher.search(search));
}, [search, searcher]);
const gridItems = useMemo(() => {
if (search.trim()) {
return results;
}
return results.filter((b) => b.slug !== featuredSlug);
}, [results, search, featuredSlug]);
return (
<section aria-labelledby="archive-heading">
<div className="mb-8 flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
<h2
id="archive-heading"
className="font-serif text-2xl font-medium text-neutral-900 dark:text-neutral-100"
>
From the archive
</h2>
<label className="relative w-full sm:max-w-md">
<span className="sr-only">Search articles</span>
<SearchIcon className="pointer-events-none absolute top-1/2 left-4 -translate-y-1/2 text-neutral-400" />
<input
type="search"
value={search}
onChange={(e) => setSearch(e.target.value)}
placeholder="Search by title or topic…"
className="w-full rounded-full bg-white py-3 pr-4 pl-12 text-sm text-neutral-800 shadow-sm ring-1 shadow-black/10 ring-black/10 transition outline-none placeholder:text-neutral-400 focus:border-neutral-400 focus:ring-2 focus:ring-neutral-200/80 dark:bg-neutral-900 dark:text-neutral-100 dark:placeholder:text-neutral-500 dark:focus:border-neutral-500 dark:focus:ring-neutral-700/50"
/>
</label>
</div>
{gridItems.length === 0 ? (
<p className="rounded-2xl border border-dashed border-neutral-300 py-16 text-center text-neutral-500 dark:border-neutral-700 dark:text-neutral-400">
No articles match that search.
</p>
) : (
<ul className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
{gridItems.map((blog) => (
<li key={blog.slug}>
<MagazineCard blog={blog} />
</li>
))}
</ul>
)}
</section>
);
}
function MagazineCard({ blog }: { blog: BlogEntry }) {
return (
<Link
href={blog.url}
className="group/card flex h-full flex-col overflow-hidden rounded-2xl bg-white shadow-sm ring-1 shadow-black/10 ring-black/10 transition hover:-translate-y-0.5 hover:shadow-lg dark:border-neutral-800 dark:bg-neutral-900/50 dark:hover:border-neutral-700"
>
<div className="relative aspect-16/10 overflow-hidden bg-neutral-100 dark:bg-neutral-800">
{blog.image ? (
<img
src={blog.image}
alt={blog.title}
className="h-full w-full object-cover transition duration-300 group-hover/card:scale-105"
/>
) : (
<div className="flex h-full items-center justify-center text-neutral-400">
No image
</div>
)}
</div>
<div className="flex flex-1 flex-col p-5">
<time
className="text-xs font-medium tracking-wider text-neutral-500 uppercase dark:text-neutral-400"
dateTime={blog.date}
>
{format(new Date(blog.date), "MMM d, yyyy")}
</time>
<h3 className="mt-2 font-serif text-lg leading-snug font-medium text-neutral-900 dark:text-neutral-100">
{blog.title}
</h3>
<p className="mt-2 flex-1 text-sm leading-relaxed text-neutral-600 dark:text-neutral-400">
{truncate(blog.description, 110)}
</p>
<div className="mt-4 flex items-center gap-2 pt-4">
<img
src={blog.authorAvatar}
alt={blog.author}
width={24}
height={24}
className="h-6 w-6 rounded-full object-cover"
/>
<span className="text-xs text-neutral-600 dark:text-neutral-300">
{blog.author}
</span>
</div>
</div>
</Link>
);
}

61
surfsense_web/app/(home)/blog/page.tsx Normal file
View file

@ -0,0 +1,61 @@
import { loader } from "fumadocs-core/source";
import type { Metadata } from "next";
import { blog } from "@/.source/server";
import { BlogWithSearchMagazine } from "./blog-magazine";
export const metadata: Metadata = {
title: "Blog | SurfSense - AI Search & Knowledge Management",
description:
"Product updates, tutorials, and tips from the SurfSense team.",
alternates: {
canonical: "https://surfsense.com/blog",
},
};
const source = loader({
baseUrl: "/blog",
source: blog.toFumadocsSource(),
});
export interface BlogEntry {
title: string;
description: string;
date: string;
slug: string;
url: string;
image: string;
author: string;
authorAvatar: string;
}
export default async function BlogPage() {
const allPages = source.getPages() as Array<{
url: string;
slugs: string[];
data: {
title: string;
description: string;
date: string;
image?: string;
author?: string;
authorAvatar?: string;
};
}>;
const blogs: BlogEntry[] = allPages
.map((page) => ({
title: page.data.title,
description: page.data.description ?? "",
date: page.data.date,
slug: page.slugs.join("/"),
url: page.url,
image: page.data.image ?? "/og-image.png",
author: page.data.author ?? "SurfSense Team",
authorAvatar: page.data.authorAvatar ?? "/logo.png",
}))
.sort(
(a, b) => new Date(b.date).getTime() - new Date(a.date).getTime(),
);
return <BlogWithSearchMagazine blogs={blogs} />;
}

13
surfsense_web/app/(home)/changelog/page.tsx
View file

@ -1,12 +1,16 @@
import { loader } from "fumadocs-core/source";
import type { Metadata } from "next";
import { changelog } from "@/.source/server";
import { BreadcrumbNav } from "@/components/seo/breadcrumb-nav";
import { formatDate } from "@/lib/utils";
import { getMDXComponents } from "@/mdx-components";
export const metadata: Metadata = {
title: "Changelog | SurfSense",
description: "See what's new in SurfSense.",
description: "See what's new in SurfSense. Latest updates, features, and improvements.",
alternates: {
canonical: "https://surfsense.com/changelog",
},
};
const source = loader({
@ -42,6 +46,13 @@ export default async function ChangelogPage() {
<div className="max-w-5xl mx-auto relative">
<div className="p-6 flex items-center justify-between">
<div>
<BreadcrumbNav
items={[
{ name: "Home", href: "/" },
{ name: "Changelog", href: "/changelog" },
]}
className="mb-4"
/>
<h1 className="text-4xl font-bold tracking-tight bg-gradient-to-r from-gray-900 to-gray-600 dark:from-white dark:to-gray-400 bg-clip-text text-transparent">
Changelog
</h1>

5
surfsense_web/app/(home)/contact/page.tsx
View file

@ -3,7 +3,10 @@ import { ContactFormGridWithDetails } from "@/components/contact/contact-form";
export const metadata: Metadata = {
title: "Contact | SurfSense",
description: "Get in touch with the SurfSense team.",
description: "Get in touch with the SurfSense team for enterprise AI search, knowledge management, or partnership inquiries.",
alternates: {
canonical: "https://surfsense.com/contact",
},
};
const page = () => {

36
surfsense_web/app/(home)/page.tsx
View file

@ -1,49 +1,23 @@
"use client";
import dynamic from "next/dynamic";
import { useRouter } from "next/navigation";
import { useEffect } from "react";
import { HeroSection } from "@/components/homepage/hero-section";
import { getBearerToken } from "@/lib/auth-utils";
import { AuthRedirect } from "@/components/homepage/auth-redirect";
import { FeaturesCards } from "@/components/homepage/features-card";
import { FeaturesBentoGrid } from "@/components/homepage/features-bento-grid";
const WhySurfSense = dynamic(
() => import("@/components/homepage/why-surfsense").then((m) => ({ default: m.WhySurfSense })),
{ ssr: false }
);
const FeaturesCards = dynamic(
() => import("@/components/homepage/features-card").then((m) => ({ default: m.FeaturesCards })),
{ ssr: false }
);
const FeaturesBentoGrid = dynamic(
() =>
import("@/components/homepage/features-bento-grid").then((m) => ({
default: m.FeaturesBentoGrid,
})),
{ ssr: false }
);
const ExternalIntegrations = dynamic(() => import("@/components/homepage/integrations"), {
ssr: false,
});
const ExternalIntegrations = dynamic(() => import("@/components/homepage/integrations"));
const CTAHomepage = dynamic(
() => import("@/components/homepage/cta").then((m) => ({ default: m.CTAHomepage })),
{ ssr: false }
);
export default function HomePage() {
const router = useRouter();
useEffect(() => {
if (getBearerToken()) {
router.replace("/dashboard");
}
}, [router]);
return (
<main className="min-h-screen bg-gradient-to-b from-gray-50 to-gray-100 text-gray-900 dark:from-black dark:to-gray-900 dark:text-white">
<AuthRedirect />
<HeroSection />
<WhySurfSense />
<FeaturesCards />

17
surfsense_web/app/(home)/pricing/page.tsx
View file

@ -1,14 +1,27 @@
import type { Metadata } from "next";
import { BreadcrumbNav } from "@/components/seo/breadcrumb-nav";
import PricingBasic from "@/components/pricing/pricing-section";
export const metadata: Metadata = {
title: "Pricing | SurfSense",
description: "Explore SurfSense plans and pricing options.",
title: "Pricing | SurfSense - Free AI Search Plans",
description:
"Explore SurfSense plans and pricing. Use ChatGPT, Claude AI, and any AI model free. Open source NotebookLM alternative for teams.",
alternates: {
canonical: "https://surfsense.com/pricing",
},
};
const page = () => {
return (
<div>
<div className="container mx-auto pt-24 px-4">
<BreadcrumbNav
items={[
{ name: "Home", href: "/" },
{ name: "Pricing", href: "/pricing" },
]}
/>
</div>
<PricingBasic />
</div>
);

3
surfsense_web/app/(home)/privacy/page.tsx
View file

@ -3,6 +3,9 @@ import type { Metadata } from "next";
export const metadata: Metadata = {
title: "Privacy Policy | SurfSense",
description: "Privacy Policy for SurfSense application",
alternates: {
canonical: "https://surfsense.com/privacy",
},
};
export default function PrivacyPolicy() {

3
surfsense_web/app/(home)/terms/page.tsx
View file

@ -3,6 +3,9 @@ import type { Metadata } from "next";
export const metadata: Metadata = {
title: "Terms of Service | SurfSense",
description: "Terms of Service for SurfSense application",
alternates: {
canonical: "https://surfsense.com/terms",
},
};
export default function TermsOfService() {

BIN
surfsense_web/app/apple-icon.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 66 KiB

Some files were not shown because too many files have changed in this diff Show more