Shopify AI Toolkitの16スキルを全解説 ― SKILL.mdに書かれた指示書の中身を読む

はじめに

Shopify AI Toolkitには16個のAgent Skillがバンドルされています。

AI Toolkitの概要や導入手順を知りたい方は Shopify AI Toolkitとは？Claude Codeでの導入手順とサードパーティスキルからの移行体験 をご覧ください

外部記事Shopify AI Toolkitとは？Claude Codeでの導入手順とサードパーティスキルからの移行体験

各スキルはSKILL.mdというマークダウンファイルに「AIへの指示書」が書かれており、GitHubでオープンソースとして公開されています。

この記事では、リポジトリを実際にクローンして16個のSKILL.mdを全て読み、それぞれの中身を解説します。

外部記事Shopify-AI-Toolkit/skills at main · Shopify/Shopify-AI-Toolkit

2026/04/29追記

新たに3つのスキルが追加されてましたので、下記で解説しています！

外部記事ryoma.online

全スキルに共通するアーキテクチャ

個別のスキルを見る前に、ほぼ全スキルに共通する構造を押さえておきます。

3ステップの強制フロー

16個中14個のスキルが、以下の手順をAIに強制しています。

1. scripts/search_docs.mjs でShopifyの公式ドキュメントを検索する
2. 検索結果をもとにコードを書く
3. scripts/validate.mjs でAPIスキーマに対してバリデーションする
4. バリデーション失敗時は最大3回リトライする
5. バリデーション通過後にのみコードをユーザーに返す

SKILL.mdには「You must run both search_docs.mjs and validate.mjs in every response. Do not return code to the user without completing step 3.」と太字で書かれています。

さらに、16個中14個のスキルには「You cannot trust your trained knowledge for this API. Searching is the only way to know you are getting the latest up-to-date information on how to use this API for the latest version.」という一文が含まれています。 AIモデルのトレーニングデータは時点が古い可能性があるため、必ず公式ドキュメントを検索してから回答せよ、という指示です。

バンドルされたAPIスキーマ

GraphQL系のスキルには assets/ ディレクトリに admin_2026-04.json.gz のような圧縮スキーマファイルが含まれています。

validate.mjs はこのスキーマに対してコードを検証します。

スキーマのバージョンが 2026-04 であることから、Shopifyの四半期リリースに合わせて更新されていることがわかります。

validate.mjsは何をしているのか

validate.mjs は18,000行を超えるバンドルファイルですが、やっていることはシンプルです。

1. 構文解析（parse）: バンドルされた graphql ライブラリ（v16.13.1）でGraphQLコードをパースする。 構文エラーがあればここで失敗する
2. スキーマバリデーション（validate）: assets/admin_2026-04.json.gz を読み込んでGraphQLスキーマオブジェクトを構築し、パースしたコードをスキーマに対して検証する。 存在しないフィールド、型の不一致、引数の間違いなどがここで検出される。 非推奨フィールドの使用も検出して警告する
3. 必要スコープの解析: バリデーション通過後、クエリで使われているフィールドから必要なアクセススコープ（read_products、write_orders 等）を解析して出力する。 shopify-admin-executionスキルが shopify store auth --scopes ... に使う値となる

つまりネットワーク越しにShopifyのAPIを叩いているわけではなく、ローカルにバンドルされたスキーマファイルに対してバリデーションしています。 開発ストアがなくても、認証なしでもバリデーションが動く仕組みです。

なお、バリデーション結果はデフォルトで shopify.dev/mcp/usage に送信されます。

2つのバリデーション方式

スキルによってバリデーションの呼び出し方が異なります。

GraphQL系（shopify-admin、shopify-customerなど）はインラインで渡します。

node scripts/validate.mjs --code '...' --model YOUR_MODEL_NAME ...

JSXを含むUI Extension系（shopify-polaris-*、shopify-pos-uiなど）はファイル経由で渡します。 JSXの属性文字列がシェルのクォートを壊すためです。

cat > /tmp/extension.tsx << 'SHOPIFY_EOF'
YOUR CODE HERE
SHOPIFY_EOF
node scripts/validate.mjs --file /tmp/extension.tsx --target "app-home" ...

各スキルの詳細解説

1. shopify-admin（102行）

役割: Admin GraphQL APIの操作全般

