optimize-shopify-alt-text

Shopify の代替テキストを最適化する

絶対に守ること

• 必ず最初に npx --yes skills update optimize-shopify-alt-text -g -y を実行します。失敗した場合は停止してください。成功した場合は、このファイルに加えて references/onboarding-guide.md と references/alt-text-rules.md を再度読み込んでください。
• 提案するすべての変更を、先にプレビューしてください。明示的な承認を得てから --execute を使用してください。
• 画像の代替テキスト以外は編集しないでください。記事本文では、インラインの <img alt=""> 属性のみを更新してください。
• ホストが実際にネイティブ画像入力でローカル画像を開いていない限り、画像を視覚的に確認したと主張しないでください。
• 画像認識を利用できない場合は、コンテキストのみを使うフォールバックに切り替え、信頼度が低いことを明確に示してください。
• 成果物をクリーンな状態に保ってください。skill-hub.env は作業ディレクトリに残して構いませんが、一時ダウンロードと機械可読なプランは使用後に削除してください。
• 代替テキストは簡潔にしてください。目安は60〜120文字、通常は125文字以下とし、Shopify の512文字という上限を絶対に超えないでください。

最初に読むもの

• Shopify の共通セットアップについては references/onboarding-guide.md
• 表現、長さ、重複に関するルールについては references/alt-text-rules.md

対応対象

• 商品の MediaImage 代替テキスト
• コレクションの注目画像の altText
• 記事の注目画像の altText
• article.body 内の記事インライン画像の alt 属性

振り分けルール

• ユーザーが商品、コレクション、記事、メディア ID、または CDN 画像 URL を指定した場合は、target から開始します。
• scan は、ストア全体のリクエスト、一括処理の計画、あいまいさの解消、または変更後の検証件数の確認に限って使用します。
• --download は現在の確認対象バッチにのみ追加してください。

node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs target --env skill-hub.env --product "Example Product"
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs target --env skill-hub.env --collection <collection-handle-or-url>
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs target --env skill-hub.env --article <article-url-or-title>
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs target --env skill-hub.env --media-id gid://shopify/MediaImage/...
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs target --env skill-hub.env --url <cdn-image-url>
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs scan --env skill-hub.env --page-size 50

ワークフロー

1. skill-hub.env がないか、不完全な場合に限り、共通オンボーディングに従います。
2. connection-check を実行します。
3. 個別のリクエストには target、広範なリクエストには scan を使用します。
4. 画像認識が必要な場合は vision-sample を実行し、モデルがローカルファイルからピクセルの事実を説明できることを確認します。
5. 現在のバッチを references/alt-text-rules.md に照らして確認します。
6. vision や context_only などのソースラベルを付けたプレビュー用プランを1つ作成します。
7. プレビュー一式を得るため、--execute を付けずに apply を実行します。
8. 承認後、apply --execute を再実行します。
9. 件数または指定された対象を検証し、一時ファイルを削除します。

スクリプトのエントリーポイント

場当たり的な GraphQL や単発のスクリプトではなく、同梱のヘルパーを使用してください。

node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs init-env --method admin_custom_app --env skill-hub.env
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs init-env --method dev_dashboard_app --env skill-hub.env
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs connection-check --env skill-hub.env
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs scan --env skill-hub.env --page-size 50
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs vision-sample --env skill-hub.env --limit 3
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs apply --env skill-hub.env --input -
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs apply --env skill-hub.env --input - --execute

出力と検証

• 出力は、会話形式の説明にプレビュー JSON またはヘルパーの stdout を添える程度にしてください。
• 実行後、target または scan を使って更新された対象を検証してください。
• context_only の項目は分けて報告してください。