seo-schema

出力例：examples/seo-schema-budgetbytes-slow-cooker-chicken-noodle-soup-20260514/SCHEMA.md

スキーママークアップ

ページのSchema.org JSON-LDを検出、検証、生成します。CMSやページテンプレートにそのまま貼り付けられる <script> ブロックと、現在の状態および問題点をまとめた検証レポートを出力します。

前提条件

• 検出／検証の手順で必須： mcp__firecrawl-mcp__firecrawl_scrape（生のHTMLへのアクセス）。WebFetchが返すのはMarkdownのみです。すべての <script type="application/ld+json"> ブロックは、このスキルが読み取る前に削除されます。Firecrawlがなくても、意図の検出（ステップ4～6）に基づいて新しいスキーマを生成できますが、ページ上にすでに存在するものの検出や検証（ステップ2～3、7）はできません。
• 任意：SE Ranking MCP サーバー（ステップ7で競合のスキーマをベンチマークする際に使用します）。
• ユーザーが指定するもの：対象URL。URLのパターンからページの種類が明らかでない場合は、「これは商品ページです」「これはハウツー記事です」など、ページの意図を示すヒントも指定できます。

プロセス

1. HTMLを取得 mcp__firecrawl-mcp__firecrawl_scrape（推奨）または代替手順を実行

   • コストに関する注意： Firecrawlでは対象URLに1クレジット、さらにステップ7（競合ベンチマーク）を実行する場合は10クレジット（検索結果上位10件につき1クレジット）が必要です。クレジットを節約するため、ユーザーは --no-firecrawl を指定して代替手順（生成のみのモード）を強制できます。
   • Firecrawlを利用できる場合： 対象URLをスクレイピングします。SPAの場合は waitFor: 2000（またはメインコンテンツのCSSセレクター）を渡し、JavaScriptでレンダリングされたDOMを取得します。ステップ2でのJSON-LD解析にはレスポンスの html を、canonical／robotsの照合には metadata を使用します。
   • Firecrawlを利用できない場合： 生のHTMLが必要なステップ2、3、7をすべてスキップします。ステップ4～6は引き続き実行されます。このスキルは「生成のみ」となり、ページ上にあるスキーマとの比較は行わず、意図の検出に基づいて推奨JSON-LDブロックを生成します。SCHEMA.md に次の内容を明記します：Existing-schema detection: skipped — Firecrawl required (WebFetch returns markdown only). Install via extensions/firecrawl/install.sh.
   • Firecrawlを利用できる場合でも、JSON-LDブロックがJavaScriptのレンダリング後にのみ表示される場合は、出力に次の警告を記載します：「JavaScriptでレンダリングされたスキーマは、すべてのクローラーで検出されない可能性があります。可能な場合は、サーバーサイドでJSON-LDをレンダリングしてください。」

2. 既存のスキーマを検出（ステップ1で取得したFirecrawlのHTMLが必要です）

   • 返された html から、すべての <script type="application/ld+json"> ブロックを抽出します。
   • 各ブロックをJSONとして解析します。構文エラーを報告します。
   • 検出した @type をそれぞれ列挙します。
   • Microdata（itemscope／itemprop）とRDFa（typeof／property）も検出します。レガシー形式として示し、JSON-LDへの移行（Googleが明示している推奨形式）を推奨します。
   • ステップ1で代替手順を実行した場合： このステップをスキップします。01-detected.md に Existing-schema detection skipped と記録します。

3. Googleの仕様に照らして検証

   • references/google-rich-results.md を読み込みます。
   • 検出した各 @type について、必須プロパティと推奨プロパティを確認します。
   • よくあるエラーを提示します。例：@context の欠落、ISO 8601形式ではない日付、数値で指定された価格（文字列で指定する必要があります）、schema.orgのURLではなくプレーンテキストで指定された availability、国際形式ではない電話番号。

