Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.
#!/usr/bin/env python3
"""
Primary-source Google updates query tool.
Reads ``data/google-updates.json`` and surfaces filtered views of the
confirmed Google ranking / spam / QRG / product / schema updates
since March 2024. Every entry cites a Google-owned URL.
The companion file lists *unverified* third-party claims separately. Those
entries are explicitly NOT used to drive recommendations until they are
confirmed against ``status.search.google.com``.
Usage::
python scripts/seo_updates.py # latest 10
python scripts/seo_updates.py --since 2025-06 # ISO yyyy or yyyy-mm filter
python scripts/seo_updates.py --kind core
python scripts/seo_updates.py --json
python scripts/seo_updates.py --unverified # show 3rd-party claims awaiting check
JSON output carries ``freshness`` (age in days, ``stale`` after 30 days). Text
output prints a warning to stderr when the ledger is stale.
"""
from __future__ import annotations
import argparse
import json
import sys
from datetime import date
from pathlib import Path
from typing import Iterable
_DATA_FILE = Path(__file__).resolve().parents[1] / "data" / "google-updates.json"
# Every kind the ledger schema accepts. tests/test_content_quality.py asserts the
# ledger only uses these, and the CLI --kind filter accepts exactly the same set.
KNOWN_KINDS = (
"core", "spam", "core+spam", "policy", "qrg", "product", "schema", "cwv",
"discover", "documentation",
)
STALE_AFTER_DAYS = 30
_STATUS_URL = "https://status.search.google.com/"
def freshness(last_verified: str | None, today: date | None = None,
max_age: int = STALE_AFTER_DAYS) -> dict:
"""Return the ledger age and whether it is too old to trust for recent updates."""
today = today or date.today()
try:
verified = date.fromisoformat(str(last_verified))
except ValueError:
return {"age_days": None, "stale": True,
"warning": "last_verified is missing or not an ISO date."}
age = (today - verified).days
stale = age > max_age
warning = (f"Ledger last verified {age} days ago. Updates released since "
f"{verified.isoformat()} are missing; check {_STATUS_URL} before "
"attributing recent traffic changes.") if stale else None
return {"age_days": age, "stale": stale, "warning": warning}
def _load() -> dict:
with _DATA_FILE.open() as fh:
return json.load(fh)
def _parse_since(since: str) -> date:
"""Parse a ``--since`` value into a date.
Accepts ``yyyy``, ``yyyy-mm`` and ``yyyy-mm-dd``; the month and day may be
given without a leading zero (``2025-9`` means September 2025). Any other
shape, or an out-of-range month/day, raises ``ValueError`` with a message
the CLI turns into a clean error instead of a traceback.
"""
parts = since.split("-")
try:
if len(parts) == 1:
return date(int(parts[0]), 1, 1)
if len(parts) == 2:
return date(int(parts[0]), int(parts[1]), 1)
if len(parts) == 3:
return date(int(parts[0]), int(parts[1]), int(parts[2]))
except ValueError:
pass
raise ValueError(
f"invalid --since value: {since!r} (expected yyyy, yyyy-mm, or yyyy-mm-dd)"
)
def _filter(
updates: Iterable[dict],
*,
since: str | None = None,
kinds: set[str] | None = None,
) -> list[dict]:
out = list(updates)
if since:
since_date = _parse_since(since)
out = [u for u in out if date.fromisoformat(u["date"]) >= since_date]
if kinds:
# A combined "core+spam" rollout is both a core and a spam update, so
# asking for either one must include it (e.g. March 2024).
wanted = set(kinds)
if wanted & {"core", "spam"}:
wanted.add("core+spam")
out = [u for u in out if u.get("kind") in wanted]
out.sort(key=lambda u: u["date"], reverse=True)
return out
def main() -> int:
parser = argparse.ArgumentParser(
description="Query the primary-source Google updates changelog."
)
parser.add_argument(
"--since",
help="ISO date (yyyy, yyyy-mm, or yyyy-mm-dd) to filter from.",
)
parser.add_argument(
"--kind",
action="append",
choices=KNOWN_KINDS,
help="Filter to one or more kinds (repeatable).",
)
parser.add_argument(
"--limit", type=int, default=10,
help="Maximum number of entries to show (default 10).",
)
parser.add_argument(
"--unverified",
action="store_true",
help="Show only the unverified third-party claims awaiting "
"confirmation against status.search.google.com.",
)
parser.add_argument("--json", action="store_true")
args = parser.parse_args()
data = _load()
fresh = freshness(data.get("last_verified"))
if fresh["stale"] and not args.json:
print(f"WARNING: {fresh['warning']}", file=sys.stderr)
if args.unverified:
result = {
"last_verified": data.get("last_verified"),
"source_of_truth": data.get("source_of_truth"),
"unverified": data.get("unverified", []),
}
if args.json:
json.dump(result, sys.stdout, indent=2)
sys.stdout.write("\n")
else:
print(f"Source of truth: {result['source_of_truth']}")
print(f"Last verified: {result['last_verified']}")
print()
if not result["unverified"]:
print("(no unverified third-party claims tracked)")
for entry in result["unverified"]:
print(f" {entry['date']}: {entry['claim']}")
print(f" status: {entry['status']}")
for s in entry.get("third_party_sources", []):
print(f" third-party: {s}")
print(f" primary-check: {entry['primary_source_check']}")
print()
return 0
kinds = set(args.kind) if args.kind else None
try:
filtered = _filter(data["updates"], since=args.since, kinds=kinds)[: args.limit]
except ValueError as exc:
print(f"Error: {exc}", file=sys.stderr)
return 2
if args.json:
json.dump(
{
"source_of_truth": data["source_of_truth"],
"last_verified": data["last_verified"],
"freshness": fresh,
"filter": {"since": args.since, "kinds": list(kinds or [])},
"count": len(filtered),
"updates": filtered,
},
sys.stdout,
indent=2,
)
sys.stdout.write("\n")
return 0
print(f"Source of truth: {data['source_of_truth']}")
print(f"Last verified: {data['last_verified']}")
print(f"Showing {len(filtered)} updates"
f"{' since ' + args.since if args.since else ''}"
f"{' kind=' + '/'.join(kinds) if kinds else ''}")
print()
for u in filtered:
print(f" {u['date']} [{u['kind']:<10}] {u['name']}")
print(f" source: {u['source']}")
print(f" notes: {u['notes']}")
print()
return 0
if __name__ == "__main__":
sys.exit(main())