UCP Skill — Universal Commerce Protocol Implementation
Core Principles
- Edge runtime is NOT USED — Only Node.js (default) or Bun (opt-in) runtimes
- Interactive error handling — When ambiguous, ask the user how to proceed
- Config-driven — All decisions persist in
ucp.config.json
- Spec-grounded — All implementations reference the canonical UCP specification
- Next.js conventions — Follow App Router patterns for code organization
- Deep analysis — Use AST parsing and data flow tracing for gap detection
Spec Repository Handling
Location Priority
Check in this order:
./ucp/ — User's local copy (use as-is)./.ucp-spec/ — Previously cloned spec (update it)- Neither exists — Clone fresh
Clone Procedure
When cloning is needed:
git clone --depth 1 https://github.com/Universal-Commerce-Protocol/ucp.git .ucp-spec
If HTTPS fails, try SSH:
git clone --depth 1 [email protected]:Universal-Commerce-Protocol/ucp.git .ucp-spec
Update Procedure
When ./.ucp-spec/ exists:
cd .ucp-spec && git pull && cd ..
Gitignore Management
After cloning, ensure .ucp-spec/ is in .gitignore:
- Read
.gitignore if it exists
- Check if
.ucp-spec/ or .ucp-spec is already listed
- If not, append
.ucp-spec/ on a new line
Spec File Locations (read on demand)
docs/specification/overview.md
docs/specification/checkout.md
docs/specification/checkout-rest.md
docs/specification/checkout-mcp.md
docs/specification/checkout-a2a.md
docs/specification/embedded-checkout.md
docs/specification/order.md
docs/specification/fulfillment.md
docs/specification/discount.md
docs/specification/buyer-consent.md
docs/specification/identity-linking.md
docs/specification/ap2-mandates.md
docs/specification/payment-handler-guide.md
docs/specification/tokenization-guide.md
spec/services/shopping/rest.openapi.json
spec/services/shopping/mcp.openrpc.json
spec/services/shopping/embedded.openrpc.json
spec/handlers/tokenization/openapi.json
spec/schemas/shopping/*
spec/discovery/profile_schema.json
Configuration File
Location
./ucp.config.json at project root
Schema
{
"$schema": "./ucp.config.schema.json",
"ucp_version": "2026-01-11",
"roles": ["business"],
"runtime": "nodejs",
"capabilities": {
"core": ["dev.ucp.shopping.checkout"],
"extensions": []
},
"transports": ["rest"],
"transport_priority": ["rest", "mcp", "a2a", "embedded"],
"payment_handlers": [],
"features": {
"ap2_mandates": false,
"identity_linking": false,
"multi_destination_fulfillment": false
},
"domain": "",
"existing_apis": {},
"policy_urls": {
"privacy": "",
"terms": "",
"refunds": "",
"shipping": ""
},
"scaffold_depth": "full",
"generated_files": [],
"answers": {},
"deployment": {
"platform": "vercel",
"region": "iad1",
"mcp": {
"enabled": false,
"max_duration": 60
}
}
}
Field Descriptions
| Field |
Type |
Description |
ucp_version |
string |
UCP spec version (date-based) |
roles |
string[] |
One or more of: business, platform, payment_provider, host_embedded |
runtime |
string |
nodejs (default) or bun |
capabilities.core |
string[] |
Required capabilities to implement |
capabilities.extensions |
string[] |
Optional extensions to implement |
transports |
string[] |
Enabled transports: rest, mcp, a2a, embedded |
transport_priority |
string[] |
Order to implement transports |
payment_handlers |
string[] |
Payment handler IDs to support |
features.ap2_mandates |
boolean |
Enable AP2 mandate signing |
features.identity_linking |
boolean |
Enable OAuth identity linking |
features.multi_destination_fulfillment |
boolean |
Enable multi-destination shipping |
domain |
string |
Business domain for /.well-known/ucp |
existing_apis |
object |
Map of existing API endpoints to analyze |
policy_urls |
object |
URLs for privacy, terms, refunds, shipping policies |
scaffold_depth |
string |
types | scaffolding | full |
generated_files |
string[] |
Files created by scaffold (for tracking) |
answers |
object |
Raw answers to qualifying questions |
Sub-command: (no argument)
Trigger
User runs /ucp with no sub-command
Behavior
Display help listing all available sub-commands:
UCP Skill — Universal Commerce Protocol Implementation
Available commands:
/ucp init — Initialize UCP in this project (clone spec, create config)
/ucp consult — Full consultation: answer qualifying questions, build roadmap
/ucp plan — Generate detailed implementation plan
/ucp gaps — Analyze existing code against UCP requirements
/ucp scaffold — Generate full working UCP implementation
/ucp validate — Validate implementation against UCP schemas
/ucp profile — Generate /.well-known/ucp discovery profile
/ucp test — Generate unit tests for UCP handlers
/ucp docs — Generate internal documentation
Typical workflow:
/ucp init → /ucp consult → /ucp plan → /ucp scaffold → /ucp profile → /ucp test → /ucp validate
Configuration: ./ucp.config.json
Spec location: ./ucp/ or ./.ucp-spec/
Sub-command: init
Trigger
User runs /ucp init
Purpose
Bootstrap UCP in a project: clone spec, create config, ask essential questions.
Procedure
Step 1: Check/Clone Spec Repository
- Check if
./ucp/ exists
- If yes: "Found local UCP spec at ./ucp/"
- If not, check if
./.ucp-spec/ exists
- If yes: Run
git pull to update
- If no: Clone the repo (see Spec Repository Handling)
- After cloning, add
.ucp-spec/ to .gitignore
Step 2: Check for Existing Config
- Check if
./ucp.config.json exists
- If yes, ask: "Config file exists. Overwrite, merge, or abort?"
- Overwrite: Delete and create fresh
- Merge: Keep existing values as defaults
- Abort: Stop init
Step 3: Ask Essential Questions (4 questions)
Q1: What role(s) are you implementing?
- Business (merchant of record)
- Platform (consumer app or agent)
- Payment credential provider
- Host embedding checkout
- Multiple (specify)
If user selects multiple roles, WARN:
"Implementing multiple roles is unusual. This is typically for marketplace/aggregator scenarios. Are you sure?"
Q2: What runtime will you use?
- Node.js (recommended, stable)
- Bun (opt-in, experimental)
NOTE: If user mentions Edge, respond:
"Edge runtime is not supported for UCP implementations. Please choose Node.js or Bun."
Q3: What is your business domain?
- The domain that will host
/.well-known/ucp
- Example:
shop.example.com
Q4: Which transports do you need at launch?
- REST (recommended baseline)
- MCP (Model Context Protocol)
- A2A (Agent-to-Agent)
- Embedded (iframe checkout)
Step 4: Create Config File
Create ./ucp.config.json with:
- Answers from essential questions
- Sensible defaults for other fields
ucp_version set to latest from spec
Step 5: Output Ready Message
UCP initialized successfully!
Config: ./ucp.config.json
Spec: ./.ucp-spec/ (or ./ucp/)
Role: {role}
Domain: {domain}
Next steps:
/ucp consult — Complete full consultation (recommended)
/ucp plan — Skip to implementation planning
/ucp gaps — Analyze existing code first
Sub-command: consult
Trigger
User runs /ucp consult
Purpose
Walk through all 12 qualifying questions, update config, produce implementation roadmap.
Prerequisites
- Config file must exist (run
/ucp init first)
- Spec must be available
Procedure
Step 1: Load Existing Config
Read ./ucp.config.json and use existing answers as defaults.
Step 2: Walk Through 12 Qualifying Questions
Ask each question. If already answered in config, show current value and ask to confirm or change.
Q1: Are we implementing the business side, the platform side, or both?
- Map to
roles in config
- If both/multiple, warn about unusual scenario
Q2: Which UCP version and which capabilities/extensions are in scope?
- Read available versions from spec
- Present capability options:
- Core:
dev.ucp.shopping.checkout (required)
- Extensions:
dev.ucp.shopping.fulfillmentdev.ucp.shopping.discountdev.ucp.shopping.buyer_consentdev.ucp.shopping.ap2_mandatedev.ucp.shopping.orderdev.ucp.common.identity_linking
Q3: Which payment handlers do we need?
- Wallets (Apple Pay, Google Pay)
- PSP tokenization (Stripe, Adyen, etc.)
- Custom handler
- None yet (decide later)
Q4: Do we need AP2 mandates and signing key infrastructure?
- Yes → set
features.ap2_mandates: true
- No → set
features.ap2_mandates: false
- If yes, explain: "You'll need to provide JWS signing keys (ES256 recommended)"
Q5: Do we need fulfillment options and multi-group/multi-destination support?
- No fulfillment needed
- Single destination only
- Multi-destination support → set
features.multi_destination_fulfillment: true
Q6: Do we need discounts, buyer consent capture, or identity linking?
- Discounts → add
dev.ucp.shopping.discount to extensions
- Buyer consent → add
dev.ucp.shopping.buyer_consent to extensions
- Identity linking → add
dev.ucp.common.identity_linking, set features.identity_linking: true
Q7: What are the existing checkout and order APIs we should map to UCP?
- Ask for existing endpoint paths
- Store in
existing_apis object
- Examples:
/api/checkout, /api/cart, /api/orders
Q8: What are the required policy URLs?
- Privacy policy URL
- Terms of service URL
- Refund policy URL
- Shipping policy URL
- Store in
policy_urls object
Q9: What authentication model is required for checkout endpoints?
- None (anonymous checkout)
- API key
- OAuth 2.0
- Session-based
- Store in
answers.authentication_model
Q10: Who will receive order webhooks and what event cadence is required?
- Webhook URL for order events
- Event types needed:
order.created, order.updated, order.fulfilled, order.canceled
- Store in
answers.webhook_config
Q11: Do we need to support MCP, A2A, or embedded checkout at launch?
- Confirm/update
transports array
- Set
transport_priority order
Q12: What is the business domain that will host /.well-known/ucp?
- Confirm/update
domain field
Step 3: Update Config
Write all answers to ./ucp.config.json
Step 4: Generate Implementation Roadmap
Based on answers, produce a roadmap:
UCP Implementation Roadmap
==========================
Role: Business (merchant)
Version: 2026-01-11
Domain: shop.example.com
Capabilities to implement:
✓ dev.ucp.shopping.checkout (core)
✓ dev.ucp.shopping.fulfillment
✓ dev.ucp.shopping.discount
○ dev.ucp.shopping.order
Transports (in order):
1. REST
2. MCP
Payment handlers:
- Stripe tokenization
Key implementation tasks:
1. Create /.well-known/ucp discovery profile
2. Implement checkout session endpoints (create, get, update, complete)
3. Implement fulfillment options logic
