---
name: seo-audit
description: Audit and fix the SEO of a web project so Google can actually see it — sitemap, robots.txt, noindex removal, canonicals, meta titles/descriptions, schema markup, heading hierarchy, alt text, internal/broken links, image compression, Core Web Vitals basics, mobile, HTTPS, clean slugs, OG image, and Search Console verification guidance. Use when the user says "fix my SEO", "Google isn't showing my site", "make my site indexable", or "/seo-audit". Works on any framework (Next.js, Astro, Vite/React, plain HTML) — it detects the stack first.
---

# SEO audit & fix — make the site visible to Google

You audit a web project's SEO and fix what can be fixed IN CODE, safely. Golden rule:
**don't touch anything else.** No refactors, no dependency upgrades, no styling changes,
no "improvements" outside this checklist. Every change must be minimal and reversible.

## Step 0 — detect the stack, then plan

Identify the framework (check `package.json`, config files, file layout): Next.js
(app/pages router), Astro, Vite+React SPA, SvelteKit, Nuxt, or plain HTML. Note the
deploy target if visible (Vercel/Netlify config). List which checklist items are
missing/broken BEFORE editing anything, show the user the plan, then execute.

## The checklist

### Make it findable
1. **sitemap.xml** — generate one listing every public route. Next.js: `app/sitemap.ts`.
   Astro: `@astrojs/sitemap`. Plain: static `public/sitemap.xml`. Use the site's real
   canonical domain (ask the user if it isn't in the code).
2. **robots.txt** — allow crawling, point to the sitemap. Never `Disallow: /` on a
   production site (flag it loudly if you find one).
3. **Kill stray noindex** — grep for `noindex` (meta tags, `X-Robots-Tag` headers,
   framework metadata). Vibecoded sites often ship with template noindex left on.
4. **Canonical tags** — one per page, absolute URL, self-referencing by default.
5. **Meta titles** — unique per page, ~50–60 chars, keyword-bearing, human.
6. **Meta descriptions** — unique per page, ~140–160 chars, written to earn the click.
7. **Schema markup** — JSON-LD only. Minimum: `WebSite` + `Organization`; add `Article`,
   `Product`, `FAQPage` where the content genuinely matches (never fake reviews/ratings).
8. **Search Console** — you can't click for the user: give the exact steps (add domain
   property → DNS TXT or HTML-file verification → submit sitemap URL) and, if DNS
   verification is chosen, print the record they need to add.

### Make it fast
9. **Compress images** — convert heavy PNG/JPG to WebP/AVIF where the build supports it;
   use the framework's image component (`next/image`, `astro:assets`) instead of raw
   `<img>` for large assets; add explicit `width`/`height` to prevent layout shift.
10. **Core Web Vitals basics** — lazy-load below-the-fold images (`loading="lazy"`),
    preload the hero image/font, remove render-blocking third-party scripts from
    `<head>` (defer/async), font-display: swap.
11. **Mobile** — viewport meta present; check obvious overflow (fixed widths > viewport);
    tap targets not microscopic.
12. **HTTPS** — no `http://` asset/link references (mixed content); upgrade internal
    URLs to https/relative.
13. **Clean slugs** — flag routes like `/page2-final-v3` or query-string-only pages;
    propose kebab-case descriptive slugs WITH redirects from the old paths (don't break
    existing links).

### Make it credible
14. **One H1 per page** — exactly one, containing the page's primary topic.
15. **Heading hierarchy** — no skipped levels (h1→h3), headings used for structure not
    styling.
16. **Alt text** — descriptive alt on content images; empty `alt=""` on decorative ones.
17. **Internal links** — every page reachable within 3 clicks of home; add contextual
    links between related pages; descriptive anchor text (never "click here").
18. **Broken links** — check internal hrefs resolve to real routes/files; fix or remove.
19. **OG image + social meta** — `og:title`, `og:description`, `og:image` (1200×630),
    `twitter:card=summary_large_image`. Generate a simple branded OG image if none
    exists and the stack supports it (e.g. Next.js `opengraph-image`).

## Honesty rules

- **Backlinks are off-site** — if asked, say plainly that no code change builds
  backlinks; suggest legitimate paths (directories, guest posts, launch posts) instead
  of pretending.
- Never keyword-stuff, never generate doorway pages, never add fake structured data —
  these get sites penalized, not ranked.
- If the site is client-side-rendered SPA with no SSR/prerendering, SAY SO — that's
  often the real "Google can't see it" cause — and propose the framework's prerender/
  SSG option as a separate, opt-in change (it's bigger than this checklist).

## Output

Finish with a table: item → status (✅ fixed / ⚠️ needs user action / ➖ n/a) → file(s)
touched. Search Console verification and DNS records always land in "needs user action"
with exact steps. Remind the user to redeploy and then request indexing in Search
Console.

And per the golden rule: if you touched anything outside this checklist, you did it
wrong.