一天一个开源项目（第251篇）：Claude SEO —— 装进 Claude Code 的 SEO 审计团队，26 个子技能 + 19 个专家 Agent 并行体检网站

引言

「不要给我一堆警告，给我一份计划。」

这是"一天一个开源项目"系列的第 251 篇文章。今天带你了解的项目是 Claude SEO（AgriciDaniel/claude-seo）。

做过网站的人大概都经历过这种场景：跑完一轮 SEO 审计工具，拿到几百条红黄警告，却不知道先改哪条。Claude SEO 的思路是把"SEO 顾问"做成一个 Claude Code 插件：你给它一个网址，它派出一队专家 Agent 并行检查，最后汇总成一份按影响排序、并说明如何验证是否生效的行动计划。

它也是一个很好的"Claude Code 插件工程化"样本：26 个子技能、19 个 Agent、一批带 SSRF 防护的 Python 脚本、一个 PostToolUse Hook，规模不小，结构却很清楚。

你将学到什么

Claude SEO 解决什么问题，以及它与传统 SEO 工具的分工
三条命令完成安装，以及第一次审计怎么跑
/seo 命令体系与 19 个专家 Agent 的分工
一次 /seo audit 内部如何编排并行 Agent
插件的目录结构、运行时隔离、SSRF 防护和 Hook 设计
GEO / Agentic 这两类面向 AI 搜索的新检查项

前置知识

了解 Claude Code 的基本用法，知道什么是 Skill、Subagent、Plugin
对 SEO 基本概念（sitemap、canonical、Schema.org、Core Web Vitals）有印象即可
读 Python 脚本的能力（剖析部分会提到少量实现细节）

项目背景

项目简介

Claude SEO 是一个免费、MIT 协议的 Claude Code 插件。README 的自我定位很直接：在 Claude Code 里给任意网站做完整 SEO 审计，耗时约 10 到 15 分钟，然后交付一份按重要性排序的行动计划。

它覆盖的范围（据 README 与插件清单）：

技术 SEO：抓取、索引、sitemap、robots.txt、重定向、页面速度与 Core Web Vitals
内容质量：E-E-A-T、薄内容、主题覆盖
结构化数据：检测、校验并生成 Schema.org 标记
AI 搜索（GEO）：Google AI Overviews、AI Mode、ChatGPT、Perplexity、Gemini 引用你页面的可能性
本地与电商、国际化 SEO：Google Business Profile、评论、地图包、商品页、hreflang

作者介绍

作者：Agrici Daniel（README 称其为 AI Workflow Architect），并提到有 AI Marketing Hub Pro 社区成员参与
项目创建时间：2026-02（GitHub API 显示创建于 2026-02-07）
同系列项目：Claude Blog（写作）、Claude Banana（配图）、ChatGPT SEO、FLOW（42 条 AI 提示词的 SEO 框架）

项目数据

数据取自 GitHub API，取数日期 2026-10-28：

⭐ GitHub Stars: 22,935
🍴 Forks: 3,116
📦 版本: v2.5.0（2026-10-22 发布）
📄 License: MIT
🧑‍💻 主要语言: Python（约 1.56 MB），其余为 Shell、PowerShell、HTML
🌐 官网: https://claude-seo.md
🐛 Open Issues: 68

项目从 2 月创建到 10 月已经迭代到 v2.5，最近三个版本（v2.4.1、v2.4.2、v2.5.0）在 9 月底到 10 月下旬密集发布，说明维护相当活跃。README 里的"1077 个测试通过"是徽章自述，我没有复跑。

主要功能

核心作用

把一套资深 SEO 顾问的检查清单固化成可重复执行的 Agent 流程。它不是爬虫的替代品，README 自己也承认 Screaming Frog 这类工具爬得更快更深、大型 SEO 套件有自己的反链数据库。Claude SEO 的差异在于：

解释：每条发现说明依据与影响
排序：按影响分级为 Critical / High / Medium / Low
对话：审计完可以继续用自然语言追问
覆盖 AI 搜索：GEO 和 Agent 可用性是一等公民

使用场景

