seo-analysis

seo-analysis

Audit a codebase for search visibility risks at the requested scope. Provide an implementation handoff when requested or useful, not as a prerequisite to answering a focused question.

This skill is framework- and language-agnostic. Start from the live repository and rendered output, not from assumptions about React, Next.js, Rails, Laravel, Astro, WordPress, or any other stack.

Decision Tree

What SEO problem are you solving?

• Need a full technical and on-page audit of a codebase

  • Read references/methodology.md
  • Then read references/technical-audit.md

• Need metadata, social preview, canonicals, or indexability checks

  • Read references/metadata-and-previews.md

• Need schema.org / JSON-LD / entity / rich result analysis

  • Read references/structured-data-and-entities.md

• Need content quality, information architecture, internal linking, or template-level page targeting analysis

  • Read references/content-and-information-architecture.md

• Need AI-era search guidance for crawl/render controls, preview controls, and answer-engine readiness

  • Read references/agentic-search-and-ai-surfaces.md

• Need the exact remediation handoff format for another session

  • Read references/fix-prompt-spec.md
  • Use templates/fix-prompt-template.md
  • Optionally generate a draft with python3 scripts/build_fix_prompt.py --input findings.json

• Need edge cases, policy traps, or common false positives

  • Read references/gotchas.md

Quick Reference

Task	Use	Outcome
Run a full repo audit	references/methodology.md	Ordered checklist and evidence collection flow
Check indexability and rendering	references/technical-audit.md	Crawl, render, canonical, robots, sitemap, and status-code findings
Check titles, meta descriptions, OG, X cards, favicons, site names	references/metadata-and-previews.md	SERP and social preview findings
Check structured data and entity signals	references/structured-data-and-entities.md	Rich-result and graph readiness findings
Check content and link architecture	references/content-and-information-architecture.md	Content gaps, duplication, orphan pages, weak anchors
Check AI-era search readiness	references/agentic-search-and-ai-surfaces.md	Preview controls, crawl access, citation readiness
Produce a fix session prompt	references/fix-prompt-spec.md + templates/fix-prompt-template.md	Copy-paste prompt for a second implementation session
Generate an optional prompt draft from findings JSON	python3 scripts/build_fix_prompt.py --input findings.json (put repo in the JSON)	Draft to review for evidence, constraints, and acceptance criteria

Core Workflow

1. Match the user's scope and requested output form. Inspect the relevant routing, templates, layout files, and head/metadata abstractions before drawing conclusions; broaden only to trace shared causes.
2. Inspect representative URLs or templates for the page types in scope. For a full audit, include home, category, product/service, article/docs, auth/account, paginated/filter pages, and utility pages where applicable.
3. Separate findings by severity and by layer:
   • Crawl/index controls
   • Render/discovery/canonicalization
   • Metadata/social preview
   • Structured data/entity signals
   • Content/internal linking/information architecture
   • Performance/page experience
   • AI-era search surface readiness
4. For every finding, capture evidence from code, built HTML, or runtime behavior. Do not speculate when you can verify.
5. Deduplicate root causes before prioritizing fixes. One broken metadata abstraction can explain hundreds of bad pages. If a handoff is requested or useful within scope, use references/fix-prompt-spec.md; the helper is optional and its draft is not evidence.

Audit Deliverables

Match the requested form: a scoped answer, findings table, full report, or implementation handoff. Create files only when requested. A full audit normally includes:

1. Executive summary — the observed risks to search visibility, without inventing ranking effects.
2. Findings table — severity, URL/template scope, evidence, impact, fix direction.
3. Page-type coverage map — which templates or routes were checked and which were not.
4. Remediation sequence — what to fix first, second, and later.
5. Limits and unknowns — unavailable runtime checks, evidence dates, and unresolved questions.

A focused answer can be much shorter, but retain the evidence and limitations needed to support its conclusion. Add an implementation prompt only when requested or useful; do not expand a scoped request into a full report packet.

Analysis Rules

