Purpose

This is a reusable guide for running a full SEO audit with Claude on a new client website. It was developed and refined across multiple B2B SaaS audits and covers the complete workflow: data collection, skill application, synthesis, and report design.

Tools and skills used: Squirrel Scan collects crawl evidence. Our five public SEO Playbook Skills supply AI-search analysis, schema validation, conversion-safe AI-copy editing, traffic trend analysis, and claim verification. The remaining analysis skills come from coreyhaines31/marketingskills. Use /skill-name in Claude Code or ask Cursor or Codex to use the installed skill by name.

If a skill is missing: run its installation command for the agent and project you are using. A project installation is available in that project; use --global to make it available across projects. Restart the agent session if needed.

Install the playbook skills

These five skills are public on GitHub and install through the skills CLI:

npx skills add BigChrisCooke/seo-playbook-skills --skill remove-ai-slop-without-removing-ctas-and-good-marketing-copy trend-scan claim-check ai-seo-better-than-corey-haines schema-markup-better-than-corey-haines

Select your agent in the installer (Claude Code, Cursor, or Codex). Installation is project-local by default; add --global for all projects. Requires Node.js/npm for installation and Python 3.10+ for the helpers; no pip packages or API keys are needed for these three scripts. Restart the agent session if the skills are not yet visible.

This collection supplies two core analysis skills and three helpers. Install the remaining upstream analysis skills separately. It does not include the optional /seo-audit orchestrator; their setup is explained on the skill-pack page.

Skill names and existing audit files

Use the published skills below. Older audits keep their existing evidence filenames; these filenames are storage locations, not skill commands.

Corey’s comparison-page skill is now named competitors. Install it and the other two upstream dependencies separately:

npx skills add coreyhaines31/marketingskills --skill programmatic-seo site-architecture competitors

If using the standalone runbook without our optional orchestrator, also install seo-audit from that upstream repository. If using our orchestrator, it supplies that checklist itself; do not replace it with the upstream skill of the same name.

Before analysis, resolve each required skill by its published name. If one is missing, link its source above and provide the install command; mark it blocked until installed. Do not silently use an older local ai-seo or schema-markup copy. If an upstream skill cross-references those older names, route AI visibility and structured-data work through the published variants above. Use the runbook’s audit-only scope and verification rules throughout.

Verify this release and the complete installation

Playbook release: 2026-11-06.1. The current release manifest lists SHA-256 hashes and byte counts for the clean downloads. At session start, read this file from disk and report its absolute path and release. Compare with the live manifest; do not infer freshness from a download timestamp or file size. A working copy’s hash will change when its Ledger is edited. Preserve that Ledger when upgrading instructions, and record the new release only after applying them.

For Claude Code, run these commands from the audit project folder. They install complete packages into that project. For Codex or Cursor, replace claude-code with codex or cursor.

npx --yes skills add BigChrisCooke/seo-playbook-skills --skill claim-check trend-scan remove-ai-slop-without-removing-ctas-and-good-marketing-copy ai-seo-better-than-corey-haines schema-markup-better-than-corey-haines --agent claude-code --copy --yes
npx --yes skills add coreyhaines31/marketingskills --skill programmatic-seo site-architecture competitors --agent claude-code --copy --yes

For the standalone runbook, also run npx --yes skills add coreyhaines31/marketingskills --skill seo-audit --agent claude-code --copy --yes. Skip that command if using our optional orchestrator, which supplies the checklist under the same name.

Download check-skills.py into the audit project, then run:

python check-skills.py --project . --standalone

Omit --standalone when using our optional orchestrator. The checker performs no installs or network requests. It checks all five public packages against the published file hashes, verifies the three upstream entrypoints and their referenced resources, and runs the bundled Python helpers with --help. Missing scripts, changed package contents, or conflicting installed copies are reported with paths. --skills-dir PATH restricts checking to an explicitly selected skills directory; only use it after confirming that the agent will load that directory.

Save its JSON output as audit-data/<client>/skill-preflight.json. Record the release, selected skill paths, hashes, results, and fresh-session confirmation in the Ledger. A successful disk check does not prove that a running agent has refreshed its registered skill instructions. After installing or changing skills, checkpoint and start a fresh agent session, then confirm the selected paths before invoking them. Do not report an update as applied merely because a command ran.

The old editor name edit-conversion-safe-blogs maps to remove-ai-slop-without-removing-ctas-and-good-marketing-copy; use the published name. Use the two published analysis variants instead of old local schema, schema-markup, or ai-seo copies. schema-detector is not required: the published schema variant plus the two validators cover that step.

Check delivery dependencies at the start: a missing claim-check package or script blocks the delivery QA gate. Record it immediately, install the complete package, and verify it before marking delivery ready. Independent data collection may continue while it is blocked. Manual trend analysis must be labelled manual; it does not establish that trend-scan is installed. The conditional editor still requires its complete package when AI-written pages are in scope.

SXO and drift setup: a skill entrypoint alone is insufficient. If using seo-sxo, add --with-sxo to the checker; if capturing or comparing with seo-drift, add --with-drift. Use both flags when running both, and pass --seo-bundle "<bundle>" with the complete upstream repository root. The checker verifies the selected skill, the shared fetch_page.py, parse_html.py, and render_page.py files, and (for drift) drift_baseline.py and drift_compare.py. It checks managed runtime and Chromium readiness, then starts the scripts with --help in that runtime. It does not fetch pages or prove that a baseline was saved.

