schema-markup

schema-markup スキルの概要

schema-markup スキルでできること

schema-markup スキルは、実際のページに対して有効な schema.org パターンを使い、構造化データの追加・修正・改善を進めるためのスキルです。特に JSON-LD を中心に、Google で可視化されるリッチリザルトの可能性を意識した設計になっています。すでにマークアップしたいページは決まっていて、「どの schema type を選ぶべきか」「必須プロパティは何か」「そのまま実装できるコード例が欲しい」といった判断を素早く進めたいときに、schema-markup スキルは特に役立ちます。

schema-markup を導入すべき人

この schema-markup スキルは、ドキュメントを手探りで読むのではなく、確度高く構造化データを実装したい SEO チーム、コンテンツマーケター、Web 開発者、サイト運営者に向いています。特に相性がよいのは次のケースです。

• マーケティングサイトや SaaS ホームページ
• ブログや記事テンプレート
• product、software、FAQ、event、local business 系のページ
• 不正確または不完全なマークアップを整理したいチーム

ユーザーが本当に解決したい仕事

多くのユーザーが求めているのは、構造化データの理論講座ではありません。すぐに必要なのは、実務で使える判断です。

• このページにはどの schema type が合うのか？
• 複数の schema type は組み合わせてよいのか？
• 今の時点で追加する価値があるプロパティは何か？
• 過剰な主張をせず、安全に実装できる範囲はどこか？
• 今日このページテンプレートに入れるべき JSON-LD は何か？

このスキルは、単に schema type を列挙するのではなく、こうした判断を前提に設計されています。

schema-markup スキルが他と違う点

schema-markup スキルの最大の違いは、「考えられる schema を全部入れる」方向ではなく、ページの実態に合った正確なマークアップへ導いてくれる点です。リポジトリには references/schema-examples.md という実用的なファイルもあり、Organization、WebSite、Article、Product、SoftwareApplication、FAQPage、HowTo、BreadcrumbList、LocalBusiness、Event など、よく使う型の具体例がまとまっています。一般的なプロンプトよりも、すぐ使える判断材料と実装イメージが手に入りやすい構成です。

インストール前に知っておきたい大きな制約

これは crawler でも validator でも live-page scanner でもありません。schema-markup スキルは、あなたが渡したページ情報を前提に動きます。入力が曖昧だと、出力は見た目こそ整っていても、適格性や実装の観点では誤っている可能性があります。また、主眼はマークアップの生成と選定にあり、より広い technical SEO 診断まではカバーしません。

schema-markup スキルの使い方

schema-markup スキルをインストールする

リポジトリからのインストールは次のコマンドです。

npx skills add https://github.com/coreyhaines31/marketingskills --skill schema-markup

インストール前に評価したい場合は、次のファイルを確認してください。

• skills/schema-markup/SKILL.md
• skills/schema-markup/references/schema-examples.md
• skills/schema-markup/evals/evals.json

この 3 つを見れば、発動条件、期待される出力、使えるパターン例といった重要点をおおむね把握できます。

最初に読むべきファイル

読む順番は次の通りです。

1. ワークフローと判断ルールを確認する SKILL.md
2. そのまま参考にできる JSON-LD パターンを見る references/schema-examples.md
3. 実際に「よい出力」がどう見えるかを把握する evals/evals.json

特に evals は有用です。まず文脈を確認すること、関連する schema type を選ぶこと、必要なら @graph を使うこと、完全な JSON-LD を出すこと、さらに validation を勧めることなど、このスキルが想定する挙動が具体的に読み取れます。

schema-markup を使うときの最適な入力形式

schema-markup スキルは、「schema を追加して」のような抽象的な依頼より、ページ単位の事実情報を渡したときに最も力を発揮します。含めたい情報は次の通りです。

• page URL または page type
• ページの目的
• ページ上で実際に見えている entity
• ビジネスタイプ
• 狙いたい rich result があればその内容
• 現在入っている schema やエラー
• CMS または framework
• 実際に埋められるフィールド

弱い依頼の例:

• “Add schema markup for SEO.”

強い依頼の例:

• “Create JSON-LD for our SaaS homepage. We are a project management platform. Visible elements include company name, logo, product overview, customer logos, pricing link, and site search. We want Organization, WebSite, and the most appropriate product-related type. We deploy in Next.js and can inject one script in the layout.”

ざっくりした目的を使えるプロンプトに変える

