### AI search optimization (the new layer)
- **AI Visibility Score** via `scripts/ai_visibility_score.py` — composite 0-100 across 6 components (AI crawler accessibility, SSR completeness, schema, llms.txt, hreflang, live Gemini citations)
- **AEO — Answer Engine Optimization.** Live citation testing: query 5 LLM
surfaces (ChatGPT, Claude, Perplexity, Grok, **and Gemini with Google
Search grounding** — the closest publicly-available proxy for Google AI
Overviews / AI Mode) for your target queries and report which providers
cite your domain.
- **GEO — Generative Engine Optimization.** Optimize for Google AI Overviews,
ChatGPT search, Perplexity search, and other generative answer engines.
- **`llms.txt` validation** — checks existence, structure, AEO-language
signals, recommended sections.
- **AI bot accessibility** — verifies `GPTBot`, `ClaudeBot`, `PerplexityBot`,
`Google-Extended`, `Apple-Extended` access in `robots.txt`.

### Content quality (E-E-A-T)
- **E-E-A-T framework** per the September 2025 Quality Rater Guidelines update
- Author bylines, content dates, citations to authoritative sources
- Reading level, word count, keyword stuffing, link density, text-to-HTML ratio
- Industry-specific quality gates (SaaS, e-commerce, local, publisher, agency)

### Growth (not just audit)
- **Competitor keyword gap analysis** via the backlink/keyword data layer
- **Top competitor pages by organic traffic** to identify content types you're
missing (comparison pages, alternatives pages, listicles, glossary)
- **Opportunity scoring by impact ÷ effort** with KD (keyword difficulty)
filters
- **Programmatic SEO planning** with thin-content safeguards

## Why use this skill

| | Standard SEO tools | Amazing SEO Skill |
|---|---|---|
| Findings per audit | 5–20 high-level | 50+ specific, actionable |
| Real Core Web Vitals | Often missing | ✓ Playwright in-browser |
| Schema recommended fields | "X missing" | Names every missing field |
| Live LLM citation testing | ✗ | ✓ ChatGPT + Perplexity + Claude + Grok |
| Internal link graph | ✗ | ✓ true-orphan detection |
| Multi-page audit | Premium tier | ✓ free, scriptable |
| Industry templates | Generic | 6 templates: SaaS, e-com, local, publisher, agency, generic |
| Output format | Dashboard | Structured Markdown + JSON for piping |
| Run as Claude Code skill | ✗ | ✓ |
| Cost | $99–$999/mo | Free + your own API keys |

## Architecture — 4-layer data model

| Layer | Source | Purpose |
|-------|--------|---------|
| L0 | Claude reasoning + WebFetch | Analysis, prioritization, recommendations |
| L1 | Python scripts (~29 deterministic checkers) | Reproducible verdicts on robots, sitemap, redirects, security headers, broken links, images, hreflang, schema, llms.txt, internal links, CWV, CMS detection, JS rendering, content quality, local SEO, log analysis, AI visibility |
| L2 | Local CLI engines (configurable) | Real-browser CWV, 251-rule deep audit, live AEO citations |
| L3 | External APIs (Ahrefs, GSC) | Backlink data, real keyword performance |
| L4 | Multi-LLM ensemble (Anthropic, OpenAI, Perplexity, xAI, Google Gemini-with-Search) | Live AEO citation testing across all major AI surfaces |

Each finding carries a confidence label: **Confirmed** (data-backed),
**Likely** (data + reasoning), **Hypothesis** (reasoning fallback).

## Installation

### Lightweight mode (reasoning only — works on any Claude Code install)

```bash
git clone https://github.com/metawhisp/amazing-seo-skill.git \
~/.claude/skills/amazing-seo-skill
```

Then in Claude Code, just say `сделай SEO аудит example.com` or
`audit https://example.com` and the skill activates via its trigger keywords.

### Check what's active

After install, run the onboarding wizard — it probes prereqs, API keys,
and runs live smoke tests, then reports which layers (L0-L4) you have:

```bash
cd ~/.claude/skills/amazing-seo-skill
./tools/onboarding.sh
```

See [ONBOARDING.md](ONBOARDING.md) for the full reference: what each layer
unlocks, how to add API keys, troubleshooting.

### Full mode (all 4 layers, real CWV + live AEO)

