shopify-blog-seo-optimizer

Shopify ブログ SEO オプティマイザー

これは、プレビュー、コンテンツ監査、調査、書き込み後の検証を行う Admin 書き込みスキルです。

マーチャントが体験すること

1. スキルをインストールし、非公開の skill-hub.env ファイルを 1 つ設定します。
2. 接続チェックを実行します。スキルはストア、接続モード、付与されたスコープ、次のアクションを報告します。
3. 記事の URL、正確なタイトル、または記事 ID を指定します。スキルは監査の前に、該当する記事を確認します。
4. エージェントが現在のコンテンツを監査し、慎重な扱いが必要な主張や事実に関する主張を調査して、候補となる HTML 版を作成します。
5. エージェントは、監査、変更の概要、E-E-A-T の根拠、承認一式、レスポンシブなストアフロントプレビューを含む、単独で利用できる HTML レポートを 1 つ生成します。
6. マーチャントはレポートを確認し、提案されたフィールドを明示的に承認または却下します。
7. 承認後にのみ、スキルは articleUpdate を呼び出します。その後、記事を再度読み込み、意味上のマーカー、リンク、HTML の安全性を検証します。

マーチャントが audit-plan.json やアクセストークンを手作業で作成する必要はありません。候補とレポートのデータはエージェントが管理し、決定論的ヘルパーが検証してレンダリングします。

必須のリファレンス

• 初回の会話と接続の境界については、references/onboarding-guide.md を読んでください。
• 決定論的なチェックと重大度のルールについては、references/audit-checklist.md を読んでください。
• 事実に関する主張や慎重な扱いが必要な主張を評価または変更する前に、references/eeat-methodology.md を読んでください。
• 候補や承認用の成果物を作成する前に、references/report-schema.md を読んでください。
• 統合 HTML レポートをレンダリングする前に、references/storefront-preview.md を読んでください。

接続エラー

リクエストが失敗した場合にのみ対応し、選択したアクセス方法は変更しないでください。

• ネットワーク（fetch failed、ETIMEDOUT、ECONNRESET、ENETUNREACH）：プロキシのポートを推測しないでください。ランタイムが承認済みのプロキシを使う設定になっている場合は 1 回再試行します。それ以外の場合は、このプロセスでプロキシを利用できるようにするようマーチャントに依頼してください。
• 407：ランタイムのシークレットストアでプロキシの認証情報を修正してください。チャットに貼り付けないでください。
• CLI_NOT_FOUND / ENOENT：設定済みの CLI エントリまたはプラットフォームコマンドを解決してください。これはランチャーのエラーです。
• 401/403 / invalid_client：ストア、認証情報、アプリのインストール状況を確認してください。
• SCOPE_UPDATE_REQUIRED：不足しているスコープを表示し、承認を得て、Shopify で承認し、トークンを更新してから再試行してください。
• shop_not_permitted：このストアで許可されているアプリを使用してください。繰り返し試行しないでください。GraphQL エラーの場合は、クエリまたは入力を修正してください。やみくもに再試行しないでください。
• この方法が失敗し、ユーザーが同意した場合にのみ、別のアクセス方法を提案してください。

インストールと初回接続

公開ソースからインストールします。

npx skills add lvsao/shopify-skill-hub --skill shopify-blog-seo-optimizer

ユーザーの作業ディレクトリにプライベート設定を作成します。

node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs init-env --method shopify_cli_oauth --env skill-hub.env

クイックモードではShopifyのブラウザー認証が開き、必要なのはストアのアドレスのみです。Dev Appに直接アクセスする場合は、dev_dashboard_client_credentialsを選択し、次のプライベート値を入力します。

SKILL_HUB_SHOPIFY_ACCESS_METHOD=dev_dashboard_client_credentials
SKILL_HUB_SHOPIFY_STORE_DOMAIN=<store>.myshopify.com
SKILL_HUB_SHOPIFY_CLIENT_ID=<private-client-id>
SKILL_HUB_SHOPIFY_CLIENT_SECRET=<private-client-secret>

アプリは対象ストアにインストールされている必要があり、必要最小限のコンテンツスコープ群として、read_contentとwrite_contentの組み合わせ、またはドキュメントに記載された代替のread_online_store_pagesとwrite_online_store_pagesの組み合わせが必要です。直接接続ではクライアント認証情報を使って短時間有効なトークンをメモリ内で交換し、ファイルやレポートには書き込みません。直接認証情報を利用できない場合は、shopify_cli_oauthを選択し、CLIの認証プロンプトに従ってください。

直接接続モードのタスクで追加のスコープが必要な場合は、references/onboarding-guide.mdにある2段階の同意による権限アップグレードフローに従ってください。今後のリリースを新たな認証情報の取得なしに実行することが承認されている場合は、初回のDev Dashboardオンボーディング時にオプションのAutomation Tokenを設定します。このトークンがストアの同意を付与することはありません。エージェントがトークンを更新して再試行する前に、マーチャントがShopify管理画面でインストール済みアプリを開き、保留中の権限更新を承認する必要があります。

Articleをスキルに渡す前に、接続チェックを実行します。

node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs connection-check --env skill-hub.env

接続チェックで読み取りスコープの不足が報告された場合は、続行しないでください。書き込みスコープが不足している場合、監査とレポートの作成は続行できますが、権限更新が承認されるまでは、承認済みの書き込み処理を開始しないでください。

