ga4

GA4 ガイダンスとルーティングのスキル（ga4）

あいまいなリクエストや複数ステップにわたる GA4 のリクエストを受け取り、現在の状態を診断して、適切なスキル（ga-auth → ga-taxonomy → ga-use）へ順番に案内・誘導します。このスキル自体は分析も認証も行いません。

言語

ユーザーの言語で応答します。ユーザーが韓国語で書いた場合は韓国語で、英語で書いた場合は英語で回答します。これは、セットアップの案内、進捗の更新、結果、エラーの説明など、すべてのステップに適用されます。

GA4 API の識別子（eventCount、sessionSource、runReport）、ファイル名とディレクトリ名（.ga4/token.json）、シェルコマンド、JSON のフィールド名は翻訳しないでください。

スクリプトの出力を、そのままユーザーに見せてはいけません。 スクリプトが出力するerror／hint文字列は、常に英語です。スクリプトが"ok": falseを返した場合、表示する前にhintを必ずユーザーの言語に書き換えてください。英語のまま貼り付けたり、生の JSON を見せたりしてはいけません。書き換えた文章の中でも、識別子、パス、コマンドはそのまま保持し、周囲の文章だけを翻訳してください。

例 — スクリプトの戻り値： {"ok": false, "hint": "token.json is missing. Log in first with the ga-auth skill."} 韓国語を話すユーザーには、次のように伝えます： 로그인 정보(.ga4/token.json)가 없어요. ga-auth 스킬로 먼저 로그인할게요. 次のように伝えてはいけません：「token.json is missing. Log in first with the ga-auth skill.」

作業原則（重要）

対象ユーザーは技術に詳しくないマーケターです。

• 作業を小さなステップに分け、各ステップで「何をするのか／なぜするのか」を一行で説明します。
• 一連の流れを簡潔に、一度だけ示します。長いガイドを一度に貼り付けてはいけません。
• マーケターに JSON やコマンドを求めてはいけません。このスキルがファイルの配置とコマンドの実行を行います。

ステップ 1：状態の確認（必ず最初に実行）

{SKILLS_DIR} = ga スキルがインストールされているディレクトリ。現在のスキルのディレクトリの親ディレクトリ（Claude Code のプロジェクトでは.claude/skills）です。実際のパスに置き換えてください。

python3 {SKILLS_DIR}/ga4/scripts/ga_journey.py

コマンドは必ずプロジェクトのルートから実行してください。スクリプトのパスとデフォルトの.ga4の場所はどちらもこの場所を前提としているため、サブディレクトリから実行すると、気付かないまま診断結果がすべて false になり、すでに接続済みのユーザーをオンボーディングに戻してしまいます。 システムのpython3（標準ライブラリのみ。仮想環境がなくても動作する必要があります）で実行します。JSON を出力します：

フィールド	意味
ga4_dir / ga4_dir_present	実際に検索されたフォルダーと、そのフォルダーが存在するかどうかです。まずこれを確認してください。 .ga4 は現在の作業ディレクトリを基準に解決されるため、間違ったフォルダーから実行すると、以下のすべてのフィールドが一度に false になります。これは「何も設定されていない」と解釈され、すでに接続済みのユーザーがオンボーディングに戻される原因になります。false の場合、出力には hint が含まれます。ユーザーをどこかに誘導する前に、作業ディレクトリ（または GA4_DIR）を確認して再実行してください
oauth_client_present	.ga4/oauth_client.json が存在するかどうかです（管理者が作成した OAuth クライアント）
token_present	ログインが完了しているかどうかです（token.json + refresh_token）
property_configured / property_id	GA4 プロパティの選択が完了しているかどうかです
taxonomy_present	.ga4/taxonomy.md が存在するかどうかです。ファイルが存在するかだけを示し、中身があるかどうかは示しません
taxonomy_event_count	そのタクソノミーに実際に含まれるイベント数です。0 はファイルは存在するものの、空であることを意味します。未入力のテンプレートを解析した場合に発生します。これは「タクソノミーがまだない」として扱い、分析ではなく ga-taxonomy に誘導してください。null は件数を読み取れなかった（taxonomy.json がない、または読み取れない）ことを意味するため、この値から何も判断しないでください
platforms / platforms_checked_at / platforms_age_days	このプロパティがデータを収集するプラットフォーム（web／iOS／Android／unknown）、最後に確認した日時、確認からの経過日数です。以下のプラットフォームのコンテキストを参照してください。null は「プラットフォームがない」ではなく、「まだ調べていない」という意味です
venv_present	.ga4/venv の準備ができているかどうかです（API 呼び出しに必要です）
deps_ready	3 つのスキルで使用するすべてのライブラリがインストールされているかどうかです。false はインストールされていないことを意味します（venv 自体が存在しない場合も含みます）。null は確認に失敗したことを意味します（インストール状況は不明です。不足していると決めつけないでください）
missing_packages	（存在する場合のみ）{"skill-name": ["module-name", ...]} — 不足しているもののみ
deps_fix	（存在する場合のみ）そのまま実行できるコマンドです（改行区切り）。venv がない場合、1 行目で venv を作成します

