Agent ready

Agent-Ready: build for the agentic web

AI agents now choose and act on a user's behalf - booking, buying, integrating, configuring. Unlike a search engine, an agent does not present a list of options for a human to pick from; it picks one product and uses it end to end. A product an agent cannot find, understand, access, operate, or pay is invisible to that decision and fails silently.

This skill is a build-time companion: bake the plumbing in as you write the code, so the product works the first time an agent arrives instead of being retrofitted later. Each step of the agent journey has a reference file with the full build patterns - read the reference for the step you are working on before writing code.

Division of labor with Ora's live API. This skill is the durable part: the build patterns, the templates, and the prompt to think about agent-readiness while you code (greenfield needs that before any URL exists to scan). The live part - the current check catalog, the exact fix for each, and the score impact on a deployed product - lives in Ora's MCP/API, not here. Build with the skill; scan with scan_domain for what is actually broken and how to fix it. The skill deliberately does not duplicate that catalog, so it cannot go stale against it.

When to use

Load this skill when the task touches any public-facing or integration surface a product an agent might use:

• Designing or adding an API (REST or GraphQL), SDK, or CLI
• Building or changing auth (sign-up, API keys, OAuth, token scopes)
• Building an MCP server, or an MCP App / interactive UI an agent renders for a human
• Building checkout, billing, subscription, or any flow where money changes hands
• Writing or restructuring developer docs, a landing page, or pricing
• Adding llms.txt, structured data, or a /.well-known/ file
• Any time someone says "make this agent-ready" or "expose this to AI agents"

Do not over-apply it to general SEO, human-only UX, or purely internal infra (internal CI, data backup) where no external agent will ever interact. If unsure, ask: "would an agent ever do this on a user's behalf?" If yes, this skill applies.

Two modes

Building (greenfield or a new surface). Start at the greenfield quick start, build each relevant layer in order, then verify with Ora once deployed. Read the reference for the layer you are working on.

Improving (existing product). Scan with Ora first (scripts/verify-with-ora.sh or the scan_domain MCP tool), rank the fail/warning checks by estScoreGain, then jump to the reference file for the failing check's layer. Fix a batch, rescan, repeat. See "Verify and improve with Ora" below and references/verify-with-ora.md.

The agent journey

Agent-readiness is a sequence - each step gates the next. The first five are what an agent does on its own; handing back to a human is the deliberate exception, which is why it comes last. These six steps roll up to the five layers Ora scores - Discovery, Identity, Access, Payments, Experience. Access you and use you are the same scored layer (Access: connect, authenticate, and operate). The reference file for each step holds the full per-layer detail - file shapes, signals, templates, and pitfalls.

1. Discovery — Find you — get into the registries and indexes an agent checks before it ever reaches your site. /llms.txt, sitemap.xml, MCP registries, and an explicit AI-crawler policy in robots.txt are the primary signals; a product an agent cannot discover is invisible before it can be evaluated. → references/discovery.md
2. Identity — Understand you — answer "what is this and when should I use it?" from machine-readable signals alone. Serve real HTML (not a JS shell), add SoftwareApplication JSON-LD, and write explicit when-to-use guidance — an agent reading your homepage should extract a clear description without running a browser or digging through docs. → references/identity.md
3. Access — Access you — let an agent get credentials and act with zero human steps. A self-serve API key or OAuth client_credentials flow, documented agent auth, no captcha wall — the machine path must be completable end to end without a person in the loop. → references/access.md
4. Access — Use you — operate your product end to end: call the API, drive the MCP server, recover from errors. A published OpenAPI spec, clear MCP tool descriptions, JSON error bodies, idempotency keys, and rate-limit headers are what let an agent act reliably and resume when something breaks. → references/access.md
5. Payments — Pay you (only where relevant) — complete a transaction on agent-native rails without routing to a human-only checkout. A machine-completable path (API or MCP) plus at least one agent payment protocol (x402, ACP, UCP, AP2, MPP) and machine-readable pricing so the agent knows the cost before it commits. → references/payments.md
6. Experience — Hand back to you — for the one decision an agent should not make alone (an irreversible action, explicit payment auth, a visual choice), render an interactive UI the human acts on inside the agent surface, then resume. MCP Apps deliver a real control rather than a wall of text — integrity preserved, no relay errors. → references/experience.md

Mnemonic: can agents see you (find + understand), use you (access + operate), and pay you - handing back to a human only when a decision genuinely needs one.

Templates to copy and fill in live in assets/: llms.txt.template, openapi.skeleton.json, mcp-server-card.template.json, mcp-app-tool.example.json, agent-card.template.json.

Two rules that apply to every layer

