Claude Code SEO: the skill that audits your whole website repo
Claude Code SEO is a free Claude Code skill that audits every HTML file in a website repository: canonicals, OG tags, schema, internal links and on-page basics. It writes findings to SEO_REPORT.md and proposes fix-forward commits for review. One curl command installs it.
Install it
One command. Then open Claude Code inside your website repo and ask for the audit.
curl -o ~/.claude/skills/claude-code-seo.md https://raw.githubusercontent.com/lhitches/claude-seo-skills/main/skills/claude-code-seo.md
Then, from your repo:
cd your-website-repo claude "run the claude code seo audit"
No Claude Code? Open the skill file, copy the contents and paste it into a Claude chat along with your built HTML. The process is the same, the file access is manual.
What it checks, and what you get
Unlike a URL checker, this skill reads your actual codebase. Every HTML file, plus git history for context.
- Structural baseline: one h1 per page, canonical tags matching your live domain, full Open Graph and Twitter Card sets, valid parseable JSON-LD, lang and viewport attributes.
- AI search readiness: Organization, Person and Breadcrumb schema coverage, heading hierarchy without skipped levels, llms.txt and entity map presence.
- Linking and structure: every internal href resolved against real files and redirect rules, redirect hops, generic anchor text, orphaned pages.
- Content basics: title and meta description lengths, duplicate titles across the repo, alt text coverage, thin pages by page type.
- The deliverable: SEO_REPORT.md in your repo root with a score, a prioritised top 10 fix table, findings by category, and an offer to stage the mechanical fixes as a commit you review.
Real sample output
This excerpt comes from a genuine run against lawrencehitches.com, my own site. Read-only, nothing staged, and the findings were real enough that fixing them became a job on my list.
SEO Audit Report
Repo: github.com/lhitches/lawrencehitches-com · Live domain: www.lawrencehitches.com
Files audited: 15 of 589 HTML files (representative sample) · Score: 90/100
- The site is in genuinely good shape. All 15 sampled pages have a correct self-referencing canonical, a full Open Graph set, Twitter Card tags, valid parseable JSON-LD and lang="en-AU". Zero duplicate titles or descriptions. Zero broken internal links.
- One real content bug: the Officeworks case study ships the wrong meta description. Line 7 reads "Why can't Google crawl my React website?" and the same wrong text repeats in og:description and twitter:description. It describes a different piece of content entirely.
- Title and description lengths are the main recurring drift: 5 of 15 titles exceed 60 characters (longest is 105) and 4 of 15 meta descriptions fall outside the 120 to 160 character window.
- The 5 category pages are indexable but appear in none of the 4 sitemap files. Either add them to sitemap-core.xml or noindex them; the current state is inconsistent.
| # | Severity | File | Issue | Proposed fix |
|---|---|---|---|---|
| 1 | High | case-study-officeworks/index.html | Meta, og and twitter descriptions all read "Why can't Google crawl my React website?", unrelated to the page | Rewrite all three to summarise the case study |
| 2 | Medium | sitemap-core.xml | 5 category pages indexable but absent from every sitemap file | Add the URLs, or noindex the pages |
| 3 | Medium | ai-seo-tools/index.html | Title is 105 characters, past the 60 character display limit | Front-loaded 55 to 60 character rewrite |
| 4 | Low | answer-engine-optimization/index.html | Internal link resolves through a 301 hop via _redirects | Point the href at the destination |
| 5 | Low | index.html | 6 client logo images carry empty alt text yet convey client names | Name the clients in the alt attributes |
Excerpt from SEO_REPORT.md, generated 2026-07-09 against static-site/output/. Category scores: A 35/40, B 18/20, C 19/20, D 14/15, E 4/5.
When to use it, and when to use a sibling skill
Use Claude Code SEO when you own the codebase and want fixes staged where they actually happen: in git, before deploy.
| You want | Use | Why |
|---|---|---|
| A repo-level audit with fixes staged as commits | Claude Code SEO (this skill) | Reads every HTML file, git-aware, writes SEO_REPORT.md in the repo |
| A quick score for any live URL, no repo access | Website Score | The opening move on every StudioHawk audit, runs from a URL alone |
| A process-level audit of a live site you do not host | Technical SEO Audit | Works from live fetches and exports instead of the codebase |
| JSON-LD written for a specific page type | Schema Markup Generator | This skill flags missing schema; that one writes it |
FAQ
Does it work on any website repo?
It audits HTML, so it works on any repo that contains or builds HTML: hand-built sites, Astro, Next.js, Jekyll, Hugo and similar static setups. For JavaScript-rendered apps, run it against the built output directory rather than the source, because that is what crawlers actually see.
Will it change my code?
Only with your explicit go-ahead. The skill writes its findings to SEO_REPORT.md, then offers to stage the highest-leverage fixes as a commit you review. It never pushes, never deploys and never runs destructive git commands. The sample run on this page was fully read-only.
How long does a run take?
Minutes, depending on repo size. On small sites it reads every page. On large repos it audits a representative sample and labels the report accordingly: the run shown on this page sampled 15 of 589 HTML files across every major page type on the site.
Do I need Claude Code, or does this run in Claude Desktop?
This one is built for Claude Code, because it needs file access, bash and git to read your repo and stage fixes. If you want a URL-based audit in Claude Desktop instead, use the Website Score or Technical SEO Audit skills from the same library.
Want the theory behind it? The Hawk Academy deep dive covers how StudioHawk uses this skill on client work.
Created by Lawrence Hitches
Chief of Staff at StudioHawk. I built this library from the processes our 120-person team runs across 500+ client campaigns. Every skill is free and MIT licensed.