Skip to content

Skill: shop-via-ucp

Drop this skill into an agent's skills directory to act as a shopper's agent against a store's UCP/MCP commerce backend, instead of hand-rolling the tool-call sequence and its guardrails yourself. It's for completing a purchase. For lookups with no purchase in mind (what a store sells, a price, whether it supports automated buying), use the read-only browse-via-ucp skill.

Shopping via UCP/MCP

You are acting as a shopper's agent. The user wants something bought from an online store. Talk to that store's commerce backend over MCP (tool calls) using UCP (Universal Commerce Protocol) as the commerce-capability layer.

If the user only wants to know what a store sells, what something costs there, whether it's in stock or whether the store supports automated buying, with no purchase in mind, use the read-only browse-via-ucp skill instead. It never creates a cart or checkout.

If you're running inside Claude Code (or another host with the plugin system), prefer the buy plugin instead of this skill. It covers everything below plus the parts this file doesn't: finding stores with no URL in hand (portage find, a local store index built from your own bookmarks/history or the repo's published known-stores list), the setup wizard, hand-off to your own browser or a dedicated Portage profile, and hand-off-only retailers (Amazon and friends) that this skill's raw guardrail 1 would otherwise just call a dead end. This file stays for hosts with no plugin system, where dropping one SKILL.md into an agent's skills directory is the only option.

If the portage-ucp-client Ruby gem is available in this environment (check the project's Gemfile/gemspec, or run gem list portage-ucp-client), prefer it — it enforces every guardrail below in code. Otherwise, shell out to the portage CLI if it's installed (portage buy <url> --query "..." [--qty N] [--payment-token TOKEN] [--yes] [--dry-run] [--json]), which runs this same flow end to end including the native-UCP-then-adapter-fallback discovery logic. With --json, branch on the report's outcome rather than its message: only purchased means bought. Every hand-off outcome (requires_escalation, policy_blocked, low_confidence, no_payment_token, permission_denied, checkout_mismatch) comes with a checkout_url for the human, and checkout_mismatch always means the CLI stopped before payment (guardrail 4), and decisions: says why a gate held it: each verdict's reason is a string naming the cause, or null when that gate passed. portage history --json lists past checkouts by the same outcome, so check it before buying something twice. With portage-ucp-client, make the same calls through portage-ucp-decision (OfferRanking, EscalationPolicy, PolicyCheck, ConfidenceGate). If neither is available, make the raw MCP tool calls yourself, following the sequence below exactly.

A store with no UCP manifest isn't necessarily a dead end if you're driving a browser. When you (or the process calling portage-ucp-client/portage buy) hold a browser already navigated to the store's page, portage-ucp-webmcp's outbound transport can call whatever WebMCP tools that page itself registers — some Shopify storefronts do this today, most other platforms don't yet. It's tried after native UCP discovery finds nothing and before falling back to a platform adapter, and it never completes payment: the flow always ends by handing the shopper off to the store's own checkout page in that same browser, exactly like a requires_escalation link. A shopper who wants that hand-off page's contact and shipping fields pre-filled before they get there can opt into it — with portage buy, that's the --autofill flag or the PORTAGE_WEBMCP_AUTOFILL=approve setting — but even opted in, it only ever fills contact/shipping and the cheapest shipping rate, prompts the shopper to approve the exact fields first, and never touches anything payment-related.

Guardrails — apply these every time, no exceptions

  1. Discover the manifest before assuming any credential path. Fetch <store-url>/.well-known/ucp first. If it doesn't exist, or doesn't advertise checkout, do not fall back to scraping the site, logging in as the shopper, or using anyone's stored credentials to buy on their behalf. Say plainly that automated purchase isn't available there. The only legitimate fallback is a platform adapter this process already has real credentials for (i.e. your own store, or one you're integrated with) — never a stranger's store.
  2. Branch on requires_escalation, don't treat it as an error. A checkout response with status: "requires_escalation" is normal data carrying a links array — surface that link to the human and stop. Don't retry the call or report it as a failure.
  3. Never pass anything resembling a raw card number as payment_token. It must be a single-use, tokenized credential from a payment handler exchange. If you're making raw tool calls (not through portage-ucp-client, which enforces this via PaymentTokenGuard), check the string yourself before sending it — reject anything that's all digits, 12-19 characters, and Luhn-valid.
  4. Never pay for a checkout that doesn't match what the user approved. Before complete_checkout, compare the checkout the store returned with what the user said yes to: the same items (product or variant ids), the same quantity of each, the same unit prices, the same currency and the same total. If anything differs, or the store dropped or added a line, stop. Don't call complete_checkout, and don't adjust the checkout to make it match. Show the user what differs, and if they still want it, build a fresh checkout and ask them to approve its exact total again. There is no exception for a small difference. portage buy enforces this in code (checkout_mismatch).

Tool-call sequence (when making raw MCP calls)

  1. GET <url>/.well-known/ucp → read capabilities and services (the services entry with "transport": "mcp" has the actual endpoint to connect to).
  2. tools/call search_catalog { "query": "...", "limit": 5 } → pick the matching product.
  3. tools/call get_product { "product_id": "..." } → resolve variant-level detail if needed.
  4. tools/call create_checkout { "line_items": [...], "idempotency_key": "<generate one>" } → check status; requires_escalation triggers guardrail 2. Check the checkout against the request (guardrail 4), then confirm the exact total with the shopper before proceeding unless they've pre-authorized it.
  5. tools/call complete_checkout { "checkout_id": "...", "payment_token": "...", "idempotency_key": "<fresh>" } → guardrails 3 and 4 apply here. If the store can return the checkout again (get_checkout), re-read it just before this call and stop on any difference from what the user approved.
  6. tools/call get_order { "order_id": "..." } if an order id is available, to report back tracking/fulfillment info.

Every catalog, cart and checkout call should carry a context (address_country, and currency/address_region/postal_code/language when known). It looks optional and isn't: a store resolves which market — and so which inventory — the call is scoped to from it, and a cart built without one comes back with no line items and a merchandise_out_of_stock warning for a product the same store's search_catalog just reported as available.

Full walkthrough with example payloads: ../../docs/walkthrough.md. Troubleshooting a real external UCP store (missing PORTAGE_AGENT_PROFILE, a profile URL the store can't fetch, or Tool not found on every call once the profile's attached — which means the profile declares capability ids the store's registry doesn't have, not that you lack access): ../../docs/ucp-tool-gating-investigation.md.