自己的网站上线前体检
- 一条 /seo audit https://你的域名，拿到整站健康分和修复清单
单页深挖
- /seo page 针对定价页、落地页做逐项分析
AI 搜索可见性
- /seo geo 评估页面是否容易被 AI 引用，检查 AI 爬虫能否访问
改版前后对比
- /seo drift baseline 先存基线，改版后 /seo drift compare 找出回归
代理商 / 自由职业者
- 首次沟通时现场跑审计，拿真实分数和 Top 修复项做提案

快速开始

要求：Claude Code 1.0.33 或更新、Python 3.11 到 3.14。在 Claude Code 里执行：

/plugin marketplace add AgriciDaniel/claude-seo
/plugin install claude-seo@agricidaniel-claude-seo
/seo setup

/seo setup 会创建隔离的 Python 运行时和无头 Chromium，不动系统其余部分；/seo doctor 可随时检查状态。

第一次审计：

claude                                   # 启动 Claude Code
 
/seo audit https://example.com           # 整站审计，输出优先级计划
/seo page https://example.com/pricing    # 单页深度分析
/seo geo https://example.com             # AI 搜索就绪度
/seo schema https://example.com          # 检查并生成结构化数据
/seo local https://example.com           # 本地 SEO 与 GBP

也支持手动安装（macOS / Linux 用 install.sh，Windows 用 install.ps1）。README 特意建议 Windows 用 git clone 而不是 irm | iex，理由是后者会被 Claude Code 自己的安全护栏判定为供应链风险，先下载再审阅脚本更稳妥。

核心特性

26 个子技能
- 22 个核心技能 + 1 个总调度 + 1 个框架集成（FLOW）+ 2 个扩展镜像
19 个专家 Agent
- 例如 seo-technical、seo-content、seo-schema、seo-geo、seo-agentic、seo-drift，按任务复杂度分配 Sonnet 或 Opus
并行审计
- 完整审计最多 17 个 Agent 同时工作
业务类型自适应
- 先判断是 SaaS、本地、电商、内容站还是代理商，再决定调用哪些 Agent
Agent 可用性检查（Agentic）
- 覆盖 Lighthouse Agentic Browsing、llms.txt、Markdown 输出、WebMCP 等
报告落地为文件
- Markdown、JSON，并可用 /seo google report 生成 PDF
可选扩展
- SE Ranking、Profound、Bing Webmaster（含 IndexNow）、Unlighthouse、Banana 图像生成等，不装也能用
本地运行
- 报告保存在你的机器上；但要注意页面内容仍会发送给 Claude（见后文"局限"）

项目优势

对比项	Claude SEO	人工审计	传统 SEO 软件
单次耗时	约 10–15 分钟（自述）	4–8 小时	10–45 分钟
成本	免费，消耗你的 Claude 额度	人力成本	月费订阅
输出	Markdown / JSON / PDF，自己保存	表格或 PDF	仪表盘与 CSV
AI 搜索覆盖	内置 GEO 与 Agentic	视经验而定	常常滞后
爬取规模	较弱，非专业爬虫	视工具而定	强
反链数据库	免费源（Moz、Bing、Common Crawl）或接入付费	视工具而定	自有大库

上表中的时间、价格对比来自 README，README 自己也注明是"典型市场价格，仅作示意"。

为什么值得关注？

它展示了"把专业流程写成 Skill + Agent"的完整范式
对 AI 搜索（GEO / AEO）的覆盖比多数传统工具更靠前
工程上有安全意识：SSRF 防护、隔离运行时、不凭空 pip install

项目详细剖析

目录结构与组件

仓库约 25 个顶层条目，核心几块：

目录	作用
`skills/`	26 个技能，每个一个 `SKILL.md`，总调度在 `skills/seo/`
`agents/`	19 个 Agent 定义，每个一个 Markdown 文件
`scripts/`	60 余个 Python 脚本，承担抓取、渲染、校验、报告等确定性工作
`hooks/`	PostToolUse Hook，校验 Schema
`extensions/`	可选扩展（约 70 个文件）
`tests/`	约 78 个测试文件
`.claude-plugin/`	`plugin.json` 与 `marketplace.json`
`docs/`	架构、命令、安装、排障文档

