seo-structural-audit

Overview

Most "SEO problems" that look like content problems are actually structural — a missing canonical, a sitemap that 404s, a hero rendered only after JS hydration that Googlebot can't see, schema that fails validation, a redirect chain that drains link equity. This skill is the diagnostic playbook for that layer: a fetch protocol that gets the evidence in parallel, a per-surface check rubric that turns the evidence into a finding, and a severity matrix that says what to fix first. Output is a prioritized list with cited evidence — never inference where evidence could have been fetched.

Mental model

Structural SEO is a chain of pass-throughs:

1. The crawler can reach the URL (robots.txt allows; no infinite redirect; status 200).
2. The renderer can see the content (raw HTML carries primary content OR pre-rendered; JS hydration doesn't hide it).
3. The indexer can understand the page (meta robots indexable; canonical self-referential or correctly assigned; schema validates).
4. The ranking system can compare it (Core Web Vitals within thresholds; internal-link topology lets PageRank flow; hreflang resolves correctly per locale).

Break any link in the chain and rankings collapse downstream regardless of how good the content is. Audit walks the chain in order; the first broken link is the highest-priority finding.

Instructions

Fetch protocol (parallel, ONE block)

Before scoring anything, get the evidence:

• Read the target URL with knowledge(command="read", source="<url>") — HTML content, headings, JSON-LD.
• shell curl -sI <url> — capture raw HTTP response and follow redirect chain (-L with -w "%{redirect_url}\n%{http_code}\n").
• shell curl -s <origin>/robots.txt — fetch robots, parse Allow / Disallow / Sitemap: directives.
• shell curl -s <origin>/sitemap.xml — fetch sitemap; check for index file vs flat sitemap; spot-validate 5–10 URLs.
• Web search site:<domain> — rough indexed-page sanity check only; the search tool is not Google, so Google index coverage needs Search Console.
• For JS-rendered sites: raw HTML from shell curl -s <url> shows what non-rendering crawlers and most AI fetchers see; true render parity needs a headless browser or Search Console URL Inspection — otherwise mark it Unverified.

Run all six in one tool block. Don't serialize. If any fetch fails, the result becomes an "Unverified" finding — never inferred.

Check rubric (per surface)

Severity matrix

• Critical — blocks indexing, blocks rendering, creates indexability conflict, or hits the "poor" CWV band. Fix before anything else.
• Moderate — degrades signal (chain too long, schema missing on eligible page, "needs improvement" CWV). Fix in current cycle.
• Minor — polish (slug aesthetics, alt-text on decorative images, sitemap last-modified timestamp accuracy). Fix when convenient.

A Critical finding stays Critical even when "it's just one tag." Severity is impact-weighted, not effort-weighted.

Unverified checks — escalation rule

If a check could not run:

• 403 on robots.txt or sitemap → "Unverified: server blocks unauthenticated fetch; ask for crawler-allowed IP or share via GSC export."
• JS-render parity untestable (no headless browser available) → "Unverified: render parity needs headless render; recommend a Lighthouse run or rendered-fetch sample."
• GSC data needed (impressions, indexed-page count, crawl errors) → "Unverified: GSC access required; share read-only access or paste a coverage report."

Never infer a finding from absence of evidence. "Could not fetch" is its own finding type — it tells the user what to unblock, and it preserves trust in the rest of the report.

Schema validation notes

• Google states AI Overviews and AI Mode need no special schema, llms.txt, or content chunking (AI optimization guide, May 2026). Score schema for rich-result eligibility and entity clarity, not as an AI-citation lever.
• Retired rich results — don't report missing markup as lost visibility: FAQ (ended May 7, 2026), HowTo (2023), Practice problem (Jan 2026), and ClaimReview, Course info, Estimated salary, Learning video, Special announcement, Vehicle listing (2025–26). Leaving the markup in place is harmless. Check Google's search gallery live before citing a type.
• Article schema → headline, author (Person with name + sameAs/url), datePublished, dateModified, image. Missing author identity on a YMYL page is Critical-tier as an E-E-A-T gap, schema or not.
• Person / Organization schema → anchors entity recognition. Missing sameAs to LinkedIn / publication / org bio is Moderate.
• Review / AggregateRating → present only when genuine reviews back it; self-serving reviews on LocalBusiness/Organization aren't eligible, and fake review markup risks a manual action (and the FTC reviews rule in the US).

Core Web Vitals — interpretation, not measurement

This skill interprets CWV; it does not measure them. Source measurements:

• Field data: Google PageSpeed Insights, Search Console Core Web Vitals report, CrUX dataset.
• Lab data: Lighthouse CLI (shell capability), WebPageTest, browser DevTools.

When only lab data is available, flag the field-vs-lab gap; lab overstates good performance in many cases. INP needs field data — lab-only INP estimates are unreliable.

Internal-link topology — what to look for

• Pillar pages should link out to every cluster article in their opening section (first 200 words).
• Cluster articles should link back to the pillar within the first 100 words.
• Cluster siblings should cross-link 2–3 times where topically relevant.
• Every indexable page should be reachable within 3 clicks from the homepage.
• Orphan pages (no internal inbound links) are a Moderate finding — they signal abandoned content or template gaps.
• The link graph should mirror the topic graph, not the navigation hierarchy.

Output

Use the canonical output structure from the agent that runs this skill. Every finding includes: severity, evidence (URL + line / header / schema field / metric), why it matters, fix direction. Save as seo-audit-[slug]-[YYYY-MM-DD].md in working directory.

Checklist

• All six fetch operations ran in parallel
• Every check in the rubric was evaluated or flagged as Unverified
• Each finding cites concrete evidence (URL, line, header, schema field, metric)
• Severity assigned by impact, not effort
• Unverified findings name the specific blocker and the unblock path
• Schema findings name the type and the missing/invalid field; retired rich-result types (FAQ, HowTo, etc.) are not reported as lost visibility
• CWV findings name the source (field / lab / PSI) and the band (good / needs improvement / poor)
• Internal-link topology checked for pillar/cluster pattern and orphan pages
• Report saved to disk with timestamped filename

Composition / References

Within-domain pairings:

• Pairs with the sibling SEO skill that audits on-page content quality (titles, meta, headings, intent match, AI-citability, E-E-A-T).
• Pairs with the sibling SEO skill that audits link profile (referring-domain quality, anchor distribution, toxic neighborhoods).

External authoritative sources:

• Google Search Central — Crawling and indexing
• Google Search Central — Structured data general guidelines
• Google Search Central — Core Web Vitals
• Google Search Central — Optimizing for generative AI features (May 2026)
• Schema.org — full type vocabulary
• web.dev — INP
• Google Search Central — hreflang