schema-markup

schema-markup 技能概览

schema-markup 技能能做什么

schema-markup 技能可以帮助你在真实页面上添加、修复或升级结构化数据，使用符合 schema.org 规范的模式，并明显偏向 JSON-LD 以及 Google 可展示的富结果机会。它最适合这样的场景：你已经明确要标记的是哪个页面，但希望更快判断该用哪种 schema 类型、哪些属性是必需的，以及直接拿到可实施的代码示例。

谁适合安装 schema-markup

如果你的团队需要把结构化数据尽快上线，又不想在文档里反复猜测，schema-markup 技能会很合适。尤其适用于 SEO 团队、内容营销人员、Web 开发者和网站负责人。典型适用场景包括：

• 营销官网和 SaaS 首页
• 博客和文章模板
• 产品、软件、FAQ、活动和本地商家页面
• 正在清理错误或不完整 markup 的团队

它真正解决的工作任务是什么

大多数用户并不是想上一堂结构化数据理论课，而是要尽快回答这些实际问题：

• 这个页面最适合哪种 schema 类型？
• 多种 schema 类型能不能组合使用？
• 现阶段哪些属性最值得加？
• 哪些内容可以安全实现，而不会过度声明？
• 今天这个页面模板里到底该放什么 JSON-LD？

这个技能是围绕这些决策设计的，而不只是列一份 schema 类型清单。

schema-markup 技能的差异点在哪里

schema-markup 最突出的特点，是它会引导你做“与页面内容准确匹配”的标记，而不是“把能加的 schema 全都加上”。仓库里还有一个很实用的 references/schema-examples.md 文件，提供了常见类型的具体示例，例如 Organization、WebSite、Article、Product、SoftwareApplication、FAQPage、HowTo、BreadcrumbList、LocalBusiness 和 Event。相比泛泛而谈的通用提示词，这让它更容易直接落地。

安装前最需要知道的限制

它不是爬虫、验证器，也不是实时页面扫描工具。schema-markup 技能依赖你提供的页面事实信息。如果输入很模糊，输出看起来可能很完整、很专业，但在资格判断或实际实现上依然可能出错。它的重点也在于 markup 的选择与生成，而不是更广义的技术 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

这三个文件基本覆盖了你最关心的信息：触发条件、输出预期，以及示例模式。

先读这几个文件

建议按这个顺序阅读：

1. SKILL.md：了解工作流和决策规则
2. references/schema-examples.md：查看可直接参考的 JSON-LD 模式
3. evals/evals.json：理解实际场景里“好输出”应该长什么样

其中 evals 特别值得看，因为它直接体现了预期行为：先检查上下文、选择相关 schema 类型、必要时使用 @graph、输出完整的 JSON-LD，并建议进行验证。

schema-markup 的最佳输入方式

schema-markup 技能最适合接收“页面级事实信息”，而不是一句泛泛的“加个 schema”。建议至少提供：

• 页面 URL 或页面类型
• 页面目的
• 页面上真实可见的实体内容
• 业务类型
• 目标富结果（如果有）
• 当前已有的 schema 或报错情况
• CMS 或前端框架
• 你实际能填充的数据字段

一个较弱的请求：

• “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 提示词，最好明确要求四类输出：

1. 推荐的 schema 类型
2. 每种选择的理由
3. 完整的 JSON-LD
4. 验证与实施说明

示例提示词结构：

• “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 擅长处理的页面类型

结合仓库里的示例和 evals 来看，schema-markup 最强的页面类型包括：

• 首页 Organization 和 WebSite
• 博客 / 文章 markup
• Product 和 SoftwareApplication
• FAQPage
• HowTo
• BreadcrumbList
• LocalBusiness
• Event
• 使用 @graph 的混合页面实现

如果你的页面能清晰映射到这些类型之一，上手和落地都会比较顺畅。

schema-markup 什么时候该用 @graph

当一个页面确实同时包含多个实体或页面角色时，就应该考虑用 @graph，例如：

• 首页同时有 Organization + WebSite
• SaaS 首页同时有 Organization + WebSite + SoftwareApplication
• 文章页同时有 Article + BreadcrumbList

这一点很重要，因为很多团队要么把 markup 生硬地拆散到多个脚本里，要么把无关属性全塞进一个类型中。schema-markup 的示例和 eval 预期都明显倾向于更干净的多类型建模方式。

面向 SEO 内容团队的 schema-markup 实用工作流

一个实用的 schema-markup 使用流程通常是：

1. 明确页面的核心目的
2. 确认可见内容到底有哪些
3. 选择最小但有效的 schema 组合
4. 生成 JSON-LD
5. 实现到模板或页面组件中
6. 在 Google Rich Results Test 和 Schema.org Validator 中验证
7. 发布后再对照线上页面内容复查 markup

对于 SEO 内容团队来说，这能有效避免一个常见错误：为了追求富结果而添加了与最终渲染页面并不匹配的 markup。

会显著影响输出质量的实现细节

