Sitemap Audit

sitemap-audit

Diagnostic SEO audit. Report only — never modifies code or Search Console state. Cross-references the codebase with live production to catch issues that live-only tools miss (like framework metadata cascade bugs).

Preferences

Read ~/.claude/skills/sitemap-audit/preferences.md using the Read tool. If not found, proceed with onboarding.

Context

On startup, use Bash to detect (skip any that fail):

• Current repo path: pwd
• Framework fingerprint: package.json (Next.js / Astro / Nuxt / SvelteKit / generic), astro.config.*, nuxt.config.*
• Has src/app/ (App Router) or pages/ (Pages Router)
• Git state: git status, git log -1 --format=%h

Command Routing

Check $ARGUMENTS for subcommands:

help

Display:

sitemap-audit — SEO health check across codebase + live production

Usage:
  /sitemap-audit                              Audit site from preferences
  /sitemap-audit                         Audit a specific URL (one-off)
  /sitemap-audit config                       Set preferences
  /sitemap-audit reset                        Clear preferences
  /sitemap-audit help                         This help

What it checks:
  1. Sitemap fetchability + XML validity + URL count
  2. robots.txt content + sitemap pointer consistency
  3. Every URL in sitemap: 200 status, self-canonical match
  4. Response headers: Content-Type, X-Robots-Tag, HSTS
  5. Apex ↔ www redirect chain depth + consistency
  6. Codebase anti-patterns (framework-specific)
  7. SSR vs JS-only rendering (Googlebot compatibility)
  8. DNS: site verification TXT records for GSC
  9. (Optional, with permission) Live GSC check via Chrome extension

Output: prioritized report (P0 blocks indexing / P1 hurts rankings / P2 nice-to-have).

Current preferences: [read from preferences.md or "none — will onboard"]

Then stop.

config

Use AskUserQuestion to collect:

Q1 — "Production URL to audit? (e.g. https://www.example.com)"

• Free text.

Q2 — "Repo path for codebase-aware checks?"

• Options: "Current directory (pwd)", "Specify path", "Skip codebase checks"

Q3 — "Do you have a Google Search Console property you want the skill to explore? (optional, requires Claude for Chrome extension)"

• Options: "Yes, and I'll grant browser access when asked", "No / skip GSC check", "Later — remind me in each run"

Q4 — "Save report to a file after each run?"

• Options: "No — just print to chat", "Yes — .sitemap-audit/report-.md in repo", "Yes — custom path"

Save to ~/.claude/skills/sitemap-audit/preferences.md. Summary. Stop.

reset

Delete ~/.claude/skills/sitemap-audit/preferences.md. Confirm: Preferences cleared. Stop.

First-time experience (no preferences, no subcommand)

