shopify-seo-metadata

Shopify SEO メタデータ

商品、コレクション、ページ、ブログ記事全体を対象に、検索結果に表示されるメタデータ（Google の検索結果スニペットに表示される SEO タイトルとメタディスクリプション）のうち、欠落している項目だけを安全モードで補完します。基本原則は、空欄を埋め、上書きしないことです。マーチャントが手動で記述したメタタイトルは、モデルが生成するものより価値があります。このスキルが変更するのは、空欄のフィールドだけです。

関連スキルの shopify-alt-text は、商品画像の代替テキストに対して同じ欠落項目の補完を行い、shopify-json-ld は構造化データを扱います。ストア全体でメタデータがどれだけ欠落しているかを先に測定するには、shopify-catalog-audit が、この修正の対象範囲を決める FIND ステージです。

ストアへのアクセス

管理 API にアクセスするすべてのスキルは、以下の設定から始めます（このスキルで必要な最小スコープを後述します）。方法は 2 つあります。いずれかを選んでください。

方法 A：カスタムアプリのトークン（スクリプト実行可能）。 Shopify 管理画面で、設定 → アプリと販売チャネル → アプリを開発する → アプリを作成 の順に進み、以下のスコープを付与してから、インストールして 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,write_products,read_content,write_content を実行し、その後 shopify store execute で検証済みの操作を実行します。オーナーが対話形式でログインする、トークンを使わないストアに適しています。

このスキルに必要な最小スコープ： read_products と write_products で、商品とコレクションを扱えます（どちらも products スコープで管理されます）。ページとブログ記事には read_content と write_content が必要です。実行で触れる対象だけにスコープを限定してください。

ツールキットの事前確認。 方法 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 を使えるようにし、このスキルはその手順を提供します。

スクリプトではなくレシピ

references/queries-and-prompts.md の GraphQL ブロックはすべて、コピーして調整するための出発点です。現在のスキーマに合わせて、案件ごとに使い捨てのコードを書き、実行したら破棄してください。メタデータの補完を安全に行うには、次の 2 つのルールを守ります。

安全モードが作業のすべてです

実行前に必ず声に出して確認し、交渉の余地のないルールとして扱ってください。

1. 欠落項目のみを補完してください。既存の値は決して上書きしないでください。 エンティティごとに、最初に seo { title description }（商品／コレクション）または global.title_tag ／ global.description_tag メタフィールド（ページ／記事）を読み取ります。空でない値があるフィールドは、例外なくスキップします。「すべてを上書きする」モードは、意図的に別途行う作業です。デフォルトで有効にすることは決してなく、このスキルを使う人が自動的に利用できるものでもありません。
2. 2 つのフィールドは個別に補完してください。 商品にタイトルがあっても、ディスクリプションがないことがあります。空欄のフィールドだけを生成して書き込み、値が入力済みのフィールドは 1 バイトも変更しないでください。

まずプレビューし、その後に変更

件数を確認せずに一括書き込みを始めてはいけません。

1. 参考資料にある、エンティティごとの読み取り専用 COUNT を実行し、フィールドが欠落している項目の数を確認します。これは、同じスキップ判定を使って変更ループが処理する正確な件数です。
2. 件数が想定と合っているか確認します。 商品が 40 点のストアで、SEO が必要な項目が 3,000 件と表示された場合、スキップ判定が間違っているか、対象ストアが違います。件数が想定を大きく上回る場合は、停止して対象範囲を再確認してください。「何が起きるか見てみる」ために変更処理へ進んではいけません。カタログ全体を対象とした、範囲を限定しない書き込みは、元に戻すのも簡単ではありません。
3. 件数が妥当だと確認できてから、生成と書き込みを行います。

実際の補完でLLMキーを事前確認する

一括処理の前に、生成モデルにmodels.list()／モデル一覧の呼び出しではなく、実際に1トークンの補完を送信してください。モデル一覧の読み取り権限を持つキーでも、実際の補完では失敗することがあります（請求の期限切れ、組織のクォータ、プロジェクトの誤りなど）。処理の途中で無効なキーが見つかると、キュー全体が失敗行になり、クロールも無駄になります。最初にわずかな補完を1回行うのが、最も安価な保険です。

