amazing-seo-skill

内容来源：SKILL.md（标准 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.

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:

Detect business type from homepage signals (SaaS, local, ecommerce, publisher, agency, generic)
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
Dedupe contradictions across sub-agent reports (inline reasoning)
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.