Obtain the complete shared script bundle from the upstream repository, following its current installation instructions, and record the source revision. Do not assume a skill-only CLI install includes repository-level scripts. Keep requirements.txt at the repository root, alongside scripts/; copying only scripts/ breaks managed setup. Install the selected skill’s complete folder (including references) for your agent and resolve its commands to this same bundle.

Replace <bundle> below with the real repository path. These Python entrypoint commands work in PowerShell and POSIX shells; the upstream Bash launcher <bundle>/scripts/claude-seo setup and doctor --json are alternatives when Bash is available:

python "<bundle>/scripts/runtime.py" setup
python "<bundle>/scripts/runtime.py" doctor --json
python check-skills.py --project . --standalone --with-sxo --with-drift --seo-bundle "<bundle>"

Omit --standalone when using our orchestrator, and omit the optional flag for any step not being run. Require both ready: true and browser_ready: true; a zero doctor exit code alone can still mean Chromium is missing. Use python "<bundle>/scripts/runtime.py" run <script.py> ... for subsequent commands so they use the managed environment, rather than the system Python. Then verify an actual rendered fetch on a target page (run render_page.py <url> --mode always --json): check its status, error, mode_used, and content. Preflight success does not substitute for this evidence.

If setup is incomplete, record the affected step as unavailable and continue independent audit work. A manual SERP/page-type review is a separately labelled fallback; for CSR/hybrid/unknown pages it needs rendered evidence, not just response HTML. Even a static page requires an explicit response-versus-rendered comparison before treating response HTML as sufficient. A hand-built JSON snapshot is manual evidence, not a completed /seo-drift baseline; retain the setup action for the next cycle.

For a manual install, copy each whole skill directory, including its scripts and reference files. These skills do not depend on a particular user’s home folder. Browse the skills.sh collection or installation guide.

Missing browser or PageSpeed quota: continue with explicit limits

Playwright is one browser option, not a global audit gate. Test whichever browser capability the agent actually has; if none can access authenticated tools, request GSC/GA4 CSV exports through F-FILE and continue public crawl, source, sitemap, and supplied-file analysis. Record browser-only/rendered checks as unavailable until evidence arrives. Do not infer a rendering pass from raw HTML. Tool unavailability is a limitation of this audit environment, not evidence that the client’s website is broken.

For PageSpeed HTTP 429, record the response and URL/strategy, check for an already configured PAGESPEED_API_KEY or GOOGLE_API_KEY without displaying either value. Prefer the dedicated PageSpeed key; if absent or unusable, try the existing Google key once. Pass the selected value as the API key and verify the response: its environment-variable name does not guarantee that PageSpeed is enabled, permitted by key restrictions, or within quota. Redact keys from commands, URLs, logs, and saved evidence. Do not repeatedly call the same anonymous endpoint. A new key is optional and does not guarantee quota. Try a human-supplied PageSpeed report or local Lighthouse when Chrome and the runtime are available; neither requires Playwright. Keep Lighthouse lab measurements separate from field Core Web Vitals. If no route is available, record Performance as not measured and continue the audit. Ask once for the missing evidence; do not wait indefinitely or create cloud accounts during the audit.

A report may be delivered with these explicitly documented evidence gaps once the applicable analysis and claim-check QA are complete. Mark affected collection rows unavailable with their reason and collection action; do not mark them passed. With missing performance or other category evidence, show measured categories but withhold the overall 0–100 Health Score until its inputs exist. Do not substitute zero, invent a score, or silently redistribute weights. This evidence-gap rule takes precedence over instructions elsewhere to display a total score or wait for every collection row.

Sources: PageSpeed API setup and Lighthouse execution options.

Overview

The audit runs in three phases:

1. Data collection — gather raw exports before running any skills
2. Skill application — run each skill against the collected data, one at a time
3. Synthesis — combine outputs, deduplicate, prioritize, structure — then close the report by answering the standing Acquisition Channel Questions (what content attracts buyers vs. traffic, how blog → lead magnet → demo/trial connects) from all sources combined

The key insight: skills don’t replace data collection, they interpret it. Start with a Site Profile, route only the modules that apply, then collect the evidence. Running a skill against thin or irrelevant data produces generic recommendations.

Two ways to run it

Audit runbook (default): Download the executable audit runbook, open it in Cursor, Claude Code, or Codex, and tell the AI to follow it. It collects evidence, writes a dated, client-specific SEO audit report, then generates a dated action runbook beside the report after QA. Download

The generated action runbook is the recurring operating document: it explains what the AI can do, researches current best practice, manages approved batches, verifies them, measures outcomes, and preserves history across future audit cycles. It also carries forward content lifecycle decisions, the fixed SERP panel, backlink baselines, and conditional crawl evidence. It is generated locally because its contents depend on that client’s report, URLs, priorities, tools, and existing action history.

Skill pack (optional, Claude Code only): Install the /seo-audit orchestrator for tab-complete, tool verification, and structured phase execution. Invokes the same analysis skills against the same methodology. Install