hubspot-revops-skill

HubSpot API と SQL データウェアハウス上に収益分析基盤を構築します。ICP 検証、ML リードスコアリング、競合インテリジェンス、アクティビティ分析、パイプライン予測をカバーし、CRM データを実行可能なインテリジェンス製品へと橋渡しします。

<quick_start> Epiphan ネイティブの経路（デフォルト — Private App は不要）:

1. crm://schema.md（Epiphan AI リソース）を読み、続いてすべての集計に対して HubSpot テーブル（hubspot_contacts、hubspot_companies、hubspot_deals、…）へ execute_sql / query_dataset を実行します。
2. 人物または企業のリストを生成するあらゆるユースケース（UC1 セグメント、UC2 スコア済みリード）では、SQL で候補を抽出し、続いて各行に対して qualify_lead（Epiphan AI）を実行します — Gate Q — これはエンリッチメント、スコアリング、リストへの追加の前に行います。
3. ゲート通過後の行をエンリッチします: enrich_contact（Epiphan AI）→ Apollo apollo_people_match → Clay ウォーターフォール。
4. ユースケースごとに配信します（下の表）: XLSX/HTML、export_query_csv、または hubspot_update_contact による HubSpot プロパティ書き込み（confirm-first）。 生の SDK / Private App のセットアップは、MCP が何かに到達できない場合のみ — 付録は reference/api-guide.md にあります。 </quick_start>

<house_rules> 顧客向けスキルです。出力前に、ゲートを順番に実行します（詳細: /.claude/skills/epiphan-house-rules-skill/reference/gates.md）: S: 製品に関する主張の前に search_product_catalog（Epiphan AI）または Epiphan Knowledge 検索。 B: すべての顧客向け文字列に対して check_my_copy。 Q: 候補抽出の直後、ティアリング/エンリッチメント/ドラフトの前に qualify_lead。 D: アウトバウンドのテキストは Gmail ドラフトになり、送信されることはありません。 識別子（オーナー ID、ポータル、メール、シート数）はそのスキル内の reference/identifiers.md から取得します — ここで再記載しないでください。 いずれかのゲートが失敗した場合は reference/self-healing.md に従い（リトライ、フラグ付きでのデグレード、Tim へのアラート、停止）、/.claude/skill-runs/.jsonl に 1 行追記します。 </house_rules>

<success_criteria>

• ウェアハウスが Epiphan AI execute_sql 経由で到達可能（最初にスキーマを読む）であり、データの鮮度が検証されている（同期遅延 < 24h）
• 少なくとも 1 つのユースケース（ICP、スコアリング、競合、アクティビティ、予測）が、名前付きの配信成果物を伴う結果を生成している
• リストを生成するすべての出力（UC1、UC2）が qualify_lead を 1 行ずつ通過している。インラインでの Golden Rules / ATL-BTL / AE-owner の再実装がない
• リードスコアリングモデルが 200 件以上の過去の成約案件で学習され、測定可能な AUC を持つ
• スコアの HubSpot への書き戻しが confirm-first かつ重複排除されている
• アウトカムのサイドカー + 実行ログの行が書き込まれている </success_criteria>

HubSpot RevOps 分析

HubSpot API と SQL データウェアハウス上に構築する収益分析基盤。 CRM データ → 分析 → インテリジェンス製品 → 収益インパクトを橋渡しします。

スコープ: HubSpot 固有の分析スタック。基本的な CRM CRUD には crm-integration-skill を使用してください。汎用的なダッシュボードには data-analysis-skill を使用してください。

---

セットアップチェックリスト

1. Epiphan AI ウェアハウス（デフォルト）

Tim の HubSpot データは Epiphan AI PostgreSQL ウェアハウスに複製されています。アクセス経路:

1. crm://schema.md（または get_schema）を読みます — カラム名の推測はクエリ失敗の最大の原因です。
2. 行を取得するには execute_sql（JSON、高速）· 答えがファイルになる場合は export_query_csv · 保存済みデータセットには query_dataset · SQL で表現できない質問にのみ ask_agent（低速、従量制）。
3. 鮮度を検証します: SELECT max(hs_lastmodifieddate) FROM hubspot_contacts — 遅延が 24h を超える場合は、すべての結果に stale のフラグを立てます。