依存関係が不足している場合は、委任する前に自分で解決してください：deps_ready が false の場合、deps_fix コマンドを自分で実行し（1 行で「分析に必要なライブラリをインストールします」）、確認に通ることを再チェックしてから委任してください。マーケターに pip コマンドの実行を依頼しないでください。venv_present が false の場合、最初の deps_fix 行で venv が作成されるため、それも実行してください。この手順を省略して委任すると、委任先のスキルが .ga4/venv/bin/python を実行しようとしてシェルエラー（no such file or directory）が発生し、マーケターには JSON ではなく生のエラーが表示されます。再チェック後も false の場合は、同じコマンドを繰り返さず、何が失敗したかをユーザーに直接伝えてください。deps_ready が null の場合、インストール状況を確認できなかったため、そのまま進め、実際にエラーが発生した場合にのみセットアップを行ってください。

出力が "ok": false の場合は、付随する hint に従い、ユーザーの次の操作を案内できるよう、ユーザーの言語で説明してください。

接続の確認：「接続済み」とみなすには、token_present と property_configured の両方が true である必要があります。接続されていない場合、どのようなリクエストにも 1 行で応答してください — 「まず GA4 を接続する必要があります（1 分で確認 → ログイン → プロパティを選択）」— その後、ga-auth に委任してください。ただし、まだログインしていない場合（token_present=false — Step 5 の条件）は、委任する前にStep 5 の進行概要を表示してください。

プラットフォームのコンテキスト

ステータスチェックではplatformsが報告されます。これは、このプロパティがデータを収集しているプラットフォームを、GA4独自の表記（web、iOS、Android、unknown）で示します。どのイベントやディメンションが存在し得るかに影響するため、何かが欠けていると判断する前に確認してください。

• nullは、まだ一度も調べられていないことを意味します。プラットフォームを推測しないでください。 推測による判断を防ぐために、このフィールドがあります。.ga4/venv/bin/python {SKILLS_DIR}/ga-auth/scripts/ga4_admin.py get-property <PROPERTY_ID>を再実行し、ga-authスキルのステップ4の項目4と5を通じて保存してください。保存時にconfig.jsonが一から再構築されるため、通貨、タイムゾーン、保持期間も同じコマンドで再度渡さないとnullになります。その場合、ga-useはレポートする収益の通貨（リアルタイムのレスポンスにはメタデータがまったく含まれません）と、空のファネルチェックで使う保持期間の値を利用できなくなります。
• []は、プロパティにデータストリームがないことを意味します。何も収集していません。
• unknownの項目は、ストリームを分類できなかったことを意味します。そのため、リストだけでは完全な回答になりません。unknownが含まれている場合、webがないからといって「アプリ専用」と判断しないでください。ウェブ専用またはアプリ専用という判断を適用せず、プロパティを分類できなかったと伝えてください。
• platforms_age_daysが180を超えている場合、リストの取得後にチームがプラットフォームを追加している可能性があります。これを根拠に判断する前に再確認してください。
• platformsはストリームが設定されていることを示し、platformディメンションは実際に到着したトラフィックを示します。設定済みのストリームでもデータがゼロの場合があるため、一方を他方であるかのように説明しないでください。

