UCP Shopper Skill

A lightweight buyer-agent skill for using merchant-published UCP to buy, order, book, reserve, schedule, or subscribe to products and services.

It is generic by design. It is not tied to one merchant, platform, payment provider, or protocol implementer.

Install

Fresh install from npm:

npm install --foreground-scripts ucp-shopper-skill@latest

On a first run, npm automatically installs the local agent skill and launches UCP Shopper setup. The --foreground-scripts flag keeps npm from hiding the interactive setup wizard. Setup walks through wallet approval, an arrow-key payment-method menu, saved-method review, and the final purchase handoff. Payment methods are additive and skippable: add VGS card/network token, add Link, or finish and complete a merchant-advertised provider flow later. PayPal, Google Pay, Apple Pay, and Stripe rails appear at checkout only when the merchant advertises them. Setup never asks for raw card number, PAN, CVC, or CVV; card setup must happen inside provider-owned hosted or tokenization UI.

Readiness is layered:

• Passkey wallet: ready means the local native helper is installed/trusted/enrolled and can show a macOS user-presence prompt. It is not proof that a card, Link account, PayPal account, or other buyer payment method was added.
• Provider readiness means a merchant rail or local tool may be usable when a merchant advertises that handler through UCP. It is not buyer payment setup by itself.
• Buyer payment methods: configured is only set after setup verifies a saved/tokenized buyer payment method or receives a safe hosted setup receipt.

VGS card/network-token setup uses a hosted-browser callback contract. Set UCP_SHOPPER_CARD_SETUP_URL to the VGS setup page and leave UCP_SHOPPER_CARD_SETUP_PROVIDER=vgs_card_network_token as the default. The wizard opens that URL with ucp_callback_url, ucp_setup_nonce, ucp_card_setup_provider, and ucp_receipt_format query parameters. The hosted page must POST a safe receipt back to the local callback with a VGS Card Object reference such as vgs_card_id or credential_reference. The receipt may include brand, bin, last4, expiry, capabilities, and network-token readiness, but it must never include PAN, CVC, CVV, DPAN, cryptogram, or full card number. UCP Shopper marks the VGS card method saved after that safe receipt is received, even if network-token provisioning is still pending provider enablement. The preserved CyberSource/Visa fallback uses UCP_SHOPPER_CARD_SETUP_PROVIDER=cybersource_visa_card_token and is not the default.

After VGS enables network-token provisioning for the account/vault, re-check the saved VGS Card Object without asking the buyer for card data:

UCP_SHOPPER_CARD_SETUP_URL=http://localhost:8787 npx -y ucp-shopper-skill vgs-readiness

The command calls the configured VGS setup helper for the saved vgs_card_id, updates local state to vgs_network_token_ready when a real network token is available, and otherwise leaves the card in vgs_network_token_provider_pending. It does not request or persist a checkout cryptogram; the setup-side cryptogram status stays not_requested_until_checkout until the backend creates a fresh cryptogram after buyer approval for a specific checkout.

Provider rail readiness in the current package is merchant-rail capability detection. PayPal, Google Pay, Apple Pay, and Stripe are not counted as saved buyer payment methods just because the rail is available. At checkout, UCP Shopper can use one of those rails only when the merchant advertises it, and the buyer may still need wallet approval, provider login, card/network-token setup, or another provider-owned credential flow.

Link setup is always offered as its own step. If link-cli is already installed, setup runs link-cli auth login --client-name "UCP Shopper"; otherwise it runs the same command through npx -y @stripe/link-cli. Link may open a browser or ask for login, OTP, or passkey approval. UCP Shopper does not run Link's demo checkout flows during first-run setup. After login, setup verifies saved Link payment methods with payment-methods list --format json; if it cannot verify a saved method, Link remains unverified instead of pretending buyer payment setup is complete.

Native wallet approval requires a macOS helper app because Secure Enclave, Keychain, and Touch ID approval are OS-native operations. Public distribution still requires a Developer ID signed and notarized helper. Until that release artifact exists, clean-user dogfood tests must stage the local development helper explicitly; normal public users should not see those development paths.

If you need to install the npm package without touching local agent state, opt out explicitly:

UCP_SHOPPER_SKIP_POSTINSTALL=1 npm install ucp-shopper-skill@latest

You can rerun setup at any time:

npx -y ucp-shopper-skill setup

To simulate a first-time user again on the same macOS account:

npx -y ucp-shopper-skill reset --yes --include-link-state
npm install --foreground-scripts ucp-shopper-skill@latest

For the cleanest first-user test, create a new macOS user. The reset command removes UCP-owned home-directory state, and --include-link-state moves common Link CLI preference folders aside. It intentionally does not erase unrelated Keychain entries or uninstall a separately installed native helper app.

For local dogfood testing before Apple's signed/notarized helper distribution is available, use a local source repo to install the development helper for that macOS user:

npx -y ucp-shopper-skill setup \
  --install-dev-wallet-helper \
  --dev-helper-root "/path/to/source-repo"

If you already built the helper from your normal macOS account and are testing under a clean macOS user, pass the prebuilt app instead of rebuilding with Xcode in that user:

mkdir -p ~/.ucp-shopper
cat > ~/.ucp-shopper/setup.env <<'EOF'
UCP_SHOPPER_INSTALL_DEV_WALLET_HELPER=1
UCP_SHOPPER_DEV_HELPER_ROOT="/path/to/source-repo"
UCP_SHOPPER_DEV_HELPER_APP="/path/to/source-repo/hexagon-pay/build/SecureEnclaveProofDerived/Build/Products/Debug/SecureEnclaveProofApp.app"
EOF
npm install --foreground-scripts ucp-shopper-skill@latest

