seo-analysis
Audit a codebase for search visibility risks, then produce a fix-ready prompt another session can execute.
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
- Run python3 scripts/build_fix_prompt.py --help - 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 a prompt draft from findings JSON | python3 scripts/build_fix_prompt.py --input findings.json --repo /abs/path | Structured prompt with priorities, constraints, and acceptance criteria |
Core Workflow
- Inspect the repository structure, routing model, page templates, layout files, and any head/metadata abstractions before drawing conclusions.
- Inspect representative URLs or templates for each page type: home, category, product/service, article/docs, auth/account, paginated/filter pages, and utility pages.
- 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
- For every finding, capture evidence from code, built HTML, or runtime behavior. Do not speculate when you can verify.
- Turn the findings into an implementation prompt for another session only after deduplicating root causes. One broken metadata abstraction can explain hundreds of bad pages.
Audit Deliverables
Produce these artifacts in the response:
- Executive summary — what is blocking or suppressing search visibility right now.
- Findings table — severity, URL/template scope, evidence, impact, fix direction.
- Page-type coverage map — which templates or routes were checked and which were not.
- Remediation sequence — what to fix first, second, and later.
- Implementation prompt — a clean handoff for another session to make code changes safely.
Analysis Rules
- Work from the rendered reality of the site, not only source files. SSR, SSG, CSR, hydration, and edge rendering change what crawlers actually receive.
- Treat crawlability, renderability, and canonicalization as prerequisites. Title tweaks do not matter if important pages are blocked, duplicated, or undiscoverable.
- Evaluate page types, not just single pages. SEO failures usually come from shared template logic.
- Distinguish intentional exclusions from mistakes. Login, cart, internal search, faceted combinations, and thin utility pages are often meant to be
noindex. - Check both search-result previews and social previews. Missing or conflicting Open Graph data is a distribution problem even when classic SEO looks acceptable.
- Prefer supported structured data aligned to page purpose. Do not recommend schema spam or irrelevant types.
- Treat AI-answer visibility as an extension of crawlability, metadata clarity, structured facts, and trustworthy content. Do not invent a separate magical “AI SEO” system.
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.
Use the references as the first source of truth, then verify live details when the target stack or search surface has materially changed.
Gotchas
- Missing SEO is often a shared abstraction bug: a single layout, metadata helper, or head component can poison every route.
- Do not treat every
noindexas wrong: many utility surfaces should stay out of the index. - Do not recommend
robots.txtfor canonicalization: blocking a duplicate URL inrobots.txtcan prevent crawlers from seeing the canonical signal at all. - Do not assume OG tags equal SEO tags: search titles, social titles, canonicals, and schema each serve different consumers.
- Do not confuse “AI SEO” with hidden hacks: the durable wins are still crawl access, strong facts, clear metadata, and useful original content.
- 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.