Amazing Seo Skill

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 | Full website audit, parallel sub-agents, site-wide Health Score. Delegates to tools/site_audit.sh for multi-page parallelism. | | page | 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 | Composite AI Visibility Score (0-100) — AI crawler access + SSR + schema + llms.txt + hreflang + live citations. | | cms | Detect CMS / framework (24+ platforms) and get platform-specific SEO tips | | js_render | Compare raw HTML vs JS-rendered HTML — critical for SPA SEO | | logs | Parse server access logs: bot behavior, crawl waste, error spikes, sitemap cross-check | | content | Content quality + Flesch + E-E-A-T markers + citable-passage extraction | | local | Local-SEO audit: NAP, LocalBusiness schema, GBP, citations | | serp "" | SerpAPI: top-10 organic, SERP features, AI Overview, target-domain position | | technical | Technical SEO across 9 categories (robots/sitemap/security/redirects/CWV) | | schema | Detect, validate, generate Schema.org markup | | images | Image optimization (alt, format, dims, lazy, size) | | links | Broken-link audit (4xx + 5xx + auth-gated) | | security | Security-headers audit (HSTS, CSP, XFO, mixed content) | | sitemap | Analyze or generate XML sitemaps | | geo | AI Overviews / Generative Engine Optimization | | aeo [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 | Render page_score JSON → styled HTML report | | plan | 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 | 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 -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

1. Dedupe contradictions across sub-agent reports (inline reasoning)
2. 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/.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/.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 | 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 | XML validity, sitemap-index recursion, URL count vs 50k limit, HTTPS-only, lastmod sanity, deprecated `/, sample HTTP-200 check, robots.txt cross-reference | --sample N configurable | | redirectchainchecker.py | per-hop redirect trace, HTTP→HTTPS upgrade, 301 vs 302 mix, loop detection, canonical alignment on final URL | Hop count ≥ 3 flagged | | securityheaderschecker.py | 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 | | brokenlinkschecker.py | Per-page link audit: every , , , , , , CSS background. Concurrent HEAD with GET fallback. Splits 4xx vs 5xx vs auth-gated 401/403 (separate bucket — soft signal) | --max-links, --internal-only | | imagesaudit.py | 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 | | hreflangchecker.py | BCP-47 codes, x-default, self-reference, reciprocity (parallel) | --check-reciprocity | | schemarecommendedfields.py | Per-schema-item required vs recommended field coverage; per-item completeness 0-100 | Article: per Google "no required fields" | | llmstxtchecker.py | llms.txt existence, structure, link-validity (HEAD probe of referenced URLs), AEO-language heuristics | --skip-links for fast mode | | internallinkgraph.py | Crawl-built adjacency: true orphans (sitemap not linked), sitemap gaps, depth-4+ pages, hub pages, dead-ends | --max-pages, --max-depth | | psichecker.py | PageSpeed Insights API v5: field CrUX (LCP/INP/CLS/FCP/TTFB at 75th percentile) + lab Lighthouse | API key from env GOOGLEPSIAPIKEY or Keychain google-psi-api-key | | aeogemini.py "" … | 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 | | cmsdetector.py | 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 | | jsrenderingdiff.py | 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 | | loganalyzer.py | 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 | | contentquality.py | 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 | | localseochecker.py | 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 | | aivisibilityscore.py | 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 | | audithistory.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 | | serpapiintegration.py "" | 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 SERPAPIKEY or Keychain serpapi-key | | renderhtmlreport.py | **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 | | parsehtml.py | Extract title/meta/headings/canonical/hreflang/images/links/schema/word-count from saved HTML | Used internally by pagescore.py | | fetchpage.py | 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 majorhit / partial / benign / recovery / mixed / insufficientdata. | Calendar covers all major core/spam/Discover updates 2024-2026. Exit codes: 0 clean, 1 partial, 2 major hit | | sitemap_freshness.py | 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 / bulkupdatespresent / warningdecay / criticaldecay / nolastmodsignal | | 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: Aproduct / Ablogrelevant / Bdevtutorial / Cdivergent. 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 | 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 --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 [--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 --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 —

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: metawhisp
• Source: metawhisp/amazing-seo-skill
• License: Apache-2.0
• Homepage: https://github.com/metawhisp/amazing-seo-skill

Install and usage instructions live in the source repository linked above.