That creates a per-user ~/.ucp-shopper/dev-helper-trust marker so the npm wallet bridge can use the Apple Development-signed helper. This is only for local testing; public distribution still requires the Developer ID signed and notarized helper.

Then start Codex, Claude Code, or another compatible local agent normally and ask for what you want to buy.

For an isolated package install test that does not touch your real agent homes:

export UCP_TEST_HOME="$(mktemp -d /tmp/ucp-shopper-fresh.XXXXXX)"
HOME="$UCP_TEST_HOME" \
CODEX_HOME="$UCP_TEST_HOME/.codex" \
CLAUDE_HOME="$UCP_TEST_HOME/.claude" \
AGENTS_HOME="$UCP_TEST_HOME/.agents" \
npm install --foreground-scripts ucp-shopper-skill@latest

HOME="$UCP_TEST_HOME" \
CODEX_HOME="$UCP_TEST_HOME/.codex" \
codex

From this source directory:

./install.sh

The installer refuses to overwrite an existing ucp-shopper skill or command unless it was previously installed by this package. Use ./install.sh --force only when you intentionally want to replace an existing local copy.

The installer copies the same skill into the common local agent locations:

• ~/.claude/skills/ucp-shopper
• ~/.agents/skills/ucp-shopper
• ~/.codex/skills/ucp-shopper

It also installs a small explicit command at:

• ~/.claude/commands/ucp-shop.md
• ~/.agents/commands/ucp-shop.md
• ~/.codex/commands/ucp-shop.md

For Codex installs, CODEX_HOME is respected when set.

Use

After install, ask naturally:

Buy me the golden serum from that skincare store.
Book me a morning train ticket to San Jose.
Reserve a table for two tomorrow night.

The skill tells the agent to check merchant UCP surfaces first when a merchant/provider is known or can be inferred. If the user gives a merchant name without a domain, the agent should resolve the official merchant-owned domain, then probe UCP before generic product search or manual checkout. If UCP is unavailable, the agent should fall back to normal safe web shopping behavior and say that UCP was not found.

For payment, the skill stays generic but includes provider playbooks. The agent should inspect the merchant's advertised payment or credential handlers, offer to help the buyer through the matching provider flow after consent, use a matching local wallet/CLI/MCP/tool when available, and involve the buyer only for explicit auth or approval steps. If shipping, contact, schedule, or option details are still missing, the agent should ask for those details while still naming the assisted provider flow it can run next. Payment-boundary responses should either offer to check/run the matching local provider capability after consent or say that capability was checked and is unavailable. After the buyer confirms the displayed total and selected payment path, the agent should keep going through setup/auth/approval/token creation and UCP completion until the merchant confirms the transaction or a concrete provider/tool blocker prevents it. Placeholder tokens in merchant docs are provider artifact shapes, not something the buyer should be asked to manually create or paste unless no matching local capability exists and the buyer explicitly chooses that fallback.

For Google Pay or AP2-style wallet approval, the skill treats a merchant-authorized approval URL as valid only when it is advertised by UCP for the current checkout. The agent should ask the buyer whether to proceed with the displayed total, open or present that approval URL after consent, let the buyer approve in the browser/wallet sheet, and verify the merchant order. The buyer should never be asked to paste a Google Pay token.

For first-time setup, the skill should offer VGS card/network-token enrollment as the recommended saved card path, Stripe Link for Link/SPT merchants, and concrete alternative capability families when relevant: Google Pay/AP2, Visa Intelligent Commerce tokenized credentials, Mastercard Agent Pay agentic tokens, AgentCard or other virtual-card providers, PayPal, Apple Pay, bank/open-banking authorization, stablecoin/x402, BNPL, gift card, loyalty, account credit, or invoice/net terms. At checkout, the agent must filter choices to the handlers the merchant actually advertises through UCP. Concrete VGS, Stripe Link, PayPal, wallet, and passkey helper playbooks are included, but the core skill is still provider-neutral.

For hosts that support slash commands:

/ucp-shop buy the golden serum from example-merchant.com

Capability Doctor

Before a first payment attempt, run the local doctor from npm:

npx -y ucp-shopper-skill doctor

For machine-readable output:

npx -y ucp-shopper-skill doctor --json

From this source directory:

./tools/doctor.sh

For machine-readable output:

./tools/doctor.sh --json

To enroll the local passkey-gated wallet helper when it is installed but not ready, run from a visible local user session:

./tools/doctor.sh --enroll-wallet

The doctor checks whether the skill is installed, whether a passkey-gated local wallet helper is available and enrolled, whether a Link-compatible CLI is present, and whether PayPal/network-token environment variables are present. It never prints secret values. These checks only prove local capability presence; at checkout, the agent still filters to the payment or credential handlers advertised by the merchant's UCP profile for the exact unpaid draft.

The npm installer also installs a local wallet bridge:

~/.ucp-shopper/bin/hexagon-wallet

That bridge does not include or fake the native macOS helper app. It only talks to a trusted helper installed in the package's default per-user Application Support path. Until that signed helper app is installed, doctor reports the wallet bridge as setup-required rather than ready.

Validate

./tests/validate-package.sh

Uninstall

./uninstall.sh