agentleFS
amirjahfar1amirjahfar1/automate-seo-with-claude/skills/seo-sxo/SKILL.md

seo-sxo

Skill2 starsChanged 5 months agoMITView on GitHub

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 mismatch", or wants a wireframe.

21 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use seo-agentic, public-relations and 8 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • AgriciDanielSkill

    seo-agentic

    Audit and fix agent readiness: the Lighthouse Agentic Browsing fraction, accessibility tree for agents, robots.txt and Content-Signal for AI agents, WAF treatment of agent traffic, llms.txt, Markdown delivery, ai-catalog.json, /.well-known discovery files, and WebMCP tools. Use when the user asks whether AI agents can use or browse the site, or about llms.txt or WebMCP. Exclude AI citability and brand signals (seo-geo) and commerce protocol depth (seo-ecommerce).

    Also in 4 projects that use this

  • CesarjoquinSkill

    public-relations

    When the user wants help with public relations, earned media, press coverage, journalist outreach, or media strategy (not pull requests). Also use when the user mentions 'PR,' 'public relations,' 'press,' 'press release,' 'press coverage,' 'media outreach,' 'pitch a journalist,' 'get featured,' 'media list,' 'media kit,' 'press kit,' 'newsjacking,' 'news hijack,' 'HARO,' 'Qwoted,' 'Featured,' 'Help A Reporter,' 'reporter request,' 'tech press,' 'TechCrunch,' 'earned media,' 'thought leadership placement,' 'op-ed,' 'guest article,' 'press contacts,' or 'how do I get press.' Use this for earned media work — finding journalists, pitching stories, newsjacking, and responding to press requests. For startup/SaaS/AI directory submissions, see directory-submissions. For product launches, see launch. For social-media engagement, see social. For cold-email outreach to prospects, see cold-email.

    Also in 3 projects that use this

  • prayceoSkill

    product-marketing

    Applies Meghan Keaney Anderson and Mary Sheehan's Mastering Product Marketing frameworks to build influence and demonstrate impact by delivering great products to market successfully. Covers product positioning, go-to-market strategy, and launch planning and tiering. Activates when making decisions about your product's positioning, planning feature or product launches, defining go-to-market strategy, or crafting product messaging. For pricing and packaging frameworks, see consumer-subscription. Triggers when someone asks about positioning, go-to-market, launch planning, competitive differentiation, or says "how should we position this?" or "how do we launch this feature?

    Also in 3 projects that use this

  • insight68Skill

    pricing

    Help figure out pricing for a product or service using minimalist entrepreneur principles. Use when someone is setting prices, considering price changes, or struggling with what to charge.

    Also in 3 projects that use this

  • AnasX7Skill

    minimalist-ui

    Clean editorial-style interfaces. Warm monochrome palette, typographic contrast, flat bento grids, muted pastels. No gradients, no heavy shadows.

    Also in 4 projects that use this

  • megastepSkill

    ads

    Comprehensive paid advertising audit and optimization for any business type. Performs full multi-platform audits (Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads, Microsoft Ads), single-platform deep analysis, conversion tracking health checks, creative quality assessment, budget allocation optimization, bidding strategy evaluation, and compliance verification. Industry detection for SaaS, e-commerce, local service, B2B enterprise, info products, mobile app, real estate, healthcare, finance, and agency. Triggers on: "ads", "PPC", "paid advertising", "Google Ads", "Meta Ads", "Facebook Ads", "LinkedIn Ads", "TikTok Ads", "Microsoft Ads", "Bing Ads", "ad audit", "campaign audit", "ROAS", "conversion tracking", "creative fatigue", "bid strategy".

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 5 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 20 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If the AI Overview block is present for the keyword, capture the answer text and citation list from the SERP-feature payload.

    line 33
  2. Very specific:

    --screenshots flag (opt-in, +4 Firecrawl credits): when passed, also call firecrawl_scrape with formats: ["screenshot"] on the user's …

    line 42
  3. Very specific:

    Use the heuristics in references/page-type-patterns.md.

    line 46
  4. Distinctive:

    If two tie at 4–4, the SERP is "split intent" — both work.

    line 52
  5. Very specific:

    Use the rubrics in references/persona-rubrics.md.

    line 56
  6. Distinctive:

    If user's page type matches dominant: SXO score reflects how well it executes the pattern.

    line 61
  7. Distinctive:

    If user's page type does NOT match dominant: this is the "page-type mismatch" case.

    line 62
  8. Very specific:

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

    line 67
  9. Distinctive:

    When the dominant pattern is split-intent (4-4), ship two pages — one per intent — rather than trying to make one page serve both.

    line 145

“Common” is measured: kept by at least 6 in 10 of the 20 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Example output: 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 <title>, 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 @types 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 <title> 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:

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.