google-search-console

Google Search Console スキル

Return Zero Inc. が作成

Claude Code に検索アナリティクス、URL 検査、サイトマップ管理、サイト確認機能を提供する、包括的な Google Search Console API スキルです。

使用する場面

• ユーザーが「Google Search Console」、「GSC」、「search console」に言及した場合
• ユーザーが検索パフォーマンス、クリック数、表示回数、CTR について尋ねた場合
• ユーザーが URL のインデックス登録状況や検査を必要としている場合
• ユーザーがサイトマップを管理したい場合
• ユーザーが検索順位やインデックス状況について尋ねた場合
• ユーザーが Google の SEO アナリティクスデータを必要としている場合

機能

1. 検索アナリティクス ⭐

• 検索パフォーマンスデータ（クリック数、表示回数、CTR、掲載順位）を照会
• 日付範囲、ページ、クエリ、国、デバイスでフィルタリング
• ディメンション（クエリ、ページ、国、デバイス、日付）でグループ化
• 期間を比較
• CSV/JSON にエクスポート

2. URL 検査

• 特定 URL のインデックス登録状況を確認
• クロール情報を表示
• モバイル ユーザビリティを確認
• インデックス登録の問題を特定
• URL のインデックス登録をリクエスト

3. サイトマップ管理

• サイトのすべてのサイトマップを一覧表示
• 新しいサイトマップを送信
• サイトマップを削除
• サイトマップのステータスとエラーを確認

4. サイト管理

• 確認済みのサイトをすべて一覧表示
• 新しいサイトを追加
• サイトを削除
• 確認ステータスを確認

環境変数

このスキルでは、jelly-dotenv が管理する環境変数を使用します。設定の詳細については、skills/jelly-dotenv/SKILL.md を参照してください。

オプション 1：サービスアカウント（推奨）

# Service account JSON key file path
GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/service-account.json

# Or inline JSON (for CI/CD environments)
GOOGLE_SERVICE_ACCOUNT_KEY_JSON='{"type":"service_account","project_id":"...","private_key":"..."}'

オプション 2：OAuth 2.0 クライアント認証情報

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REFRESH_TOKEN=your-refresh-token

共通設定

# Default site URL (optional, can be specified per request)
GOOGLE_SEARCH_CONSOLE_SITE_URL=https://your-site.com

# Alternative naming patterns (auto-detected)
GSC_SITE_URL=https://your-site.com
SEARCH_CONSOLE_SITE=sc-domain:your-site.com

変数は次のいずれかに設定できます：

• skills/jelly-dotenv/.env（スキル共通、優先度が最も高い）
• プロジェクトルートの /.env（プロジェクト固有、フォールバック）

設定

サービスアカウントの設定

1. Google Cloud Console に移動します
2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します
3. 「Google Search Console API」を有効にします
4. サービスアカウントを作成します：
   • IAM と管理 → サービス アカウントに移動します
   • サービスアカウントを作成します
   • JSON キーファイルをダウンロードします
5. サービスアカウントのメールアドレスを Search Console に追加します：
   • Search Console に移動します
   • 設定 → ユーザーと権限に移動します
   • サービスアカウントのメールアドレスを使ってユーザーを追加します
   • 「フル」または「制限付き」のアクセス権を付与します

OAuth 2.0 の設定

1. Google Cloud Console に移動します
2. OAuth 2.0 認証情報を作成します（ウェブアプリケーション）
3. 承認済みのリダイレクト URI を設定します
4. OAuth Playground またはアプリを使用して、更新トークンを取得します
5. 必要なスコープ：https://www.googleapis.com/auth/webmasters.readonly

使用シナリオ

シナリオ 1：検索パフォーマンスの概要

ユーザーのリクエスト：「過去 7 日間の検索パフォーマンスを表示してください」

スキルの動作：

1. 環境から認証情報を読み込みます
2. 日付範囲を指定して Search Analytics API にクエリを送信します
3. クリック数、表示回数、CTR、掲載順位を集計します
4. 傾向を示す Markdown テーブルに整形します

出力：

## Search Performance (Last 7 Days)

| Metric | Value | Change |
|--------|-------|--------|
| Clicks | 1,234 | +12% |
| Impressions | 45,678 | +8% |
| CTR | 2.7% | +0.3% |
| Avg Position | 15.2 | -2.1 |

### Top Queries
| Query | Clicks | Impressions | CTR | Position |
|-------|--------|-------------|-----|----------|
| keyword 1 | 234 | 5,678 | 4.1% | 8.5 |
| keyword 2 | 189 | 4,321 | 4.4% | 12.3 |

シナリオ 2：URL 検査

ユーザーのリクエスト：「https://example.com/page のインデックス登録状況を確認してください」

スキルの動作：

1. URL Inspection API を呼び出します
2. インデックス登録結果を解析します
3. カバレッジのステータスを確認します
4. モバイル ユーザビリティを表示します

出力：

## URL Inspection: https://example.com/page

