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.comNo 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.
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.txtname 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?
- Commerce structured data — are your Product/Offer JSON-LD blocks complete enough for agent-driven checkout?
- Identity corroboration — does the
sameAsgraph 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.
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.
Nothing to install — use npx:
npx @kirkelabs/agent-readiness-scan https://your-site.comOr add it to a project:
npm i -D @kirkelabs/agent-readiness-scanRequires Node.js ≥ 20.
# 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 --jsonFiles 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 |
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 + /.well-known/oauth-protected-resource with PKCE/S256 (NSA May-2026 guidance) |
| 5 | Agentic-commerce manifests | 7 | /.well-known/acp/manifest.json (OpenAI/Stripe) and/or /.well-known/ucp (Google Universal Cart) |
| 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.
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.comimport { scan } from '@kirkelabs/agent-readiness-scan';
const result = await scan('https://your-site.com');
console.log(result.score, result.grade);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 v0.1.0 score below 50 is normal today; a score above 80 puts you among the earliest customs-house operators. The bar will rise.
Once the scanner has graded your site, two prompt templates let Claude Code in your source repo do the rest:
- 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.
- 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.
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.
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.
MIT © 2026 Kirke Labs — Soleman El Gelawi and Steve Kirton. A genuine gift to the community — attribution appreciated, not required.