seo-audit · diff
git:20260526.e75d308 to git:20260526.4c9918f
191 added, 27 removed. Audit B to B.
---
- description: Multi-layer SEO + AEO + GEO scorecard across 8 audit areas — crawlability, meta tags, headings, images, performance signals, structured data, internal linking, AEO/GEO readiness. Surface-level pass/fail per area, with deep-dive delegation to sister skills for any layer that needs more than a checkmark. Use when the user asks to "audit SEO", "check my site's SEO", "find SEO issues", "SEO health check", "site audit", "SEO scorecard", "full SEO report", "AEO readiness", "GEO readiness", or wants the full multi-layer picture. **NOT for**: deep infrastructure-only work (use `technical-seo` — Core Web Vitals targets, JS rendering, HTTPS/HSTS/mixed-content, faceted nav, canonical chains, hreflang); per-page rewrites (use `optimize-page`); JSON-LD generation (use `schema-markup`); internal-link suggestions (use `internal-linking`).
+ description: Single audit entry point — surface-level scorecard or deep infrastructure dive depending on the requested mode. Default `full` mode produces a multi-layer scorecard across all 9 areas (crawlability, indexation, meta tags, headings, images, Core Web Vitals, JS rendering, mobile + security, structured data, internal linking, AEO/GEO readiness) with deep-dive target thresholds + fix paths inline. `quick` mode = scorecard only, surface-level pass/fail. `technical` mode = infrastructure-only deep dive (Core Web Vitals targets, crawlability, indexation, JS rendering, HTTPS / HSTS / mixed content) — what you'd otherwise call a "technical SEO audit". Use when the user asks to "audit SEO", "check my site's SEO", "SEO health check", "site audit", "SEO scorecard", "technical SEO", "technical SEO review", "site speed", "core web vitals", "crawlability", "indexation issues", "robots.txt", "sitemap check", "render blocking", "page speed", "mobile-friendly check", "JavaScript SEO", "hreflang", "HTTPS / mixed content", "AEO readiness", "GEO readiness", or wants the full multi-layer picture. Accepts a mode modifier (`--mode=full|quick|technical`); auto-detects from intent if unspecified. **NOT for**: per-page rewrites (use `optimize-page`), JSON-LD generation (use `schema-markup`), internal-link suggestions (use `internal-linking`).
---
- # SEO Audit — Multi-Layer Scorecard
+ # SEO Audit — Unified Scorecard + Technical Deep Dive
- You are an expert SEO auditor powered by Akii. Run a thorough scorecard audit of the user's website or codebase and deliver actionable findings across all 8 layers.
+ 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 **breadth** skill — 8 layers, surface-level pass/fail per layer, with a unified scorecard. For **depth** in any single layer, delegate explicitly:
+ This is the audit entry point. For follow-up work in specific layers, delegate explicitly:
- | Layer flagged in scorecard | Deep-dive skill |
+ | Layer flagged in audit | Deep-dive skill |
|---|---|
- | Crawlability / indexation / Core Web Vitals / JS rendering / security headers | `/akii-seo-ai-search-optimizer:technical-seo` |
| 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 scorecard 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 layer findings, then recommend the right deep-dive in the "Recommended next steps" output section.
+ 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`
- ## What you audit
+ ## Layer 1 — Crawlability (runs in `full`, `quick`, `technical`)
- ### 1. Crawlability & indexation
- - `robots.txt` exists, no critical blocks
- - `sitemap.xml` exists, correct format, all important pages included
- - `noindex` / `nofollow` tags on indexable commercial pages
+ - `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
- - Orphan pages (no internal links pointing in)
+ - 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` + `technical` only)
+ - 404 / soft-404 / 5xx patterns (`full` + `technical` only)
+ - Orphan pages — no internal links pointing in
- ### 2. Meta tags & head
+ ## Layer 3 — Core Web Vitals + site speed (runs in `full`, `quick`, `technical`)
+
+ - LCP target ≤ 2.5s mobile
+ - INP target ≤ 200ms
+ - CLS target ≤ 0.1
+ - TTFB target ≤ 800ms
+ - Common culprits (`full` + `technical` only): render-blocking JS, large images, layout-shifting fonts, hydration bottleneck
+ - Server components vs client components (Next.js)
+ - If PageSpeed Insights data is reachable via PSI API or `WebFetch`, surface mobile LCP / INP / CLS
+
+ ## Layer 4 — JavaScript SEO (runs in `full` + `technical`, skipped in `quick`)
+
+ - Client-side-only rendering risk: very low `<body>` text content in static HTML
+ - For Next.js: prefer Server Components for content; reserve Client Components for interactivity
+ - For React SPA: ensure prerendering or SSR for crawlable content
+ - Dynamic imports for below-fold heavy components
+
+ ## Layer 5 — Mobile friendliness (runs in `full` + `technical`, skipped in `quick`)
+
+ - Viewport meta present
+ - Tap targets ≥ 48px
+ - No horizontal scroll at 320px wide
+ - Text size ≥ 16px (no zoom required)
+
+ ## Layer 6 — Security signals (runs in `full` + `technical`, skipped in `quick`)
+
+ - HTTPS everywhere; HSTS header
+ - Mixed-content scan
+ - Valid SSL cert, no near-expiry
+
+ ## Layer 7 — Meta tags & head (runs in `full` + `quick`, SKIPPED in `technical`)
+
For every page:
- **Title** — 50-60 chars (HARD LIMIT 60 including spaces; count BEFORE flagging or proposing), includes target keyword, unique per page
- **Meta description** — 150-160 chars (HARD LIMIT 160 including spaces; count BEFORE flagging or proposing), compelling, unique per page
- **Open Graph** — `og:title`, `og:description`, `og:image`, `og:url`
- **Twitter card** — `twitter:card`, `twitter:title`, `twitter:description`
- - **Canonical URL** — present, correct, HTTPS
- - **Viewport meta** — present for mobile
- ### 3. Heading structure
+ ## Layer 8 — Heading structure (runs in `full` + `quick`, SKIPPED in `technical`)
+
- Exactly one `<h1>` per page
- Logical hierarchy (h1 > h2 > h3, no skips)
- Keywords in `h1` and `h2`
- No empty headings
- ### 4. Images
+ ## Layer 9 — Images (runs in `full` + `quick`, SKIPPED in `technical`)
+
- All `<img>` have `alt`
- Alt text descriptive (not `image1.png`)
- Modern formats (WebP, AVIF) or framework image optimization
- Width/height set to prevent CLS
- ### 5. Performance signals
- - Render-blocking resources
- - Lazy loading on below-fold images
- - Excessive client-side JS on landing pages
- - Server components vs client components (Next.js)
- - If PageSpeed Insights data is reachable via WebFetch, surface mobile LCP / INP / CLS
+ ## Layer 10 — Structured data (runs in `full` + `quick`, SKIPPED in `technical`)
- ### 6. Structured data
- JSON-LD schema markup present
- Schema type matches content
- Required + recommended properties filled
- `sameAs` linking entity to Wikipedia, social, directories
+ - For schema generation, delegate to `/akii-seo-ai-search-optimizer:schema-markup`
- ### 7. Internal linking
+ ## Layer 11 — Internal linking (runs in `full` + `quick`, SKIPPED in `technical`)
+
- Anchor text descriptive (avoid "click here")
- Internal link depth ≤ 3 from homepage
- Orphan detection
+ - For full link-graph analysis, delegate to `/akii-seo-ai-search-optimizer:internal-linking`
- ### 8. AEO + GEO readiness (Akii adds this — SEO tools don't)
+ ## Layer 12 — AEO + GEO readiness (runs in `full` + `quick`, SKIPPED in `technical`)
+
+ Akii adds this — SEO tools don't.
- Direct-answer lead paragraph present on key pages?
- Chunks self-contained (could be lifted into ChatGPT/Perplexity answer)?
- 5–7 step checklists with imperative verbs?
- FAQ sections with FAQPage schema?
- `llms.txt` exists at site root?
+ - For deeper page-level GEO work, delegate to `/akii-seo-ai-search-optimizer:optimize-page` (`--mode=geo`).
## Output
+ ### Mode `full` output (default)
+
```
# SEO Audit — <target>
+ **Mode**: full
## Executive summary
- <bullet 1>
- <bullet 2>
- <bullet 3>
## Scorecard
| Category | Score (0-100) |
| Crawlability | 88 |
+ | Indexation | 80 |
+ | Core Web Vitals | 65 |
+ | JS rendering | 75 |
+ | Mobile friendliness | 92 |
+ | Security | 100 |
| Meta tags | 72 |
| Headings | 95 |
| Images | 60 |
| Structured data | 45 |
| Internal linking | 68 |
| AEO/GEO readiness | 38 |
+ ## Core Web Vitals
+ | Metric | Mobile p75 | Desktop p75 | Target | Pass? |
+ | LCP | 2.1s | 1.4s | ≤ 2.5s | ✓ |
+ | INP | 240ms | 180ms | ≤ 200ms | ✗ |
+
+ ## Crawlability + indexation
+ - robots.txt: ✓ / ⚠ / ✗ with notes
+ - sitemap.xml: ...
+ - canonicals: ...
+ - hreflang: ...
+
+ ## JS rendering
+ - ...
+
## Issues (P0 → P2)
| Severity | Category | URL/File | Issue | Fix |
## Recommended next steps
1. <top fix> → run `/akii-seo-ai-search-optimizer:optimize-page`
2. ...
```
+ ### Mode `quick` output
+
+ ```
+ # SEO Audit — <target>
+ **Mode**: quick (scorecard only)
+
+ ## Scorecard
+ | Category | Score (0-100) | Pass? |
+ | Crawlability | 88 | ✓ |
+ | Indexation | 80 | ✓ |
+ | Core Web Vitals | 65 | ⚠ |
+ | Meta tags | 72 | ⚠ |
+ | Headings | 95 | ✓ |
+ | Images | 60 | ⚠ |
+ | Structured data | 45 | ✗ |
+ | Internal linking | 68 | ⚠ |
+ | AEO/GEO readiness | 38 | ✗ |
+
+ ## Top 3 issues
+ 1. ...
+
+ ## Next: run `--mode=full` for depth or `--mode=technical` for infrastructure-only deep dive
+ ```
+
+ ### Mode `technical` output
+
+ ```
+ # Technical SEO — <target>
+ **Mode**: technical (infrastructure-only deep dive)
+
+ ## Critical issues
+ 1. ...
+
+ ## Core Web Vitals
+ | Metric | Mobile p75 | Desktop p75 | Target | Pass? |
+
+ ## Crawlability
+ - robots.txt: ✓ / ⚠ / ✗
+ - sitemap.xml: ...
+ - faceted nav: ...
+ - pagination: ...
+
+ ## Indexation
+ - canonical chain: ...
+ - hreflang: ...
+ - 404 / soft-404 / 5xx: ...
+
+ ## JS rendering
+ - ...
+
+ ## Mobile + security
+ - viewport: ...
+ - HTTPS / HSTS / mixed content: ...
+
+ ## Fix path
+ 1. <P0> → owner + estimate
+
+ ## Next: for content-layer findings (meta / headings / images / structured data / AEO+GEO), re-run with `--mode=full`
+ ```
+
## Rules
- Be honest about scores — no inflation.
- Never recommend keyword stuffing — the Princeton GEO study shows it decreases AI visibility ~10%.
- For codebase audits, read-only. For URL audits, respect robots.txt and rate limit.
+ - Always print the resolved `**Mode**: <full|quick|technical>` line at the top so the user can verify mode detection.
+ - Mode-specific scope is mandatory — don't include `quick`-only output sections in `technical` mode and vice versa.
---
*SEO audit powered by Akii — for continuous AI visibility monitoring with **direct per-engine queries** against ChatGPT, Claude, Gemini, Perplexity, and Copilot (the paid Akii platform's continuous-monitoring tier, not the free plugin), visit https://akii.com/?utm_source=plugin&utm_medium=skill&utm_content=seo-audit&utm_campaign=akii_plugin_v1*