seo

SEO スキル（エージェント型／Claude／Codex）

LLM ファーストの SEO 分析スキルです。ウェブサイト、ブログ、GitHub リポジトリの最適化に対応する、16 の専門サブスキル、10 の専門エージェント、89 のスクリプトを備えています。

決定論的なトリガーマッピング

Codex／エージェント IDE でプロンプトの信頼性を高めるため、よく使われるユーザーの表現を固定のワークフローに対応付けます。

• ユーザーが perform seo analysis on <url>（または URL を含む、同様の一般的な SEO リクエスト）と言った場合は、単一 URL の完全監査として扱います。
• 明示的なサブスキルの指定がない場合は、LLM ファーストの推論とスクリプトで裏付けられた証拠を用いて、完全監査／ページ監査の手順を実行します。
• 完全監査／ページ監査では、必ず次の成果物を作成します。
  • FULL-AUDIT-REPORT.md（詳細な調査結果）
  • ACTION-PLAN.md（優先順位を付けた修正項目）
• generate_report.py を実行した場合は、保存した HTML のパス（例：SEO-REPORT.html）も返します。

利用可能なコマンド

コマンド	サブスキル	説明
seo audit <url>	seo-audit	スコアリング付きのウェブサイト全体の監査
seo page <url>	seo-page	単一ページの詳細分析
seo technical <url>	seo-technical	技術的な SEO チェック
seo content <url>	seo-content	コンテンツの品質と E-E-A-T
seo schema <url>	seo-schema	スキーマの検出／検証／生成
seo sitemap <url>	seo-sitemap	サイトマップの分析と生成
seo images <url>	seo-images	画像最適化の監査
seo geo <url>	seo-geo	AI 検索最適化（GEO）
seo programmatic <url>	seo-programmatic	プログラマティック SEO の安全対策
seo competitors <url>	seo-competitor-pages	比較ページ／代替案ページ
seo hreflang <url>	seo-hreflang	国際 SEO の検証
seo plan <url>	seo-plan	戦略的な SEO 計画
seo github <repo_or_url>	seo-github	GitHub リポジトリの見つけやすさ、README、トピック、コミュニティの健全性、トラフィックの記録
seo article <url>	seo-article	記事データの抽出と LLM 最適化
seo links <url>	seo-links	外部バックリンクのプロファイルとリンクの健全性
seo aeo <url>	seo-aeo	回答エンジン最適化（強調スニペット、PAA、ナレッジパネル）

---

オーケストレーションロジック

ユーザーが SEO 分析を依頼した場合は、次のルーティングに従います。

ステップ 1 — タスクの特定

ユーザーのリクエストを解析し、実行するサブスキルを特定します。

