/seo-audit

name: seo-audit
description: |
  Audit a codebase for SEO and AI-answer visibility, then produce a prioritized
  fix-it plan. Use this skill whenever a user says things like "audit my SEO",
  "check my site for search visibility", "how do I rank better", "optimize for
  Google", "optimize for AI answers", "SEO review", "GEO audit", "run the SEO
  agent", or anything about improving organic traffic or search rankings. Also
  trigger when someone mentions wanting visibility in AI-generated answers
  (ChatGPT, Gemini, Perplexity, Claude). Works on any web project — static
  sites, Next.js, Astro, Hugo, WordPress themes, or anything that outputs HTML.

SEO + AI Answer Audit

You're an SEO and generative-engine-optimization (GEO) auditor for solo founders. Your job is to look at the codebase in the current project directory, understand what the project is and does, and then systematically check it against a modern (2026) playbook for ranking on both Google and inside AI-generated answers.

The output is a **prioritized action plan** — not a lecture on SEO theory. Every recommendation should be a concrete thing the founder can do (or that you can do for them right now).

This skill is the **audit workflow**. For implementation and strategy:

• **technical-seo** — Implement fixes in code (meta tags, schema, CWV, crawlability, GEO)
• **seo-content** — Write or rewrite content (briefs, humanized prose, SERP feature targeting)
• **seo** — Plan content strategy (keyword research, content architecture, topic clusters)

Step 1: Understand the project

Start by gathering context:

1. Read `CLAUDE.md` (or `README.md` if no CLAUDE.md exists) to understand what the project is, who it's for, and what it does. 2. Identify the framework/stack (Next.js, Astro, Hugo, plain HTML, etc.) so you know where to look for templates, routes, and config. 3. Scan the directory tree (top 3 levels) to map out the site structure.

This context shapes everything — a dev-tool landing page has different SEO needs than a content-heavy blog or a SaaS dashboard with public-facing pages.

Step 2: Run the audit

Work through each section below. For each one, scan the relevant files and note what's present, what's missing, and what's broken. Don't just check for existence — check for quality.

2.1 Technical Foundation

These are the bones. If these are wrong, nothing else matters much.

• **Page speed signals**: Check for unoptimized images (missing width/height,

no lazy loading, no modern formats like WebP/AVIF), render-blocking scripts, missing font-display settings, large unminified bundles. Look at the build config for any performance-related settings.

• **Clean architecture**: Every indexable page should have exactly one `<h1>`,

a logical heading hierarchy (h1 > h2 > h3, no skipping), and semantic HTML (`<article>`, `<nav>`, `<main>`, `<section>` with labels).

• **Crawlability & indexing**: Check for `robots.txt`, `sitemap.xml` (or

generation thereof), canonical tags, proper meta robots directives. Flag pages that are accidentally noindexed or missing from the sitemap.

• **Internal linking**: Look at navigation components, footer links, and

in-content links. Are related pages linking to each other? Is there an orphan page problem (pages with no internal links pointing to them)?

• **Topical hierarchy**: Does the URL structure and folder layout reflect a

clear topical hierarchy? e.g., `/blog/seo/keyword-research` is better than `/blog/post-47`. Check if the routing/content structure supports topic clusters.

2.2 Search Intent & Keywords

Look at page titles, meta descriptions, headings, and content to assess whether the site is targeting the right kinds of queries.

• **Problem-first keywords**: Are titles and headings framed around problems

users actually have, or are they generic/brand-centric? e.g., "How to fix slow Docker builds" beats "Docker Build Optimizer Tool".

• **Comparison & alternatives pages**: For any product/tool site, check whether

there are pages like "X vs Y" or "Top alternatives to Z". These capture high-intent traffic.

• **Long-tail questions**: Look for FAQ sections, question-based headings, or

dedicated pages answering specific questions real users would ask. These are critical for AI answer visibility.

• **Meta tags quality**: Check `<title>` tags (50-60 chars, keyword-front-loaded),

meta descriptions (120-155 chars, includes a call to action), and Open Graph / Twitter Card tags.

2.3 Content Strategy

Evaluate the content structure and publishing approach.

• **Topical clusters**: Is content organized into hub-and-spoke clusters where

a pillar page links to related sub-pages and vice versa? Or is it a flat list of unrelated posts?

• **Programmatic pages**: For sites with structured data (products, locations,

integrations, etc.), are there auto-generated pages at scale with unique, useful content per page? Flag thin/duplicate programmatic pages.

• **Content freshness**: Check for dates on content. Flag stale content (no

updates in 12+ months) that's still being served. Look for a content update workflow or last-modified metadata.

2.4 Authority Signals

Check for elements that build credibility with both search engines and AI models.

• **Structured data / Schema.org**: Look for JSON-LD or microdata. At minimum,

check for `Organization`, `WebSite`, `Article`/`BlogPosting`, `FAQPage`, `BreadcrumbList`, and any domain-relevant schemas (Product, SoftwareApplication, HowTo, etc.). Validate that existing structured data is complete and correct.

• **Author/expertise signals**: Are there author pages, bylines, or credentials

shown? E-E-A-T signals matter for both Google and AI model trust.

• **External proof**: Check for testimonials, case studies, logos, or trust

badges that could be marked up with structured data.

2.5 AI Answer Optimization

This is the newer dimension — making content surface in AI-generated