エンティティごとに生成、書き込み、検証する

各エンティティタイプの構成は同じです。異なるのは読み取りクエリ、書き込みミューテーション、コンテンツのソースフィールドだけです（4種類すべてリファレンスに記載されています）。

• 商品： ソース＝商品タイトル＋本文HTML。input.seo { title description }を指定してproductUpdateで書き込みます。
• コレクション： ソース＝コレクションのタイトル＋説明。collectionUpdateと同じseo入力で書き込みます。
• ページ： ソース＝タイトル＋bodySummary。SEOはglobal.title_tag（1行）とglobal.description_tag（複数行）のメタフィールドに格納されます。metafieldsSetで書き込みます。
• ブログ記事： ソース＝タイトル＋summary（＋コンテキスト用の親ブログタイトル）。同じglobal.*_tagメタフィールドを、同じmetafieldsSetで書き込みます。

ソースデータが出力品質の上限を決めます。 商品は本文HTMLから生成します。このカタログに対して一括説明文のクリーンアップや書き換えを実行した直後（例：shopify-catalog-cleanupを使用した場合）は、生成する前に編集後の再スキャンに合格したことを確認してください。そうしないと、変換でマークアップが壊れた商品の内容が、そのまま新しいメタデータに大量に取り込まれます。エンリッチメントで不良なソースデータを修正することはできません。新しいフィールドへ移し替えるだけです。

書き込みのたびに、リソースID、フィールド、旧値、新値、ステータスをCSVまたは改行区切りのログに記録してください。このログが証拠となり、再試行する項目の一覧にもなります。

書き込み後にAdmin API経由で検証する。ストアフロントは使わない

userErrorsなしで返されたミューテーションは、あくまで主張であって、証明ではありません。次の手順で確認してください。

• 実行後、書き込んだリソースのうち2～3件について、admin/api/2025-07/graphql.json経由でseo { title description }（またはglobal.*_tagメタフィールド）を再読み込みし、値が書き込んだ内容と一致することを確認します。
• ストアフロントではなく、Admin API経由で読み戻してください。 ストアフロントの<meta>タグはCDNにキャッシュされ、最新の状態を正しく反映しません。書き込みが反映された後も、エッジに残った古いページには古いタグ（または空のタグ）が表示され、存在しない不具合を追うことになります。真実の情報源はAdmin APIです。

プロンプトの指針

生成されるメタデータの品質は、モデルが推測できない次の3つの要素に左右されます。

• すべてのプロンプトにストアのポジショニングを含めてください。 販売対象、文体、カテゴリをまとめた1段落のブランド説明が、ブランドに合ったコピーとありきたりな埋め草を分けます。説明が不十分または誤っていると、大量のブランドイメージに合わないメタデータが生成されます。一括処理の前に、きちんとした説明を用意してください。
• 長さの目標を設定してください。 SEOタイトルは約50～60文字（Googleは約60文字を超えると省略します）、メタディスクリプションは約150～160文字です。モデルは文字数を正確に数えられないため、コードで長さを検証し、上限を超えたものは、モデルが指示に従うことを当てにせず、再度プロンプトを実行してください。
• キーワードを詰め込まないでください。 購入者が実際に検索する主要キーワードを1つだけ冒頭に置き、検索結果を読む人に向けて書き、そこで止めてください。キーワードの繰り返しやすべて大文字の宣伝文句はスパムのように見え、何の効果もありません。

クエリ、ミューテーション、プロンプトの詳細： references/queries-and-prompts.md。

出典とメンテナンス

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

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: 3) { nodes { title seo { title description } } } }"}'

正規のドキュメント：リソースの seo フィールドと、Admin GraphQL のメタフィールドモデル。このスキルは、参照ドキュメントにはない運用上のセーフモードの方針をまとめたものであり、参照ドキュメントの代わりではありません。