2. Private App / 生の SDK（付録 — MCP が到達できない場合のみ）

HubSpot Private App（contacts/companies/deals/owners/timeline スコープ）と Python SDK パターンは reference/api-guide.md に記載されています。以下のどのユースケースにも不要です。そこから始めないでください。

---

主なユースケース

#	ユースケース	入力	出力	ツール	成果物
1	ICP 検証	連絡先 + 企業データ	セグメント別コンバージョン率 + ゲート済みターゲットリスト	SQL → qualify_lead → Clay/Apollo	export_query_csv/openpyxl による XLSX（セグメントシート + ゲート済み連絡先シート）
2	リードスコアリング	過去の商談	リードごとの受注確率（ゲート済み）	SQL + ML → qualify_lead	HubSpot カスタムプロパティへの書き込み（hubspot_update_contact、確認優先）+ XLSX 監査
3	競合インテリジェンス	商談のクローズ理由	競合別の勝敗	SQL	${CLAUDE_OUTPUTS_DIR:-./outputs/} 内の HTML マトリクス + Tim への Slack DM サマリー
4	アクティビティ分析	エンゲージメントデータ	アクティビティ→成果の相関	SQL	HTML レポート
5	パイプライン予測	進行中の商談 + ステージ履歴	加重収益予測	SQL	XLSX 予測（ステージ別、担当者別）+ 1 段落のサマリー

ユースケースの詳細

UC1 — ICP 検証: SQL で連絡先 + 企業 + 商談を結合し、業界/規模/地域でセグメント化し、セグメントごとのコンバージョン率を計算します（集計は SQL 内に留めます）。セグメントがターゲットリストになったら、まずすべての候補行に対して qualify_lead を実行します（Gate Q — 顧客、チャネル、製品のみのエンゲージ、アクティブな AE 所有、抑制対象は除外されます。古い AE リードは STALE AE LEAD として表面化します。ティアは判定結果から取得します）。その後、残った行をエンリッチメントウォーターフォールに流します：

1. find-and-enrich-company または find-and-enrich-contacts-at-company でターゲット連絡先を特定
2. add-contact-data-points / add-company-data-points でエンリッチメントジョブをキューに投入
3. get-task で結果をポーリングし、state: completed を確認
4. エンリッチされたデータを API または Epiphan CRM 連携経由で HubSpot に書き戻す

代替案: ウォーターフォールの待機なしで直接エンリッチするには Apollo MCP（apollo_people_match）を使用します。

UC2 — リードスコアリング: 過去の受注/失注商談で GradientBoostingClassifier をトレーニングします。特徴量: 企業規模、業界、エンゲージメントスコア、パイプライン滞在日数、qualify_lead ティア。Gate Q を通過した行のみをスコアリングし、スコアを hubspot_update_contact 経由でカスタムプロパティとして HubSpot にデプロイします（確認優先、hs_object_id で重複排除）。

UC3 — 競合インテリジェンス: 商談の closed_lost_reason から競合の言及を抽出します。競合別の勝敗マトリクスを構築します。競合による置き換えパターンで Webhook アラートをトリガーします。

UC4 — アクティビティ分析: メール開封、予約されたミーティング、記録された通話を商談成果と相関付けます。どのアクティビティが実際に商談を前進させるかを特定します。

UC5 — パイプライン予測: 過去データからのステージ別受注率を用いて加重予測を計算します。商談の経過期間、ベロシティ、担当者のパフォーマンスを考慮します。

参照: ユースケースごとの完全な SQL テンプレートについては reference/sql-analytics.md を参照してください。

---

見込み客の品質: Gate Q がゴールデンルールを担う

qualify_lead は、このスキルが生成するすべてのリスト（UC1 のターゲットリスト、UC2 の スコア済みリード）の信頼できる情報源です。顧客、チャネルパートナー、製品のみのエンゲージ、 AE 所有のアクティブ、抑制対象、重複はこの判定結果であり、ATL/BTL ティアも同じ呼び出しから 取得します。ルールの全文とオーナー ID は CLAUDE.md の「Golden Rules」と house-rules スキルの reference/identifiers.md にあり、ここでは再実装されていません。

