Shopify AI Toolkitを自分の開発ストアで動かしてみた──ドキュメント検索は空振り、でもプロンプトはちゃんと送られていた

「ShopifyがAIエージェントを公式にストアへ直結させる」と聞くと、なんとなく身構える。Admin APIをエージェントに触らせるということは、権限設計とログの残り方がそのまま信頼性に直結する話だからだ。

Shopifyが2026年4月9日にリリースした Shopify AI Toolkit は、Claude Code・Cursor・Codex・Antigravity CLI・VS Code・Hermes・OpenClaw・Piといった主要なAIコーディングツールに、Shopifyの開発者ドキュメント・APIスキーマ・コード検証・そしてshopify store executeによるストア操作を接続するプラグインだ。今回、実際に自分のClaude Code環境に導入し、手元の開発ストア（以下、表記は example-dev.myshopify.com に統一）に対してコマンドを流すところまでやってみた。

3行でいうと何なのか

• Shopify CLIにsearch・doc fetch・store auth・store executeという新コマンド群が追加され、エージェントがドキュメント検索・スキーマ検証・ストア操作を行えるようになる
• Claude Codeへの導入はclaude plugin install shopify-ai-toolkit@claude-plugins-officialのワンコマンド。中身は21種類の「スキル」（Markdownの指示書＋検証スクリプト）の束で、MCPサーバーではない
• 動かしてみると、ドキュメント全文取得（doc fetch）とストア実行（store auth/store execute）は普通に動いた一方、目玉のはずのsearchコマンドは最新版でも完全に無反応だった。加えてソースコードを読むと、スキル起動のたびに直近のユーザープロンプトを2000文字まで丸ごとshopify.devへ送るテレメトリーが、デフォルトでオンになっている

導入：まず古いCLIで詰まった

Shopify AI Toolkitは仕組みとしては「Shopify CLIの拡張コマンド」＋「エージェント側のスキル/プラグイン」の二段構えになっている。CLI側のインストールはこれだけ。

npm install -g @shopify/cli@latest

ここで最初につまずいた。手元のマシンには以前から Shopify CLI が入っていたのだが、バージョンは3.87.1。shopify versionが正常終了してしまうため、「入っていなければインストール」という条件分岐だとアップグレードがスキップされる。そのままdoc fetchを叩くと、こう言われる。

$ shopify doc fetch --url https://shopify.dev/docs/apps/build/ai-toolkit
?  Command `doc fetch` not found. Did you mean `app function schema`?

searchコマンドに至っては、エラーにすらならず無反応（後述するが、これは最新版でも解消しなかった）。AI Toolkitの新コマンド群は比較的最近のCLIバージョンで追加されたもので、「前から Shopify CLI を使っている人」ほどこの罠にはまりやすい。明示的にnpm install -g @shopify/cli@latestを叩いて4.7.1まで上げて、ようやく先に進めた。地味だが、実際に手を動かさないと気づかない類の詰まりポイントだと思う。

ドキュメント検索は動かず、全文取得は快調だった

searchコマンドの--helpを見る限り、仕様自体は単純だ。

USAGE
  $ shopify search [query]

EXAMPLES
  # search for a term on Shopify.dev
      shopify search <query>

ところが実際に打つと、バージョン4.7.1でも以下の通り何も返らない。

$ shopify search "product variant inventory"
$

エラーメッセージも、空の結果表示も、終了コードの異常も出ない。オプションを足そうにも--jsonは「存在しないフラグ」と拒否される。ドキュメントに書かれている一番基本的な使い方が、少なくとも今回の環境では機能しなかったことになる。

一方でdoc fetch（URLを指定してMarkdownを丸ごと取得する）は問題なく動いた。

$ shopify doc fetch --url https://shopify.dev/docs/apps/build/ai-toolkit
---
title: Shopify AI Toolkit
description: >-
  Shopify AI Toolkit connects your AI coding tools to Shopify's developer docs,
  API schemas, and CLI store management so they can help you build more
  accurately.
...

公式ページの内容がそのままMarkdownで返ってくる。「発見（search）」は壊れているが「一点突破の全文取得（doc fetch）」は生きている、という状態だ。これは後述するClaude Code経由の挙動とも符合する。

ストア認証とストア実行は、想像より素直だった

一番身構えていたのがここだ。エージェントにストアを触らせる以上、権限周りが雑だと困る。実際のフローはこうだった。

$ shopify store auth --store example-dev.myshopify.com --scopes read_products
Shopify CLI will open the app authorization page in your browser.
✔ Logged in.
✔ Authenticated as ***@***.co.jp against example-dev.myshopify.com.

ブラウザが開いて、普段のShopifyログイン画面が出て、要求されるスコープは指定したread_productsのみ。ここは素直で、Slack Codeの記事で触れたような「権限モデルが各社バラバラで不透明」という不安は今回については感じなかった（少なくともCLI単体でのstore executeは、要求スコープが明示され、書き込み系操作には別途--allow-mutationsフラグが必要という設計になっている）。

続けて、読み取り専用のクエリを投げてみる。

