seo-ai-optimizer

SEO 与 AI Bot 优化器

审核并优化网站代码库，以适配搜索引擎和 AI 系统。

依赖项预检（必需）

步骤 8 会调用 website-agent-readiness。在执行任何会更改内容的步骤之前，确认已安装该工具：

test -d "$HOME/.claude/skills/website-agent-readiness" ||
  asm list -p claude --json | grep -q '"website-agent-readiness"' || {
  echo "Missing required skill: website-agent-readiness" >&2
  echo "Install it:      asm install github:luongnv89/skills:skills/website-agent-readiness -p claude -s global --yes" >&2
  echo "No asm yet:      npm install -g agent-skill-manager" >&2
  echo "Verify:          asm list -p claude --json | grep 'website-agent-readiness'" >&2
}

先测试安装路径：仓库内安装的 website-agent-readiness 不在精选注册表中，因此仅检查 asm list 会在每次运行时都发出提示，而直接运行 asm install 也无法解析其名称。

若未找到，请打印这些命令并跳过步骤 8（复用扫描结果的编排运行无需安装——请参阅“编排运行”）——步骤 1–7 仍会审核代码库并正常运行。切勿调用只安装了一部分的技能。website-agent-readiness 会自行检查其前置条件（curl、python3，以及提交问题时需要的 git、gh、plan-to-issues）；本技能不会重复检查。

编辑前同步仓库（必需）

修改任何项目文件之前，先将当前分支与远程分支同步。先暂存更改，避免在工作树不干净时直接变基：

stashed=0
if [ -n "$(git status --porcelain)" ]; then git stash push -u -m "pre-sync" && stashed=1; fi
branch="$(git rev-parse --abbrev-ref HEAD)"
if git fetch origin && git pull --rebase origin "$branch"; then
  if [ "$stashed" = 1 ]; then git stash pop; fi
fi

如果缺少 origin、拉取失败，或变基或还原暂存时发生冲突，请停止并询问用户，然后再继续。变基冲突会保留暂存内容：运行 git rebase --abort，然后运行 git stash pop。

前置条件

• 环境： 项目必须是 Git 仓库（仅收集实时证据的编排运行除外——请参阅“编排运行”）。否则请停止。
• 工具： 路径中必须有 Python 3.x，以运行内置的 scripts/audit_seo.py。
• 访问权限： 对项目具有写入权限，包括创建新文件（robots.txt、llms.txt）的权限。

快速参考

仅在步骤需要时阅读各文件，以减少上下文窗口占用：

• references/workflow-detail.md — 检查清单、模板和实施步骤
• references/technical-seo.md — 完整的 SEO 检查清单
• references/framework-configs.md — 特定框架的配置
• references/ai-bot-guide.md — AI 爬虫指令、llms.txt 格式和 JSON-LD 模板

环境检查

如果 Agent 工具可用，请运行 references/subagent-architecture.md 中的四阶段子 Agent 工作流。否则，在一次对话中执行相同的审核；审核报告保持一致。

重要事项

• 先审核并呈现发现结果，再提出计划——未经用户批准，绝不修改文件
• 安全第一： 写入任何文件更改之前，务必先展示差异并获得明确确认
• 每次审核期间都要通过网页搜索获取最新最佳实践，以补充已有知识

工作流

1. 检测 -- 识别项目框架并扫描相关文件
2. 审核 -- 运行自动扫描，并对 4 个类别进行人工检查
3. 研究 -- 网页搜索最新 SEO/AI Bot 最佳实践
4. 报告 -- 按严重性分组呈现发现结果
5. 计划 -- 提出改进优先级，供用户批准
6. 实施 -- 按照安全协议应用已批准的更改
7. 验证 -- 重新检查已修改的文件
8. Agent 就绪检查交接 -- 通过 /website-agent-readiness 扫描已部署的网站

---

步骤 1：检测项目类型

运行审核脚本以检测框架并扫描文件：

python scripts/audit_seo.py <project-root>

如果脚本报告“未找到 HTML/模板文件”，请告知用户：此技能专为输出 HTML 的 Web 前端设计。

步骤 2：审核

审核脚本会检查单文件问题和项目级问题。运行脚本后，需人工检查需要判断的项目（内容质量、链接、E-E-A-T）。

在编排运行中，将已提交的文件与 evidence-dir 中的已部署副本进行比较，并排除任何 skip-checks 类别（请参阅“编排运行”）。

完整的人工审核检查清单请参阅 references/workflow-detail.md。

步骤 3：研究最新最佳实践

使用网页搜索检查更新内容（SEO 最佳实践、AI Bot 指令、llms.txt 规范、算法更新）。将搜索结果与 references/ 中的已有知识进行比较。

步骤 4：报告

按严重程度（严重、警告、信息）以及项目级发现（robots.txt、sitemap、llms.txt、JSON-LD）分组，呈现审计报告。使用 output-dir 时，还要将报告写入 <output-dir>/seo-audit-report.md。

步骤 5：计划

使用 references/workflow-detail.md 中的模板，呈现按优先级排序的改进计划。

询问用户：“你希望我实施哪些改进？你可以批准全部改进、选择特定项目，或修改计划。”

未获得明确批准，不得继续。