| Property | Status |
|----------|--------|
| Index Status | ✅ Indexed |
| Crawled | 2024-01-15 |
| Canonical | https://example.com/page |
| Mobile Usability | ✅ Mobile friendly |
| Rich Results | ⚠️ 2 warnings |

シナリオ 3：サイトマップ管理

ユーザーのリクエスト：「すべてのサイトマップを表示して、新しいサイトマップを送信してください」

スキルの動作：

1. 既存のサイトマップを一覧表示します
2. ステータスと最終送信日を表示します
3. 新しいサイトマップ URL を送信します
4. 送信を確認します

シナリオ 4：上位ページの分析

ユーザーのリクエスト：「パフォーマンスの高いページを教えてください」

スキルの動作：

1. ページ別にグループ化して Search Analytics にクエリを送信します
2. クリック数順に並べ替えます
3. 表示回数、CTR、掲載順位を含めます
4. 表示回数は多いものの CTR が低いページを強調します

API リファレンス

Search Analytics クエリ

interface SearchAnalyticsRequest {
  startDate: string;      // YYYY-MM-DD
  endDate: string;        // YYYY-MM-DD
  dimensions?: ('query' | 'page' | 'country' | 'device' | 'date')[];
  searchType?: 'web' | 'image' | 'video' | 'news';
  dimensionFilterGroups?: FilterGroup[];
  aggregationType?: 'auto' | 'byPage' | 'byProperty';
  rowLimit?: number;      // Max 25000
  startRow?: number;
}

URL 検査

interface UrlInspectionRequest {
  inspectionUrl: string;
  siteUrl: string;
  languageCode?: string;
}

サイトマップ操作

操作	メソッド	エンドポイント
一覧表示	GET	/webmasters/v3/sites/{siteUrl}/sitemaps
取得	GET	/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}
送信	PUT	/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}
削除	DELETE	/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}

出力形式

Markdown（デフォルト）

• 指標を含む整形済みテーブル
• トレンド表示（↑↓）
• ステータスアイコン（✅⚠️❌）
• 重要な分析結果の概要

JSON

• API レスポンスをそのまま出力
• 完全なデータ構造
• プログラムからのアクセス

CSV

• スプレッドシート対応のエクスポート
• すべてのデータ行
• さらなる分析用

エラー処理

認証エラー

エラー	原因	解決策
401 Unauthorized	認証情報が無効です	サービスアカウントキーまたは OAuth トークンを確認してください
403 Forbidden	サイトへのアクセス権がありません	Search Console にサービスアカウントを追加してください
Invalid scope	OAuth スコープが間違っています	webmasters.readonly スコープを使用してください

API エラー

エラー	原因	解決策
404 Not Found	サイトが Search Console にありません	先に Search Console にサイトを追加してください
400 Bad Request	パラメーターが無効です	日付形式（YYYY-MM-DD）を確認してください
429 Rate Limit	リクエストが多すぎます	待機して、バックオフを適用して再試行してください

よくある問題

「Configuration error: No Google credentials found」

# Solution: Add credentials to .env
GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/key.json

「Site not found or no access」

# Solution: Add service account email to Search Console
# Go to: Search Console → Settings → Users and permissions

「Invalid date range」

# Solution: Use YYYY-MM-DD format, max 16 months historical data

セキュリティポリシー

認証

• サービスアカウント：サーバー側での使用に推奨
• OAuth 2.0：ユーザー認証が必要なリクエスト用
• 認証情報：環境変数からのみ読み込み
• ログ記録：秘密鍵とトークンは自動的にマスキング

データアクセス

• デフォルトは読み取り専用：webmasters.readonly スコープを使用
• 書き込み操作：サイトマップの送信／削除にはフルスコープが必要
• サイト単位：アクセスは許可されたサイトのみに限定

レート制限

• 自動：Google API の割り当てを遵守
• 再試行：429 エラー発生時に指数バックオフを適用
• 1 日あたりの割り当て：1 日あたり 1,200 クエリ（デフォルト）

制限事項

• 過去のデータ：検索データは最大 16 か月分
• データの鮮度：検索アナリティクスには 2～3 日の遅延があります
• URL 検査：サイトあたり 1 日 2,000 リクエスト
• 行数制限：クエリあたり最大 25,000 行
• ディメンション：クエリあたり最大 3 個

Claude Code との連携

ユーザーが次の語句に言及すると、このスキルが自動的に有効になります：

• 「google search console」、「gsc」、「search console」
• 「search performance」、「search analytics」
• 「url inspection」、「index status」
• 「sitemap」、「sitemap management」
• 「seo analytics」、「seo data」

このスキルは次の処理を行います：

1. .env から Google の認証情報を読み込む
2. 要求されたクエリ／操作を実行する
3. 結果を Markdown テーブルとして整形する
4. 実行可能な分析結果と推奨事項を提示する

参考資料

• Google Search Console API ドキュメント
• Search Analytics API リファレンス
• URL Inspection API リファレンス
• OAuth 2.0 の設定
• API の割り当てと制限