Agentic Commerce Skills

A curated, framework-organized library of Agent Skills for building commerce agents on top of Google's Universal Commerce Protocol (UCP) — compatible with AP2 (Agent Payments Protocol), A2A (Agent2Agent), and MCP (Model Context Protocol).

基于 Google 通用商业协议 (UCP) 框架组织的一套 Agent Skills 库，记录"Agent + 商业" 落地能力。兼容 AP2 / A2A / MCP。每个 skill 都是可被 Claude Code / Agent 直接加载调用的 SKILL.md。

---

Why this repo / 为什么有这个仓库

Agentic commerce is moving from "an agent that describes products" to "an agent that transacts" — searching catalogs, building carts, linking identity, completing checkout with cryptographic proof of user consent, and managing orders after the sale. Google's Universal Commerce Protocol (UCP) is emerging as the common language for that across agents, merchants, and payment providers.

This repo turns UCP's lifecycle into reusable, executable agent skills. Instead of one giant integration doc, each capability is a self-contained SKILL.md an agent can load on demand.

商业 Agent 正从"能介绍商品"走向"能完成交易"：搜目录、建购物车、绑身份、带用户授权密码学 证明地结算、售后管订单。Google UCP 正在成为打通 Agent / 商家 / 支付方的通用语言。本仓库 把 UCP 全旅程拆成可复用、可执行的 agent skill——按需加载，而不是一份大而全的集成文档。

---

The framework: UCP capabilities → skills / 框架：UCP 能力映射到 skills

Each skill maps to a real UCP capability identifier (verified against the UCP spec), not a marketing label. Two important truths from the spec: the cart is not a separate capability — it is the line_items of a checkout session, and core UCP has no agent-facing catalog "search" endpoint — discovery is product-feed/index based.

每个 skill 对应一个真实的 UCP 能力标识符(已对照 spec 核对)。两点重要事实:购物车不是独立 能力——它就是 checkout session 的 line_items;核心 UCP 没有给 agent 调的目录"搜索"端点—— 发现走商品 feed/索引。

Capability ID / 能力标识符	Stage / 阶段	Skill
(Merchant Center feed + /.well-known/ucp)	Discovery / 发现	ucp-product-discovery
dev.ucp.common.identity_linking	Identity / 身份	ucp-identity-linking
dev.ucp.shopping.checkout (incl. cart)	Checkout / 结算	ucp-checkout-session
dev.ucp.shopping.fulfillment	Checkout / 履约	ucp-fulfillment
dev.ucp.shopping.discount	Checkout / 折扣	ucp-discount
AP2 mandates (VDC) + UCP Payment Token Exchange	Payment / 支付	ap2-payment-mandate
dev.ucp.shopping.order	Orders / 售后	ucp-order-management

Discovery ──▶ ┌─────────────── Checkout session (dev.ucp.shopping.checkout) ───────────────┐ ──▶ Orders
 (feed)       │  line_items(cart) · fulfillment · discount · identity · AP2 payment proof   │   (webhooks)
  发现 feed    └────────────────────────────────────────────────────────────────────────────┘    订单售后

See the full primer: docs/ucp-primer.md.

---

Runnable example: a LangGraph shopping agent / 可运行示例：LangGraph 购物 Agent

Want to see the whole journey transact, not just read the specs? examples/shopping-agent is a self-contained, runnable demo that wires all 7 skills into a working agent:

• a LangGraph agent that loads every SKILL.md into its prompt and backs each skill with a tool that calls a real UCP REST endpoint;
• a mock UCP merchant (FastAPI) implementing /.well-known/ucp, a product feed, the five /checkout-sessions endpoints, AP2 Ed25519 payment-mandate verification, and order webhooks (created → shipped → delivered);
• a React chat UI with a live inspector showing the checkout session, authoritative totals, the signed AP2 payment, and order tracking.

cd examples/shopping-agent && ./run.sh   # backend :8000 + frontend :5173

It is driven by any OpenAI-compatible LLM (the demo uses BigModel / 智谱 GLM). See the example's README for the skill→tool mapping and setup.

这是一个可直接运行的端到端示例：把全部 7 个 skill 接成一个 LangGraph Agent + 内置 mock UCP 商家(FastAPI,含 AP2 Ed25519 验签与订单 webhook)+ React 对话前端。./run.sh 即起。