SQL は、Gate Q より緩いままである限り（決して厳しくならず）、AE 条件がハード除外ではなく 90 日間の古いリードの例外に一致する限り、Gate Q の前に候補量を削減するために事前フィルタ を行ってもかまいません：

-- candidate pre-filter only; qualify_lead still runs on every surviving row
WHERE lifecyclestage <> 'customer'
  AND COALESCE(device_count, 0) < 1
  AND COALESCE(is_channel, false) = false
  AND country IN ('United States', 'Canada')
  -- AE-owned: keep if last activity > 90 days (surfaces as STALE AE LEAD); drop if worked recently
  -- mirror of identifiers.md (Lex 82625923 NA-only, Ron 423155215 all, Phil 190030668 NA-only)
  AND NOT (hubspot_owner_id IN (82625923, 423155215, 190030668)
           AND notes_last_updated >= NOW() - INTERVAL '90 days')

前バージョンの hubspot_owner_id IN (…) は、AE 所有の連絡先のみをターゲットとして読み取り、 古いものをハード除外していました。どちらも 2026-03-21 の古い AE の例外に矛盾しており、削除 されています。 リストを生成する実行で qualify_lead が利用できない場合 → リストを停止し（集計は引き続き 提供可能）、Tim に警告します。

---

クイックリファレンス: HubSpot API エンドポイント

オブジェクト	エンドポイント	主な操作
コンタクト	/crm/v3/objects/contacts	検索、作成、更新、一括処理
企業	/crm/v3/objects/companies	検索、コンタクトへの関連付け
取引	/crm/v3/objects/deals	パイプライン、ステージ履歴
エンゲージメント	/crm/v3/objects/engagements	メール、通話、会議
プロパティ	/crm/v3/properties/{object}	カスタムプロパティの CRUD
関連付け	/crm/v4/associations/{from}/{to}	オブジェクトのリンク
検索	/crm/v3/objects/{object}/search	フィルタ + ソート (最大 10k)

リファレンス: 認証、SDK パターン、一括操作については reference/api-guide.md を参照してください。

---

クイックリファレンス: SQL オブジェクトモデル

HubSpot オブジェクト	SQL テーブル (一般的な例)	主要カラム	結合キー
コンタクト	hubspot.contacts	email, lifecycle_stage, lead_score	contact_id
企業	hubspot.companies	domain, industry, employee_count	company_id
取引	hubspot.deals	amount, stage, close_date, pipeline	deal_id
取引ステージ	hubspot.deal_stage_history	stage, timestamp, duration	deal_id
エンゲージメント	hubspot.engagements	type, created_at, contact_id	engagement_id
オーナー	hubspot.owners	email, first_name, team	owner_id

結合パターン: コンタクト → 関連付け → 企業/取引 (関連付けテーブル経由)

---

統合ポイント

スキル	関係
crm-integration-skill	基本的な CRUD パターン、認証設定
data-analysis-skill	可視化、Streamlit ダッシュボード
sales-revenue-skill	パイプライン指標、MEDDIC コンテキスト、予測
research-skill	市場/競合調査の方法論
cost-metering-skill	API 呼び出し + Clay エンリッチメントの支出を追跡
prospect-research-to-cadence-skill	自動化された取引フロー、Golden Rules フィルタ
deal-momentum-analyzer-skill	パイプライン健全性スコアリング

MCP 統合ポイント

MCP コネクター	利用可能なツール
Epiphan AI (mcp__claude_ai_Epiphan_Ai__)	execute_sql, query_dataset, export_query_csv, get_schema, qualify_lead, enrich_contact, hubspot_search_companies, hubspot_search_contacts, hubspot_search_deals, hubspot_get_company, hubspot_get_contact, hubspot_get_deal, hubspot_update_contact, hubspot_create_list, crm_search_customers, crm_get_customer, crm_get_order, crm_get_customer_orders, analytics_get_device, analytics_search_by_email, ask_agent (AI クエリ、読み取り専用)
Clay MCP	find-and-enrich-company, find-and-enrich-contacts-at-company, find-and-enrich-list-of-contacts, add-contact-data-points, add-company-data-points, get-task
Apollo	apollo_people_match, apollo_contacts_create, apollo_contacts_search, apollo_organizations_enrich, apollo_mixed_companies_search, apollo_emailer_campaigns_*

