agent-readiness-scan

Is your brand ready for AI agents to act on it? Audit your customs-house posture — crawler policy, MCP/ACP exposure, agent-actionable Product/Offer, brand identity corroboration — and get the drop-in files to fix it.

npx @kirkelabs/agent-readiness-scan https://your-site.com

No install. No account. No data leaves your machine.

Built by Soleman El Gelawi (CTO, Kirke Labs), with Steve Kirton — open-sourced as a gift to the Algorand ecosystem. MIT licensed. Use it, fork it, ship it.

What is this?

The open web is becoming a customs house. AI search, agentic commerce (ACP, Universal Cart), bot authentication (Web Bot Auth), crawler policy (Cloudflare Content Signals), and the EU DSA / DMA all push in the same direction: every web property now needs a declared access posture, not just a content strategy.

agent-readiness-scan audits that posture. It fetches a URL plus seven .well-known/* paths plus robots.txt, and scores 8 dimensions covering:

• Crawler policy — does your robots.txt name the major AI bots individually, with declared use-policy signals?
• Bot authentication — is a Web Bot Auth key directory present?
• Agent action surfaces — MCP server card, Agentic Commerce Protocol manifest, Google Universal Cart manifest, Open Agent Access + x402 policy?
• Commerce structured data — are your Product/Offer JSON-LD blocks complete enough for agent-driven checkout?
• Identity corroboration — does the sameAs graph reach registry-grade sources (Wikidata, Crunchbase, Companies House, SEC EDGAR, GLEIF)?
• Source operations & regulatory transparency — dateModified, security.txt, T&Cs, contact, privacy.

Then it generates the files you need to fix the gaps — a drop-in robots.txt, .well-known/security.txt, MCP server card, and ACP manifest scaffolds.

Companion to @kirkelabs/ai-legibility-scan: that one scores how legible your site is to an AI crawler. This one scores how agent-ready it is once the crawler can read it.

Why?

The strategic paper this tool is built on — The Web Becomes a Customs House — argues that the new web bargain is declared-access-for-action. A page may be cited without being visited; a product may be transacted without a click. Existing "AI visibility" tools tell you you're invisible. This one is a free CLI that audits your customs-house posture and hands you the drop-in declarations to fix it.

Install

Nothing to install — use npx:

npx @kirkelabs/agent-readiness-scan https://your-site.com

Or add it to a project:

npm i -D @kirkelabs/agent-readiness-scan

Requires Node.js ≥ 20.

Quickstart

# default scan
npx @kirkelabs/agent-readiness-scan https://your-site.com

# write artefacts to ./report
npx @kirkelabs/agent-readiness-scan https://your-site.com --out ./report

# machine-readable output for scripting
npx @kirkelabs/agent-readiness-scan https://your-site.com --json

Files land in the output directory (default ./agent-readiness-out/):

| File / Directory | What it is | | ------------------------------------------------------ | --------------------------------------------------------------------- | | score.json | Machine-readable result — gate your CI on it | | report.md | Human-readable findings | | scorecard.html | Self-contained shareable scorecard | | customs-declaration/robots.txt | Drop-in robots.txt with per-AI-bot rules + Cloudflare Content Signals | | customs-declaration/.well-known/security.txt | RFC 9116 scaffold | | customs-declaration/.well-known/mcp/server-card.json | MCP server card scaffold | | customs-declaration/.well-known/acp/manifest.json | Agentic Commerce Protocol manifest scaffold |

How it scores

Eight weighted dimensions, normalised to 0–100 and graded A–F:

| # | Dimension | Weight | What it checks | | --- | ------------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Per-bot crawler policy | 10 | robots.txt names individual AI bots (GPTBot, ClaudeBot, OAI-SearchBot, PerplexityBot, Google-Extended, anthropic-ai, Claude-Web, ChatGPT-User, Claude-User, CCBot, Bytespider, Amazonbot, Applebot-Extended, meta-externalagent) | | 2 | Declared use-policy signals | 7 | Cloudflare Content Signals (search / ai-input / ai-train), noai / noimageai meta, X-Robots-Tag | | 3 | Bot-Auth readiness | 5 | /.well-known/http-message-signatures-directory (Web Bot Auth, IETF draft) | | 4 | MCP exposure | 7 | /.well-known/mcp/server-card.json + scoped auth via /.well-known/oauth-protected-resource with PKCE/S256 (NSA May-2026 guidance) or an Open Agent Access policy guard — accepted as equivalent postures | | 5 | Agentic-commerce manifests | 7 | /.well-known/acp/manifest.json (OpenAI/Stripe), /.well-known/ucp (Google Universal Cart), and/or /.well-known/agent-access.json (Open Agent Access + x402 on Algorand) — accepted as standards-neutral alternatives | | 6 | Agent-actionable Product/Offer | 7 | Product/Offer JSON-LD completeness (price, availability, priceValidUntil-future, shippingDetails, acceptedPaymentMethod, hasMerchantReturnPolicy, aggregateRating) | | 7 | Brand identity corroboration | 8 | sameAs to registry-grade sources (Wikidata, Crunchbase, OpenCorporates, Companies House, SEC EDGAR, GLEIF, plus LinkedIn/GitHub) | | 8 | Source provenance & regulatory | 5 | dateModified/datePublished, security.txt, T&Cs, contact, privacy policy |

Full rubric, thresholds and rationale: docs/METHODOLOGY.md.

Use in CI

The CLI exits non-zero when the score drops below 50:

# .github/workflows/agent-readiness.yml
- run: npx @kirkelabs/agent-readiness-scan https://staging.your-site.com

Programmatic use

import { scan } from '@kirkelabs/agent-readiness-scan';

const result = await scan('https://your-site.com');
console.log(result.score, result.grade);

Limitations (read this)

This tool measures heuristic indicators of agent-readiness. A high score makes a site easier for an AI agent to discover, declare access to, and act on — it is not a guarantee of agent uptake, citation, or transaction. The weights are informed by 2026 standards work (MCP, ACP, UCP, Web Bot Auth, Content Signals) but are judgement calls, documented openly in docs/METHODOLOGY.md. See also SECURITY.md.

Most of the dimensions check standards that are emerging, not universal. A score below 50 is normal today; a score above 80 puts you among the earliest customs-house operators. The bar will rise.

Disclosure: Open Agent Access (OAA), one of the recognized signals in the MCP-exposure and agentic-commerce dimensions, is implemented by Kirke Labs — the author of this tool. OAA is scored as one of several live standards (alongside ACP, UCP, and OAuth), never privileged: weights are unchanged and detection is held to the same evidence bar as the others. A site using only ACP/UCP/OAuth scores exactly as it did before OAA was recognized. See docs/METHODOLOGY.md.

Audit, recon, fix — three steps to lift your score

Once the scanner has graded your site, two prompt templates let Claude Code in your source repo do the rest:

1. docs/RECON_PROMPT.md — read-only reconnaissance prompt that greps the codebase and returns a structured report of your framework, existing manifests, identity URLs, and routes.
2. docs/PROMPT_TEMPLATE.md — the fix prompt. Fill in the placeholders informed by the recon, paste into a new Claude Code session to ship the customs declaration.

Companion tool

See also @kirkelabs/ai-legibility-scan — scores how legible your page is to AI crawlers (the layer below this one). Together they cover the audit-recon-fix loop for both halves of the customs-house thesis: legibility + declared access.

Contributing

Issues and PRs welcome — especially scoring false positives, new checks tracking emerging standards, and additional identity-registry coverage. See CONTRIBUTING.md and the Code of Conduct.

Licence

MIT © 2026 Kirke Labs — Soleman El Gelawi and Steve Kirton. A genuine gift to the community — attribution appreciated, not required.

— www.kirkelabs.com