seo-analysis

seo-analysis

在指定范围内审查代码库，找出搜索可见性风险。用户提出要求或确有帮助时，提供实施交接内容；但不要将其作为回答具体问题的前提。

此技能与框架和语言无关。应从当前代码库和渲染后的输出入手，而不要基于对 React、Next.js、Rails、Laravel、Astro、WordPress 或任何其他技术栈的假设。

决策树

你要解决什么 SEO 问题？

• 需要对代码库进行全面的技术和页面内审查

  • 阅读 references/methodology.md
  • 然后阅读 references/technical-audit.md

• 需要检查元数据、社交媒体预览、规范链接或可编入索引性

  • 阅读 references/metadata-and-previews.md

• 需要分析 schema.org / JSON-LD / 实体 / 富媒体搜索结果

  • 阅读 references/structured-data-and-entities.md

• 需要分析内容质量、信息架构、内部链接或模板级页面定位

  • 阅读 references/content-and-information-architecture.md

• 需要了解 AI 时代的搜索指南，包括抓取/渲染控制、预览控制和答案引擎就绪情况

  • 阅读 references/agentic-search-and-ai-surfaces.md

• 需要为另一个会话提供确切的修复交接格式

  • 阅读 references/fix-prompt-spec.md
  • 使用 templates/fix-prompt-template.md
  • 也可使用 python3 scripts/build_fix_prompt.py --input findings.json 生成草稿

• 需要了解边缘情况、策略陷阱或常见误报

  • 阅读 references/gotchas.md

快速参考

任务	使用	结果
对整个代码库进行审查	references/methodology.md	按顺序排列的检查清单和证据收集流程
检查可编入索引性和渲染情况	references/technical-audit.md	关于抓取、渲染、规范链接、robots、站点地图和状态码的发现
检查标题、元描述、OG、X 卡片、网站图标、站点名称	references/metadata-and-previews.md	SERP 和社交媒体预览相关发现
检查结构化数据和实体信号	references/structured-data-and-entities.md	富媒体搜索结果和知识图谱就绪情况相关发现
检查内容和链接架构	references/content-and-information-architecture.md	内容缺口、重复内容、孤立页面、锚文本薄弱等问题
检查 AI 时代的搜索就绪情况	references/agentic-search-and-ai-surfaces.md	预览控制、抓取访问、引用就绪情况
生成修复会话提示词	references/fix-prompt-spec.md + templates/fix-prompt-template.md	可复制粘贴的提示词，用于启动第二个实施会话
根据 findings JSON 生成可选的提示词草稿	python3 scripts/build_fix_prompt.py --input findings.json（在 JSON 中填入 repo）	供审阅证据、约束和验收标准的草稿

核心工作流程

1. 对照用户指定的范围和输出形式开展工作。在得出结论前，检查相关路由、模板、布局文件以及 head/元数据抽象；仅在追踪共因时扩大检查范围。
2. 检查范围内具有代表性的 URL 或模板。全面审查时，酌情涵盖首页、类别页、产品/服务页、文章/文档页、身份验证/账户页、分页/筛选页和实用工具页。
3. 按严重程度和层级分类列出发现：
   • 抓取/索引控制
   • 渲染/发现/规范化
   • 元数据/社交媒体预览
   • 结构化数据/实体信号
   • 内容/内部链接/信息架构
   • 性能/页面体验
   • AI 时代的搜索界面就绪情况
4. 对每项发现，收集来自代码、构建后的 HTML 或运行时行为的证据。能够核实的内容，不要靠猜测。
5. 确定修复优先级前，先合并共因。一个损坏的元数据抽象可能导致数百个页面出错。如果用户要求提供交接内容，或在当前范围内这样做确有帮助，请使用 references/fix-prompt-spec.md；辅助脚本是可选的，其生成的草稿不能作为证据。

审计交付内容

根据请求选择交付形式：范围明确的答复、问题发现表、完整报告或实施交接。仅在收到请求时创建文件。完整审计通常包括：

1. 执行摘要——已观察到的搜索可见性风险，不要臆造排名影响。
2. 问题发现表——严重程度、URL／模板范围、证据、影响、修复方向。
3. 页面类型覆盖图——检查过和未检查的模板或路由。
4. 修复顺序——哪些先修、其次修，哪些稍后处理。
5. 限制和未知项——无法进行的运行时检查、证据日期及未解决的问题。

针对范围明确的问题，答复可以简短得多，但应保留支撑结论所需的证据和限制。仅在用户要求或确有帮助时添加实施提示词；不要把范围明确的请求扩展成完整报告套件。

分析规则