一言で言うと: 正しいGraphQLコードを生成して、スキーマに対して「正しい」ことを保証するまでが役割。 実行はしない。

アプリ開発で最も使用頻度の高いスキルです。

商品・注文・顧客データのクエリやミューテーションを生成します。

SKILL.mdの指示内容は、検索→コード生成→バリデーションの基本フローに加えて、検索結果に含まれるURLをレスポンスにリンクとして含めるよう指定されています。 バリデーション通過後、ユーザーがストアに対して実行したい場合はshopify-admin-executionスキルに引き継ぐ旨も記載されています。

assets に admin_2026-04.json.gz をバンドルしており、最新のAdmin APIスキーマに対してバリデーションが行われます。

2. shopify-admin-execution（86行）

役割: バリデーション済みGraphQLをストアに対して実行する

一言で言うと: shopify-adminが作ったバリデーション済みGraphQLを受け取って、shopify store auth + shopify store execute のCLIコマンドに包み、実際のストアに対して実行する。 自分ではGraphQLを推測も生成もしない。

16スキルの中で唯一、コード生成ではなく実際のストア操作を行うスキルです。 search_docs.mjs も validate.mjs もアセットも持ちません。

SKILL.mdには以下の重要なルールが書かれています。

• 必ず先にshopify-adminスキルでバリデーション済みのGraphQLを取得してから使うこと。 自分でGraphQLを推測してはいけない
• レスポンスは常に shopify store auth --store ... --scopes ... と shopify store execute --store ... --query ... のCLIコマンド形式で返す
• GraphQLの単独コードブロックを返してはいけない。 ページネーションや閾値変更のオプションも、CLIコマンド形式で提示する
• 中間的なルックアップ（在庫アイテムIDやロケーションIDの取得）も store execute 内で完結させ、手動GraphQLに切り替えない

shopify-adminが「バリデーション済みのコードを作る工場」、shopify-admin-executionが「それをストアに対して走らせるランナー」という関係です。

3. shopify-dev（30行）

役割: API横断的なドキュメント検索のフォールバック

一言で言うと: 他のどのスキルにも該当しない質問が来たときに、shopify.dev全体を横断検索するためのフォールバック用スキル。 バリデーション機能は持たない。

最もシンプルなスキルです。 search_docs.mjs のみで、バリデーションスクリプトもアセットも持ちません。

SKILL.mdには「Use this skill ONLY when no API-specific skill applies to the task. Admin API、Liquid、Checkout Extensionsなど特定APIのスキルがある場合はそちらを使え」と明記されています。

4. shopify-functions（490行）

役割: Shopify Functionsのコード生成

一言で言うと: ディスカウント・配送・決済カスタマイズなどのバックエンドロジック（Shopify Functions）のコードを、正しいファイル構成・命名規則・戻り値の型まで含めて生成するスキル。 デフォルト言語はRust。

指示量が3番目に多いスキルで、内容も最も実装寄りです。 対応するFunction APIが全てリストアップされています。

• Discount（統合ディスカウント。Order Discount / Product Discount / Shipping Discountは非推奨）
• Cart and Checkout Validation
• Cart Transform
• Delivery Customization
• Payment Customization
• Fulfillment Constraints
• Local Pickup Delivery Option Generator
• Pickup Point Delivery Option Generator
• Order Routing Location Rule

特に注目すべき指示がいくつかあります。

• デフォルト言語はRust。 ユーザーが指定しない場合はRustで書く
• Functionsは純粋関数。 ネットワーク、ファイルシステム、乱数、現在時刻にアクセスできない
• 戻り値の型名を出力型（FunctionRunResult や CartLinesDiscountsGenerateRunResult）から導出するルールが詳細に定義されている
• ファイル命名規則: src/run.rs + src/run.graphql（src/input.graphql は禁止）
• 「絶対に shopify app deploy するな」 という禁止事項が太字で書かれている
• shopify app function build でビルド確認、shopify app function run --input=input.json でローカルテスト

assets には13個ものFunction API別スキーマファイルがバンドルされており、全Function APIの入出力をバリデーションできます。

5. shopify-liquid（1,718行）

役割: Liquidテンプレートの開発とバリデーション

