audit-seo

name	audit-seo
description	Audit SEO for any Next.js App Router project. Checks technical SEO, metadata, structured data, performance, i18n, LLM content, and Core Web Vitals readiness. Generates a scored report in docs/.

SEO Audit

Audit a Next.js App Router project and produce a scored report at docs/SEO-AUDIT-REPORT-{YYMMDD}.md.

---

Step 0: Ask 3 Questions (REQUIRED — before reading any file)

Before I start the audit, 3 quick questions:

1. What type is this website?
   A) Blog / News / Magazine
   B) E-commerce / Marketplace
   C) SaaS / Web Application
   D) Local Business / Service Provider
   E) Portfolio / Agency / Personal Brand
   F) Documentation / Knowledge Base

2. Is this a multilingual site?
   A) Yes — which locales? (e.g. en, ar, fr)
   B) No — single language

3. Does it have dynamic content routes? (blog posts, products, etc.)
   A) Yes
   B) No — all static pages

The answers determine which checks are scored as required vs. optional.

---

Execution Steps

Run these checks in order, collecting evidence for every item:

1. Check src/app/layout.tsx — root metadata fields
2. Grep metadata across all layout.tsx and page.tsx files
3. Grep generateMetadata in dynamic route files
4. Check src/app/sitemap.ts or public/sitemap.xml
5. Check src/app/robots.ts or public/robots.txt
6. Check src/app/not-found.tsx
7. Grep application/ld+json across all files — collect all schema types found
8. Check public/og-image.png exists
9. Check src/app/og/route.tsx for dynamic OG
10. Grep next/image vs raw <img usage
11. Grep 'use client' — count client components in page routes
12. Check src/app/llms.txt/route.ts and src/app/llms-full.txt/route.ts
13. Grep hreflang or alternates if multilingual
14. Grep canonical in metadata
15. Check next.config.* for i18n config and image domains
16. Run npm run build (or next build) — note any errors or warnings
17. Calculate scores per category
18. Write report

---

Audit Checklist

Category 1: Technical SEO (20 points)

Check	Tool	Points	Pass	Fail
Build succeeds with no errors	npm run build	5	No errors	Build fails
sitemap.ts or sitemap.xml exists	File check	4	Exists	Missing
robots.ts or robots.txt exists	File check	3	Exists	Missing
Custom 404 (not-found.tsx)	File check	2	Custom design	Default Next.js
Clean URL structure (kebab-case, no query params)	Route check	3	/blog/my-post	/blog?id=123
metadataBase set in root layout	Grep	3	Set	Missing

Category 2: Metadata & On-Page SEO (25 points)

Check	Tool	Points	Pass	Fail
Root layout has title.default + title.template	Grep layout.tsx	4	Both set	Missing
Root layout has description (150–160 chars)	Read	3	Unique, correct length	Generic/too short
Each page has unique title	Grep all layouts	4	All unique	Duplicates found
Each page has unique description	Grep all layouts	4	All unique	Missing/duplicates
openGraph fully configured (title, description, url, images)	Grep	4	Complete	Partial/missing
twitter card configured	Grep	2	Card + image	Missing
alternates.canonical on dynamic pages	Grep generateMetadata	3	Present	Missing
viewport exported separately (not in metadata)	Grep	1	Correct	In metadata

Category 3: Structured Data (20 points)

Check	Required for	Points	Pass	Fail
WebSite JSON-LD	All	3	Present	Missing
Organization/Person/LocalBusiness	All	4	Correct type	Missing
BreadcrumbList on inner pages	All	3	Present	Missing
Article/BlogPosting on posts	Blog (A)	4	Present	Missing
Product + Offer on product pages	E-commerce (B)	4	Present	Missing
SoftwareApplication on app pages	SaaS (C)	4	Present	Missing
LocalBusiness with address/hours	Local (D)	4	Complete	Missing
FAQPage where applicable	SaaS/Blog	3	Present	Missing
datePublished + dateModified	Blog/Docs	2	Both set	Missing
Validated (no errors)	All	3	No errors	Has errors

For scoring: count only the schemas required for the site type (answer 1). Schemas for other types are N/A.

Category 4: Performance & Images (15 points)

Check	Tool	Points	Pass	Fail
All images use next/image	Grep <img	5	Zero raw <img>	Any found
LCP image has priority prop	Grep	3	Set on hero images	Missing
Client components minimal in page routes	Grep 'use client'	3	Only where needed	Excessive
Static OG image exists (public/og-image.png)	File check	2	1200×630px	Missing
Dynamic OG image route exists	File check	2	Edge route	Missing

Category 5: Content Quality (10 points)

Check	Tool	Points	Pass	Fail
Each page has a single H1	Read pages	3	One H1	Multiple/none
Heading hierarchy (H1 > H2 > H3)	Read pages	2	Proper nesting	Skipped levels
All next/image have descriptive alt	Grep	3	Descriptive	Missing/empty
Internal links use next/link	Grep <a href	2	Zero bare anchors	Any found

Category 6: Multilingual / i18n (5 points — only if answer 2 = A)