---

よくある間違い

間違い	修正
100 リクエスト/10 秒のレート制限を超えている	バッチエンドポイントを使用し、指数バックオフを追加する
10k 件を超える結果に Search API を使用している	一括分析には SQL ウェアハウスに切り替える
プロパティの内部名をハードコードしている	まずプロパティ定義を取得する: GET /crm/v3/properties/{object}
オブジェクトリンク用のアソシエーション API が欠落している	v4 アソシエーションを使用する: POST /crm/v4/associations/{from}/{to}/batch/read
Postgres での SQL DATEDIFF	AGE() または EXTRACT(EPOCH FROM ...) を使用する — 方言に関する注記を参照
HubSpot の hs_object_id を処理していない	プロパティリクエストには常に hs_object_id を含める
エンリッチメント後に電話番号が欠落している	Apollo の後に Clay waterfall を使用する: まず Apollo（高速・無料）、次に電話番号検証のために Clay MCP（find-and-enrich-contacts-at-company → add-contact-data-points → get-task）。Clay はマッチ率を高めるために 50 以上のデータプロバイダーを集約します。
小規模なデータセットでスコアリングモデルを学習している	信頼性の高い ML スコアには最低 200 件以上の成約案件が必要
Apollo のみのエンリッチメントでデータが欠落している	Clay MCP をフォールバックとして使用: find-and-enrich-company で taskId を作成し、Email/電話番号/職歴のために add-contact-data-points を実行し、get-task で結果をポーリングする

---

ワークフローフェーズ

フェーズ 1: 基盤

1. crm://schema.md を読み、list_tables で HubSpot テーブルを確認する
2. データの鮮度（同期ラグ）を検証する
3. MCP がデータセットに到達できない場合のみ: reference/api-guide.md に従って Private App を使用する

フェーズ 2: 分析

5. ICP 検証クエリを構築する（UC1）
6. パイプライン速度ダッシュボードを作成する（UC2、UC5）
7. 競合インテリジェンスのトラッキングを設定する（UC3）

フェーズ 3: インテリジェンス

8. 過去の案件でリードスコアリングモデルを学習させる
9. API 経由でスコアを HubSpot にデプロイする
10. エンリッチメントパイプラインを構築する（Clay → HubSpot）
11. 自動アラートと webhook を設定する

参考: ML スコアリングと Clay 連携については reference/enrichment-pipelines.md を参照してください。 参考: デプロイパターンとコスト見積もりについては reference/architecture.md を参照してください。

<self_healing> success = クエリが実行され、成果物が納品され、リストがゲートされた。 partial = 成果物は納品されたが ある段階が劣化した（ウェアハウスのラグが 24 時間超でフラグが立った、エンリッチメント層が失敗した、HubSpot への書き込みが確認されなかった、サンプルが モデルに対して小さすぎた）— その段階を明示すること。 error = 成果物がない（リトライ後もウェアハウスに到達できない、 スキーマの不一致が未解決）またはリストを生成する実行で qualify_lead が利用できない → リストを 停止する。 ~/.claude/skills/epiphan-house-rules-skill/reference/self-healing.md に従ったラダー: バックオフ付きで一度リトライする（レート制限 / タイムアウト） → 劣化させる（SQL のみ、エンリッチメントをスキップ） → Tim にアラートする → 停止する。 実行ごとに 1 行を ~/.claude/skill-runs/hubspot-revops-skill.jsonl に追記する。 </self_healing>

結果サイドカーを出力する

最後のステップとして、~/.claude/skill-analytics/last-outcome-hubspot-revops-skill.json に書き込みます:

{"ts":"[UTC ISO8601]","skill":"hubspot-revops-skill","version":"<frontmatter version>","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"queries_executed":[n],"reports_generated":[n],"insights_found":[n],"rows_gated":[n],"excluded_by_qualify":[n],"stale_ae_surfaced":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

一部の段階が失敗しても結果が生成された場合は、ステータス「partial」を使用してください。error の場合はその段階を明示する必要があります。出力がまったく生成されなかった場合にのみ「error」を使用してください。