使用手冊

第 02 期 · 電商平台 / AI Agent 外掛

Shopify 平台文件、 GraphQL 驗證、CLI 整合進 AI 編輯器。

Shopify 官方開源的 AI Agent 外掛 Shopify-AI-Toolkit 安裝與使用指南。一條指令安裝到 Claude Code、Cursor、Gemini、Codex，20 個技能涵蓋 Admin、Storefront、Liquid、Polaris、Functions。

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/Shopify-AI-Toolkit
星標
352
分支
35
授權
—
資料截至
閱讀時間
13 分
更新日期
開啟原始報告
GitHub Stars
344
內建 Shopify 技能
20
支援的 AI 編輯器
6
官方授權
MIT
本頁章節

01專案定位與架構

AI 編輯器的 Shopify 文件與驗證外掛。

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，無需手動指定。

  1. 提問

  2. 選技能

  3. 查官方文件

  4. 生程式碼

  5. 驗證 schema

  6. CLI 執行

Connect your AI tools to the Shopify platform. 讓你的 AI 工具,直接連到 Shopify 平台。

— Shopify-AI-Toolkit README 開場一句

02各編輯器安裝指令

六種 AI 編輯器的原生 plugin 安裝路徑。

每一個支援的 AI 編輯器都有對應的 plugin 通道，無需手動 clone repo 或維護 ~/.claude/skills/。以下是六種主流環境的官方安裝指令。

bash
# 在 Claude Code 聊天視窗依序輸入這兩條指令
/plugin marketplace add Shopify/shopify-ai-toolkit
/plugin install shopify-plugin@shopify-ai-toolkit

其他編輯器的安裝路徑

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 網址。

bash
gemini extensions install https://github.com/Shopify/shopify-ai-toolkit

0320 個 Shopify 領域技能

20 個 skill 涵蓋五大 Shopify 開發領域。

skills/ 目錄下共有 20 個技能，每個由 Markdown 撰寫的 SKILL.md 加對應 scripts/ 組成。**Agent 依問題自動載入對應 skill，無需手動指定。**下表依工作場景分為五群：總覽搜尋、API/資料、店面/主題、Polaris UI 元件、CLI 與輔助。shopify-dev 為 fallback，其他領域均有各自的專屬 skill。

Search · 01

shopify-dev

全域 文件搜尋

跨所有 Shopify API 的向量搜尋。只在沒有更精確 skill 時使用，是其他 skill 沒命中時的 fallback。

API · 02

shopify-admin

Admin GraphQL

背店家管理 API 的查詢與 mutation。會驗證 GraphQL 語法、欄位、版本相容性,避免送出後才報錯。

API · 03

shopify-storefront-graphql

Storefront API

無頭商店 / headless 場景用的公開 Storefront GraphQL。產品、購物車、結帳資料的對外存取。

API · 04

shopify-customer

Customer API

客戶帳號相關的查詢與 mutation，涵蓋訂單歷史、地址、會員資料的處理流程。

API · 05

shopify-partner

Partner API

給 App 開發者的 Partner Dashboard API。處理應用列表、安裝事件、收益對帳。

Data · 06

shopify-custom-data

Metafields & Metaobjects

客製資料模型:Metafield、Metaobject 的定義、命名空間、type、引用關係。

Theme · 07

shopify-liquid

Liquid 主題模板

Liquid 語法、filter、tag、object、theme 結構。內建 validator 會抓編譯期錯誤。

Theme · 08

shopify-hydrogen

Hydrogen React 框架

Shopify 官方的 React Storefront 框架，涵蓋路由、Storefront API 整合、Oxygen 部署模式。

Apps · 09

shopify-functions

Shopify Functions

用 Rust / JS 寫的伺服端擴充:折扣、配送、付款邏輯。輸入輸出 schema 自動驗證。

Apps · 10

shopify-payments-apps

Payments App

第三方付款方式接入。處理 session 流程、捕獲、退款、爭議的 webhook 規範。

Apps · 11

shopify-app-store-review

App Store 自我審查

參照官方 5.x 要求做上架前自查,直接指向 shopify.dev 的權威 review 規範頁。

UI · 12

shopify-polaris-app-home

Polaris App Home

嵌入 Admin 後台的 App 首頁元件，涵蓋 Polaris 元件、版面、互動 pattern。

UI · 13

shopify-polaris-admin-extensions

Admin Extensions