Check	Tool	Points	Pass	Fail
hreflang alternates on all localized pages	Grep alternates	2	All locales	Missing
x-default alternate set	Grep	1	Set	Missing
Locale in OG (openGraph.locale)	Grep	1	Correct	Missing
i18n sitemap with alternates.languages	Read sitemap.ts	1	Present	Missing

If single language: award full 5 points (N/A).

Category 7: LLM Content / AI Discoverability (5 points)

Check	Tool	Points	Pass	Fail
llms.txt route exists	File check	1	Exists	Missing
llms-full.txt route exists	File check	1	Exists	Missing
llms.txt has content (name, description, links)	Read	1	Complete	Empty/generic
llms-full.txt is comprehensive	Read	1	Detailed	Brief
robots.txt allows AI bots (GPTBot, Claude-Web, etc.)	Read robots.ts	1	Allowed	Blocked/missing

---

Scoring

Points Tally

Category 1: Technical SEO      — max 20
Category 2: Metadata & On-Page — max 25
Category 3: Structured Data    — max 20
Category 4: Performance        — max 15
Category 5: Content Quality    — max 10
Category 6: i18n               — max  5
Category 7: LLM Content        — max  5
                                 ————————
Total                          — max 100

Score Thresholds

Score	Status	Meaning
95–100	Excellent	Production-ready, fully optimized
85–94	Good	Minor gaps, mostly solid
70–84	Fair	Several important items missing
55–69	Poor	Significant SEO work needed
< 55	Critical	Core SEO requirements not met

Deduction Rules

• Critical item missing (metadataBase, sitemap, structured data for site type): −5 each
• Important item missing (canonical, OG image, unique titles): −3 each
• Nice-to-have missing (dynamic OG, llms-full.txt): −1 each
• Build fails: cap score at 50 regardless of other checks

---

Report Template

Write the completed report to docs/SEO-AUDIT-REPORT-{YYMMDD}.md:

# SEO Audit Report

**Project:** {PROJECT_NAME}
**Date:** {DATE}
**Domain:** {DOMAIN}
**Site Type:** {SITE_TYPE}
**Audited by:** Claude Code /audit-seo

---

## Overall Score: {SCORE}/100 — {STATUS}

| Category             | Score | Max     | Status |
| -------------------- | ----- | ------- | ------ |
| Technical SEO        |       | 20      |        |
| Metadata & On-Page   |       | 25      |        |
| Structured Data      |       | 20      |        |
| Performance & Images |       | 15      |        |
| Content Quality      |       | 10      |        |
| i18n / Multilingual  |       | 5       |        |
| LLM Content          |       | 5       |        |
| **Total**            |       | **100** |        |

---

## Issues Found

### Critical (fix immediately)

- [ ] ...

### High Priority (fix before launch)

- [ ] ...

### Medium Priority (fix soon)

- [ ] ...

### Low Priority / Nice-to-have

- [ ] ...

---

## What's Working Well

- ...

---

## Quick Wins (easiest fixes first)

- [ ] Add `metadataBase` to root layout — 5 min
- [ ] Add `alternates.canonical` to dynamic routes — 10 min
- [ ] Replace `<img>` tags with `next/image` — 30 min
- [ ] ...

---

## Structured Data Status

| Schema Type         | Required        | Found | Valid |
| ------------------- | --------------- | ----- | ----- |
| WebSite             | Yes             |       |       |
| Organization        | Yes             |       |       |
| BreadcrumbList      | Yes             |       |       |
| Article/BlogPosting | {if Blog}       |       |       |
| Product             | {if E-commerce} |       |       |
| LocalBusiness       | {if Local}      |       |       |

---

## File Inventory

| File                             | Status  | Notes |
| -------------------------------- | ------- | ----- |
| `src/app/layout.tsx`             | ✅ / ❌ |       |
| `src/app/sitemap.ts`             | ✅ / ❌ |       |
| `src/app/robots.ts`              | ✅ / ❌ |       |
| `src/app/not-found.tsx`          | ✅ / ❌ |       |
| `src/app/og/route.tsx`           | ✅ / ❌ |       |
| `src/app/llms.txt/route.ts`      | ✅ / ❌ |       |
| `src/app/llms-full.txt/route.ts` | ✅ / ❌ |       |
| `public/og-image.png`            | ✅ / ❌ |       |

---

## Next Steps

1. Fix all Critical issues
2. Fix High Priority issues
3. Run `/seo-optimizer-nextjs` for any missing implementations
4. Validate structured data: https://search.google.com/test/rich-results
5. Test OG tags: https://www.opengraph.xyz
6. Re-run `/audit-seo` after fixes to verify score improvement

---

Validation Tools Reference

Tool	URL	What it checks
Google Rich Results Test	https://search.google.com/test/rich-results	Structured data validity
Google Search Console	https://search.google.com/search-console	Index coverage, Core Web Vitals
PageSpeed Insights	https://pagespeed.web.dev	LCP, INP, CLS scores
Open Graph Debugger	https://www.opengraph.xyz	OG/Twitter card preview
Schema Markup Validator	https://validator.schema.org	JSON-LD validation
Lighthouse	Chrome DevTools	Performance, SEO, accessibility