schema-markup

schema-markup 技能總覽

schema-markup 技能是做什麼的

schema-markup 技能可協助你在實際頁面上新增、修正或升級結構化資料，採用有效的 schema.org 模式，並明確偏向使用 JSON-LD 以及 Google 可辨識的 rich result 機會。當你已經知道要標記的是哪一個頁面，但希望更快判斷適合的 schema 類型、必要屬性，以及可直接落地實作的程式碼範例時，這個技能特別實用。

哪些人適合安裝 schema-markup

這個 schema-markup 技能很適合 SEO 團隊、內容行銷人員、網站開發者，以及需要在不反覆查文件的情況下快速交付結構化資料的網站擁有者。尤其適合以下情境：

• 行銷網站與 SaaS 首頁
• 部落格與文章範本
• 產品、軟體、FAQ、活動與在地商家頁面
• 正在清理不正確或不完整標記的團隊

使用者真正要解決的問題

大多數使用者並不是想上結構化資料理論課。他們需要快速回答實務問題：

• 這個頁面適合哪一種 schema 類型？
• 多種 schema 類型可以一起用嗎？
• 哪些屬性值得現在就補上？
• 哪些內容可以安全實作、不會過度宣稱？
• 今天這個頁面範本裡應該放什麼樣的 JSON-LD？

這個技能的設計核心就是幫你做出這些決策，而不只是列出一串 schema 類型。

schema-markup 技能與其他工具的差異

schema-markup 技能最明顯的差異，在於它會引導你產出與頁面內容相符、較精準的標記，而不是走「能加的 schema 全都加上去」的路線。repository 也提供了很實用的 references/schema-examples.md，裡面有常見類型的具體範例，例如 Organization、WebSite、Article、Product、SoftwareApplication、FAQPage、HowTo、BreadcrumbList、LocalBusiness 與 Event。因此它比一般泛用 prompt 更容易直接拿來實作。

安裝前要先知道的最大限制

這不是 crawler、validator，也不是即時頁面掃描器。schema-markup 技能仰賴你提供的頁面事實資訊。如果你的輸入很模糊，輸出即使看起來完整專業，也可能在 eligibility 或實作層面出錯。它的重點也放在標記生成與類型選擇，而不是更廣泛的 technical SEO 診斷。

如何使用 schema-markup 技能

安裝 schema-markup 技能

可用以下指令從 repo 安裝：

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

這三個檔案幾乎已經涵蓋最重要的資訊：觸發條件、輸出預期，以及實際範例模式。

先讀這些檔案

建議依照以下順序閱讀：

1. SKILL.md：理解 workflow 與判斷規則
2. references/schema-examples.md：直接參考可複製的 JSON-LD 模式
3. evals/evals.json：看實務上什麼叫做「好的輸出」

其中 evals 特別值得看，因為它能直接反映這個技能預期的行為方式：先檢查脈絡、選擇相關 schema 類型、必要時使用 @graph、提供完整的 JSON-LD，並建議進行驗證。

schema-markup 最佳輸入格式

schema-markup 技能最適合接收「頁面層級的事實」，而不是只丟一句「幫我加 schema」。建議至少提供：

• page URL 或 page type
• 頁面用途
• 頁面上看得到的實體／內容元素
• business type
• 目標 rich result（如果有）
• 目前已有的 schema 或錯誤
• CMS 或 framework
• 你實際能填入的欄位

一個弱的請求：

• 「幫我加 schema markup 做 SEO。」

一個強的請求：

• 「為我們的 SaaS 首頁建立 JSON-LD。我們是專案管理平台。頁面上可見元素包含公司名稱、logo、產品概述、客戶 logo、pricing 連結與站內搜尋。我們想要 Organization、WebSite，以及最合適的產品相關類型。我們使用 Next.js 部署，且可以在 layout 中注入一段 script。」

把模糊目標變成可用的 prompt

一個好的 schema-markup prompt，最好明確要求四種輸出：

1. 建議的 schema 類型
2. 每個選擇的理由
3. 完整的 JSON-LD
4. 驗證與實作注意事項

範例 prompt 結構：

• 「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.」

這樣的 framing，通常比單純要求提供 sample code 更可靠。

schema-markup 特別擅長處理的頁面類型

從 repository 的 examples 與 evals 來看，schema-markup 技能最強的場景包括：

• 首頁的 Organization 與 WebSite
• blog/article 標記
• Product 與 SoftwareApplication
• FAQPage
• HowTo
• BreadcrumbList
• LocalBusiness
• Event
• 使用 @graph 的混合型頁面實作

如果你的頁面能清楚對應到上述類型之一，導入通常會很順利。

schema-markup 什麼時候該用 @graph

當同一個頁面合理地同時包含多個實體或多種頁面角色時，就應考慮使用 @graph，例如：

• 首頁同時有 Organization + WebSite
• SaaS 首頁同時有 Organization + WebSite + SoftwareApplication
• 文章頁同時有 Article + BreadcrumbList

這一點很重要，因為不少團隊不是把標記生硬拆成多段 script，就是把彼此無關的屬性硬塞進同一種類型。這個技能的範例與 eval 預期，明顯更傾向結構乾淨的多類型建模方式。

schema-markup 用於 SEO 內容的實務流程

一個實際可行的 schema-markup 使用流程如下：

1. 先確認頁面的主要目的
2. 確認哪些內容是真正在頁面上可見的
3. 選出最小且有效的 schema 組合
4. 生成 JSON-LD
5. 實作到 template 或 page component
6. 用 Google Rich Results Test 與 Schema.org Validator 驗證
7. 發布後再比對 markup 與實際頁面內容是否一致

對 SEO 內容團隊來說，這能有效避免常見錯誤：為了 rich result 而加上與實際渲染頁面不符的標記。