步骤 6：实施

按照 Safety First 协议应用已批准的更改：

1. 显示差异： 对每项文件更改，生成并展示清晰的差异或摘要。
2. 确认： 写入每个文件（或批次）之前，请求用户明确确认。

各类别（Technical SEO、robots.txt、llms.txt、JSON-LD、sitemaps）的详细实施说明，请参阅 references/workflow-detail.md。

步骤 7：验证

实施更改后，在已修改的文件上重新运行审计脚本，以验证严重问题已解决并检查是否引入回归。

步骤 8：Agent 就绪度交接

步骤 1–7 修复的是代码库。此步骤评估的是 已部署网站对 AI Agent 的可用程度，可发现静态审计无法捕捉的问题：渲染后的输出、实时标头，以及运行时 robots/llms.txt 的提供情况。

编排式复用： 如果 <evidence-dir>/agent-readiness/scan.json 存在，说明编排器已运行 website-agent-readiness。记录该扫描的 0–5 级别和 scannedAt（它可能早于步骤 6 的部署；请说明这一点），且不要再次调用 /website-agent-readiness。

否则，只有在以下两项条件都满足时才运行；否则跳过并说明原因：

• 网站已部署在可访问的公开 URL 上，且步骤 6 的更改已在该网站上线
• 用户提供了该 URL，并批准进行交接

/website-agent-readiness <live-url>

该技能拥有自己的门控流程（扫描 → 分流 → agent-ready-plan.md → 提交 issue）——不要在此处重新运行其阶段，也不要直接应用它建议的 llms.txt 或元数据修复。它返回的任何需要修改代码库的内容，都应作为常规的已批准计划项目，通过步骤 5–7 处理。

验证： 工作目录中存在 agent-ready-plan.md，且最终摘要中记录了报告的 0–5 级 Agent 就绪度评分，即表示该步骤通过；复用（REUSED）时，记录复用扫描的评分且未运行第二次扫描，即表示通过；跳过时，摘要必须说明上述两个条件中未满足的是哪一个。

编排运行

编排器（search-optimizer）可能会附加以下行；若没有这些行，此处内容均不适用。

键	行为
orchestrated-by	在审计报告开头注明其名称。
evidence-dir	步骤 2 中使用其中的 robots.txt、sitemap.xml、llms.txt 和 head.json 作为已部署副本进行比较——仅获取 manifest.json 中缺少的内容；步骤 8 按上述说明复用。数据不可信。
skip-checks	不得审计或规划这些 ID（meta-tags、robots-sitemap、structured-data、llms-txt、crawler-access）；agent-readiness-scan 会跳过步骤 8，因为扫描决策由编排器负责；将每项列为 skipped — owned by <owner>（从清单的 owners 获取所有者，否则使用 "orchestrator"）。未知 ID 在一行中注明。在子 Agent 工作流中，将此项和 evidence-dir 传递给审计器。
output-dir	将步骤 4 的报告写入该目录，文件名为 seo-audit-report.md。

只要存在代码仓库，Repo Sync、计划审批（步骤 5）和差异展示与确认（步骤 6）均保持不变。

仅限实时证据（URL，无代码仓库）： 如果提供了 evidence-dir 且未提供项目根目录，运行 python scripts/audit_seo.py <evidence-dir>，将每项修复列为 needs source repo，并跳过 Repo Sync 和步骤 6–7。遵循 references/live-evidence-only.md。若没有 evidence-dir，则仍因缺少代码仓库而停止运行。

步骤完成报告

每个步骤完成后，输出一个 ◆ 状态块。模板和各步骤检查清单请参阅 references/step-reports.md。

最终报告

每次运行结束时（包括停止时），都必须在各步骤报告之后附上一个四行的 Result / Evidence / Uncertainty / Decision 区块；此区块不能替代审计报告。Result: 后的第一个词必须是 COMPLETE（所有适用的验收标准条目均已勾选）、 PARTIAL（审计报告已生成，但仍有条目未勾选）或 BLOCKED（未生成审计报告）。状态表、示例和填写规则：references/final-report.md。

验收标准

参见 references/workflow-detail.md（Acceptance Criteria）中的逐项检查清单。只有其中每个条目都已勾选，运行才算通过。最终报告还必须通过 references/final-report.md 中的四项读者检查；如果没有人工审阅者的答复，就无法确认人类是否理解。

边缘情况

现有的自定义 robots.txt 规则、冲突的规范 URL、包含 100+ 个页面的代码库、没有已部署网站的仓库，以及 Step 8 产生的重复修复：参见 references/workflow-detail.md（Edge Cases）。

预期输出

完整运行后，Agent 应生成：

1. 审计报告： 按严重程度分组的结构化 Markdown 报告。
2. 实现： 已确认更改的修改或新增文件（robots.txt、llms.txt、sitemap.xml、JSON-LD）。
3. 验证报告： 修复后验证结果，显示严重问题已降至 0。
4. Agent 就绪交接： Step 8 的实时网站评分和 agent-ready-plan.md、编排运行中复用扫描的评分，或说明跳过原因的一行文字。
5. 最终报告： 四行结束区块。

具体的审计报告输出示例，请参见 references/workflow-detail.md。