Schema.org 構造化データ実装 — 完全ワークフロースキル
このスキルは、ウェブサイトの分析、schema.orgマークアップの設計、開発者向けチケットの作成を行うためのエンドツーエンドの方法論を提供します。多言語・多地域のウェブサイトに構造化データを実装する実際のプロジェクトで磨かれてきました。
この方法論はクライアントに依存しません。プロジェクト管理ツール(JIRA、Wrike、または類似のもの)を介した開発者への引き渡しを含む、包括的なschema.orgカバレッジを目指すあらゆるウェブサイトで機能します。
ライセンス: このスキルは、Creative Commons Attribution 4.0 International (CC BY 4.0) ライセンスの下で公開されています。適切なクレジットを元の作者に提供する限り、このスキルをあらゆる目的で自由に共有および改変できます。
関連監査: このスキルのフェーズ5では、実際の出力をフェーズ2で設計された仕様と照らし合わせて検証します。タスクがロケール間での報告された修正の検証(「すべての言語で修正済み」、「全デプロイ済み」)である場合は、JSON-LD検証監査を実行します。このスキルが保持しない要求検証の原則(キャッシュバスティングゲート、サイトマップインデックス/ライブhreflangセットからの母集団列挙、およびポジティブコントロール)を用います。パンくずリスト作業の監査側はパンくずナビゲーション監査です。このスキルはチケット側を処理します。
このスキルの仕組み
これはプロジェクトスキルであり、通常のウェブサイトでは1~2セッションで1~3時間で完了します。多くのページタイプを持つ複雑な多言語サイトでは、より長くかかる場合があります。このスキルは、5つの連続した納品フェーズを定義しています:フェーズ0(セットアップ)、フェーズ1(発見)、フェーズ2(スキーマ設計)、フェーズ3(チケット作成)、フェーズ4(再生成と納品) — その後、開発者がリリースした後に実行される2つのデプロイ後フェーズが続きます:フェーズ5(デプロイ後検証)とフェーズ6(影響測定)。Claudeはユーザーがどのフェーズにいるかを特定し、それをガイドする必要があります。
ユーザーが提供するもの: プロジェクトコンテキスト、分析とチケット案へのフィードバック、プロジェクト固有のルール、未解決の質問への回答。 Claudeが提供するもの: ページタイプの発見、HTML分析、スキーマ設計、チケット案(親+子)、および最終的な再生成されたチケットセット。
用語注記: このスキルでは、「チケット」を開発者向け成果物の総称として使用します。実際の形式は、フェーズ0で選択されたプロジェクト管理プラットフォーム(JIRAチケット、Wrikeタスクなど)によって異なります。
参照ファイル — オンデマンドで読み込み
フェーズ1から6は、フェーズごとに1つのファイルとして参照ファイルにあります。各ポインタはそのトリガーを示します。これらの読み込みは必須の手順です:フェーズが開始されたら、作業を行う前にそのファイルを読み込んでください — このコアファイルからフェーズを即興で作成しないでください。フェーズがファイルを読み込まずに処理されたことに気付いた場合は、その旨を伝え、ファイルを読み込み、これまでに行われた作業をそれに照らして再確認してください。
references/discovery.md— フェーズ1:ページタイプカタログ、トリアージ、Googleガイダンス確認、ページタイプごとの分析(3つの形式すべての既存スキーマ、条件付きスキーマトリアージ、ロケール配信)、実データの保存、統合、分類。ページタイプカタログを構築する前、および各ページタイプのHTMLを分析する前に読み込んでください。references/schema-design.md— フェーズ2、セクション2.1~2.7:グローバルおよびページ固有のスキーマ、@id相互参照、非推奨化と削除、形式移行の処置、プロパティ選択ルール、多言語プロパティ値、前提条件の検証、プロジェクトルール。任意のページタイプのスキーマタイプまたはプロパティを選択する前に読み込んでください。references/ticket-writing.md— フェーズ3:事前チェック、チケットテンプレート、サブエージェントガイドライン、番号付きチケット作成ルール(1~46)、親チケット、納品前チェックリスト、フィードバックワークフロー、および共通スキーマ決定事項(§3.7)。任意のチケットを作成、改訂、またはチェックする前、チケットについてサブエージェントに指示を与える前、および設計中に§3.7の決定事項が発生した場合に読み込んでください。references/delivery.md— フェーズ4:再生成計画、プラットフォーム固有のフォーマット(Wrike、JIRA、リッチテキストエディタ、WAFで保護されたツール)、納品形式決定ツリー、編集パス、チケット間の一貫性チェック、パッケージ化、Wrike XLS + HTMLペースト。最終再生成の前、およびターゲットツール用にチケットをフォーマットする前に読み込んでください。references/post-deployment-verification.md— フェーズ5:全母集団スイープトリガー、フェーズ5事前チェックリスト、言語間検証と取得技術、4つの調査カテゴリとレポート骨子、フォローアップコメント、URLとソース値の検証、GSCエラーの調整と診断、単一取得による誤った合格、クロールエクスポートからのカバレッジ監査。デプロイされたスキーマを検証する前、チケットを完了として確認する前、クライアントから報告された不一致に返信する前、およびSearch Consoleの構造化データエラーを診断する前に読み込んでください。references/measuring-impact.md— フェーズ6:検索表示の内訳、期待値ステートメント、測定可能なチャネル、データ保持。クライアントが構造化データの成果を尋ねた場合、インパクト数値が引き出される前に読み込んでください。
セクション番号(§1.2、§5.4)とルール番号(ルール35、アンチパターン21)はすべてのファイルで同じであるため、相互参照はこのマップを通じて解決されます。
フェーズ0:セットアップとツール
目標: 利用可能なツールとアクセスを評価し、最も効率的なワークフローを設定し、コンテンツ作業を開始する前にプロジェクトレベルの設定を収集します。
0.1 利用可能なツールの評価
分析作業を開始する前に、どのような機能が利用可能かを判断します。
- ブラウザアクセス(例:Chrome拡張機能のClaude、Coworkブラウザツール) — Claudeがページを直接ナビゲートし、レンダリングされたHTMLをキャプチャし、データを抽出し、自律的に事実を検証できるようにします。これは最も効率的なワークフローです。
- ウェブ検索 — ブラウザアクセスなしで、サイト構造をマッピングし、サイトマップを見つけ、ページタイプを発見できるようにします。
- ファイルシステムアクセス — 分析ドキュメントとチケット案を段階的に保存できるようにします。
- 直接サイトアクセス — 一部のサイトは自動アクセスをブロックします(403エラー)。ウェブフェッチが失敗した場合、ブラウザアクセスまたは手動HTMLアップロードがフォールバックになります。
0.2 ユーザーをブラウザアクセスへ導く
ブラウザ支援分析は、このスキルにおける主要な推奨ワークフローです。これにより、Claudeは以下のことが可能になります:
- ページタイプを自律的に発見しマッピングする
- 手動のコピーペーストなしで任意のページからレンダリングされたHTMLをキャプチャする
- 検出シグナル、データソース、テンプレート構造を数分で抽出する
- チケットを作成する前に事実(URLパターン、言語バリアント、フィールドの可用性)を検証する
ブラウザアクセスがまだ利用できない場合は、その利点を説明し、セットアップをガイドします。ユーザーの役割は「HTML収集者」(退屈で価値が低い)から「レビューアおよび意思決定者」(価値が高く、ドメインの専門知識が活かされる)へと移行します。
ブラウザアクセスが利用できない場合、またはサイトが自動ブラウジングを完全にブロックする場合は、フェーズ1.2で説明されている手動ワークフローにフォールバックします。
コスト認識: ブラウザアクセスは最も徹底的な分析を可能にしますが、トークン使用量が大幅に増加します — Chromeツールの呼び出しは大きなペイロードを返し、会話が長くなるにつれて二次関数的に増大します。リアルタイムのページ検査が真の価値を追加する初期発見と検証フェーズにブラウザワークフローを予約してください。ページタイプのインベントリがすでに確立されているタスク(例:完了した監査からチケットを作成する場合)では、ブラウザ以外のワークフローも同様に効果的であり、はるかに安価です。ブラウザを使用する場合は、負荷の高い呼び出し(完全なDOMのread_page、完全なトラフィックのread_network_requests)よりも、ターゲットを絞った呼び出し(外科的抽出のためのget_page_text、find、javascript_tool)を優先してください。
0.3 プロジェクト設定の収集
コンテンツ作業を開始する前に、ユーザーに尋ねます。
- プロジェクト管理プラットフォーム — 「これらのチケットはどのシステムで作成されますか?(JIRA、Wrike、Asanaなど)」これにより、用語(チケット vs タスク vs アイテム)、フォーマット制約(例:Wrikeはリストアイテム内のネストされたコードブロックをレンダリングしません —
references/delivery.mdの§4.4 プラットフォーム固有のフォーマットパスを参照)、および納品ファイルの命名規則が決まります。 - チケット構造 — 「あなたの組織では、開発者タスク用に確立されたチケット構造やテンプレートはありますか?もしあれば、テンプレートまたはチケット作成ガイドラインを共有してください。チームの慣習に合わせてスキーマチケットを適応させます。」テンプレートがない場合は、スキルのデフォルト構造を使用します。
- 挨拶とトーン — 例:「チームの皆さん、」とピアツーピアのトーン、またはフォーマルなトーン。
- プロジェクト固有のルール — プライバシー制約、用語、ブランドルールなど。(これらはフェーズ2でも収集できます。)
フェーズ1:発見とページタイプカタログ
目標: ウェブサイト上のすべてのページタイプの完全なインベントリを、検出シグナル、既存のスキーマカバレッジ、およびチケットコード例用に保存された実際のデータとともに構築します。
このフェーズを開始する前に references/discovery.md を読み込んでください。 フェーズ全体が含まれています。
- 1.1 ページタイプリストの収集
- 1.1b 優先順位評価/トリアージ
- 1.1c Googleの現在のガイダンスの確認
- 1.2 各ページタイプの分析
- 1.3 チケットコード例用の実データの保存
- 1.4 発見結果の文書化
- 1.5 統合機会の特定
- 1.6 各ページタイプの分類
フェーズ2:スキーマ設計
目標: 各ページタイプで使用するスキーマタイプとプロパティを決定し、スキーマがサイト全体でどのように相互に関連するかを決定します。
スキーマタイプまたはプロパティを選択する前に references/schema-design.md を読み込んでください。 セクション2.1~2.7が含まれています。
- 2.1 グローバル/共有スキーマの設計
- 2.2 ページ固有のスキーマの設計
- 2.3 相互参照の設計
- 2.4 非推奨化と削除
- 2.4b 形式移行チケット — 既存形式の処置
- 2.5 プロパティ選択ルールの適用
- 2.5b 多言語プロパティ値
- 2.6 確定前の前提条件の検証
- 2.7 プロジェクト固有のルール
§2.8はこのコアファイルに残ります。すべてのチケットとすべての検証に適用されるためです。
2.8 普遍的な技術要件
これらはすべてのプロジェクトに適用されます。
- スキーマはサーバーサイドレンダリングされていること — サーバーから返される初期HTMLに存在し、JavaScriptによって動的に挿入されないこと。これはSEOのベストプラクティスであり、プロジェクト固有の設定ではありません。
- JSON-LD形式 — 常に
<head>セクション内の<script type="application/ld+json">として実装します。 - 個別のscriptタグ — 各スキーマタイプは独自の
<script>タグを取得します。 - @context形式 — 常に
https://schema.orgを使用します(末尾のスラッシュなし)。これをすべてのチケットで一貫して適用します。 - 実際のJSONシリアライザを介して出力する — CMS値を文字列連結/テンプレート化によってJSON-LDを手動で組み立てないでください。手作りのJSON-LDは、エスケープされていない文字だけよりも広範な、あるクラスの破損を起こしやすくなります。補間された値のエスケープされていない引用符、スマート/カーリー引用符の置換(ストレート
"が属する場所でのU+201C/U+201D/U+201E)、および構造エラー(例えば、余分な括弧のセットでラップされた@id値)などです。シリアライザはクラス全体を排除します。エスケープルールだけでは不十分です。 - テキスト値のHTMLエンティティをデコードする — テキストプロパティはデコードされた文字(
'、&)を保持し、CMSフィールドやページソースが格納するHTMLエンティティ('、&)は保持しません。ソースフィールドがエンコードされたテキストを保持している場合、テンプレートはシリアライズする前にそれをデコードします。 - 日付はISO 8601、日時はタイムゾーンオフセット付き — すべての日付と日時プロパティ(
datePublished、dateModified、startDate、validFrom…)はISO 8601を使用します。日時はそのオフセット(YYYY-MM-DDThh:mm:ss+hh:mm)を保持し、裸のローカル時刻やページからコピーされた表示形式は使用しません。
フェーズ3:チケット作成
目標: 開発者向けのチケットを作成します — 共有スキーマ用の1つの親チケット、ページタイプごと(または統合グループごと)に1つの子チケット。
チケットを作成、改訂、またはチェックする前に references/ticket-writing.md を読み込んでください。 フェーズ全体が含まれています。
- 3.1 事前チェック
- 3.2 チケット構造テンプレート
- 3.2b サブエージェント使用ガイドライン
- 3.3 チケット作成ルール
- 3.4 親チケットの作成
- 3.5 事前チェックリスト(納品前)
- 3.6 フィードバックと反復ワークフロー
- 3.7 共通スキーマ決定事項
フェーズ4:最終再生成と納品
目標: 蓄積されたすべてのルール、決定、修正を適用して、チケット間の一貫性を確保しながら、すべてのチケットを1回のパスで再生成します。
最終再生成パスの前に references/delivery.md を読み込んでください。 フェーズ全体が含まれています。
- 4.1 再生成計画の策定
- 4.2 最初にすべての未解決の質問を解決する
- 4.3 順番に再生成する
- 4.4 プラットフォーム固有のフォーマットパス
- 納品形式決定ツリー
- 4.5 編集パス
- 4.6 チケット間の一貫性チェック
- 4.7 納品用のパッケージ化
- 4.8 Wrike納品 — XLSスケルトン + HTMLペースト
フェーズ5:デプロイ後検証
目標: 開発者がスキーマをデプロイした後、実際の出力が仕様と一致していることを確認します — 特に多言語カバレッジと数値型の正確性に注意します。
デプロイされたスキーマを検証する前、チケットを完了として確認する前、またはSearch Consoleエラーを診断する前に references/post-deployment-verification.md を読み込んでください。 フェーズ全体が含まれています。
- フェーズ前文 — スコープ注記(報告された修正の検証はJSON-LD検証監査に進む)、全母集団スイープの2つのトリガー、およびサイト全体のチケットテンプレートインベントリ
- フェーズ5事前チェックリスト(レポート送信前)
- 5.1 言語間検証パターン
- 5.2 監査結果カテゴリ
- 5.3 いつ仕様を再開するか
- 5.4 URL検証 — 公開前手順
- 5.5 ソース値検証 — ミラー監査だけでは不十分
- 5.6 GSCエラー数と実際のクロールの調整
- 5.7 動的にレンダリングされるフィールドでの単一取得による誤った合格
- 5.8 同じページタイプのURL間でのGSC「解析不可能な構造化データ/不適切な値の型」の診断
- 5.9 クロールエクスポートからのカバレッジ監査
フェーズ6:影響測定
目標: 構造化データ実装のビジネスインパクトを評価します。
references/measuring-impact.md を、クライアントが構造化データの成果を尋ねた場合、インパクト数値が引き出される前に読み込んでください。
- 6.1 検索表示の内訳
- 6.2 期待値ステートメント
- 6.3 測定可能なチャネル
- 6.4 データ保持
付録
キーワード: このスキルは、「schema.org」、「構造化データ」、「リッチリザルト」、「JSON-LD」、「JIRAチケット for schema」、「Wrikeタスク for schema」、またはウェブサイトページのSEOマークアップ分析リクエストという言及によってトリガーされます。また、ユーザーがスキーマ実装方法論、フェーズ、チケット構造、または開かれた質問を参照する場合にも使用します。
クイックリファレンス:
- フェーズ0:セットアップとツール
- フェーズ1:発見とページタイプカタログ(
references/discovery.md) - フェーズ2:スキーマ設計(
references/schema-design.md) - フェーズ3:チケット作成(
references/ticket-writing.md) - フェーズ4:最終再生成と納品(
references/delivery.md) - フェーズ5:デプロイ後検証(
references/post-deployment-verification.md) - フェーズ6:影響測定(
references/measuring-impact.md)
貢献: 改善提案やバグ報告は大歓迎です。このスキルは実世界のプロジェクト経験に基づいて継続的に改善されています。