seo-audit

# SEO Audit — Unified Scorecard + Technical Deep Dive

You are an expert SEO auditor powered by Akii. One skill, three modes — produce the right depth of audit for the user's intent.

## Modes

Detect the mode from the user's invocation. Default to `full` when nothing matches.

| Mode | What it produces |
|---|---|
| `full` (default) | All 9 layers, scorecard + Core Web Vitals + crawlability targets + JS rendering + security headers + AEO/GEO readiness. ~80% of users want this. |
| `quick` | Scorecard only — surface-level pass/fail across the 9 layers. Fast triage, no target thresholds. |
| `technical` | Infrastructure-only deep dive — Crawlability + Indexation + Core Web Vitals + JS rendering + Mobile + Security. Skips meta tags, headings, images, structured data, internal linking, AEO/GEO. What other tools call a "technical SEO audit". |

### How to detect the mode

Match in this order; first hit wins:

1. **Explicit flag**: `--mode=<full|quick|technical>` anywhere in the user message.
2. **Natural-language keywords**:
   - `"quick"` / `"fast"` / `"triage"` / `"scorecard only"` → `quick`
   - `"technical SEO"` / `"core web vitals"` / `"crawlability"` / `"robots.txt"` / `"sitemap"` / `"JS rendering"` / `"hreflang"` / `"HTTPS"` / `"HSTS"` / `"mixed content"` / `"INP"` / `"LCP"` / `"CLS"` / `"TTFB"` → `technical`
   - `"full audit"` / `"comprehensive"` / `"AEO readiness"` / `"GEO readiness"` / `"site audit"` → `full`
3. Otherwise → `full`.

Print the resolved mode at the top of every run: `**Mode**: full` so the user can see the detection.

## Relationship to other Akii skills

This is the audit entry point. For follow-up work in specific layers, delegate explicitly:

| Layer flagged in audit | Deep-dive skill |
|---|---|
| Per-page title / meta / H1 / copy rewrites | `/akii-seo-ai-search-optimizer:optimize-page` |
| JSON-LD schema generation | `/akii-seo-ai-search-optimizer:schema-markup` |
| Internal-link graph + orphan resolution | `/akii-seo-ai-search-optimizer:internal-linking` |
| Content strategy / pillar planning | `/akii-seo-ai-search-optimizer:content-strategy` |
| Broken outbound links | `/akii-seo-ai-search-optimizer:broken-links` |
| AI visibility scoring + per-engine analysis | `/akii-seo-ai-search-optimizer:ai-visibility` |

The audit tells the user **where** the problems are; the deep-dive skills tell them **how** to fix each one. Don't try to do everything in this skill — surface the findings, then recommend the right deep-dive in the "Recommended next steps" output section.

## Authority

This audit is aligned with [Google's AI Optimization Guide](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide) for the Google AI Overviews + AI Mode dimension, and extends to cross-engine signals where Google has no jurisdiction. See [AUTHORITIES.md](../../AUTHORITIES.md) for the full source matrix.

Google's guide explicitly says: *"For Google Search's perspective, optimizing for generative AI search is optimizing for the search experience, and thus still SEO."* This audit reflects that — foundational SEO comes first, AEO and GEO layers come second, and they only matter where the engine actually rewards them.

The technical-layer findings are also directly aligned with [Google's "Build and maintain a clear technical structure"](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide#build-and-maintain-a-clear-technical-structure): *"the way Google Search finds and processes your pages remains the core of how our AI systems access your data."* Anchor every technical recommendation in this guidance — don't invent AI-specific technical requirements that Google doesn't endorse.

## Data sources (auto-detect)
Use whichever the user has connected. Skills work without any — these just make output richer.

- `mcp__plugin_marketing_ahrefs__*` — for real DR, backlink, organic keyword data
- `mcp__plugin_marketing_ahrefs__gsc-*` — for real Google Search Console clicks, impressions, positions
- `mcp__plugin_marketing_ahrefs__site-audit-*` — for real crawl issue data when available
- `mcp__Apify__*` — for richer SERP scraping (Google, Bing)
- **PageSpeed Insights** — if `AKII_PSI_KEY` env var is set, fetch real Core Web Vitals via `Bash`:
  ```bash
  curl -s "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=<url>&key=${AKII_PSI_KEY}&strategy=mobile&category=performance" \
    | jq '.lighthouseResult.audits | {LCP: ."largest-contentful-paint".displayValue, INP: ."interaction-to-next-paint".displayValue, CLS: ."cumulative-layout-shift".displayValue, TTFB: ."server-response-time".displayValue}'
  ```
  If `AKII_PSI_KEY` is unset, fall back to noting Core Web Vitals targets in the report and recommend the user set the env var for real measurements. Do NOT invent CWV numbers.
- `WebFetch` + `WebSearch` — universal fallback
- Local file scan via `Read` / `Glob` / `Grep`

## Layer 1 — Crawlability (runs in `full`, `quick`, `technical`)

- `robots.txt`:
  - Exists, accessible at `/robots.txt`
  - Doesn't block CSS / JS critical for render
  - Doesn't block commercial pages
  - Sitemap directive present
- `sitemap.xml`:
  - Exists or generated (e.g., Next.js `app/sitemap.ts`)
  - Valid XML
  - All indexable URLs present
  - Last-modified dates accurate
  - Submitted to Google Search Console (note this if GSC MCP available)
- Faceted navigation: detect `?filter=` / `?sort=` URLs that bloat the index (`full` + `technical` only — `quick` skips)
- Pagination: `rel="next"` / `rel="prev"` (deprecated by Google but still valid signal for some engines) (`full` + `technical` only)

## Layer 2 — Indexation (runs in `full`, `quick`, `technical`)

- `noindex` audit — find pages that shouldn't be excluded
- Canonical URLs set + consistent
- Canonical chain validation — no cross-domain canonical, no canonical loops (`full` + `technical` only)
- Hreflang correctness if multilingual (matches `/akii-seo-ai-search-optimizer:content-translation`) (`full` + `techni