claude-seo-ai

Two scores, never blended. A page can rank well in Google yet be uncitable by ChatGPT, Perplexity, Google AI Overviews, Gemini, and Claude — or the reverse. claude-seo-ai measures both and tells you exactly what to fix.

🇪🇸 Resumen en español al final · guías completas en docs/es/.

---

Why

AI answer engines now sit beside classic search as a primary discovery channel, and the rules for being cited differ from the rules for ranking. Most SEO tools treat AI search as a footnote and never write fixes back into your code. This one is built for 2026–2027: honest, agent-native, and able to both diagnose and (opt-in) fix.

It is original work — inspired by the patterns of community SEO tooling but copies no branding, text, or names from any other project. MIT-licensed.

Install

As a Claude Code plugin (recommended):

/plugin marketplace add Hainrixz/claude-seo-ai
/plugin install claude-seo-ai@claude-seo-ai
/reload-plugins

Cross-agent (Cursor, Codex, Gemini CLI, Windsurf…) via Vercel Skills:

npx skills add Hainrixz/claude-seo-ai

The plugin works fully offline (Tier 0, no keys). See Data tiers for optional rendering and API integrations. The skills-only channel ships the Markdown but not the scripts/ acquisition layer — see docs/en/distribution.md.

Usage

/claude-seo-ai:audit   <url|path> [--pages N] [--max N] [--render static|auto|js]
                                  [--ua default|googlebot|bingbot|gptbot|oai-searchbot|claude-searchbot]
                                  [--vertical ecommerce,docs] [--environment production|preview|staging|local]
                                  [--feed <path>] [--out <dir>]

/claude-seo-ai:geo     <url|path> [--pages N] [--render static|auto|js] [--feed <path>]
                                  [--probe "<question>"] [--gsc-ai-export <csv>]

/claude-seo-ai:score   [findings.json | run-dir | latest[:host]]

/claude-seo-ai:compare <urlA> <urlB> [<urlC>…] | --baseline [latest] --against <url|run>
                     | --staging <url> --prod <url> | <url> --gap "<query>"

/claude-seo-ai:fix     <url|path> [--target auto|local|shopify|wordpress|webflow|wix|ghost|hubspot|bigcommerce|instructions]
                                  [--category M5 --category auto] [--include-proposed]
                                  [--project <dir>] [--dev-url <u>] [--run <id>] [--lang en|es]
                                  [--dry-run] [--publish] [--rollback <run_id>] [--force]

audit, geo, score and compare are read-only and never touch your files. fix previews everything by default and writes only after you confirm each change. --render defaults to static, so a run never launches a browser unless you ask. Power users can call any module directly, e.g. /claude-seo-ai:seo-schema-jsonld.

Every audit is persisted under ${CLAUDE_PLUGIN_DATA}/runs/<host>/<run-id>/ — which is why score, compare and fix work from a report on disk instead of "the last audit this session". Full flags and the run layout: docs/en/usage.md.

Works on any site

The audit is the same everywhere. What changes per platform is what the platform already generates for you, what it refuses to let anyone change, and whether a fix can be written back at all — so a four-layer detector (platform · framework · CMS plugins · hosting) writes a profile.json for every run, and the fixer routes each finding to the adapter that owns that surface.

Status is the header of each platform's knowledge card: stable = exercised end to end with a rollback · beta = implemented but thinly exercised, changes stay PROPOSED · instructions-only = no write API exists, so every fix is a click path for a human.

Platform	Detected	Extra checks	Apply method	Preview/staging	Credentials	Status
Shopify	yes	11	shopify-theme (CLI) + shopify-admin (GraphQL)	unpublished theme; Admin API is live	SHOPIFY_STORE, SHOPIFY_THEME_TOKEN, SHOPIFY_ADMIN_TOKEN	beta
WordPress	yes	10	wordpress-rest or wordpress-wpcli	none — live on apply	WP_URL, WP_USER, WP_APP_PASSWORD · or WP_SSH	beta
WooCommerce	yes	via WordPress	same as WordPress	none	same as WordPress	beta
Webflow	yes	—	page-api	staged until published	WEBFLOW_TOKEN, WEBFLOW_SITE_ID	beta
HubSpot	yes	—	page-api	staged — draft, then push-live	HUBSPOT_TOKEN	beta
Ghost	yes	—	page-api	drafts stay drafts; published posts are live	GHOST_URL, GHOST_ADMIN_KEY	beta
Wix	yes	—	page-api	none you can rely on	WIX_API_KEY, WIX_SITE_ID	beta
BigCommerce	yes	—	page-api	none — live on write	BIGCOMMERCE_STORE_HASH, BIGCOMMERCE_TOKEN	beta
Next.js · Nuxt · Astro · SvelteKit · React Router · Gatsby	yes	3 · 1 · 1 · — · 1 · 2	local-files (source tree, via the route map)	none — a file edit; your deploy publishes it	—	beta
Hugo · Jekyll · Eleventy · Docusaurus · Payload	yes	1 · 1 · — · — · —	local-files	none	—	beta
Plain static HTML	yes	1	local-files	none	—	stable
Squarespace · Framer · Magento · Drupal	yes	—	instructions (+ local-files with a checkout, for Magento/Drupal)	the platform's own publish flow	none	instructions-only

