amazing-seo-skill

name	amazing-seo-skill
description	SEO + AEO + GEO analysis for any website (SaaS, e-commerce, local, publisher, agency). Full-site audits, single-page deep-dive, technical SEO (crawl, index, CWV with INP, JS-rendering), Schema.org detection/validation/gen, E-E-A-T content quality, image optimization, sitemap, hreflang, programmatic SEO, competitor pages, and Generative/Answer Engine Optimization (AI Overviews, ChatGPT, Perplexity, Claude, Gemini citations). Detects business type, applies industry thresholds. 4-layer model: reasoning, deterministic Python checkers, real-browser CWV, 5-LLM citation ensemble. Triggers on: "SEO", "audit", "schema", "Core Web Vitals", "INP", "sitemap", "E-E-A-T", "AI Overviews", "GEO", "AEO", "technical SEO", "hreflang", "programmatic SEO", "competitor pages".
allowed-tools	["Read","Grep","Glob","Bash","WebFetch","WebSearch"]

Amazing SEO Skill

Single entry-point orchestrator for end-to-end SEO/AEO/GEO analysis across all industries. Combines reasoning, deterministic checkers, real-browser measurement, and multi-LLM cross-validation into one unified workflow.

First time setup? Tell the user: "Run ./tools/onboarding.sh in the skill directory — it shows which capability layers (L0-L4) are active on this machine and lists the API keys needed to unlock the rest." See also ONBOARDING.md for the full reference.

Quick Reference

Command	What it does
audit <domain>	Full website audit, parallel sub-agents, site-wide Health Score. Delegates to tools/site_audit.sh for multi-page parallelism.
page <url>	Single-page deep-dive. Runs every L1 checker on one URL, aggregates into 0-100 Health Score with prioritized findings. Calls scripts/page_score.py.
ai_visibility <url>	Composite AI Visibility Score (0-100) — AI crawler access + SSR + schema + llms.txt + hreflang + live citations.
cms <url>	Detect CMS / framework (24+ platforms) and get platform-specific SEO tips
js_render <url>	Compare raw HTML vs JS-rendered HTML — critical for SPA SEO
logs <log_file>	Parse server access logs: bot behavior, crawl waste, error spikes, sitemap cross-check
content <url>	Content quality + Flesch + E-E-A-T markers + citable-passage extraction
local <url>	Local-SEO audit: NAP, LocalBusiness schema, GBP, citations
serp "<query>"	SerpAPI: top-10 organic, SERP features, AI Overview, target-domain position
technical <url>	Technical SEO across 9 categories (robots/sitemap/security/redirects/CWV)
schema <url>	Detect, validate, generate Schema.org markup
images <url>	Image optimization (alt, format, dims, lazy, size)
links <url>	Broken-link audit (4xx + 5xx + auth-gated)
security <url>	Security-headers audit (HSTS, CSP, XFO, mixed content)
sitemap <url | generate>	Analyze or generate XML sitemaps
geo <url>	AI Overviews / Generative Engine Optimization
aeo <url> [keyword]	Live AEO citation check (5-LLM ensemble inc. Gemini)
history {store|list|diff|trend}	SQLite audit history — store runs, compare over time
dashboard	Build static HTML dashboard from history.db
serve_dashboard [PORT]	Serve dashboard on localhost:8080
report <json_file>	Render page_score JSON → styled HTML report
plan <industry>	Strategic SEO plan from industry template
programmatic [url | plan]	Programmatic SEO analysis or planning
competitor-pages [url | generate]	Competitor comparison page generation
hreflang [url]	Hreflang/i18n SEO audit and generation
growth <url>	Growth opportunities vs competitors (Ahrefs gap)

Architecture: 4-Layer Data Model

Layer	Source	When to use
L0	Claude reasoning + WebFetch	Analysis, prioritization, recommendations
L1	Python scripts in scripts/	Deterministic checkers: robots, sitemap, hreflang, schema, llms.txt, redirect chains, internal link graph, PSI/CWV
L2	Local CLIs in .bin/	251-rule deep audit + real-browser CWV; live AEO citations
L3	External APIs	Ahrefs MCP, Google Search Console
L4	Multi-LLM ensemble	Cross-validation via 5 LLM providers (anthropic, openai, perplexity, xai, gemini-with-search-grounding)

