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

Architecture: 4-Layer Data Model

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.