mcpField
S
shopify-catalog-audit

shopify-catalog-audit

github.com/kgelsterデータ・データベース5045 回インストール10 週間前に更新
リポジトリ

shopify-catalog-audit について

shopify-catalog-auditは、商品データの欠陥を調べるShopify向けの読み取り専用監査スキルです。カタログを索引化し、根拠のある対象を詳しく調査してAdmin APIで確認しますが、修正は行いません。

主な機能

  1. 01カタログの読み取り専用検査
  2. 02商品全体の決定的な索引作成
  3. 03根拠付きの問題仮説の順位付け
  4. 04Admin APIによる問題の検証
  5. 05修正スキル向けの引き継ぎ一覧

活用シーン

  1. 01画像不足、説明文の短さ、価格異常の検出
  2. 02商品タイプやベンダー情報の欠落確認
  3. 03大規模カタログの監査と修正スキルへの振り分け

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/kgelster/awesome-ecom-skills --skill shopify-catalog-audit

インストール後、Claude Code で/shopify-catalog-auditを入力して読み込まれたか確認します。

同梱ファイルreferences/queries.mdreferences/triage-method.md

詳細

Shopify Catalog Audit

問題を見つけるものであり、修正はしません。これはカタログ作業の FIND ステージです。商品データの不備を、根拠を示して優先順位付けした一覧を作成し、引き継ぎます。FIX ステージは、関連するスキルで扱います。shopify-catalog-cleanup（アーカイブ／不要データ）、shopify-seo-metadata（不足している SEO メタデータ）、shopify-alt-text（不足している画像の代替テキスト）が該当します。ここでは変更を加えないでください。

基本原則：目視で確認するには大きすぎるカタログでは、すべての商品詳細ページを読まないでください。 カタログ全体を対象に、低コストで決定論的なインデックスを作成し、モデルに問題が集中している箇所について根拠のある仮説を立てさせ、その範囲だけを詳しく読み込んだうえで、Admin API で検証します。手法の全容はreferences/triage-method.mdに、GraphQL のレシピはreferences/queries.mdにあります。

ストアへのアクセス

読み取り専用の監査です。最小限のスコープである read_products のみを付与し、それ以外は付与しないでください。このスキルでは書き込みスコープは必要ありません。読み取り専用トークンを使うことで、カタログを損傷できないことを確実にするのが最も簡単です。

レーン A：カスタムアプリのトークン（スクリプトで使用可能）。 Shopify 管理画面で、Settings → Apps and sales channels → Develop apps → アプリを作成 → read_products を付与し、アプリをインストールして Admin API アクセストークンをコピーします。環境変数に設定し、コミット対象のファイルには決して書き込まないでください。

export SHOPIFY_STORE="your-store.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="<your Admin API access token>"   # env, not disk

curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ shop { name } }"}'

レーン B：Shopify CLI OAuth（トークンを保存しません）。 shopify store auth --store $SHOPIFY_STORE --scopes read_products を実行し、続いて shopify store execute で検証済みの読み取りを実行します。オーナーが対話的にログインする、トークンを持たないストアに適しています。

ツールキットの事前確認。 レーン B は Shopify CLI を使用します。まず shopify version を実行し、インストールされていなければインストールしてください。Admin GraphQL スキーマ全体と検証済みの実行を利用するには、このスキルと Shopify 公式の AI ツールキットプラグインを組み合わせてください。Claude Code では claude plugin list を確認し、プラグインがなければ次を実行します。

claude plugin marketplace add Shopify/Shopify-AI-Toolkit
claude plugin install shopify-plugin@shopify-ai-toolkit

推奨ですが、必須ではありません。レーン A に必要なのは curl とトークンだけです。ツールキットはエージェントに API を提供し、このスキルは監査の手順を提供します。

非破壊の原則

これは読み取り専用のスキルです。この原則は簡単に守れますが、検証の方法にも適用されます。

  • 変更は決して加えないでください。 productUpdate、productDelete、一括書き込みは禁止です。修正が必要な問題を見つけたら、該当する関連 FIX スキルを示して終了してください。
  • サイトマップではなく、Admin API で存在と状態を確認してください。 サイトマップ（/sitemap_products_1.xml）には公開済みの商品しか掲載されません。下書き、アーカイブ済みの商品、未公開の商品は通知なく漏れますが、データの不要物が隠れているのはまさにこうした商品です。サイトマップを信頼する監査では、問題を過少報告します。admin/api/.../graphql.json を通じて商品状態を読み取ってください。
  • 自己評価より実際のデータを優先してください。 インデックスの結果ではなく、Admin API に再クエリして、公開中のオブジェクトに不備があると確認できた場合にのみ、問題があると判断してください。

監査ループ

2 つのレイヤーで進めます。まずカタログ全体を対象に、低コストで決定論的なインデックスを作成し、その上で仮説に基づくトリアージを行います。「念のため」とモデルにカタログ全体を貼り付けるのはやめてください。この手法で避けるのは、まさにそれによるコストの増大です。