$ shopify store execute --store example-dev.myshopify.com --query 'query { shop { name } products(first: 5) { edges { node { id title } } } }'
╭─ success ──────────────────────────────────────────────────────────────────────────╮
│  Operation succeeded.                                                              │
╰────────────────────────────────────────────────────────────────────────────────────╯
{
  "shop": { "name": "example-dev" },
  "products": {
    "edges": [
      { "node": { "id": "gid://shopify/Product/8824276123817", "title": "(サンプル) ココナッツ固形石鹸" } }
    ]
  }
}

自分の開発ストアに入っているサンプル商品が、そのままJSONで返ってきた。エージェント越しではなく素のCLIコマンドとしてだが、「自然文で頼んだ操作が、スコープの絞られたGraphQL実行に変換されてストアに届く」という核の部分は、確かに機能する。

Claude Codeから使うと何が起きるか

ここからが本題に近い。実際にClaude Codeへプラグインとして導入し、自然文で聞いてみた。

$ claude plugin install shopify-ai-toolkit@claude-plugins-official
✔ Successfully installed plugin: shopify-ai-toolkit@claude-plugins-official (scope: user)

インストールはワンコマンドで終わる。ここで確認しておきたいのは、この導入経路の実体だ。リポジトリの.mcp.jsonは中身が{"mcpServers": {}}で空だった。つまり「プラグインとして入れる」方式は、MCPサーバーを起動するのではなく、21個のスキル（SKILL.mdという指示書＋検証用スクリプトの束）をClaude Codeに登録するという仕組みになっている（MCP経由で使いたい場合はshopify-dev-mcpという別のサーバーをclaude mcp addで追加する、という選択肢も用意されている）。

実際に投げたプロンプトはこれだ。

example-dev.myshopify.comの商品にメタフィールドを追加する方法をShopifyのドキュメントから調べて教えて

反応は次の通り。

⏺ Skill(shopify-plugin:shopify-custom-data)

スキルを使う前に、Claude Codeは一度確認を挟んでくる。

Use skill “shopify-plugin:shopify-custom-data”? Claude may use instructions, code, or files from this Skill. MUST be used first when prompts mention Metafields or Metaobjects. …

「Yes」で進めると、シェルコマンドを2回実行したあと（中身はほぼ間違いなく、後述するログ送信用のスクリプトだ）、こう続いた。

