agent-readiness-scan

name	agent-readiness-scan
description	Use when a client audit, GEO/AI-visibility snapshot, or remediation re-scan needs the Cloudflare agent-readiness score from isitagentready.com — e.g. Theo client audits, "is the site agent-ready", markdown negotiation / MCP / llms.txt / Content-Signal checks, or tracking score deltas after Tier 0/1 fixes.
metadata	{"version":"1.0.0","origin":"extracted from production GEO-audit + agent-readiness remediation sessions"}

Agent-Readiness Scan (isitagentready.com)

Produce the official Cloudflare agent-readiness result for a domain as audit-grade artifacts: fixed-schema CSV + raw evidence + the 0-100 score.

Critical facts (learned the hard way)

1. Two sources, both required:
   • POST https://isitagentready.com/api/scan body {"url":"https://<domain>"} → full JSON (level, levelName, per-check status + embedded request/response evidence, nextLevel remediation prompts + skillUrls). No numeric score in the JSON.
   • The 0-100 score renders only in the web UI. Playwright-navigate to https://isitagentready.com/<host> and read the score dial: an <svg> carrying aria-label="Overall score: N out of 100". Never wait_for that text — it's an attribute, not visible text (text-waits time out). Take a page snapshot or evaluate document.querySelector('[aria-label*="Overall score"]'). A fresh "Last scanned" timestamp = results are rendered (the step-1 API POST itself refreshes the scan, so no Scan click is normally needed). Without the 0-100 you cannot track deltas (e.g. a site improving 21→43 after fixes).
2. Don't freeze the checklist. The scanner evolves (new checks appear). Emit whatever .checks returns, mapped through the fixed CSV schema — never hand-author check rows.
3. Scored vs supplementary. llms.txt, llms-full.txt, security.txt are NOT scored by Cloudflare but Theo audits track them — they go in Supplementary (not scored) rows from curl probes, never mixed into scored categories.
4. Commerce is informational unless isCommerce is true — one NOT CHECKED row, "does not affect score".

Workflow

scripts/run_scan.sh https://<domain> <outdir>/raw-data

Then get the official score via Playwright (see Critical fact 1 for the exact method). Save the page snapshot to raw-data/isitagentready_<client-slug>_snapshot.txt (client slug, e.g. acme — matches your audit config slug). Then:

python3 scripts/scan_to_csv.py \
  <outdir>/raw-data/iar_scan.json --score <N> --out <outdir>/csv-base-data/agent_readiness_checks.csv

(csv-base-data/ is the Theo full-pack convention; scoped snapshots have used plain csv/ — either is fine, pass --out explicitly.)

CSV schema (fixed — cross-client comparability depends on it)

category,check,result,detail,source

• Row 1: OVERALL,Agent-readiness score,<N>/100 - Level <L> <Name>,<p> pass / <f> fails; Commerce <note>,isitagentready.com/<host> (Cloudflare) <YYYY-MM-DD>
• Category names carry computed tallies, e.g. Discoverability (1/4) — denominators come from whatever the scanner returns that run (it grows new checks), counting scored checks only (pass/fail), never neutral ones.
• Results: PASS / FAIL / NOT CHECKED (scanner statuses other than pass/fail — e.g. neutral, skip — map to NOT CHECKED and are excluded from tallies); detail = scanner message verbatim (commas stripped/quoted)
• Supplementary rows last, PRESENT/ABSENT from curl.

Report section + remediation

Headline format: Agent readiness (Cloudflare isitagentready.com) | **N/100 — Level L "Name"** (p pass, f fails). For remediation, lift nextLevel.requirements[].prompt verbatim (they're copy-paste fix prompts with spec URLs); the common Tier 0/1 fix pattern is a markdown negotiation map, robots Content-Signal, link headers, llms-full.txt, and security.txt.

Common mistakes

Mistake	Fix
Reporting only Level, no 0-100	UI aria-label is the only score source — Playwright step is not optional
Inventing/renaming categories ("Protocol Discovery")	Use the mapping in scan_to_csv.py; discovery → API Auth MCP & Skill Discovery
WebFetch on isitagentready.com/	JS app — returns shell, no results. API or Playwright only
curl-only assessment without the official scan	curl corroborates; the scan JSON is the authority for scored checks
Mixing llms.txt into scored categories	Supplementary, not scored