Content & Media Creation · AgriciDaniel/claude-seo
claude-seo
Comprehensive SEO analysis for any website or business type. Full site audits, single-page analysis, technical SEO (crawlability, indexability, Core Web Vitals with INP), schema markup, content quality (E-E-A-T), image optimization, sitemap analysis, and GEO for AI Overviews/ChatGPT/Perplexity. Industry detection for SaaS, e-commerce, local, publishers, agencies. Triggers on: SEO, audit, schema, Core Web Vitals, sitemap, E-E-A-T, AI Overviews, GEO, technical SEO, content quality, page speed.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandInstall DepsNetwork AccessWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
The entire repository is structured as a Claude Code plugin (dual manifest via .claude-plugin/plugin.json and marketplace.json). Its flagship entrypoint is skills/seo/SKILL.md: it performs no analysis directly, instead dispatching `/seo <command> <url>` to 24 peer sub-skills and conditionally spawning 18 subagents in parallel during full-site audits.
skills/seo/SKILL.md
**Invocation:** `/seo $1 $2` where `$1` is the command and `$2` is the URL or argument.
"25 sub-skills / 18 subagents" corresponds to the actual count of 25 directories under skills/ (including the orchestrator itself) and 18 .md files under agents/. SKILL.md self-documents orchestrating 24 sub-skills (21 core + 1 framework + 2 extension mirrors), with the 25th being the orchestrator itself. The routing table covers 20+ subcommands: audit, page, sitemap, schema, images, technical, content, content-brief, geo, plan, programmatic, competitor-pages, local, maps, hreflang, google, backlinks, cluster, sxo, drift, ecommerce, flow, setup, doctor, etc.
The repository enforces a strict single-script invocation pattern: skills, agents, and hooks must execute built-in Python solely through `"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run <script.py>`, strictly forbidding naked interpreter calls. Placing the launcher in scripts/ instead of bin/ is a hard marketplace constraint.
skills/seo/SKILL.md
canonical form used by every skill and agent. Claude Code expands
This convention converges 55 scripts/*.py files into a single entrypoint and serves as the prerequisite for allowlisting and isolated venv enforcement. For manual installations, install.sh uses sed to rewrite this token to `"$HOME/.claude/skills/seo/scripts/claude-seo"` (idempotent and applied only to copied-in .md files).
The launcher strictly handles interpreter resolution: it probes for a >=3.10 interpreter in the order CLAUDE_SEO_PYTHON → py -3 → python3 → python, exits with an error if all fail, and does not install anything itself.
scripts/claude-seo
echo "Claude SEO requires Python 3.10 or newer. Tried CLAUDE_SEO_PYTHON, py -3, python3, and python." >&2
The probe script runs `-c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)'`. Once found, it execs runtime.py in the same directory. CLAUDE_SEO_PYTHON is treated as a single array element rather than an evaluated shell command; comments explicitly state this is to prevent injection and safely support paths with spaces.
Runtime execution is managed in scripts/runtime.py: the `run` subcommand first validates scripts against a strict allowlist (a frozenset of 52 core scripts + filename regex + directory traversal checks) before executing via the isolated venv interpreter; if the runtime is not ready, it explicitly prompts running `/seo setup` first.
scripts/runtime.py
raise ValueError("script is not in the bundled runtime allowlist")
Actual audit: of the 55 .py files under scripts/, only release_sign.py, verify_release.py, and runtime.py are excluded from the allowlist (release tools and the invoked runtime itself cannot be called by agents). extensions/*/scripts follow a separate extension argument path, and the banana extension includes a MANUAL_EXTENSION_SKILLS fallback for manual directory layouts.
`/seo setup` atomically builds a virtual environment inside a persistent data directory: venv --without-pip → ensurepip → pip install -r requirements.txt → playwright install chromium, rolling back completely if any phase fails.
scripts/runtime.py
[str(staged_python), "-m", "pip", "install", "--disable-pip-version-check", "-r", str(root / "requirements.txt")],
This is the plugin's only large-scale network package installation action. Dependencies are locked in requirements.txt (18 packages, annotated individually with CVE notes). Chromium can be skipped via --skip-browser; missing render engines return exit code 10 indicating "core functional, browser incomplete", which install.sh/install.ps1 translate into warning notices.
The plugin includes an integrated PostToolUse hook: after each Edit/Write, Node triggers hooks/validate-schema.py to inspect JSON-LD in modified files; placeholder or deprecated schema errors block the edit by returning exit code 2.
hooks/hooks.json
"${CLAUDE_PLUGIN_ROOT}/hooks/run-python-hook.js",
hooks.json only declares the matcher `Edit|Write`. run-python-hook.js resolves Python cross-platform (including Windows Store alias stub detection). validate-schema.py only processes .html, .htm, .jsx, .tsx, .vue, .svelte, .php, and .ejs files, skips files >10MiB, and deliberately allows FAQPage (Google deprecated FAQ rich results, but the schema type remains formally valid). Manual installation copies the hook file, but install.sh notes: "hook enforcement requires plugin install".
Data fetching targeting external sites is unified behind an SSRF and DNS-rebinding protection layer: fetch_page.py uses url_safety.safe_requests_session, while render_page.py and capture_screenshot.py use Playwright with re-verification of every subresource host at the route() layer.
scripts/url_safety.py
Centralizes SSRF protection, DNS rebinding mitigation, and DNS-pinned HTTP
url_safety also provides validate_url_strict (resolving all A records, validating against private networks, and returning pinned IPs), safe_requests_get/head/session, and a CLAUDE_SEO_LOCAL_TARGETS allowlist (applied only to initial top-level URLs; redirects, subresources, and browser requests are not permitted, and cloud metadata addresses are rejected even if allowlisted). SECURITY.md notes residual risks: Chromium internal DNS and CONNECT proxies weaken pinning, and pure IPv6 targets fail-closed.
Optional capabilities (8 MCP extensions) are excluded from the core package; individual installers merge MCP servers and user credentials into mcpServers in `~/.claude.json` (atomic replacement with chmod 0600) and copy mirror skills into ~/.claude/skills/.
extensions/dataforseo/install.sh
os.chmod(tmp, 0o600)
The same pattern applies across: firecrawl (FIRECRAWL_API_KEY), banana (GOOGLE_AI_API_KEY → nanobanana-mcp), and ahrefs (AHREFS_API_TOKEN). bing-webmaster, profound, and seranking instead persist keys in the env section of `~/.claude/settings.json`. Code comments explain why mcpServers is not written to settings.json: "`mcpServers` is not a key Claude Code reads there".
2Core Capabilities
01Parallel subagent orchestration for full-site audits (/seo audit)
02Command routing surface across 24 sub-skills (single entrypoint `/seo <command> <url>` covering technical, content, schema, images, GEO, local, maps, hreflang, ecommerce, backlinks, clustering, SXO, drift, programmatic, planning, and reporting)
03First-party Google data integration (GSC, PageSpeed v5, CrUX, Indexing, GA4, Ads, NLP, YouTube) tiered into 4 credential capability levels
04AI search & GEO auditing (AI crawler accessibility, llms.txt validation, paragraph-level citability scoring, aligned strictly with official Google guidance)
05Backlink profiling and toxic link detection (free sources via Moz, Bing, Keywords Everywhere, Common Crawl + paid DataForSEO + live verification crawler)
06Structured data detection, validation, and generation, with an active hook blocking invalid JSON-LD during file edits
07SEO drift monitoring: baseline / compare / history tripartite workflow snapshotting key on-page SEO elements to disk for regression analysis
08Deliverable generation: structured audit artifacts saved under `{domain}-audit/`, with professional A4 PDF, HTML, and Excel report export (weasyprint + matplotlib + openpyxl)
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | git |
| cli | python3 >= 3.10（或 CLAUDE_SEO_PYTHON / py -3 / python） |
| cli | node（hook 包装器） |
| cli | npx / Node 18+（MCP server 与 unlighthouse 经 npx 拉起） |
| network | PyPI（pip install -r requirements.txt，18 个包） |
| network | Playwright Chromium 下载 |
| api | Google PageSpeed Insights v5 |
| api | Chrome UX Report (CrUX) 现场数据与 25 周历史 |
| api | Google Search Console / Indexing / GA4 / Ads（google-api-python-client + OAuth） |
| api | Google Cloud Natural Language（实体/情感/分类） |
| api | Moz Link Explorer API（DA/PA、spam、domains、anchors） |
| api | Bing Webmaster Tools API |
| api | Keywords Everywhere openPageRank（免费反链回退档） |
| network | Common Crawl 超链接图（域名级 PageRank，无 key） |
| api | IndexNow（Bing/Yandex/Seznam/Naver 收录提交） |
| api | DataForSEO API（脚本直连路径）与 dataforseo-mcp-server（MCP 路径） |
| api | GitHub Contents API：把上游 FLOW 仓库的 prompt 文档同步进本 skill 的 references（写盘） |
| api | Gemini 图像生成（banana 扩展，generativelanguage v1beta） |
| api | Ahrefs 官方 MCP server（@ahrefs/mcp@0.0.11） |
| package | Python 依赖：requests/beautifulsoup4/lxml/lxml_html_clean/playwright/urllib3/trafilatura/htmldate/courlan/matplotlib/numpy/weasyprint/openpyxl/google-api-python-client/google-auth/google-auth-httplib2/google-analytics-data/google-ads |
| package | npm 包（扩展运行时）：firecrawl-mcp@3.11.0、@ycse/nanobanana-mcp@1.1.1、unlighthouse@0.13.5 |
| network | 任意用户指定目标站（HTTP 抓取 + Playwright 渲染 + 反链存活验证 + 截图） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Executes local scripts or commands: scripts/claude-seo (bash) → scripts/runtime.py: `run` executes one of 52 allowlisted scripts; `setup` builds runtime
- scripts/ 或 SKILL.md: Declares dynamic installation of external language package dependencies
- 网络端点: Declares external network access: pypi.org (runtime.py `-m pip install -r requirements.txt`, 18 packages)
- 本地工作目录: File read/write and artifact output: ~/.claude/skills/** (seo and 24 seo-* sub-skills, extension mirror skills), ~/.claude/agents/seo-*
Audit Notes: Not Red: Contains no obfuscated or hidden payloads (zero matches for base64/eval/exec/\xNN across the repo), no telemetry, licensed under MIT, implements unusually robust SSRF and DNS-rebinding mitigations (url_safety with 91 regression tests), enforces 0600 permissions on credential files, provides reversible uninstallation, and explicitly warns about curl|bash risks in the README. However, it exceeds Yellow due to: 1) Installing the plugin registers a PostToolUse hook on the host, executing Node + Python on every Edit/Write with the power to block edits (exit code 2), representing continuous code execution; 2) install.sh and setup perform pip installations of 18 packages and download Chromium, while extension installers use npx to fetch and warm up 5 npm packages (supply chain surface; versions are pinned but lack checksum or signature verification, with SECURITY.md noting installer verification is "tracked for v2.3"); 3) 8 extension installers read and write ~/.claude.json / ~/.claude/settings.json, persisting credentials in plaintext (including DataForSEO credentials, Ahrefs/Firecrawl/Gemini keys) and modifying existing user Claude configurations; 4) Its primary purpose involves fetching arbitrary third-party web pages and prompting an LLM with their contents, creating an inherently large prompt injection attack surface defended primarily via prompt-level safeguards; 5) sync_flow.py writes upstream repository text into references, establishing an external command ingestion channel. Because any of these triggers real side effects on the user machine, it is classified as Orange. Pre-use recommendations: audit the hook configuration, supply dedicated revocable keys for extension credentials, and avoid enabling rendering pipelines on untrusted domains.
5Second-Pass Verification
- [ok] skill.path 定位 — 候选：仓库根（无 SKILL.md，只有 README/AGENTS/CLAUDE/SECURITY 等治理文件）、skills/seo/（SKILL.md frontmatter `name: seo` + `user-invocable: true`，Quick Reference 表是全插件唯一命令入口，runtime 约定、编排逻辑、评分权重只写在这里）、skills/seo-audit/（只是被路由到的子技能）、extensions/*（需另行安装的可选项）。结论 skills/seo 为该插件旗舰入口目录，与被分配的 path 一致。注意本行 identity 是整个插件，故 analysis 覆盖全仓（8 扩展、18 agent、55 脚本、hook、安装器）而非仅路由文件。
- [discrepancy] 「扩展把 MCP 配置合并进 ~/.claude/settings.json」的说法 — docs/ARCHITECTURE.md:346 写「6. Merges MCP config into `~/.claude/settings.json` non-destructively」，但实际 dataforseo/firecrawl/banana/ahrefs 四个 installer 写的是 `~/.claude.json`，并在注释中明确反驳该文档（「MCP servers live in ~/.claude.json (the file `claude mcp add` writes). NOT ~/.claude/settings.json - `mcpServers` is not a key Claude Code reads there」）。真正写 settings.json 的是 bing-webmaster/profound/seranking（写 env 段，语义正确）。属文档未同步，非行为缺陷。
- [ok] 运行时白名单是否会挡住合法脚本 — 正则提取 ALLOWED_CORE_SCRIPTS 得 52 项，与 scripts/ 下 55 个 .py 的差集恰为 release_sign.py、verify_release.py、runtime.py；前两者是发布签名/校验工具，后者是 launcher 目标本身（_resolve_script 显式拒绝 candidate == __file__）。文档中被引用的脚本（render_page/fetch_page/google_auth/backlinks_auth/drift_*/schema_generate/sync_flow 等）全在白名单内，声明与实现相符。
- [discrepancy] CLAUDE.md 称 scripts/ 有 54 个 Python 执行脚本 — 实测 `ls scripts/*.py` = 55（白名单 52 + 3 个发布/运行时）。差一行注释，不影响能力结论，但说明此类计数属陈旧文案，引用须以磁盘为准。
- [ok] 「25 子技能 / 18 子agent」是否夸大 — skills/ 下 25 个目录、agents/ 下 18 个 .md，与 plugin.json「25 sub-skills (21 core + 1 orchestrator + 1 framework + 2 extension mirrors) and 18 sub-agents」精确对应；SKILL.md 正文说「orchestrates 24 sub-skills」并解释第 25 个是 orchestrator 自身，两种表述数学自洽。
- [ok] 「410 tests passing」徽章 — README 徽章声明 410 passing；本地 tests/ 有 90+ 个 test_*.py，且存在安全主题测试（test_url_safety、test_extension_installer_injection、test_agent_untrusted_content、test_banana_api_key_safety、test_google_api_key_safety 等）。按批 2 约束未执行任何测试，故仅作为「测试面存在」的证据，不背书通过数。
- [ok] 是否漏掉网络调用 / 隐藏脚本 / 混淆 — 全仓扫描 http(s) 主机与 requests./urlopen/subprocess/npx/pip/playwright 调用点后，未发现未列入 external_deps 的外发目标；base64 -d、eval(、exec(、\xNN、`curl | bash`、`irm | iex` 全部零命中；install.sh 把 clone 固定在 tag（REPO_TAG=v2.3.1，注释说明防 main 静默漂移），并有 test_manifest_consistency.py 守卫与 plugin.json 一致。
- [ok] 外部依赖逐条回源 — 22 条 external_deps 全部由「常量定义行 / installer 写入行 / env 读取行」直接引证，无一条取自 README 宣传语。唯一非源码级的是 Playwright Chromium 的下载域名（runtime.py 只写 `-m playwright install chromium`，域名未出现在仓库），已在该条 endpoint 如实标注。
6Verdict & Scenarios
Best for: Designed for users needing a repeatable, production-grade SEO workflow: agency teams auditing client sites at scale, in-house SEO specialists seeking an automated second opinion before releases, or independent consultants generating client-ready audit deliverables. A standard workflow involves running `/seo setup` after plugin installation to build the isolated environment, executing `/seo audit <url>` to launch parallel subagents, integrating first-party data (GSC, PSI) as needed, and generating PDF reports. For high-compliance settings, the core can be run entirely standalone with zero extensions (the default core uses no third-party APIs and accesses only the user-specified target site).
Not for: Not suitable for users expecting zero-setup, instant execution (requires running `/seo setup` on first launch to install 24 pip packages and download Chromium); environments prohibiting host-level edit hooks (manual installation bypasses hooks, but loses the schema validation quality gate); users seeking formal compliance certification (findings are point-in-time snapshots relative to a specific commit and industry window); environments where credentials cannot be stored in plaintext JSON (extensions persist keys to ~/.claude.json or settings.json); or adversarial environments rendering untrusted sites directly (Chromium DNS rebinding is documented as a known residual risk).
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload claude-seo.tar.gz
sha256:
Option B · Copy Guide for Agent50b15d6fd70df445…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 92795530b4.