API keys for L4 are read from macOS Keychain at runtime: anthropic-api-key, openai-api-key, perplexity-api-key, x.ai-api-key, google-gemini-api-key (the latter enables a Gemini-with-Google-Search probe that closes the Google AI Overviews / AI Mode gap). Retrieve with security find-generic-password -s <name> -w.

Orchestration Logic

When invoked with audit, delegate to sub-agents in parallel:

1. Detect business type from homepage signals (SaaS, local, ecommerce, publisher, agency, generic)
2. Spawn parallel sub-agents:
   • technical — crawlability, indexability, security, CWV
   • content — E-E-A-T, readability, thin content
   • schema — detection, validation, generation
   • sitemap — structure, coverage, quality gates
   • performance — Core Web Vitals via real browser
   • visual — screenshots, mobile testing, above-fold
3. Dedupe contradictions across sub-agent reports (inline reasoning)
4. Generate unified report:
   • SEO Health Score (0-100)
   • Findings table with confidence labels (Confirmed / Likely / Hypothesis)
   • Prioritized action plan (Critical → High → Medium → Low)

For individual commands, load the relevant module from skills/ directly.

Industry Detection

Identify business type from homepage signals:

• SaaS — pricing page, /features, /integrations, /docs, "free trial", "sign up"
• Local Service — phone number, address, service area, "serving [city]", Google Maps embed
• E-commerce — /products, /collections, /cart, "add to cart", Product schema
• Publisher — /blog, /articles, /topics, Article schema, author pages, publication dates
• Agency — /case-studies, /portfolio, /industries, "our work", client logos

Apply industry-specific thresholds and templates from industry/<type>.md.

Quality Gates (hard rules)

Read references/quality-gates.md for thin-content thresholds per page type. Hard rules that override any contrary suggestion:

• ⚠️ WARNING at 30+ location pages (enforce 60%+ unique content)
• 🛑 HARD STOP at 50+ location pages (require user justification)
• Never recommend HowTo schema (deprecated September 2023)
• FAQ schema only for government and healthcare sites
• All Core Web Vitals references use INP, never FID
• Never suggest doorway pages or thin content at scale

Reference Files

Load these on-demand as needed — do NOT load all at startup:

• references/cwv-thresholds.md — Current Core Web Vitals thresholds (LCP, CLS, INP)
• references/schema-types.md — All supported schema types with deprecation status
• references/eeat-framework.md — E-E-A-T evaluation criteria (Sept 2025 QRG update)
• references/quality-gates.md — Content length minimums, uniqueness thresholds
• industry/<type>.md — Industry template for detected business type
• docs/google-seo-reference.md — Google search documentation reference

Deterministic Checkers (L1)

Lightweight Python scripts in scripts/. Each runs standalone, outputs JSON, returns a meaningful exit code (0 = clean, 1 = fetch failed, 2 = issues found), and is wired through scripts/_fetch.py (realistic Chrome UA, SSRF guard, retries). Use these for Confirmed findings; falling back to L0 reasoning only when the relevant checker can't reach the target.

