[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M718DN0BKN9RMEMDV3C5SJ6N":3,"skill-same:01M718DN0BKN9RMEMDV3C5SJ6N":72},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":49,"commitSha":50,"skillDirectory":51,"forksCount":52,"repositoryHtmlUrl":53,"repositoryHomepageUrl":54,"ownerHtmlUrl":55,"ownerBlogUrl":56,"ownerDescription":6,"updatedAt":57,"install":58,"resources":71},"01M718DN0BKN9RMEMDV3C5SJ6N","commerce-architecture",null,"How the reference commerce agents of either role are structured, covering the loop, where each rule lives, skills, the backend interface, delegates, and model fields. Load when designing or reviewing the structure of a shopping or merchant agent.","anthropics\u002Fcommerce-agents","anthropics","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F76263028?v=4","01M697XGDPXJAVQ8391V2BCYTE","Anthropic","01M718D5FGWKEA8ZJF2GGGYZWB",3473,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fcommerce-agents\u002Fblob\u002Fmain\u002Fplugins\u002Fcommerce-builder\u002Fskills\u002Fcommerce-architecture\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"architecture","commerce","commerce architecture","structured","when","role","either","rule","load","loop","reference","fields","interface","how","model","backend","delegates","merchant","shopping","structure","2026-11-10 10:12:30",false,"---\nname: commerce-architecture\ndescription: How the reference commerce agents of either role are structured, covering the loop, where each rule lives, skills, the backend interface, delegates, and model fields. Load when designing or reviewing the structure of a shopping or merchant agent.\n---\n\n# Commerce agent architecture\n\nPaths are in the reference repo: `commerce_common\u002F` is `commerce-common\u002Fcommerce_common\u002F`, `shopping_agent\u002F` is\n`shopping-agent\u002Fcore\u002Fshopping_agent\u002F`, `merchant_agent\u002F` is `merchant-agent\u002Fcore\u002Fmerchant_agent\u002F`, and the runtimes are\n`shopping-agent\u002Fruntime-messages-api\u002Fshopping_agent_runtime\u002F` and `merchant-agent\u002Fruntime-messages-api\u002Fmerchant_agent_runtime\u002F`.\n\n## One loop\n\n- One model owns the conversation. A turn is `ShoppingAgent.stream_turn` or `MerchantAgent.stream_turn` (each\n  runtime's `orchestrator.py`): the model reads the cached prompt, calls tools (one round's calls run\n  concurrently), and ends with text plus presentation calls. There is no router, classifier, or hand-off.\n- Every call on every path runs through the role executor (`ShoppingToolExecutor` in `shopping_agent\u002Fexecutor.py`,\n  `MerchantToolExecutor` in `merchant_agent\u002Fexecutor.py`) over `BaseToolExecutor` in `commerce_common\u002Fexecution.py`.\n  The Messages API runtime, the Agent SDK toolset, and the MCP server call the same `execute`, which never raises;\n  after `max_tool_iterations` rounds (`commerce_common\u002Fconfig.py`) the runtime forces a round without tools.\n\n## Where a rule lives\n\n| A rule that applies | Lives in | Reference |\n|---|---|---|\n| While one call's arguments are being filled in | That tool's description | `build_tools` in each role's `tools\u002Fregistry.py` |\n| On most turns: cart and checkout, the staged-write contract, presentation grammar, tool order, trust rules | The static prompt | `build_static_system` in each role's `prompt.py` |\n| On the minority of requests that need a multi-step procedure | A skill, loaded on demand | `shopping-agent\u002Fskills\u002F`, `merchant-agent\u002Fskills\u002F` |\n\nA rule the core journey needs on most conversations moves a layer down. This table is the one statement of the layering.\n\n## Skills\n\n- A skill is a directory holding `SKILL.md`: frontmatter `name` and `description`, then the body (`parse_skill_md`\n  in `commerce_common\u002Fskills.py`). The description names the request class; it carries no sample utterances.\n- The static prompt carries the index alone (`SkillRegistry.index_block`, sorted by name) and `load_skill` returns\n  one body (`_load_skill` in `commerce_common\u002Fexecution.py`). On the Agent SDK, `ensure_project_skills` links the\n  same directories into `.claude\u002Fskills\u002F` and `SKILL_TOOL_ADAPTER` points the model at the SDK's `Skill` tool\n  (`commerce_common\u002Fagent_sdk.py`); the hosted manifests list the directories under `skills[]` in `agent.yaml`.\n\n## The backend interface\n\nA deployment implements one abstract class per role; nothing else reaches its systems.\n\n- `StorefrontBackend` (`shopping_agent\u002Fbackend.py`): 11 abstract methods, catalog (2), cart (4), preferences (1),\n  orders (2), policies (1), fulfillment (1); `get_account_context`, `get_disclosure`, and `checkout_handoff` have defaults. No method\n  places an order or moves money; `checkout_handoff` names where payment happens (a hosted checkout URL, or one per seller) and the host renders it.\n- `MerchantBackend` (`merchant_agent\u002Fbackend.py`): 16 abstract methods, reads (8: performance 3, catalog 2,\n  inventory and order health 2, pricing 1) and the change lifecycle (8: five `stage_*`, `get_pending_changes`,\n  `apply_change`, `discard_change`); `execute_analysis_query`, `get_analysis_schema`, `get_merchant_context` have defaults.\n- A product or listing sold by size, color, or tier is a family record carrying `options`, its variants each a\n  record with `option_values` and `variant_of`; the cart and price or restock writes take a variant's id and the\n  gates hold a family's. `docs\u002Fbackends.md` has the mapping from common catalog models and what to return for a figure\n  the platform cannot supply.\n- Eligibility, pricing, inventory, and quantity rules are enforced in the backend; the gates check provenance and\n  caps (commerce-trust-safety). Everything a backend returns is fenced before the model reads it.\n- A system that is not wired yet is a method that fails (merchant methods raise `ChangeNotApplicable` from\n  `merchant_agent\u002Fchanges.py`); the tool stays registered, so prompt bytes do not change. A system the business\n  does not have at all is absent: an `enable_*` switch on the role's config turned off, which removes its tools\n  (`absent_tools()`), prompt lines, and grounding rule on all three paths, and the executor refuses those names;\n  the skills that need it are parked under `skills\u002F_staged\u002F`, and the bytes are then fixed for that deployment. `NotOffered` (`shopping_agent\u002Fbackend.py`) is the narrower signal:\n  one item or seller the store does not serve while the system itself is on.\n- `executor_class=` on `ShoppingAgent` \u002F `MerchantAgent`, the SDK toolsets, and the MCP servers' `build_server`\n  takes a subclass of the role's executor for a deployment's own `domain_error` mapping or result wording.\n\n## Delegates\n\nA second model call takes one shape: a `DelegateExtension` (`commerce_common\u002Fdelegation.py`). It receives a brief\nand the handles in `DelegationContext`, never the conversation or the executor; it returns one result validated\nagainst `result_model`; it cannot write, present, or call a delegate; `_run_delegate` in `commerce_common\u002Fexecution.py`\ncaps its calls per turn at `max_delegate_calls_per_turn`. `MerchantAgent` takes `extra_delegates`, and its\nbuilt-in instance is `run_analysis` (commerce-merchant-operations). `ShoppingAgent` registers none.\n\n## Model fields\n\n`model` runs the turn loop and `memory_model` the post-turn extraction (`BaseAgentConfig` in `commerce_common\u002Fconfig.py`);\n`analysis_model` runs the delegate, and `None` means `model` (`MerchantAgentConfig` in `merchant_agent\u002Fconfig.py`). The\nSDK runtimes copy `config.model` into the options; the manifests set `model:`. Choose the values with your own evals.\n\n## Do not\n\n- Vary `tools[]` or the static prompt by request (commerce-prompt-caching).\n- Put a most-turns rule in a skill, or a one-tool rule in the prompt.\n- Enforce a cap or a permission in prompt text alone; it belongs in the executor or the backend.\n- Let the model author a price, a figure, or a term; components are joined from server records (commerce-ui-tools).\n- Add a domain tool to a core package; a vertical adds UI through `PresentationExtension` and keeps the rest in its own code.\n","# Commerce agent architecture\n\nPaths are in the reference repo: `commerce_common\u002F` is `commerce-common\u002Fcommerce_common\u002F`, `shopping_agent\u002F` is\n`shopping-agent\u002Fcore\u002Fshopping_agent\u002F`, `merchant_agent\u002F` is `merchant-agent\u002Fcore\u002Fmerchant_agent\u002F`, and the runtimes are\n`shopping-agent\u002Fruntime-messages-api\u002Fshopping_agent_runtime\u002F` and `merchant-agent\u002Fruntime-messages-api\u002Fmerchant_agent_runtime\u002F`.\n\n## One loop\n\n- One model owns the conversation. A turn is `ShoppingAgent.stream_turn` or `MerchantAgent.stream_turn` (each\n  runtime's `orchestrator.py`): the model reads the cached prompt, calls tools (one round's calls run\n  concurrently), and ends with text plus presentation calls. There is no router, classifier, or hand-off.\n- Every call on every path runs through the role executor (`ShoppingToolExecutor` in `shopping_agent\u002Fexecutor.py`,\n  `MerchantToolExecutor` in `merchant_agent\u002Fexecutor.py`) over `BaseToolExecutor` in `commerce_common\u002Fexecution.py`.\n  The Messages API runtime, the Agent SDK toolset, and the MCP server call the same `execute`, which never raises;\n  after `max_tool_iterations` rounds (`commerce_common\u002Fconfig.py`) the runtime forces a round without tools.\n\n## Where a rule lives\n\n| A rule that applies | Lives in | Reference |\n|---|---|---|\n| While one call's arguments are being filled in | That tool's description | `build_tools` in each role's `tools\u002Fregistry.py` |\n| On most turns: cart and checkout, the staged-write contract, presentation grammar, tool order, trust rules | The static prompt | `build_static_system` in each role's `prompt.py` |\n| On the minority of requests that need a multi-step procedure | A skill, loaded on demand | `shopping-agent\u002Fskills\u002F`, `merchant-agent\u002Fskills\u002F` |\n\nA rule the core journey needs on most conversations moves a layer down. This table is the one statement of the layering.\n\n## Skills\n\n- A skill is a directory holding `SKILL.md`: frontmatter `name` and `description`, then the body (`parse_skill_md`\n  in `commerce_common\u002Fskills.py`). The description names the request class; it carries no sample utterances.\n- The static prompt carries the index alone (`SkillRegistry.index_block`, sorted by name) and `load_skill` returns\n  one body (`_load_skill` in `commerce_common\u002Fexecution.py`). On the Agent SDK, `ensure_project_skills` links the\n  same directories into `.claude\u002Fskills\u002F` and `SKILL_TOOL_ADAPTER` points the model at the SDK's `Skill` tool\n  (`commerce_common\u002Fagent_sdk.py`); the hosted manifests list the directories under `skills[]` in `agent.yaml`.\n\n## The backend interface\n\nA deployment implements one abstract class per role; nothing else reaches its systems.\n\n- `StorefrontBackend` (`shopping_agent\u002Fbackend.py`): 11 abstract methods, catalog (2), cart (4), preferences (1),\n  orders (2), policies (1), fulfillment (1); `get_account_context`, `get_disclosure`, and `checkout_handoff` have defaults. No method\n  places an order or moves money; `checkout_handoff` names where payment happens (a hosted checkout URL, or one per seller) and the host renders it.\n- `MerchantBackend` (`merchant_agent\u002Fbackend.py`): 16 abstract methods, reads (8: performance 3, catalog 2,\n  inventory and order health 2, pricing 1) and the change lifecycle (8: five `stage_*`, `get_pending_changes`,\n  `apply_change`, `discard_change`); `execute_analysis_query`, `get_analysis_schema`, `get_merchant_context` have defaults.\n- A product or listing sold by size, color, or tier is a family record carrying `options`, its variants each a\n  record with `option_values` and `variant_of`; the cart and price or restock writes take a variant's id and the\n  gates hold a family's. `docs\u002Fbackends.md` has the mapping from common catalog models and what to return for a figure\n  the platform cannot supply.\n- Eligibility, pricing, inventory, and quantity rules are enforced in the backend; the gates check provenance and\n  caps (commerce-trust-safety). Everything a backend returns is fenced before the model reads it.\n- A system that is not wired yet is a method that fails (merchant methods raise `ChangeNotApplicable` from\n  `merchant_agent\u002Fchanges.py`); the tool stays registered, so prompt bytes do not change. A system the business\n  does not have at all is absent: an `enable_*` switch on the role's config turned off, which removes its tools\n  (`absent_tools()`), prompt lines, and grounding rule on all three paths, and the executor refuses those names;\n  the skills that need it are parked under `skills\u002F_staged\u002F`, and the bytes are then fixed for that deployment. `NotOffered` (`shopping_agent\u002Fbackend.py`) is the narrower signal:\n  one item or seller the store does not serve while the system itself is on.\n- `executor_class=` on `ShoppingAgent` \u002F `MerchantAgent`, the SDK toolsets, and the MCP servers' `build_server`\n  takes a subclass of the role's executor for a deployment's own `domain_error` mapping or result wording.\n\n## Delegates\n\nA second model call takes one shape: a `DelegateExtension` (`commerce_common\u002Fdelegation.py`). It receives a brief\nand the handles in `DelegationContext`, never the conversation or the executor; it returns one result validated\nagainst `result_model`; it cannot write, present, or call a delegate; `_run_delegate` in `commerce_common\u002Fexecution.py`\ncaps its calls per turn at `max_delegate_calls_per_turn`. `MerchantAgent` takes `extra_delegates`, and its\nbuilt-in instance is `run_analysis` (commerce-merchant-operations). `ShoppingAgent` registers none.\n\n## Model fields\n\n`model` runs the turn loop and `memory_model` the post-turn extraction (`BaseAgentConfig` in `commerce_common\u002Fconfig.py`);\n`analysis_model` runs the delegate, and `None` means `model` (`MerchantAgentConfig` in `merchant_agent\u002Fconfig.py`). The\nSDK runtimes copy `config.model` into the options; the manifests set `model:`. Choose the values with your own evals.\n\n## Do not\n\n- Vary `tools[]` or the static prompt by request (commerce-prompt-caching).\n- Put a most-turns rule in a skill, or a one-tool rule in the prompt.\n- Enforce a cap or a permission in prompt text alone; it belongs in the executor or the backend.\n- Let the model author a price, a figure, or a term; components are joined from server records (commerce-ui-tools).\n- Add a domain tool to a core package; a vertical adds UI through `PresentationExtension` and keeps the rest in its own code.\n",{"name":5,"description":7},"main","fd4d59224ab96b43c6dc6888207c67b3bd5a24cf","plugins\u002Fcommerce-builder\u002Fskills\u002Fcommerce-architecture",714,"https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fcommerce-agents","https:\u002F\u002Fclaude.com\u002Fsolutions\u002Fcommerce","https:\u002F\u002Fgithub.com\u002Fanthropics","https:\u002F\u002Fanthropic.com","2026-11-04 19:55:09",{"source":8,"skillName":5,"commands":59,"prompt":69,"zipAvailable":70},[60,63,66],{"tool":61,"command":62},"npx","npx skills add anthropics\u002Fcommerce-agents --skill commerce-architecture",{"tool":64,"command":65},"bunx","bunx skills add anthropics\u002Fcommerce-agents --skill commerce-architecture",{"tool":67,"command":68},"pnpm","pnpm dlx skills add anthropics\u002Fcommerce-agents --skill commerce-architecture","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fcommerce-agents\u002Fblob\u002Fmain\u002Fplugins\u002Fcommerce-builder\u002Fskills\u002Fcommerce-architecture\u002FSKILL.md",true,[],[73,97,118,138,162,180],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":44},"01M718ECZVF8TFQM4CVAT5HGQG","search-discovery","Turning a described need (several constraints, a gift, a choice between candidates already in view, a search that came back empty or sold out) into a shortlist and a pick. Not needed when one search for the thing the customer named answers the request, or when the customer wants to learn what matters in a category first (purchase-research).","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fcommerce-agents\u002Fblob\u002Fmain\u002Fshopping-agent\u002Fskills\u002Fsearch-discovery\u002FSKILL.md",[],[80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,28,95,96],"discovery","search","search discovery","back","research","first","gift","view","customer","for","request","pick","purchase","choice","empty","learn","constraints",{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":106,"publishedAt":44},"01M718EAXW7452GQ9336TFCEMH","purchase-research","Teaching a customer how to choose before any candidates appear, when they ask what matters in a category, how two approaches to it differ, or where to begin. Not needed once the customer has named the thing they want, however considered the purchase (that is search work), nor for outfitting a space or an event (planning-goals).","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fcommerce-agents\u002Fblob\u002Fmain\u002Fshopping-agent\u002Fskills\u002Fpurchase-research\u002FSKILL.md",[103],{"categoryNo":104,"categoryName":105,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000021","资料检索与研究",[84,107,92,108,109,110,88,37,89,111,112,81,113,114,28,115,116,117],"purchase research","work","goals","planning","event","choose","space","how to","ask","teaching","it",{"skillNo":119,"name":120,"nameZh":6,"description":121,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":122,"categories":123,"keywords":124,"publishedAt":44},"01M718E8N33VV0XXCY2DA4Y548","planning-goals","Planning a coordinated set of items toward a goal, an event, a trip, or a project, where the request only comes together as several purchases with a structure between them, and later changes to a plan you have presented. Not needed when the customer wants a single item, however carefully chosen.","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fcommerce-agents\u002Fblob\u002Fmain\u002Fshopping-agent\u002Fskills\u002Fplanning-goals\u002FSKILL.md",[],[125,109,110,126,127,128,43,129,130,131,88,132,133,111,90,134,135,28,136,137],"planning goals","SET","with","as","plan","changes","later","project","goal","single","only","you","trip",{"skillNo":139,"name":140,"nameZh":6,"description":141,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":142,"categories":143,"keywords":144,"publishedAt":44},"01M718E5ES8CYDTZFZPB5XDTYP","memory-personalization","Requests about what is remembered, however short, from an ask to remember one thing to asks to say what is on file, correct it, or forget it; a bare save or an answer from the profile alone does not cover these. Also applying what the store already knows, recalling an older fact (a past recipient, a size, a recurring order) when it would change the pick, and deciding what should outlast the session. Not needed when the request carries no personal context to apply or keep.","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fcommerce-agents\u002Fblob\u002Fmain\u002Fshopping-agent\u002Fskills\u002Fmemory-personalization\u002FSKILL.md",[],[145,146,147,148,149,150,151,152,153,154,91,28,155,115,156,157,158,159,160,161],"memory","memory personalization","personalization","bare","remember","recurring","answer","session","correct","short","keep","apply","file","store","forget","say","change",{"skillNo":163,"name":164,"nameZh":6,"description":165,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":166,"categories":167,"keywords":168,"publishedAt":44},"01M718E3E3Y51D55XXTQ9979T9","customer-care","Help after a purchase or booking, covering the status of an order or delivery whether or not the customer names it, returns, refunds, exchanges, and cancellations, an item that arrived damaged, incomplete, or late, and questions about the store's terms or a membership. Not needed for finding, comparing, or choosing something new.","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fcommerce-agents\u002Fblob\u002Fmain\u002Fshopping-agent\u002Fskills\u002Fcustomer-care\u002FSKILL.md",[],[88,169,158,89,170,171,172,173,174,92,175,176,177,117,178,179],"customer care","help","booking","questions","about","delivery","status","new","terms","refunds","returns",{"skillNo":181,"name":182,"nameZh":6,"description":183,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":184,"categories":185,"keywords":197,"publishedAt":44},"01M718E0X4VE056S16PA347Z3F","commerce-ui-tools","The reference presentation-tool contract, covering server-side enrichment, suggestion chips, the event stream, progressive rendering, both roles' built-in components, and adding a vertical component. Load when building or reviewing how a commerce agent's output reaches a frontend.","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fcommerce-agents\u002Fblob\u002Fmain\u002Fplugins\u002Fcommerce-builder\u002Fskills\u002Fcommerce-ui-tools\u002FSKILL.md",[186,189,192],{"categoryNo":187,"categoryName":188,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000003","演示文稿",{"categoryNo":190,"categoryName":191,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":193,"categoryName":194,"taxonomyType":195,"taxonomyTypeDesc":196},"01JBSEEDCAT000000000000037","律师与法务","PROFESSION","适用职业",[198,199,200,25,201,202,203,204,37,111,205,206,207,208,209,210,211,34,32,28],"commerce ui tools","ui","Tools","roles","server","component","enrichment","server-side","tool","rendering","frontend","progressive","contract","stream"]