SEO Audit

SEO Audit

Audit a website's search-engine readiness and produce a prioritized, actionable report. There are two modes — pick based on what the user gives you:

• URL mode — the user gives a live URL (or just a domain). Run the bundled Python script; it fetches the page, crawls a few internal pages, scores everything, and writes the report.
• Code mode — you have the project's source code (running inside Claude Code / Cursor / an agent with repo access). Audit the source against the same checklist, citing real files, because many issues (sitemap generation, head/meta management, structured data, image alt) are best fixed at the source.

When both are available (e.g. a repo with a running dev server), do both: run the script against the live/dev URL for ground truth, then map findings back to the source to recommend fixes.

Golden rules

1. Measure, don't guess. In URL mode, run the script and report what it actually found. In code mode, read the real files — never invent meta tags, schema, or config that isn't there.
2. Prioritize ruthlessly. Lead with the few changes that move the needle (indexability, titles, mobile, structured data), not an undifferentiated wall of nitpicks.
3. Explain the why and the fix. Every finding should tell the user what's wrong, why it matters for search, and the concrete change to make.
4. Know the tool's limits. The script does static analysis of server-rendered HTML. For JS-heavy SPAs it may under-count content/links — say so. It does not measure real Core Web Vitals; recommend PageSpeed Insights / Lighthouse for field data.

URL mode — how to run

Locate the script (important)

Run the script by its real path, not relative to the user's current directory — when this skill triggers, the working directory is the user's project, not the skill folder. The script self-locates its own helpers, so it works from any directory once you give it the right path.

• Installed as a Claude Code plugin: use the plugin root variable: "${CLAUDE_PLUGIN_ROOT}/skills/seo-audit/scripts/seo_audit.py".
• Installed as a personal/project skill or on Claude Desktop: the scripts/ folder sits next to this SKILL.md. Use that directory's absolute path (the one this file was loaded from), e.g. <skill-dir>/scripts/seo_audit.py.

In the commands below, SEO=<that absolute path>/seo_audit.py.

Dependencies (optional, best-effort)

The engine has no required dependencies — it falls back to the Python standard library. But requests + BeautifulSoup make parsing more robust, so before the first URL audit, try to install them (ignore failure and proceed regardless):

pip install -r "<skill-dir>/requirements.txt" || true
python "$SEO" --self-check        # shows Python version + which backend is active

Run the audit

python "$SEO" <url> [--crawl N] [--out DIR] [--json-only] [--md-only]

• <url> — homepage URL (scheme optional; https:// is assumed).
• --crawl N — max pages to crawl, homepage included. Default 8. Use 1 for homepage-only.
• --out DIR — output directory. Default ./seo-report. Writes report.md and report.json.
• --self-check — print the runtime environment / active backend and exit (no URL needed).

Example:

python "$SEO" https://example.com --crawl 8 --out ./seo-report

After it runs: read seo-report/report.md, then present to the user:

1. Check confidence first. If the report shows a ⚠️ Low confidence banner (also in report.json under confidence), lead with that — the site likely blocked the bot or served a stripped/JS-rendered shell, so the score reflects what a bot saw, not real users. Recommend verifying in a browser / headless renderer before trusting the findings.
2. The overall score + grade and the per-category scores.
3. The top priority fixes (critical → warning → notice), each with the why and the fix.
4. Offer to go deeper on any category or, if you have the source, to apply the fixes.

The script prints which backend it used and a one-line summary to stderr; the full detail is in the report files.

What gets checked

Seven categories, scored 0–100 each and rolled into an overall weighted score. Full detail, including exact thresholds and rationale, is in references/checklist.md and references/thresholds.md — read those when the user wants depth or asks "why".

Code mode — auditing source

When you have the repository, audit the source against the same seven categories. The framework-specific guidance — where titles/meta live, how sitemaps and robots are generated, how to add JSON-LD, common pitfalls in Next.js / React (Vite/CRA) / Astro / Nuxt / plain HTML / WordPress — is in references/code-audit.md. Read it, detect the stack, then walk the source and produce findings that cite real files (e.g. app/layout.tsx:14).

If there's a runnable dev server, also run URL mode against it (http://localhost:PORT) and reconcile the two: the live run shows symptoms, the source shows where to fix them.

Reporting

In URL mode the script writes the report for you. In code mode (or when summarizing), follow the structure in assets/report-template.md: overall grade → executive summary → top fixes → per-category findings with severity, the problem, why it matters, and the fix.

Keep severities consistent with the engine: 🔴 critical (blocks indexing/ranking), 🟠 warning (real problem), 🟡 notice (minor/improvement), 🟢 pass, ℹ️ info (context).

Keyword & topic suggestions

The Keywords & Topics category measures what the page already signals; turn that into forward-looking suggestions. After the audit, read the Detected keyword profile finding (keyword-profile in report.json, under findings[].evidence) — it lists the apparent focus term, the top terms, and the top phrases. From that profile plus the page's content:

1. Confirm the target. State the page's apparent primary keyword and search intent (informational / commercial / navigational). If it doesn't match what the page should rank for, that mismatch is the headline recommendation.
2. Suggest keywords to implement. Propose a short list (≈5–10) of related terms the page is not yet targeting — semantic variants, long-tail and question forms, and adjacent subtopics the copy implies but doesn't cover.
3. Say where each goes. For every suggestion, name the slot: title, H1, a new H2 section, body copy, image alt, or internal anchor text.

Be explicit that these are content-derived suggestions, not validated against real search volume or difficulty — see Limits for how to confirm demand.

Limits & optional extensions

• Bot-blocking / cloaking: some sites (e.g. Amazon, sites behind aggressive WAFs) serve a stripped page or a challenge to non-browser clients. The engine detects this and marks the audit low confidence with reasons — honor that signal and don't over-trust the score.
• JS-rendered sites: static HTML may miss client-rendered content/links (also surfaced via low confidence). Note it, and verify in a browser or with a headless renderer if accuracy matters.
• Core Web Vitals: not measured here. Recommend PageSpeed Insights or Lighthouse; the PageSpeed Insights API (free key) can be wired in as an optional extension.
• Keyword suggestions are content-derived. The Keywords & Topics category and any suggested keywords come from the page's own text — there is no search-volume or difficulty data. Validate demand and competition with Google Search Console (your own queries/impressions) or a keyword tool (Keyword Planner, Ahrefs, Semrush) before committing to new targets. Wiring one of those in is an optional, key-requiring extension, deliberately outside the self-contained core.
• Large sites: the crawler is intentionally small and polite. For full-site crawls, raise --crawl deliberately and mind the target's load.

Reference files

• references/checklist.md — the complete basic→advanced SEO checklist.
• references/thresholds.md — exact thresholds (lengths, counts) and the reasoning.
• references/code-audit.md — per-framework source-auditing guide.
• assets/report-template.md — report skeleton for code-mode / manual reports.