よい schema-markup プロンプトでは、4 つの出力を求めるのが効果的です。

1. 推奨 schema type
2. 各選定理由
3. 完全な JSON-LD
4. validation と実装上の注意点

プロンプト構成の例:

• “Use the schema-markup skill.”
• “First determine the page type and rich result eligibility.”
• “Then recommend the minimal correct schema set.”
• “Generate production-ready JSON-LD.”
• “Flag any claims that are unsupported by visible content.”
• “Tell me where to place it in our template.”

単にサンプルコードを求めるより、この形のほうが信頼できる出力になりやすいです。

schema-markup が得意なページタイプ

リポジトリ内の examples と evals から見ると、schema-markup スキルが特に強いのは次の領域です。

• ホームページ向けの Organization と WebSite
• ブログ／記事マークアップ
• Product と SoftwareApplication
• FAQPage
• HowTo
• BreadcrumbList
• LocalBusiness
• Event
• @graph を使う複合ページ実装

ページがこれらのいずれかに明確に当てはまるなら、導入判断はしやすいはずです。

schema-markup で @graph を使うべき場面

1 ページに複数の entity や役割が正当に存在するなら、@graph を使うのが適切です。たとえば次のようなケースです。

• Organization + WebSite を持つホームページ
• Organization + WebSite + SoftwareApplication を含む SaaS ホームページ
• Article + BreadcrumbList を持つ記事ページ

ここは実務上かなり重要です。チームによっては複数の script に不自然に分割したり、1 つの type に無関係なプロパティを詰め込みすぎたりしがちですが、このスキルの examples と evals は、より整理された複数 type のモデル化を促しています。

SEO コンテンツ向け schema-markup の実践フロー

SEO コンテンツで schema-markup を使うなら、実務フローは次の形が現実的です。

1. ページの主目的を特定する
2. 実際に表示されている内容を確認する
3. 最小限で有効な schema セットを選ぶ
4. JSON-LD を生成する
5. テンプレートまたはページコンポーネントへ実装する
6. Google Rich Results Test と Schema.org Validator で検証する
7. 公開後にマークアップと実ページ内容を照合する

SEO コンテンツチームにとっては、レンダリングされたページと一致しないリッチリザルト狙いのマークアップを追加してしまう、よくある失敗を避けやすくなります。

出力品質を左右する実装向け入力のコツ

次の情報を入れると、結果の質がかなり変わります。

• canonical URL、logo URL、image URL を渡す
• ratings、pricing、FAQ が本当に表示されているか明示する
• そのページが transactional、editorial、navigational、local のどれに近いか伝える
• Next.js、WordPress、head-script injection などの framework 制約を書く
• マークアップを minimal にしたいか comprehensive にしたいか伝える

こうした情報がないと、type の選定は合っていても、プロパティの網羅性が弱くなりがちです。

schema-markup 導入後の検証ステップ

マークアップ生成後は、次のツールで検証します。

• Google Rich Results Test
• Schema.org Validator

そのうえで手動でも確認してください。

• マークアップした各フィールドが実際にページ上に存在するか
• URL が absolute URL になっているか
• 日付が有効な形式か
• 画像が crawl 可能か
• 複数 entity がテンプレートをまたいで不整合に重複していないか

このリポジトリは繰り返し「まず正確さ」を重視しており、その姿勢は導入時にも適切です。

リポジトリ由来で流用しやすい代表パターン

同梱の examples ファイルは、特に次の用途でパターン集として使う価値があります。

• sameAs と contactPoint を含む Organization
• SearchAction を含む WebSite
• 完全な FAQ の question/answer ネスト
• product 系・software 系 entity の組み立て
• Next.js での実装例

つまり、この schema-markup ガイドは概念説明にとどまらず、スターターキットとして実際に使えます。

schema-markup スキル FAQ

schema-markup は通常の AI プロンプトより優れていますか？

実装できるマークアップを求めるなら、通常は yes です。一般的なプロンプトでも文法的に正しい JSON-LD は出せますが、type の選定を誤ったり、重要なプロパティを落としたり、ページ上に存在しないものまでマークアップしたりしがちです。schema-markup スキルは、ページ適合性、正確性、複数 schema の組み合わせについて、より明確な方針を持っています。

schema-markup スキルは初心者向けですか？