一言で言うと: テーマ開発に必要なディレクトリ構造、各ファイルタイプのルール、schemaタグの書き方までを体系的にカバーした、テーマ開発者のためのスキル。 検索が空振りした場合はAI自身のLiquid知識にフォールバックする唯一のスキル。

2番目に大きなスキルです。 テーマのディレクトリ構造（sections, blocks, snippets, layout, config, templates, locales, assets）の定義から始まり、各ファイルタイプの役割と制約が網羅されています。

• sections: {% schema %} タグ必須。 マーチャントがテーマエディタでカスタマイズ可能
• blocks: {% schema %} タグ必須 + ネストブロック対応。 静的レンダリング時は {% doc %} タグが必須
• snippets: render タグで呼び出す。 テーマエディタからは直接編集不可。 {% doc %} タグが必須
• layout: {{ content_for_header }} と {{ content_for_layout }} が必須

バリデーション時には --filename と --filetype（sections, snippets, blocks等）を指定する必要があります。 検索は最大2回まで。 2回とも結果が空の場合は、ビルトインのLiquid知識にフォールバックする指示になっています。 他のスキルにはないルールです。

6. shopify-hydrogen（3,404行）

役割: Hydrogenストアフロントの実装レシピ集

一言で言うと: Shopifyのヘッドレスフレームワーク「Hydrogen」の実装パターン集。 B2B、バンドル、サブスクリプション、GTM連携などのレシピが大量に含まれており、「Hydrogen」というキーワードが出たら問答無用でこのスキルが優先される。

最大のスキルです。 Shopifyの React ベースのヘッドレスフレームワーク「Hydrogen」の実装パターンが大量に含まれています。

レシピとして記載されているもの: B2B Commerce、Bundles、Combined Listings、Custom Cart Method、Dynamic Content with Metaobjects、Express Server、Google Tag Manager連携、Infinite Scroll、Legacy Customer Account Flow、Markets、Partytown + GTM、Subscriptions、Third-party API Queries and Caching。

バリデーション時は --target "hydrogen" を指定し、JSXを含むためファイル経由で渡します。

descriptionに「MANDATORY: Use this API for ANY Hydrogen storefront question - do NOT use Storefront GraphQL when 'Hydrogen' is mentioned.」と書かれており、「Hydrogen」というキーワードが出たら必ずこのスキルが優先されるようになっています。

7. shopify-custom-data（319行）

役割: メタフィールドとメタオブジェクトの設計・操作

一言で言うと: メタフィールドの定義はTOMLで行え、namespace: app は間違い、書き込みは metafieldsSet を使え、など実務でハマりやすいポイントを徹底的に潰すためのスキル。 自前のスクリプトは持たず、shopify-adminのツールに依存する。

自前のスクリプトやアセットを持たず、shopify-adminスキルのツールに依存します。 その代わりSKILL.mdの指示量が多く、Shopifyアプリ開発でよくあるミスを防ぐためのルールが詳細に書かれています。

最も重要な指示は以下の通りです。

• メタフィールド・メタオブジェクトの定義は99.99%のケースで shopify.app.toml（TOML）で行え。 GraphQLの metafieldDefinitionCreate は原則使うな
• [metaobjects.app.example] で定義したメタオブジェクトは type: $app:example でアクセスする
• [product.metafields.app.example] で定義したメタフィールドは namespace: $app + key: example でアクセスする
• 「namespace: app は深刻な間違い」 と太字で警告されている
• メタフィールドの書き込みには必ず metafieldsSet ミューテーションを使う

実務でメタフィールドを扱う開発者にとって、このスキルの存在だけでも公式プラグインを入れる価値があります。

8. shopify-customer（110行）

役割: Customer Account APIのGraphQL操作

一言で言うと: 顧客が自分のデータ（注文履歴、支払い方法、住所）にアクセスするためのAPIスキル。 構造はshopify-adminと同じ「検索→生成→バリデーション」パターンで、対象APIだけが異なる。

assets に customer_2026-04.json.gz をバンドルしています。

9. shopify-storefront-graphql（101行）

役割: Storefront APIでのカスタムショッピング体験構築

一言で言うと: カスタムストアフロントを構築する際のGraphQLクエリ・ミューテーション生成スキル。 HTMLタグ（<shopify-store> 等）が出てきた場合はこのスキルではなくstorefront-web-componentsを使えという切り分けルールがある。