---

How to use these skills / 如何使用

With Claude Code / Agent SDK

Each skill is a directory containing a SKILL.md with YAML frontmatter (name, description). Drop the skill folder where your agent discovers skills, or point your loader at this repo.

# Clone and copy a skill into your agent's skills directory
git clone https://github.com/fxp/agentic-commerce-skills.git
cp -r agentic-commerce-skills/skills/03-checkout/ucp-checkout-session ~/.claude/skills/

When a user asks the agent to do something matching a skill's description, the agent loads that SKILL.md and follows its workflow.

每个 skill 是一个目录，内含带 YAML frontmatter 的 SKILL.md。把 skill 目录放到你的 agent 能发现 skill 的位置即可；当用户请求匹配该 skill 的 description 时，agent 会加载并执行。

As reference / 当作参考

Even without an agent runtime, each SKILL.md is a concise, implementable spec for that UCP capability — REST/JSON-RPC shapes, required objects, edge cases, and a worked example.

---

Repository layout / 仓库结构

agentic-commerce-skills/
├── README.md                 # this file / 本文件
├── SKILLS.md                 # machine-friendly skill index / skill 索引
├── CONTRIBUTING.md           # how to add a skill / 如何贡献 skill
├── LICENSE
├── docs/
│   └── ucp-primer.md         # UCP / AP2 / A2A / MCP primer / 协议入门
├── skills/
│   ├── 01-discovery/ucp-product-discovery/SKILL.md
│   ├── 02-identity/ucp-identity-linking/SKILL.md
│   ├── 03-checkout/ucp-checkout-session/SKILL.md     # dev.ucp.shopping.checkout (cart lives here)
│   ├── 03-checkout/ucp-fulfillment/SKILL.md          # dev.ucp.shopping.fulfillment
│   ├── 03-checkout/ucp-discount/SKILL.md             # dev.ucp.shopping.discount
│   ├── 03-checkout/ap2-payment-mandate/SKILL.md      # AP2 mandates + UCP payment
│   └── 04-orders/ucp-order-management/SKILL.md       # dev.ucp.shopping.order
└── examples/
    └── shopping-agent/       # runnable: LangGraph agent + mock UCP merchant + React UI
        ├── backend/          # FastAPI: agent (/api/chat) + UCP merchant (/ucp/v1)
        └── frontend/         # Vite + React chat UI & live commerce-state inspector

---

Related & reference implementations / 相关项目与落地实现

These skills describe the protocol shape. For a real, hardware-backed UCP implementation:

• fxp/vending-protocol — battle-tested protocols
  • Claude skills for vending machines / unmanned retail. Its adapters/ucp/ exposes a physical WM800 serial vending machine as a UCP REST service (with a hardware-free mock server + 71 protocol tests). Its references/mapping.md is a candid UCP compliance-gap analysis against the exact fields these skills document — /checkout-sessions (vs /v1/checkout), status: completed, required currency / totals, RFC 9421 signatures, UCP-Agent / Idempotency-Key. A great real-world pitfalls checklist.

这些 skill 描述协议形态;真实硬件落地见 vending-protocol 的 UCP 适配器——把实体 WM800 串口 贩卖机暴露成 UCP REST(带无硬件 mock + 71 个测试)。其 mapping.md 是对照本库所记同一批字段的 合规差距分析,可直接当"实现避坑清单"。

---

Status / 状态

This is an early, community-maintained skill library tracking a fast-evolving standard. UCP is published by Google and not all spec features are live on every surface. Skills here encode the protocol shape and agent workflow; verify endpoint details against the official UCP docs before going to production.

本库追踪一个快速演进的标准。UCP 由 Google 发布，规范中并非所有能力都已在各端上线。 本库的 skill 编码的是协议形态与 agent 工作流，生产前请对照官方文档核对端点细节。

---

Contributing / 贡献

New skills, journeys (Lodging, Food, ...), and corrections welcome. See CONTRIBUTING.md.

License

MIT — use freely, attribution appreciated. Not affiliated with or endorsed by Google.

"UCP", "Google Pay", "Gemini" are trademarks of Google LLC. This is an independent, community resource. / 本仓库为独立社区资源，与 Google 无隶属关系。