Schema.org 结构化数据实现 — 完整工作流技能
本技能提供了一套端到端的方法论,用于分析网站、设计 schema.org 标记并生成开发者可直接使用的工单。该方法论通过在实际项目中为多语言、多区域网站实现结构化数据而不断完善。
此方法论与客户无关。适用于任何以全面覆盖 schema.org 并通过项目管理工具(JIRA、Wrike 或类似工具)交接给开发者为目标的网站。
许可证: 此技能根据 知识共享署名 4.0 国际 (CC BY 4.0) 许可证发布。只要您给予原作者适当的署名,即可自由地为此技能做任何目的的分享和改编。
相关审计: 本技能的第 5 阶段会对照第 2 阶段设计的规范验证线上输出。当任务是在不同区域验证已报告的修复(例如,“已修复所有语言”、“已部署到所有地方”)时,请进行 JSON-LD 验证审计,并遵守本技能不包含的声明验证规范:缓存清除门控、根据站点地图索引/在线 hreflang 集进行种群枚举,以及阳性对照。面包屑工作的审计端是面包屑导航审计;本技能处理其工单端。
此技能如何工作
这是一个项目型技能,对于大多数网站通常需要 1-3 小时,分 1-2 次会话完成。复杂的多语言网站(包含许多页面类型)可能需要更长时间。该技能定义了五个连续的交付阶段:阶段 0(设置)、阶段 1(发现)、阶段 2(模式设计)、阶段 3(工单创建)和阶段 4(重构与交付)—— 然后是开发者部署后运行的两个阶段:阶段 5(部署后验证)和阶段 6(衡量影响)。Claude 应识别用户当前所处的阶段并引导他们完成该阶段。
用户提供: 项目背景、对分析和工单草案的反馈、项目特定规则以及未解决问题的决议。
Claude 提供: 页面类型发现、HTML 分析、模式设计、工单草案(父工单 + 子工单)以及最终重构的工单集。
术语说明: 本技能使用“工单”作为面向开发者的交付物的通用术语。实际格式取决于在阶段 0 中选择的项目管理平台(JIRA 工单、Wrike 任务等)。
参考文件 — 按需加载
第 1 至 6 阶段的内容存放在参考文件中,每个阶段一个文件。每个指针命名其触发器。这些加载是强制性步骤:当一个阶段开始时,在开始工作之前加载其文件——永远不要凭此核心文件即兴完成一个阶段。如果您注意到某个阶段在未加载其文件的情况下被处理,请说明这一点,加载该文件,并对照它重新检查已完成的工作。
references/discovery.md— 阶段 1:页面类型目录、分类、Google 指南检查、每页面类型分析(三种格式的现有模式、条件模式分类、语言环境交付)、保存真实数据、合并、分类。在构建页面类型目录和分析任何页面类型的 HTML 之前加载。references/schema-design.md— 阶段 2,第 2.1-2.7 节:全局和页面特定模式、@id交叉引用、弃用 vs 移除、格式迁移处置、属性选择规则、多语言属性值、验证假设、项目规则。在为任何页面类型选择模式类型或属性之前加载。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 预检清单、跨语言验证和获取技术、四个发现类别和报告模板、后续评论、URL 和源值验证、GSC 错误协调与诊断、单次获取的假阳性、来自爬取导出的覆盖率审计。在验证任何已部署的模式、确认工单完成、回复客户报告的差异以及诊断 Search Console 结构化数据错误之前加载。references/measuring-impact.md— 阶段 6:搜索外观分解、预期声明、可衡量的渠道、数据保留。在客户询问结构化数据的成效、提取任何影响数据之前加载。
章节编号(§1.2,§5.4)和规则编号(规则 35,反模式 21)在所有文件中保持一致,因此交叉引用可以通过此映射进行解析。
阶段 0:设置与工具
目标: 评估可用工具和访问权限,建立最高效的工作流程,并在开始内容工作前收集项目级别的偏好。
0.1 评估可用工具
在任何分析工作开始之前,确定可用的能力:
- 浏览器访问(例如,Chrome 扩展中的 Claude、Cowork 浏览器工具)— 使 Claude 能够直接浏览页面、捕获渲染后的 HTML、提取数据并自主验证事实。这是最高效的工作流程。
- 网络搜索 — 使 Claude 能够映射网站结构、查找站点地图,并在没有浏览器访问的情况下发现页面类型。
- 文件系统访问 — 允许增量保存分析文档和工单草案。
- 直接站点访问 — 某些站点会阻止自动访问(403 错误)。如果网页抓取失败,浏览器访问或手动 HTML 上传是备选方案。
0.2 引导用户启用浏览器访问
浏览器辅助分析是本技能的主要推荐工作流程。它使 Claude 能够:
- 自主发现和映射页面类型
- 从任何页面捕获渲染后的 HTML,无需手动复制粘贴
- 在几分钟内提取检测信号、数据源和模板结构
- 在编写工单前验证事实(URL 模式、语言变体、字段可用性)
如果浏览器访问尚不可用,请解释其优势并引导用户完成设置。用户的角色将从“HTML 收集者”(繁琐、低价值)转变为“审查者和决策者”(高价值,他们的领域专业知识在此发挥作用)。
如果浏览器访问不可用,或者站点完全阻止自动浏览,则回退到阶段 1.2 中描述的手动工作流程。
成本意识: 浏览器访问虽然能进行最彻底的分析,但会显著增加 Token 消耗——Chrome 工具调用会返回大量数据,这些数据会随着会话的进行而呈二次方增长。将浏览器工作流程保留在初始发现和验证阶段,在这些阶段实时页面检查能带来真正的价值。对于页面类型清单已经确定的任务(例如,根据已完成的审计编写工单),非浏览器工作流程同样有效且更经济。当使用浏览器时,优先使用目标明确的调用(get_page_text、find、用于精确提取的 javascript_tool),而不是重量级调用(用于完整 DOM 的 read_page、用于全部流量的 read_network_requests)。
0.3 收集项目偏好
在开始内容工作之前,询问用户:
- 项目管理平台 — “这些工单将在哪个系统中创建?(JIRA、Wrike、Asana 等)”这决定了术语(工单 vs 任务 vs 项目)、格式化约束(例如,Wrike 无法正确渲染列表项内的嵌套代码块——请参见
references/delivery.md中的 §4.4 特定平台格式化处理)以及交付文件的命名约定。 - 工单结构 — “您的组织是否有既定的开发者任务工单结构或模板?如果有,请分享模板或工单创建指南。我将根据您团队的约定调整 schema 工单。”如果不存在模板,则使用此技能的默认结构。
- 问候语和语气 — 例如,“Hi team,” 搭配对等语气,或者正式语气。
- 项目特定规则 — 隐私约束、术语、品牌规则等。(这些也可以在阶段 2 期间收集。)
阶段 1:发现与页面类型目录
目标: 构建网站上所有页面类型的完整清单,包括检测信号、现有 schema 覆盖范围以及用于工单代码示例的已保存真实数据。
在此阶段开始前加载 references/discovery.md。 它包含了整个阶段:
- 1.1 收集页面类型列表
- 1.1b 优先级评估/分类
- 1.1c 验证 Google 当前指南
- 1.2 分析每种页面类型
- 1.3 保存用于工单代码示例的真实数据
- 1.4 记录发现
- 1.5 识别合并机会
- 1.6 对每种页面类型进行分类
阶段 2:模式设计
目标: 确定为每种页面类型使用哪些 schema 类型和属性,以及 schema 在网站中如何相互关联。
在选择 schema 类型或属性之前加载 references/schema-design.md。 它包含第 2.1-2.7 节:
- 2.1 设计全局/共享模式
- 2.2 设计页面特定模式
- 2.3 设计交叉引用
- 2.4 弃用 vs 移除
- 2.4b 格式迁移工单 — 现有格式的处置
- 2.5 应用属性选择规则
- 2.5b 多语言属性值
- 2.6 在最终确定前验证假设
- 2.7 项目特定规则
§2.8 保留在此核心文件中,因为每个工单和每次验证都会应用它:
2.8 通用技术要求
这些要求适用于每个项目:
- Schema 必须服务端渲染 — 存在于服务器返回的初始 HTML 中,而非由 JavaScript 动态注入。这是 SEO 最佳实践,非项目特定偏好。
- JSON-LD 格式 — 始终在
<head>部分中实现为<script type="application/ld+json">。 - 独立的 script 标签 — 每种 schema 类型拥有自己的
<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:工单创建
目标: 生成开发者可直接使用的工单——共享模式对应一个父工单,每种页面类型(或合并的组)对应一个子工单。
在起草、修订或检查任何工单之前加载 references/ticket-writing.md。 它包含了整个阶段:
- 3.1 预检检查
- 3.2 工单结构模板
- 3.2b 子代理使用指南
- 3.3 工单编写规则
- 3.4 编写父工单
- 3.5 交付前预检清单
- 3.6 反馈与迭代工作流
- 3.7 常见模式决策
阶段 4:最终重构与交付
目标: 一次性重新生成所有工单,应用所有累积的规则、决策和更正,以确保跨工单的一致性。
在最终重构之前加载 references/delivery.md。 它包含了整个阶段:
- 4.1 制定重构计划
- 4.2 首先解决所有未解决问题
- 4.3 按顺序重构
- 4.4 特定平台格式化处理
- 交付格式决策树
- 4.5 编辑审阅
- 4.6 跨工单一致性检查
- 4.7 打包交付
- 4.8 Wrike 交付 — XLS 骨架 + HTML 粘贴
阶段 5:部署后验证
目标: 在开发者部署 schema 后,确认线上输出与规范匹配——特别关注多语言覆盖范围和数值类型的正确性。
在验证已部署的 schema、确认工单完成或诊断 Search Console 错误之前加载 references/post-deployment-verification.md。 它包含了整个阶段:
- 阶段序言 — 范围说明(已报告修复的验证转至 JSON-LD 验证审计)、全种群扫描的两个触发器以及全站工单模板清单
- 阶段 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 数据保留
此技能的完整 SKILL.md 文件到此结束。