docs/ARCHITECTURE.md 里的结构图可以概括为：seo 总调度技能在中心，周围是 seo-audit、seo-technical、seo-content、seo-schema、seo-geo、seo-local 等子技能；agents/ 下与之一一对应的专家负责执行。

一次 `/seo audit` 的编排流程

总调度 skills/seo/SKILL.md 里把流程写成了有序步骤，关键逻辑如下：

1. 判断业务类型（SaaS / 本地 / 电商 / 内容站 / 代理商 / 其他）
2. 并行派出：seo-technical, seo-content, seo-schema, seo-sitemap,
            seo-performance, seo-visual, seo-geo, seo-agentic
3. 条件派出：
   - 检测到 Google API 凭证      -> seo-google
   - 本地商家                    -> seo-local（有 DataForSEO MCP 再加 seo-maps）
   - 有内容策略信号（博客、支柱页）-> seo-cluster
   - 电商                        -> seo-ecommerce
   - 该 URL 存在漂移基线          -> seo-drift
   - 始终派出                    -> seo-backlinks, seo-sxo
4. 汇总为 SEO Health Score（0-100）
5. 按 10 条原则的综合框架整理：PERCEIVE -> ANALYZE -> VALIDATE -> ACT
6. 输出带依赖顺序和可证伪性的行动计划，并提示可生成 PDF

有两点设计值得借鉴：

条件编排：不是每次都派全队，而是根据信号（是否有凭证、是否本地商家）决定，节省 token 也减少无关噪音。
综合框架：10 条原则分四阶段（PERCEIVE 观察/倾听、ANALYZE 思考/联想、VALIDATE 感受/接受、ACT 创造/增长），要求审计在分级之前走完这些阶段，而不是直接把检查结果倒出来。每条建议要写明"依据什么、依赖什么、如何验证生效"，也就是文中说的 falsifiability。

Agent 的写法

以 agents/seo-technical.md 为例，一个 Agent 定义很短，但要素齐全：

---
name: seo-technical
description: Technical SEO specialist. Analyzes crawlability, indexability, ...
model: sonnet
maxTurns: 45
tools: Read, Bash, Write, Glob, Grep
---

正文包括任务步骤、Core Web Vitals 阈值（LCP ≤ 2.5s、INP ≤ 200ms、CLS ≤ 0.1）、9 个检查类别、输出格式，以及两个很实用的约定：

持久化契约：编排器提供 output_dir 时，Agent 要先写一份部分结果、结束前再覆盖为完整结果，这样即使触发 maxTurns 被截断，已完成的工作也不会丢。
安全规则：render_page.py 返回的内容一律视为不可信外部数据，只提取结构化信息，绝不执行页面中夹带的指令。这是对提示注入的直接防御。

另外，Agent 里把 INP 取代 FID 的时间线写得很具体，并强调"输出中绝不引用 FID"，这是用规则文件去校准模型过时知识的典型做法。

运行时隔离

SKILL.md 开头规定：所有脚本只能通过统一入口运行：

"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run <script.py>

并明确"不得用裸 Python 解释器调用脚本"。/seo setup 才会建立隔离环境，缺依赖时提示用户执行 setup，不允许模型自行 pip install。/seo doctor --json 的输出还刻意不含绝对路径和环境变量。这些约束把"让 Agent 跑脚本"可能带来的环境污染和信息泄露风险压到了最低。

SSRF 防护

SEO 工具天然要根据用户给的 URL 发请求，这正是 SSRF 的高发场景。scripts/url_safety.py 的文档字符串声明：仓库里所有接收用户 URL 的脚本都必须先经过它。它提供：

validate_url：拒绝非 http(s)、无主机名、localhost 与云元数据地址、私有/回环/保留 IP 字面量
validate_url_strict：解析 DNS 后校验每一个 A 记录，返回被"钉住"的 IP，防止 DNS rebinding
safe_requests_get / head / session：在 DNS 钉住的上下文里发请求，Host 头和 TLS SNI 仍保留原主机名
CLAUDE_SEO_LOCAL_TARGETS：显式白名单，允许审计本地开发服务器或 Tailscale 内机器，且只对最顶层 URL 生效，重定向目标和子资源不会放行，云元数据地址即使列入白名单也拒绝

