Skip to content

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

fix(seo): keep skill descriptions under the 1024-character limit (#126)

Deepanshu Pal44019679837c
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index eca7d79b..478f12cf 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -5,14 +5,14 @@
},
"metadata": {
"description": "The official ads, analytics, SEO, and GEO plugin from NotFair.",
- "version": "0.27.11"
+ "version": "0.27.12"
},
"plugins": [
{
"name": "notfair",
"source": "./",
"description": "Operate Google, Meta, X, LinkedIn, Reddit, and TikTok Ads; WordPress and GoHighLevel; analyze Search Console and GA4; and run open-source SEO, GEO, and content workflows.",
- "version": "0.27.11",
+ "version": "0.27.12",
"author": {
"name": "NotFair",
"url": "https://notfair.co"
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index add61cad..dc1701ff 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "notfair",
- "version": "0.27.11",
+ "version": "0.27.12",
"description": "The official ads, analytics, SEO, and GEO plugin from NotFair. Operate Google, Meta, X, LinkedIn, Reddit, and TikTok Ads; WordPress and GoHighLevel; analyze Google Search Console and GA4; and run open-source search and content workflows from any compatible agent.",
"author": {
"name": "NotFair",
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 20d04d45..2c60b6e0 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "notfair",
- "version": "0.27.11",
+ "version": "0.27.12",
"description": "The official ads, analytics, SEO, and GEO plugin from NotFair.",
"author": {
"name": "NotFair",
diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
index 1ec848c2..2f536cb3 100644
--- a/.cursor-plugin/plugin.json
+++ b/.cursor-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "notfair",
"displayName": "NotFair",
- "version": "0.27.11",
+ "version": "0.27.12",
"description": "One NotFair OAuth MCP for Google, Meta, X, LinkedIn, Reddit, and TikTok Ads, GA4, Search Console, GoHighLevel, and WordPress, plus open-source SEO, GEO, and content skills.",
"author": {
"name": "Notfair",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 05a4a59a..e28f72b9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,12 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [Unreleased]
+## [0.27.12] — 2026-09-23
+
+### Fixed
+
+- Seven SEO skill descriptions (`seo-analysis`, `hreflang-international`, `ecommerce-seo`, `local-seo`, `sxo`, `programmatic-seo`, `seo-page`) were over the 1024-character description limit. They are trimmed in both `seo/` and the Codex `skills/` wrappers with every quoted trigger phrase and cross-skill pointer kept, and a unit test now enforces the limit and keeps wrapper descriptions in sync with their canonical skills.
+
## [0.27.11] — 2026-09-21
### Fixed
diff --git a/VERSION b/VERSION
index adb8d6a4..26363026 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.27.11
+0.27.12
diff --git a/gemini-extension.json b/gemini-extension.json
index e2e2341b..f2c3ada7 100644
--- a/gemini-extension.json
+++ b/gemini-extension.json
@@ -1,6 +1,6 @@
{
"name": "notfair",
- "version": "0.27.11",
+ "version": "0.27.12",
"description": "Operate ads and analytics, and run open-source SEO, GEO, and content workflows with NotFair.",
"contextFileName": "AGENTS.md",
"mcpServers": {
diff --git a/plugin.json b/plugin.json
index ca9ffe2b..4816f4a9 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,7 +1,7 @@
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "notfair",
- "version": "0.27.11",
+ "version": "0.27.12",
"description": "Operate Google, Meta, X, LinkedIn, Reddit, and TikTok Ads plus GA4, Search Console, GoHighLevel, and WordPress through one OAuth MCP, and run open-source SEO, GEO, and content workflows.",
"author": {
"name": "NotFair",
diff --git a/seo/ecommerce-seo/SKILL.md b/seo/ecommerce-seo/SKILL.md
index e6f43060..9cd523db 100644
--- a/seo/ecommerce-seo/SKILL.md
+++ b/seo/ecommerce-seo/SKILL.md
@@ -3,19 +3,17 @@ 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.
+ Covers category / product listing pages (PLP), product detail pages (PDP), faceted
+ navigation and its crawl-budget and duplicate-content traps, pagination,
+ canonicals for variants and filters, out-of-stock / discontinued products,
+ internal linking and breadcrumbs, and Product / Offer / Review / AggregateRating /
+ BreadcrumbList structured data. Use whenever the user runs an online store and
+ asks about product or category page SEO, filter URLs being indexed, product rich
+ results, 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
diff --git a/seo/hreflang-international/SKILL.md b/seo/hreflang-international/SKILL.md
index e8f32a36..56040881 100644
--- a/seo/hreflang-international/SKILL.md
+++ b/seo/hreflang-international/SKILL.md
@@ -2,20 +2,18 @@
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
+ International / multilingual SEO audit focused on hreflang correctness: missing or
+ broken return tags, wrong language/region codes, missing x-default,
+ self-referencing errors, hreflang vs canonical conflicts, and inconsistent signals
+ across HTML head, HTTP headers and XML sitemap. Also reviews URL structure (ccTLD
+ vs subdirectory vs subdomain), language targeting and geo signals. Use whenever
+ the user runs a multi-language or multi-region site and asks about hreflang,
+ international or multilingual SEO, the wrong-language page showing in search, or
+ duplicate content across country versions. 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", "th/en page ranking in the wrong country", or any
+ cross-language/cross-country ranking question. For full-site audits use
/seo-analysis; for a single URL use /seo-page.
---
diff --git a/seo/local-seo/SKILL.md b/seo/local-seo/SKILL.md
index cc1f1ba1..a0f0a52f 100644
--- a/seo/local-seo/SKILL.md
+++ b/seo/local-seo/SKILL.md
@@ -2,21 +2,18 @@
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 and Google Business Profile audit: diagnose why a business isn't ranking
+ in the local pack / map results and produce a fix plan. Covers GBP completeness,
+ NAP (name/address/phone) consistency across the site and citations, local pack and
+ "near me" ranking factors, review velocity and responses, local landing pages,
+ service-area pages, and LocalBusiness JSON-LD. Use whenever the user asks about
+ local rankings, map results, Google Maps ranking, NAP consistency, store/branch
+ pages, or multi-location SEO. 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", "why don't I show up on
+ Google Maps", "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
diff --git a/seo/programmatic-seo/SKILL.md b/seo/programmatic-seo/SKILL.md
index 0969abdb..37ae84a6 100644
--- a/seo/programmatic-seo/SKILL.md
+++ b/seo/programmatic-seo/SKILL.md
@@ -2,20 +2,18 @@
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 planning and audit: building or evaluating large sets of
+ template-generated pages that target long-tail query patterns (e.g. "[service] in
+ [city]", "[product] vs [product]", "[tool] for [use-case]"). Covers data-source
+ and template design, thin/duplicate-content and doorway-page risks, per-page
+ uniqueness and value thresholds, internal linking and hubs, indexation management
+ (publish vs. noindex), and scaling without a manual action. Use whenever the user
+ wants to generate many pages from a template/dataset, build
+ location/comparison/use-case pages at scale, or asks why 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
diff --git a/seo/seo-analysis/SKILL.md b/seo/seo-analysis/SKILL.md
index 5da8422e..458924cd 100644
--- a/seo/seo-analysis/SKILL.md
+++ b/seo/seo-analysis/SKILL.md
@@ -2,25 +2,18 @@
name: seo-analysis
argument-hint: "<URL to audit, e.g. https://example.com>"
description: >
- Full SEO audit: Google Search Console data + URL Inspection API + PageSpeed
- Insights API + technical crawl + keyword research + metadata audit + schema
- markup audit + search intent analysis + Core Web Vitals monitoring. Feeds real
- GSC data and PageSpeed metrics into AI to surface quick wins, diagnose traffic
- drops, find content gaps, identify metadata mismatches, detect schema gaps,
- monitor page performance, and produce an actionable 30-day plan. Use this skill
- whenever the user asks about SEO, search rankings, organic traffic, Google
- Search Console, keyword performance, traffic drops, content gaps, search
- visibility, technical SEO, meta tags, schema markup, structured data, URL
- indexing, keyword research, indexing issues, page speed, performance, Core Web
- Vitals, LCP, INP, CLS, or Lighthouse scores. Also trigger on: "why is my
- traffic down", "what keywords am I ranking for", "improve my rankings", "check
- my search console", "SEO audit", "analyze my SEO", "technical SEO", "meta
- tags", "indexing issues", "crawl errors", "content strategy", "keyword
- cannibalization", "search intent", "schema markup", "structured data", "URL
- inspection", "page speed", "performance score", "core web vitals", "lighthouse",
- or any organic search question. If in doubt, trigger. This skill handles
- everything from quick GSC checks to deep technical audits with performance
- monitoring.
+ Full SEO audit combining Google Search Console, URL Inspection API, PageSpeed
+ Insights, a technical crawl, keyword research, and metadata, schema, search intent
+ and Core Web Vitals checks. Surfaces quick wins, diagnoses traffic drops and
+ content gaps, and produces an actionable 30-day plan. Use whenever the user asks
+ about SEO, search rankings, organic traffic, Google Search Console, keyword
+ performance, search visibility, technical SEO, URL indexing, or LCP, INP, CLS or
+ Lighthouse scores. Also trigger on: "why is my traffic down", "what keywords am I
+ ranking for", "improve my rankings", "check my search console", "SEO audit",
+ "analyze my SEO", "technical SEO", "meta tags", "indexing issues", "crawl errors",
+ "content strategy", "keyword cannibalization", "search intent", "schema markup",
+ "structured data", "URL inspection", "page speed", "performance score", "core web
+ vitals", "lighthouse", or any organic search question. If in doubt, trigger.
---
# SEO Analysis
diff --git a/seo/seo-page/SKILL.md b/seo/seo-page/SKILL.md
index 5bab19bf..7b65b94e 100644
--- a/seo/seo-page/SKILL.md
+++ b/seo/seo-page/SKILL.md
@@ -2,20 +2,18 @@
name: seo-page
argument-hint: "<URL of the page to analyze, e.g. https://example.com/blog/my-post>"
description: >
- Single-page SEO audit: deep content quality evaluation using Google's E-E-A-T
- framework, Helpful Content guidelines, on-page SEO factors, search intent
- alignment, technical signals, and readability analysis. Fetches GSC performance
- data for that specific page, crawls the live HTML, evaluates metadata, schema
- markup, internal linking, content depth, and produces a scored report with
- actionable fixes. Use this skill whenever the user wants to analyze a specific
- page or URL — not the whole site. Trigger on: "analyze this page", "audit this
- URL", "how is this page doing", "evaluate my blog post", "check this landing
- page", "page SEO", "content quality check", "is this page good enough",
- "review this page's SEO", "what's wrong with this page", "how can I improve
- this page", "page analysis", "single page audit", "content audit for [URL]",
- or any request that names a specific URL/page for SEO evaluation. If the user
- provides a specific URL (not just a domain), this is likely the right skill —
- use /seo-analysis for full-site audits instead.
+ Single-page SEO audit: content quality under Google's E-E-A-T framework and
+ Helpful Content guidelines, on-page factors, search intent, technical signals and
+ readability. Pulls GSC data for the page, crawls the live HTML, checks metadata,
+ schema, internal linking and depth, and produces a scored report with fixes. Use
+ whenever the user wants to analyze a specific page or URL, not the whole site.
+ Trigger on: "analyze this page", "audit this URL", "how is this page doing",
+ "evaluate my blog post", "check this landing page", "page SEO", "content quality
+ check", "is this page good enough", "review this page's SEO", "what's wrong with
+ this page", "how can I improve this page", "page analysis", "single page audit",
+ "content audit for [URL]", or any request naming a specific URL/page for SEO
+ evaluation. If the user provides a specific URL (not just a domain), this is
+ likely the right skill; use /seo-analysis for full-site audits instead.
---
# Single-Page SEO Analysis
diff --git a/seo/sxo/SKILL.md b/seo/sxo/SKILL.md
index 149f759b..3d9c8bef 100644
--- a/seo/sxo/SKILL.md
+++ b/seo/sxo/SKILL.md
@@ -2,20 +2,19 @@
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), the bridge between SEO and UX/CRO. Audits
+ the journey from the SERP click to the on-page goal: click-through factors (title,
+ meta, rich results), then post-click signals that keep users and drive
+ conversions: above-the-fold relevance and intent match, page speed / Core Web
+ Vitals, readability, clear CTAs, mobile usability, and what causes pogo-sticking
+ back to Google. Use when the user has decent rankings but poor CTR or poor on-page
+ conversion, wants better dwell time / engagement, less bounce, or a page
+ experience aligned 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)
diff --git a/server.json b/server.json
index f4e4180a..3ba34d9a 100644
--- a/server.json
+++ b/server.json
@@ -8,7 +8,7 @@
"url": "https://github.com/nowork-studio/notfair-plugin",
"source": "github"
},
- "version": "0.27.11",
+ "version": "0.27.12",
"remotes": [
{
"type": "streamable-http",
diff --git a/skills/ecommerce-seo/SKILL.md b/skills/ecommerce-seo/SKILL.md
index 3cf79eab..0f054bf8 100644
--- a/skills/ecommerce-seo/SKILL.md
+++ b/skills/ecommerce-seo/SKILL.md
@@ -3,19 +3,17 @@ 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.
+ Covers category / product listing pages (PLP), product detail pages (PDP), faceted
+ navigation and its crawl-budget and duplicate-content traps, pagination,
+ canonicals for variants and filters, out-of-stock / discontinued products,
+ internal linking and breadcrumbs, and Product / Offer / Review / AggregateRating /
+ BreadcrumbList structured data. Use whenever the user runs an online store and
+ asks about product or category page SEO, filter URLs being indexed, product rich
+ results, 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.
---
# Canonical NotFair workflow
diff --git a/skills/hreflang-international/SKILL.md b/skills/hreflang-international/SKILL.md
index 98eedccf..fcebfce7 100644
--- a/skills/hreflang-international/SKILL.md
+++ b/skills/hreflang-international/SKILL.md
@@ -2,20 +2,18 @@
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
+ International / multilingual SEO audit focused on hreflang correctness: missing or
+ broken return tags, wrong language/region codes, missing x-default,
+ self-referencing errors, hreflang vs canonical conflicts, and inconsistent signals
+ across HTML head, HTTP headers and XML sitemap. Also reviews URL structure (ccTLD
+ vs subdirectory vs subdomain), language targeting and geo signals. Use whenever
+ the user runs a multi-language or multi-region site and asks about hreflang,
+ international or multilingual SEO, the wrong-language page showing in search, or
+ duplicate content across country versions. 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", "th/en page ranking in the wrong country", or any
+ cross-language/cross-country ranking question. For full-site audits use
/seo-analysis; for a single URL use /seo-page.
---
diff --git a/skills/local-seo/SKILL.md b/skills/local-seo/SKILL.md
index 0653555e..14c6f90d 100644
--- a/skills/local-seo/SKILL.md
+++ b/skills/local-seo/SKILL.md
@@ -2,21 +2,18 @@
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 and Google Business Profile audit: diagnose why a business isn't ranking
+ in the local pack / map results and produce a fix plan. Covers GBP completeness,
+ NAP (name/address/phone) consistency across the site and citations, local pack and
+ "near me" ranking factors, review velocity and responses, local landing pages,
+ service-area pages, and LocalBusiness JSON-LD. Use whenever the user asks about
+ local rankings, map results, Google Maps ranking, NAP consistency, store/branch
+ pages, or multi-location SEO. 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", "why don't I show up on
+ Google Maps", "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.
---
# Canonical NotFair workflow
diff --git a/skills/programmatic-seo/SKILL.md b/skills/programmatic-seo/SKILL.md
index bb84dfb3..bb730199 100644
--- a/skills/programmatic-seo/SKILL.md
+++ b/skills/programmatic-seo/SKILL.md
@@ -2,20 +2,18 @@
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 planning and audit: building or evaluating large sets of
+ template-generated pages that target long-tail query patterns (e.g. "[service] in
+ [city]", "[product] vs [product]", "[tool] for [use-case]"). Covers data-source
+ and template design, thin/duplicate-content and doorway-page risks, per-page
+ uniqueness and value thresholds, internal linking and hubs, indexation management
+ (publish vs. noindex), and scaling without a manual action. Use whenever the user
+ wants to generate many pages from a template/dataset, build
+ location/comparison/use-case pages at scale, or asks why 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.
---
# Canonical NotFair workflow
diff --git a/skills/seo-analysis/SKILL.md b/skills/seo-analysis/SKILL.md
index 57b0e09e..3d73ccfc 100644
--- a/skills/seo-analysis/SKILL.md
+++ b/skills/seo-analysis/SKILL.md
@@ -2,25 +2,18 @@
name: seo-analysis
argument-hint: "<URL to audit, e.g. https://example.com>"
description: >
- Full SEO audit: Google Search Console data + URL Inspection API + PageSpeed
- Insights API + technical crawl + keyword research + metadata audit + schema
- markup audit + search intent analysis + Core Web Vitals monitoring. Feeds real
- GSC data and PageSpeed metrics into AI to surface quick wins, diagnose traffic
- drops, find content gaps, identify metadata mismatches, detect schema gaps,
- monitor page performance, and produce an actionable 30-day plan. Use this skill
- whenever the user asks about SEO, search rankings, organic traffic, Google
- Search Console, keyword performance, traffic drops, content gaps, search
- visibility, technical SEO, meta tags, schema markup, structured data, URL
- indexing, keyword research, indexing issues, page speed, performance, Core Web
- Vitals, LCP, INP, CLS, or Lighthouse scores. Also trigger on: "why is my
- traffic down", "what keywords am I ranking for", "improve my rankings", "check
- my search console", "SEO audit", "analyze my SEO", "technical SEO", "meta
- tags", "indexing issues", "crawl errors", "content strategy", "keyword
- cannibalization", "search intent", "schema markup", "structured data", "URL
- inspection", "page speed", "performance score", "core web vitals", "lighthouse",
- or any organic search question. If in doubt, trigger. This skill handles
- everything from quick GSC checks to deep technical audits with performance
- monitoring.
+ Full SEO audit combining Google Search Console, URL Inspection API, PageSpeed
+ Insights, a technical crawl, keyword research, and metadata, schema, search intent
+ and Core Web Vitals checks. Surfaces quick wins, diagnoses traffic drops and
+ content gaps, and produces an actionable 30-day plan. Use whenever the user asks
+ about SEO, search rankings, organic traffic, Google Search Console, keyword
+ performance, search visibility, technical SEO, URL indexing, or LCP, INP, CLS or
+ Lighthouse scores. Also trigger on: "why is my traffic down", "what keywords am I
+ ranking for", "improve my rankings", "check my search console", "SEO audit",
+ "analyze my SEO", "technical SEO", "meta tags", "indexing issues", "crawl errors",
+ "content strategy", "keyword cannibalization", "search intent", "schema markup",
+ "structured data", "URL inspection", "page speed", "performance score", "core web
+ vitals", "lighthouse", or any organic search question. If in doubt, trigger.
---
# Canonical NotFair workflow
diff --git a/skills/seo-page/SKILL.md b/skills/seo-page/SKILL.md
index e6510ab4..b4008495 100644
--- a/skills/seo-page/SKILL.md
+++ b/skills/seo-page/SKILL.md
@@ -2,20 +2,18 @@
name: seo-page
argument-hint: "<URL of the page to analyze, e.g. https://example.com/blog/my-post>"
description: >
- Single-page SEO audit: deep content quality evaluation using Google's E-E-A-T
- framework, Helpful Content guidelines, on-page SEO factors, search intent
- alignment, technical signals, and readability analysis. Fetches GSC performance
- data for that specific page, crawls the live HTML, evaluates metadata, schema
- markup, internal linking, content depth, and produces a scored report with
- actionable fixes. Use this skill whenever the user wants to analyze a specific
- page or URL — not the whole site. Trigger on: "analyze this page", "audit this
- URL", "how is this page doing", "evaluate my blog post", "check this landing
- page", "page SEO", "content quality check", "is this page good enough",
- "review this page's SEO", "what's wrong with this page", "how can I improve
- this page", "page analysis", "single page audit", "content audit for [URL]",
- or any request that names a specific URL/page for SEO evaluation. If the user
- provides a specific URL (not just a domain), this is likely the right skill —
- use /seo-analysis for full-site audits instead.
+ Single-page SEO audit: content quality under Google's E-E-A-T framework and
+ Helpful Content guidelines, on-page factors, search intent, technical signals and
+ readability. Pulls GSC data for the page, crawls the live HTML, checks metadata,
+ schema, internal linking and depth, and produces a scored report with fixes. Use
+ whenever the user wants to analyze a specific page or URL, not the whole site.
+ Trigger on: "analyze this page", "audit this URL", "how is this page doing",
+ "evaluate my blog post", "check this landing page", "page SEO", "content quality
+ check", "is this page good enough", "review this page's SEO", "what's wrong with
+ this page", "how can I improve this page", "page analysis", "single page audit",
+ "content audit for [URL]", or any request naming a specific URL/page for SEO
+ evaluation. If the user provides a specific URL (not just a domain), this is
+ likely the right skill; use /seo-analysis for full-site audits instead.
---
# Canonical NotFair workflow
diff --git a/skills/sxo/SKILL.md b/skills/sxo/SKILL.md
index 238c6972..d3d08e9e 100644
--- a/skills/sxo/SKILL.md
+++ b/skills/sxo/SKILL.md
@@ -2,20 +2,19 @@
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), the bridge between SEO and UX/CRO. Audits
+ the journey from the SERP click to the on-page goal: click-through factors (title,
+ meta, rich results), then post-click signals that keep users and drive
+ conversions: above-the-fold relevance and intent match, page speed / Core Web
+ Vitals, readability, clear CTAs, mobile usability, and what causes pogo-sticking
+ back to Google. Use when the user has decent rankings but poor CTR or poor on-page
+ conversion, wants better dwell time / engagement, less bounce, or a page
+ experience aligned 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.
---
# Canonical NotFair workflow
diff --git a/test/unit/test_skill_descriptions.py b/test/unit/test_skill_descriptions.py
new file mode 100644
index 00000000..40eb6a5e
--- /dev/null
+++ b/test/unit/test_skill_descriptions.py
@@ -0,0 +1,78 @@
+"""Skill descriptions stay within the documented 1024-character limit.
+
+The description is the part of a skill that is always loaded into context, and
+Anthropic's skill authoring guidance caps it at 1024 characters. Codex wrappers
+under skills/ repeat the canonical frontmatter, so they must stay in sync.
+"""
+
+import re
+from pathlib import Path
+
+import pytest
+
+
+ROOT = Path(__file__).resolve().parents[2]
+MAX_DESCRIPTION_CHARS = 1024
+SKIP_DIRS = {".git", "node_modules"}
+
+
+def _skill_files():
+ return sorted(
+ path
+ for path in ROOT.rglob("SKILL.md")
+ if not SKIP_DIRS.intersection(path.relative_to(ROOT).parts)
+ )
+
+
+def _description(path):
+ text = path.read_text(encoding="utf-8")
+ match = re.match(r"---\r?\n(.*?)\r?\n---", text, re.S)
+ if not match:
+ return None
+ lines = match.group(1).splitlines()
+ for index, line in enumerate(lines):
+ if not line.startswith("description:"):
+ continue
+ value = line[len("description:"):].strip()
+ if value not in (">", ">-", "|", "|-"):
+ return value.strip("\"'")
+ block = []
+ for follow in lines[index + 1:]:
+ if follow and not follow[0].isspace():
+ break
+ block.append(follow.strip())
+ joiner = "\n" if value.startswith("|") else " "
+ return joiner.join(part for part in block if part)
+ return None
+
+
+SKILLS = [path for path in _skill_files() if _description(path) is not None]
+
+
+def test_skills_are_discovered():
+ assert len(SKILLS) > 0
+
+
+ "path", SKILLS, ids=lambda p: str(p.relative_to(ROOT))
+)
+def test_description_within_limit(path):
+ length = len(_description(path))
+ assert length <= MAX_DESCRIPTION_CHARS, (
+ f"{path.relative_to(ROOT)} description is {length} characters; "
+ f"the limit is {MAX_DESCRIPTION_CHARS}"
+ )
+
+
+WRAPPERS = []
+for wrapper in sorted((ROOT / "skills").glob("*/SKILL.md")):
+ target = re.search(r"\.\./\.\./(.+?)/SKILL\.md", wrapper.read_text(encoding="utf-8"))
+ if target and (ROOT / target.group(1) / "SKILL.md").exists():
+ WRAPPERS.append((wrapper, ROOT / target.group(1) / "SKILL.md"))
+
+
+ "wrapper,canonical", WRAPPERS, ids=lambda p: str(p.relative_to(ROOT))
+)
+def test_codex_wrapper_description_matches_canonical(wrapper, canonical):
+ assert _description(wrapper) == _description(canonical)