Checker	What it verifies	Notes
robots_checker.py <domain>	robots.txt: structure, sitemap refs, per-bot Allow/Disallow for 20 crawlers (GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-User, PerplexityBot, Google-Extended, meta-externalagent, Bytespider, etc.)	Recommends 301 vs 302 for upgrades
sitemap_validator.py <url>	XML validity, sitemap-index recursion, URL count vs 50k limit, HTTPS-only, lastmod sanity, deprecated <priority>/<changefreq>, sample HTTP-200 check, robots.txt cross-reference	--sample N configurable
redirect_chain_checker.py <url>	per-hop redirect trace, HTTP→HTTPS upgrade, 301 vs 302 mix, loop detection, canonical alignment on final URL	Hop count ≥ 3 flagged
security_headers_checker.py <url>	HSTS (max-age, includeSubDomains, preload), CSP (unsafe-inline / nonce / hash), X-Frame-Options or CSP frame-ancestors, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, mixed-content scan	Page Experience signals
broken_links_checker.py <url>	Per-page link audit: every <a>, <link>, <script>, <img>, <source>, <iframe>, CSS background. Concurrent HEAD with GET fallback. Splits 4xx vs 5xx vs auth-gated 401/403 (separate bucket — soft signal)	--max-links, --internal-only
images_audit.py <url>	Alt-text coverage, format mix (WebP/AVIF/JPEG/PNG/SVG) with next-gen target ≥70%, width/height dims for CLS, lazy-loading on below-fold, size flags ≥200KB/≥500KB	--no-size-probe for fast mode
hreflang_checker.py <url>	BCP-47 codes, x-default, self-reference, reciprocity (parallel)	--check-reciprocity
schema_recommended_fields.py <url>	Per-schema-item required vs recommended field coverage; per-item completeness 0-100	Article: per Google "no required fields"
llms_txt_checker.py <domain>	llms.txt existence, structure, link-validity (HEAD probe of referenced URLs), AEO-language heuristics	--skip-links for fast mode
internal_link_graph.py <seed>	Crawl-built adjacency: true orphans (sitemap not linked), sitemap gaps, depth-4+ pages, hub pages, dead-ends	--max-pages, --max-depth
psi_checker.py <url>	PageSpeed Insights API v5: field CrUX (LCP/INP/CLS/FCP/TTFB at 75th percentile) + lab Lighthouse	API key from env GOOGLE_PSI_API_KEY or Keychain google-psi-api-key
aeo_gemini.py <domain> "<query>" …	Gemini-with-Google-Search-grounding probe: does the LLM cite the target domain when answering each query? Proxy for Google AI Overviews / AI Mode	Needs google-gemini-api-key
cms_detector.py <url>	Identifies platform from body / headers / generator meta (WordPress, Shopify, Webflow, Wix, Squarespace, Ghost, Drupal, Magento, HubSpot, BigCommerce, Next.js, Nuxt, Gatsby, Hugo, Astro, etc.) + tailored SEO tips for that platform.	24+ platforms covered
js_rendering_diff.py <url>	Server-rendered HTML vs Playwright-rendered HTML structural diff: canonical/robots/title/meta/schema/word-count/hreflang. P0 flags when canonical or schema only in rendered (AI crawlers + Googlebot indexing delay)	Requires Playwright Chromium
log_analyzer.py <log_file>	Parses Apache/Nginx access logs (incl .gz): per-bot breakdown (Googlebot, GPTBot, ClaudeBot, PerplexityBot, etc.), crawl-waste detection (UTM, fbclid, feeds, parameter explosions), 4xx/5xx spike days, sitemap cross-check (orphans + cold pages).	--sitemap, --days N
content_quality.py <url>	Word count vs page-type baseline, Flesch reading ease, avg sentence/paragraph length, keyword density (stuffing detection at >5%), AI-generation marker phrases, 134-200 word citable-passage extraction, author byline + dates (E-E-A-T).	--page-type blog|service|home
local_seo_checker.py <url>	NAP discoverability (Name + Address + Phone), LocalBusiness schema required+recommended fields, Google Maps embed, GBP / Yelp / BBB / Facebook citations, NAP consistency (schema vs visible page text).	Use for local-intent pages
ai_visibility_score.py <url>	Composite 0-100 AI Visibility Score across 6 components (AI crawler accessibility, SSR completeness, Schema, llms.txt, hreflang, live Gemini citation rate). Verdict + per-component breakdown.	Optional live Gemini probe with --queries
audit_history.py {store|list|diff|trend|prune}	SQLite-backed audit history. Stores page_score JSON, computes score trends over time, diffs two runs (findings added vs removed), prunes old runs.	DB at ~/.amazing-seo-skill/history.db
serpapi_integration.py "<query>"	Optional SERP layer via SerpAPI: top-10 organic, SERP features (AI Overview, Featured Snippet, PAA, Knowledge Panel, Local Pack), target-domain position, AI Overview citation check, People Also Ask.	Needs SERPAPI_KEY or Keychain serpapi-key
render_html_report.py < page_score.json	Renders a page_score.py --format json into a self-contained styled HTML report. Dark theme, severity-coloured findings, category cards, score gauge.	Pipe page_score JSON in
page_score.py <url>	Single-page orchestrator: runs every applicable L1 checker on one URL in parallel, aggregates into 0-100 Health Score with category breakdown + prioritized findings. JSON or Markdown output.	--format markdown|json, --no-psi
parse_html.py <file>	Extract title/meta/headings/canonical/hreflang/images/links/schema/word-count from saved HTML	Used internally by page_score.py
fetch_page.py <url>	Standalone fetcher with SSRF guard; saves HTML to disk for offline analysis	Pre-stage for parse_html.py

