schema-markup
作者 alirezarezvanischema-markup skill 可帮助 agent 规划、编写、审计并验证用于富媒体搜索结果的 JSON-LD。适用于 Article、FAQPage、HowTo、Product、LocalBusiness、Organization 和 BreadcrumbList 标记，提供实施模式、schema 类型指导，以及面向 Technical Seo 工作流的 Python validator 脚本。
该 skill 评分为 84/100，说明它很适合收录给希望让 agent 实施、审计或验证 schema markup 的目录用户，相比通用 SEO prompt 更少依赖猜测。该仓库提供了清晰的激活条件、可复用模板、schema 类型指导和 validator 脚本；不过如果能补充明确的安装说明，并更清楚说明本地 validator 能证明什么、不能证明什么，采用门槛会更低。
- frontmatter 中的触发条件非常清晰，包括 structured data、JSON-LD、rich results、FAQ/Product/HowTo schema 等正向触发，也明确排除了通用 SEO 或抓取审计场景。
- 操作内容扎实：SKILL.md 定义了上下文收集、实施/审计/验证用例，以及在提问前何时应先参考产品营销背景。
- 配套材料实用，包括 schema 类型指导、可直接复制粘贴的 JSON-LD 实施模式，以及可从 HTML 中提取并验证 JSON-LD 的 Python 脚本。
- skill 路径下没有提供安装命令或 README，因此目录用户需要根据仓库的通用约定自行推断安装方式。
- 内置 validator 可以在本地评估必填/推荐字段的覆盖情况，但参考资料仍建议使用 Google Rich Results 进行测试；它不能替代官方的富媒体搜索结果验证。
schema-markup skill 概览
schema-markup 能做什么
schema-markup skill 可帮助 AI agent 规划、编写、审计和验证 JSON-LD 结构化数据，适用于需要提升 Google rich results 展示资格、并为 AI search 提供更清晰机器可读上下文的页面。它面向 Technical Seo 场景：交付物不是泛泛的网站审计，而是可落地的 schema markup，例如 Article、BlogPosting、FAQPage、HowTo、Product、LocalBusiness、Organization、BreadcrumbList 以及相关的 schema.org 类型。
这个 skill 最适合哪些场景
当你已经知道页面类型或具体问题时，适合使用这个 schema-markup skill：例如缺少 FAQ schema、Product markup 报错、Article rich result 资格问题、Search Console 结构化数据警告，或需要在 CMS 中统一 JSON-LD 输出。它尤其适合营销人员、SEO 专家、开发者和内容团队：你需要的是可直接实施的 JSON-LD 和验证建议，而不是对 schema.org 的泛泛解释。
它和普通 prompt 有什么不同
这个 repository 包含实战参考资料、可直接复用的实施模式，以及一个 Python validator script。schema 工作往往败在细节上：绝对图片 URL、必填属性、与可见内容一致、publisher logo、ISO 日期，以及 CMS 注入限制。这个 skill 会在生成 markup 前引导 agent 完成结构化信息收集，从而降低生成“看起来合理但实际无效”的 JSON-LD 的风险。
什么时候不该用它
不要把 schema-markup 当作完整技术爬取、JavaScript 渲染诊断、内链审查或网站架构审计的替代品。如果真正的问题是可索引性、canonical、爬取深度或模板渲染，应先使用更完整的 SEO 或网站架构工作流，等目标页面和模板稳定后，再回到 schema 处理。
如何使用 schema-markup skill
schema-markup 安装方式和优先查看的文件
使用以下命令安装：
npx skills add alirezarezvani/claude-skills --skill schema-markup
安装后，先阅读 marketing-skill/skills/schema-markup/SKILL.md，了解触发规则和信息收集流程。然后查看 references/schema-types-guide.md，用于选择类型和确认必填字段；查看 references/implementation-patterns.md，获取 JSON-LD 示例；如果你想在本地对必填和推荐字段做基础检查，可以查看 scripts/schema_validator.py。
生成 JSON-LD 前需要提供哪些输入
要更好地使用 schema-markup，不要只告诉 agent“add schema”，而应提供页面级事实信息，包括：
- Page URL 和 canonical URL
- Page type，例如 product、article、FAQ、local business、how-to 或 category
- 页面可见 title、author、publish 和 modified dates
- Primary image URL 及尺寸
- Organization name、logo URL 和 sameAs profiles
- 在相关场景下提供 product price、availability、SKU、reviews 或 offers
- CMS 或实施方式，例如 WordPress plugin、Webflow custom code、Shopify theme，或是否可直接访问
<head> - 现有 Search Console errors 或 rich result test messages
较弱的 prompt 是：“Create schema for this page.”
更好的 prompt 是：“Use the schema-markup skill to create JSON-LD for this BlogPosting page. URL: https://example.com/blog/schema-guide. H1: Schema Markup Guide. Author: Jane Smith. Published: 2026-02-10. Modified: 2026-03-01. Image: https://example.com/images/schema-guide.jpg, 1200x630. Publisher logo: https://example.com/logo.png, 250x60. Match visible page content and flag any missing fields before writing final JSON-LD.”
实施时的实用工作流
先审计现有 markup。查看页面源代码，检查 Search Console 结构化数据报告，或保存渲染后的 HTML 并运行 python3 scripts/schema_validator.py page.html。然后让这个 skill 判断页面类型，并选择最窄且有效的 schema type。例如，博客文章通常应使用 BlogPosting，而交易型产品页需要使用带有 offers 的 Product。
接下来生成 JSON-LD，将每个属性与页面可见内容逐项核对，并在上线前用 Google Rich Results Test 测试。上线后，再次测试 live URL，并持续监控 Search Console。这个 skill 可以帮助解读验证信息，但不能保证一定获得 rich results；Google 是否展示取决于内容质量、政策合规性、可爬取性以及搜索需求。
提升输出质量的技巧
明确要求“implementation-ready JSON-LD plus missing-field notes”。这样可以避免 agent 悄悄编造不可用的数据。对于模板场景，要求提供带变量的可复用模式，例如 {{ product.title }} 或 {{ article.published_at }}。对于受监管或信任要求较高的页面，要求生成保守版本，只标记页面上可见的内容。对于包含多种 schema 的页面，要求 skill 用稳定的 @id 值连接实体，避免 Organization、WebPage、BreadcrumbList 和 Article 数据看起来彼此割裂。
schema-markup skill 常见问题
schema-markup 对新手友好吗？
友好，前提是你能收集页面事实并测试输出。参考资料会说明常见 schema type 的作用、哪些字段重要，以及哪些错误会阻碍资格。新手应先从一种页面类型开始，例如 Article 或 FAQPage；验证通过后，再把已验证的模式扩展到模板。
它能修复 Search Console 结构化数据错误吗？
它可以帮助解读并修复许多结构化数据错误，尤其是缺少必填属性、JSON-LD 格式错误、schema type 选错，以及 Product 或 Article 字段不完整等问题。但它无法修复由页面不可访问、脚本被阻止、模板损坏，或 Google 无法渲染的内容导致的错误。遇到这类情况，应先解决技术问题。
它和 schema plugins 有什么区别？
Plugins 可以快速注入 schema，但往往使用通用默认值，容易遗漏业务特定的实体细节，或在 theme 和 extension 之间产生重复 markup。schema-markup skill 更适合需要编辑判断、自定义 JSON-LD、模板策略，或审计 plugin 已输出内容的场景。
schema-markup 只适合 Technical Seo 团队吗？
不是，但它在 Technical Seo 工作流中最能发挥价值，因为结构化数据必须准确、可测试、可部署。内容团队可以用它规划 Article、FAQ 和 HowTo。开发者可以用它把已批准的 schema 转成模板。电商团队可以在上线前检查 Product、Offer、availability 和 review markup。
如何改进 schema-markup skill 的使用效果
提供更可靠的来源证据
提升 schema-markup 结果的最佳方式，是提供 Google 也能验证的同类证据：渲染后的页面文案、可见 headings、产品详情、作者页、图片、日期、breadcrumbs 和 organization profiles。如果某个字段页面上不可见或无法验证，应告诉 agent 将其标记为缺失，而不是编造。
留意常见的 schema-markup 失败模式
常见失败包括使用相对图片 URL、为页面上不可见的问题添加 FAQ markup、把营销文案标记成 reviews、Product schema 缺少 offers、author name 不一致、日期格式无效，以及多个 plugins 产生重复 JSON-LD。另一个常见问题是过度标记：不是选择少数能准确代表页面的 schema type，而是把所有可能的类型都加上。
首次输出后继续迭代
拿到第一版 JSON-LD 后，要求做一次验证检查：“Check required fields, recommended fields, visible-content alignment, Google rich result eligibility, and implementation risks.” 然后运行 validator script 或 Google 测试工具，并把精确错误信息粘贴回 agent。围绕具体错误迭代，通常比要求“整体重写”效果好得多。
让 skill 适配你的 CMS 和模板
如果要可重复落地，可以把一个已验证的页面升级为模板级实施方案。要求 skill 将 schema 字段映射到 CMS variables，识别字段为空时的 fallback behavior，并定义 JSON-LD 应注入的位置。这正是 schema-markup 比一次性 prompting 更有价值的地方：它可以帮助建立一个由编辑、SEO 和开发者共同维护的受控结构化数据工作流。