# SEO SXO Human Guide

## What This Is For
SXO bridges the gap between SEO (what Google rewards) and UX (what users need). It gives the agent a clearer input/output frame for search and SEO workflows: what context to ask for, what decisions to make, and what usable artifact to return.

Use this as a human-readable version of the SEO SXO agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions.

## When To Use This
- Use this when you need a repeatable process for SEO SXO.
- Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt.
- Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact.

## When Not To Use This
- Do not use this when you only need a quick factual answer.
- Do not use this when the work depends on private data you cannot share with the assistant.
- Do not use this as a replacement for legal, compliance, financial, or medical review.

## What You Need Before Starting
- The goal or business outcome you want.
- The audience, customer segment, or market context.
- Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance.
- Constraints such as tone, length, channel, deadline, region, or approval requirements.
- A clear definition of what a good final answer should look like.

## Step-By-Step Workflow
1. State the job clearly: "Use the SEO SXO guide to help me with..."
2. Add context: audience, goal, offer, channel, source material, and constraints.
3. Ask the assistant to identify missing inputs before producing the final output.
4. Have the assistant follow the skill-specific guidance below.
5. Review the result against the final checklist and ask for revisions where needed.

## Skill-Specific Guidance
- Fetch the target URL via `scripts/render_page.py --mode auto` (SPA-aware and SSRF-safe)
- Parse with `scripts/parse_html.py` to extract: title, H1, meta description,
- If no keyword provided, extract primary keyword from title tag + H1 overlap
- Validate keyword is non-empty before proceeding
- Search Google for the target keyword (WebSearch)
- 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)

## Decision Points And Nuance
The original skill emphasizes: Core Insight, Commands, Execution Pipeline, Step 1: Target Acquisition, Step 2: SERP Backwards Analysis, Step 3: Page-Type Mismatch Detection, Step 4: User Story Derivation, Step 5: Gap Analysis, Step 6: Persona-Based Scoring, Step 7: Wireframe Generation (Optional).

Use these questions to steer the work:
- What is the intended audience or buyer?
- What source material must be preserved?
- What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion?
- What examples represent the desired quality bar?
- What should the assistant avoid?

## Common Mistakes
- pages for your keyword, your blog post will never break through -- no matter how
- Media expectations (video required? images critical?)
- **Required elements:** Primary CTA above fold, trust badges, at least one testimonial,
- **Required elements:** Article or BlogPosting schema, author entity, datePublished,
- **Required elements:** Product schema (name, price, availability, review),
- **Required elements:** FAQPage or HowTo schema combined with product schema,
- **Required elements:** Service or ProfessionalService schema, clear process
- **Required elements:** Comparison table with clear criteria, pros/cons for each

## Copy-And-Paste Prompt
```text
Use the SEO SXO human guide.

My goal:
[Describe the business outcome]

Audience:
[Describe who this is for]

Context and source material:
[Paste notes, examples, links, or existing copy]

Constraints:
[Tone, length, channel, timeline, must-include items, must-avoid items]

Before producing the final output, ask me for any missing information that would materially improve the result.
```

## Final Checklist
- [ ] The output matches the original goal.
- [ ] The audience and context are reflected in the answer.
- [ ] Important constraints and source material were preserved.
- [ ] The assistant made the relevant decisions explicit.
- [ ] The final artifact is ready to use, review, or hand to the next person.

## Source
This guide was generated from the agricidaniel/claude-seo skill entry for `seo-sxo`.

## Source Skill Notes
These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic.

# Search Experience Optimization (SXO)

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/render_page.py --mode auto` (SPA-aware and 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