When Shopify shipped @shopify/ucp-cli last week, most of the coverage focused on the obvious part: AI agents can now browse and buy from Shopify stores using the Universal Commerce Protocol.
What got less attention was the file bundled inside the package — SKILL.md.
That file is not protocol. It's instructions. It tells AI agents how to behave when shopping on Shopify: start with discovery, sequence cart before checkout, render totals in the order the merchant provides them, treat escalation as a normal lifecycle step not an error. It encodes operational knowledge that the UCP spec alone doesn't cover.
Shopify proved something important: protocol + agent instructions is stronger than protocol alone.
We build UCPReady — a WooCommerce plugin that implements the full UCP stack. And until last week, WooCommerce merchants running it had the protocol layer but not the instruction layer. No file telling agents how to work with their store. No guidance surface beyond /.well-known/ucp.
We shipped that this week.
The gap Shopify exposed
UCP standardizes the transport and schema. Every conformant store — Shopify, WooCommerce, BigCommerce, custom — exposes the same protocol surface. That's the point.
But Benji Fisher at UCP Checker wrote a sharp breakdown of what Shopify's CLI actually does, and one line stuck:
It can buy from any UCP-compliant store on any platform. It can only find Shopify stores.
The discovery layer defaults to catalog.shopify.com. The transaction layer is pure, open UCP. Shopify owns the index; the protocol is shared.
That asymmetry matters. But there's a second asymmetry that's just as real: Shopify agents arrive at a store already knowing how to behave. Non-Shopify agents arrive and have to figure it out from the profile alone.
A SKILL.md bundled in a CLI is one way to solve that. But it only works for agents that installed that specific CLI. The more durable fix is publishing the operating manual on the merchant's own domain — discoverable by any agent, from any platform, the moment it finds the store.
What we shipped: the Agent Guidance Layer
UCPReady now auto-generates two public documents on every merchant site:
/agents.md — human and agent readable Markdown. Tells any agent:
- Start with
/.well-known/ucp, use the advertised endpoint, never assume/api/ucp/mcp - What capabilities this specific merchant supports (cart, checkout, orders, returns, identity linking, embedded checkout)
- How to sequence checkout operations
- What payment handlers are available
- When to stop and escalate to the buyer
- Whether return flows include retention/keep-offer decisions (KeepCard integration)
/llms-full.txt — compact, machine-oriented. Covers protocol version, supported transports (REST, MCP, Embedded), capability inventory, and explicit safe probing guidance.
Both are generated dynamically from live merchant capabilities. If cart is disabled, the cart section doesn't appear. If KeepCard isn't active, no keep-offer guidance is included. Nothing is hardcoded; nothing claims unsupported behavior.
Here's what it looks like for a real production store — House of Parfum, currently #1 on ucpchecker.com with a perfect 100/100 score:
# House of Parfum
This merchant uses UCPReady and publishes UCP-compatible shopping
endpoints for AI agents.
## Merchant Profile
- **Store:** House of Parfum
- **Description:** Van iconische parfums tot luxe skincare
- **Discovery:** https://houseofparfum.nl/.well-known/ucp
- **Shop:** https://houseofparfum.nl/shop/
## Start Here
- Discover this merchant from https://houseofparfum.nl/.well-known/ucp
- Use the service endpoint advertised in the profile.
- Do not assume /api/ucp/mcp.
- MCP endpoint: https://houseofparfum.nl/wp-json/ucpready/v1/mcp
- REST endpoint: https://houseofparfum.nl/wp-json/ucpready/v1
## Supported Capabilities
- Catalog browsing and product lookup
- Cart creation and update
- Checkout creation, update, and completion
- Order lookup
- Return flows
- Identity linking
- Embedded checkout
## Checkout Guidance
- Create checkout first, then update it with buyer, fulfillment,
and payment data as needed.
- Read payment handlers from the live checkout response.
- If checkout reaches a completed state, use the final order as
the source of truth for totals and discounts.
- Treat coupon failures as recoverable checkout issues, not as
silent success.
## Returns Guidance
- This merchant supports return tooling.
- Return flows may include optional retention / keep-offer decisions
when enabled by merchant integrations.
- Ask the buyer before accepting or declining any keep-offer outcome.
## Payment Handlers
- dev.ucp.delegate_payment
- com.terrawallet.store_credit
## Escalate to the Buyer When
- variant or quantity selection is ambiguous
- identity linking is required
- coupon validation fails
- the merchant response requires approval or additional buyer action
You can hit it live: houseofparfum.nl/agents.md
Why this matters more than it might look
When Google announced Universal Cart at I/O 2026, the commerce director described UCP as "a common language that lets agents reach businesses securely and seamlessly." Universal Cart, AI Mode checkout, YouTube Shopping — they all run on it.
The stores that benefit are the ones agents can actually work with reliably. A broken or ambiguous implementation gets abandoned. A store with a valid manifest, correct capability declarations, and clear operating guidance gets completed transactions.
Shopify's approach is to bundle instructions in a CLI. That works for Shopify's ecosystem. Our approach is to publish instructions on the merchant's own domain, discoverable by any agent from any platform.
The instruction layer is not optional anymore. It's part of what makes a store agent-ready.
That's the WooCommerce answer to what Shopify bundled in their CLI — platform-level agent guidance, open and accessible, not locked to a single discovery surface.
If you're running WooCommerce and want to see where your store stands: ucpchecker.com
UCPReady is at zologic.nl/ucpready.
Top comments (1)
Thanks to @benjifisher for the sharp breakdown of the Shopify UCP CLI — the observation about the two layers (transaction vs discovery) and the SKILL.md angle was the direct trigger for this. Good signal.