Build only the surfaces your product genuinely has. Every check is gated on the surface it measures - if a surface does not exist, its checks are skipped, never counted as failures. Never add a surface just to satisfy a check; an absent surface was already free. So: OpenAPI/errors/idempotency/pagination only if you expose an API; MCP tools/annotations/server-card only if you ship an MCP server; payment rails only if you sell; MCP Apps only if you have a real human-handoff moment; accessibility-tree operability only for a step that lives solely in a web GUI.

Do established signals first, emerging ones as a forward bet. Established signals are proven and broadly relied on - do them first. Emerging signals (newer .well-known files, nascent protocols, draft standards) are worth adopting when cheap or strategically important, but may not count for much yet. A recommendation tagged (emerging) in the references is useful, not load-bearing - never block a launch on one.

Greenfield quick start (the minimal baseline)

Highest-leverage, lowest-cost moves; do these first, then go deeper in the reference for each layer:

1. Serve raw, readable content. AI crawlers do not execute JS - render meaningful HTML server-side (or a markdown fallback). → references/identity.md
2. Publish /llms.txt. A lean nav index of what you are and where the important pages are. Copy assets/llms.txt.template. A link index, not prose. → references/discovery.md
3. Add SoftwareApplication / Organization JSON-LD to the homepage with name, description, url, offers, sameAs. → references/identity.md
4. Publish an OpenAPI spec at /openapi.json if you have any API. Copy assets/openapi.skeleton.json - this one file unlocks most of the integration step. → references/access.md
5. Document machine auth. A self-serve path to an API key or OAuth client-credentials flow an agent can complete with no human. → references/access.md
6. Ship an MCP server if agents will take actions (not just read). Expose it at a discoverable path; add assets/mcp-server-card.template.json. → references/access.md
7. Return JSON errors, not HTML, from every API path - including unknown paths and auth failures. → references/access.md
8. If you sell, expose an agent-payable path. A machine-completable checkout plus at least one agent payment protocol. → references/payments.md
9. When a decision needs a human, render a UI, not a wall of text. Use an MCP App for that confirm / select / authorize moment. → references/experience.md

Verify and improve with Ora

Ora scans these same surfaces at run time. It is a loop, not a one-shot check: scan, triage the failing checks by impact, fix, rescan. Both interfaces return stable check ids, a per-check recommendation, and per-layer scores.

# Cached result with the full per-layer / per-check breakdown (fast)
curl https://ora.ai/api/score/yourdomain.com
# Or run a fresh scan
curl -X POST https://ora.ai/api/scan -H "Content-Type: application/json" -d '{"url":"yourdomain.com"}'

scripts/verify-with-ora.sh wraps this. Agent-native: connect to Ora's MCP server at https://ora.ai/api/mcp (Streamable HTTP) - scan_domain and get_score return the breakdown plus a prioritized "Top fixes" summary.

The improve loop: rank fail/warning checks by estScoreGain (the estimated 0-100 uplift, already in the response - not the raw maxScore − score gap, which overstates it), fix a batch of the biggest from each check's recommendation (skip na; bonus checks are upside-only), then rescan once and confirm the score moved - estScoreGain ranks fixes, it does not sum, so trust the rescan. First check analysisStatus is complete (a partial/stuck result is still running); stop when you hit your target grade or the top remaining gain is negligible.

Full response shape and endpoint/tool reference: references/verify-with-ora.md.

Anti-patterns to avoid

• Client-only rendering with no fallback - AI crawlers see an empty shell.
• HTML error pages from API routes - an agent expecting JSON gets an unparseable page and gives up.
• Human-only onboarding - sales-call-to-get-a-key, captcha walls, and manual approval all stop an agent cold.
• A captcha at the checkout or confirm step - it blocks the one moment an agent most needs to complete.
• A text-only handoff for a visual decision - relaying seat numbers or plan tiers as free text invites errors a simple UI would prevent.
• A marketing homepage masquerading as llms.txt - it must be a real, lean nav index.
• An MCP server with vague, undescribed tools - an agent cannot tell what a tool does or how to call it.
• Naming a backend vendor in agent-facing copy - describe the capability, not the implementation.
• Treating agent-readiness as a one-time checkbox - protocols evolve; re-verify when you ship public-surface changes.

How to apply this skill in a build task

1. Identify which step the task touches (an API change is "use you" / Access; a confirm screen is "hand back to you"; a checkout is "pay you").
2. Apply the two rules: confirm the product genuinely has that surface (else the layer is N/A - skip it), and do established signals before any (emerging) ones.
3. Read that step's reference file before writing code, and copy any relevant template from assets/.
4. Cross-check against the anti-patterns above.
5. If the surface is public, verify with the Ora scan once deployed - and if the goal is to raise the score, run the improve loop.