1. 提出运行时相关主张时，先验证渲染后的行为。SSR、SSG、CSR、水合和边缘渲染会影响爬虫实际获取的内容。离线或仅能查看源代码时，应标明结果仅基于源代码，并列出仍需进行的运行时检查。
2. 将可抓取性、可渲染性和规范化视为前提。如果重要页面被屏蔽、重复或无法发现，调整标题就无关紧要。
3. 评估页面类型，而不只是单个页面。SEO 问题通常源于共享模板逻辑。
4. 区分有意排除与错误。登录页、购物车、站内搜索、分面组合页面和内容单薄的工具页面通常应设为 noindex。
5. 同时检查搜索结果预览和社交媒体预览。即使传统 SEO 表现尚可，缺失或冲突的 Open Graph 数据仍会影响内容传播。
6. 优先使用真实、有效的 schema.org 标记，并确保其与可见内容和页面用途一致。应单独评估当前是否符合搜索富媒体结果的展示条件；不符合条件不代表标记无效或具有误导性。
7. 将 AI 答案可见性视为可抓取性、元数据清晰度、结构化事实和可信内容的延伸。不要臆造排名或 AI 可见性的保证。

阅读指南

如果任务是……	阅读
从代码审计到实施交接的完整审计	先读 references/methodology.md，再读 references/fix-prompt-spec.md
诊断渲染、规范链接、robots、站点地图、hreflang 或内链问题	references/technical-audit.md
诊断标题、摘要、链接预览或 OG／X 元数据问题	references/metadata-and-previews.md
诊断缺失或无效的 schema，以及薄弱的实体标记	references/structured-data-and-entities.md
诊断主题定位薄弱、内容重复、孤立页面或锚文本问题	references/content-and-information-architecture.md
讨论 AI Overviews、引用展示面或面向答案引擎的就绪情况	references/agentic-search-and-ai-surfaces.md
避免过度推断或误报	references/gotchas.md

已核实的外部基准

本技能的指导依据于 2026 年 4 月核对的最新一手资料，包括：

• Google Search Central 关于 SEO 基础知识、实用内容、JavaScript SEO、robots 元指令、规范化、摘要、结构化数据、站点地图、网站名称、网站图标和首选来源的资料。
• Open Graph 协议规范中关于必需 OG 字段和图像元数据的内容。

保留上述稳定证据和安全原则。随附参考资料是带有日期的基准，不可替代最新官方指导。若参考资料不足、不确定、过时或相互冲突，请查阅相关 Google Search Central、schema.org 或协议文档，以及可信的目标证据。记录来源和版本或检索日期；若处于离线状态，应说明不确定性，而不要臆造当前规则。

提出规范的仓库更新方案，列出过时段落原文、替代来源／版本，以及具体示例或回归测试。审计网站时，不要擅自修改已安装的技能。

注意事项

1. SEO 缺失通常是共享抽象层的问题：单个布局、元数据辅助程序或 head 组件就可能影响所有路由。
2. 不要把每个 noindex 都当成错误：许多实用功能页面本就不应被收录。
3. 不要建议用 robots.txt 处理规范化：在 robots.txt 中屏蔽重复 URL，可能会导致爬虫根本看不到规范链接信号。
4. 不要把 OG 标签等同于 SEO 标签：搜索标题、社交标题、规范链接和结构化数据分别面向不同的使用方。
5. 不要把“AI SEO”和隐藏技巧混为一谈：持久有效的做法仍然是确保爬取访问、提供可靠事实、设置清晰的元数据，并创作有用的原创内容。
6. 没有证据就不要交付修复提示词：第二个会话应收到具体文件、页面类型和验收标准，而不是泛泛的 SEO 建议。

辅助文件

• references/methodology.md — 端到端审计工作流和证据模型。
• references/technical-audit.md — 爬取、渲染、规范链接、robots、站点地图、hreflang、分页和内部链接发现。
• references/metadata-and-previews.md — 标题、描述、OG、X 卡片、网站图标、站点名称和图像预览。
• references/structured-data-and-entities.md — JSON-LD 策略和验证优先级。
• references/content-and-information-architecture.md — 内容质量、重复内容、模板定位和链接架构。
• references/agentic-search-and-ai-surfaces.md — 不炒作地解读 AI 时代的搜索。
• references/fix-prompt-spec.md — 精确的交接提示词规范。
• references/gotchas.md — 高价值陷阱和反模式。
• templates/fix-prompt-template.md — 可直接复制的交接提示词框架。
• scripts/build_fix_prompt.py — 根据 findings JSON 生成确定性提示词。
• scripts/probe_seo_analysis.py — 用于检查问题规范化和提示词生成的本地回归测试。
• scripts/validate.py — 此技能的结构验证器。
• scripts/test_skill.py — 打包和确定性探测测试运行器。