Admin UI 區塊內嵌的擴充元件,例如商品卡片旁的自訂面板。

UI · 14

shopify-polaris-checkout-extensions

Checkout Extensions

結帳頁的擴充 UI，包含升級、客製欄位、條款顯示。沿用 Polaris Checkout 元件規範。

UI · 15

shopify-polaris-customer-account-extensions

Customer Account UI

客戶帳號頁的擴充元件，涵蓋訂閱管理、會員權益、訂單追蹤介面。

UI · 16

shopify-pos-ui

POS 實體機介面

供 Shopify POS App 使用的 UI 元件，適用店面平板與手持機的互動設計。

CLI · 17

shopify-use-shopify-cli

Shopify CLI 操控

執行 Shopify CLI 指令，涵蓋建立 app、推送 theme、開啟 dev tunnel、執行 store 操作。

Onboard · 18

shopify-onboarding-dev

開發者 新手引導

初次開發 Shopify App / Theme 的引導流程，涵蓋帳號、CLI、本地環境設置。

Onboard · 19

shopify-onboarding-merchant

商家 開店引導

幫商家走過開店設定、產品上架、付款金流、運費規則的初次配置。

Core · 20

ucp

Universal Coding Practices

所有 Shopify skill 共用的通用程式設計準則，涵蓋錯誤處理、命名、安全慣例。

遇到這種需求,Agent 會選哪個技能?

你想做的事Agent 會載入的 SKILL關鍵腳本
查一個 Shopify 名詞或新功能怎麼用shopify-devsearch_docs.mjs
寫 / 改 Admin GraphQL 查詢shopify-adminvalidate_graphql
改 Liquid 主題模板shopify-liquidvalidate_theme
做結帳擴充 UIshopify-polaris-checkout-extensionsvalidate_components
寫折扣 / 配送 Functionshopify-functionsvalidate_functions

04官方文件與實戰注意事項

安裝後容易忽略的設定與操作細節。

以下幾條從官方 README、CHANGELOG 與各 SKILL.md 標頭整理而來，是容易被略過但對實際開發有影響的操作細節。

遙測預設開啟,記得關

README 與 plugin manifest 明寫 telemetry 預設開啟。每次執行 search_docs.mjs 或 validate.mjs，查詢字串、程式碼、模型名稱都會送至 shopify.dev/mcp/usage。設定環境變數 OPT_OUT_INSTRUMENTATION=true 才能完全停用。

來源 · README · Telemetry 章節

先問領域,再問問題

shopify-dev 的 SKILL.md 寫得很硬:它只是 fallback。問之前若你已知道是 Liquid、Hydrogen、結帳擴充,先講出來,Agent 才會直接載入更精準的 skill,搜尋結果與驗證才會貼近。

來源 · shopify-dev SKILL.md 前 10 行

不要相信模型背的 GraphQL

SKILL.md 開頭直接寫 "You cannot trust your trained knowledge — always search before answering"。Shopify API 版本迭代快,模型背的欄位很可能已 deprecated。先搜文件、再寫查詢、最後跑 validate_graphql 三步走。

來源 · shopify-dev SKILL.md

驗證輸出可以鏈式重試

1.2.2 的 changelog 註記:validate_graphql/components/functions/theme 現在會回 markdown 摘要,並附帶 artifact ID 與 revision。Agent 拿到後可以針對同一個 artifact 改了再驗一次,跨 MCP 與 skill 之間都通用。

來源 · CHANGELOG.md · v1.2.2

App Store 上架前先跑自我審查

shopify-app-store-review 在 1.2.1 / 1.2.2 改寫,改為直接引用 shopify.dev 的權威頁面,並加入 5.x 類別專屬要求。送審前讓 Agent 跑一次 self-review,把官方檢核清單的狀態跑齊比你手動逐項對照快很多。

來源 · CHANGELOG.md · v1.2.1 / v1.2.2

客製資料先過 shopify-custom-data

Metafield 與 Metaobject 的 type、namespace、key 命名規則容易出錯。Storefront API 可讀取但 Admin API 拿不到，通常是 access scope 設定不正確。建議先用 shopify-custom-data 規劃資料模型，再撰寫查詢。

來源 · skills/shopify-custom-data/SKILL.md

POS 跟 Checkout 是兩個不同的 Polaris