assets に storefront-graphql_2026-04.json.gz をバンドルしています。

10. shopify-partner（98行）

役割: Partner APIのGraphQL操作

一言で言うと: Partner Dashboardのデータ（アプリ情報、テーマ、アフィリエイト紹介）にプログラムからアクセスするためのスキル。 アプリをApp Storeに公開・管理している開発者向け。

assets に partner_2026-04.json.gz をバンドルしています。

11. shopify-payments-apps（109行）

役割: 決済アプリ開発のAPI

一言で言うと: 決済プロバイダーがShopifyのチェックアウトに統合するためのGraphQL操作スキル。 一般的なアプリ開発者が使うケースは少ないが、決済系アプリを開発する場合には必要。

assets に payments-apps_2026-04.json.gz をバンドルしています。

12. shopify-pos-ui（355行）

役割: POS UI Extensionの開発

一言で言うと: 実店舗向けのPOSアプリケーションUI構築スキル。 Smart Gridへの配置やPOS固有のUIコンポーネントが対象。 HTMLコメント（<!-- -->）はバリデータが誤認するため使用禁止。

JSXを含むためファイル経由でバリデーションします。 Shopify CLIでの Extension スキャフォールドコマンドもサポートしています。

13. shopify-polaris-app-home（202行）

役割: アプリホーム画面のUI構築

一言で言うと: Shopify Admin内に埋め込まれるアプリのメイン画面を、Polaris UIコンポーネントで構築するスキル。 「Polaris」とだけ言われて文脈が不明な場合、デフォルトでこのスキルが選ばれる。

バリデーション時のtargetは "app-home" です。

14. shopify-polaris-checkout-extensions（279行）

役割: チェックアウトUI Extensionの開発

一言で言うと: チェックアウトフローの各ポイント（商品情報、配送、決済、注文概要、Shop Pay）にカスタムUIを追加するスキル。 Shopify CLIでの新規Extension生成コマンドもサポート。

15. shopify-polaris-admin-extensions（242行）

役割: Admin UI Extensionの開発

一言で言うと: Shopify Adminの文脈に応じたスポット（商品詳細ページ、注文詳細ページなど）にカスタムアクションやブロックを追加するスキル。 Admin画面にアプリの機能を埋め込みたいときに使う。

16. shopify-polaris-customer-account-extensions（260行）

役割: カスタマーアカウントUI Extensionの開発

一言で言うと: 顧客アカウントページ（注文一覧、注文ステータス、プロフィール）にカスタム機能を追加するスキル。 顧客が自分のアカウントページで操作するUI Extensionを構築する。

スクリプト・アセット一覧

各スキルが持つスクリプトとAPIスキーマの一覧です。

アプリ開発者が押さえるべきスキル

16個全てを意識する必要はありません。 開発するものに応じて、特に関係の深いスキルが変わります。

カスタムアプリ（Remixバックエンド）: shopify-admin + shopify-admin-execution + shopify-custom-data。 Admin APIのクエリ生成・バリデーション・実行と、メタフィールドの正しい設計がカバーされます。

Checkout UI Extension: shopify-polaris-checkout-extensions + shopify-functions。 チェックアウト画面のUIとディスカウント・バリデーションのバックエンドロジック。

テーマ開発: shopify-liquid。 1,718行の指示書がテーマ開発のほぼ全領域をカバーしています。

Hydrogenストアフロント: shopify-hydrogen + shopify-storefront-graphql。 3,404行のレシピ集が実装パターンを網羅。

さいごに

SKILL.mdの中身を読んでみると、単なるドキュメントの要約ではないことがわかります。 「AIがShopify開発で間違えやすいポイント」を熟知した上で、具体的な禁止事項やフォールバックルールが細かく定義されています。

特にshopify-custom-dataの「namespace: app は深刻な間違い」、shopify-functionsの「絶対にdeployするな」、shopify-admin-executionの「必ずバリデーション済みのGraphQLを使え」といった指示は、実務で実際にハマるポイントそのものです。

AI Toolkitを入れるだけで恩恵はありますが、SKILL.mdの中身を理解しておくと、AIが何を根拠にコードを生成しているのかがわかり、出力の品質をより的確に判断できるようになります。

外部記事GitHub - Shopify/Shopify-AI-Toolkit: Agent plugins/extensions for CLIs and IDEs