Anything the detector cannot name still gets the full audit — it simply routes every fix to instructions, which renders the exact snippet and the panel or file it belongs in, in EN or ES. That is a real outcome, not a failure.

Credential setup, per-platform quick starts, what never goes live by default, and the full UNVERIFIED list: docs/en/platforms.md.

Two scores, never blended

Every audit reports two 0–100 scores with letter bands (A–F) and a one-line interpretation (details):

• Search SEO — weighted toward indexability, Core Web Vitals, on-page, schema.
• AI Visibility (GEO/AEO) — weighted toward answer extractability, schema, fact density, AI-crawler access, entities.

Severity gating caps an axis at 40 when a severity: 5, established, failing finding lands in an active category (e.g. site-wide noindex) — a directional failure never caps. Conditional verticals re-normalize so a blog isn't penalized for lacking Product schema. needs_api and manual_review checks are excluded from the math and counted separately as score confidence. An axis with no scored finding reports unscored, never F.

How it works

A skill-first, three-layer design — the scripts acquire and prove, the model judges:

1. Directive — one of the five command skills (audit/geo/score/compare/fix).
2. Orchestration — seo-orchestrator runs the deterministic pipeline in one command (crawl → platform profile → 25 checks → first report), then dispatches four read-only specialist subagents in parallel with an absolute-path envelope, and merges everything into a persisted, schema-validated report.
3. Execution — 23 focused seo-* module skills, preloaded into their agent, each emitting findings that conform to schema/finding.schema.json — with observed evidence and a runnable verification.reproduce command.

See docs/en/architecture.md.

What it audits

A complete 2026 suite, grouped:

Area	Modules
Crawl & index	crawlability/robots (M1), indexability + canonical + site health (M2/M3), rendering CSR/SSR/SSG (M4), sitemaps (M17)
Structured data	Tier-1 JSON-LD validate + generate (M5), entity/Knowledge-Graph sameAs (M6)
On-page & meta	title/meta/head (M7), mobile (M7b), headings (M7c), social cards (M8), images & alt (M9), internal linking (M10)
AI search (GEO/AEO)	answer extractability (M11), fact density & original data (M12), AI-crawler access + Google AI-feature eligibility (M14), AI discovery & agent endpoints (M21, weight 0), agent readiness (M22)
Content & trust	E-E-A-T (M16), freshness (M13)
Performance	Core Web Vitals — LCP/INP/CLS (M15)
Verticals (conditional)	e-commerce + agentic commerce (M18), local (M19), international/hreflang (M20)

The deterministic half of that is a registry of 25 checks emitting 151 finding ids, which run with no model in the loop and never throw: a check that fails is isolated per page and its error is recorded in checks.json.

Get cited by AI engines

The GEO/AEO modules score how citable your content is — and they lead with the one thing a vendor actually documents.

• Google's eligibility gate is Search eligibility. Per Google's "AI features and your website" documentation, a page can appear in AI Overviews / AI Mode only if it is indexed and eligible to be shown with a snippet. That is the whole gate. noindex, nosnippet, max-snippet:0 and data-nosnippet on the primary content remove you; Google-Extended does not — it is a training/grounding token that leaves Search-based AI features untouched. These M14.ai_eligibility.* findings are the only established ones on the AI axis.
• AI-crawler access. Whether retrieval bots (OAI-SearchBot, Claude-SearchBot, PerplexityBot, Amazonbot, DuckAssistBot…) can reach and render your page, with a per-vendor source for every user-agent row. See references/ai-crawlers.md.
• Content-Signal in robots.txt (search / ai-input / ai-train) is parsed in both its global and per-group placements. It is a preference, not an enforcement: the IETF draft expired in 2026-04 and no AI vendor documents compliance, so those findings are directional at most — and a Content-Signal line is never presented as a substitute for a Disallow.