search-console

name	search-console
description	Query Google Search Console Search Analytics via the webmasters API. Use when the user asks about search queries, clicks, impressions, CTR, ranking positions, top pages, or month-over-month traffic on their site. Handles OAuth scope + quota project automatically, supports multiple sites via config, and can join page URLs with WordPress post titles for readability.
compatibility	claude-code-only

Search Console

Google Search Console Search Analytics を手早く引くためのラッパー群。gcloud auth application-default の ADC を利用し、クォータプロジェクトとサイトURLの指定を自動化する。

前提

• gcloud CLI インストール済み、gcloud auth application-default login で webmasters.readonly スコープを承認済み
  • 未承認なら: gcloud auth application-default login --scopes="https://www.googleapis.com/auth/webmasters.readonly,https://www.googleapis.com/auth/cloud-platform"
• jq と python3 が PATH にある
• gcloud が PATH にない場合は GCLOUD_BIN 環境変数で実体パスを指定(例: ~/google-cloud-sdk/bin/gcloud)

設定

優先順位: 環境変数 > ~/.claude/skills/search-console/config.json > gcloud デフォルト

設定ファイル形式

~/.claude/skills/search-console/config.json:

{
  "default_site": "welovefactorio",
  "sites": {
    "mysite": {
      "url": "https://example.com",
      "quota_project": "your-gcp-project-id",
      "wp_ssh": "user@host",
      "wp_path": "/var/www/example.com/public_html",
      "wp_bin_path": "/home/user/bin"
    }
  }
}

サイトごとのフィールド:

• url — Search Console 登録のサイトURL(必須、末尾スラッシュ等まで完全一致)
• quota_project — Google Cloud プロジェクトID(必須)
• wp_ssh — WP-CLI 用 SSH ホスト(任意。sc-join-titles.sh を使うなら必要)
• wp_path — リモート上の WordPress インストールパス(任意。sc-join-titles.sh で必要)
• wp_bin_path — リモート上の wp コマンドが置かれているディレクトリ(任意。リモートPATHに wp が無い場合に指定)

環境変数による上書き

• SC_SITE_URL — サイトURL
• SC_QUOTA_PROJECT — クォータプロジェクトID
• SC_WP_SSH — WP-CLI 用 SSH ホスト
• SC_WP_PATH — リモート WordPress インストールパス
• SC_WP_BIN_PATH — リモート上の wp コマンドのディレクトリ
• SC_SITE — 設定ファイル内のサイトキー
• GCLOUD_BIN — gcloud バイナリのパス

コマンド

スクリプトは scripts/ 配下。直接実行する。

sc-query

検索クエリ/ページ別集計を取得。

~/.claude/skills/search-console/scripts/sc-query.sh [options]

オプション:

• --dim DIM — 次元: query | page | country | device | date(既定: query)
• --start DATE — 開始日 YYYY-MM-DD(既定: 33日前)
• --end DATE — 終了日 YYYY-MM-DD(既定: 3日前。GSC のデータ反映に約 2-3 日かかるため)
• --limit N — 行数上限(既定: 25)
• --site KEY — 設定ファイル内のサイトキー
• --format table|json|csv — 出力形式(既定: table)
• --raw — API生レスポンスをそのまま出力

例:

# 直近30日のクエリ上位
sc-query.sh

# ページ別、直近60日、CSV
sc-query.sh --dim page --start 2026-02-20 --end 2026-04-20 --format csv

# JSON(他スクリプトへのパイプ用)
sc-query.sh --dim page --format json --limit 50

sc-compare

前月比(=期間Aと期間Bの比較)。

~/.claude/skills/search-console/scripts/sc-compare.sh [options]

オプション:

• --dim DIM — query | page | total(既定: total)
• --current-start / --current-end — 現期間(既定: 33日前〜3日前)
• --previous-start / --previous-end — 比較期間(既定: 現期間の直前同じ日数)
• --limit N — 表示行数(既定: 15)
• --site KEY

例:

# サイト全体の前月比
sc-compare.sh

# ページ別 前月比 Top 20
sc-compare.sh --dim page --limit 20

sc-join-titles

ページ URL の一覧を stdin で受け取り、WP 投稿タイトルを joined したテーブルを出力する。wp_ssh が設定されている必要あり。

sc-query.sh --dim page --format json | sc-join-titles.sh

URL から投稿IDを抽出し(/archives/<ID> or /archives/<cpt>/<ID>)、wp post get <ID> --field=title でタイトルを取得する。

ワークフロー

ユーザーが Search Console について聞いてきたときの流れ:

1. 初回: 設定ファイルの存在を確認。なければ config.json を作成する提案をする
2. 認証確認: gcloud auth application-default print-access-token で成功するか確認
3. スコープ/クォータ不足エラーが出たら、必要な手順を案内
   • スコープ不足 → gcloud auth application-default login --scopes=... を提示
   • クォータプロジェクト欠落 → 設定ファイルか env で指定するよう案内
4. 意図に応じてコマンド選択:
   • 「どんなクエリで来てる?」→ sc-query.sh --dim query
   • 「どのページが見られてる?」→ sc-query.sh --dim page + sc-join-titles.sh
   • 「前月比は?」→ sc-compare.sh
5. 結果をテーブル形式で要約し、所感(伸びている/落ちている/改善余地)を一言添える

トラブルシューティング

Insufficient Permission / ACCESS_TOKEN_SCOPE_INSUFFICIENT

ADC が webmasters.readonly スコープで承認されていない。gcloud auth application-default login --scopes="https://www.googleapis.com/auth/webmasters.readonly,https://www.googleapis.com/auth/cloud-platform" を実行。

requires a quota project, which is not set by default

クォータプロジェクトが未設定。以下のいずれかで解決:

• gcloud auth application-default set-quota-project <PROJECT_ID>(永続)
• SC_QUOTA_PROJECT 環境変数で指定
• config.json の quota_project に書く

SERVICE_DISABLED

そのプロジェクトで Search Console API が無効。gcloud services enable searchcoreconsole.googleapis.com --project=<PROJECT_ID>(※ 正確な API 名は searchconsole.googleapis.com)

データが0件

• サイトURLが正確に Search Console 登録値と一致しているか(末尾スラッシュ、http/https、www有無)
• 期間が GSC のデータ反映ラグ(約2-3日)より新しすぎないか

配布

このスキルはプラグイン形式にパッケージ化して個人リポジトリで公開可能。~/.claude/skills/search-console/ ディレクトリ丸ごとを、プラグインリポジトリの skills/search-console/ に配置すればよい。