v0.8.0 Premium Audit Edition — consultant-grade diagnostics

Checker	What it verifies	Notes
google_updates_correlator.py --gsc-daily CSV	Aligns daily GSC/Ahrefs traffic with the verified Google updates calendar (references/google_updates.json). For each update: Δ clicks & impressions over 14-day before/after windows. Classifies as major_hit / partial / benign / recovery / mixed / insufficient_data.	Calendar covers all major core/spam/Discover updates 2024-2026. Exit codes: 0 clean, 1 partial, 2 major hit
sitemap_freshness.py <sitemap>	Lastmod age distribution by month/year, stale-share % (default >180 days), bulk-update detection at exact-timestamp AND same-day granularity. Catches scripted touches Google has learned to discount.	Verdict bands: healthy / bulk_updates_present / warning_decay / critical_decay / no_lastmod_signal
cannibalization_detector.py --gsc CSV (or --ahrefs)	Detects queries where >1 site URL ranks. Aggregates by query, sorts by total impressions/traffic, identifies high-impact cannibalization vs minor overlap.	Auto-detects GSC vs Ahrefs CSV column shapes
intent_classifier.py --csv keywords.csv	LLM-backed (Claude Haiku) classifier — every keyword gets one of: informational / commercial / transactional / navigational. Aggregates: count + metric share per intent. Flags "we rank where buyers don't search" pattern.	Batches 50 keywords/request. Cost ~$0.20-0.40 per 5,000 keywords
content_tier_classifier.py --csv urls.csv --product-domain "..."	LLM-backed classifier — every URL gets a tier: A_product / A_blog_relevant / B_dev_tutorial / C_divergent. Computes URL share vs metric share, surfaces "12% of URLs drives 40% of traffic but it's off-topic" disproportion.	Uses URL + title + snippet when available
eeat_antipatterns.py <url>	E-E-A-T anti-pattern detector: Open-in-AI widget (chatgpt/perplexity/grok links), anonymous bylines, generic team authors, missing author bio, missing external credentials (LinkedIn/GitHub/RFCs), missing review signal, missing dates, unsourced charts.	Triggered post-Mar-2026 Core update where first-hand experience dominates
backlinks_toxicity.py --ahrefs CSV (or --semrush, --majestic)	DR distribution (overall + recent acquisitions), anchor spam patterns (buy/cheap-links phrasing, Telegram channel references, named link-selling networks), unusual target subdomains (open-redirect abuse), per-domain toxicity score 0-100, disavow file generation.	Output: JSON envelope + Markdown + disavow.txt (manual review required)
premium_report.py envelopes/*.json --output report.html	Renders one or more JSON envelopes from the v0.8.0 checker family into a single self-contained consultant-grade HTML report. DM Serif Display + Inter + JetBrains Mono, monochrome with tunable accent (--accent #00d4aa), sticky sidebar nav, auto-extracted TL;DR.	Sections appear only when their envelope is supplied

Site-level orchestrator

Tool	What it does
tools/site_audit.sh <domain> --limit N	Fetches sitemap (aggregates sitemap-index), samples N URLs, runs page_score.py on each in parallel, aggregates into a site-wide Markdown report with: overall Health Score, category averages, top recurring findings across pages, under-performers list, per-page summary.
tools/crawl.sh <url> [--max-pages N]	Smart crawler dispatcher: auto-selects between Screaming Frog (if installed, ≤500 URLs) and our own amazing-crawl (async Python, unlimited URLs). Override with --force-sf / --force-amazing.
scripts/amazing_crawl.py <url> --max-pages N --concurrency K	Open-source async crawler — SF alternative when SF isn't available or you hit the 500-URL free-tier cap. Captures status/title/meta/canonical/H1/schema/word-count/links/images per URL into SQLite, resumes from checkpoint, exports CSV/JSON.
scripts/build_dashboard.py	Static-HTML dashboard generator from audit_history.db: per-domain trends (inline SVG sparklines), score deltas, top recurring P0/P1 findings across all tracked domains, drillable run-detail pages. Self-contained — open dashboard/index.html directly or serve via tools/serve_dashboard.sh.
tools/serve_dashboard.sh [PORT]	Spins up python -m http.server on the dashboard folder. Optional port (default 8080).
tools/onboarding.sh	Probes prereqs / engines / API keys / runs smoke tests. Tells the user which layers (L0-L4) are active. Run after install.
tools/multi-page-audit.sh <domain>	Engine-based (L2) multi-page audit using the deep-audit engine. Use when L2 is configured.
tools/aeo-citations.sh <domain> "<query>" …	5-LLM ensemble citation probe (anthropic, openai, perplexity, xai, gemini-with-grounding).

Modules (sub-skills)

Each module is a self-contained sub-skill in skills/*.md. Load only the relevant ones for the current task:

Module	File	Scope
Audit orchestrator	skills/audit.md	Full website audit with parallel delegation
Page deep-dive	skills/page.md	Single-page analysis
Technical SEO	skills/technical.md	9 technical categories
Content quality	skills/content.md	E-E-A-T + readability
Schema markup	skills/schema.md	Detection, validation, generation
Image optimization	skills/images.md	Alt text, formats, lazy-loading
Sitemap	skills/sitemap.md	Analysis and generation
GEO / AI Overviews	skills/geo.md	Generative Engine Optimization
Strategic planning	skills/plan.md	Industry-specific plans
Programmatic SEO	skills/programmatic.md	Scale page generation safely
Competitor pages	skills/competitor-pages.md	"X vs Y" / "alternatives to X"
Hreflang / i18n	skills/hreflang.md	International SEO
Growth opportunities	skills/growth.md	Competitor gap analysis via Ahrefs MCP

Scoring Methodology

SEO Health Score (0-100)

Weighted aggregate across categories. Source of truth: scripts/page_score.py:CHECKERS — these weights mirror it exactly.

Category	Weight	Checkers
Technical	20%	redirect_chain_checker + security_headers_checker
Schema / Structured Data	15%	schema_recommended_fields
Images	15%	images_audit
Links	15%	broken_links_checker
Performance (CWV)	15%	psi_checker (skipped if no API key — weight removed from denominator)
Content	10%	content_quality
GEO	10%	hreflang_checker + llms_txt_checker
On-page / Platform	0%	parse_html, cms_detector (informational only)

Priority Levels

• Critical — blocks indexing or causes penalties (immediate fix)
• High — significantly impacts rankings (fix within 1 week)
• Medium — optimization opportunity (fix within 1 month)
• Low — nice to have (backlog)

Confidence Labels (for findings)

• Confirmed — verified by deterministic check (L1) or real-browser measurement (L2)
• Likely — supported by reasoning (L0) and at least one external signal
• Hypothesis — based on reasoning alone, requires validation

Output Formats

• Markdown report — human-readable summary
• JSON — structured for programmatic processing
• LLM-XML — optimized for handoff to another agent

Internal Engines

Heavy lifting is done by underlying engines, hidden behind brand-neutral wrappers in .bin/. Modules invoke these via tools/* rather than calling external CLIs directly:

• .bin/_engine_deep_audit — 251-rule deterministic audit + real-browser CWV
• .bin/_engine_aeo_citations — live LLM citation checking

Execution Mode (dual)

This skill supports two installation modes:

• Lightweight — only SKILL.md and skills/*.md are present. All analysis happens via Claude reasoning + WebFetch. No Python or external CLIs needed.
• Full — full repo cloned. All 4 layers active, including deterministic checkers, real-browser CWV, AEO citations, and multi-LLM ensemble.

Detect mode at runtime: if .venv/bin/python exists → full mode; otherwise lightweight.