下面这些输入信息，会明显提升结果质量：

• 提供 canonical URL、logo URL 和图片 URL
• 明确说明评分、价格或 FAQ 是否真的在页面上可见
• 说明页面属于交易型、编辑型、导航型还是本地型
• 提及类似 Next.js、WordPress 或 head-script injection 这类框架限制
• 告诉技能你希望 markup 是精简版还是完整覆盖版

缺少这些细节时，模型可能能选对类型，但属性覆盖会偏弱。

安装 schema-markup 后的验证步骤

生成 markup 之后，建议用以下工具验证：

• Google Rich Results Test
• Schema.org Validator

然后再手动检查：

• 每个被标记的字段在页面上是否真实存在
• URL 是否都是绝对路径
• 日期格式是否有效
• 图片是否可抓取
• 多个实体是否在不同模板中被不一致地重复定义

从仓库整体思路来看，它始终优先强调准确性，这也是正确的采用方式。

可直接借用的常见仓库模式

仓库附带的示例文件很值得当作模式库来用，尤其适合参考这些场景：

• 带有 sameAs 和 contactPoint 的 Organization
• 带 SearchAction 的 WebSite
• 完整的 FAQ 问答嵌套结构
• 产品类与软件类实体的设置方式
• 一个 Next.js 实现示例

也就是说，schema-markup 不只是讲概念，它本身就可以作为上手即用的 starter kit。

schema-markup 技能 FAQ

schema-markup 比普通 AI 提示词更好吗？

大多数情况下是的，尤其当你的目标是可直接实施的 markup。普通提示词也许能生成语法上正确的 JSON-LD，但仍可能选错类型、漏掉关键属性，或者给页面上根本不存在的内容做标记。schema-markup 在页面匹配度、准确性和多 schema 组合上更有明确倾向。

schema-markup 技能对新手友好吗？

友好，前提是你能把页面描述清楚。你不需要对 schema.org 有很深的了解，也能从中获得价值。但新手仍然需要提供真实、明确的页面信息。这个技能不是魔法，不会安全地替你推断缺失的业务细节。

schema-markup 能帮助修复已有的错误 markup 吗？

可以，而且这是它非常适合的一类用法。把当前 markup、页面类型以及页面上真实可见的内容一起提供给它，并要求它识别不匹配项、移除没有依据的属性，并重新整理出干净的 JSON-LD。

schema-markup 能保证拿到富结果吗？

不能。schema-markup 技能可以提升富结果资格和实现质量，但是否展示富结果，最终由 Google 决定。正确的 markup、页面质量、内容类型以及搜索需求，都会影响结果。

什么情况下不该只依赖 schema-markup？

如果你需要以下能力，就不要只依赖这个技能：

• 完整的技术 SEO 审计
• 大规模在线站点爬取
• 排名诊断
• JavaScript 渲染分析
• 更广泛的内容策略规划

它最适合做页面级结构化数据决策，而不是整站 SEO 排障。

schema-markup 对 SaaS 和营销型网站有用吗？

有用。evals 已经明确指向首页类场景，例如 Organization、WebSite 和 SoftwareApplication 这类建模方式。相比只关注电商场景的 schema 指南，它对现代 B2B 和 SaaS 团队更有现实意义。

如何改进 schema-markup 技能的使用效果

给 schema-markup 提供它无法自行推断的页面事实

想最快提升输出质量，最有效的方法就是补充这些信息：

• 页面准确用途
• 页面上的可见元素
• 品牌名称和 URL
• 在相关场景下提供作者、发布者、日期、价格、评分、FAQ 或活动数据
• 明确哪些内容你在法律或技术上可以声明，哪些不可以

这样能减少错误假设，并提升属性完整度。

先让 schema-markup 做 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.”

这样可以更早发现类型选择错误，尤其在页面目的混杂时，会让 schema-markup 的可靠性高很多。

避开最大的失败模式：过度标记

最常见的 schema 错误，就是给页面上并没有明确呈现的内容强行加标记。例如：

• 把隐藏的或用户不可见的 FAQ 标成 FAQPage
• 没有可见依据却加上 Review 或评分数据
• 在泛品牌页上使用 Product，但页面其实没有真正的产品详情
• 把本质上是博客文章的页面标成 HowTo

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

用明确关系提升多实体 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”

这样能帮助 schema-markup 生成更干净的 @graph 输出，而不是彼此割裂的实体集合。

把示例文件当作 schema-markup 质量基准

正式上线前，把输出结果与 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 真正达到可生产使用的状态，恰恰是在第二轮细化之后。

让 schema-markup 配合验证工具和 SERP 现实检查一起使用

即便 JSON-LD 看起来已经很完整，仍然应该结合以下内容一起检查：

• 页面实际渲染出来的内容
• 验证工具结果
• 目标富结果对该页面类型是否现实可行

最好的 schema-markup 工作流不是“生成一次然后直接粘贴”，而是“生成、验证、校对、发布”。