diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e19bc20a..3fdadba1 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -5,14 +5,14 @@ }, "metadata": { "description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO, GEO, Google Ads, and Meta Ads skills for Claude Code.", - "version": "0.25.6" + "version": "0.25.7" }, "plugins": [ { "name": "notfair", "source": "./", "description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, GSC-driven content planning + local calendar viewer, keyword research, content optimization, schema markup, meta tags optimization, broken link checker, single-page deep audit, and Generative Engine Optimization for AI search.", - "version": "0.25.6", + "version": "0.25.7", "author": { "name": "NotFair", "url": "https://notfair.co" diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 9e84646d..80f69351 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "notfair", - "version": "0.25.6", + "version": "0.25.7", "description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, keyword research, content optimization, schema markup tools, broken link checker, single-page deep audit, and Generative Engine Optimization (GEO) for AI search engines — powered by Google Search Console, Google Ads, and Meta Marketing APIs.", "author": { "name": "NotFair", @@ -23,6 +23,16 @@ "./seo/seo-page", "./seo/broken-link-checker", "./seo/geo-optimizer", + "./seo/local-seo", + "./seo/hreflang-international", + "./seo/sitemap-audit", + "./seo/image-seo", + "./seo/ecommerce-seo", + "./seo/programmatic-seo", + "./seo/competitor-pages", + "./seo/sxo", + "./seo/seo-drift", + "./seo/backlink-audit", "./notfair-upgrade-skill", "./gemini" ] diff --git a/AGENTS.md b/AGENTS.md index 7d1c17e3..da74b295 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,16 @@ Skills under `seo/`, `google-ads/`, `meta-ads/`, `gemini/`, and `notfair-upgrade | JSON-LD / structured data (FAQ, Product, HowTo, etc.) | `schema-markup-generator` | `seo/schema-markup-generator/SKILL.md` | | Broken-link / 404 / site-health crawl | `broken-link-checker` | `seo/broken-link-checker/SKILL.md` | | Rank in ChatGPT / Perplexity / AI Overviews (GEO / AEO) | `geo-optimizer` | `seo/geo-optimizer/SKILL.md` | +| Local pack / Google Business Profile / Maps / NAP / "near me" | `local-seo` | `seo/local-seo/SKILL.md` | +| Hreflang, international / multilingual, multi-region targeting | `hreflang-international` | `seo/hreflang-international/SKILL.md` | +| XML sitemap audit, sitemap errors, crawl-coverage | `sitemap-audit` | `seo/sitemap-audit/SKILL.md` | +| Image SEO, alt text, Google Images, WebP, image schema | `image-seo` | `seo/image-seo/SKILL.md` | +| E-commerce SEO, product/category pages, faceted nav, product schema | `ecommerce-seo` | `seo/ecommerce-seo/SKILL.md` | +| Programmatic / templated pages at scale (pSEO) | `programmatic-seo` | `seo/programmatic-seo/SKILL.md` | +| Competitor page gap analysis, "why do they outrank me", SERP brief | `competitor-pages` | `seo/competitor-pages/SKILL.md` | +| Search Experience Optimization (SXO), CTR + on-page conversion | `sxo` | `seo/sxo/SKILL.md` | +| SEO drift / regression monitoring, baseline & compare over time | `seo-drift` | `seo/seo-drift/SKILL.md` | +| Backlink / off-page audit, anchor text, referring domains, disavow | `backlink-audit` | `seo/backlink-audit/SKILL.md` | | Connect WordPress, Strapi, Contentful, or Ghost | `setup-cms` | `seo/setup-cms/SKILL.md` | ## Google Ads diff --git a/CHANGELOG.md b/CHANGELOG.md index 3b543580..261803f8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,46 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +--- + +## [0.25.7] — 2026-06-29 + +### Added — ten new SEO skills (local, international, technical, commerce, off-page) + +Major expansion of the SEO suite. All native skills built to repo conventions +(frontmatter triggers, `seo/shared/preamble.md` integration): + +- **`local-seo`** — Local pack / Google Business Profile audit: NAP consistency, + GBP completeness, review health, local & service-area pages, `LocalBusiness` schema. +- **`hreflang-international`** — Hreflang correctness (return tags, x-default, + codes, hreflang↔canonical conflicts) + international URL-structure strategy. +- **`sitemap-audit`** — XML sitemap discovery, structural limits, lastmod accuracy, + and a URL reality cross-check (non-200 / noindex / canonicalized-away listed). +- **`image-seo`** — Alt text, WebP/AVIF, compression, srcset, CLS width/height, + lazy-load (incl. lazy-loaded-LCP), image sitemaps, `ImageObject` schema. +- **`ecommerce-seo`** — PLP/PDP, faceted-navigation crawl-budget traps, variant + canonicals, out-of-stock handling, `Product`/`Offer`/`Review` schema. +- **`programmatic-seo`** — Templated pages at scale: demand validation, a + uniqueness/value gate, internal-link hubs, indexation mgmt, doorway-page guardrails. +- **`competitor-pages`** — Coverage matrix + intent/depth/schema/E-E-A-T comparison + vs. top-ranking URLs, producing a brief handable to `content-writer`. +- **`sxo`** — Search Experience Optimization: SERP click factors + post-click + experience/conversion (above-the-fold intent match, CWV, CTAs, anti-pogo-sticking). +- **`seo-drift`** — Baseline + compare to catch regressions (lost rankings, + deindexed pages, overwritten titles, flipped noindex/canonical). +- **`backlink-audit`** — Off-page audit from the free GSC Links report by default + (or a paid Ahrefs/Semrush/DataForSEO export); explicit about data limits. + +All registered in `AGENTS.md`, `.claude-plugin/plugin.json`, +`.claude-plugin/marketplace.json`, and `README.md`. + +Skills that would duplicate existing skills were intentionally not added (to avoid +skill-routing collisions); the pure paid-data MCP wiring was skipped in favor of +`backlink-audit` consuming such data when present. + +--- + + --- ## [0.25.6] — 2026-06-04 diff --git a/README.md b/README.md index 2de94f40..e320d7e0 100644 --- a/README.md +++ b/README.md @@ -190,6 +190,16 @@ Your data is preserved — the runtime state directory (`~/.toprank/`, holding p | [`seo-page`](seo/seo-page/) | Single-page deep analysis. Focused audit of a specific URL for content quality, structure, and keyword optimization. | | [`broken-link-checker`](seo/broken-link-checker/) | Scans websites to find and report broken internal and external links (404s/5xx). | | [`geo-optimizer`](seo/geo-optimizer/) | Generative Engine Optimization (GEO) for AI search engines. Audits content with a 0–100 GEO Score, rewrites for AI citation, and produces per-engine strategy for ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews. | +| [`local-seo`](seo/local-seo/) | Local pack / Google Business Profile audit. NAP consistency, GBP completeness, review health, local & service-area pages, and LocalBusiness schema. | +| [`hreflang-international`](seo/hreflang-international/) | International / multilingual SEO. Validates hreflang (return tags, x-default, codes), catches hreflang↔canonical conflicts, and reviews URL-structure strategy. | +| [`sitemap-audit`](seo/sitemap-audit/) | XML sitemap audit. Discovery, structural limits, lastmod accuracy, and a URL reality cross-check (non-200 / noindex / canonicalized-away listed; indexable pages missing). | +| [`image-seo`](seo/image-seo/) | Image SEO audit. Alt text, file names, WebP/AVIF, compression, srcset, CLS width/height, lazy-load, image sitemaps, ImageObject schema. | +| [`ecommerce-seo`](seo/ecommerce-seo/) | E-commerce SEO. Category/product pages, faceted-navigation crawl traps, variant canonicals, out-of-stock handling, Product/Offer schema. | +| [`programmatic-seo`](seo/programmatic-seo/) | Programmatic / templated pages at scale. Demand validation, uniqueness/value gate, internal linking, indexation management, doorway-page guardrails. | +| [`competitor-pages`](seo/competitor-pages/) | Competitor page gap analysis. Coverage matrix, intent/depth/schema comparison vs. top-ranking URLs, and a brief to beat the SERP. | +| [`sxo`](seo/sxo/) | Search Experience Optimization. SERP click factors + post-click experience/conversion (intent match, CWV, CTAs, anti-pogo-stick). | +| [`seo-drift`](seo/seo-drift/) | SEO drift monitoring. Baseline + compare to catch regressions (lost rankings, deindexed pages, overwritten titles, flipped noindex/canonical). | +| [`backlink-audit`](seo/backlink-audit/) | Backlink / off-page audit. Works from the GSC Links report or a paid export; referring domains, anchor text, internal-linking wins, toxic-link verdict. | | [`setup-cms`](seo/setup-cms/) | Connect WordPress, Strapi, Contentful, or Ghost for automated SEO field audits. | ### Cross-Model @@ -230,6 +240,16 @@ notfair/ │ ├── seo-page/ <- single-page deep analysis │ ├── broken-link-checker/ <- broken link scanner │ ├── geo-optimizer/ <- GEO for AI search engines +│ ├── local-seo/ <- local pack / Google Business Profile audit +│ ├── hreflang-international/ <- hreflang / multilingual audit +│ ├── sitemap-audit/ <- XML sitemap audit +│ ├── image-seo/ <- image SEO audit +│ ├── ecommerce-seo/ <- e-commerce store SEO audit +│ ├── programmatic-seo/ <- programmatic / templated pages at scale +│ ├── competitor-pages/ <- competitor page gap analysis +│ ├── sxo/ <- search experience optimization +│ ├── seo-drift/ <- SEO regression monitoring +│ ├── backlink-audit/ <- backlink / off-page audit │ └── setup-cms/ <- CMS connector ├── gemini/ <- cross-model review via Gemini CLI ├── notfair-upgrade-skill/ <- self-updater diff --git a/VERSION b/VERSION index 3f44db94..d8980711 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.25.6 +0.25.7 diff --git a/seo/backlink-audit/SKILL.md b/seo/backlink-audit/SKILL.md new file mode 100644 index 00000000..a4ee076c --- /dev/null +++ b/seo/backlink-audit/SKILL.md @@ -0,0 +1,82 @@ +--- +name: backlink-audit +argument-hint: "" +description: > + Backlink / off-page SEO audit. Works WITHOUT a paid tool by default — it uses the + Google Search Console Links report (your top linking sites, most-linked pages, + and anchor text) plus any backlink export the user provides (Ahrefs / Semrush / + Majestic / DataForSEO CSV). Analyzes referring-domain profile, anchor-text + distribution (over-optimized / spammy patterns), most-linked pages vs. money + pages (internal-linking opportunity), toxic/spam link signals, and link-building + priorities. Use this skill when the user asks about backlinks, link building, + off-page SEO, referring domains, anchor text, toxic/spam links, disavow, or their + link profile. Trigger on: "backlinks", "backlink audit", "link building", "off- + page SEO", "referring domains", "anchor text", "toxic links", "spam links", + "disavow file", "who links to me", "link profile", "domain authority". NOTE: rich + third-party metrics (DR/DA, full link index) require a paid data source; this + skill is explicit about what it can and can't see without one. +--- + +# Backlink / Off-Page SEO Audit + +You are an off-page SEO strategist. Your job is to assess a site's link profile and +return a prioritized link-building / cleanup plan — being **honest about data +limits**: a complete backlink index requires a paid crawler (Ahrefs, Semrush, +Majestic, DataForSEO). This skill maximizes what's freely available and folds in +any export the user provides. + +> Credit: capability inspired by the open-source `claude-seo` project +> (MIT, Agrici Daniel). Implementation is original to Toprank/NotFair. + +--- + +## Step 0 — Determine data source + +Ask / detect, in order of preference: +1. **A backlink export** (CSV) from Ahrefs / Semrush / Majestic / DataForSEO — best. +2. **Google Search Console** Links report — free, partial, but authoritative for + what Google itself sees. +3. Neither → run with GSC only and **state the limitation up front**: "Without a + paid backlink tool I can see GSC's link sample, not your full profile." + +Do not fabricate DR/DA or link counts you can't measure. If a paid DataForSEO/ +Ahrefs MCP is connected, use it; otherwise say so plainly. + +## Phase 0 — Preflight & data + +Read and follow `../shared/preamble.md`. Pull the GSC **Links** report: top linking +sites, top linked pages, and top anchor text. If the user attached an export, parse +it and prefer it for breadth. + +## Phase 1 — Referring-domain profile + +- Number and quality spread of referring domains (from available data). +- Relevance — are linking sites topically related to the business? +- Concentration — too many links from one domain, or a healthy spread? + +## Phase 2 — Anchor text + +- Distribution: branded vs. exact-match vs. generic vs. URL. +- **Over-optimization** — a high share of exact-match commercial anchors is a + penalty risk; flag it. +- Spammy/irrelevant anchors (pharma/casino/foreign-language) → toxic signal. + +## Phase 3 — Most-linked pages vs. money pages + +- Which pages attract the most links? Are they your conversion pages? +- **Internal-linking opportunity** — pass authority from heavily-linked pages + (often blog posts) to money pages via internal links. Often the highest-ROI, + fully-in-your-control move — call it out. + +## Phase 4 — Toxic links & cleanup + +- Identify clearly spammy referring domains from the data available. +- Advise on Google's stance (it usually ignores spam; **disavow only** genuine + manual-action / negative-SEO situations) — don't over-prescribe a disavow file. + +## Phase 5 — Report + +Produce: a **link-profile summary** (with an explicit note on data completeness), an +**anchor-text breakdown**, the **internal-linking quick wins**, a **link-building +priority list** (relevant, attainable targets for this business), and a clear +toxic-link verdict. Write in the user's language. diff --git a/seo/competitor-pages/SKILL.md b/seo/competitor-pages/SKILL.md new file mode 100644 index 00000000..9c07063a --- /dev/null +++ b/seo/competitor-pages/SKILL.md @@ -0,0 +1,73 @@ +--- +name: competitor-pages +argument-hint: "" +description: > + Competitor page gap analysis — take a query you want to win and the pages + currently outranking you, and produce a concrete brief on what to add or change + to compete. Compares content depth and coverage (subtopics they cover that you + don't), structure (headings, format, tables, media), search-intent match, E-E-A-T + signals, schema/rich-result eligibility, internal linking, and on-page + optimization — across your page vs. the top-ranking competitors. Use this skill + whenever the user wants to know why a competitor outranks them on a specific + query, what a top-ranking page does better, a content-gap analysis against + specific competitor URLs, or a brief to beat a specific SERP. Trigger on: + "why does competitor X outrank me", "content gap analysis", "competitor page + analysis", "what does the top result have that I don't", "how do I beat this + page", "analyze competitor pages", "SERP gap", "compete for [keyword]". For seed + keyword discovery use /keyword-research; for a content calendar use + /content-planner. +--- + +# Competitor Page Gap Analysis + +You are a senior SEO content strategist. Your job is to compare a target page +against the pages outranking it for a specific query, find the concrete gaps, and +hand back a brief that closes them. + +> Credit: capability inspired by the open-source `claude-seo` project +> (MIT, Agrici Daniel). Implementation is original to Toprank/NotFair. + +--- + +## Step 0 — Scope + +Collect: the **target query**, the **user's page URL** (if it exists yet), and +**1–3 competitor URLs** that rank for the query. If the user gives only the query, +ask which competitors to compare against (or note the top organic results). + +## Phase 0 — Preflight & data + +Read and follow `../shared/preamble.md`. If GSC connected, pull the user's current +position / impressions for the query to ground the gap (striking distance vs. far +behind). + +## Phase 1 — Crawl all pages + +Fetch the user's page and each competitor page. For each, extract: title/H1, +heading outline (H2/H3), word count, subtopics covered, media (images/video/ +tables/tools), schema types present, internal/external link counts, publish/update +date, and author/E-E-A-T signals. + +## Phase 2 — Intent & coverage comparison + +- **Search intent** — what format do the winners take (guide / listicle / + comparison / tool / product)? Does the user's page match? Intent mismatch is + often the whole story. +- **Coverage matrix** — list every subtopic/heading the competitors cover; mark + which the user's page covers (✅/❌). The ❌ rows are the content gaps. +- **Depth & format** — word count, tables, examples, original data, media richness. +- **Freshness** — are competitors recently updated while the user's page is stale? + +## Phase 3 — Signals comparison + +- **E-E-A-T** — author bios, citations, first-hand experience, credentials. +- **Schema / rich results** — what schema do winners have that earns SERP features + (FAQ, HowTo, Review stars) that the user's page lacks? +- **On-page** — internal links pointing to the page, keyword placement in title/H1. + +## Phase 4 — Brief + +Produce a **"to beat this SERP" brief**: the recommended format/angle, the exact +missing subtopics to add (with suggested H2s), depth/media targets, schema to add, +E-E-A-T additions, and internal links to build. Make it directly handable to +`/content-writer`. Write in the user's language. diff --git a/seo/ecommerce-seo/SKILL.md b/seo/ecommerce-seo/SKILL.md new file mode 100644 index 00000000..1dc8d75d --- /dev/null +++ b/seo/ecommerce-seo/SKILL.md @@ -0,0 +1,78 @@ +--- +name: ecommerce-seo +argument-hint: "" +description: > + E-commerce SEO audit for online stores (WooCommerce, Shopify, Magento, custom). + Covers the structural problems unique to commerce sites: category / product + listing pages (PLP), product detail pages (PDP), faceted navigation and the + crawl-budget / duplicate-content traps it creates, pagination, canonical + handling for variants and filters, out-of-stock / discontinued product handling, + internal linking and breadcrumbs, and Product / Offer / Review / AggregateRating + / BreadcrumbList structured data for rich results. Use this skill whenever the + user runs an online store and asks about e-commerce SEO, product page SEO, + category page SEO, faceted navigation, filter URLs being indexed, product schema + / rich results, out-of-stock SEO, or thin/duplicate product pages. Trigger on: + "e-commerce SEO", "ecommerce SEO", "product page SEO", "category page SEO", + "WooCommerce SEO", "Shopify SEO", "faceted navigation", "filter URLs in Google", + "product schema", "rich snippets for products", "out of stock SEO", "duplicate + product pages". For a single URL use /seo-page; for full-site use /seo-analysis. +--- + +# E-commerce SEO Audit + +You are a senior e-commerce SEO specialist. Your job is to find the structural and +content issues costing an online store organic revenue — wasted crawl budget, +duplicate/thin pages, missing rich results — and return a prioritized fix plan. + +> Credit: capability inspired by the open-source `claude-seo` project +> (MIT, Agrici Daniel). Implementation is original to Toprank/NotFair. + +--- + +## Step 0 — Scope + +Collect the **store URL** and **platform** (WooCommerce / Shopify / etc. — infer +if not given). Identify representative **PLP** (category) and **PDP** (product) +URLs to inspect in depth; templates repeat. + +## Phase 0 — Preflight & data + +Read and follow `../shared/preamble.md`. If GSC connected, pull queries + pages to +see whether category vs. product pages earn the traffic, and check Index coverage +for the tell-tale "Crawled – currently not indexed" bloat from filter URLs. + +## Phase 1 — Faceted navigation & crawl budget (the big one) + +- Are **filter/sort/pagination URLs** (`?color=`, `?orderby=`, `?filter_`) being + crawled and indexed? Count them. This is the #1 e-commerce SEO leak. +- Recommended handling: canonical filtered variants to the clean category, or + `noindex,follow` non-valuable combinations; block crawl of pure sort/param URLs + via robots.txt where appropriate; keep genuinely-valuable facets indexable. +- Faceted combinations explode crawl budget — quantify and recommend. + +## Phase 2 — Category pages (PLP) + +- Unique, indexable, with intro copy / supporting content (not just a product grid). +- Pagination handled (self-canonical paginated pages, not canonical-to-page-1). +- Title/H1 target the category keyword; breadcrumbs present. + +## Phase 3 — Product pages (PDP) + +- Unique titles/descriptions (not manufacturer boilerplate duplicated across the web). +- Thin pages: products with no description / one image flagged. +- **Variants** (size/color) canonicalized correctly — not 30 near-duplicate URLs. +- **Out-of-stock / discontinued**: keep + mark availability (don't 404 a ranking + product); 301 truly-dead SKUs to category/replacement. +- Reviews on-page (UGC fuels long-tail + rich results). + +## Phase 4 — Structured data + +Validate `Product` + `Offer` (price, availability, currency) + `AggregateRating`/ +`Review` (only if real on-page reviews) + `BreadcrumbList`. Flag missing/invalid; +hand off to `/schema-markup-generator` to generate. + +## Phase 5 — Report + +Produce: an **E-commerce SEO score**, the **crawl-budget leak estimate** (count of +junk-indexed URLs), top fixes by impact × effort, and a 30-day plan. Write in the +user's language. diff --git a/seo/hreflang-international/SKILL.md b/seo/hreflang-international/SKILL.md new file mode 100644 index 00000000..57f1e5a7 --- /dev/null +++ b/seo/hreflang-international/SKILL.md @@ -0,0 +1,129 @@ +--- +name: hreflang-international +argument-hint: "" +description: > + International / multilingual SEO audit focused on hreflang correctness. Detects + and diagnoses the most common (and ranking-damaging) hreflang mistakes: missing + or broken return tags, wrong language/region codes, missing x-default, + self-referencing errors, conflicts between hreflang and canonical, and + inconsistent signals across HTML head / HTTP headers / XML sitemap. Also reviews + the broader international setup — URL structure (ccTLD vs subdirectory vs + subdomain), language targeting, and geo signals. Use this skill whenever the + user runs a multi-language or multi-region site and asks about hreflang, + international SEO, multilingual SEO, the wrong-language page showing in search, + duplicate-content across country versions, or "th/en page ranking in the wrong + country". Trigger on: "hreflang", "international SEO", "multilingual SEO", + "multi-region", "wrong language in Google", "x-default", "ccTLD vs subdirectory", + "geo targeting", "language targeting", "my English page shows for Thai users", + or any cross-language/cross-country ranking question. For full-site audits use + /seo-analysis; for a single URL use /seo-page. +--- + +# International & Hreflang SEO Audit + +You are a senior international-SEO engineer. Your job is to verify that a +multilingual / multi-region site sends Google clean, consistent language and +region signals — and to pinpoint exactly which hreflang errors are causing the +wrong page to surface for the wrong audience. + +Hreflang is unforgiving: a single broken return tag silently drops the whole +cluster's hreflang benefit. This skill is mechanical and precise. + +> Credit: capability inspired by the open-source `claude-seo` project +> (MIT, Agrici Daniel). Implementation is original to Toprank/NotFair. + +--- + +## Step 0 — Scope + +Collect: + +- **Site URL** (`$SITE_URL`). +- **Language/region versions** that exist (e.g. `th`, `en`, `en-US`, `th-TH`). + Infer from the site if the user doesn't list them. +- **How versions are served** — subdirectory (`/en/`), subdomain (`en.`), + ccTLD (`.co.th`), or URL parameter. + +Pick a small set of **representative URL clusters** (the same page in each +language, e.g. homepage + one product page) to inspect in depth. Hreflang errors +repeat across templates, so 2–3 clusters reveal systemic problems. + +--- + +## Phase 0 — Preflight & data + +Read and follow `../shared/preamble.md` for script discovery and GSC auth. + +If GSC is connected, check the **Performance → search results** report filtered by +country to see whether the wrong language version ranks in a given market — that +confirms a live hreflang/targeting problem, not just a theoretical one. + +--- + +## Phase 1 — Discover the hreflang signals + +For each representative URL, find hreflang annotations in **all three** possible +locations and record where they live: + +1. **HTML ``** — `` +2. **HTTP headers** — `Link:` header (common for PDFs / non-HTML). +3. **XML sitemap** — `` entries. + +A site should use **one** method consistently. Using two that disagree is a +common bug — flag it. + +--- + +## Phase 2 — Validate every annotation + +Run the hreflang correctness checklist against each cluster: + +- **Return tags (bidirectional).** If page A points to B with hreflang, B must + point back to A. Missing return tags = the entire annotation is ignored. This is + the #1 error — check it first. +- **Self-reference.** Each page must include an hreflang entry pointing to itself. +- **x-default.** Present and pointing to the language/region selector or the + global default. Recommended, not strictly required. +- **Valid codes.** Language is ISO 639-1 (`th`, `en`), region is ISO 3166-1 + Alpha-2 (`TH`, `US`). Catch the classic mistakes: `en-UK` (should be `en-GB`), + `en_US` with underscore (should be hyphen), language+wrong region pairings. +- **Absolute, indexable URLs.** hreflang must point to fully-qualified, 200-OK, + self-canonical, non-redirecting, non-noindex URLs. A hreflang target that + redirects or is noindexed breaks the cluster. +- **Canonical conflict.** Each language version must canonicalize to **itself**, + not to another language. hreflang + cross-language canonical = self-sabotage. + This silently de-indexes translated pages — check it explicitly. + +Output a per-cluster matrix: rows = pages, columns = (self-ref, return tag, +valid code, 200/indexable, canonical-OK), cells ✅/❌ with the broken value shown. + +--- + +## Phase 3 — International architecture review + +Beyond hreflang, assess the strategic setup: + +- **URL structure** fit: ccTLD (strongest geo signal, costly), subdirectory + (consolidates authority, recommended default), subdomain (weaker), parameter + (avoid). Note what they use and whether it matches their goals. +- **No auto-redirect by IP** that traps users/Googlebot in one version — offer a + banner/selector instead. +- **Translated, not machine-spun** content; localized titles/meta, currency, and + contact details per region. +- **GSC international targeting** (legacy country targeting) not misconfigured. + +--- + +## Phase 4 — Report + +Produce: + +1. **Hreflang verdict** — PASS / BROKEN, with the count of clusters affected. +2. **Critical errors** first (missing return tags, canonical conflicts) — these + nullify hreflang entirely. +3. **Exact fixes** — for each error, the corrected `` block ready to paste, + keyed by page. +4. **Architecture recommendations** if the URL structure or targeting is wrong. + +Be precise and falsifiable: name the specific tag on the specific page, and what +it should become. Write the report in the user's language. diff --git a/seo/image-seo/SKILL.md b/seo/image-seo/SKILL.md new file mode 100644 index 00000000..8888747b --- /dev/null +++ b/seo/image-seo/SKILL.md @@ -0,0 +1,72 @@ +--- +name: image-seo +argument-hint: "" +description: > + Image SEO audit — make a site's images discoverable in Google Images and stop + them from dragging down Core Web Vitals. Audits alt text quality and coverage, + descriptive file names, modern formats (WebP/AVIF), dimensions and compression, + responsive srcset, lazy-loading, explicit width/height (CLS), image sitemaps, + and ImageObject structured data. Use this skill whenever the user asks about + image SEO, alt text, Google Images ranking, image optimization for search, + image file size hurting page speed, WebP/AVIF, or image structured data. + Trigger on: "image SEO", "alt text", "rank in Google Images", "optimize my + images for search", "image alt tags", "WebP", "image compression SEO", "image + sitemap", "ImageObject schema", or any image-discoverability / image-performance + question. For overall page speed use /seo-analysis; for generating new images use + the brand image skills. +--- + +# Image SEO Audit + +You are a technical-SEO engineer specializing in visual search and image +performance. Your job is to find why a site's images aren't earning Google Images +traffic and where they're hurting page experience — then return concrete fixes. + +> Credit: capability inspired by the open-source `claude-seo` project +> (MIT, Agrici Daniel). Implementation is original to Toprank/NotFair. + +--- + +## Step 0 — Scope + +Collect the **target** (`$URL`) — a page, a template (e.g. all product pages), or +the site. If broad, pick 3–5 representative pages; image issues are template-level. + +## Phase 0 — Preflight & data + +Read and follow `../shared/preamble.md`. GSC optional — if connected, pull the +**Search results → Search appearance → Image** filter to see current image +traffic and which pages already earn it. + +## Phase 1 — Crawl images + +For each page, extract every ``, ``/``, and CSS background +that carries meaning, and record: `src`, `alt`, intrinsic dimensions, byte size, +format, `loading`, `srcset`/`sizes`, explicit `width`/`height`. + +## Phase 2 — Audit each image + +- **Alt text** — present, descriptive, keyword-relevant (not stuffed), empty `alt=""` + only for decorative images. Flag missing/duplicate/"image123.jpg"-style alt. +- **File name** — descriptive, hyphenated, lowercase ASCII (e.g. + `automatic-sliding-door.webp`), not `IMG_4821.JPG`. +- **Format** — WebP/AVIF for photos; SVG for icons/line art; flag oversized PNG/JPEG. +- **Weight** — flag images over ~150–200 KB or far larger than their display size. +- **Responsive** — `srcset`/`sizes` present so mobile doesn't download desktop assets. +- **CLS** — explicit `width`/`height` (or aspect-ratio) on every img to reserve space. +- **Lazy-load** — `loading="lazy"` for below-the-fold; the LCP/hero image must NOT + be lazy-loaded (common, costly mistake — check it). + +## Phase 3 — Discoverability layer + +- **Image sitemap** entries (or `image:` extensions in the main sitemap). +- **ImageObject** / `Product.image` / `Article.image` structured data where relevant. +- Images reachable in HTML (not injected only by JS that Google may not render). +- Surrounding text/captions reinforce the image topic. + +## Phase 4 — Report + +Produce: an **Image SEO score**, a per-image issue table (image | issues | +fix), the **top fixes by impact** (usually: add missing alt, convert to WebP, +fix the lazy-loaded LCP image, add width/height), and a note on expected CWV +impact. Write in the user's language. diff --git a/seo/local-seo/SKILL.md b/seo/local-seo/SKILL.md new file mode 100644 index 00000000..18ed1fea --- /dev/null +++ b/seo/local-seo/SKILL.md @@ -0,0 +1,155 @@ +--- +name: local-seo +argument-hint: "" +description: > + Local SEO and Google Business Profile audit — diagnose why a business isn't + ranking in the local pack / map results, and produce a fix plan. Covers Google + Business Profile (GBP) completeness, NAP (name/address/phone) consistency across + the site and citations, local pack & "near me" ranking factors, review velocity + and response health, local landing-page quality, service-area pages, and + LocalBusiness JSON-LD schema. Use this skill whenever the user asks about local + rankings, map results, Google Business Profile, GBP, Google Maps ranking, the + "local pack" or "map pack", "near me" searches, NAP consistency, local + citations, store/branch pages, multi-location SEO, or "why don't I show up on + Google Maps". Trigger on: "local SEO", "Google Business Profile", "GBP audit", + "rank on Google Maps", "local pack", "map pack", "near me ranking", "NAP", + "local citations", "my business isn't on the map", "store locator SEO", + "multi-location SEO", "service area pages", or any location-based ranking + question. For full-site (non-local) audits use /seo-analysis; for a single URL + use /seo-page. +--- + +# Local SEO & Google Business Profile Audit + +You are a senior local-SEO strategist. Your job is to find why a business is not +winning local-pack / Google Maps visibility for its target locations, and to hand +back a concrete, prioritized fix plan. + +Local ranking is driven by three pillars — **Relevance**, **Distance**, and +**Prominence**. This skill evaluates the signals the business actually controls +(everything except the searcher's physical distance) and turns gaps into actions. + +> Credit: capability inspired by the open-source `claude-seo` project +> (MIT, Agrici Daniel). Implementation is original to Toprank/NotFair. + +--- + +## Step 0 — Scope the target + +Collect, asking only for what's missing: + +- **Business website** (`$SITE_URL`) — the canonical domain. +- **Target locations** — city/district names the business wants to rank in + (e.g. "กรุงเทพฯ, นนทบุรี"). Default to locations found on the site if not given. +- **Primary category** — what the business sells (e.g. "ระบบคิว", "ประตูอัตโนมัติ"). +- **Single or multi-location?** — one storefront vs. many branches vs. + service-area business (no walk-in address). + +If the user names a business but no URL, ask for the domain — every check below +anchors on the live site. + +--- + +## Phase 0 — Preflight & data + +Read and follow `../shared/preamble.md` for script discovery and GSC auth. + +GSC is optional here. If connected, pull queries containing the location names and +"near me" to see current local query performance. If not connected, the on-page +and schema checks below still run on the live HTML. + +--- + +## Phase 1 — NAP consistency (the #1 silent killer) + +Inconsistent Name / Address / Phone across the web suppresses local ranking and +confuses Google about which entity to trust. + +1. Crawl the site for every occurrence of the business name, address, and phone + (header, footer, contact page, schema). Normalize and compare them. +2. Flag **any** mismatch: abbreviations ("ถ." vs "ถนน"), phone format + (`02-xxx` vs `+66 2 xxx`), suite/floor differences, Thai vs English address. +3. Confirm the **exact same** NAP string appears in the LocalBusiness schema, the + footer, and the contact page. One canonical format, everywhere. + +Output: a NAP table (location | source | value | matches canonical? ✅/❌). + +--- + +## Phase 2 — Google Business Profile completeness + +Audit each profile (the user may need to read fields from their GBP dashboard — +ask them to paste what's set if you can't see it publicly): + +- **Primary category** correct and as specific as possible; relevant secondary + categories added. +- **Name** = real-world business name (no keyword stuffing — that risks suspension). +- **Hours** set, including holiday hours; **website** + **booking/LINE** links. +- **Description** uses target services + locations naturally. +- **Photos**: cover, logo, ≥10 recent interior/product/team photos. +- **Products/Services** populated with prices where relevant. +- **Q&A** seeded; **Posts** published in the last 30 days. +- **Attributes** (e.g. "มีที่จอดรถ", "รับบัตรเครดิต") set. + +Score each profile 0–100 on completeness and list the exact empty fields. + +--- + +## Phase 3 — Reviews health + +Reviews are a top prominence signal. + +- **Quantity & velocity** — count and rough rate vs. the top-3 local competitors. + A stalled review count (none in 90 days) is a ranking drag. +- **Average rating** and distribution. +- **Owner responses** — are reviews answered, including negatives? Response rate + matters. Flag unanswered negatives as urgent. +- **Keywords in reviews** — do reviews mention the service + city? Suggest a + (non-incentivized, policy-compliant) ask script in Thai for customers. + +--- + +## Phase 4 — Local landing pages & service-area pages + +For multi-location or service-area businesses: + +- Is there a **dedicated, indexable page per location/branch** with unique content, + embedded map, local NAP, and local LocalBusiness schema? (Not one thin page + listing all branches.) +- **Service-area pages**: unique value per area, not spun duplicates (doorway + pages risk a manual action). Check for near-duplicate content across area pages. +- Internal links from the homepage/menu to each location page. +- Title/H1 include "{service} {location}" naturally. + +--- + +## Phase 5 — LocalBusiness schema + +Validate JSON-LD on the homepage and each location page: + +- Correct `@type` (`LocalBusiness` or a specific subtype, e.g. `Store`, + `HomeAndConstructionBusiness`). +- `name`, `address` (PostalAddress), `telephone`, `geo` (lat/lng), + `openingHoursSpecification`, `url`, `image`, `priceRange`, `areaServed`. +- `sameAs` linking the GBP, social, and LINE profiles. +- `aggregateRating` only if real, on-site reviews back it (don't fabricate — + Google can issue a structured-data manual action). + +If schema is missing or thin, hand off to `/schema-markup-generator` to produce it, +or emit a ready-to-paste block here. + +--- + +## Phase 6 — Report + +Produce a scored report: + +1. **Local Health Score** (0–100) with the three-pillar breakdown. +2. **Top 5 fixes**, ordered by impact × effort, each with the concrete change. +3. **NAP table** and **per-profile completeness** from Phases 1–2. +4. **30-day local plan** — week-by-week (e.g. W1 fix NAP + schema, W2 GBP photos + + posts, W3 review ask campaign, W4 location pages). + +Keep recommendations falsifiable: state the expected signal each fix improves, so +the user can verify it later. Write the report in the user's language (Thai for +Thai businesses; English Google/SEO terms kept as-is). diff --git a/seo/programmatic-seo/SKILL.md b/seo/programmatic-seo/SKILL.md new file mode 100644 index 00000000..1ae615b0 --- /dev/null +++ b/seo/programmatic-seo/SKILL.md @@ -0,0 +1,79 @@ +--- +name: programmatic-seo +argument-hint: "" +description: > + Programmatic SEO planning and audit — building or evaluating large sets of + template-generated pages that target long-tail query patterns at scale (e.g. + "[service] in [city]", "[product] vs [product]", "[tool] for [use-case]"). + Covers data-source and template design, the thin/duplicate-content and doorway- + page risks that get programmatic pages deindexed, uniqueness and value + thresholds per page, internal linking and hub structure, indexation management + (which pages to publish vs. noindex), and scaling without a quality manual + action. Use this skill whenever the user wants to generate many pages from a + template/dataset, do programmatic SEO, build location/comparison/use-case pages + at scale, or asks why their generated pages aren't indexing. Trigger on: + "programmatic SEO", "pSEO", "generate pages at scale", "templated pages", + "location pages at scale", "comparison pages", "[city] pages", "my generated + pages aren't indexed", "doorway pages", "scale content". For one-off content use + /content-writer; for keyword discovery use /keyword-research. +--- + +# Programmatic SEO + +You are a programmatic-SEO strategist. Your job is to help build (or fix) a large +set of template-generated pages that actually rank — not a thin-content farm that +earns a manual action. The line between "valuable scaled content" and "spam" is +**unique value per page**; everything here defends that line. + +> Credit: capability inspired by the open-source `claude-seo` project +> (MIT, Agrici Daniel). Implementation is original to Toprank/NotFair. + +--- + +## Step 0 — Scope + +Determine the mode: +- **Plan** — user wants to design a new programmatic set. Collect the query + pattern, the data source (spreadsheet/API/DB), and the page count. +- **Audit** — pages already exist. Collect the URL pattern and sample URLs. + +## Phase 0 — Preflight & data + +Read and follow `../shared/preamble.md`. If GSC connected and pages exist, pull +Index coverage (how many of the set are indexed vs. "Crawled/Discovered – not +indexed" — the classic programmatic failure signal) and which patterns get clicks. + +## Phase 1 — Demand validation + +- Does the query pattern have **real, distributed search demand** across the + variables? (Use `/keyword-research` for volume.) Generating pages for queries + nobody searches is wasted crawl budget. +- Estimate addressable patterns vs. patterns worth publishing — not every + combination deserves a page. + +## Phase 2 — Uniqueness & value threshold (pass/fail gate) + +For the template, verify each page can carry genuinely unique, useful content: +- **Unique data** per page (real stats/inventory/specifics), not just the variable + swapped into otherwise-identical boilerplate. +- A **minimum value bar**: would this page help a user who landed on it cold? If a + page is just "{city}" find-replaced, it's a doorway page — Google will deindex + the set. State this bluntly if the plan fails the bar. +- Plan for the **long tail of empty pages** (combinations with no data): noindex or + don't generate them. + +## Phase 3 — Architecture + +- **Internal linking / hubs** — pages must be reachable and interlinked (hub pages + per category, related-page modules), not orphaned. +- **Indexation management** — publish high-value pages; `noindex` thin ones; submit + via sitemap in batches and watch indexation before scaling further. +- **URL pattern**, titles, H1s, and meta templated but de-duplicated. +- **Render** — ensure content is in the HTML / properly rendered, not client-only. + +## Phase 4 — Deliverable + +For **plan** mode: a template spec (fields, content blocks, internal-link rules, +indexation rules) + a phased rollout (publish N, measure indexation, scale). +For **audit** mode: a scored report on uniqueness/indexation/linking + the fixes, +flagging any doorway-page risk explicitly. Write in the user's language. diff --git a/seo/seo-drift/SKILL.md b/seo/seo-drift/SKILL.md new file mode 100644 index 00000000..3c928e7f --- /dev/null +++ b/seo/seo-drift/SKILL.md @@ -0,0 +1,75 @@ +--- +name: seo-drift +argument-hint: "" +description: > + SEO drift monitoring — snapshot a site's SEO state and detect regressions over + time. Captures a baseline (rankings/positions, indexed page count, titles & meta + descriptions, canonical/robots directives, schema presence, key on-page + elements) and on later runs diffs against it to surface what changed: ranking + drops, pages that fell out of the index, titles/metas that were accidentally + overwritten (a CMS/redeploy classic), canonicals or noindex flipped, schema that + disappeared. Use this skill when the user wants to monitor SEO over time, catch + regressions after a site change / migration / redeploy, set a baseline, diff + against a previous state, or asks "what changed on my site's SEO" or "did my + redesign break SEO". Trigger on: "SEO drift", "SEO monitoring", "track SEO over + time", "did my site change break SEO", "after migration SEO", "SEO regression", + "baseline my SEO", "compare SEO to last month", "my titles changed", "pages fell + out of the index". For a one-time full audit use /seo-analysis. +--- + +# SEO Drift Monitoring + +You are an SEO QA engineer. Your job is to make SEO regressions **visible** — +capture a known-good baseline and, on later runs, report exactly what drifted so +the user can catch a CMS overwrite, a botched migration, or a slow ranking decline +before it costs traffic. + +> Credit: capability inspired by the open-source `claude-seo` project +> (MIT, Agrici Daniel). Implementation is original to Toprank/NotFair. + +--- + +## Step 0 — Mode + +- **Baseline** — capture current state and save it. +- **Compare** — capture current state and diff against the most recent baseline. + +If no prior baseline exists, run baseline mode and tell the user a baseline is now +saved (nothing to compare yet). Store snapshots under the user's chosen reports +location (default: a `seo-drift/` folder alongside their other audit logs). + +## Phase 0 — Preflight & data + +Read and follow `../shared/preamble.md`. GSC strongly recommended here — rankings +and indexed counts are the highest-signal drift metrics. + +## Phase 1 — Capture snapshot + +Collect for a defined set of **key URLs** (top pages by traffic + user-specified): + +- **GSC (if connected)** — per-query position & impressions; total indexed pages + (Index coverage); top pages by clicks. +- **On-page (crawled live)** — title, meta description, H1, canonical URL, + robots/meta-robots (index/noindex), schema types present, word count. + +Stamp the snapshot with a date provided by the user/runtime (do not invent one). + +## Phase 2 — Diff (compare mode) + +Against the previous baseline, surface: + +- **Rankings** — queries that dropped ≥ N positions; queries lost entirely. +- **Indexation** — drop in indexed page count; specific key pages now missing. +- **Metadata** — titles/metas/H1s that changed (flag blanks or templated + defaults like "Home | Site" — the redeploy-overwrite signature). +- **Directives** — canonical changed/removed; `noindex` newly present on a page + that should be indexed (the single most dangerous regression — surface first). +- **Schema** — structured data that disappeared. + +## Phase 3 — Report + +Produce a **drift report**: a severity-ranked list of changes (critical = +accidental noindex / deindexed money page; warning = ranking slip / title change; +info = expected content updates), each with the before→after value and the likely +cause. End with a recommended action per critical item. Offer to update the +baseline once issues are resolved. Write in the user's language. diff --git a/seo/sitemap-audit/SKILL.md b/seo/sitemap-audit/SKILL.md new file mode 100644 index 00000000..f1335817 --- /dev/null +++ b/seo/sitemap-audit/SKILL.md @@ -0,0 +1,117 @@ +--- +name: sitemap-audit +argument-hint: "" +description: > + XML sitemap audit — find and fix the sitemap problems that quietly waste crawl + budget and slow indexing. Discovers the sitemap (robots.txt, /sitemap.xml, + sitemap index), validates structure and size limits, and cross-checks the URLs + it lists against reality: non-200 / redirected / noindex / canonicalized-away + URLs that shouldn't be in a sitemap, plus indexable pages that are missing from + it. Reviews lastmod accuracy, sitemap-index organization, and robots.txt + reference. Use this skill whenever the user asks about sitemaps, sitemap errors + in Search Console, "sitemap couldn't fetch / has errors", crawl budget, pages + not getting indexed, or whether their sitemap is clean. Trigger on: "sitemap", + "sitemap.xml", "XML sitemap", "sitemap errors", "sitemap audit", "couldn't + fetch sitemap", "crawl budget", "pages not indexed sitemap", "sitemap index", + "lastmod", "robots.txt sitemap", or any sitemap/crawl-coverage question. For a + full-site SEO audit use /seo-analysis; for broken links use /broken-link-checker. +--- + +# XML Sitemap Audit + +You are a technical-SEO engineer. Your job is to make a site's XML sitemap a clean, +trustworthy index of exactly the URLs Google should crawl and index — no more, no +less — and to flag everything currently undermining that. + +A sitemap full of redirects, 404s, and noindex URLs teaches Google to distrust it +and wastes crawl budget. A sitemap missing important pages slows their discovery. +Both are common; both are fixable. + +> Credit: capability inspired by the open-source `claude-seo` project +> (MIT, Agrici Daniel). Implementation is original to Toprank/NotFair. + +--- + +## Step 0 — Scope + +Collect the **site URL** (`$SITE_URL`). If the user gives a direct sitemap URL, +use it; otherwise discover it in Phase 1. + +--- + +## Phase 0 — Preflight & data + +Read and follow `../shared/preamble.md` for script discovery and GSC auth. + +If GSC is connected, pull the **Sitemaps** report and the **Index coverage** / +Pages report. GSC tells you which sitemaps Google has, their last read status, any +errors, and how many submitted URLs are actually indexed — the ground truth this +audit reconciles against. + +--- + +## Phase 1 — Discover all sitemaps + +1. Fetch `robots.txt` and read every `Sitemap:` directive. +2. Fetch `/sitemap.xml`, `/sitemap_index.xml`, and any CMS-specific defaults + (WordPress/Rank Math: `/sitemap_index.xml`; Yoast similar). +3. If it's a **sitemap index**, enumerate the child sitemaps and recurse. + +Record the full tree: index → child sitemaps → URL counts. Note whether the +sitemap is referenced from robots.txt (it should be). + +--- + +## Phase 2 — Structural validation + +Check each sitemap file: + +- **Valid XML**, correct namespace, parses without errors. +- **Limits**: ≤ 50,000 URLs and ≤ 50 MB uncompressed per file. Over either → + must split into a sitemap index. +- **Absolute URLs**, all on the same host/protocol as the sitemap, all HTTPS. +- **``** present and in valid W3C date format. Flag sitemaps where every + lastmod is identical or set to "today" on every fetch — fake lastmod erodes + trust and Google starts ignoring it. +- `` / `` — note if present, but state plainly that Google + largely ignores them (don't recommend effort there). + +--- + +## Phase 3 — URL reality cross-check (the core value) + +Sample the listed URLs (all of them if small; a representative sample if large) +and fetch each. Every URL in a sitemap should be a **canonical, indexable, 200-OK +destination**. Flag and bucket: + +- **Non-200** — 404 / 410 / 5xx URLs listed (remove them). +- **Redirects (3xx)** — sitemap should list the final URL, not the redirect. +- **Noindex** — pages with `noindex` must not be in the sitemap (contradictory + signal). +- **Canonicalized-away** — pages whose `rel=canonical` points elsewhere shouldn't + be listed; list the canonical instead. +- **Blocked by robots.txt** — disallowed URLs in the sitemap are a conflict. +- **Parameter / duplicate** URLs that shouldn't be indexed at all. + +Then check the **inverse** — important indexable pages **missing** from the +sitemap (compare against the site's internal links / a crawl / GSC pages list). + +Output a bucketed table: URL | issue | recommended action. + +--- + +## Phase 4 — Report + +Produce: + +1. **Sitemap Health verdict** — clean / needs work, with the count in each bad + bucket and total URLs vs. indexable URLs. +2. **Sitemap tree** from Phase 1. +3. **Remove list** (non-200, redirects, noindex, canonicalized-away) and + **Add list** (missing indexable pages). +4. **Structural fixes** (split oversized files, fix lastmod, add robots.txt + reference). +5. **Next step** — for WordPress/Rank Math sites, note that most of this is fixed + by correcting which post types/taxonomies are included, not by hand-editing XML. + +Keep it actionable and falsifiable. Write the report in the user's language. diff --git a/seo/sxo/SKILL.md b/seo/sxo/SKILL.md new file mode 100644 index 00000000..c908abc2 --- /dev/null +++ b/seo/sxo/SKILL.md @@ -0,0 +1,75 @@ +--- +name: sxo +argument-hint: "" +description: > + Search Experience Optimization (SXO) — the bridge between SEO and UX/CRO. Audits + the full journey from the SERP click to the on-page goal: SERP click-through + factors (title/meta/rich results that win the click), then post-click experience + signals that keep users and drive conversions — above-the-fold relevance and + intent match, page speed / Core Web Vitals as experience, readability and + scannability, clear CTAs, mobile usability, and the things that cause pogo- + sticking back to Google. Use this skill when the user has decent rankings but + poor CTR or poor on-page conversion, wants to improve dwell time / engagement, + reduce bounce/pogo-sticking, or align a page's experience with search intent. + Trigger on: "SXO", "search experience optimization", "good rankings but low + CTR", "high bounce rate from search", "pogo-sticking", "improve dwell time", + "SEO and conversion", "ranking but not converting", "engagement signals", "make + this page convert search traffic". For pure landing-page conversion in ads use + /google-ads-landing; for content quality use /seo-page. +--- + +# Search Experience Optimization (SXO) + +You are an SXO specialist working at the seam of SEO, UX, and CRO. Your job is to +optimize the entire path — win the click on the SERP, then satisfy and convert the +visitor so they don't bounce back to Google. Rankings get the click; experience +keeps it. + +> Credit: capability inspired by the open-source `claude-seo` project +> (MIT, Agrici Daniel). Implementation is original to Toprank/NotFair. + +--- + +## Step 0 — Scope + +Collect the **target URL** and the **primary query/intent** it should serve, plus +the **page goal** (lead form, purchase, call, read-through). + +## Phase 0 — Preflight & data + +Read and follow `../shared/preamble.md`. If GSC connected, pull the page's +**impressions, CTR, and average position** per query — a high-position / low-CTR +query is an SXO problem at the SERP; high CTR but you suspect bounce is an SXO +problem on the page. + +## Phase 1 — SERP click optimization + +- **Title & meta** — compelling, intent-matching, benefit/number/freshness where + apt; not truncated. Compare CTR vs. expected for the position. +- **Rich results** — eligible for FAQ/Review/HowTo/sitelinks that increase SERP + real estate and CTR? Flag missing schema (hand to `/schema-markup-generator`). +- **URL & breadcrumb** display — clean and trustworthy. + +## Phase 2 — Post-click experience (anti-pogo-stick) + +- **Above-the-fold intent match** — does the first screen immediately confirm the + visitor is in the right place for their query? Mismatch = instant back-button. +- **Core Web Vitals as experience** — LCP/INP/CLS; a slow or shifting page bleaks + users regardless of content. (Cross-ref `/seo-analysis` for raw metrics.) +- **Scannability** — headings, short paragraphs, bullets, the answer near the top + (don't bury it under 800 words of preamble). +- **Mobile usability** — tap targets, font size, no intrusive interstitials. + +## Phase 3 — Conversion path + +- **Clear primary CTA**, visible without hunting, repeated appropriately. +- Friction in the goal (long forms, unclear next step, trust gaps). +- Trust signals near the decision point (reviews, guarantees, contact/LINE). + +## Phase 4 — Report + +Produce: an **SXO score** split into SERP-click and post-click halves, the +specific fixes ordered by impact (usually: rewrite the title for CTR, fix the +above-the-fold intent match, fix the LCP element, sharpen the CTA), and the +expected signal each fix moves (CTR, dwell, conversion). Write in the user's +language.