はじめに
Claude Code に「サーチコンソールの直近30日の上位クエリ教えて」と頼んだとき、毎回こんな curl をこねくり回していませんか。
TOKEN=$(gcloud auth application-default print-access-token)
curl -s -X POST "https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fexample.com/searchAnalytics/query" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: my-gcp-project" \
-d '{ "startDate": "...", "endDate": "...", "dimensions": ["query"], ... }' \
| python3 -m json.tool
OAuth スコープ追加 → クォータプロジェクト指定ヘッダ → JSON 整形 → 日付計算…毎回これをやっていると無駄ですし、何より Claude Code が「ユーザーの隣で気軽に SEO 分析する相棒」になりません。
Claude Code の スキル(Skill) という仕組みでこれを丸ごとカプセル化して、しかもプラグインとしてパブリックリポジトリで公開できる、というところまでやったので記事にします。
リポジトリ: https://github.com/yousan/claude-skill-search-console
Claude Code のスキルとは
Claude Code には公式に「スキル」という拡張機構があり、~/.claude/skills/<name>/SKILL.md というファイルを置いておくと、以後そのプロジェクトでの会話中に トリガー条件にマッチしたら Claude が自動的にスキルを起動 してくれます。
スキル本体は単なる Markdown + 任意のスクリプト群なので、
- Claude が読む手順書(
SKILL.md) - スキル内から実行できる shell スクリプト等
- 設定ファイル
を1ディレクトリにまとめておくだけ。シンプルです。
SKILL.md の冒頭に Frontmatter を書きます。
---
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.
compatibility: claude-code-only
---
description がトリガー判定の核です。「サーチコンソールの上位ページは?」「検索クエリは?」のような問いに対して Claude が自分で「あ、これ search-console スキル使うやつだ」と気付いてくれるように、自然言語で どういうとき呼ぶか を書きます。
何を作ったか
リポジトリ構成:
claude-skill-search-console/
├── .claude-plugin/plugin.json # プラグインマニフェスト
├── README.md
├── skills/
│ └── search-console/
│ ├── SKILL.md # スキル本体(手順書)
│ ├── config.example.json # 設定例
│ └── scripts/
│ ├── _common.sh # 共通ヘルパー(認証/設定解決)
│ ├── sc-query.sh # クエリ・ページ等の集計取得
│ ├── sc-compare.sh # 前月比
│ └── sc-join-titles.sh # ページURL → WP投稿タイトル結合
主な機能:
-
sc-query.sh --dim query --limit 25… クエリ Top 25 -
sc-query.sh --dim page… ページ Top -
sc-compare.sh --dim total… サイト全体の前月比 -
sc-compare.sh --dim page --limit 20… ページ別前月比 -
sc-query.sh --dim page --format json | sc-join-titles.sh… URL を WP 投稿タイトルに結合
WordPress サイトを運用していると Search Console のページ一覧は https://example.com/archives/123 のような URL の羅列で見にくい、というのが個人的なペインだったので、wp post get <ID> --field=title で結合する仕組みも入れています。
設計のキモ:設定の優先順位
複数サイトで使い回すために、設定の優先順位を 環境変数 > config.json > gcloud デフォルト に統一しました。
config.json:
{
"default_site": "mysite",
"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"
}
}
}
サイト切り替えは --site mysite で。複数サイトを順番に分析する用途にもそのまま使えます。
config.jsonには SSH 接続先などの機密情報が入るため、.gitignoreに必ずskills/*/config.jsonを追加してから運用を始めてください。コミットすべきはconfig.example.jsonのみです。
クォータプロジェクトという落とし穴
Search Console API を初めて叩くと、たいていここで詰まります。
The searchconsole.googleapis.com API requires a quota project, which is not set by default.
「クォータプロジェクト(quota project)」 とは、その API 呼び出しが「どの GCP プロジェクトに紐づくか」を指定するもので、
- API が有効化されているプロジェクトの確認
- 1日あたりのリクエスト数制限(クォータ)の管理
- 課金(有料 API の場合)
の3つを担います。Search Console API は無料ですが、それでも どのプロジェクトのクォータを使うか の指定は必須です。
ADC(Application Default Credentials)で認証している場合、指定方法は2つ:
-
リクエストごとに
x-goog-user-project: <PROJECT_ID>ヘッダを付ける -
ADC 全体に設定
gcloud auth application-default set-quota-project <PROJECT_ID>で永続化
このスキルでは config.json の quota_project から読み取って自動で 1 のヘッダを付与しているので、利用者は意識しなくて OK です。
OAuth スコープの追加
gcloud auth application-default login を素で叩くと、デフォルトのスコープでは Search Console API は呼べません。--scopes フラグでスコープを明示する必要があります。
gcloud auth application-default login \
--scopes="https://www.googleapis.com/auth/webmasters.readonly,https://www.googleapis.com/auth/cloud-platform"
ADC は OS のユーザー単位（実体は ~/.config/gcloud/application_default_credentials.json）なので一度承認しておけば、以後どのプロジェクト(tmux ウィンドウ)でも同じトークンで叩けます。これがめちゃくちゃ便利。
スクリプトの作り方ポイント
共通ヘルパーで認証と設定解決をまとめる
_common.sh を sourceするだけで SITE_URL QUOTA_PROJECT WP_SSH WP_PATH WP_BIN_PATH が解決済みになります。本体スクリプトは sc_resolve_site を呼ぶだけ。
sc_resolve_site "$SITE_KEY"
RESP=$(sc_api_post "searchAnalytics/query" "$BODY")
sc_api_post は内部で
- gcloud で access token 取得
- サイト URL を URL エンコード
- クォータプロジェクトヘッダ付与
を全部やってくれます。
出力フォーマットを切り替えられるようにする
ターミナルで眺めたいときは表、別スクリプトに繋ぎたいときは JSON、Excel に貼りたいときは CSV、と用途別に切り替えたい。--format table|json|csv を全コマンドに揃えておくと使い勝手が一気に上がります。
sc-query.sh --dim page --format json | sc-join-titles.sh
このパイプラインで「Search Console から API でページ取得 → SSH 越しに wp-cli でタイトル取得 → 結合」が1行で書けるのは個人的にお気に入りです。
パブリック公開する
スキル本体は ~/.claude/skills/search-console/ に置いておけば自分のローカルで使えます。これを公開するために、別ディレクトリに「プラグイン形式」でコピーして GitHub に上げました。
プラグイン形式といっても大したことはなく、
my-plugin-repo/
├── .claude-plugin/plugin.json # 名前・バージョン等のメタデータ
├── README.md
└── skills/
└── <skill-name>/
├── SKILL.md
└── ...
の構成にして、.gitignore に skills/*/config.json を入れて自分のサイト情報をコミットしないようにする、それだけです。
利用者側は:
git clone https://github.com/yousan/claude-skill-search-console.git
cp -r claude-skill-search-console/skills/search-console ~/.claude/skills/
cp ~/.claude/skills/search-console/config.example.json ~/.claude/skills/search-console/config.json
# config.json を自分のサイト情報に書き換える
chmod +x ~/.claude/skills/search-console/scripts/*.sh
これでインストール完了。次回以降の Claude Code セッションで「サーチコンソールの上位クエリは?」と聞くだけで自動的にこのスキルが動きます。
効果
導入前:
- ユーザー「サーチコンソールどう?」
- Claude「curl で叩きます…」(scope エラー、quota project エラー、JSON手動整形…の応酬)
導入後:
- ユーザー「サーチコンソールどう?」
- Claude(裏でスキル起動)「直近30日の上位クエリは…(整形済みの表)…伸びているのはバランサー系ですね」
体感が完全に変わりました。
まとめ
- Claude Code のスキルは
~/.claude/skills/<name>/SKILL.mdを置くだけで作れる - 自然言語の
descriptionでトリガー条件を書くと Claude が勝手に呼んでくれる - スクリプトに認証・クォータプロジェクト・JSON 整形を全部隠蔽すれば「Claude に頼める便利な相棒」になる
- プラグイン形式にして GitHub に置けばパブリック公開できる
リポジトリ: https://github.com/yousan/claude-skill-search-console
PR、Issue、ご意見お待ちしています。同じパターンで Google Analytics 用、Slack 用などいくらでも作れる気がしているので、気が向いたらそっちもやってみたいです。
参考リンク
- Claude Code: スキル(Skill)
- Claude Code: SKILL.md Frontmatter リファレンス
- Claude Code: プラグインリファレンス
- Google Search Console API: Search Analytics: query
- Google Cloud: Application Default Credentials (ADC)
- Google Cloud: クォータプロジェクトを設定する
- Google Cloud: API システムパラメータ (
x-goog-user-project) - gcloud:
auth application-default login - gcloud:
auth application-default set-quota-project - WP-CLI:
wp post get