diff --git a/public/.well-known/agent-skills/index.json b/public/.well-known/agent-skills/index.json index 4f1ce201..cf25e706 100644 --- a/public/.well-known/agent-skills/index.json +++ b/public/.well-known/agent-skills/index.json @@ -6,7 +6,7 @@ "type": "skill-md", "description": "Query and apply The Website Specification — a platform-agnostic specification of what a good website does. Use when the user asks what their site should have, whether something is required, how to audit a URL, what's missing for agent readiness, or anything else where you'd otherwise be guessing at web best practice. Backs answers with primary sources and ships an MCP server with search, list, fetch, checklist, and audit tools.", "url": "/.well-known/agent-skills/specification-website/SKILL.md", - "digest": "sha256:7070db105de9efc80aecd3cf5ccf3c232da7116dd182f022ea20e38631127dcd" + "digest": "sha256:46e263c6c9b1ab557c6616b13293786a2ba1fb88ad425a530e86daf96bd6acad" } ] } diff --git a/public/.well-known/agent-skills/specification-website/SKILL.md b/public/.well-known/agent-skills/specification-website/SKILL.md index 796bae40..953c526f 100644 --- a/public/.well-known/agent-skills/specification-website/SKILL.md +++ b/public/.well-known/agent-skills/specification-website/SKILL.md @@ -5,7 +5,7 @@ description: Query and apply The Website Specification — a platform-agnostic s # specification.website -The Website Specification is a single source of truth for what a good website does. Ten categories, 177 pages, every item tagged with a status. It ships in three machine-readable forms: per-page Markdown, llms.txt / llms-full.txt, and an MCP server. +The Website Specification is a single source of truth for what a good website does. Ten categories, 178 pages, every item tagged with a status. It ships in three machine-readable forms: per-page Markdown, llms.txt / llms-full.txt, and an MCP server. ## When to use this skill diff --git a/public/og-default.png b/public/og-default.png index 2048eced..a5d3c3d2 100644 Binary files a/public/og-default.png and b/public/og-default.png differ diff --git a/public/og/checklist.png b/public/og/checklist.png index 336b24c2..65dd77b5 100644 Binary files a/public/og/checklist.png and b/public/og/checklist.png differ diff --git a/public/og/spec.png b/public/og/spec.png index 48f8ce05..25ae3fc6 100644 Binary files a/public/og/spec.png and b/public/og/spec.png differ diff --git a/public/og/spec/agent-readiness.png b/public/og/spec/agent-readiness.png index 5f62da69..ba70d605 100644 Binary files a/public/og/spec/agent-readiness.png and b/public/og/spec/agent-readiness.png differ diff --git a/public/og/spec/agent-readiness/universal-commerce-protocol.png b/public/og/spec/agent-readiness/universal-commerce-protocol.png new file mode 100644 index 00000000..d23245ad Binary files /dev/null and b/public/og/spec/agent-readiness/universal-commerce-protocol.png differ diff --git a/src/content/changelog/2026-10-28-universal-commerce-protocol.md b/src/content/changelog/2026-10-28-universal-commerce-protocol.md new file mode 100644 index 00000000..08d0ecb2 --- /dev/null +++ b/src/content/changelog/2026-10-28-universal-commerce-protocol.md @@ -0,0 +1,8 @@ +--- +title: Added Universal Commerce Protocol business profiles +date: "2026-10-28" +type: added +relatedSlugs: [universal-commerce-protocol] +--- + +Added an optional page on the [Universal Commerce Protocol](/spec/agent-readiness/universal-commerce-protocol/) and its `/.well-known/ucp` business profile, provisionally registered with IANA on 26 October 2026 and already served by Shopify storefronts. It explains that the profile is a capability manifest for agent checkout, not a product-discovery signal, and covers the spec's hosting rules on redirects and caching. diff --git a/src/content/spec/agent-readiness/a2a-agent-cards.md b/src/content/spec/agent-readiness/a2a-agent-cards.md index 93e0c297..9f06e8ea 100644 --- a/src/content/spec/agent-readiness/a2a-agent-cards.md +++ b/src/content/spec/agent-readiness/a2a-agent-cards.md @@ -6,7 +6,7 @@ summary: "The Agent-to-Agent (A2A) protocol lets an autonomous agent find anothe status: optional order: 82 appliesTo: [all] -relatedSlugs: [agent-readiness-overview, mcp-and-tool-discovery, agent-skills-discovery, machine-readable-formats, link-headers, api-catalog, dns-aid, agentic-resource-discovery] +relatedSlugs: [agent-readiness-overview, mcp-and-tool-discovery, agent-skills-discovery, machine-readable-formats, link-headers, api-catalog, dns-aid, agentic-resource-discovery, universal-commerce-protocol] updated: "2026-10-15T00:00:00.000Z" sources: - title: "A2A Protocol — Specification" diff --git a/src/content/spec/agent-readiness/agent-readiness-overview.md b/src/content/spec/agent-readiness/agent-readiness-overview.md index 516629ab..90d2600d 100644 --- a/src/content/spec/agent-readiness/agent-readiness-overview.md +++ b/src/content/spec/agent-readiness/agent-readiness-overview.md @@ -6,7 +6,7 @@ summary: "Agent readiness is the set of choices that make a site legible to AI a status: recommended order: 10 appliesTo: [all] -relatedSlugs: [llms-txt, markdown-source-endpoints, robots-for-ai-crawlers, tdmrep, stable-urls, structured-data-for-agents, machine-readable-formats, agent-skills-discovery, mcp-and-tool-discovery, a2a-agent-cards, web-bot-auth, webmcp, nlweb, server-side-rendering, agentic-resource-discovery, auth-md] +relatedSlugs: [llms-txt, markdown-source-endpoints, robots-for-ai-crawlers, tdmrep, stable-urls, structured-data-for-agents, machine-readable-formats, agent-skills-discovery, mcp-and-tool-discovery, a2a-agent-cards, web-bot-auth, webmcp, nlweb, server-side-rendering, agentic-resource-discovery, auth-md, universal-commerce-protocol] updated: "2026-06-08T00:00:00.000Z" sources: - title: "Is It Agent Ready?" diff --git a/src/content/spec/agent-readiness/mcp-and-tool-discovery.md b/src/content/spec/agent-readiness/mcp-and-tool-discovery.md index 3540d453..1d626778 100644 --- a/src/content/spec/agent-readiness/mcp-and-tool-discovery.md +++ b/src/content/spec/agent-readiness/mcp-and-tool-discovery.md @@ -6,7 +6,7 @@ summary: "The Model Context Protocol is an emerging way for sites to expose quer status: optional order: 80 appliesTo: [all] -relatedSlugs: [agent-readiness-overview, machine-readable-formats, llms-txt, link-headers, api-catalog, agent-skills-discovery, a2a-agent-cards, webmcp, nlweb, agentic-resource-discovery, oauth-protected-resource, deprecation-and-sunset] +relatedSlugs: [agent-readiness-overview, machine-readable-formats, llms-txt, link-headers, api-catalog, agent-skills-discovery, a2a-agent-cards, webmcp, nlweb, agentic-resource-discovery, oauth-protected-resource, deprecation-and-sunset, universal-commerce-protocol] updated: "2026-07-28T00:00:00.000Z" sources: - title: "Model Context Protocol" diff --git a/src/content/spec/agent-readiness/universal-commerce-protocol.md b/src/content/spec/agent-readiness/universal-commerce-protocol.md new file mode 100644 index 00000000..d1156981 --- /dev/null +++ b/src/content/spec/agent-readiness/universal-commerce-protocol.md @@ -0,0 +1,73 @@ +--- +title: "Universal Commerce Protocol (/.well-known/ucp)" +slug: universal-commerce-protocol +category: agent-readiness +summary: "A store that wants AI agents to check out on a shopper's behalf publishes a Universal Commerce Protocol (UCP) business profile at `/.well-known/ucp`. The profile does not list products; it says which commerce capabilities the store supports, which protocol versions it speaks, and where the transactional endpoints live." +status: optional +order: 84 +appliesTo: [all] +relatedSlugs: [mcp-and-tool-discovery, a2a-agent-cards, web-bot-auth, structured-data-for-agents, well-known-overview, cache-control, agent-readiness-overview] +updated: "2026-10-28T00:00:00.000Z" +sources: + - title: "IANA — Well-Known URIs registry (ucp)" + url: "https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml" + publisher: "IANA" + - title: "Universal Commerce Protocol — Specification overview" + url: "https://ucp.dev/latest/specification/overview/" + publisher: "UCP" + - title: "RFC 8615 — Well-Known Uniform Resource Identifiers (URIs)" + url: "https://www.rfc-editor.org/rfc/rfc8615" + publisher: "IETF" + - title: "Google Merchant Center — Universal Commerce Protocol" + url: "https://developers.google.com/merchant/ucp" + publisher: "Google" +--- + +## What it is + +The Universal Commerce Protocol (UCP) is an open protocol for agentic commerce: an AI agent, acting for a shopper, builds a cart and checks out with a business without a custom integration for each store. It is co-developed by retailers, platforms and payment companies (Google, Shopify, Etsy, Wayfair, Target and Walmart among them), and in October 2026 `/.well-known/ucp` was provisionally registered in the IANA Well-Known URIs registry. + +A business advertises its support by publishing a **business profile** at `/.well-known/ucp`. The profile is a JSON object with a `ucp` member that declares: + +- `version`: the protocol version, a date such as `2026-08-25`, not a semver number; +- `services`: the transports the business offers (REST, [MCP](/spec/agent-readiness/mcp-and-tool-discovery/), [A2A](/spec/agent-readiness/a2a-agent-cards/), or an embedded checkout), each with its endpoint and schema; +- `capabilities`: what the store can do, such as `dev.ucp.shopping.checkout`, plus extensions like fulfilment or discounts; +- `payment_handlers`: the payment methods the agent may use. + +The platform on the other side (the agent's host) publishes its own profile and names it on each request in a `UCP-Agent` header. The business fetches it, works out the intersection of capabilities both sides support, and proceeds. + +The common wrong belief is that this file makes your products visible to AI shopping assistants. It does not. The profile contains no products, prices or stock. Product discovery still depends on your [structured data](/spec/agent-readiness/structured-data-for-agents/) and merchant feeds. UCP comes later: it is the contract for _transacting_ once an agent has decided what to buy. A profile on a store whose product pages an agent cannot parse is a checkout with no way in. + +This site does not ship it: we sell nothing, so there is no checkout to expose. + +## Why it matters + +- **Agents can transact without screen-scraping.** Without a profile, an agent buying from your store has to drive your checkout UI like a person, which breaks on every redesign and fails at CAPTCHAs and payment challenges. With one, the agent calls typed endpoints and gets typed errors. +- **The business stays in control.** The protocol keeps the business as merchant of record and lets it decide which capabilities, payment handlers and platforms to accept. The `continue_url` field hands the shopper back to your own site when an agent cannot finish. +- **It is already deployed at scale.** Shopify serves a profile on its merchants' storefronts, so a large number of shops already publish one, often without the owner having looked at it. + +The status is `optional` because it only applies to sites that sell something. For a shop that wants agent-driven sales, treat it as you would a payment integration: deliberate, tested, and owned. + +## How to implement + +- **Check whether your platform already publishes one.** Request `/.well-known/ucp` on your own domain before building anything. Hosted commerce platforms may serve it for you, and then your job is to review what it declares rather than to write it. +- **Serve it exactly as the spec requires.** Profiles MUST be served over HTTPS, MUST NOT redirect, and MUST carry `Cache-Control` with `public` and a `max-age` of at least 60 seconds. `private`, `no-store` and `no-cache` are forbidden. Add an `ETag` or `Last-Modified` so consumers can revalidate. See [Cache-Control](/spec/performance/cache-control/). +- **Keep the profile stable.** It describes the business, not a session. No per-visitor or per-transaction values belong in it. +- **Declare only what works.** Every `services` entry needs a live endpoint and every capability a working implementation. Advertise every protocol version you still serve, so older agents can negotiate down. +- **Authenticate the agents that call you.** Businesses SHOULD verify the platform before acting on its requests. UCP supports API keys, OAuth 2.0, mTLS, and HTTP Message Signatures (RFC 9421). The signature route works with [Web Bot Auth](/spec/agent-readiness/web-bot-auth/), so a business that already verifies signed crawlers can reuse that verification. +- **Bound the cost of discovery.** Fetching the profile of an unknown platform is outbound work you do on demand. The spec suggests a fixed-size cache, a global rate limit, and backoff on failing profile URLs. + +## Common mistakes + +- **Treating the profile as an SEO or discovery asset.** It is a capability manifest. Publishing it does nothing for whether an agent finds or recommends your products. +- **Redirecting the well-known path.** A common habit is redirecting apex to `www` or `http` to `https`. The profile URL itself must answer `200` directly. +- **Serving it uncacheable.** A blanket `no-store` rule from a CDN or framework violates a MUST in the spec. Check the header on the actual response, not the configuration. +- **Advertising a capability you have not tested.** If the profile claims discounts or a particular payment handler, an agent will try to use them. A failed checkout costs more than a missing capability. +- **Expecting `rel="ucp"` to be standard.** Some implementations add a `Link: ; rel="ucp"` header. That relation is not in the IANA Link Relations registry, so clients should fetch the well-known path directly. + +## Verification + +- `curl -sI https://your-store.example/.well-known/ucp` returns `200` (no `3xx`) with `Content-Type: application/json` and a `Cache-Control` containing `public` and `max-age=60` or more. +- The body parses as JSON and contains `ucp.version`, `ucp.services` and `ucp.payment_handlers`. The two registries must be present even when empty. +- Every endpoint listed under `services` responds. A REST or MCP endpoint answering with an HTML error page is a broken profile. +- Every capability in the profile has been exercised end to end, with a real checkout on a test order, from at least one UCP-speaking platform. diff --git a/src/content/spec/agent-readiness/web-bot-auth.md b/src/content/spec/agent-readiness/web-bot-auth.md index a0577d17..24c321c5 100644 --- a/src/content/spec/agent-readiness/web-bot-auth.md +++ b/src/content/spec/agent-readiness/web-bot-auth.md @@ -6,7 +6,7 @@ summary: "Web Bot Auth lets a bot prove who it is by signing each HTTP request w status: optional order: 45 appliesTo: [all] -relatedSlugs: [robots-for-ai-crawlers, content-signals, agent-readiness-overview, link-headers, well-known-overview] +relatedSlugs: [robots-for-ai-crawlers, content-signals, agent-readiness-overview, link-headers, well-known-overview, universal-commerce-protocol] updated: "2026-09-10T00:00:00.000Z" sources: - title: "RFC 9421 — HTTP Message Signatures"