/seo-sitemap

name: seo-sitemap
description: >
  Analyze existing XML sitemaps or generate new ones with industry templates.
  Validates format, URLs, and structure. Use when user says "sitemap",
  "generate sitemap", "sitemap issues", or "XML sitemap".
user-invocable: true
argument-hint: "[url or generate]"
license: MIT
metadata:
  author: AgriciDaniel
  version: "2.6.0"
  category: seo

Sitemap Analysis & Generation

Mode 1: Analyze Existing Sitemap

Discover candidates before reporting a sitemap missing, and read every sitemap found in the same run:

"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run sitemap_discovery.py <url> --expand --json

The helper reads every bounded `Sitemap:` declaration in robots.txt, validates cross-host targets through the shared SSRF-safe fetch layer, and still probes common paths when a declared sitemap is stale or invalid. Use only entries in `found`; preserve declared failures as findings instead of treating a robots.txt line alone as proof that a sitemap works. Gzip sitemaps (`.xml.gz`) are inflated and classified by their content; such an entry carries `gzip: true`.

With `--expand` it also follows a sitemap index one level down to its child sitemaps and counts every entry. `expanded.files` has one object per sitemap file and `expanded.totals` sums them. Read these checks from the output; do not count or parse sitemap files by hand:

| Check | Fields in `expanded` | |-------|----------------------| | Valid XML, file reachable | `files[].valid`, `error`, `status_code`, `kind` | | Per-file limit: **≤50,000 URLs AND ≤50MB uncompressed** | `url_count`, `bytes`, `decompressed_bytes`; `findings` holds `over_50000_urls`, `over_50000_sitemaps` or `over_50mib_uncompressed` | | Index structure | `child_count`, child files carry `parent`; `nested_sitemap_index` in `findings` means an index lists another index (not allowed, not followed) | | `<lastmod>` present and valid **W3C Datetime** | `lastmod_count` against `url_count`, `lastmod_invalid_count` | | `<lastmod>` suspiciously uniform | `lastmod_identical_share` near 1.0 on a file with many URLs, with `lastmod_most_common`, `lastmod_oldest`, `lastmod_newest` | | URLs on another host than their sitemap | `cross_host_url_count`, `cross_host_url_examples`; a child file on another host has `cross_host` | | Duplicate or malformed URLs | `duplicate_count` (repeats inside one file), `totals.duplicates_across_files` (URL already listed by an earlier file; each entry is counted one way only), `invalid_loc_count`, `totals.unique_urls` against `totals.total_urls` | | Tokens or session IDs in listed URLs | `redacted_url_count`, `redacted_url_examples` (values replaced) | | Sitemap referenced in robots.txt | `source` is `robots.txt` (top-level `declared` lists every directive) | | Run cut short | `truncated`, `children.skipped`; rerun with a higher `--max-children` (default 50) |

Sitemap file URLs (`url`, `parent`) and `cross_host_url_examples` are printed without their query string (`query_redacted` refers to the file URL). Every page URL is counted, but only `--sample` distinct URLs per file (default 20) are printed in `sample_urls`. Those keep their query string and can be requested as printed. URLs in `redacted_url_examples` had a value replaced: report them, do not status-check them.

Validation Checks

The script cannot judge these; check them yourself:

• URLs return HTTP 200: spot-check `sample_urls` from each file (never

`redacted_url_examples` or `cross_host_url_examples`, which are not exact URLs)

• `<lastmod>` accuracy: it must reflect the **last significant content change**

(main content, structured data, links, not copyright/boilerplate edits). Google only honours `<lastmod>` when consistently and verifiably accurate, so warn when values are newer than the page's real content.

• No deprecated tags: `<priority>` and `<changefreq>` are ignored by Google
• Compare crawled pages vs sitemap; flag missing pages

Quality Signals

• Sitemap index file if >50k URLs (`totals.total_urls`, `kind`)
• Split by content type (pages, posts, images, videos)
• No non-canonical URLs in sitemap
• No noindexed URLs in sitemap
• No redirected URLs in sitemap
• HTTPS URLs only (no HTTP)

Common Issues

| Issue | Severity | Fix | |-------|----------|-----| | >50k URLs in single file | Critical | Split with sitemap index | | >50MB uncompressed single file | Critical | Split with sitemap index | | Non-200 URLs | High | Remove or fix broken URLs | | Noindexed URLs included | High | Remove from sitemap | | Redirected URLs included | Medium | Update to final URLs | | All identical lastmod | Low | Use actual modification dates | | Priority/changefreq used | Info | Can remove (ignored by Google) |

Extension sitemaps (image / video / news)

Google documents three subtypes with their own rules, validate per-subtype:

• **Image** (`http://www.google.com/schemas/sitemap-image/1.1`): only two valid

tags remain, `<image:image>` and `<image:loc>` (max **1,000** `<image:image>` per `<url>`). `<image:caption>`/`<image:geo_location>`/`<image:title>`/ `<image:license>` were deprecated (2022), flag as info-level removable.

• **Video**: required `<video:video>` with `<video:thumbnail_loc>`,

`<video:title>`, `<video:description>`, plus `<video:content_loc>` or `<video:player_loc>`; mRSS also supported. Flag deprecated/removed tags (`<video:category>`, `<video:gallery_loc>`, `<video:price>`, `<video:tvshow>`, player autoplay/allow_embed) as info-level removable; recheck Google docs before citing a removal date.

• **News**: max **1,000** `<news:news>` tags per file. Keep the 50,000 URL and

50 MB checks; do not replace them when the `news:` namespace is present (https://developers.google.com/search/docs/crawling-indexing/sitemaps/news-sitemap). Include `<news:news>` only on articles from the **last 2 days**; required `<news:publication>`/`<news:name>`/`<news:language>`/`<news:publication_date>`/ `<news:title