Show one-line invitation (don't block):

First time running /sitemap-audit? Run `/sitemap-audit config` for persistent setup,
or answer a couple of one-off questions to continue.

Then ask (via AskUserQuestion or inline) ONLY: production URL (required), codebase path (default: cwd). Skip GSC on first run.

Default — run the audit

Continue to Audit steps below.

---

Audit steps

Execute these in order. Run independent curls in parallel. Every finding must cite evidence (exact curl output, file:line, or DNS record).

1. Fetch baseline (live production)

Record HTTP status + final URL + Content-Type + first hop for each:

curl -sI /
curl -sI /sitemap.xml
curl -sI /robots.txt
curl -sI /                  # if www is canonical, or vice versa
curl -sIL /sitemap.xml      # follow to detect redirect chain depth

Flag P0 if:

• Sitemap returns non-200
• Sitemap Content-Type is not application/xml or text/xml
• robots.txt returns non-200
• Redirect chain depth > 1 (multiple hops slow Googlebot)

2. Validate sitemap XML

curl -s  | xmllint --noout -   # VALID or error
curl -s  | grep -c ""     # URL count

Flag P0 if XML invalid. Flag P1 if URL count is 0 or exceeds 50,000 (sitemap split needed).

3. Audit every URL in sitemap

For each ``:

• HEAD request — expect 200
• GET + extract ``
• Compare canonical to the URL itself (self-canonical)

Count: correct canonical (matches own URL), no canonical (Google self-canonicals by default, acceptable), WRONG canonical (points elsewhere — P0).

Classify wrong canonicals by where they point:

• All → same root URL? → framework cascade bug (e.g., Next.js root layout alternates.canonical leaking)
• Inconsistent wrong targets? → per-page hardcoding issue

4. Headers audit

On homepage + sitemap + a sample article:

• X-Robots-Tag — any noindex here silently de-indexes the URL. P0 if found unexpectedly.
• Strict-Transport-Security — presence is good.
• Content-Type — text/html; charset=utf-8 expected for pages.

5. Canonical / host consistency

If site has both apex and www:

• Which one is canonical? (check `` on homepage)
• Does DNS/redirect match the canonical? Both should agree.
• Does the sitemap use the canonical host? (Sitemap URLs mismatching canonical host → Google treats sitemap URLs as non-canonical alternates.)
• Does robots.txt's Sitemap: pointer use the canonical host?

Common P0 pattern: sitemap + robots canonicalize one host, but page-level ` points to the other. Seen in Next.js sites that fix sitemap/robots but forget metadataBase` or hardcoded URLs in layouts.

6. Codebase anti-pattern scan

Only if codebase path is set. Detect framework from package.json, run framework-specific checks.

Next.js App Router (15+)

Read these files:

• next.config.*, next.config.ts
• src/app/layout.tsx (root) — scan for metadata.alternates.canonical
• src/app/sitemap.ts — check baseUrl consistency with production canonical host
• src/app/robots.ts — check sitemap: pointer matches
• src/lib/metadata.ts or similar — grep for hardcoded URLs: grep -rn "https?://" src/

Anti-patterns to flag:

• P0 — Root canonical cascade: alternates.canonical set in src/app/layout.tsx cascades to every child route that doesn't override. Result: every page claims to be the homepage. Fix: remove root canonical; let pages self-canonical or add explicit per-route.
• P0 — Host mismatch: siteUrl in src/lib/metadata.ts is apex but sitemap/robots/redirect canonicalize to www (or vice versa). Grep: grep -rn "https://" src/ --include="*.ts" --include="*.tsx".
• P1 — Missing metadataBase: root layout has no metadataBase, so relative URLs in metadata won't resolve.
• P1 — Dynamic sitemap using filesystem at runtime: readdirSync(join(process.cwd(),...)) in sitemap.ts can fail in serverless if files not bundled. Prefer compile-time aggregation.
• P2 — lastModified omitted: sitemap entries without lastModified give Google no crawl-priority signal.

Next.js Pages Router

• Check pages/sitemap.xml.ts or similar; flag if missing.
• Check ` in document.js / app.js` for canonical setup.
• Flag P1 if canonical is set in _document (applies site-wide, same cascade trap).

Astro

• Check astro.config.mjs for site (required for canonical URLs).
• Check @astrojs/sitemap integration — flag P1 if site has >20 pages and no sitemap integration.
• Check `` or layout for canonical.

Nuxt

• Check nuxt.config.ts → site or @nuxtjs/sitemap module.
• Check useHead canonical usage.

SvelteKit

• Check svelte.config.js → kit.prerender.
• Check +layout.svelte `` for canonical.

Generic / unknown framework

• Grep for `/ | grep -oE "/ | grep -c " A

dig +short TXT dig +short www. CNAME

Flag:
- P2 (info) — presence of `google-site-verification=...` TXT. If present, Domain property is set up in GSC (ideal).
- P1 — apex has no A record but www does (or vice versa) — bots that pick the "wrong" host will fail.
- P2 — multiple google-site-verification TXT (usually harmless but worth flagging).

### 9. Optional — Google Search Console live check

Only if user granted permission in preferences or this run.

Using the Claude for Chrome extension (`mcp__claude-in-chrome__*`):
1. Navigate to `https://search.google.com/search-console/sitemaps?resource_id=sc-domain%3A` (or `?resource_id=` for URL-prefix properties)
2. Use `get_page_text` to read the sitemaps table
3. Report: property type, submitted sitemaps, status, last read date, discovered pages count

**Do NOT** modify GSC state (no remove/resubmit). Read-only.

If any sitemap shows "Couldn't fetch" and production verifies healthy → flag as P1 with explicit user action: "remove + resubmit sitemap in GSC (use trailing slash trick to cache-bust if removal alone doesn't clear it)."

### 10. Build the report

Format:

╔═══════════════════════════════════════════════════════════════╗ ║ sitemap-audit — ║ ║ · · in sitemap ║ ╚═══════════════════════════════════════════════════════════════╝

SUMMARY P0 (blocks indexing): P1 (hurts rankings): P2 (nice-to-have):

P0 — Blocks indexing • Evidence: Fix:

P1 — Hurts rankings • ...

P2 — Nice-to-have • ...

CLEAN PASSES ✓ Sitemap XML valid ✓ All URLs return 200 ✓ robots.txt consistent ...

NEXT ACTIONS (prioritized)

1. [P0]
2. [P0]
3. [P1]

GSC ACTIONS (manual — skill does not modify GSC) •

### 11. Offer follow-up

After displaying the report, ask:

> **Want me to open a fix PR for P0/P1 findings?**
> This would modify code only — never GSC. You'll review the PR before merge.

If yes:
- Create branch `fix/seo-sitemap-audit-`
- Apply per-framework fixes (e.g., remove Next.js root canonical, fix host mismatch)
- Include detailed commit message citing evidence
- Open PR with before/after expected canonical count
- **Do not merge** — hand back for review.

If no: done.

If preferences.md has `saveReport: true`: write the report to the configured path.

## Memory and preferences

Save to `~/.claude/skills/sitemap-audit/preferences.md`:

```markdown
# /sitemap-audit preferences
Updated: 

## Defaults
- url: https://www.example.com
- repoPath: /Users/x/Dev/myproject
- gscMode: ask-per-run | always-skip | always-run
- saveReport: false | path
- framework: nextjs-app | nextjs-pages | astro | nuxt | sveltekit | generic

Learn silently:

• User corrects detected framework → save.
• User always skips GSC → switch to always-skip.
• User always requests PR at the end → save as default.

Content guidelines

• Every finding needs evidence (curl output, file:line, or DNS record). No vibes-based claims.
• Use three tiers: P0 / P1 / P2. Don't invent more.
• Cite the Next.js version when reporting framework-specific issues (read from package.json).
• When a finding is framework-specific, name the pattern (e.g., "Next.js App Router root layout canonical cascade").
• If a check can't run (tool unavailable, permission denied), note it in the report, don't silently skip.

Limits

• Does not fix Google Search Console state (GSC is shared; user must click).
• Does not modify production directly (only via a PR for review).
• Does not require API keys (everything is curl + read-only DOM).
• Will not auto-submit sitemaps or request indexing — GSC quotas and user intent.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mostafa-drz
• Source: mostafa-drz/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.