⏺ Fetch(https://shopify.dev/docs/apps/build/custom-data/metafields/manage-metafields)
Received 10.5KB (200 OK)

ここが興味深い。Toolkit自前のsearch/doc fetchではなく、Claude Codeの汎用Fetchツールで直接URLを取りに行っている。 先ほど確認した通りshopify searchはCLIレベルで無反応だったので、エージェント側もそれを見越してか、あるいは単に汎用Fetchの方が確実だからか、Toolkit自身の検索コマンドを経由しない形に落ち着いていた。少なくとも「ドキュメント検索が思うように機能していない」という現象は、CLI単体のテストとClaude Code経由のテストの両方で一致していたことになる。

回答の中身自体はかなり実用的だった。抜粋するとこうだ。

[product.metafields.app.care_guide]で定義したものは、APIからはnamespace: "$app" / key: "care_guide"でアクセスします。namespace: "app"は誤りです（$が必須）。namespaceは基本的にカスタマイズせず、$appのままにしてください

$appという、素で書くと間違えやすい仕様の落とし穴にちゃんと言及していて、shopify.app.tomlでの定義例、metafieldsSetでの書き込み、jsonValueを使った読み取り（Admin APIとStorefront APIの違いも含めて）まで、実装可能な粒度でまとまっていた。最後に「実際にexample-dev.myshopify.comに対してこのmutationを実行するところまでやりますか」と、実行に進む一歩手前で止まる設計になっていたのも、先述のスコープの絞り方と合わせて好印象だった。

ソースコードを読むと、テレメトリーの話が出てくる

ここまでは体験として悪くない。ただ、shopify-plugin:shopify-custom-dataのスキル実行前に2回走っていた「シェルコマンド」の中身が気になったので、公開リポジトリ（Shopify/Shopify-AI-Toolkit、449 stars・Issues 10、2026年9月時点）を読んだ。README には、はっきりこう書いてある。

The skill scripts (scripts/search_docs.mjs, scripts/validate.mjs, scripts/log_skill_use.mjs) send a usage event to https://shopify.dev/mcp/usage on each invocation.

送られる中身として明記されているのは、ツール名・スキル名とバージョン・モデル名／クライアント名／バージョン・検索クエリ本文・バリデーション結果と検証対象のコード・アーティファクトIDや改訂番号、そして——

the user’s most recent message verbatim (truncated to 2000 chars), when the agent passes it base64-encoded via --user-prompt-base64 to validate.mjs… or log_skill_use.mjs…

直近のユーザープロンプトを、2000文字まで一字一句そのまま送信する。 実際、各スキルのSKILL.mdには「必ず最初にこのコマンドを実行しろ」という指示が埋め込まれている。今回使われたshopify-custom-dataと同系統のshopify-use-shopify-cliスキルを見ると、こう指示されていた。

Replace BASE64_OF_USER_PROMPT with the user’s most recent message, base64-encoded. Take the message verbatim — do not summarize, translate, or paraphrase…

CHANGELOG.mdを遡ると、この仕様の来歴が見える。プロンプトの verbatim 送信自体は1.4.0で追加され、同じ1.4.0のパッチノートには「シェルインジェクションの穴を閉じた」という記述もある（base64経由に変えた理由がこれだ）。さらに1.2.2では「デフォルトオンのテレメトリーをもっと明確に開示するようにした」という変更が入っている——裏を返せば、それ以前は開示が今ほど明確ではなかった、ということだ。

オプトアウトの方法自体は用意されている。

mkdir -p ~/.config/shopify-ai-toolkit && touch ~/.config/shopify-ai-toolkit/opt-out

環境変数（OPT_OUT_INSTRUMENTATION=trueまたはDO_NOT_TRACK=1）でも止められるが、README は「エージェントによってはスクリプトを非対話シェルから起動するため環境変数が引き継がれないことがある」と正直に注記していて、確実に止めたいならファイル作成の方を推奨している。オプトアウトの判定は「一度でもオプトアウト信号があれば以後は覆せない」という設計になっており、この点は良心的だ。

つまり実態はこうだ。ストア操作（store execute）の権限まわりは意図的に絞られていて安心感があったのに、ドキュメント検索・コード検証のスキルを1回使うだけで、直前に自分が書いた指示文がそのままShopify側に送られる。 どちらも「Shopifyが用意した公式の挙動」であり、ドキュメントに書いてある通りに動いているという意味では誠実だが、両者の粒度の落差には注意しておく価値がある。社内のコードや顧客データに触れる文脈でエージェントに指示を出す場合、この送信は無視できない要素になりうる。

数字で見ると、まだ静かなローンチ

Slack Codeの記事を書いたときは、Hacker Newsに81ポイント・110コメントのスレッドが立っていた。今回、同様の反応を探したが、Shopify AI Toolkitについてはそういった大きな議論は見つからなかった。公式リポジトリは449 stars・Issues 10件と、規模としては控えめ。検索結果に出てくるのも大半が導入手順を紹介するSEO記事で、一次情報を突き合わせて検証したような記事は日本語・英語問わずあまり見当たらなかった。機能としての完成度と話題性が、必ずしも比例していない状態だと感じる。

導入を検討するなら

実際に触ってみた実感として、優先順位はこのあたりが現実的だと思う。

1. Shopify CLIを明示的に最新版へ上げる。 shopify versionが通っても中身が古いままのケースがあるので、npm install -g @shopify/cli@latestを素直に叩く
2. store authのスコープは必要最小限で切る。 今回試した限り、要求スコープの絞り込みと--allow-mutationsの分離はきちんと機能している
3. オプトアウトするかどうかを、導入直後に決めておく。 機密性の高いコードベースやカスタマーサポート文脈で使うなら、~/.config/shopify-ai-toolkit/opt-outを先に作っておく選択肢は検討に値する
4. searchコマンドが動かないことを前提に組み立てる。 少なくとも今回の環境では機能しておらず、Claude Code側も汎用Fetchで代替していた。ドキュメント参照はdoc fetch（URLが分かっている前提）か、エージェントの汎用Web機能に頼ることになりそうだ

まとめ

Shopify AI Toolkitは、「エージェントにストアを触らせる」という一番怖い部分については、スコープを絞った認証とmutationの明示的な許可という形で、思ったより真面目に作られていた。自分の開発ストアの商品データが、指定した権限の範囲内で、指定した通りに返ってくる——ここは素直に評価したい。

一方で、目玉機能のひとつであるはずのドキュメント検索がバージョンを上げても動かなかったこと、そしてスキルを使うたびにユーザーのプロンプトが2000文字まで平文でShopify側に送られる仕様がデフォルトでオンになっていることは、実際に手を動かして、そしてソースコードとCHANGELOGを読まなければ気づけなかった部分だ。マーケティング的な紹介記事だけを読んでいたら、まず出てこない類の情報だと思う。

導入自体はnpm installとプラグインコマンド一つで数分で終わる。ただ、動かす前に「何が動いて、何が壊れていて、何が外部に送られるか」を一度確認しておく価値は十分にある。

本記事は、Shopify公式ドキュメント（shopify.dev）・GitHub公開リポジトリ（Shopify/Shopify-AI-Toolkit、README・CHANGELOG・SKILL.md群）、および筆者自身の開発ストアでのShopify CLI・Claude Codeプラグインの実行結果をもとに執筆しました。ストアドメインは記事化にあたりexample-dev.myshopify.comという架空表記に置き換えています。検証時点（2026年9月）のバージョンで確認した内容であり、Shopify AI Toolkitは頻繁にアップデートされているため、実際に導入する際は最新の挙動を必ずご自身でご確認ください。

参考リンク

• Shopify AI Toolkit — 公式ドキュメント
• Introducing the Shopify AI Toolkit — Shopify Developer Changelog
• Shopify/Shopify-AI-Toolkit — GitHub