會直接影響輸出品質的實作細節

有幾種輸入資訊，會明顯提升結果品質：

• 提供 canonical URL、logo URL 與 image URLs
• 明確說明 ratings、pricing 或 FAQs 是否真的在頁面上可見
• 指出頁面屬於 transactional、editorial、navigational 或 local
• 說明像 Next.js、WordPress 或 head-script injection 這類 framework 限制
• 告訴技能你要的是精簡版還是完整型 markup

少了這些細節，模型即使選對類型，屬性的覆蓋程度也可能偏弱。

安裝 schema-markup 後的驗證步驟

產生 markup 後，請用以下工具驗證：

• Google Rich Results Test
• Schema.org Validator

接著再人工確認：

• 每一個被標記的欄位都確實存在於頁面上
• URL 都是 absolute
• 日期格式有效
• 圖片可被 crawl
• 多個實體不會在不同 template 中被重複且不一致地標記

從 repository 的整體寫法可以看出，它反覆強調的是「先求正確，再求擴充」，這也是最適合採用 schema-markup 的心態。

可以直接借用的常見 repository 模式

內建的 examples 檔很值得當成 pattern library 使用，尤其適合參考：

• 帶有 sameAs 與 contactPoint 的 Organization
• 帶有 SearchAction 的 WebSite
• 完整的 FAQ 問答巢狀結構
• 類產品與軟體相關實體的設定方式
• 一個 Next.js 的實作範例

這代表 schema-markup 不只是概念型指南，也可以當成實作起手式工具包。

schema-markup 技能 FAQ

schema-markup 會比一般 AI prompt 更好嗎？

通常會，前提是你的目標是拿到可直接實作的 markup。一般 prompt 也許能產出語法正確的 JSON-LD，但仍可能選錯類型、漏掉重要屬性，或替頁面上根本不存在的內容加上標記。schema-markup 技能對頁面適配性、標記正確性，以及多 schema 組合方式有更明確的判斷。

schema-markup 技能對新手友善嗎？

友善，只要你能清楚描述頁面即可。你不需要非常深入的 schema.org 知識也能得到價值。不過新手仍然必須提供真實、具體的頁面資訊。這個技能不是魔法，無法安全推斷你沒有提供的商業細節。

schema-markup 能幫忙修正既有的錯誤標記嗎？

可以。這其實是它很適合的一種用法。把目前的 markup、頁面類型，以及實際可見內容一起提供給它，要求它找出不一致之處、移除沒有依據的屬性，並重新整理成乾淨的 JSON-LD。

schema-markup 能保證 rich results 嗎？

不能。schema-markup 技能可以提升 eligibility 與實作品質，但是否顯示 rich results 仍由 Google 決定。正確的標記、頁面品質、內容類型，以及搜尋需求都會影響結果。

什麼情況不該只靠 schema-markup？

當你需要以下工作時，不應只依賴這個技能：

• 完整的 technical SEO audit
• 大規模的 live site crawling
• 排名診斷
• JavaScript rendering analysis
• 廣泛的內容策略規劃

它最適合的是頁面層級的結構化資料決策，而不是整站 SEO 疑難排解。

schema-markup 對 SaaS 與行銷網站有幫助嗎？

有。evals 很明確地指向首頁場景，例如 Organization、WebSite 與 SoftwareApplication 這類建模方式。因此相較於只聚焦 ecommerce 的 schema 指南，它對現代 B2B 與 SaaS 團隊更有參考價值。

如何提升 schema-markup 技能的使用效果

提供 schema-markup 無法自行推斷的頁面事實

要最快提升輸出品質，最有效的方法就是提供：

• 精確的頁面用途
• 可見元素
• 品牌名稱與 URLs
• 視情況提供 author、publisher、date、price、rating、FAQ 或 event 資料
• 哪些內容你可以、哪些內容你不能在法律或技術上宣稱

這能降低錯誤假設，也能讓屬性更完整。

先要求 schema 判斷，再要求程式碼

更好的 prompt 順序通常是：

1. 「先判斷正確的 schema 類型。」
2. 「說明每一種為什麼適合。」
3. 「列出完整實作前還缺哪些資料。」
4. 「再產出最終的 JSON-LD。」

這樣能提早抓出類型選錯的問題，對於用途混合的頁面，也會讓 schema-markup 技能更可靠。

避開最大失敗模式：過度標記

最常見的 schema 錯誤，就是替頁面上沒有明確出現的內容加標記。例如：

• 把隱藏或非使用者可見的 FAQ 做成 FAQPage
• 沒有可見證據卻加入 Review 或 rating 資料
• 在只有品牌介紹、沒有真實產品細節的頁面上使用 Product
• 實際上是 blog post，卻套成 HowTo

如果你以較保守的方式使用 schema-markup，結果通常會更好。

用明確關係提升多實體輸出的品質

當你要求多種類型時，請直接告訴技能它們彼此的關係：

• 「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」

這會幫助技能產出更乾淨的 @graph，而不是一堆彼此斷裂的實體。

把 examples 檔當作品質基準

在正式上線前，拿輸出結果對照 references/schema-examples.md。檢查你的結果是否包含該類型常見且預期的結構模式。這是在不必通讀整個 schema.org 的前提下，提升 schema-markup 使用品質最實際的方法之一。

不要直接收下初稿，先做第二輪迭代

拿到第一版輸出後，可以繼續追問：

• 「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。

把 schema-markup 搭配驗證與 SERP 現實檢查

即使是品質不錯的 JSON-LD，也應該拿去檢查：

• 實際渲染後的頁面內容
• 驗證工具結果
• 目標 rich result 是否真的符合該頁面類型

最理想的 schema-markup workflow 不是「生成一次就貼上」，而是「生成、驗證、校對、發布」。