# Seo Sxo

> Diagnose why a page is not ranking by reading the SERP backwards. Identifies the page type Google rewards for the target keyword, scores the candidate page against that pattern from multiple persona perspectives, and recommends the page format that would win the SERP. Use when the user asks "why isn't this page ranking", "page type mismatch", "SXO", "search experience optimization", "intent misma…

- **Type:** Skill
- **Install:** `agentstack add skill-amirjahfar1-automate-seo-with-claude-seo-sxo`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [amirjahfar1](https://agentstack.voostack.com/s/amirjahfar1)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [amirjahfar1](https://github.com/amirjahfar1)
- **Source:** https://github.com/amirjahfar1/automate-seo-with-claude/tree/main/skills/seo-sxo
- **Website:** https://nextbrainsolutions.com/

## Install

```sh
agentstack add skill-amirjahfar1-automate-seo-with-claude-seo-sxo
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> Example output: [examples/seo-sxo-bigin-com-20260514/SXO-REPORT.md](../../examples/seo-sxo-bigin-com-20260514/SXO-REPORT.md)

# SEO SXO — Search Experience Optimization

Diagnose why a "well-optimized" page doesn't rank. Reads the actual SERP for the target keyword, infers the page type Google is rewarding, scores the candidate page against that pattern from multiple persona perspectives, and recommends the page format that would win the SERP.

> **Acknowledgements:** SXO-as-a-skill framework originated in `claude-seo` by AgriciDaniel (with the original concept credited to Florian Schmitz, Pro Hub Challenge). MIT-licensed both directions; this implementation is independent but the framing is theirs.

## Prerequisites

- DataForSEO MCP server connected.
- Claude's `WebFetch` tool available.
- User provides: (a) target page URL, (b) target keyword the page is meant to rank for, optionally (c) target country (default `us`).

## Process

1. **Validate inputs.** Both URL and keyword are required. If keyword missing, ask the user — don't infer.

2. **Pull the SERP** `mcp__dataforseo__serp_organic_live_advanced`
   - Top 10 organic results with URL, title, snippet.
   - SERP features: AI Overview presence, People Also Ask, image carousel, video carousel, shopping pack, Twitter pack, Featured Snippet, etc.
   - **Mode selection (cost driver — read this).** `serp_organic_live_advanced` returns the full SERP-feature payload (AIO/PAA/carousels) plus organic inline in a single live call. DataForSEO bills per call (pay-per-call; no pre-run credit gate); this is the single most-expensive call this skill makes, so use the mode flags to control how much you fetch and how many keywords you run it against.
     - **Default — `mode=full`:** issues `serp_organic_live_advanced` with default `depth` (top-100) and parses the SERP-feature blocks. Use when persona scoring needs PAA / AIO / pack signals (most cases).
     - **`mode=lite`:** issues `serp_organic_live_advanced` with a reduced `depth` (e.g. `depth: 10`) and ignores the feature blocks — organic top-10 only. Use when (a) the user is screening many keywords and SERP features aren't load-bearing, (b) call volume is constrained, (c) the user explicitly asks for a cheap pass. The persona scoring still runs but the SERP-features row in `SXO-REPORT.md` will read `(skipped — lite mode)` and the dominant-pattern detection will rely on URL/title heuristics alone.
     - Surface the chosen mode + estimated call cost up front. If the user didn't specify and the keyword looks ad-heavy or commercial-high-volume, recommend `mode=lite` first and re-run with `mode=full` only if dominant-pattern confidence is low.

3. **Pull AIO context** (from the same `mcp__dataforseo__serp_organic_live_advanced` response — `mode=full`)
   - If the AI Overview block is present for the keyword, capture the answer text and citation list from the SERP-feature payload.
   - Note which top-10 organic results are also cited in the AIO.

4. **Fetch user's page + top 3 winners** `WebFetch` (always) + `mcp__firecrawl-mcp__firecrawl_scrape` (when available)
   - **WebFetch first** (free): pull markdown for the user's page + top 3 winners. Extract ``, all H-tags, primary content structure (numbered list / table / prose / Q&A), word count, image mentions, comparison-table presence, CTA mentions.
   - **Firecrawl second** (4 Firecrawl credits typical — 1 per page) — recovers what WebFetch can't show:
     - JSON-LD `@type`s per page (Product, FAQPage, BreadcrumbList, Article, Review, ItemList, etc.) — these are **load-bearing** for page-type classification in step 5. WebFetch's markdown can't see schema.
     - `og:title` / `og:image` / `twitter:card` from `metadata`.
     - Real `` length (the markdown first-heading is sometimes wrong).
   - **`--screenshots` flag (opt-in, +4 Firecrawl credits):** when passed, also call `firecrawl_scrape` with `formats: ["screenshot"]` on the user's page + top 3 winners. Save as `screenshots/{page}.png`. Reference in the wireframe (step 8) to ground recommendations in the visual layout, not just the text outline.
   - **If Firecrawl unavailable (or `--no-firecrawl` passed):** WebFetch portion runs. Page-type classification in step 5 falls back to URL/title heuristics + content-structure heuristics only — schema-based classification is skipped. Note in `02-page-type-classification.md`: `Schema-based classification: skipped — Firecrawl required.` Confidence in dominant-pattern detection drops accordingly.

5. **Classify each top-10 result by page type**
   - Use the heuristics in `references/page-type-patterns.md`.
   - For each: assign one of {comparison, alternatives, listicle, how-to, definition, product, editorial, forum, video}.
   - Note signals that informed the classification (URL pattern, title pattern, schema, content structure).

6. **Detect the dominant pattern**
   - Count types in top 10. If one type ≥ 6, that's dominant.
   - If two tie at 4–4, the SERP is "split intent" — both work; commercial vs informational angle determines which to choose.
   - Cross-reference with SERP features: video carousel → expect ≥ 2 video results; PAA → expect informational results; shopping pack → commercial intent dominant; AIO → informational consensus.

7. **Score the user's page** against the dominant pattern × 4 personas
   - Use the rubrics in `references/persona-rubrics.md`.
   - 4 personas: Skimmer, Researcher, Buyer, Validator.
   - 0–10 per persona. Apply the intent-weighting profile (also in persona-rubrics.md) to get a single 0–100 SXO score.

8. **Synthesise verdict and wireframe**
   - If user's page type matches dominant: SXO score reflects how well it executes the pattern. Recommend specific persona-targeted improvements.
   - If user's page type does NOT match dominant: this is the "page-type mismatch" case. Output a wireframe for the dominant page type, anchored in observed patterns from the top 3 winners.
   - Write `SXO-REPORT.md`.

## Output format

Create a folder `seo-sxo-{target-slug}-{YYYYMMDD}/` with:

```
seo-sxo-{target-slug}-{YYYYMMDD}/
├── 01-serp-snapshot.md            (top 10 + features + AIO)
├── 02-page-type-classification.md (each top-10 result classified)
├── 03-user-page-fingerprint.md    (the candidate page's structure)
├── 04-persona-scores.md           (4 personas × current page)
├── 05-recommendation.md           (verdict + page-type-winning wireframe)
├── screenshots/                   (only if --screenshots ran: candidate.png + winner-1/2/3.png)
└── SXO-REPORT.md                  (executive summary deliverable)
```

`SXO-REPORT.md` shape:

```markdown
# SXO Report: {URL} for keyword "{keyword}"

> Snapshot dated {YYYY-MM-DD} · Country: {country}

## SERP profile
- Top 10 page types: {comparison: 4, listicle: 3, editorial: 2, video: 1}
- Dominant pattern: **{pattern}** ({n} of 10)
- SERP features: AIO ✓ ({n} citations), PAA ✓ ({n} questions), Image carousel ✗, Video carousel ✗, Shopping pack ✗
- Intent: {informational | commercial-investigation | transactional | navigational}

## Your page
- Page type: **{detected type}**
- Page-type match with dominant: **{✓ match | ✗ MISMATCH — see Verdict}**
- Word count: {n}
- Primary content structure: {prose | numbered-list | table | step-blocks | Q&A | mixed}

## SXO score: **{score}/100**

| Persona | Weight | Score | Notes |
|---|---|---|---|
| Skimmer | {%} | {n}/10 | {1-line note} |
| Researcher | {%} | {n}/10 | {1-line note} |
| Buyer | {%} | {n}/10 | {1-line note} |
| Validator | {%} | {n}/10 | {1-line note} |

## Verdict

{One paragraph. If page type matches: "Your page is the right type for this SERP. The score gap is {X} points — see persona-specific gaps below." If MISMATCH: "Your page is a {your type} but the SERP rewards {dominant type}. No amount of on-page optimization will close the gap; ship a {dominant type} page instead. Wireframe below."}

## If MISMATCH — wireframe for the winning page type

\`\`\`
{Page title pattern — e.g., "{Brand A} vs {Brand B}: 2026 Comparison"}

[Hero / TL;DR — first 200 words answer the comparative question]
[Comparison table — must be visually dominant]
[Section per dimension — each with H2 named after the dimension]
[Verdict / recommendation — explicit, justified]
[FAQ — top 3–5 PAA questions]
[Schema — Product (×2) + BreadcrumbList + FAQPage]
\`\`\`

## If MATCH — top 3 changes by persona

1. {Skimmer}: {specific change}
2. {Researcher}: {specific change}
3. {Buyer or Validator}: {specific change}

## Raw data
- 02-page-type-classification.md — every top-10 result, classified
- 03-user-page-fingerprint.md — your page's signals
- 04-persona-scores.md — full persona-by-persona breakdown
```

## Tips

- DataForSEO allows up to 2,000 calls/min, 30 concurrent. The SERP calls in step 2/3 are fast; WebFetch calls in step 4 dominate latency, not API.
- **Cost is mode-dependent.** DataForSEO is pay-per-call (no pre-run credit gate). `mode=full` issues one full-depth `serp_organic_live_advanced` call per keyword (the dominant cost); `mode=lite` issues a reduced-`depth` call. Surface the per-keyword call estimate up front, and cap multi-keyword screens by running `mode=lite` first. Step 4 adds 4 Firecrawl credits when Firecrawl is available, +4 more if `--screenshots` is passed. Pass `--no-firecrawl` to skip both.
- **`mode=full` (full-depth `serp_organic_live_advanced`) is the only way to get AIO / PAA / pack data.** A reduced-`depth` lite call returns organic-only. Don't try to reconstruct SERP features from organic results — that's what the full call is for.
- Page-type classification is a heuristic — `references/page-type-patterns.md` documents the signals so users can override. If the heuristic gets a result wrong, edit that file with the correction.
- The 4 personas are opinionated. They come from the framework's original source — don't invent more without good reason.
- The SXO score is directional. An 85/100 doesn't guarantee ranking; a 35/100 strongly suggests the page won't break through. Treat as a diagnostic, not a forecast.
- When the dominant pattern is split-intent (4-4), ship two pages — one per intent — rather than trying to make one page serve both. Google's SERPs reflect this split for a reason.
- The wireframe in MISMATCH mode is a starting point. The user still needs to write the content. This skill diagnoses; `seo-content-brief` produces the writer-ready brief.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [amirjahfar1](https://github.com/amirjahfar1)
- **Source:** [amirjahfar1/automate-seo-with-claude](https://github.com/amirjahfar1/automate-seo-with-claude)
- **License:** MIT
- **Homepage:** https://nextbrainsolutions.com/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-amirjahfar1-automate-seo-with-claude-seo-sxo
- Seller: https://agentstack.voostack.com/s/amirjahfar1
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.