/seo-sxo

name: seo-sxo
description: >
  Search Experience Optimization: reads Google SERPs backwards to detect page-type
  mismatches, derives user stories from search intent signals, and scores pages
  from multiple persona perspectives. Identifies why well-optimized pages fail
  to rank by analyzing what Google rewards for each keyword. Use when user says
  "SXO", "search experience", "page type mismatch", "SERP analysis", "user story",
  "persona scoring", "why isn't my page ranking", "intent mismatch", or "wireframe".
user-invokable: true
argument-hint: "<url> [keyword]"
license: MIT
metadata:
  author: AgriciDaniel
  original_author: "Florian Schmitz (Pro Hub Challenge)"
  version: "1.9.6"
  category: seo

Search Experience Optimization (SXO)

Shared Data Cache

**Step 0 -- Check shared data cache:**

Before gathering, check `.seo-cache/` for reusable context from related SEO skills. Reference: `../seo/references/shared-data-cache.md` for schemas and dependency map.

Check these cache files when present:

• `.seo-cache/site-meta.json` for domain, business type, industry, and crawl context
• `.seo-cache/audit-scores.json` for prior full-audit priorities
• `.seo-cache/pages/{url-slug}/page-analysis.json` for page-level context when a URL is provided

• If found: parse and use clearly valid fields (note "Using cached [X] from [date]")
• If missing, corrupt, or irrelevant: continue with fresh evidence
• If the user says "refresh" or "re-run": ignore cache reads and overwrite on write

SXO bridges the gap between SEO (what Google rewards) and UX (what users need). Traditional SEO audits check technical health. SXO asks: "Does this page deserve to rank for this keyword based on what Google is actually rewarding in the SERP?"

Core Insight

A page can score 95/100 on technical SEO and still fail to rank because it is the **wrong page type** for the keyword. If Google shows 8 product pages and 2 comparison pages for your keyword, your blog post will never break through -- no matter how well-optimized it is.

Commands

| Command | Purpose | |---------|---------| | `/seo sxo <url>` | Full SXO analysis (auto-detect keyword from page) | | `/seo sxo <url> <keyword>` | Full SXO analysis for a specific keyword | | `/seo sxo wireframe <url>` | Generate IST/SOLL wireframe with concrete placeholders | | `/seo sxo personas <url>` | Persona-only scoring (skip SERP analysis) |

Execution Pipeline

Step 1: Target Acquisition

1. Fetch the target URL via `scripts/fetch_page.py` (SSRF-safe) 2. Parse with `scripts/parse_html.py` to extract: title, H1, meta description, headings hierarchy, word count, schema markup, CTAs, media elements 3. If no keyword provided, extract primary keyword from title tag + H1 overlap 4. Validate keyword is non-empty before proceeding

Step 2: SERP Backwards Analysis

Read `references/page-type-taxonomy.md` for classification rules.

1. Search Google for the target keyword (WebSearch) 2. For each of the top 10 organic results, record:

• URL and domain authority tier (brand / niche authority / unknown)
• Page type (classify using taxonomy)
• Content format (long-form, listicle, how-to, comparison, tool, video)
• Word count estimate (from snippet length and page structure)
• Schema types present (from SERP features: ratings, FAQ, HowTo)
• Media signals (video carousel, image pack, thumbnail presence)

3. Record SERP features present:

• Featured snippet (paragraph / list / table / video)
• People Also Ask (extract all visible questions)
• Ads (top and bottom -- count and analyze ad copy themes)
• Related searches (extract all)
• Knowledge panel / local pack / shopping results
• AI Overview presence and source types

4. Calculate SERP consensus:

• Dominant page type (>60% = strong consensus, 40-60% = mixed, <40% = fragmented)
• Content depth expectations (average word count tier)
• Schema expectation (most common structured data types)
• Media expectations (video required? images critical?)

Step 3: Page-Type Mismatch Detection

This is the core SXO insight. Compare target page type against SERP consensus.

**Mismatch severity levels:**

| Target Type | SERP Expects | Severity | Recommendation | |-------------|-------------|----------|----------------| | Blog Post | Product Pages | CRITICAL | Create dedicated product page | | Blog Post | Comparison | HIGH | Restructure as comparison with matrix | | Product | Informational | HIGH | Add educational content layer | | Landing Page | Tool/Calculator | HIGH | Build interactive tool component | | Service Page | Local Results | MEDIUM | Add location signals + local schema | | Any type match | - | ALIGNED | Focus on content depth and UX |

**Classification rules:**

• Classify target page using `references/page-type-taxonomy.md`
• Classify each SERP result using the same taxonomy
• Flag mismatch if target type differs from SERP dominant type
• If SERP is fragmented (no dominant type), note opportunity for differentiation

Step 4: User Story Derivation

Read `references/user-story-framework.md` for the full framework.

From SERP signals, derive user stories:

1. **PAA questions** reveal knowledge gaps and concerns 2. **Ad copy themes** reveal commercial triggers and value propositions 3. **Related searches** reveal the search journey (what comes before/after) 4. **Featured snippet format** reveals the expected answer structure 5. **AI Overview** reveals what Google considers the definitive answer

For each signal cluster, generate a user story:

As a [persona derived from signal],
I want to [goal derived from query intent],
because [emotional driver from ad copy / PAA tone],
but I'm blocked by [barrier derived from PAA questions / related searches].

Generate 3-5 user stories covering the primary intent angles.

Step 5: Gap Analysis

Compare the target page against SERP expectations across 7 dimensions:

| Dimension | What to Compare | Score | |-----------|-