1仕組みと動作原理
リポジトリ全体がClaude Codeプラグインとして構成されており（.claude-plugin/plugin.json と marketplace.json のデュアルマニフェスト）、フラグシップのエントリポイントは skills/seo/SKILL.md です。それ自体は分析を実行せず、`/seo <command> <url>` を同階層の24個のサブスキルにディスパッチし、サイト全体監査時には18個のサブエージェントを条件に応じて並列起動（spawn）します。
skills/seo/SKILL.md
**Invocation:** `/seo $1 $2` where `$1` is the command and `$2` is the URL or argument.
「25個のサブスキル / 18個のサブエージェント」は、skills/ 配下の25ディレクトリ（オーケストレータ自身を含む）と agents/ 配下の18個の .md ファイルの実数に対応します。SKILL.md 自体は24個（コア21個 + フレームワーク1個 + 拡張ミラー2個）のオーケストレーションを定義しており、25個目がオーケストレータ自身となります。ルーティングテーブルは 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 など20以上のサブコマンドを網羅しています。
全リポジトリで単一のスクリプト呼び出し形式を強制しています。skill/agent/hook は内蔵Pythonを `"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run <script.py>` 経由でのみ実行可能で、生のインタプリタ直接呼び出しは厳禁とされています。ランチャーを bin/ ではなく scripts/ に配置しているのはマーケットプレイスの厳格な制約です。
skills/seo/SKILL.md
canonical form used by every skill and agent. Claude Code expands
この規約により scripts/*.py にある55個のスクリプトが単一のエントリポイントに集約され、ホワイトリストと隔離されたvenvの有効化の前提となっています。手動インストール時、install.sh は sed を使用してこのトークンを `"$HOME/.claude/skills/seo/scripts/claude-seo"` に書き換えます（今回のインストールでコピーされた .md ファイルのみを対象とし、冪等性が保たれます）。
ランチャーはインタプリタの解決のみを行います。CLAUDE_SEO_PYTHON → py -3 → python3 → python の順序で >=3.10 のインタプリタを探索し、すべて失敗した場合はエラーを出力して終了します。ランチャー自体が何かをインストールすることはありません。
scripts/claude-seo
echo "Claude SEO requires Python 3.10 or newer. Tried CLAUDE_SEO_PYTHON, py -3, python3, and python." >&2
検出スクリプトは `-c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)'` を実行し、発見後は同ディレクトリの runtime.py を exec します。CLAUDE_SEO_PYTHON はシェルの評価コマンドではなく単一の配列要素として扱われ、コメントではインジェクション防止およびスペースを含むパスへの安全な対応のためと明記されています。
ランタイムは scripts/runtime.py にあります。`run` サブコマンドは、まずスクリプトのホワイトリスト検証（コアスクリプト52個の frozenset + ファイル名正規表現 + ディレクトリトラバーサル検査）を行い、隔離されたvenvのインタプリタで実行します。ランタイムが準備されていない場合は、明示的に `/seo setup` の事前実行を要求します。
scripts/runtime.py
raise ValueError("script is not in the bundled runtime allowlist")
実態確認: scripts/ 配下の55個の .py のうち、release_sign.py、verify_release.py、runtime.py のみがホワイトリスト対象外です（リリースツールおよび呼び出されるランタイム自身はエージェントから呼び出し不可）。extensions/*/scripts は独立した extension 引数パスを通り、banana 拡張には手動レイアウト用のフォールバック MANUAL_EXTENSION_SKILLS も備わっています。
`/seo setup` は永続データディレクトリ内にアトミックにvenvを構築します: venv --without-pip → ensurepip → pip install -r requirements.txt → playwright install chromium。いずれかのフェーズで失敗した場合は完全にロールバックされます。
scripts/runtime.py
[str(staged_python), "-m", "pip", "install", "--disable-pip-version-check", "-r", str(root / "requirements.txt")],
これは本プラグインにおける唯一の大規模な外部ネットワークパッケージインストール処理です。依存関係は requirements.txt（18パッケージ、各行にCVE注記付き）で固定されています。Chromiumは --skip-browser でスキップ可能であり、レンダリング環境が不完全な場合は終了コード10（「コア機能は利用可能、ブラウザは不完全」）を返し、install.sh/install.ps1 が警告通知として処理します。
プラグインには組み込みの PostToolUse フックが用意されています。Edit/Write の実行ごとに Node 経由で hooks/validate-schema.py が起動され、書き込まれたファイル内の JSON-LD を検証します。プレースホルダーや非推奨（deprecated）などのスキーマエラーが検出された場合、終了コード2で編集操作をブロックします。
hooks/hooks.json
"${CLAUDE_PLUGIN_ROOT}/hooks/run-python-hook.js",
hooks.json ではマッチャー `Edit|Write` のみが宣言されています。run-python-hook.js がクロスプラットフォームでPythonを探索し（Windows Storeのエイリアススタブ検出を含む）、validate-schema.py は .html/.htm/.jsx/.tsx/.vue/.svelte/.php/.ejs のみを処理、10MiBを超えるファイルはスキップします。FAQPageは意図的にブロックされません（GoogleはFAQリッチリザルトを廃止しましたが、スキーマ型自体は有効なため）。手動インストールではフックファイルがコピーされるのみであり、install.sh には「hook enforcement requires plugin install」と明記されています。
対象サイトへのデータ取得は、SSRFおよびDNSリバインディング対策レイヤーで統一されています。fetch_page.py は url_safety.safe_requests_session を使用し、render_page.py / capture_screenshot.py は Playwright を使用して route() レイヤーで各サブリソースのホストを再検証します。
scripts/url_safety.py
Centralizes SSRF protection, DNS rebinding mitigation, and DNS-pinned HTTP
url_safety は validate_url_strict（全Aレコードを解決しプライベートIPを判定した上でピン留めIPを返却）、safe_requests_get/head/session、および CLAUDE_SEO_LOCAL_TARGETS ホワイトリスト（最初のトップレベルURLのみに適用され、リダイレクト/サブリソース/ブラウザリクエストには適用外。クラウドメタデータアドレスはホワイトリストにあっても拒否）を提供します。SECURITY.md では残存リスクとして、Chromium内部DNSとCONNECTプロキシによるピン留めの弱体化、IPv6専用ターゲットのフェイルクローズが自己開示されています。
オプション機能（8つのMCP拡張機能）はコアパッケージには含まれず、各インストーラーがMCPサーバーとユーザー認証情報を `~/.claude.json` の mcpServers にアトミックにマージし（chmod 0600 を適用）、ミラースキルを ~/.claude/skills/ にコピーします。
extensions/dataforseo/install.sh
os.chmod(tmp, 0o600)
同一のパターンが適用されます: firecrawl（FIRECRAWL_API_KEY）、banana（GOOGLE_AI_API_KEY → nanobanana-mcp）、ahrefs（AHREFS_API_TOKEN）。bing-webmaster、profound、seranking はキーを `~/.claude/settings.json` の env セクションに書き込みます。コードコメントでは settings.json の mcpServers に書き込まない理由が説明されています（「`mcpServers` is not a key Claude Code reads there」）。
2コア機能
01サイト全体監査のための並列サブエージェントオーケストレーション（/seo audit）
0224のサブスキルにわたるコマンドルーティング（`/seo <command> <url>` の単一エントリポイントから、テクニカル、コンテンツ、スキーマ、画像、GEO、ローカル、マップ、hreflang、Eコマース、被リンク、クラスタリング、SXO、ドリフト、プログラマティック、計画、レポート作成を網羅）
03Googleファーストパーティデータの統合（GSC / PageSpeed v5 / CrUX / Indexing / GA4 / Ads / NLP / YouTube）、保有する認証情報に応じて4段階の機能を提供
04AI検索およびGEO監査（AIクローラー到達性、llms.txtの検証、段落単位の引用性スコアリング、Google公式ガイダンス準拠）
05被リンクプロファイリングと有害リンク判定（Moz、Bing、Keywords Everywhere、Common Crawlの無料ソース + 有料DataForSEO + 生存確認クローラー）
06構造化データの検出・検証・生成、およびファイル編集時に不正なJSON-LDをフックによりブロックする機能
07SEOドリフト監視: baseline / compare / history の3段階ワークフローにより、主要なオンページSEO要素のスナップショットを保存して回帰比較を実行
08成果物生成: 監査結果を `{domain}-audit/` に構造化出力し、A4 PDF/HTML/Excel形式のプロフェッショナルレポート（weasyprint + matplotlib + openpyxl）を生成可能
3外部依存関係
| 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/[email protected]） |
| 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 包（扩展运行时）：[email protected]、@ycse/[email protected]、[email protected] |
| network | 任意用户指定目标站（HTTP 抓取 + Playwright 渲染 + 反链存活验证 + 截图） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: scripts/claude-seo (bash) → scripts/runtime.py: `run` でホワイトリストに登録された52個のスクリプトのいずれかを実行、`setup` でランタイムを構築
- scripts/ 或 SKILL.md: 外部言語パッケージ依存関係の動的インストールの宣言
- 网络端点: 外部ネットワークアクセスの宣言: pypi.org (runtime.py `-m pip install -r requirements.txt`、18パッケージ)
- 本地工作目录: ファイルの読み書きおよび成果物の出力: ~/.claude/skills/** (seoおよび24個のseo-*サブスキル、拡張ミラースキル)、~/.claude/agents/seo-*
監査ノート： レッド判定ではありません: 難読化や隠蔽されたペイロード（リポジトリ全体で base64/eval/exec/\xNN の該当ゼロ）、テレメトリなし、MITライセンス、SSRFおよびDNSリバインディングに対する堅牢なエンジニアリング対策（url_safety および91件の回帰テスト）、認証情報ファイルの0600パーミッション強制、完全可逆なアンインストール、READMEでの curl|bash に対するリスク警告と事前レビュー推奨がなされています。しかし、以下の理由によりイエロー基準を超過しています: ① プラグインをインストールするとホスト側に PostToolUse フックが登録され、Edit/Write のたびに Node+Python が実行され、終了コード2で編集をブロックできる（継続的なコード実行権限）; ② install.sh / setup は18個のパッケージをpipインストールし、Chromiumをダウンロードするほか、拡張機能インストーラーが npx 経由で5つのnpmパッケージを取得・ウォームアップする（サプライチェーンリスク。バージョンは固定されているがチェックサムや署名検証がなく、SECURITY.md にもインストーラー検証は「tracked for v2.3」と記載）; ③ 8個の拡張機能インストーラーが ~/.claude.json / ~/.claude/settings.json を読み書きし、認証情報（DataForSEOアカウント・パスワード、Ahrefs/Firecrawl/Geminiキーなど）を平文保存し、ユーザーの既存Claude設定を変更する; ④ 任意のサードパーティWebページを取得し、その内容に基づいてLLMに提案を出力させるという主目的から、プロンプトインジェクションの攻撃対象面が本質的に広範であり、対策が主にプロンプトレベルに依存している; ⑤ sync_flow.py がアップストリームリポジトリのテキストを自リポジトリの references に書き込み、外部コンテンツの取り込みチャネルを形成している。これらの挙動はいずれもユーザー環境に実質的な副作用をもたらすため、オレンジ（Orange）と判定します。利用前の推奨事項: フック設定を事前監査の対象に含めること、拡張機能の認証情報には専用の失効可能なキーを使用すること、信頼できないドメインに対してレンダリングパスを有効化しないこと。
5二重目の独立検証
- [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 如实标注。
6結論
最適な用途： 再現性があり、そのまま納品可能なSEOワークフローを求めるユーザーに最適です（代理店によるクライアントサイトの一括監査、インハウスSEOによる本番リリース前のセカンドオピニオン検証、独立コンサルタントによる提案用監査レポート作成など）。標準的なユースケースとしては、プラグイン導入後に `/seo setup` で隔離された実行環境を構築し、`/seo audit <url>` で並列サブエージェントを実行、必要に応じてGSCやPSIなどのデータを連携してPDFレポートを出力します。コンプライアンス要件が厳しい環境では、拡張機能を一切導入せずコアのみで使用することも可能です（デフォルトのコアはサードパーティAPIを使用せず、指定された対象サイトのみにアクセスします）。
不向きな用途： 「設定不要ですぐに使える」ことを期待するユーザー（初回に `/seo setup` で24個のpipパッケージのインストールとChromiumのダウンロードが必須です）、ホスト環境での編集時フックの登録が禁止されている環境（手動インストールで回避可能ですが、スキーマ検証の品質ゲートも失われます）、監査結果を公式なコンプライアンス認証として扱う用途（結果は特定コミット・特定時点でのスナップショットであり、業界の動向変化に依存します）、認証情報を平文JSONに保存することを許容できない環境（拡張機能がキーを ~/.claude.json または settings.json に書き込みます）、信頼できないサイトを直接レンダリングパスに流し込む高リスクな環境（ChromiumのDNSリバインディングが既知の残存リスクとして明記されています）には適していません。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload claude-seo.tar.gz
sha256:
Option B · Copy Guide for Agent50b15d6fd70df445…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 92795530b4.