hubspot-audit

HubSpot ポータル監査

HubSpot ポータルの総合診断監査を実行します。1 つの読み取り専用スクリプトで指標を収集し、各項目を評価して、実行すべきスキルを優先順位順に並べたリストから始まるレポートを作成します。

1 つのエンジン、3 つの視点

この監査は、--scope フラグを使う単一のエンジン（scripts/audit_portal.py）です。各項目には shared、marketing、sales のいずれかが付与されています。

スコープ	実行内容	レポート	エントリーポイント
full（デフォルト）	shared + marketing + sales	reports/hubspot-audit-{date}.md	このスキル
marketing	shared + marketing	reports/hubspot-marketing-audit-{date}.md	/hubspot-marketing-audit
sales	shared + sales	reports/hubspot-sales-audit-{date}.md	/hubspot-sales-audit

shared の項目はすべてのスコープで実行されるため、同じポータルに対する marketing 監査と sales 監査では、共通する数値が一致します。ポータル全体を担当している場合はこのスキルを使用し、一方のみを担当するチームにはスコープを絞った監査を渡してください。

セットアップ

1. API トークンを取得します。 .env の HUBSPOT_ACCESS_TOKEN を確認してください。設定されていない場合は、読み取りスコープの HubSpot アクセストークンをユーザーに依頼し、.env に保存します。

   HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxx
   

2. 監査を実行します。 このスクリプトには PEP 723 のインラインメタデータが含まれており、依存関係を自動的に解決する uv で実行します。

   uv run scripts/audit_portal.py              # full
   uv run scripts/audit_portal.py --scope marketing
   uv run scripts/audit_portal.py --scope sales
   

スクリプトは必要に応じて reports/ を作成し、Markdown レポートと、他のスキルが読み込める同名の JSON ファイル（拡張子は .json）を書き出します。

監査項目

Shared（すべてのスコープ）

項目	測定内容	評価対象
データベースサイズ	コンタクト、会社、取引の合計数	評価なし
所有者の健全性	所有者のいないコンタクトと会社、無効化された所有者が引き続き所有しているレコード	所有者のいないコンタクト + 孤立したコンタクト
会社データの完全性	ドメイン、業種、国が未入力の会社	ドメインの未入力
重複	/merge-duplicate-companies の対象としてフラグ付け（正確なスキャンには全ページの取得が必要です）	評価なし

Marketing

項目	測定内容	評価対象
メール配信到達性	マーケティングコンタクト、ハードバウンス、全体配信停止、3 回以上のバウンス、メール未送信	ハードバウンス + 配信停止
コンタクトデータの完全性	メールアドレス、ライフサイクルステージ、会社、業種、国、役職が未入力のコンタクト	ライフサイクルステージの未入力
エンゲージメントの健全性	過去 90 日間に開封、未開封、最終開封から 1 年超、ライフサイクルステージが誤っている既存顧客	未開封
リスト、ワークフロー、フォームの健全性	リスト数、ワークフロー数（アクティブと非アクティブ）、フォーム数	評価なし

Sales

項目	測定内容	評価対象
パイプライン構成	パイプライン数、パイプラインごとの取引数、空のパイプライン、オープンステージが 10 を超えるパイプライン	空 + 過剰なパイプライン
取引データの品質	金額、クローズ日、所有者、関連付けられたコンタクトが未設定のオープン取引、失注理由がない失注取引	金額 + クローズ日の未入力
パイプラインの整備と速度	60 日以上アクティビティのないオープン取引、過去の日付が設定されたクローズ日、次のアクティビティがない取引、過去 90 日間の受注率	停滞中 + 期限超過の取引
営業の所有権と引き継ぎ	無効化された所有者が所有するオープン取引、所有者のいない SQL／Opportunity コンタクト、取引のない Opportunity コンタクト	孤立した取引 + 営業ステージで所有者のいないコンタクト
アクティビティとフォローアップ	オープンおよび期限超過のタスク、リードと所有者のいないリード	期限超過のタスク

しきい値（停滞中の取引と見なす期間、受注率の対象期間、ステージ数の上限）は、スクリプト先頭の # --- Configuration --- ブロックにあります。

API 技術メモ

• Null チェック：プロパティが一度も設定されていないレコードを見つけるには、NOT_HAS_PROPERTY 演算子を使用します。HubSpot は「一度も発生していない」状態を、0 や空文字列ではなく、プロパティが存在しない状態として保存します。
• カウント：このスクリプトは Search API の total を使ってカウントします。この値は、ページング上限の 10,000 件を超えても正確です。10,000 件を超えるレコードをページングするには、クエリを分割する必要があります。
• 検索制限：1 秒あたり 5 リクエスト、1 クエリあたり 5 フィルターグループ、1 グループあたり 6 フィルターです。スクリプトはレート制限を下回るようにリクエスト間隔を調整します。
• n/a はゼロではありません：トークンでオブジェクトを読み取れない場合（スコープ不足、またはハブで未購入の場合）、行には n/a、ディメンションの評価には ? が表示されます。問題なしと解釈するのではなく、スコープを修正して再実行してください。
• 無効化されたオーナー：Owners API で取得するには、archived=true を指定する必要があります。
• オープンな取引：hs_is_closed = false で絞り込みます。ステージ名に関係なく、すべてのパイプラインで機能します。
• マーケティングコンタクトのステータス：hs_marketable_status は読み取りおよびフィルタリングが可能ですが、API 経由では読み取り専用です。
• API では取得できない情報：メールごとの開封率／クリック率は、マーケティングメール統計 API または UI から取得します。予測精度とステージ滞在時間は、UI の予測レポートとパイプラインレポートから取得します。