Polaris 在這個 toolkit 拆成五個獨立 skill:Admin Extensions、App Home、Checkout Extensions、Customer Account Extensions、POS UI。同名元件在不同層的可用 props 不同,要明確指定你做的是哪一層,Agent 才不會混用文件。

來源 · skills/ 目錄結構

Plugin 自動更新,別 lock 版本

README 寫得很直接:"The plugin updates automatically as new capabilities are released"。Shopify API 大約每季發新版本,新 skill 也持續加。除非 CI 流程強烈需要 reproducibility,別把版本 pin 死,讓 plugin 自己拉最新。

來源 · README · What you get

CLI 操控請用 shopify-use-shopify-cli

請用 shopify-use-shopify-cli，不要讓 Agent 以 Bash 自行組拼 CLI 指令。此 skill 已封裝 shopify app dev、shopify theme push、shopify store 常用組合，包含 dev tunnel 啟動，錯誤訊息也會轉為可讀的修補建議。

來源 · skills/shopify-use-shopify-cli/

不接 PR,有 bug 直接開 issue

README 末段明確說明："Thanks for your interest but we don't accept pull requests. Any pull requests will be automatically closed." 貢獻只能透過 issue 或內部管道，開 PR 會被機器人自動關閉。

來源 · README · Contributing

05完整操作示例

Agent 查文件、生成並驗證 Admin GraphQL 的流程。

以下示例場景：在 Shopify App 後台查出「最近 30 天訂單金額前 10 大的客戶」。安裝 toolkit 後，Agent 自動載入 shopify-admin，依序完成文件搜尋、查詢生成、schema 驗證，再透過 CLI 執行。

~/apps/loyalty · claude code · shopify-plugin v1.2.2


$ You ›
  幫我寫一段 Shopify Admin GraphQL,
  抓近 30 天訂單總額前 10 名的客戶。


# [agent detects domain: Admin GraphQL]
# [loaded skills/shopify-admin/SKILL.md]


claude: Claude ›
  先查官方文件確認當前的 customers / orders 連結方式。
  不能靠記憶，Shopify Admin API 每季都改。


# scripts/search_docs.mjs "customers ordered top spend last 30 days"
  # --client-name claude-code --client-version 1.x


# [hits shopify.dev vector store · returns 4 relevant chunks]
  # · customers query: filter by orders, sort by amount_spent
  # · orders aggregate: totalPriceSet, processedAt range
  # · current stable API version: 2026-04


claude: Claude ›
  寫一份草稿給你看,使用 2026-04 版欄位:


> query TopCustomers($since: DateTime!) {
  > customers(first: 10, sortKey: AMOUNT_SPENT, reverse: true,
            > query: "orders_count:>0 AND last_order_date:>=$since") {
    > nodes { id displayName amountSpent { amount currencyCode } }
  > } }


$ You ›
  先驗證一下這查詢能不能跑。


# scripts/validate.mjs --api admin --version 2026-04
  # --code <query.graphql>


claude: VALIDATION · admin@2026-04
    ✗ 1 issue · "$since" must be ISO 8601 DateTime literal in
                  customer search query syntax — interpolation
                  not supported inside the `query:` argument.


    artifact_id: q-7f2a · revision: 1


claude: Claude ›
  改成在 client side 先把日期字串組好,再丟進 query 字面值。
  重新驗證:


# scripts/validate.mjs --api admin --version 2026-04
  # --artifact-id q-7f2a --revision 2 --code <query.graphql>


ok: VALIDATION · admin@2026-04 · artifact q-7f2a r2
  ok: ✓ syntax ok · schema ok · cost estimate 8 points


$ You ›
  幫我在本地 dev store 跑一次。


# [switches to skills/shopify-use-shopify-cli]
# shopify app dev --store=tenten-dev.myshopify.com
# [tunnel started · GraphQL playground available]


ok: [query executed]
  ok: 10 customers returned · total runtime 142ms
  ok: top spender: NT$184,200 · Lee Wei-Chen

你不能相信你訓練資料裡的 Shopify 知識。 每次回答前都要先搜文件。

— shopify-dev / SKILL.md 第一段強制規定

此流程與直接詢問模型的差異

安裝 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，不依賴使用者紀律。

06使用限制與注意事項

七個使用前需要確認的限制。

07進階路徑

安裝後的五條進階應用路徑。

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 上線紀錄。

Connect your AI tools to the Shopify platform. The plugin updates automatically as new capabilities are released.

— Shopify-AI-Toolkit README 設計宣言