対象の選択

次のうち、必ず1つだけ指定します。

• --url <public Shopify article URL>
• --title <exact or close article title>
• --article-id <gid://shopify/Article/...>

一致したタイトル、ハンドル、ブログ、Article ID、公開状態、作成者、更新日、ストアフロントURLを確認します。類似した候補の最初のものを、確認なしに選択しないでください。公開URLは対象を特定するためだけに使用し、正確な情報源はAdmin GraphQLとします。

監査と候補のワークフロー

決定論的な取得とチェックには、ヘルパーを使用します。

node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs find --env skill-hub.env --url <article-url>
node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs audit --env skill-hub.env --article-id <article-gid> --output audit.json

references/audit-checklist.mdとreferences/eeat-methodology.mdを読みます。その後、エージェントは元のArticle ID、候補のbodyと任意のsummary、平易な表現によるchangesリスト、調査ソース、E-E-A-Tの所見、正確なupdates一式を含むcandidate.jsonを作成します。仕様にはreferences/report-schema.mdを使用してください。

マーチャントに中間計画の作成を求めず、統合レポートをレンダリングします。

node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs report --audit audit.json --candidate candidate.json --output shopify-blog-seo-report.html --lang zh-CN

レポートには、次の内容を含める必要があります。

• 重大度と根拠を含む、決定論的な監査結果。
• 変更前と変更後の内容を平易な表現で示したもの。
• 調査ソース、E-E-A-Tの根拠、信頼度、未解決の質問。
• Shopifyで提案する正確なフィールドと、意図的に変更しないフィールド。
• Preview only — not publishedバッジ。
• クリック可能な目次と使いやすいFAQ開閉機能を備えた、レスポンシブな候補記事のプレビュー。
• ライブページにアクセスできた場合のみreal-storefront-referenceを指定します。アクセスできなかった場合は、アクセスできない理由とともにtheme-like-fallbackを指定します。
• レポートの言語は、明示的なリクエスト、続いて最新のレポートに関するリクエスト／現在の会話の順に判断し、--lang enまたは--lang zh-CNを渡します。レポートの文面を選ぶ際に、ストアフロントのロケールを使用しないでください。

安全な最適化の範囲

デフォルトでリスクの低い変更は、安定した見出し ID、クリック可能な目次、根拠に裏付けられた有用な FAQ／HowTo コンテンツ、読みやすい見出しとリスト、スペルと文法の修正、空要素の整理、確認済みのリンク修正、文脈に即した画像の代替テキスト、現在の概要が空欄の場合の簡潔な概要です。

認証情報、直接の体験、著者の資格、専門家によるレビュー、顧客の証拠、新たな事実に関する主張、規制対象または安全性に関わるアドバイス、記事の意味を変える変更には、マーチャントの入力が必要です。E-E-A-T の根拠を捏造しないでください。

マーチャントが明示的に範囲を拡大しない限り、ハンドル、公開状態、著者、タグ、画像、テーマファイル、メタフィールドは変更しないでください。記事本文の HTML にスクリプト、JSON-LD、JavaScript、フォーム、iframe、イベントハンドラー、非表示のキーワードブロックを入れないでください。Article API で直接編集できない場合は、メタタイトル、メタディスクリプション、canonical、robots、Open Graph、JSON-LD を個別に監査してください。

承認と書き込み

candidate.json の正確なフィールドを報告してください。ドライランは常に実行できます。

node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs apply --env skill-hub.env --input candidate.json

マーチャントがまとめて報告された内容を明示的に承認した後、approved: true（または approval.confirmed: true）を設定した承認済みプランを作成し、次を実行してください。

node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs apply --env skill-hub.env --input approved-plan.json --execute
node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs verify --env skill-hub.env --article-id <article-gid>

このヘルパーが書き込むのは body と summary のみで、userErrors を確認し、明示的な承認マーカーがない場合は --execute を拒否します。その後、Shopify がマークアップを正規化する可能性があるため、HTML のバイト単位の一致ではなく、意味上のマーカーを比較してください。

決定論的な検証

Hermes PR を提出または更新する前に、ネットワークを使用しない回帰テストスイートを実行してください。

node --test <absolute-path-to-skill>/tests/test-shopify-blog-seo-optimizer.mjs

このスイートでは、レポートの CSP と信頼できない HTML の処理、公開 URL の検証、DNS のプライベート範囲への解決の拒否、プレビュー専用のレポート経路を確認します。Shopify ストア、認証情報、パッケージのインストールは必要ありません。

障害への対応

• ARTICLE_NOT_FOUND：候補を表示するか、別の検索条件を尋ねてください。
• SCOPE_UPDATE_REQUIRED：不足している範囲の分類を正確に示し、書き込み前に停止してください。
• shop_not_permitted：直接のクライアント認証情報が使えるのは、対象となるインストール済みストアのみであることを説明し、CLI OAuth の代替手段を提示してください。
• パスワード保護されたストアフロント、またはブロックされたストアフロント：テーマに似せたフォールバックでレポートを生成し、実際のフロントエンドを検証したと決して主張しないでください。
• 調査上の不確実性：元の主張を維持してレビュー対象として印を付け、権威性を捏造しないでください。