Agent skill

SEO Search Experience Optimization

by AgriciDaniel in AgriciDaniel/claude-seo

Diagnoses ranking problems caused by intent and page-type mismatch by analyzing the live SERP for a keyword, plus user stories and persona scoring.

MITAuto-check passedMarketing & SEO

Install SEO Search Experience Optimization

skills CLI
$ npx skills add AgriciDaniel/claude-seo --skill seo-sxo -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install AgriciDaniel/claude-seo seo-sxo --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/seo-sxo .claude/skills/seo-sxo && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
seo-sxo
GitHub stars
19k
Token cost
~2.5k tokens
SKILL.md length
1,140 words
Files
5 (incl. references)
Skills in repo
33
Repo updated
First seen
Licence
MIT

At a glance

Diagnoses ranking problems caused by intent and page-type mismatch by analyzing the live SERP for a keyword, plus user stories and persona scoring.

  • Works in 7 steps: Target Acquisition → SERP Backwards Analysis → Page-Type Mismatch Detection → …
  • Rankings are weak even though the page is technically healthy
  • SKILL.md covers Core Insight, Commands, Execution Pipeline and DataForSEO Integration, plus 5 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Search experience optimization sits between SEO and UX. Instead of asking whether a page is technically healthy, it asks whether the page deserves to rank given what the SERP rewards, since a well-optimized blog post cannot break through where the results are mostly product or comparison pages. Commands are /seo sxo with a URL, with a URL and keyword, a wireframe mode that produces an IST and SOLL wireframe, and a personas mode that scores personas without the SERP analysis.

The pipeline fetches the target page with render_page.py and parses its title, H1, meta description, headings, word count, schema, CTAs and media with parse_html.py, deriving a keyword from the title and H1 if none is given. It then searches Google and records each of the top 10 results by authority tier, page type, content format, estimated word count, schema and media signals, along with SERP features such as featured snippets and People Also Ask. Four reference files cover page types, personas, user stories and wireframes.

When your agent uses it

  • Rankings are weak even though the page is technically healthy
  • Checking whether a page type matches what the SERP rewards for a keyword
  • Scoring a page from the viewpoint of several searcher personas
  • Producing a wireframe that moves a page toward the format the SERP expects

Example prompts

  • “Run an SXO analysis on https://example.com/crm-software for the keyword best crm for startups.”
  • “Compare my blog post's page type with the top ten results for this keyword.”
  • “Score https://example.com/pricing against the main searcher personas only.”
  • “Generate an IST and SOLL wireframe for this landing page.”

Requirements

  • The claude-seo plugin scripts render_page.py and parse_html.py
  • Web search access to read the live SERP

Workflow steps

7 steps, taken from the step headings in SKILL.md.

  1. Target Acquisition
  2. SERP Backwards Analysis
  3. Page-Type Mismatch Detection
  4. User Story Derivation
  5. Gap Analysis
  6. Persona-Based Scoring
  7. Wireframe Generation (Optional)

What it can do on your machine

Read from SKILL.md and the folder at commit 4b99de2. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

SEO Search Experience Optimization loads about 2.5k tokens when it runs, and up to ~9k if it reads all its reference files. Until then it costs about 43 tokens; SKILL.md has 1,140 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~43
When it runs · the whole SKILL.md, loaded when a task matches
~2.5k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from AgriciDaniel/claude-seo at commit 4b99de2, republished under its MIT licence (© AgriciDaniel). 1,140 words, ~2,545 tokens.