1. Verify rendered behavior when making runtime claims. SSR, SSG, CSR, hydration, and edge rendering change what crawlers receive. When offline or limited to source, label the result source-only and list runtime checks still needed.
2. Treat crawlability, renderability, and canonicalization as prerequisites. Title tweaks do not matter if important pages are blocked, duplicated, or undiscoverable.
3. Evaluate page types, not just single pages. SEO failures usually come from shared template logic.
4. Distinguish intentional exclusions from mistakes. Login, cart, internal search, faceted combinations, and thin utility pages are often meant to be noindex.
5. Check both search-result previews and social previews. Missing or conflicting Open Graph data is a distribution problem even when classic SEO looks acceptable.
6. Prefer truthful, valid schema.org markup aligned to visible content and page purpose. Assess current search rich-result eligibility separately; ineligible does not mean invalid or misleading.
7. Treat AI-answer visibility as an extension of crawlability, metadata clarity, structured facts, and trustworthy content. Do not invent ranking or AI-visibility guarantees.

Reading Guide

If the task is...	Read
Full audit from code to implementation handoff	references/methodology.md, then references/fix-prompt-spec.md
Diagnose a rendering, canonical, robots, sitemap, hreflang, or internal-link issue	references/technical-audit.md
Diagnose bad titles, snippets, link previews, or OG/X metadata	references/metadata-and-previews.md
Diagnose missing or invalid schema and weak entity markup	references/structured-data-and-entities.md
Diagnose weak topical targeting, duplication, orphan pages, or anchor text problems	references/content-and-information-architecture.md
Discuss AI Overviews, citation surfaces, or answer-engine readiness	references/agentic-search-and-ai-surfaces.md
Avoid overreaching or false positives	references/gotchas.md

Verified External Baseline

The guidance in this skill was grounded against current primary sources in April 2026, including:

• Google Search Central on SEO basics, helpful content, JavaScript SEO, robots meta directives, canonicalization, snippets, structured data, sitemaps, site names, favicons, and preferred sources.
• The Open Graph protocol specification for required OG fields and image metadata.

Keep the stable evidence and safety principles above. Bundled references are a dated baseline, not a substitute for current official guidance. When they are inadequate, uncertain, stale, or conflicting, consult the relevant Google Search Central, schema.org, or protocol documentation and trusted target evidence. Record the source and version or retrieval date; if offline, disclose the uncertainty rather than inventing a current rule.

Propose a canonical repository update with the exact stale passage, replacement source/version, and a concrete example or regression test. Do not silently edit an installed skill while auditing a site.

Gotchas

1. Missing SEO is often a shared abstraction bug: a single layout, metadata helper, or head component can poison every route.
2. Do not treat every noindex as wrong: many utility surfaces should stay out of the index.
3. Do not recommend robots.txt for canonicalization: blocking a duplicate URL in robots.txt can prevent crawlers from seeing the canonical signal at all.
4. Do not assume OG tags equal SEO tags: search titles, social titles, canonicals, and schema each serve different consumers.
5. Do not confuse “AI SEO” with hidden hacks: the durable wins are still crawl access, strong facts, clear metadata, and useful original content.
6. Do not hand off a fix prompt without evidence: the second session should receive concrete files, page types, and acceptance criteria, not generic SEO advice.

Helper Files

• references/methodology.md — end-to-end audit workflow and evidence model.
• references/technical-audit.md — crawl, rendering, canonicals, robots, sitemaps, hreflang, pagination, internal-link discovery.
• references/metadata-and-previews.md — titles, descriptions, OG, X cards, favicons, site names, image previews.
• references/structured-data-and-entities.md — JSON-LD strategy and validation priorities.
• references/content-and-information-architecture.md — content quality, duplication, template targeting, and link architecture.
• references/agentic-search-and-ai-surfaces.md — AI-era search interpretation without hype.
• references/fix-prompt-spec.md — exact handoff prompt contract.
• references/gotchas.md — high-value traps and anti-patterns.
• templates/fix-prompt-template.md — copy-ready handoff prompt shell.
• scripts/build_fix_prompt.py — deterministic prompt builder from findings JSON.
• scripts/probe_seo_analysis.py — local regression checks for issue normalization and prompt generation.
• scripts/validate.py — structural validator for this skill.
• scripts/test_skill.py — packaging and deterministic probe test runner.