1. 低コストのインデックスを作成します。 products をページネーションで取得し、PDP の品質がわかるフィールドだけを取り込みます（レシピはreferences/queries.mdを参照）。商品ごとに、コードで決定論的なフラグを計算します（コードで判断できることはコードに任せます）。

  • 画像： mediaCount／画像数が 0（写真がない）、または 1（複数のアングルを見せるべき商品のプレースホルダーである可能性が高い）。
  • 説明： descriptionHtml が空、またはタグを除去した後の長さが短いしきい値を下回る（例：約 20 文字未満なら、実質的に空）。品質はまだ判断せず、「情報不足」としてフラグを付けます。
  • 価格の異常： いずれかのバリエーションの price が 0.00、または compareAtPrice が設定されているのに price 以下（割引がない、あるいはマイナスになる、逆転した、または見せかけの「セール」）。
  • 分類の不足： productType または vendor が空。これらが空だと、フィルター付きコレクション、ファセット検索、Google Shopping フィードに支障が出ます。
  • ステータスのコンテキスト： status（ACTIVE/DRAFT/ARCHIVED）と publishedAt も保持し、フラグの重み付けに使います（下書きの $0 はノイズですが、公開中の ACTIVE 商品の $0 は実際に存在する不具合です）。

商品ごとにコンパクトな行（handle、id、status、ブール値のフラグ）を出力します。モデルが推論する対象はこのテーブルであり、生のカタログではありません。

2. インデックスに基づき、根拠のある仮説を立てます。 モデルはフラグのテーブルを読み取り、実際の問題が集中している箇所を順位付けします。各仮説には明示的な理由を付けてください。理由がなければ、その仮説は除外します。 優れた仮説は、単に行を列挙するのではなく、パターンを見つけます。「先月インポートされたベンダー X の商品はすべて画像が 0 枚で、フィードのインポートが壊れている可能性が高い」は、「この 40 商品には画像がない」よりも有用です。公開中の商品への影響を考慮します。公開中の商品で価格が $0 なら売上の損失につながりますが、同じフラグが下書きに付いていてもノイズです。

3. 対象を絞って詳細を読み込みます。 根拠のある仮説が対象として示した商品だけ、詳細情報（PDP、バリエーションテーブル、メディア）を取得します。ここで実際にトークンを使います。「念のため」に対象をカタログ全体へ広げ直すのはやめてください。それではこの手法の意味がなくなります。

4. 実際のデータと照合して検証します。 絞り込み後に残った各指摘を Admin API で再クエリし、実際のオブジェクトに不具合があることを確認します。インデックスやサイトマップとの照合ではありません。実データを取得して確認できたことが証拠になります。

運用上のルール

  • 根拠を示すか、除外します。 モデルが説明できないフラグは、詳細を読み込みません。
  • 対象範囲を記録します。 何をインデックス化し、何をインデックス化しなかったかを明記します。「問題のある商品が 18 件見つかった」と報告しても、「カタログに問題がない」という意味に受け取られてはいけません。インデックス化したのは画像、説明、価格、分類であり、それ以外のすべて（壊れたバリエーション、オプションの不一致、不適切なメタフィールドなど）は把握できません。見落としの範囲を明示してください。トリアージは保証ではありません。
  • 対象を広げず、狙いを変えます。 結果が乏しい場合は、別のシグナルにフラグを付けるなど、より良いインデックスを作成します。モデルに生のカタログをさらに渡すのではありません。
  • レート制限は実際に発生します。 products 接続にはクエリコストによるスロットリングがあります。カタログ全体をクロールする前に、references/queries.mdのコストと同時実行に関する注意事項を確認してください。

引き継ぎ形式

不具合の分類ごとにグループ化した、順位付きのリストを出力します。各行には handle、product id、status、具体的なフラグ、根拠、および対処を担当する関連 FIX スキルを記載します。画像の不足・情報不足 → 写真がある場合は shopify-alt-text も適用します。副次的に見つかった SEO メタデータの不足 → shopify-seo-metadata。アーカイブ可能な不要データや $0 の下書き → shopify-catalog-cleanup。

参考資料

  • references/queries.md：ページネーション対応の products GraphQL レシピ、インデックス用に取得するフィールド、クエリコストとレート制限に関する注意事項、Plus ストアでの同時実行に関する注意事項。
  • references/triage-method.md：カタログ作業向けに一般化した、仮説に基づくトリアージ手法。

出典とメンテナンス

最終確認日：2026-07-05。GraphQL は Admin API 2025-07 に固定されています。Shopify は四半期ごとのローリングスケジュールでバージョンを非推奨にするため、バージョン固有の記述を信頼する前に、shopify.dev でフィールド名とバージョンを確認してください。トークンがストアに到達し、監査フィールドがライブスキーマで解決されることを確認するため、第三者が実行できる読み取り専用の再検証：

curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ products(first:5){ edges{ node{ handle status productType vendor descriptionHtml mediaCount{count} variants(first:5){ edges{ node{ price compareAtPrice } } } } } } }"}'

正規ドキュメント：Admin GraphQL、products クエリ。 このスキルは、ドキュメントでは説明されていない監査方法をまとめたものです。リファレンスの代替ではありません。

コメント

Markdown 対応