Download SKILL.mdSave it as .claude/skills/seo-sxo/SKILL.md (or your agent's skills folder). This skill also uses 4 other files; get the full folder from GitHub.
name
seo-sxo
description
Diagnose search-experience and intent mismatches using SERP page types, user stories, and persona scoring. Use when ranking problems appear intent- or layout-driven.
user-invocable
true
argument-hint
<url> [keyword]
license
MIT
metadata.author
AgriciDaniel
metadata.original_author
Florian Schmitz (Pro Hub Challenge)
metadata.version
2.4.2
metadata.category
seo

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

CommandPurpose
/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 "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run render_page.py <URL> --mode auto (SPA-aware and SSRF-safe)
  2. Parse with "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run parse_html.py <URL> 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 currently supported SERP features; exclude 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 TypeSERP ExpectsSeverityRecommendation
Blog PostProduct PagesCRITICALCreate dedicated product page
Blog PostComparisonHIGHRestructure as comparison with matrix
ProductInformationalHIGHAdd educational content layer
Landing PageTool/CalculatorHIGHBuild interactive tool component
Service PageLocal ResultsMEDIUMAdd location signals + local schema
Any type match-ALIGNEDFocus 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:

DimensionWhat to CompareScore
Page TypeTarget type vs SERP dominant type0-15
Content DepthWord count, heading depth, topic coverage0-15
UX SignalsCTA clarity, above-fold content, mobile layout0-15
Schema MarkupPresent vs expected structured data types0-15
Media RichnessImages, video, interactive elements vs SERP norm0-15
Authority SignalsE-E-A-T markers, social proof, credentials0-15
FreshnessLast updated, date signals, content recency0-10

Total: 0-100 SXO Gap Score (lower = larger gap, higher = better alignment)

Show full SKILL.md (494 more words)Show less
Step 6: Persona-Based Scoring

Read references/persona-scoring.md for methodology.

  1. Derive 4-7 personas from SERP intent signals:
    • Cluster PAA questions by theme
    • Segment ad copy by target audience
    • Map related searches to journey stages
  2. For each persona, score the target page on 4 dimensions (25 pts each):
    • Relevance: Does the page address this persona's need?
    • Clarity: Can this persona find their answer within 10 seconds?
    • Trust: Are there adequate trust signals for this persona?
    • Action: Is there a clear next step for this persona?
  3. Output persona cards with scores and specific improvement recommendations
  4. Sort recommendations by weakest persona first (biggest opportunity)
Step 7: Wireframe Generation (Optional)

Only execute when /seo sxo wireframe is invoked.

Read references/wireframe-templates.md for templates.

  1. Generate IST (current state) wireframe from parsed page structure
  2. Generate SOLL (target state) wireframe based on:
    • SERP consensus page type
    • Gap analysis findings
    • Persona scoring weaknesses
  3. Use ultra-concrete placeholders:
    • NOT: "Add a CTA here"
    • YES: "Add pricing CTA with annual savings badge below hero, linking to /pricing#enterprise"
  4. Output as semantic HTML section outline with annotations

DataForSEO Integration

If DataForSEO MCP tools are available:

  1. Before any API call, run cost estimate and confirm with user
  2. Use serp_organic_live_advanced for precise SERP data (positions, features, snippets)
  3. Use kw_data_google_ads_search_volume for search volume and competition metrics
  4. Fall back to WebSearch if DataForSEO unavailable -- note reduced precision in output

SXO Score vs SEO Health Score

The SXO score is separate from the main SEO Health Score.

  • SEO Health Score = technical compliance (crawlability, speed, schema, etc.)
  • SXO Gap Score = alignment between page and SERP expectations
  • A page can score 95 SEO + 30 SXO = technically perfect but strategically misaligned
  • Both scores should be reported together when both are available

Cross-Skill References

FindingHand Off To
E-E-A-T gaps in persona scoring/seo content for deep E-E-A-T audit
Missing schema types/seo schema for generation
Local intent detected in SERP/seo local for GBP analysis
Content depth gaps/seo page for deep page analysis
Technical issues found during fetch/seo technical for full audit
Image/media gaps/seo images for optimization

Output Format

Full SXO Analysis
## SXO Analysis: [URL]
### Target Keyword: [keyword]

### 1. SERP Landscape
- Dominant page type: [type] ([confidence]% consensus)
- SERP features: [list]
- Content depth norm: [word count range]
- Schema expectation: [types]

### 2. Page-Type Alignment
- Your page type: [type]
- SERP expects: [type]
- Verdict: [ALIGNED | MISMATCH (severity)]
- Impact: [explanation]

### 3. User Stories (derived from SERP signals)
[3-5 user stories with source signals]

### 4. Gap Analysis (SXO Score: XX/100)
[7-dimension breakdown table]

### 5. Persona Scores
[4-7 persona cards with 4-dimension scores]

### 6. Priority Actions
[Ranked list: fix mismatch first, then weakest persona gaps]

### 7. Limitations
[What could not be assessed, data source notes]

Error Handling

ErrorAction
URL fetch failsReport error, suggest checking URL accessibility
No keyword provided or detectedAsk user to provide target keyword
WebSearch returns <5 resultsProceed with available data, note limited sample
SERP has no organic results (all ads)Note highly commercial SERP, analyze ad copy only
Target page is JavaScript-renderedNote limitation, use available HTML content
DataForSEO cost exceeds thresholdFall back to WebSearch, notify user

Quality Checklist

Before delivering results, verify:

  • Target URL was fetched via "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run render_page.py <URL> --mode auto (not raw curl/fetch)
  • Page type classification uses taxonomy from references
  • At least 5 SERP results were analyzed
  • User stories cite specific SERP signals as evidence
  • Persona scores include concrete improvement suggestions
  • SXO score is clearly labeled as separate from SEO Health Score
  • Limitations section is present and honest
  • Cross-skill recommendations are included where relevant

© AgriciDaniel, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 4 other files (references) in skills/seo-sxo of AgriciDaniel/claude-seo.

  • SKILL.md
  • references/page-type-taxonomy.md
  • references/persona-scoring.md
  • references/user-story-framework.md
  • references/wireframe-templates.md

Open the folder on GitHubat commit 4b99de2

Compare with similar skills

SEO Search Experience Optimization next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

SEO Search Experience Optimization compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
SEO Search Experience Optimization this skillAgriciDaniel/claude-seo19k—~2.5kAutomated safety check: PassMIT
SEO Optimizerailabs-393/ai-labs-claude-skills4551 repos~3.2kAutomated safety check: PassMIT
GEO Platform Optimizerzubair-trabzada/geo-seo-claude11k2 repos~4.7kAutomated safety check: NotesMIT
SEO PageAgriciDaniel/codex-seo7995 repos~1.2kAutomated safety check: PassMIT
E2E SEO Assistantirinabuht12-oss/marketing-skills4.1k—~1.9kAutomated safety check: PassNone
SEO Auditandrew-yangy/gru-ai155—~731Automated safety check: PassMIT

Similar skills

  • SEO Optimizer

    ailabs-393/ai-labs-claude-skills

    This skill should be used when analyzing HTML/CSS websites for SEO optimization, fixing SEO issues, generating SEO reports, or implementing SEO best practices.

    455 GitHub starsUsed in 1 repo~3.2k tokens
    Marketing & SEOAuto-check passed
  • GEO Platform Optimizer

    zubair-trabzada/geo-seo-claude

    Audits a site for AI search visibility one platform at a time, scoring Google AI Overviews, ChatGPT, Perplexity, Gemini and Bing Copilot and listing gaps to fix.

    11k GitHub starsUsed in 2 repos~4.7k tokens
    Marketing & SEOAuto-check: notes
  • SEO Page

    AgriciDaniel/codex-seo

    Deep single-page SEO analysis covering on-page elements, content quality, technical meta tags, schema, images, and performance.

    799 GitHub starsUsed in 5 repos~1.2k tokens
    Marketing & SEOAuto-check passed
  • E2E SEO Assistant

    irinabuht12-oss/marketing-skills

    Full SEO workflow covering technical audits, content gaps, backlink opportunities, on-page fixes, and content briefs.

    4.1k GitHub stars~1.9k tokensUpdated 17 days ago
    Marketing & SEOAuto-check passed
  • SEO Audit

    andrew-yangy/gru-ai

    Full website SEO audit with parallel subagent delegation. An agent skill from andrew-yangy/gru-ai.

    155 GitHub stars~731 tokensUpdated 7 mo ago
    Marketing & SEOAuto-check passed
  • Geo Meta Tags Audit

    thedaviddias/Front-End-Checklist

    Audits and fixes geo.region, geo.placename and geo.position meta tags on regional pages, noting where they help (Bing) and where they do not (Google).

    74k GitHub stars~763 tokensUpdated 4 days ago
    Marketing & SEOAuto-check passed

More from AgriciDaniel/claude-seo

All 33 skills in this repo
  • Hreflang and International SEO

    AgriciDaniel/claude-seo

    Audits, validates and generates hreflang tags for multi-language and multi-region sites in HTML, HTTP headers or XML sitemaps, flagging common code and return-tag mistakes.

    19k GitHub starsUsed in 5 repos~3.4k tokens
    Auto-check passed
  • Google SEO APIs

    AgriciDaniel/claude-seo

    Pulls real Google data for SEO work: Search Console, PageSpeed Insights, CrUX field data, the Indexing API and GA4 organic traffic, through /seo google commands.

    19k GitHub starsUsed in 1 repo~4.2k tokens
    Auto-check passed
  • SEO Keyword Clustering

    AgriciDaniel/claude-seo

    Clusters keywords by how much their search results overlap and designs a hub-and-spoke content plan with an internal link matrix and an interactive cluster map.

    19k GitHub starsUsed in 2 repos~3.3k tokens
    Auto-check passed
  • SEO Content Brief Generator

    AgriciDaniel/claude-seo

    Builds research-backed SEO content briefs with competitor scoring, per-section word counts and page-type templates, for new pages or improving existing ones.

    19k GitHub starsUsed in 2 repos~2.6k tokens
    Auto-check passed
  • FLOW SEO Framework

    AgriciDaniel/claude-seo

    Brings the FLOW framework's stage-specific SEO prompts into the agent, from keyword discovery through backlinks, on-page work and conversion to local SEO, loaded on demand.

    19k GitHub starsUsed in 2 repos~1.4k tokens
    Auto-check passed
  • SEO Image Generator

    AgriciDaniel/claude-seo

    Generates Open Graph previews, blog hero images, product photos and infographics for SEO use through Gemini image tools and the banana extension.

    19k GitHub starsUsed in 2 repos~2.1k tokens
    Auto-check passed

Categories

Questions about SEO Search Experience Optimization

What does SEO Search Experience Optimization do?

Diagnoses ranking problems caused by intent and page-type mismatch by analyzing the live SERP for a keyword, plus user stories and persona scoring. Search experience optimization sits between SEO and UX. Instead of asking whether a page is technically healthy, it asks whether the page deserves to rank given what the SERP rewards, since a well-optimized blog post cannot break through where the results are mostly product or comparison pages.

When should I use SEO Search Experience Optimization?

SEO Search Experience Optimization fits situations like: rankings are weak even though the page is technically healthy; checking whether a page type matches what the SERP rewards for a keyword; scoring a page from the viewpoint of several searcher personas; producing a wireframe that moves a page toward the format the SERP expects.

How do I install SEO Search Experience Optimization in Claude Code?

Run `npx skills add AgriciDaniel/claude-seo --skill seo-sxo -a claude-code`. Or copy the skill folder (skills/seo-sxo in AgriciDaniel/claude-seo) into .claude/skills/seo-sxo in your project. Claude Code loads it when a task matches its description.

How do I install SEO Search Experience Optimization in Codex?

Run `npx skills add AgriciDaniel/claude-seo --skill seo-sxo -a codex`. Or copy the skill folder (skills/seo-sxo in AgriciDaniel/claude-seo) into .agents/skills/seo-sxo in your project. Codex loads it when a task matches its description.

Can I use SEO Search Experience Optimization in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add AgriciDaniel/claude-seo --skill seo-sxo -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/seo-sxo, .gemini/skills/seo-sxo, .github/skills/seo-sxo and .opencode/skills/seo-sxo in your project.

What does SEO Search Experience Optimization need to run?

SKILL.md names no scripts, command-line tools or credentials: SEO Search Experience Optimization is instructions for the agent only. Our summary lists: The claude-seo plugin scripts render_page.py and parse_html.py; Web search access to read the live SERP.

Does SEO Search Experience Optimization access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is SEO Search Experience Optimization safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does SEO Search Experience Optimization use?

SEO Search Experience Optimization is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does SEO Search Experience Optimization use?

About 2.5k tokens (SKILL.md is roughly 10k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 6.5k tokens, read only when the agent opens those files.

What are the alternatives to SEO Search Experience Optimization?

Skills that share tags, products or a category with SEO Search Experience Optimization: SEO Optimizer (ailabs-393/ai-labs-claude-skills, 455 stars), GEO Platform Optimizer (zubair-trabzada/geo-seo-claude, 11k stars), SEO Page (AgriciDaniel/codex-seo, 799 stars) and E2E SEO Assistant (irinabuht12-oss/marketing-skills, 4.1k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains SEO Search Experience Optimization?

AgriciDaniel (a GitHub user) maintains it in AgriciDaniel/claude-seo, which has 18,627 GitHub stars. The repository holds 33 skills in this directory. The repository was last updated on October 4, 2026.

Source: AgriciDaniel/claude-seo on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.