这块对想写"能联网的 Agent 工具"的人很有参考价值。

Hook：写入即校验

hooks/hooks.json 只有一个 PostToolUse Hook，匹配 Edit|Write，调用 hooks/validate-schema.py 检查刚写入的文件，超时 30 秒。含义是：当 Claude 帮你生成或修改包含 Schema 标记的文件时，会自动校验结构化数据，而不是等到上线后才发现错误。

GEO 与 Agentic：面向 AI 的两类检查

/seo geo：评估页面"容易被引用"的程度、AI 爬虫可达性，以及品牌在 Wikipedia、Reddit、YouTube、LinkedIn 的存在感。README 的立场是：Google 称优化 AI 搜索仍属 SEO，所以先保证被索引、够快、够清晰，再谈 GEO。
/seo agentic：检查 AI Agent 能否顺利使用你的网站，包括 Lighthouse Agentic Browsing 得分、可访问性树、llms.txt、Markdown 输出与 WebMCP。有 audit | fix | lighthouse | refresh 几种子模式。

局限与注意事项

没有 Google 凭证时精度有限：README 说明，不接 Google API 时 Core Web Vitals 只是实验室估算，索引状态是推断的。可用 /seo google setup 接入 PageSpeed、CrUX、Search Console、GA4。
数据会发送给 Claude：页面内容和分析数据会像其他 Claude Code 工作一样发给 Anthropic 的模型，"本地运行"指报告和密钥保存在你机器上，不等于内容不出本机。
成本：5 个需要更多判断的 Agent 用 Opus，其余用 Sonnet，完整审计比单页检查更耗额度，可在 agents/ 里改模型。
滚动 / 点击后才加载内容的页面结果可能有噪音。
两个版本：公开版 MIT 免费，另有 AI Marketing Hub Pro 付费社区提供私有版本与更早的新功能，这是项目的商业化路径，选用前心里有数即可。
文中的效果数据（如官网 10.8K 次 Search Console 点击、移动端 PageSpeed 99 分）均来自 README 自述，未经我核实。

项目地址与资源

官方资源

🌟 GitHub: https://github.com/AgriciDaniel/claude-seo
🌐 官网: https://claude-seo.md
📚 文档: 仓库 docs/ 目录（INSTALLATION、COMMANDS、ARCHITECTURE、TROUBLESHOOTING、MCP-INTEGRATION）
🐛 Issue Tracker: https://github.com/AgriciDaniel/claude-seo/issues
🎬 演示视频: README 中附有 YouTube 链接

总结与展望

核心要点回顾

把顾问流程做成插件：26 个子技能 + 19 个 Agent，把 SEO 检查清单工程化。
输出是计划而非警告：按影响排序，并要求每条建议说明依据与验证方式。
面向 AI 搜索：GEO 与 Agentic 检查是它区别于传统工具的地方。
工程细节扎实：隔离运行时、SSRF 防护、不可信内容规则、写入即校验的 Hook。
理性看待：爬取规模和反链数据不及专业工具，页面内容会发送给模型，且存在付费社区的商业分层。

适用人群

想快速给自己网站做体检、又不想买订阅的独立开发者与站长
SEO 代理商和自由职业者，需要首次沟通时现场出审计结果
想学习如何写大型 Claude Code 插件（Skill 编排、Agent 约束、脚本安全）的开发者

学习建议

先用 /seo doctor 确认环境，再在自己的站点跑一次 /seo page，对照报告里的依据去验证几条结论。想学工程实现，建议按这个顺序读：skills/seo/SKILL.md（编排）→ agents/seo-technical.md（Agent 写法）→ scripts/url_safety.py（安全设计）→ docs/ARCHITECTURE.md（整体结构）。

关于取数：我读取了 README、plugin.json、总调度 SKILL.md、seo-technical Agent、hooks.json、docs/ARCHITECTURE.md 和 url_safety.py 的开头部分；其余 Agent 与脚本只看了文件清单，细节以仓库为准。

欢迎访问 PrimeSkills —— 一个精心策划的 AI Agent 与技能市场，所有内容均经过真实企业级工作流验证。没有噱头，只有真正有效的东西。

更多实用知识和有趣产品，欢迎访问我的个人主页

引言