4. ページの意図を検出

   • URLのパターン（/blog/、/products/、/contact/、/how-to/、`/faq/）に基づきます。
   • <title> と <h1> の語調に基づきます。
   • コンテンツのシグナルに基づきます（番号付き手順のリスト → HowTo、画面上に表示されたQ&Aブロック → FAQPage、価格＋購入ボタン → Product、住所＋営業時間 → LocalBusiness）。
   • 複数の意図が検出された場合は、それぞれに対応するスキーマを生成します。

5. 不足している JSON-LD を生成する

   • 有効なスキーマが一致しない検出済みのインテントごとに、templates/ から該当するテンプレートを読み込みます。
     • article.json — 編集記事／ブログコンテンツ用
     • product.json — 商品／SKU ページ用
     • local-business.json — 実店舗のランディングページ用
     • faq-page.json — 明示的な Q&A ブロック用（政府機関／医療機関の許可リストに限る — references/google-rich-results.md を参照）
     • breadcrumb-list.json — パンくずナビゲーションがあるページ用
   • ライブ HTML の情報を使ってテンプレートのフィールドを埋めます（タイトル → headline、h2 → mainEntity の質問など）。
   • 自動入力できなかったフィールドには {REPLACE: ...} を付け、ユーザーが入力すべき箇所を示します。
   • HowTo は生成しないでください — Google は 2023 年 9 月に HowTo リッチリザルトを終了しました（モバイルとデスクトップ）。意味を明確にするためにスキーマを含めることはできますが、リッチリザルトの向上は見込めません。HowTo を現在利用可能な選択肢として扱わず、推奨理由にこの点を記載してください。

6. 生成した JSON-LD を検証する

   • ステップ 3 と同じ検証基準を、生成したブロックに再適用します。
   • {REPLACE: ...} のまま残っている必須フィールドを明示します。

7. 任意：上位 SERP 結果とのベンチマーク DATA_getSerpResults + mcp__firecrawl-mcp__firecrawl_scrape

   • ページの主要キーワードを特定します（<title> またはユーザー入力から）。
   • オーガニック検索結果の上位 10 件を取得します。
   • Firecrawl が利用可能な場合： 上位 10 件をそれぞれスクレイピングします（Firecrawl クレジットを 10 消費）。各ページについて、返された html から JSON-LD ブロックを解析し、検出された @type を一覧表示します。これにより、Markdown から推測するのではなく、実際のスキーマデータを取得できます。
   • Firecrawl が利用できない場合： ベンチマークをスキップします。WebFetch の Markdown ではスキーマブロックが除去されるため、そこからの「検出」は推測にすぎません。04-competitor-benchmark.md に Competitor benchmark skipped — Firecrawl required to read JSON-LD from competitor pages. と記載します。
   • 「上位 10 件のうち 6 件以上で使われており、このページにはないスキーマタイプ」を明示します。優先度の高い追加候補の一覧です。（ベンチマークを実施した場合のみ出力します。）

8. SCHEMA.md を作成する

   • 検証レポート（既存のスキーマについて、ブロックごとの合格／不合格）。
   • 推奨する追加項目（ステップ 4 の検出結果またはステップ 7 のベンチマークに基づく理由を記載）。
   • そのまま貼り付けて使える生成済みの <script> ブロック。

出力形式

seo-schema-{target-slug}-{YYYYMMDD}/ フォルダーを作成し、次を含めます。

seo-schema-{target-slug}-{YYYYMMDD}/
├── 01-detected.md           (existing schema, validation results)
├── 02-recommended.md        (which types this page should add and why)
├── 03-generated/
│   ├── article.jsonld
│   ├── faq-page.jsonld
│   └── ... (per generated type)
├── 04-competitor-benchmark.md  (only if step 7 ran)
└── SCHEMA.md                (deliverable: paste-ready blocks + install instructions)

SCHEMA.md は次の形式に従います。

# Schema Markup: {URL}

> Snapshot dated {YYYY-MM-DD}.

## Currently present
- `Article` — valid ✓
- `BreadcrumbList` — invalid ✗ (missing `position` on item 2)
- ...

## Recommended additions
- `FAQPage` — page has 6 visible Q&A blocks but no FAQ schema. Adding this is eligible for FAQ rich results (subject to Google's 2024+ tightening — see references/google-rich-results.md).
- `HowTo` — ...

## Paste these into the `<head>` of the page

### FAQPage
\`\`\`html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [...]
}
</script>
\`\`\`

### ... (per generated block)

## Validation pass
- All generated blocks parse cleanly ✓
- All required fields filled ({n} {REPLACE: ...} placeholders remain — see below)
- {REPLACE: ...} placeholders to fill manually:
  - article.jsonld → `image` (need a hero image URL ≥ 1200×800)
  - ...

## Install
1. Copy each `<script>` block above.
2. Paste into the `<head>` of the relevant page (or the global `<head>` template, gated by page type).
3. Test with [Google's Rich Results Test](https://search.google.com/test/rich-results).
4. Submit the URL to GSC for re-indexing if changes are critical.

ヒント

• JSON-LD は <head> または <body> の先頭に配置します。奥深くに埋め込まないでください。
• 公開前に、生成した各ブロックを Google のリッチリザルト テスト でテストしてください。ステップ 3／6 の検証は公開仕様に準拠していますが、Google の実際のテスト結果が最終的な判断基準です。
• references/google-rich-results.md には日付があります。このスキルの実行時点で 6 か月以上前の情報であれば、出力に古い情報であることを明記し、ユーザーに最新のドキュメントで確認するよう勧めてください。
• ページ上に表示されていないコンテンツにはマークアップを付けないでください。 Google は非表示コンテンツのスキーマをペナルティの対象とします。ページ上に FAQ が実際に表示されていない場合は、FAQPage スキーマを生成しないでください。
• Article スキーマでは image が必須です。ページに明確なメイン画像がない場合は、推測せずに {REPLACE: hero image URL} のプレースホルダーを残してください。
• このスキルによる SE Ranking の利用は、読み取り中心です。ステップ 7（競合ベンチマーク）を依頼されない限り、SE Ranking クレジットは消費しません。依頼された場合は DATA_getSerpResults により SE Ranking クレジットを約 5～10 消費します。Firecrawl のコストは別途かかります。対象 URL で 1 クレジット、ステップ 7 の実行時にさらに 10 クレジットです。
• デプロイ後に検証してください： 生成したスキーマを CMS に貼り付けて再デプロイしたら、同じ URL でこのスキルを再実行してください。新しい実行結果の「Currently present」セクションでライブ状態を確認し、スキーマが実際に表示されていること（CMS に保存されただけで、まだ公開されていない状態ではないこと）を確認できます。代替手段として、URL に対して seo-firecrawl を実行し、META.md で想定される @type を検索する方法もあります。