SEO Ops skill

seo-ops · SEO foundation engineering

Review a site's templates and output against the C set (30 structural checks), or run the checker to produce an acceptance report.

How to work

When this skill triggers, introduce it in one sentence — "30 structural checks (the C set): can crawlers fetch, read, index, and cite this site" — then immediately ask one question (as selectable options if your environment has an option/question UI):

What should I check?

1. A URL — live domain or local deployment (http://localhost:<port>), both fine; produces a report
2. The code — review templates/pages in this repo against the checklist, no script

That one answer decides the path; don't ask anything else before starting — no config is needed, the checker runs with defaults on a bare --target. Never bring configuration up on your own; it only becomes relevant if the user asks for the extras (CrUX field data, IndexNow, multi-site roster — see "Configuration").

The user gave	Path	Section to follow
a domain / URL (live or localhost)	run the checker, produce a report	"Run the checker" → then "Read the report"
code, templates, a PR, page files	no script; review the machine-readable output surface against the C set item by item	"Scope" sets the boundary; references/checklist/checklist.md lists the items — but judge each one by its canonical doc references/checklist/references/C<N>.md, not by the index row alone

Once intent is confirmed, do not keep asking for permission. Everything else: the user asks why a check exists / how to fix it → "After the report"; dependencies won't install → "Environment".

Both paths treat references/checklist/checklist.md as authoritative — never judge from memory; if unsure about an item, read references/checklist/references/C<N>.md. Cite items by ID (C12); IDs are permanent — never renumber or reorder.

After the report

The report itself is the conclusion — don't walk through it item by item unprompted. Each row carries a Docs column: the GitHub link to that check's canonical doc — that link is for the person reading the report (it opens wherever the report is sent). What you yourself read is the local copy: references/checklist/references/C<N>.md.

When the user asks about a check, read references/checklist/references/C<N>.md before answering (for C12, read references/checklist/references/C12.md): "why it's a problem" comes from ## Introduction, "how to fix it" from ## Implementation guidance. Never answer by inferring from the evidence — evidence only says which pages failed; it can't tell you why the check exists, what the correct fix is, or where the authoritative reference lives.

Environment

python3 -c "import requests, yaml" || pip install -r scripts/requirements.txt

On externally-managed-environment (PEP 668, common on Debian/Ubuntu), use the system packages apt install python3-requests python3-yaml or create a venv — do not add --break-system-packages; that gambles the system Python for a two-line dependency.

Scope

SEO foundation engineering = the machine-readable structure a site must have so that search engines and AI retrieval can fetch, read, index, and cite it.

What it checks: the machine-readable surface of the final HTTP/HTML output — regardless of who produced it (backend templates, frontend code, third-party scripts); if a crawler can see it, it's covered. The boundary is "machine-readable surface / human-perceivable surface", not frontend/backend.

What it doesn't check: styling, interaction, UX, code quality; content truthfulness and quality; ranking and traffic; process. All green ≠ fully compliant.

The human gate is a separate set: the R1-R8 prohibitions (buying links, cloaking, fake structured data, PII in prompts, etc.) live in redlines.md; the machine doesn't check them. Read them before touching content strategy, links, or structured data.

What's here

Path	What it is
references/checklist/checklist.md	The C set index: 30 checks, split into site-level / per indexed page / conditional
references/checklist/references/C<N>.md	Each C check's canonical doc: ## Introduction (why) + ## Implementation guidance (how to fix) + authoritative references
references/content/	The T set: for tracing a red C back to "who owes the input"; outside this skill's duties
scripts/run.py · scripts/config.py	Check logic / check parameters
references/ai-crawlers.yaml	The AI crawler UA roster for C1, read at runtime
references/{sites,config}.example.yaml · references/.env.example	Three config templates, see "Configuration"

<N> maps one-to-one to the IDs in the checklist; C12's canonical doc is references/checklist/references/C12.md. Gaps in the numbering are normal (retired IDs are never recycled).

The skill directory is read-only — zero writes. Updates overwrite the whole package; anything written inside will be lost.

Run the checker

Confirm the target is an origin → run. No config file is required and none should be asked about — defaults cover everything; the optional files exist for users who come asking for more (see "Configuration").

One "site" = one origin (scheme + host[:port], no path/query). Subdomains count as separate sites (blog. / docs. are each one); the apex domain and www don't count as two — they should 301 to a single canonical host, which is exactly what C3 checks, so only the one you pick counts.

Single site: no config file needed

python3 scripts/run.py --target https://example.com      # live site
python3 scripts/run.py --target http://localhost:3000    # local deployment, auto-detected as local mode

--target must be an origin; a URL with path/query exits with an error immediately — no guessing.

Public staging domains are not supported — they'd be tested as production domains, and the canonicalization check (C3) would false-red for sure. To test before launch, pick one: run a local deployment at http://localhost:<port>, or wait and run against the production domain after launch.

Multi-site: run a batch in one go

"Multi-site" = you have several domains to accept at once (e.g. example.com + example.org + blog.example.com), don't want to retype --target every time, and want each site to carry its own rendering strategy and must-test pages. After creating sites.yaml (see "Configuration"):

python3 scripts/run.py               # run every site in the roster
python3 scripts/run.py --site <id>   # run just one

Each entry takes: id (used for the report filename and the checks table's site column), production (origin, required), rendering (ssr/ssg/isr; C15 branches on it), sitemap (defaults to <production>/sitemap.xml), samples (must-test pages fetched in addition to the sitemap; mark ymyl: true to trigger the C21 human review). If the roster can't be found, the script exits and prints where to create it — it never silently runs empty.

Common flags

One-off overrides: --page-sample N --sitemap-sample N --max-pages N --sleep S --workers N. Output overrides: --state-dir <path> / --out <path>. --verify-only: run only the two drift guards, no network; exits 1 on drift (for CI).

Runtime: at the default single worker with a 1s interval, roughly 2 × sitemap entries requests. A 271-page site takes about 7 minutes (tell the user roughly how long the wait is before running); for speed, sample with --page-sample 100 — structural problems are template-level, so a sample and a full run see the same set.

Read the report

Each run writes two outputs to ~/Documents/seo-ops/out/ (--state-dir / --out / $SEO_OPS_DIR to change):

Output	For	What it is
report-<site>-<date>.md	humans	mirrors the checklist one-to-one; the same 30 rows every run
checks.db	machines	SQLite, checks(site, url, rule_id, status, evidence, checked_at), primary key (site,url,rule_id); accumulates across runs for diffing

Result	Meaning
✅ pass	tested, passed
🔴 fail	tested, failed — the Evidence column shows the violating pages and why
⚪ N.A.	not tested; the reason code is in parentheses. "Not tested" is not "fine"
👤 human review	the script doesn't judge; listed to remind a human to go through it

Common N.A. reason codes: need-domain (local mode), need-crux-key / need-crux-data (C4), need-key-declaration (C5), need-declaration (no rendering strategy declared), no-pages, crawl-capped (crawl hit the cap), throttled (throttled by the target; rerun slower).

Check the warning lines at the top of the report first — if any are present, this run's verdict is incomplete:

• 🚦 throttled by the target (429/503) — we hit it too fast; the site is not at fault. Affected verdicts are recorded as N.A., not fail (a false red is more dangerous than a slow run). For a complete verdict: halve --workers or raise --sleep and rerun.
• ⚠️ sample fetches failed (not throttling) — genuinely unreachable; these pages are excluded from the denominator.

Priorities: P0 = existence/incident layer (can't be fetched or indexed); P1 = performance layer (ranking and citation are discounted); P2 = optimizations.

Configuration

None of the three files is required. They live in ~/.config/seo-ops/ ($SEO_OPS_CONFIG_DIR to change); just copy from the templates — do not edit scripts/config.py; it's the skill body and gets overwritten wholesale on update.

mkdir -p ~/.config/seo-ops

File	When you need it	Cost of not creating it	How to create
sites.yaml	multi-site, or to declare a rendering strategy / mark YMYL pages	single-site runs fine with --target; C15 records need-declaration, C21 has no human-review list	cp references/sites.example.yaml ~/.config/seo-ops/sites.yaml
.env	only when the user wants a "complete verdict" (CrUX / IndexNow key)	not required; C4 records need-crux-key, C5 records need-key-declaration, everything else runs	cp references/.env.example ~/.config/seo-ops/.env
config.yaml	only to change thresholds	none; all defaults apply	cp references/config.example.yaml ~/.config/seo-ops/config.yaml

.env is a hidden file; ls without -a makes the directory look empty. Exported environment variables always beat .env — a key injected by CI can't be overridden by someone's local file. Legacy locations (<state-dir>/sites.yaml, <state-dir>/.env, scripts/.env) are still read, but whenever a value is actually taken from one, a warning prompts you to move it — a silently misplaced config makes the same command give different verdicts.

What config.yaml can tune

Every line in the template is the current default; keeping it as-is equals not configuring it. Change only the lines you need. Commonly tuned:

Parameter	Effect
FETCH_SLEEP / FETCH_CONCURRENCY	fetch throttling; overall QPS ≈ workers / interval. Defaults 1 / 1
PAGE_SAMPLE_SIZE	page-level check coverage: 0 = full, >0 = sample cap
CRAWL_MAX_PAGES	internal crawl cap (C6)
TITLE_MAX_CHARS / DESC_MAX_CHARS	C11 length limits
THROTTLE_*	throttle backoff and recovery
DOC_BASE_URL	base URL for the report's Docs column links; switch it to a commit SHA to pin a version

Unregistered keys and type mismatches exit with an error, never silently ignored — a typo'd key producing a report on defaults is more dangerous than an error.

Three categories can't be tuned here: secrets (live in .env); constants (the three CWV thresholds are Google's official "good" lines, the sitemap 50k cap is a protocol hard limit, the viewport token is the spec value — change them and it's no longer the same check); structural judgments (TYPE_REQUIRED, LD_REJECTED_TYPES, BODY_HIDE_PATTERNS — changing them changes the check logic; that belongs in a human-reviewed PR, not hidden in someone's local yaml).