```bash
git clone https://github.com/metawhisp/amazing-seo-skill.git \
~/.claude/skills/amazing-seo-skill
cd ~/.claude/skills/amazing-seo-skill

# Set engine package identifiers (your choice — installer is engine-agnostic)
DEEP_AUDIT_ENGINE_PKG="<npm-pkg-for-deep-audit>" \
DEEP_AUDIT_ENGINE_BIN_NAME="<bin-name>" \
AEO_CITATIONS_ENGINE_PKG_SPEC="<pip-spec-for-aeo>" \
AEO_CITATIONS_ENGINE_BIN_NAME="<bin-name>" \
AEO_CITATIONS_ENGINE_CONFIG_FILENAME="<config-filename>" \
./install.sh
```

For live AEO citation testing across 5 LLM surfaces, store API keys in
macOS Keychain:

```bash
security add-generic-password -s anthropic-api-key -a $USER -w
security add-generic-password -s openai-api-key -a $USER -w
security add-generic-password -s perplexity-api-key -a $USER -w
security add-generic-password -s x.ai-api-key -a $USER -w
security add-generic-password -s google-gemini-api-key -a $USER -w # Gemini + Google Search grounding (AI Overviews proxy)
```

For real Core Web Vitals via PageSpeed Insights API (improves rate limit
from ~25/day keyless to ~25,000/day), also add:

```bash
security add-generic-password -s google-psi-api-key -a $USER -w
```

## Usage

Just describe what you want. Claude picks up the skill automatically via
trigger keywords:

```
audit https://example.com — full site audit
page https://example.com/blog/post — single-page deep analysis
technical https://example.com — technical SEO only
schema https://example.com — Schema.org validation
geo https://example.com — AI Overviews readiness
aeo https://example.com "best email tool" — live LLM citation check
hreflang https://example.com — i18n / hreflang validation
growth https://example.com — competitor gap + opportunities
plan saas — strategic planning
competitor-pages generate — comparison page templates
```

Output: **SEO Health Score (0–100)** + prioritized action plan
(Critical / High / Medium / Low) with confidence labels.

## Use cases

- **Pre-launch audit** before shipping a new site or major redesign
- **Quarterly SEO review** with month-over-month tracking
- **AI search visibility audit** — find out if your domain is actually cited
by ChatGPT / Perplexity / Claude / Grok
- **Competitor research** for content strategy
- **Schema markup migration** when moving CMS or redesigning templates
- **International SEO** before launching new locale versions
- **Programmatic SEO planning** — quality gates prevent thin-content traps

## Industry templates

Built-in playbooks for 6 business types under `industry/`:

- **SaaS** — pricing, features, integrations, free trial signals
- **E-commerce** — product schema, faceted nav, OOS handling
- **Local service** — NAP, LocalBusiness schema, service-area pages
- **Publisher** — Article schema, author E-E-A-T, content velocity
- **Agency** — case studies, portfolio, industry pages
- **Generic** — fallback for hybrid models

The orchestrator auto-detects business type from homepage signals and applies
the right template.

## Trigger keywords

The skill activates automatically when any of these appear in your prompt:
`SEO`, `audit`, `schema`, `structured data`, `JSON-LD`, `Core Web Vitals`,
`INP`, `LCP`, `CLS`, `sitemap`, `E-E-A-T`, `AI Overviews`, `GEO`, `AEO`,
`technical SEO`, `content quality`, `page speed`, `hreflang`, `programmatic
SEO`, `competitor pages`, `growth opportunities`, `keyword gap`,
`llms.txt`, `AI search`, `LLM citations`.

## Repository layout

```
amazing-seo-skill/
├── SKILL.md # entry-point orchestrator (auto-loaded by Claude)
├── README.md # this file
├── install.sh # full-mode installer (engine-agnostic)
├── skills/ # 13 sub-skill modules — each works standalone too
├── agents/ # parallel sub-agents (growth-finder)
├── scripts/ # Python deterministic checkers
├── tools/ # user-facing wrappers (cwv-checker, aeo-citations, ...)
├── .bin/ # internal engine wrappers (env-driven, brand-neutral)
├── integrations/ # Ahrefs, GSC integration guides
├── references/ # CWV thresholds, E-E-A-T, quality gates, schema types
├── industry/ # 6 industry templates
├── schema/ # JSON-LD templates
├── hooks/ # optional pre-commit SEO validation
└── docs/ # reference docs
```

## Status

Active development. v0.7 series — 29 deterministic checkers + 6 orchestrator
tools, all verified end-to-end on production sites. See [releases](https://github.com/metawhisp/amazing-seo-skill/releases) for changelog.

## Contributing

Issues and pull requests welcome. The skill is intentionally **engine-
agnostic**: deep-audit and AEO-citations engines are configured per-environment,
so you can swap implementations without forking.

## License

Apache License 2.0 — see [LICENSE](LICENSE).

## Tags