# Amazing Seo Skill

> >

- **Type:** Skill
- **Install:** `agentstack add skill-metawhisp-amazing-seo-skill-amazing-seo-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [metawhisp](https://agentstack.voostack.com/s/metawhisp)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [metawhisp](https://github.com/metawhisp)
- **Source:** https://github.com/metawhisp/amazing-seo-skill
- **Website:** https://github.com/metawhisp/amazing-seo-skill

## Install

```sh
agentstack add skill-metawhisp-amazing-seo-skill-amazing-seo-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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
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/.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 |
| `redirect_chain_checker.py ` | 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 ` | 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 ` | 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` |
| `images_audit.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 |
| `hreflang_checker.py ` | BCP-47 codes, x-default, self-reference, reciprocity (parallel) | `--check-reciprocity` |
| `schema_recommended_fields.py ` | Per-schema-item required vs recommended field coverage; per-item completeness 0-100 | Article: per Google "no required fields" |
| `llms_txt_checker.py ` | llms.txt existence, structure, link-validity (HEAD probe of referenced URLs), AEO-language heuristics | `--skip-links` for fast mode |
| `internal_link_graph.py ` | Crawl-built adjacency: true orphans (sitemap not linked), sitemap gaps, depth-4+ pages, hub pages, dead-ends | `--max-pages`, `--max-depth` |
| `psi_checker.py ` | 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  "" …` | 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 ` | 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 ` | 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 ` | 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 ` | 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 ` | 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 ` | 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 ""` | 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 ` | **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 ` | Extract title/meta/headings/canonical/hreflang/images/links/schema/word-count from saved HTML | Used internally by `page_score.py` |
| `fetch_page.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 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 ` | 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 ` | 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](https://github.com/metawhisp)
- **Source:** [metawhisp/amazing-seo-skill](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-metawhisp-amazing-seo-skill-amazing-seo-skill
- Seller: https://agentstack.voostack.com/s/metawhisp
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.