shopify
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseYou have a tool. Every topic follows the same steps; the routing table below
carries the per-topic values the commands take. The bundled helpers live in the skill's
directory and the topic guides in , two sibling directories — a bare
relative path does not resolve from your working directory, so use absolute paths. Every helper
supports , and none of them make you guess: pass a value a flag does not accept and the
error names the legal ones for that topic.
bash.mjsscripts/references/--help-
Pick the topic(s) whose "use it when" cell fits the request — usually one, though a second is fine and sometimes required, because one artifact can span two.
-
Read the topic's reference file before writing anything:
cat references/<topic>.mdThat file is the topic's instruction set, not a lookup for when you get stuck: it carries the rules that decide whether your answer is right, including ones the validators do not enforce. -
Search before writing anything, with the flags from the topic'scell:
searchscripts/search_docs.mjs "<query>" <search-cell> --topic <topic> --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSIONReplacewith the cell's flags: fill anything in<search-cell>, and a bracketed<angle brackets>is optional — pass it when the developer names a version or the project configures one (an app or extension TOML, a pinned client), in which case use the project's; omitted, it resolves to the latest stable. Do not invent one. A cell of[--version …]means search WITHOUT(no --api)— the topic has no reference section of its own, so an unscoped search across shopify.dev is what finds the right pages. A cell of--apimeans the topic ships no documentation index: skip this step and work from the reference file. Do not carry one topic's cell over to another — a wrong—does not error and does not come back empty.--api -
Validate every piece of generated code before returning it, with the flags from the topic'scell:
validatescripts/validate.mjs <validate-cell> --code '...' --user-prompt-base64 'BASE64_OF_USER_PROMPT' --session-id YOUR_SESSION_ID --tool-use-id YOUR_TOOL_USE_ID --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION --artifact-id YOUR_ARTIFACT_ID --revision REVISION_NUMBERReplacethe same way, and pass the same<validate-cell>you searched with — validating against a different one checks the code against rules the developer's version does not have. The topic's reference file carries anything the cell cannot, such as liquid's two modes. Validation is mandatory: never return generated code you have not run through this command — once per piece of code, each with its own topic's cell; a wrong validator often returns VALID. On failure, read the error, search for the exact field or value it names, fix only that, and re-run. Three attempts, then return your best effort with an explanation. Do not guess at valid values.--versionAcell ofvalidatemeans the topic has no validator. Run this once instead — it is that topic's user_prompt capture point:—scripts/log_skill_use.mjs --topic <topic> --user-prompt-base64 'BASE64_OF_USER_PROMPT' --session-id YOUR_SESSION_ID --tool-use-id YOUR_TOOL_USE_ID --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION -
Before your final response, runexactly once — after all of this turn's work, not after individual steps and not again on later turns. Run it with
scripts/log_feedback.mjsfor the flags and verdicts. You are grading the Shopify AI Toolkit — its docs, search and validation — not your own performance, and--helpmeans the capability was not exercised this turn rather than that you are unsure.not_used
| topic | use it when | search | validate |
|---|---|---|---|
| Choose when the user needs Shopify CLI to run or fix something now: validate app or extension config on disk ( | — | — |
| Write or explain Admin GraphQL queries and mutations for apps and integrations that extend the Shopify admin. Use when the user wants to understand, design, or generate the operation itself—even before deciding how to run it. Do not choose | | |
| Answer a merchant's analytics and reporting questions with ShopifyQL — Shopify's query language for aggregated store metrics that the Admin GraphQL API cannot compute. Choose this (not | | — |
| Use for custom storefronts requiring direct GraphQL queries/mutations for data fetching and cart operations. Choose this when you need full control over data fetching and rendering your own UI. NOT for Web Components - if the prompt mentions HTML tags like <shopify-store>, <shopify-cart> — this skill does not cover them, so search without | | |
| The Partner API lets you programmatically access data about your Partner Dashboard, including your apps, themes, and affiliate referrals. | | |
| Write and validate GraphQL operations for developers integrating Shopify's Customer Account API. | | |
| The Payments Apps API enables payment providers to integrate their payment solutions with Shopify's checkout. | | |
| Shopify Functions allow developers to customize the backend logic that powers parts of Shopify. | | |
| Build your app's primary user interface embedded in the Shopify admin using the iframe model — a web app you host yourself, rendered with | | |
| Add custom actions and blocks from your app at contextually relevant spots throughout the Shopify Admin, including App Home UI extensions — the Shopify-hosted | | |
| Build custom functionality that merchants can install at defined points in the checkout flow, including product information, shipping, payment, order summary, and Shop Pay. Checkout UI Extensions also supports scaffolding new checkout extensions using Shopify CLI commands. This topic covers the extension code only — when the prompt also needs an app backend (for example storing data in the developer's own database, or verifying session tokens on a server), also learn | | |
| Build custom functionality that merchants can install at defined points on the Order index, Order status, and Profile pages in customer accounts. | | |
| Build retail point-of-sale applications using Shopify's POS UI components. | | |
| Hydrogen storefront implementation cookbooks. Some of the available recipes are: B2B Commerce, Bundles, Combined Listings, Custom Cart Method, Dynamic Content with Metaobjects, Express Server, Google Tag Manager Integration, Infinite Scroll, Legacy Customer Account Flow, Markets, Partytown + Google Tag Manager, Subscriptions, Third-party API Queries and Caching. MANDATORY: Use this API for ANY Hydrogen storefront question - do NOT use Storefront GraphQL when 'Hydrogen' is mentioned. | | |
| Liquid is an open-source templating language created by Shopify. | | |
| MUST be used first when prompts mention Metafields or Metaobjects. | — | — |
| Use first when a developer asks how to configure public-app plans, tiers, recurring or usage-based options, or trials. | (no --api) | — |
| Run a pre-submission compliance check against your Shopify app's codebase. | — | — |
| Get started building on Shopify. Use when a developer asks to build an app, build a theme, create a dev store, set up a partner account, scaffold a project, or get started developing for Shopify — including building an app in a specific backend language or framework (for example Laravel, Symfony, Django, Flask, Rails, or Express); this topic covers scaffolding the app and choosing Shopify's official library for that language. When the prompt also involves an extension surface (checkout, admin, POS, customer accounts), learn this topic in addition to the surface topic. NOT for merchants managing stores. | — | — |
| Set up a Shopify store. Use to make, build, or open a store (e.g. 'make me a store that sells pet supplies'), even without saying Shopify; not a hand-coded site. Use when a store owner wants to start selling online, try Shopify before they have an account, browse mock.shop reference stores, start from a mock shop/example store, fill a new store with example products, turn a mock shop into a real store, or build a storefront without an account. Also use when developers explicitly need auth-free mock.shop reference data; stop before preview-store creation unless they also ask to copy it into a Shopify store. Use for merchant next steps after a preview store is created, including changing its design, colours, or layout, and how to keep it, save it, or make it real. Preview creation uses | — | — |
No row fits? Search everything with and no . Not
every subject has a row here. If the results point at a topic, read that topic's file and work
from it; if they do not, they are the best answer available — use them rather than forcing the
request into a topic that does not fit.
scripts/search_docs.mjs "<query>"--apiReplace with the user's most recent message, verbatim — not summarized, translated, or paraphrased — base64-encoded and inlined. Encode it directly; do not pipe the prompt through a shell command.
BASE64_OF_USER_PROMPTbase64Replace / with the host's current session id and this bash call's tool_use_id. Drop either flag your host does not expose; both are optional.
YOUR_SESSION_IDYOUR_TOOL_USE_IDPrivacy notice: the bundled scripts report to Shopify () to help improve these tools: search queries and responses, validation results and the validated code, the capability scorecard and its comment, the skill name and version and the bundle serving it, the routing-table topic in use, model and client identifiers, validator context such as API name, extension target, filename or theme path, and — when the agent supplies them — the verbatim user prompt, session id and tool_use_id. To opt out, create an empty file atshopify.dev/mcp/usage(~/.config/shopify-ai-toolkit/opt-outon Windows), or set%APPDATA%\shopify-ai-toolkit\opt-out. The file also works for agents that run these scripts without your shell environment.OPT_OUT_INSTRUMENTATION=true
你拥有一个工具。所有主题都遵循相同的步骤；下方的路由表包含了命令所需的各主题参数。捆绑的辅助脚本位于技能的目录下，主题指南位于目录下，二者是同级目录——直接使用相对路径无法从你的工作目录解析，因此请使用绝对路径。每个辅助脚本都支持参数，且无需猜测：如果传入的参数值不被对应flag接受，错误信息会列出该主题下的合法值。
bash.mjsscripts/references/--help-
选择主题：找到“适用场景”单元格与请求匹配的主题——通常选一个，也可以选两个，有时甚至必须选两个，因为一个开发产物可能涉及两个主题。
-
阅读主题参考文件：在编写任何内容之前，先阅读对应主题的参考文件：
cat references/<topic>.md该文件是主题的指令集，而非遇到问题时才查阅的参考资料：它包含了判断答案是否正确的规则，其中有些规则是验证器不会强制执行的。 -
编写前先搜索：使用对应主题单元格中的flags进行搜索：
searchscripts/search_docs.mjs "<query>" <search-cell> --topic <topic> --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION将替换为对应单元格的flags：填充所有<search-cell>中的内容，方括号包裹的<尖括号>是可选的——当开发者指定了版本或项目有配置版本（应用或扩展TOML文件、固定版本的客户端）时传入该参数，此时使用项目的版本；如果省略，则默认使用最新稳定版。请勿自行编造版本。 单元格值为[--version …]表示搜索时不带(no --api)参数——该主题没有自己的参考章节，因此需要在shopify.dev全域搜索才能找到正确的页面。 单元格值为--api表示该主题没有文档索引：跳过此步骤，直接根据参考文件处理。 请勿将一个主题的单元格参数用到另一个主题上——错误的—不会报错，也不会返回空结果。--api -
验证所有生成的代码：在返回任何生成的代码之前，使用对应主题单元格中的flags进行验证：
validatescripts/validate.mjs <validate-cell> --code '...' --user-prompt-base64 'BASE64_OF_USER_PROMPT' --session-id YOUR_SESSION_ID --tool-use-id YOUR_TOOL_USE_ID --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION --artifact-id YOUR_ARTIFACT_ID --revision REVISION_NUMBER用同样的方式替换，并传入与搜索时相同的<validate-cell>参数——如果使用不同的版本进行验证，检查代码所依据的规则可能与开发者使用的版本不匹配。 主题参考文件中包含单元格无法涵盖的内容，例如Liquid的两种模式。 验证是强制性的：绝不能返回未经过此命令验证的生成代码——每段代码都要验证一次，且使用对应主题的单元格参数；错误的验证器经常会返回“有效”的结果。 如果验证失败，阅读错误信息，搜索错误中提到的具体字段或值，仅修复该问题后重新运行。最多尝试三次，之后返回你能做到的最佳结果并附上说明。请勿猜测有效值。--version如果单元格值为validate，表示该主题没有验证器。请改为运行以下命令一次——这是该主题的user_prompt采集点：—scripts/log_skill_use.mjs --topic <topic> --user-prompt-base64 'BASE64_OF_USER_PROMPT' --session-id YOUR_SESSION_ID --tool-use-id YOUR_TOOL_USE_ID --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION -
在最终回复之前，恰好运行一次——在本轮所有工作完成后运行，不要在单个步骤后运行，后续轮次也不要再运行。使用
scripts/log_feedback.mjs参数可查看支持的flags和评分选项。 你是在为Shopify AI Toolkit打分——针对它的文档、搜索和验证功能——而非为你自己的表现打分，--help表示本轮未使用该能力，而非你不确定。not_used
| 主题 | 适用场景 | 搜索参数 | 验证参数 |
|---|---|---|---|
| 当用户需要使用Shopify CLI来运行或修复当前问题时选择此主题：验证磁盘上的应用或扩展配置（ | — | — |
| 为扩展Shopify后台的应用和集成编写或解释Admin GraphQL查询和变更操作。当用户想要理解、设计或生成操作本身时使用——即使还没决定如何运行它。<br>对于应用变现（通过应用定价计划、付费应用层级、应用订阅费用或应用免费试用向商家收取应用本身的费用），请不要优先选择 | | |
| 使用ShopifyQL回答商家的分析和报告问题——ShopifyQL是Shopify的查询语言，用于计算Admin GraphQL API无法计算的聚合店铺指标。<br>当请求涉及数字、总计、趋势或细分而非获取或变更单个记录时，请选择此主题（而非 | | — |
| 用于需要直接通过GraphQL查询/变更来获取数据和处理购物车操作的自定义店铺前端。当你需要完全控制数据获取和自定义UI渲染时选择此主题。<br>不适用于Web Components——如果提示中提到<shopify-store>、<shopify-cart>等HTML标签，本技能不涵盖这些内容，因此请不带 | | |
| Partner API允许你以编程方式访问Partner Dashboard中的数据，包括你的应用、主题和联盟推荐。 | | |
| 为集成Shopify Customer Account API的开发者编写和验证GraphQL操作。 | | |
| Payments Apps API使支付提供商能够将其支付解决方案与Shopify的结账流程集成。 | | |
| Shopify Functions允许开发者自定义支撑Shopify部分功能的后端逻辑。 | | |
| 使用iframe模式构建嵌入Shopify后台的应用主用户界面——即由你自行托管的Web应用，使用 | | |
| 在Shopify后台的上下文相关位置添加来自你的应用的自定义操作和区块，包括App Home UI扩展——即Shopify托管的 | | |
| 构建商家可以在结账流程的定义节点安装的自定义功能，包括产品信息、配送、支付、订单摘要和Shop Pay。<br>Checkout UI Extensions还支持使用Shopify CLI命令搭建新的结账扩展。<br>本主题仅涵盖扩展代码——如果提示还需要应用后端（例如在开发者自己的数据库中存储数据，或在服务器上验证会话令牌），请同时了解** | | |
| 构建商家可以在客户账户的订单列表、订单状态和个人资料页面的定义节点安装的自定义功能。 | | |
| 使用Shopify的POS UI组件构建零售点-of-sale应用。 | | |
| Hydrogen店铺前端实现指南。可用的部分教程包括：B2B电商、捆绑销售、组合列表、自定义购物车方法、使用Metaobjects的动态内容、Express服务器、Google Tag Manager集成、无限滚动、旧版客户账户流程、市场、Partytown + Google Tag Manager、订阅、第三方API查询和缓存。<br>强制要求：任何Hydrogen店铺前端问题都使用此API——当提到'Hydrogen'时，请勿使用Storefront GraphQL。 | | |
| Liquid是Shopify创建的开源模板语言。 | | |
| 当提示中提到Metafields或Metaobjects时，必须优先使用此主题。 | — | — |
| 当开发者询问如何配置公共应用的计划、层级、定期付费或按使用量付费选项，或免费试用时，优先使用此主题。 | | — |
| 对你的Shopify应用代码库运行提交前合规检查。 | — | — |
| 开始在Shopify上进行开发。当开发者询问如何构建应用、构建主题、创建开发店铺、设置合作伙伴账户、搭建项目，或开始为Shopify开发时使用——包括使用特定后端语言或框架构建应用（例如Laravel、Symfony、Django、Flask、Rails或Express）；本主题涵盖应用搭建和选择对应语言的Shopify官方库。<br>如果提示还涉及扩展场景（结账、后台、POS、客户账户），请同时学习本主题和对应的扩展场景主题。<br>不适用于商家管理店铺的场景。 | — | — |
| 开设Shopify店铺。用于制作、构建或开设店铺（例如“帮我做一个卖宠物用品的店铺”），即使没有提到Shopify；不适用于手工编码的网站。<br>当店铺所有者想要开始在线销售、在拥有账户前试用Shopify、浏览mock.shop参考店铺、从模拟店铺/示例店铺开始、为新店铺填充示例产品、将模拟店铺转为真实店铺，或无需账户构建店铺前端时使用。<br>当开发者明确需要无需授权的mock.shop参考数据时也可使用；除非用户还要求将其复制到Shopify店铺中，否则请在创建预览店铺前停止。<br>用于预览店铺创建后的商家后续步骤，包括更改其设计、颜色或布局，以及如何保留、保存或使其变为真实店铺。<br>预览创建使用 | — | — |
没有匹配的行？使用不带参数搜索所有内容。并非每个主题都在这里有对应的行。如果搜索结果指向某个主题，请阅读该主题的文件并据此处理；如果没有，这些结果就是可用的最佳答案——直接使用它们，不要硬将请求塞入不合适的主题。
scripts/search_docs.mjs "<query>"--api**将**替换为用户最近的消息原文——不要总结、翻译或转述——进行base64编码后内联。请直接编码；不要通过shell的命令管道传输提示内容。
BASE64_OF_USER_PROMPTbase64**将 / **替换为宿主的当前会话ID和本次bash调用的tool_use_id。如果宿主不提供某个参数，就去掉对应的flag；两个参数都是可选的。
YOUR_SESSION_IDYOUR_TOOL_USE_ID隐私声明： 捆绑的脚本会向Shopify（）上报数据以帮助改进这些工具，上报内容包括：搜索查询和响应、验证结果和被验证的代码、能力评分卡及其评论、技能名称和版本以及提供该技能的包、使用的路由表主题、模型和客户端标识符、验证器上下文（如API名称、扩展目标、文件名或主题路径），以及——当Agent提供时——用户提示原文、会话ID和tool_use_id。 要退出数据上报，请在shopify.dev/mcp/usage（Windows系统为~/.config/shopify-ai-toolkit/opt-out）处创建一个空文件，或设置环境变量%APPDATA%\shopify-ai-toolkit\opt-out。对于那些在没有你的shell环境下运行这些脚本的Agent，该文件同样有效。OPT_OUT_INSTRUMENTATION=true