ステップ2：意図の分類

以下の表を使ってリクエストを分類し、適切なスキルに委任してください。目的が明確で単一のリクエストは、最初からそのスキルに該当します。このスキルで受け取った場合でも、余計な説明を加えずに、すぐそのスキルへ引き継いでください。

意図	表現の例	委任先
接続、ログイン、権限の問題	"connect GA", "login isn't working", "permission error", "GA 연결", "로그인이 안 돼", "권한 오류"	ga-auth
分類体系の解析・調整・草案作成	"register our taxonomy", "are we collecting what we designed?", "we don't have a taxonomy, make one", "정의서 등록", "설계대로 수집되고 있어?", "정의서가 없는데 만들어줘"	ga-taxonomy
データの検索・分析	"last week's page views", "top 10 events", "conversion funnel", "지난주 페이지뷰", "이벤트 상위 10개", "전환 퍼널"	ga-use
機能についての質問	"what can GA do?", "how do I use this?", "GA로 뭘 할 수 있어?", "이거 어떻게 써?"	ステップ3へ進みます（ただし、回答の冒頭で3ステップの手順を説明してください）
曖昧なリクエスト	"take a look at our GA", "how's our data?", "GA 좀 봐줘", "우리 데이터 어때?"	ステップ3へ進みます
複合（2つ以上のスキルにまたがる）	"parse our taxonomy sheet and analyze last month", "정의서 올리고 지난달 분석해줘"	ステップ4へ進みます

委任方法：利用可能なスキルの一覧から該当する名前（ga-auth／ga-taxonomy／ga-use。プラグイン配布版では<plugin>:ga-authのように表示される場合があります）を探し、Skillツールで呼び出してください。

ga-taxonomyまたはga-useに引き継ぐ際は、そのプロパティのプラットフォームを伝えてください。両スキルは、ウェブ専用、アプリ専用、混在のプロパティで異なる方法で判断します。診断ですでに答えが分かっています。

ステップ3：曖昧なリクエスト → 状態に応じた提案

診断結果に基づいて次の選択肢を2～3個提案し、ユーザーが選んだら該当するスキルに委任してください。

• 未接続 → 「① まずGA4を接続する（5～10分）」のみを提案し、ga-authに委任します。
• 接続済み＋分類体系なし → 「① 先週のデータをざっと確認する ② イベント分類体系を登録する（ある場合） ③ 実データから分類体系の草案を作成する（ない場合）」
• 接続済み＋分類体系あり → 「① 気になる指標を分析する ② 分類体系と実際の収集状況を照合する」

ステップ 4：複合リクエスト → 分解してから順番に委任

1. まず、リクエストをスキルごとのステップに分解したリストを提示します：「次の順序で進めます：① 分類体系を解析（ga-taxonomy）→ ② 先月を分析（ga-use）」。
2. 前提条件が不足している場合は、先頭に追加します（未接続の場合は⓪ ga-auth）。
3. ユーザーの同意を得たら、Skill ツールを一度に 1 ステップずつ呼び出し、各ステップの完了を確認してから次に進みます。途中のステップが失敗した場合は、そこで停止し、失敗した内容を報告します。失敗した結果の上に次のステップを積み重ねると原因が埋もれ、どのステップに問題があったのかマーケターが判断できなくなるためです。

ステップ 5：オンボーディング（初回利用時）

ユーザーがまだログインしていない場合（token_present=false）、初回利用者です。oauth_client.json がすでに存在する場合も同様です。管理者が事前にファイルを渡すのは標準的な利用開始方法であり、このケースを除外すると、明らかな初回利用者に利用の全体像を案内できなくなります。3 ステップの利用手順を簡潔に一度だけ示し、ga-auth から始めます。

Claude で GA4 を使うには、3 つのステップがあります： ① 接続（ga-auth：ログインしてプロパティを選択、5〜10 分）→ ② 分類体系（ga-taxonomy：イベント分類体系を登録・照合、任意）→ ③ 分析（ga-use：自然言語で質問し、表で結果を取得） では、まず①から始めましょう。

ステップ②は任意です。分類体系がなくても分析できるため、ユーザーが希望する場合は①から③へ進んでください。