Public agent-readiness signals, plus local, CI, browser, and commerce probes — before you ship.
The public agent-readiness tools only see what's on the open internet. That rules out http://localhost:3000, your staging deploy behind a VPN, your CI preview, and every PR before it merges — exactly when fixing things is cheap. agent-readiness is a small CLI you point at any URL you can reach.
$ agent-readiness https://example.com
agent-readiness https://example.com/
scanned 2026-05-20T07:31:09Z
[discoverability] 3/3 passing
PASS robots.txt — Valid robots.txt with 11 User-agent group(s)
PASS sitemap.xml — Valid sitemap (well-known)
PASS Link header advertising api-catalog — Link header advertises api-catalog
WARN DNS for AI Discovery (DNS-AID draft) — No DNS-AID index; DNSSEC unknown
[content] 1/1 passing
PASS Markdown content negotiation — Server returns text/markdown for Accept: text/markdown
[bot-access] 2/3 passing
PASS Content Signals policy — Valid policy: ai-train=no, search=yes
PASS AI bot rules in robots.txt — Rules present for: GPTBot, ClaudeBot, ...
PASS Bot policy matrix (Search / Agent / Training) — Search=...; Agent=...; Training=...
FAIL Web Bot Auth public key directory — 200 but content-type "text/html" — looks like SPA fallthrough
Run it without installing (Node 20+ or Bun):
npx agent-readiness-cli https://example.com
bunx agent-readiness-cli https://example.comOr install the agent-readiness command globally:
npm install -g agent-readiness-cli
agent-readiness https://example.comFrom source (needs Bun 1.1+):
git clone https://github.com/itaides/agent-readiness.git
cd agent-readiness
bun install
bun run build
bun linkScanning a local dev server (HTTPS with self-signed cert, RFC1918, IPv6 loopback — all handled):
agent-readiness http://localhost:3000141 checks across 5 categories, with unstable or runtime-dependent standards kept informational. Full pass criteria, endpoints, scoring rules, and spec references live in docs/checks.md.
robots.txt(RFC 9309)sitemap.xml(withrobots.txtfallback discovery)- Sitemap
lastmodcoverage (informational) Linkheader advertisingrel="api-catalog"(RFC 8288)- DNS-AID organization index (draft, informational)
- RSS/Atom feed discovery (informational)
- ARD / AI Catalog discovery at
/.well-known/ard.json(+ai-catalog.jsonlegacy), entry validity, trust manifest - Agent discovery files (
agent.json) and plugin manifests (ai-plugin.json) - MCP registry listing, registry branding, Wikipedia/Wikidata entity presence (opt-in
--external-lookups)
- Markdown content negotiation (
Accept: text/markdown, includingVary: Acceptcorrectness) - Per-page
.mdmarkdown mirror - Markdown discovery link relations (informational)
llms.txt(llmstxt.org — opt-in via--include-llms-txt) plus formatting/link-resolution/modular qualityllms-full.txt(opt-in via--include-llms-txt)sitemap.mdmarkdown index (informational)AGENTS.mdinstruction file (opt-in via--include-agents-md)- Page-level HTML readability (SSR content, headings, metadata, text ratio)
- JSON-LD structured data, entity
sameAslinking, Organization completeness, schema-type breadth - Content freshness signals (informational)
- Semantic agent-navigable controls (informational)
- Accessibility surface: document structure, native controls, accessible names, form labeling, injection safety
- Markdown frontmatter, code-fence validity, page token budget
- Metadata completeness, redirect hygiene, agent-friendly 404s,
pricing.md, pricing pages,?mode=agentviews - Trust anchors (about/contact/privacy), public API docs links, developer portal, agent usage guidance, docs-behind-auth sampling
- NLWeb schema feeds, MCP well-known discovery, HTTP Link-header discovery
- Content Signals in
robots.txtand response headers (ai-train,ai-input,search, optionaluse) - AI bot rules in
robots.txt— looks for User-agent lines targeting GPTBot, ClaudeBot, PerplexityBot, Google-Extended, and 10 more - Cloudflare-style Search / Agent / Training policy matrix (informational)
X-Robots-Tagrestrictive directive detection- TDMRep /
ai.txtpolicy signals (informational) - AI-bot vs browser User-Agent differential
- Web Bot Auth key directory at
/.well-known/http-message-signatures-directory robots.txtpolicy quality for AI search crawlers and user-directed agents (informational)
- A2A Agent Card at
/.well-known/agent-card.json - Agent Skills v0.2 index at
/.well-known/agent-skills/index.json, with optional SHA-256 artifact verification - API Catalog at
/.well-known/api-catalog(RFC 9727) - OAuth Authorization Server Metadata (RFC 8414) + scoped-permissions analysis
- OAuth Protected Resource Metadata (RFC 9728)
agents.txt/agents.jsoncapability declaration (informational)- OpenAPI/Swagger spec discovery at common paths
- MCP Server Card at
/.well-known/mcp/server-card.json - WebMCP (fetch-only heuristic, informational)
auth.mdagent registration guidance (opt-in, informational) plus structure/endpoint-reachability quality- MCP 2026-07-28
server/discover(explicit endpoint, informational) - Lighthouse Agentic Browsing (opt-in, informational)
- OpenAPI quality family: reachable endpoints, schema coverage, typed error model, versioning/deprecation, pagination, async jobs, batch endpoints,
Idempotency-Key, rate-limit headers, function-calling compat, schema complexity, JSON error bodies - GraphQL family: typed errors, versioning, pagination, async jobs, description coverage, batch mutations
- Deep MCP family (with
--mcp-url, read-only): initialize + server identity, tool listing/descriptions/schemas/naming/annotations, error handling, modern transport, auth mechanism, OAuth metadata, PKCE S256, resource listing/quality, multi-surface coverage, MCP Apps UI + view domain/CSP - Agent-auth family (with
--include-auth-md):agent_authdiscovery metadata,WWW-Authenticatehints, endpoint reachability - PAP/Poppy draft family: discovery doc, issuer binding, auth config, interfaces, endpoint enforcement, cross-protocol consistency
- NLWeb
/ask+ streaming, A2UI/generative-UI signals, onboarding friction, sandbox environment - SDK/CLI listings: npm/PyPI packages, multi-language SDKs, CLI tool, skills.sh presence + quality (opt-in
--external-lookups)
- UCP discovery at
/.well-known/ucp - x402 v2
PAYMENT-REQUIREDchallenge - MPP
WWW-Authenticate: Paymentchallenge - ACP
checkout_sessions+ delegate-payment endpoints (informational) - AP2 agent-payments markers (informational)
Commerce checks run only when you supply --commerce-url; they observe the initial 402 response and never pay.
Browser mode expects Lighthouse 13.3+ on PATH (for example, npm install -g lighthouse) and Chrome 150+; set AGENT_READINESS_LIGHTHOUSE to an explicit Lighthouse executable when needed.
agent-readiness <url> [options]
--preset all|content|api|commerce
Check group preset (default: all)
--site-type full|content content: skip API/auth checks a content site can't have,
and leave them out of the score (default: full)
--only id1,id2,... Run only these check IDs (overrides --preset)
--skip id1,id2,... Skip these check IDs (applied after preset)
--list-checks List every check and preset, then exit
--include-llms-txt Run the opt-in llms.txt and llms-full.txt checks
--include-auth-md Run the API-focused auth.md check
--include-agents-md Run the opt-in AGENTS.md check
--crawl <n> Sample up to n sitemap pages and aggregate page-level checks
--content-url <url> Page used for content and browser checks
--commerce-url <url> Paid resource used for UCP/x402/MPP checks
--mcp-url <url> MCP HTTP endpoint used for server/discover
--browser Run Lighthouse Agentic Browsing
--verify-skill-digests Fetch and verify Agent Skills artifacts
--external-lookups Send the site name/domain to third-party directories
(MCP registry, Wikidata, npm/PyPI, skills.sh)
--baseline <report.json> Exit 1 only for pass/fail regressions
--format human|json|html|md Output format (default: human)
--timeout <ms> Per-request timeout (default: 5000)
--concurrency <n> Parallel requests (default: 4)
--insecure Skip TLS verification (auto-on for loopback/RFC1918)
--user-agent <ua> Spoof UA (e.g. "GPTBot/1.0")
--header "K: V" Inject a request header (repeatable)
--cookie <value> Send a Cookie header to the target
--version, -v Print the version and exit
JSON output is pipeable and diffable:
agent-readiness https://example.com --format json | jq '.summary'Failed and warning checks include a concise how-to-fix suggestion plus a target-specific verification command. JSON exposes the same information as structured remediation data, and the prompts/ package contains longer copy-ready implementation prompts:
FAIL Markdown content negotiation — content-type "text/html" is not text/markdown
FIX Return Markdown plus Content-Type: text/markdown and Vary: Accept...
VERIFY agent-readiness https://example.com/ --only markdown-negotiation
HTML output is a single self-contained file — inline CSS, no external assets, dark-mode-aware — ready to open in a browser, attach to a PR comment, or drop into a dashboard:
agent-readiness https://example.com --format html > report.html
open report.htmlMarkdown output works for PR bodies and Slack threads:
agent-readiness https://example.com --format mdThe scanner, the check list and the report formatters can be imported from Node 20+ or Bun to run scans in your own program. The entry point is experimental: any 0.x minor release may change it, so pin the version.
import { checks, createHttpClient, createTarget, formatHtml, scan } from 'agent-readiness-cli/library';
const target = createTarget({ url: 'https://example.com' });
const http = createHttpClient({ timeoutMs: 10_000, userAgent: 'my-app', defaultHeaders: {}, insecure: false });
const report = await scan(target, checks, http, { concurrency: 8, siteType: 'full' });
console.log(report.score, formatHtml(report).length);It exports scan, createTarget, createHttpClient, checks, PRESETS, NOT_APPLICABLE, SITE_TYPES, addRemediation, formatJson, formatMarkdown, formatHtml, resolveScore, the report's minified REPORT_CSS and REPORT_JS, VERSION, and the report types. The browser-agentic check runs the lighthouse command, so leave it out where Lighthouse and Chrome aren't installed.
The default scan uses HTTP and DNS signals and runs against http://localhost:3000, staging, and private networks. DNS-AID and commerce skip local/private targets. Browser execution is explicit via --browser.
SPA dev servers return 200 OK + text/html for any path, including /.well-known/* paths that should be JSON. A naive scanner ("did we get 200?") reports these as passing. Every JSON check here validates the content-type and parses the body and checks required fields before claiming a pass. The same logic catches partial implementations in production — a real well-known endpoint serving JSON that's missing required fields fails for the right reason.
A default HTTP/DNS scan finishes quickly against a typical site. The core CLI is a ~50 KB minified JS bundle, and the HTML report is a separate ~45 KB file loaded only for --format html; Lighthouse is an optional runtime dependency used only by --browser.
Save a JSON report, then use it as a baseline. Existing failures remain visible but do not break the build; a pass→fail transition or a newly introduced failure exits 1.
agent-readiness https://staging.example.com --format json > readiness-baseline.json
agent-readiness https://staging.example.com --baseline readiness-baseline.jsonReady-made, tested setups for GitHub Actions and GitLab CI are in docs/ci.md: gate each pull request on its own build against main's baseline and a minimum score, keep the reports as artifacts, and scan production daily.
The tool has no analytics or telemetry. Default scans contact only the target origin plus its DNS resolver; explicit flags may load the content page in Chrome, contact a supplied MCP/commerce URL, or fetch skill artifact URLs advertised by the target. See PRIVACY.md.
The code in this repository is the code that runs on your machine. The build output in dist/ is minified JavaScript, built directly from src/: cli.js (~50 KB) plus a chunk for the HTML report that loads only with --format html.
Reporting a vulnerability: see SECURITY.md. Findings about target sites you scan are between you and those site operators. Tool bugs (a false pass in shape validation, for example) — please report privately first.
git clone git@github.com:itaides/agent-readiness.git
cd agent-readiness
bun install
bun test
bun run build # dist/cli.js + dist/library.js, shared chunks, and dist/types/*.d.ts
bun run typecheck
bun run audit:specsProject layout:
src/
cli.ts # arg parsing + main()
library.ts # the agent-readiness-cli/library entry point
scanner.ts # parallel check orchestrator
http.ts # fetch wrapper: timeout, redirects, body cap, insecure mode
target.ts # URL normalize + locality detection (loopback / RFC1918 / ULA)
report.ts # human + JSON formatters
registry.ts # check list + preset definitions
types.ts # Check, CheckResult, Target, HttpClient, Report
checks/
_shared.ts # JSON well-known fetcher + shape validation helper
*.ts # one file per check (23 of them)
test/
checks/*.test.ts # per-check unit tests
e2e.test.ts # all checks against fixture-server
testdata/
fixture-server.ts # all-pass + SPA-fallthrough modes
docs/
checks.md # spec — pass criteria for every check
roadmap.md # stabilization queue + watchlist
prompts/ # copy-ready remediation prompts
scripts/
audit-spec-staleness.ts
Adding a new check:
- Add
src/checks/<id>.tswith a default export of typeCheck. - Register it in
src/registry.ts. - Document it in
docs/checks.mdwith endpoint + pass criteria + spec URL +asOfdate. - Add fixture data to
testdata/fixture-server.tsfor the all-pass case. bun testshould still pass.
Contributions are welcome. Read CONTRIBUTING.md for development setup, check acceptance criteria, remediation requirements, safety boundaries, validation commands, and the pull request checklist.
MIT. Inspired by isitagentready.com and the Cloudflare agent-readiness blog post. Independent open-source implementation — not affiliated with Cloudflare.