Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

feat(seo): add 10 SEO skills — local, international, technical, commerce, off-page (v0.25.7)

pawit200843e9c4d77cea
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: "<site URL — optionally attach a backlink export CSV from GSC/Ahrefs/Semrush>"
+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: "<your page URL + 1-3 competitor URLs ranking for the same query>"
+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: "<store URL, e.g. https://example.com or a category/product URL>"
+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: "<website URL, e.g. https://example.com>"
+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 `<head>`** — `<link rel="alternate" hreflang="..." href="..." />`
+2. **HTTP headers** — `Link:` header (common for PDFs / non-HTML).
+3. **XML sitemap** — `<xhtml:link rel="alternate" hreflang="...">` 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 `<link>` 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: "<website URL or page URL, e.g. https://example.com/products>"
+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 `<img>`, `<picture>`/`<source>`, 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: "<business name or website URL, e.g. https://example.com or 'Dolly Solutions Bangkok'>"
+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: "<site URL + the templated page pattern, e.g. https://example.com/[city]-[service]>"
+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: "<site URL — optionally 'baseline' to snapshot or 'compare' to diff>"
+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: "<website URL or sitemap URL, e.g. https://example.com or https://example.com/sitemap.xml>"
+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.
+- **`<lastmod>`** 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.
+- `<priority>` / `<changefreq>` — 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: "<page or site URL, e.g. https://example.com/landing>"
+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.