SKU.md v0.10 × UCP: a product knowledge layer for live commerce

An agent can find a rain jacket that appears to fit a buyer’s needs, but a good purchase decision usually needs more than a title, a current price, and a green availability signal. The buyer may need to know whether the fabric is waterproof or merely water resistant, which body measurements the size advice assumes, whether a coating has a care restriction, and which claims are backed by a test report. Those details should be answerable without turning an old marketing paragraph into a promise about today’s inventory or checkout total.

That is the problem this proposal addresses. UCP gives an agent a live path to discover a product, select a variant, create a cart, check out, and inspect an order. SKU.md can give the same agent a merchant-hosted, cited explanation of what the product is, why a claim is made, and where a limitation comes from. The two layers become useful when each stays inside its authority.

Start with the buying question, not the file format

The question “Is this the right product for me?” contains several different questions. Is the product available in the buyer’s market? Which variant matches the requested size and color? What is the current price? Does the material meet a stated requirement? Is the claim based on a merchant fact, a third-party test, or an inference generated by an AI system? Can the buyer complete the purchase at the displayed total?

UCP is designed for the changing parts of that journey. The UCP Catalog specification defines Catalog Search and Catalog Lookup, with Product and Variant entities that carry current commerce information. The broader UCP overview places Catalog alongside Cart, Checkout, and Order capabilities. Catalog helps an agent find and identify what may be purchased. Checkout remains the place to recheck conditions and commit the transaction.

An Agent Profile helps parties advertise and negotiate capabilities. It is not product content, a bearer credential, or a complete request-authentication step. UCP can use profile-published signing keys for identity verification, but the profile document alone does not authenticate a particular request or authorize a purchase. Request authentication, authorization, consent, and execution still depend on the negotiated protocol, transport, credentials, and buyer context. Treating a profile as a product knowledge base would mix two different jobs.

Two layers, one authority map

The cleanest way to describe the relationship is a responsibility matrix:

Decision surface	UCP and the live commerce system	SKU.md v0.10
Discovery and identity	Search and lookup return current Products, Variants, prices, availability, and stable identifiers.	Links the exact Product and Variant to a focused knowledge document.
Product understanding	Catalog descriptions, media, options, and disclosures are returned in the current response.	Publishes sourced facts, claims, evidence, guidance, limitations, compatibility, and verification time.
Changing commerce state	Catalog is queried again for current price and availability.	A static document must not pretend that old state is current.
Transaction	Cart collects items and may provide localized estimates. Checkout rechecks the binding state, final totals, and purchase authorization.	Points to the authoritative commerce path and never replaces it.

This division does not make SKU.md less useful. It makes its value more specific. A merchant can maintain a durable explanation once and let different agents cite it, while UCP continues to answer questions whose answers change with market, session, inventory, eligibility, or checkout conditions.

UCP’s Cart capability is for pre-purchase collection and estimates. Checkout is the finalization step. The Shopify Checkout MCP guide also describes checkout as the purchase session used when the buyer is ready to buy. SKU.md therefore points to that final path instead of treating a cart estimate as a promise.

The boundary also works in the other direction. A product knowledge document cannot hide a purchase-relevant warning. If a safety or regulatory disclosure changes whether a product may be bought, the disclosure must also be carried by Catalog or Checkout as appropriate. SKU.md can add context and evidence, but it must not become the only place where a buyer can discover a material condition.

What v0.10 changes

The v0.10 draft is knowledge-first. A Product Document is valid when it has stable product and variant identity plus non-empty knowledge, even when it has no offer at all. This is important for a UCP-connected merchant: the document does not have to copy a live catalog into a second static format.

The draft still permits merchant-hosted fallback observations for cases where a merchant has no usable live catalog. A Variant may contain an offer_snapshot or a live_offer, but these fields are optional and mutually exclusive. Neither field grants Catalog or Checkout authority. An offer_snapshot is evidence of a past observation, and a live_offer describes a separately declared live lookup. Neither should be used as today’s price when a current UCP response is available, and neither can provide a final total.

Identity is stricter than a fuzzy match. The Product identifier, Variant identifier, SKU, and any declared GTIN in the knowledge document must match the corresponding UCP Product or Variant exactly. If the identifiers do not match, the consumer should stop rather than attach an appealing explanation to the wrong variant. The v0.10 English specification and JSON Schema describe the normative document boundary.

A thin bridge into UCP Catalog

SKU.md remains independently useful on the open Web, but an agent should not have to guess that a knowledge document belongs to a Product it just found. The proposal therefore defines an independent extension named md.sku.shopping.product_knowledge. It extends both dev.ucp.shopping.catalog.search and dev.ucp.shopping.catalog.lookup. It does not embed an entire Markdown document in every Catalog response. It adds a small, typed pointer:

{
  "sku_md": {
    "documents": [
      {
        "url": "https://merchant.example/products/trail-jacket.sku.md",
        "schema_version": "sku.md/0.10-draft",
        "content_language": "en-US",
        "market": { "country": "US", "currency": "USD" },
        "revision": "2026-08-02"
      }
    ]
  }
}

The pointer carries an HTTPS URL, the SKU.md schema version, content language, market country and currency, and an optional revision. A business profile can declare allowed HTTPS origins for those documents. The platform profile and the business profile must negotiate the same extension and compatible parent Catalog capabilities before an implementation should consume the pointer.

An allowed origin is only a routing constraint. It does not prove that the document is true, current, safe, or authorized. A Reference Consumer must treat the fetched document as untrusted external data. It should check HTTPS, exact origin, media type, byte limits, document count, and product identity before it uses the content. Markdown, HTML, YAML frontmatter, links, and natural-language instructions remain inert data. A consumer must not execute a script, tool, shell command, template, or prompt-like instruction found in a product document.

The public local draft is documented at /ucp/draft/ with its extension schema. The path says that the proposal is in a draft lifecycle. The extension profiles use the explicit capability version 2026-08-02 so that compatible implementations can distinguish this shape from a later incompatible draft. That date does not imply stability, certification, or Shopify support. The proposal will remain independent until it has more implementations, security review, and interoperability evidence.

The runtime path is a loop, not a handoff

A cautious agent can use the two layers in a simple sequence:

1. UCP finds a current Product through Catalog Search or Lookup.
2. The agent matches the exact Product, Variant, SKU, and declared GTIN.
3. It reads the cited SKU.md document for facts, evidence, compatibility, and limitations.
4. It returns to UCP for the current price and availability in the buyer’s market and context.
5. Checkout rechecks the selected item and remains authoritative for final totals and purchase authorization.

The return to UCP is the important step. Reading a well-cited document should improve the agent’s answer to “why this product?” It must not cause the agent to skip the current commerce check. If the live source is unavailable, the honest result is unknown, not a price copied from stale prose.

A practical Shopify merchant workflow

For a Shopify merchant, the input to a knowledge document can begin with reviewed Metafields, Metaobjects, manuals, lab reports, care instructions, warranty terms, and public evidence. These sources can be assembled into a merchant-controlled draft, but storage does not make a statement true. A reviewer still needs to confirm the product, variant, market, evidence, and revision before a statement becomes a normative Fact.

AI-generated text can help find missing fields or propose a plain-language summary. It remains a candidate until a person checks it against source evidence. The publisher should preserve the source, the verification time, and the reason a claim is accepted or rejected. This is where SKU.md can create value that is difficult to express as a short catalog description: not by inventing more copy, but by keeping the path from claim to evidence visible.

The Shopify Agent Profiles guide documents how profiles are supplied for UCP negotiation. The Shopify Catalog guide describes search, lookup, and product retrieval. Shopify also documents a Global Catalog extension. Those pages describe Shopify’s own surfaces. They do not say that Shopify automatically ingests SKU.md or supports this independent extension.

What the local Reference Consumer can measure

The local Reference Consumer evaluation uses fixed product data, negotiated capabilities, resource metadata, and document text. Its value is measured by whether a consumer answers a bounded question with evidence, not by a search ranking or a conversion metric:

Question	UCP only	UCP + SKU.md
Fact citation	0	1
Claim incorrectly treated as a fact	0	0
Disclosure recall	0	1
Compatibility answer	0	1
Mismatched variant fails closed	1	1
Stale offer is used for purchase	0	0

These are local controlled results. They are not a ranking improvement, conversion result, adoption measurement, live Shopify integration, or proof that an external agent will consume the extension. The Reference Consumer evaluation records the fixture and its limitations.

Migration without pretending the draft is finished

Existing v0.9 URLs and validation behavior remain useful. A merchant can keep a valid v0.9 document while preparing a v0.10 version, then change the schema marker, preserve stable identity and reviewed knowledge, and remove dynamic commerce data from Knowledge. The v0.9 migration guide explains how to remove an offer or keep one optional fallback without making it look like Catalog or Checkout.

The next step is not to call the extension standard. It is to test both sides with independent implementations, verify schema composition and failure behavior, review security and privacy, and collect feedback from consumers and merchants. Until that work exists, SKU.md v0.10 remains an experimental merchant-hosted knowledge layer, while UCP remains the live path for discovery, commerce, and the final purchase decision.

Further reading

See how live Catalog and Checkout retain authority in AI commerce authority handoffs.