Shopify-AI-Toolkit 是 Shopify 官方開源的 AI Agent 外掛。安裝後，Shopify 的文件、GraphQL Schema、Liquid 規格、Polaris UI 元件、CLI 操作能力可接入 Claude Code、Cursor、Gemini CLI、OpenAI Codex 或 VS Code Copilot。這份手冊涵蓋安裝步驟、20 個技能總覽、遙測設定，以及 Admin GraphQL 寫作與驗證的完整流程。
Shopify 於 2026 年 4 月將這個 repo 發佈於官方 organization 下，定位為 Agent plugins/extensions for CLIs and IDEs。它是一組「技能（Skills）」與一個 MCP 伺服器的混合外掛，讓 AI 編輯器在回應前能查詢 Shopify 最新文件、驗證 GraphQL、檢查 Liquid 模板，並代為執行 Shopify CLI 指令。
Shopify 平台的 GraphQL 分為 Admin、Storefront、Customer、Partner 四套 schema，Liquid 有獨立的 filter / tag 語法，結帳擴充分為 Polaris Checkout Extensions 與 Customer Account Extensions。依賴模型訓練資料回答時，欄位 deprecated 或版本錯誤的問題難以察覺，導致 GraphQL 執行失敗或 Liquid 編譯錯誤。Shopify-AI-Toolkit 將官方文件、API schema 與驗證工具直接提供給 AI，查到才回答、驗證過才送出。
架構上分為兩層：Skills（20 個以 Markdown 撰寫的 SKILL.md，各對應一個 Shopify 領域）與 Dev MCP server（將 search / validate 工具暴露為 Model Context Protocol）。Agent 依問題內容自動載入對應 skill，例如 Liquid 問題走 shopify-liquid，結帳 UI 問題走 shopify-polaris-checkout-extensions，無需手動指定。
每一個支援的 AI 編輯器都有對應的 plugin 通道，無需手動 clone repo 或維護 ~/.claude/skills/。以下是六種主流環境的官方安裝指令。
Cursor 直接從 Cursor Marketplace 一鍵安裝。Gemini CLI 在終端機跑一次擴充安裝即可。OpenAI Codex CLI 進去後輸入 /plugins,搜尋 Shopify,點 Add to Codex。VS Code / GitHub Copilot 開 Command Palette 後選 Chat: Install Plugin From Source,貼 repo 網址。
.claude-plugin/、.cursor-plugin/、.codex-plugin/ 三個目錄，加上 gemini-extension.json 與 VS Code Copilot plugin 入口。安裝後自動更新。README 明確說明 "The plugin updates automatically as new capabilities are released"，無需定期執行 git pull。
skills/ 目錄下共有 20 個技能，每個由 Markdown 撰寫的 SKILL.md 加對應 scripts/ 組成。Agent 依問題自動載入對應 skill，無需手動指定。下表依工作場景分為五群：總覽搜尋、API/資料、店面/主題、Polaris UI 元件、CLI 與輔助。shopify-dev 為 fallback，其他領域均有各自的專屬 skill。
| 你想做的事 | Agent 會載入的 SKILL | 關鍵腳本 |
|---|---|---|
| 查一個 Shopify 名詞或新功能怎麼用 | shopify-dev |
search_docs.mjs |
| 寫 / 改 Admin GraphQL 查詢 | shopify-admin |
validate_graphql |
| 改 Liquid 主題模板 | shopify-liquid |
validate_theme |
| 做結帳擴充 UI | shopify-polaris-checkout-extensions |
validate_components |
| 寫折扣 / 配送 Function | shopify-functions |
validate_functions |
以下幾條從官方 README、CHANGELOG 與各 SKILL.md 標頭整理而來，是容易被略過但對實際開發有影響的操作細節。
README 與 plugin manifest 明寫 telemetry 預設開啟。每次執行 search_docs.mjs 或 validate.mjs，查詢字串、程式碼、模型名稱都會送至 shopify.dev/mcp/usage。設定環境變數 OPT_OUT_INSTRUMENTATION=true 才能完全停用。
shopify-dev 的 SKILL.md 寫得很硬:它只是 fallback。問之前若你已知道是 Liquid、Hydrogen、結帳擴充,先講出來,Agent 才會直接載入更精準的 skill,搜尋結果與驗證才會貼近。
SKILL.md 開頭直接寫 "You cannot trust your trained knowledge — always search before answering"。Shopify API 版本迭代快,模型背的欄位很可能已 deprecated。先搜文件、再寫查詢、最後跑 validate_graphql 三步走。
1.2.2 的 changelog 註記:validate_graphql/components/functions/theme 現在會回 markdown 摘要,並附帶 artifact ID 與 revision。Agent 拿到後可以針對同一個 artifact 改了再驗一次,跨 MCP 與 skill 之間都通用。
shopify-app-store-review 在 1.2.1 / 1.2.2 改寫,改為直接引用 shopify.dev 的權威頁面,並加入 5.x 類別專屬要求。送審前讓 Agent 跑一次 self-review,把官方檢核清單的狀態跑齊比你手動逐項對照快很多。
Metafield 與 Metaobject 的 type、namespace、key 命名規則容易出錯。Storefront API 可讀取但 Admin API 拿不到，通常是 access scope 設定不正確。建議先用 shopify-custom-data 規劃資料模型，再撰寫查詢。
Polaris 在這個 toolkit 拆成五個獨立 skill:Admin Extensions、App Home、Checkout Extensions、Customer Account Extensions、POS UI。同名元件在不同層的可用 props 不同,要明確指定你做的是哪一層,Agent 才不會混用文件。
來源 · skills/ 目錄結構README 寫得很直接:"The plugin updates automatically as new capabilities are released"。Shopify API 大約每季發新版本,新 skill 也持續加。除非 CI 流程強烈需要 reproducibility,別把版本 pin 死,讓 plugin 自己拉最新。
來源 · README · What you get請用 shopify-use-shopify-cli，不要讓 Agent 以 Bash 自行組拼 CLI 指令。此 skill 已封裝 shopify app dev、shopify theme push、shopify store 常用組合，包含 dev tunnel 啟動，錯誤訊息也會轉為可讀的修補建議。
README 末段明確說明："Thanks for your interest but we don't accept pull requests. Any pull requests will be automatically closed." 貢獻只能透過 issue 或內部管道，開 PR 會被機器人自動關閉。
來源 · README · Contributing
以下示例場景：在 Shopify App 後台查出「最近 30 天訂單金額前 10 大的客戶」。安裝 toolkit 後，Agent 自動載入 shopify-admin，依序完成文件搜尋、查詢生成、schema 驗證，再透過 CLI 執行。
安裝 toolkit 後會發生三個關鍵動作：(1) Agent 主動執行 search_docs.mjs，不依賴記憶；(2) 查詢草稿先過 validate.mjs 對照 schema 與版本；(3) 驗證失敗時帶著 artifact_id 與 revision 重試，讓工具鏈識別這是同一查詢的連續修訂，可累積上下文。
使用者不需要記這三步。Agent 識別「Admin GraphQL」問題後，會自動載入 shopify-admin 的 SKILL.md，而該 Markdown 明確規定「Search Before Answering」與「Validate Before Returning」。規範寫入 prompt，不依賴使用者紀律。
search_docs.mjs / validate.mjs 都把查詢字串、被驗證的程式碼、API 名稱、檔名、模型名都送到 shopify.dev/mcp/usage。涉及客戶資料或內部專屬邏輯時,務必先設 OPT_OUT_INSTRUMENTATION=true。
scripts/*.mjs,沒裝 Node 就什麼都不會動。CI 機器或精簡 docker container 要先確認 Node runtime 存在,且能存取 shopify.dev/mcp/usage。
shopify-liquid 才能取得精準回答。
shopify-use-shopify-cli 等同把 Agent 接到你的店家後台,接觸到的可能包括訂單、客戶 PII、財務資料。production store 慎用,先在 dev store 練。
Shopify-AI-Toolkit 將文件查詢、程式碼驗證、CLI 操控整合為基礎配置，是 AI 開發 Shopify 的基礎層。以下五條路徑說明安裝後如何進一步整合進開發工作流程。
1. 把 plugin 寫進團隊 onboarding。新工程師入職就執行 README 上對應編輯器的安裝指令,並讓資安一併設定 OPT_OUT_INSTRUMENTATION。把 Shopify 知識「外掛化」是團隊變快的最低成本起點。
2. 用 Hydrogen + Storefront skill 做 headless 商店。同時掛 shopify-hydrogen 與 shopify-storefront-graphql,Agent 會在 React Server Component 場景自動切換 schema、查正確版本的查詢與 Oxygen 部署模式。
3. 在 App 上架前跑自我審查。送 Shopify App Store 之前讓 Agent 跑 shopify-app-store-review,直接拿官方 5.x 要求對你的程式做一輪比對,避免常見的 access scope、UI guideline 失誤。
4. 結帳擴充用 validate_components 確認品質。結帳是 Shopify 審查嚴格的區域。shopify-polaris-checkout-extensions 的 validate 腳本可發現 Polaris 不允許的 props 與權限不足的 API 呼叫，比上架後被退件再修的成本低。
5. 觀察 CHANGELOG 接住新能力。v1.2.x 系列每兩週滾一版,新 skill / 驗證輸出格式都會記錄在 CHANGELOG.md。在 RSS 或 GitHub watcher 上盯這個檔案,比看 Twitter 還準。
① shopify.dev/docs/apps/build/ai-toolkit：官方 AI Toolkit 完整文件首頁。
② README.md：六種編輯器安裝指令、遙測說明、可用能力清單。
③ CHANGELOG.md：驗證腳本格式變更、artifact ID 機制、新 skill 上線紀錄。