スクリプト

スクリプトのパスは、このスキルのディレクトリからの相対パスです。.env、data/、reports/ がプロジェクトディレクトリで解決されるよう、プロジェクトディレクトリから実行してください。各パスの前に、このスキルのインストール先を付けます（リポジトリをクローンした場合は skills/hubspot-audit/）。

ステージ	スクリプト	実行方法
監査（読み取り専用）	scripts/audit_portal.py	uv run scripts/audit_portal.py [--scope full|marketing|sales]

スクリプトで対応していない確認が必要な場合は、個別のスクリプトを別途作成するのではなく、適切なタグを付けたディメンション関数を追加してください。tests/test_audit_portal.py のオフラインテストは、偽の API に対して実行されるため、ポータルは不要です。

MCP に関する注意：HubSpot の MCP サーバーが接続されている場合（/connect-hubspot-mcp を参照）、監査中のスポットチェックに使用してください。疑わしいカウントの根拠となるサンプルレコードを開くほうが、個別のクエリを書くよりも迅速です。カウント用のクエリ自体は再現性を保つため、スクリプトに残します。

評価基準

評価	意味	基準
A	健全	影響を受けるレコードが 5% 未満
B	軽微な問題	影響を受けるレコードが 5～15%
C	要対応	影響を受けるレコードが 15～30%
D	重大な問題	影響を受けるレコードが 30～50%
F	致命的	影響を受けるレコードが 50% 超
?	不明	指標を読み取れませんでした

スクリプトは、上記の表で指定された指標に基づいて各ディメンションを評価します。評価はあくまで出発点として扱ってください。オープンな取引が 40 件あり、そのうち 3 件が古いポータルと、4,000 件あり、そのうち 300 件が古いポータルでは、どちらも評価は B でも状況は異なります。

レポートの構成

# HubSpot CRM Audit Report

**Date:** YYYY-MM-DD
**Scope:** full

## Executive Summary

| Dimension | Lens | Grade |
|---|---|---|
| Owner Health | shared | C |
| Email Deliverability | marketing | D |
| Deal Data Quality | sales | B |

## Prescription

| # | Skill | Why | Records | Priority |
|---|---|---|---|---|
| 1 | `/delete-no-email-contacts` | Contacts missing email | X,XXX | P0 |
| 2 | `/suppress-hard-bounced` | Hard bounced | X,XXX | P0 |

## 1. Database Size
...one section per dimension, each a Metric | Count | % table...

スキルの処方

スクリプトが処方を生成します。修正スキルに対応する、カウントがゼロではない指標はすべて行になり、各スキルは 1 回だけ表示されます。行は優先度（P0 が先）、次にレコード数の順に並びます。

スクリプトの実行後：

ステップ 1：レポートを読む

生成された Markdown レポートを読みます。カウントを手作業で再計算しないでください。レポートとその JSON 版が正確な情報源です。

ステップ 2：優先順位付きの処方を提示する

実際のカウントを含め、緊急度ごとにグループ化した番号付きのアクションリストとして処方を提示します。

## Your Cleanup Prescription

### Immediate (P0)
1. `/delete-no-email-contacts`: X,XXX contacts with no email are inflating your bill
2. `/reassign-deactivated-owners`: XX open deals belong to people who have left

### Next (P1)
3. `/cleanup-deals`: XXX open deals have no amount or close date
...

スクリプトでは判断できない点を補足してください。たとえば、どの指摘が共通の根本原因に由来するか、このビジネスではどれが想定内か、また、依存関係を踏まえた適切な順序（スコアリングの前にエンリッチメント、ルーティングの前にオーナー設定）などです。

Step 3: 不足しているスキルへの対応

監査の結果、既存のどのスキルでも対応できない問題が見つかった場合は、次の手順を実行します。

1. ユーザーに明確に伝えます：「この監査で、既存のどのスキルでも対応できない問題が見つかりました：[description]。」

2. その場で作成することを提案します：「この問題に対応する新しいスキルを今すぐ作成できます。名前は /[suggested-name] で、[brief description] に対応します。」

3. コミュニティへのコントリビューションを尋ねます：「この新しいスキルをコミュニティに還元しますか？同意いただける場合は、次の手順を実行します。

   • skills/[name]/SKILL.md にスキルを作成します
   • リポジトリをフォークします（まだフォークされていない場合）
   • 新しいスキルをフォークしたリポジトリにプッシュします
   • tomgranot/hubspot-admin-skills にプルリクエストを作成します

   これにより、今後これらのスキルを使うすべての人に役立ちます。」

4. ユーザーが同意した場合は、標準の SKILL.md 形式に従ってスキルを作成し、コミットして、プルリクエストを作成します。

5. ユーザーが上流へのコントリビューションを断った場合でも、ユーザーが利用できるようにローカルでスキルを作成します。

Step 4: 次のステップを提案する

最後に、次の内容を出力します。

Ready to start? Run `/hubspot-implementation-plan` to generate a full phased plan,
or jump straight to the first skill in your prescription.

実行後

• 保存したレポートのファイルパスを出力します
• スキルの推奨順序を提示します（Step 2 を参照）
• 最も重要度の高い指摘事項を3つ強調します
• 対応するスキルがない指摘事項があれば明示します（Step 3 を参照）
• 完全なフェーズ別計画を作成するため、/hubspot-implementation-plan の実行を提案します