# SEO Audit Skill Pack

Adds `/seo-audit` to Claude Code — an orchestrator that drives the full audit from the runbook: it
reads the Ledger, asks the kickoff questions, runs data collection, invokes the analysis skills,
scores the site 0–100, synthesises, and delivers a client-ready `<client-slug>-seo-audit-YYYY-MM-DD.md`. It enforces the
report-only Prime Directive — it never edits your site, it writes recommendations.

## Install the playbook skills

These five skills are public on [GitHub](https://github.com/BigChrisCooke/seo-playbook-skills) and install through the [skills CLI](https://skills.sh/docs):

```bash
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.

- `remove-ai-slop-without-removing-ctas-and-good-marketing-copy`: the conditional AI-written-page review, with its conversion guard and fallback prose rubric included.
- `trend-scan`: traffic direction and anomaly checks from exported CSVs before synthesis.
- `claim-check`: flag stale or undated claims before report delivery; the agent then verifies the primary sources.

### 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.

| Invoke | Source | Save audit evidence as |
| --- | --- | --- |
| `/ai-seo-better-than-corey-haines` | [GitHub](https://github.com/BigChrisCooke/seo-playbook-skills/tree/main/skills/ai-seo-better-than-corey-haines) · [skills.sh](https://skills.sh/BigChrisCooke/seo-playbook-skills/ai-seo-better-than-corey-haines) | `skills/ai-seo.md` |
| `/schema-markup-better-than-corey-haines` | [GitHub](https://github.com/BigChrisCooke/seo-playbook-skills/tree/main/skills/schema-markup-better-than-corey-haines) · [skills.sh](https://skills.sh/BigChrisCooke/seo-playbook-skills/schema-markup-better-than-corey-haines) | `skills/schema-markup.md` |
| `/competitors` | [GitHub](https://github.com/coreyhaines31/marketingskills/tree/main/skills/competitors) | `skills/competitor-alternatives.md` |

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

```bash
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](https://seo-audit-site.vercel.app/handover/release.json) 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`.

```bash
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](https://seo-audit-site.vercel.app/skill-pack/check-skills.py) into the audit project, then run:

```bash
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](https://github.com/AgriciDaniel/claude-seo), 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:

```bash
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](https://skills.sh/BigChrisCooke/seo-playbook-skills) or [installation guide](https://github.com/BigChrisCooke/seo-playbook-skills#install).

## Install the optional orchestrator

**Windows (PowerShell):**
```powershell
cd .\skill-pack\
powershell -ExecutionPolicy Bypass -File install.ps1
```

**macOS / Linux:**
```bash
cd skill-pack
bash install.sh
```

**Manual:** copy `skills/seo-audit/SKILL.md` to `~/.claude/skills/seo-audit/SKILL.md`.

> The orchestrator is named `seo-audit` and **supersedes the standalone `seo-audit` _analysis_ skill** —
> it invokes the other five analysis skills, conditionally runs the conversion-safe AI-writing
> review when kickoff confirms AI-written pages, and folds the SaaS-gap checklist in itself, so you don't
> need a separate `seo-audit` analysis skill. The installer backs up any existing one to `SKILL.md.bak`.

## What it invokes

During Phase 2 the orchestrator invokes these **five** analysis skills. The two published variants come from `BigChrisCooke/seo-playbook-skills`; the other three come from `coreyhaines31/marketingskills` (install commands above):

| Skill | |
|---|---|
| `/programmatic-seo` | scalable page types (integrations, comparisons, personas, glossary, templates) |
| `/ai-seo-better-than-corey-haines` | AI/GEO/AEO analysis with dated sources and a reproducible visibility sample |
| `/site-architecture` | IA + internal linking (spoke-to-hub, pillar/cluster) |
| `/schema-markup-better-than-corey-haines` | schema validation + per-page mapping |
| `/competitors` | comparison-page framework (never guesses competitors) |

The sixth piece — the **SaaS-specific gap checklist** — is built into the orchestrator.

Also keep these in your working folder (download from https://seo-audit-site.vercel.app):
- `seo-audit-runbook.md` — the executable workflow (HOW)
- `seo-audit-methodology.md` — the reference manual (WHY)

## Commands

| Command | What it does |
|---|---|
| `/seo-audit` | Reads the Ledger, picks up where you left off |
| `/seo-audit begin` | Preflight + kickoff questions + Squirrel Scan |
| `/seo-audit collect` | Phase 1 — all 9 data-collection items |
| `/seo-audit skills` | Phase 2 — the 5 analysis skills + conditional `/remove-ai-slop-without-removing-ctas-and-good-marketing-copy` review + SaaS-gap checklist |
| `/seo-audit score` | 0–100 SEO Health Score (methodology §5.6) |
| `/seo-audit synthesize` | Phase 3 — deduplicate, tier, build the 90-day plan |
| `/seo-audit report` | Assembles the dated SEO audit report, runs the QA gate |
| `/seo-audit drift` | Phase 4 — drift monitoring (retainer only) |
| `/seo-audit status` | Ledger readout — done / next / blocked |

## Uninstall

Delete `~/.claude/skills/seo-audit/` (restore `SKILL.md.bak` if you want a previous skill back).
The runbook and your audit data are unaffected.