How to Run a Technical SEO Audit with Claude Code (Our Real Results)

Step 1: Build the site and inspect what Google sees

Start by asking Claude Code to build your site and read the generated HTML for every page. Frameworks add metadata in layouts and components, so the source files alone don't tell the full story.

Build the site, then for every generated page list: title and its length,
meta description and its length, canonical URL, number of h1 tags,
Open Graph url/title/image, and which JSON-LD types appear.
Show it as a table and flag anything over 60 / 155 characters.

Step 2: Check the domain is consistent

Your preferred domain (www or not) must be the same everywhere. Ask Claude Code to compare the canonical tags, sitemap URLs and robots.txt sitemap line, and to curl the live site to see which version redirects to which.

On our site, the live domain was www.claudeagents.co, but the sitemap and robots.txt listed claudeagents.co without www — every URL in the sitemap redirected. Google Search Console confirmed it: URL Inspection showed "No referring sitemaps detected" and "User-declared canonical: None" for our homepage.

Step 3: Check structured data

Ask Claude Code which JSON-LD blocks appear on which pages and whether they match visible content. A common mistake is putting page-specific schema in a shared layout.

That's exactly what we found: our FAQPage schema lived in the root layout, so all 17 pages — including the privacy policy and every tool page — claimed to be the same FAQ page. We moved it to the homepage and added BlogPosting schema to posts and Organization schema to the homepage.

Step 4: Check social sharing metadata

Next.js and similar frameworks replace, rather than merge, nested Open Graph objects. If a page sets a title but no openGraph, it inherits the homepage's. Four of our five blog posts shared the homepage's og:url and title, so a shared blog post would have linked to the homepage.

Step 5: Check titles, headings and content

• Titles over ~60 characters get cut off — three of ours were 81–92
• Descriptions over ~155 characters get cut off — two of ours were 166–170
• Outdated years in titles look stale — our best post still said "2025 Guide"
• Inconsistent facts hurt trust — our agent count said 85, 120+ and 150 in different places
• Pages that shouldn't rank, like a post-payment page, need noindex

Step 6: Check performance basics

List every file in public/ over 100 KB, where it's used, and the size
it's displayed at. Suggest a target size and format for each.

Our logo was 969 KB but shown at 36×36 pixels, and our share image was 1.6 MB. Claude Code resized them with the built-in macOS sips tool to 62 KB and 154 KB. It also flagged a 6 MB autoplaying video that needed ffmpeg to compress.

Step 7: Fix, rebuild and verify

Ask Claude Code to fix issues in priority order, then rebuild and re-run the Step 1 table to prove each fix landed. Don't trust a fix you haven't seen in the built HTML.

1. Domain consistency: one site URL constant used by metadata, sitemap and robots
2. Canonical tag on every page
3. Structured data only where it belongs
4. Per-page Open Graph and Twitter metadata
5. Titles and descriptions within limits
6. Image sizes

Make it repeatable

Once you've done this once, turn it into a technical SEO subagent or an /seo-audit skill so you can re-run it before every release. claudeagents' SEO kit includes 50 SEO agents and slash commands like /seo-audit built for exactly this.