はい。ページ内容を明確に説明できるなら、初心者でも十分使えます。schema.org の深い知識がなくても価値は得られます。ただし、事実ベースのページ情報を渡す必要はあります。魔法ではないので、欠けている事業情報を安全に推測して埋めてくれるわけではありません。

既存の壊れたマークアップ修正にも schema-markup は使えますか？

はい。これは特に相性のよい用途の 1 つです。現在のマークアップ、ページタイプ、実際に見えているコンテンツを渡してください。そして、不一致を洗い出し、根拠のないプロパティを削除し、JSON-LD を整理して書き直すよう依頼すると効果的です。

schema-markup は rich results を保証しますか？

いいえ。schema-markup スキルは適格性や実装品質を高める助けにはなりますが、rich results を表示するかどうかは Google が判断します。正しいマークアップだけでなく、ページ品質、コンテンツ種別、検索需要も影響します。

どんなときは schema-markup を使うべきではありませんか？

次のような場面では、このスキル単体に頼るべきではありません。

• technical SEO の包括的な監査
• 大規模な live site crawling
• 順位変動や ranking の診断
• JavaScript rendering analysis
• 幅広いコンテンツ戦略の策定

schema-markup が得意なのは、サイト全体の SEO トラブルシュートではなく、ページ単位の structured data 判断です。

SaaS やマーケティングサイトでも schema-markup は有効ですか？

はい。evals でも、Organization、WebSite、SoftwareApplication を使うホームページ系ユースケースが明示的に示されています。そのため、ecommerce 中心の schema ガイドよりも、現代的な B2B や SaaS チームにとって実用性が高い内容です。

schema-markup スキルを改善するには

schema-markup が推測できないページ事実を渡す

出力を最も早く改善する方法は、次の情報を明示することです。

• ページの正確な目的
• 実際に見えている要素
• ブランド名と URL
• 該当する場合の author、publisher、date、price、rating、FAQ、event データ
• 法的または技術的に主張できること／できないこと

これによって誤った仮定が減り、プロパティの欠落も少なくなります。

コードを求める前に schema の判断をさせる

よりよいプロンプトの順序は次の通りです。

1. “Decide the correct schema types.”
2. “Explain why each fits.”
3. “List missing data needed for a complete implementation.”
4. “Then generate final JSON-LD.”

この流れなら、type 選定のミスを早い段階で見つけやすく、用途が混ざったページでも schema-markup スキルの信頼性が大きく上がります。

最大の失敗パターンは過剰マークアップ

schema で最もありがちなミスは、ページ上に明確に存在しないものまでマークアップしてしまうことです。たとえば次のようなケースです。

• 非表示、またはユーザー向けではない FAQ に FAQPage を付ける
• 目視できる根拠がないのに Review や rating データを入れる
• 実際の product detail がない一般的なブランドページに Product を付ける
• 実態はブログ記事なのに HowTo を付ける

schema-markup を保守的に使うほうが、結果的にはうまくいくことが多いです。

関係性を明示して複数 entity の出力を改善する

複数 type を依頼する場合は、それぞれの関係も伝えてください。

• “This page is the company homepage”
• “The article belongs to this publisher”
• “The software application is the main product described here”
• “Breadcrumbs are rendered above the H1”

これにより、つながりのない entity 群ではなく、整理された @graph 出力になりやすくなります。

examples ファイルを品質基準として使う

出力をそのまま公開する前に、references/schema-examples.md と見比べてください。自分の結果に、その type で期待される構造パターンが入っているかを確認します。schema.org 全体を読み込まなくても schema-markup の使い方を改善できる、かなり実践的な方法です。

初稿をそのまま採用せず、2 回目の調整をかける

最初の出力のあと、次のような追加入力をすると精度が上がります。

• “Strip this to only required and high-value recommended properties.”
• “Rewrite for a blog post rather than a generic article.”
• “Convert this to a single @graph block.”
• “Adapt this for Next.js server-rendered injection.”
• “Audit this against the visible page content and remove unsupported fields.”

schema-markup スキルが production-ready になるのは、この 2 回目の詰めであることが少なくありません。

schema-markup は validation と SERP 現実チェックと組み合わせる

強い JSON-LD であっても、次の観点で確認すべきです。

• 実際にレンダリングされたページ内容
• validation ツール
• そのページタイプで狙う rich result が現実的かどうか

最適な schema-markup ワークフローは「一度生成して貼る」ではなく、「生成し、検証し、整合を取り、公開する」です。