schema-markup

Schema Markup 是一个面向结构化数据与 schema.org 标记的专家型技能，用于在网站上添加、修复或优化 schema markup。当用户提到「schema markup」「structured data」等时触发，目标是实现能被搜索引擎理解的标记，从而获得搜索中的富媒体结果。

用途

帮助搜索引擎理解网页内容，并让页面有资格展示富媒体搜索结果。该技能覆盖从评估、实施到验证的完整流程。

初始评估

技能要求先检查产品营销上下文：若存在 .agents/product-marketing-context.md（旧版为 .claude/product-marketing-context.md），应先读取，再仅询问其中未覆盖或本任务特有的信息。实施 schema 前需理解三方面：

页面类型：页面是什么类型、主要内容是什么、可能有哪些富媒体结果。
当前状态：是否已有 schema、实现是否存在错误、已出现哪些富媒体结果。
目标：定位哪些富媒体结果、业务价值是什么。

核心原则

准确性优先：schema 必须准确反映页面内容，不为不存在的内容做标记，内容变化时保持更新。
使用 JSON-LD：Google 推荐 JSON-LD 格式，更易实现与维护，可放在 <head> 或 <body> 末尾。
遵循 Google 指南：只使用 Google 支持的标记，避免垃圾手段，审查资格要求。
全部验证：部署前测试，监控 Search Console，及时修复错误。

常见 Schema 类型

Organization：用于公司主页/关于页，必需属性 name、url。
WebSite：用于主页（搜索框），必需 name、url。
Article：用于博客文章、新闻，必需 headline、image、datePublished、author。
Product：用于产品页，必需 name、image、offers。
SoftwareApplication：用于 SaaS/应用页，必需 name、offers。
FAQPage：用于 FAQ 内容，必需 mainEntity（问答数组）。
HowTo：用于教程，必需 name、step。
BreadcrumbList：用于任何含面包屑的页面，必需 itemListElement。
LocalBusiness：用于本地商家页，必需 name、address。
Event：用于活动、网络研讨会，必需 name、startDate、location。完整 JSON-LD 示例见 references/schema-examples.md。

快速参考

Organization（公司页）：必需 name、url；推荐 logo、sameAs（社交资料）、contactPoint。
Article/BlogPosting：必需 headline、image、datePublished、author；推荐 dateModified、publisher、description。
Product：必需 name、image、offers（价格 + 库存可用性）；推荐 sku、brand、aggregateRating、review。
FAQPage：必需 mainEntity（Question/Answer 对数组）。
BreadcrumbList：必需 itemListElement（含 position、name、item 的数组）。

组合多种 Schema 类型

可在同一页面使用 @graph 组合多种 schema 类型： { "@context": "https://schema.org", "@graph": [ { "@type": "Organization", ... }, { "@type": "WebSite", ... }, { "@type": "BreadcrumbList", ... } ] }

验证与测试

工具：

Google Rich Results Test：https://search.google.com/test/rich-results
Schema.org Validator：https://validator.schema.org/
Search Console：Enhancements 报告常见错误：缺少必需属性（参照 Google 文档核对必需字段）；值无效（日期须为 ISO 8601，URL 须为完整限定地址，枚举值须精确）；与页面内容不匹配（schema 与可见内容不一致）。

实施方式

静态站点：在 HTML 模板中直接添加 JSON-LD，使用 includes/partials 复用 schema。
动态站点（React、Next.js）：使用渲染 schema 的组件，服务端渲染以利于 SEO，将数据序列化为 JSON-LD。
CMS / WordPress：使用插件（Yoast、Rank Math、Schema Pro）、主题修改，或将自定义字段转为结构化数据。

输出格式

提供完整的 JSON-LD 代码块（含 @context、@type 与完整标记），并附测试清单：能在 Rich Results Test 中验证通过、无错误或警告、与页面内容匹配、包含所有必需属性。

任务特定问题

这是什么类型的页面？
希望获得哪些富媒体结果？
有哪些数据可用于填充 schema？
页面上是否已有 schema？
技术栈是什么？

技能介绍

用途