• 完全監査：resources/skills/seo-audit.md を読み込みます。複数のページをクロールし、エージェントに処理を委任し、スコアリングしてレポートを作成します。
• 単一ページ：resources/skills/seo-page.md を読み込みます。1 つの URL を詳細に調査します。
• 特定の領域：該当する resources/skills/seo-*.md ファイルを読み込みます。
• 戦略的な計画：resources/skills/seo-plan.md と、特定された業界に該当する resources/templates/*.md を読み込みます。
• GitHub リポジトリの SEO：resources/skills/seo-github.md を読み込み、API／gh のフォールバックとして --provider auto を指定して GitHub スクリプトを使用します。
• 一般的な perform seo analysis on <url> リクエスト：単一ページの完全監査として扱い、resources/skills/seo-page.md を読み込んで、FULL-AUDIT-REPORT.md と ACTION-PLAN.md を作成します。

ステップ 2 — 証拠を収集する

主な方法（LLM 優先） — まず組み込みの read_url_content ツールを使用します：

read_url_content(url)  →  returns parsed HTML content directly

これを推論の基準となる証拠として使用します。

確定的な検証（スクリプトを実行できる場合に推奨）：

# Fetch/parse raw HTML for structured checks
python3 <SKILL_DIR>/scripts/fetch_page.py <url> --output /tmp/page.html
python3 <SKILL_DIR>/scripts/parse_html.py /tmp/page.html --url <url> --json

# Optional: generate shareable HTML dashboard artifact
python3 <SKILL_DIR>/scripts/generate_report.py <url> --output SEO-REPORT.html

サイトを直接取得できる場合や、同梱スクリプトを利用できる場合は、サードパーティのミラー（例：r.jina.ai）を主な証拠として使用しないでください。 <SKILL_DIR> = このスキルディレクトリ（この SKILL.md を含むフォルダー）の絶対パスです。

ステップ 3 — LLM 優先の分析を行う

LLM を主な SEO アナリストとして使用します。

1. ページのコンテンツ、メタデータ、任意のスクリプト出力から得られた証拠を総合します。
2. 明確な根拠を添えて調査結果を提示します：
   • Finding（調査結果）
   • Evidence（具体的な要素、指標、または抜粋）
   • Impact（ランキング／インデックス登録／UX にとって重要な理由）
   • Fix（明確な実装手順）
3. 影響度と実装工数に基づいて優先順位を付けます。
4. 確認済みの問題、可能性の高い問題、不明点（データ不足）を分けます。

監査の種類を問わず、スコア、重大度、信頼度、出力構造の一貫性を保つため、必ず resources/references/llm-audit-rubric.md を読み、適用してください。

ステップ 4 — 基準検証スクリプトを実行する（実行できる場合）

全体監査／ページ監査では、仮説だけに基づく報告を避けるため、基準チェックを実行します。スクリプトだけのスコアリングで LLM の推論を置き換えないでください。

# Check robots.txt and AI crawler management
python3 <SKILL_DIR>/scripts/robots_checker.py <url>

# Check llms.txt for AI search readiness
python3 <SKILL_DIR>/scripts/llms_txt_checker.py <url>

# Get Core Web Vitals from PageSpeed Insights (free API, no key needed)
python3 <SKILL_DIR>/scripts/pagespeed.py <url> --strategy mobile

# Check security headers (HSTS, CSP, X-Frame-Options, etc.)
python3 <SKILL_DIR>/scripts/security_headers.py <url>

# Detect broken links on a page (404s, timeouts, connection errors)
python3 <SKILL_DIR>/scripts/broken_links.py <url> --workers 5

# Trace redirect chains, detect loops and mixed HTTP/HTTPS
python3 <SKILL_DIR>/scripts/redirect_checker.py <url>

# Analyze readability from fetched HTML (Flesch-Kincaid, grade level, sentence stats)
python3 <SKILL_DIR>/scripts/readability.py /tmp/page.html --json

# Validate Open Graph and Twitter Card meta tags
python3 <SKILL_DIR>/scripts/social_meta.py <url>

# Analyze internal link structure, find orphan pages
python3 <SKILL_DIR>/scripts/internal_links.py <url> --depth 1 --max-pages 20

# Extract article content and perform keyword research for LLM-driven optimization
python3 <SKILL_DIR>/scripts/article_seo.py <url> --keyword "<optional_target_keyword>" --json

# Credentials for paid/auth APIs (PageSpeed, GitHub, GSC, Knowledge Graph)
# are loaded from CLI flags, then env vars, then a `.env` file in the repo
# root / cwd / `~/.agentic-seo/.env`. Copy `.env.example` to `.env` and fill
# in only the keys you have. Never paste secrets in prompts.

# GitHub repository SEO (provider fallback: auto|api|gh)
# Auth setup (choose one):
# export GITHUB_TOKEN="ghp_xxx"   # or export GH_TOKEN="ghp_xxx"
# gh auth login -h github.com && gh auth status -h github.com
python3 <SKILL_DIR>/scripts/github_repo_audit.py --repo <owner/repo> --provider auto --json
python3 <SKILL_DIR>/scripts/github_readme_lint.py README.md --json
python3 <SKILL_DIR>/scripts/github_community_health.py --repo <owner/repo> --provider auto --json
# Benchmark/competitor inputs should be provided by LLM/web-search discovery when possible.
# If omitted, github_seo_report.py auto-derives repo-specific benchmark queries.
python3 <SKILL_DIR>/scripts/github_search_benchmark.py --repo <owner/repo> --query "<llm_or_web_query>" --provider auto --json
python3 <SKILL_DIR>/scripts/github_competitor_research.py --repo <owner/repo> --query "<llm_or_web_query>" --provider auto --top-n 6 --json
python3 <SKILL_DIR>/scripts/github_competitor_research.py --repo <owner/repo> --competitor <owner/repo> --competitor <owner/repo> --provider auto --json
python3 <SKILL_DIR>/scripts/github_traffic_archiver.py --repo <owner/repo> --provider auto --archive-dir .github-seo-data --json
python3 <SKILL_DIR>/scripts/github_seo_report.py --repo <owner/repo> --provider auto --markdown GITHUB-SEO-REPORT.md --action-plan GITHUB-ACTION-PLAN.md --json
# Optional: increase/reduce auto-derived query volume (default: 6)
# python3 <SKILL_DIR>/scripts/github_seo_report.py --repo <owner/repo> --provider auto --auto-query-max 8 --markdown GITHUB-SEO-REPORT.md --action-plan GITHUB-ACTION-PLAN.md --json

ネットワーク、DNS、権限、または API のレート制限が原因でチェックに失敗した場合：

• それを確認済みのサイトの問題ではなく、環境上の制約として明示します。
• 該当するカテゴリーの信頼度は Hypothesis のままにします。
• 監査を中断せず、利用可能な証拠に基づいて続行します。
• フォールバックを繰り返すループに入らないでください。失敗したソースの再試行は最大 1 回にしてから、監査を完了します。
• 同じ URL に対するウェブ検索とスクレイピングを繰り返す方向に切り替えないでください。

視覚分析（Playwright が必要です。利用可能な場合は conda activate pentest を使用します）：

# Capture screenshots (desktop, laptop, tablet, mobile)
python3 <SKILL_DIR>/scripts/capture_screenshot.py <url> --all

# Analyze visual layout, above-the-fold, mobile responsiveness
python3 <SKILL_DIR>/scripts/analyze_visual.py <url> --json

HTML レポートジェネレーター — 自己完結型のインタラクティブな HTML ダッシュボードを生成します：

# Generate full SEO report (runs scripts automatically, saves HTML to PWD)
python3 <SKILL_DIR>/scripts/generate_report.py <url>
python3 <SKILL_DIR>/scripts/generate_report.py <url> --output custom-report.html

ステップ 5 — 専門エージェントに委任する

包括的な監査では、resources/agents/ から関連するエージェントファイルを読み込み、専門家の役割を担います：

Agent	File	Focus Area
技術 SEO	seo-technical.md	クロール可能性、インデックス登録可能性、セキュリティ、URL、モバイル、CWV、JS のレンダリング
コンテンツ品質	seo-content.md	E-E-A-T の評価、コンテンツ指標、AI コンテンツの検出
パフォーマンス	seo-performance.md	Core Web Vitals（LCP、INP、CLS）、最適化の推奨事項
スキーママークアップ	seo-schema.md	JSON-LD 構造化データの検出、検証、生成
サイトマップ	seo-sitemap.md	XML サイトマップの検証、生成、品質ゲート
視覚分析	seo-visual.md	スクリーンショット、ファーストビュー、レスポンシブ対応、レイアウト
検証担当（全体）	seo-verifier.md	最終レポートの前に調査結果の重複を排除し、矛盾を抑制し、証拠の関連性を検証する

ステップ 6 — 品質ゲートを適用する

resources/references/ にある品質基準を参照します。

• コンテンツの最低基準：語数、独自コンテンツの割合、タイトル／メタデータの要件については、quality-gates.md を確認してください
• スキーマの検証：有効／非推奨／制限付きのタイプについては、schema-types.md を確認してください
• Core Web Vitals：現在の指標のしきい値については、cwv-thresholds.md を確認してください
• E-E-A-T フレームワーク：採点基準については、eeat-framework.md を確認してください
• Google のリファレンス：簡易リファレンスとして、google-seo-reference.md を確認してください
• LLM レポートの評価基準：必須のエビデンス形式、確信度ラベル、出力契約については、llm-audit-rubric.md を確認してください

ステップ 6.5 — 調査結果を検証する（すべてのワークフロー）

最終レポートを作成する前に、検証を実行します。

python3 <SKILL_DIR>/scripts/finding_verifier.py --findings-json <raw_findings.json> --json

最終レポートの表には、生の調査結果ではなく、検証済みの出力を使用します。

ステップ 7 — 採点して報告する

数値スコアは指針として使用し、エビデンスの質や判断の代わりにしないでください。

デフォルトの採点ウェイト（フル監査）

正規の信頼できる情報源 — このウェイトは、ここおよび resources/skills/seo-audit.md で定義されています。 スコアの一貫性を保つため、個々のサブスキルファイルのウェイトは変更せず、この 2 か所のみを更新してください。

カテゴリ	ウェイト
テクニカル SEO	25%
コンテンツ品質	20%
オンページ SEO	15%
スキーマ／構造化データ	15%
パフォーマンス（CWV）	10%
画像の最適化	10%
AI 検索への対応（GEO）	5%

scripts/generate_report.py を使用する場合、自動ダッシュボードでは、そのスクリプト内で定義されたスクリプトレベルのカテゴリウェイトが使用されます。ナラティブ形式の監査では、LLM を優先し、エビデンスを重視してください。

ステップ 8 — 必須の成果物

seo audit、seo page、および汎用の perform seo analysis on <url> フローでは、次の手順を実行します。

1. 監査開始時に、現在の作業ディレクトリに FULL-AUDIT-REPORT.md を作成し、エビデンスの収集に合わせて更新します。
2. 監査開始時に、現在の作業ディレクトリに ACTION-PLAN.md を作成し、優先順位を付けた修正内容を記載して更新します。
3. HTML ダッシュボードを生成した場合は、保存先の正確なパス（例：SEO-REPORT.html または絶対パス）を記載します。
4. 最終回答で、生成した成果物とそのパスを明示的に列挙します。
5. 環境の制限により技術的なチェックが実行できない場合でも、両方の Markdown ファイルを作成し、「Environment Limitations」セクションを含めます。

スコアの解釈

スコア	評価
90-100	優秀
70-89	良好
50-69	改善が必要
30-49	不良
0-29	重大

---

業界の検出

seo plan を実行するときは、事業の種類を検出し、該当するテンプレートを読み込みます。

業界	テンプレートファイル
SaaS／ソフトウェア	saas.md
地域密着型サービス事業	local-service.md
E コマース／小売	ecommerce.md
出版社／メディア	publisher.md
エージェンシー／コンサルティング	agency.md
その他／汎用	generic.md

検出の手がかり：

• SaaS：料金ページ、機能ページ、/docs、/api、トライアル／デモの CTA
• 地域密着型：住所、電話番号、Google ビジネス プロフィール、サービス提供地域のページ
• E コマース：商品ページ、カート、チェックアウト、/collections、/categories
• 出版社：記事の日付、著者ページ、/news、大量のコンテンツ
• エージェンシー：事例紹介、/work、/portfolio、チームページ、サービス内容

---

スキーマテンプレート

事前構築済みの JSON-LD テンプレートを templates.json で利用できます。

• 一般：BlogPosting、Article、Organization、LocalBusiness、BreadcrumbList、WebSite（SearchAction を含む）
• 動画：VideoObject、BroadcastEvent、Clip、SeekToAction
• E コマース：ProductGroup（バリエーション）、OfferShippingDetails、Certification
• その他：SoftwareSourceCode、ProfilePage（E-E-A-T の著者ページ）

---

検証スクリプト

CI/CD 統合用に、2 つの検証スクリプトを利用できます。

コミット前 SEO チェック

bash <SKILL_DIR>/scripts/pre_commit_seo_check.sh

ステージングされた HTML ファイルをチェックし、スキーマ内のプレースホルダーテキスト、title タグの長さ、alt テキストの欠落、非推奨のスキーマタイプ、FID への言及（INP にする必要があります）、メタディスクリプションの長さを確認します。

スキーマバリデーター

python3 <SKILL_DIR>/scripts/validate_schema.py <file_path>

HTML ファイル内の JSON-LD ブロックを検証します。JSON 構文、@context/@type の有無、プレースホルダーテキスト、非推奨または制限対象のタイプを確認します。

スキルインベントリバリデーター

python3 <SKILL_DIR>/scripts/validate_skill_inventory.py

ドキュメントに記載されたサブスキル、エージェント、スクリプトの数と、ディスク上のファイルを照合して検証します。CI ではこれを使用して、README と SKILL のインベントリの不一致を防ぎます。

リファレンスの鮮度バリデーター

python3 <SKILL_DIR>/scripts/reference_freshness.py <SKILL_DIR>/resources/references --max-age-days 90

すべてのリファレンスファイルに `` マーカーがあることを確認し、設定された鮮度期間を超えているリファレンスに警告します。

---

出力形式

すべてのサブスキルレポートで、一貫した重大度レベルを使用してください。

• 🔴 重大 — ランキングまたはインデックス登録に直接影響します（直ちに修正）
• ⚠️ 警告 — 最適化の機会です（1 か月以内に修正）
• ✅ 合格 — 基準を満たしているか、上回っています
• ℹ️ 情報 — 該当しない、または情報提供のみ

レポートは次の構成にしてください。

1. 要素、値、重大度を含む概要表
2. カテゴリ別にまとめた詳細な調査結果
3. 影響度の高い順に並べた、実行可能な推奨事項

---

重要なルール

1. FID ではなく INP — FID は 2024 年 9 月 9 日に廃止されました。唯一のインタラクティビティ指標は INP（Interaction to Next Paint）です。FID には決して言及しないでください。
2. FAQ スキーマは制限対象 — FAQPage スキーマは、政府機関および医療機関の権威あるサイトにのみ制限されています（2023 年 8 月）。商用サイトには推奨しないでください。
3. HowTo スキーマは非推奨 — リッチリザルトは 2023 年 9 月に完全に廃止されました。決して推奨しないでください。
4. JSON-LD のみ — 常に <script type="application/ld+json"> を使用してください。Microdata や RDFa は決して推奨しないでください。
5. E-E-A-T はあらゆる場面で適用 — 2025 年 12 月時点で、E-E-A-T は YMYL だけでなく、競争のあるすべてのクエリに適用されます。
6. モバイルファーストは完了済み — 2024 年 7 月 5 日以降、モバイルファーストインデックス登録が 100％ 実施されています。
7. ロケーションページの上限 — 30 ページ以上で警告し、50 ページ以上で厳格に停止してください。固有コンテンツの要件を徹底してください。
8. AI クローラーの管理 — robots.txt で GPTBot、ClaudeBot、PerplexityBot、Applebot-Extended、Google-Extended、Bytespider、CCBot を確認してください。
9. LLM ファーストで、障害に強いパイプライン — まず read_url_content でページを読み込み、その後、構造化された根拠を得るために必ず関連スクリプトを実行してください。スクリプトは根拠の優先ソースです。積極的に使用してください。ただし、スクリプトが失敗した場合（タイムアウト、ネットワーク、解析エラー）でも、LLM は独自の推論を用いて、完全な分析を必ず作成してください（信頼度：Likely）。単一のスクリプトの失敗を理由にレポートを停止しないでください。
10. 監査フローでは常にファイル成果物を作成 — 完全監査またはページ監査のリクエストでは、FULL-AUDIT-REPORT.md と ACTION-PLAN.md が必須の出力です。
11. 根拠の再試行回数に上限を設ける — 長時間の検索や再試行ループを避けてください。DNS／ネットワークの問題で重要なチェックに失敗した場合は、信頼度ラベルとファイル出力を含めて速やかに完了してください。
12. 冗長な Web フォールバックを避ける — 直接取得／スクリプトが失敗し、さらにフォールバックも 1 回失敗した場合は、再試行を中止し、制約を明示してレポートを完成させてください。
13. シグナルの鮮度を追跡 — すべてのリファレンスファイルに `` コメントを含めてください。90 日を超えたリファレンスファイルはレビュー対象として警告してください。Google がアルゴリズムの変更を発表した場合は、影響を受けるリファレンスファイルを 7 日以内に確認してください。追跡すべき重要な日付：コアアップデート（四半期ごと）、スキーマの非推奨化（schema-types.md）、CWV しきい値の変更（cwv-thresholds.md）。

---

依存関係

オプションのスクリプト依存関係

• Python 3.8+
• requests（ネットワーク分析スクリプト用）
• beautifulsoup4（HTML 解析スクリプト用）
• Playwright（capture_screenshot.py および analyze_visual.py 用）

  pip install playwright && playwright install chromium
  

  または、conda を使用している場合：conda activate pentest（Playwright が事前にインストールされている場合）

スクリプトの依存関係をインストールする

pip install requests beautifulsoup4