mcpField
H
hubspot-audit

hubspot-audit

github.com/tomgranot营销与增长7838 次安装2 周前更新
代码仓库

关于 hubspot-audit

HubSpot Portal Audit 是只读诊断技能，供负责 HubSpot 门户的团队检查 CRM 数据、营销和销售健康状况。它按范围生成评分报告，并附带按优先级排列的后续技能建议。

主要功能

  1. 01全门户、营销或销售范围审计
  2. 02检查数据完整性与重复项
  3. 03评估邮件投递与互动情况
  4. 04检查销售管道和交易质量
  5. 05生成 Markdown 与 JSON 报告
  6. 06按优先级生成技能处方

适用场景

  1. 01审查 HubSpot 门户整体状况
  2. 02定位营销联系人数据问题
  3. 03发现停滞交易与跟进任务
  4. 04为门户清理安排后续步骤

MCP 相关

若已连接 HubSpot 的 MCP 服务，可用于抽查审计中异常计数对应的记录；计数查询仍由脚本执行。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tomgranot/hubspot-admin-skills --skill hubspot-audit

安装后在 Claude Code 中输入/hubspot-audit确认已加载。

附带文件scripts/audit_portal.py

详细介绍

HubSpot 门户审计

对 HubSpot 门户运行完整诊断审计。一个只读脚本会收集指标、评估各个维度，并生成一份报告，报告开篇列出优先运行的技能。

一个引擎，三个视角

审计使用单一引擎（scripts/audit_portal.py），并通过 --scope 标志指定范围。每个维度都标记为 shared、marketing 或 sales：

范围运行内容报告入口
full（默认）shared + marketing + salesreports/hubspot-audit-{date}.md此技能
marketingshared + marketingreports/hubspot-marketing-audit-{date}.md/hubspot-marketing-audit
salesshared + salesreports/hubspot-sales-audit-{date}.md/hubspot-sales-audit

每种范围都会运行 shared 维度，因此，对同一门户执行营销审计和销售审计时，两者共有的指标会保持一致。如果你负责整个门户，请使用此技能；如果团队只负责其中一部分，则将对应范围的审计交给该团队。

设置

  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 处理（精确扫描需要完整分页）不评分
营销
维度衡量内容评分依据
邮件送达能力营销联系人、硬退信、全局退订、退信次数不少于 3 次的联系人、从未发送过邮件的联系人硬退信 + 退订
联系人数据完整性缺少电子邮件、生命周期阶段、公司、行业、国家/地区或职位的联系人缺少生命周期阶段
互动状况90 天内打开过邮件、从未打开过邮件、上次打开邮件已超过一年、生命周期阶段错误的现有客户从未打开过邮件
列表、工作流与表单状况列表总数、工作流数量（活跃与非活跃）、表单数量不评分
销售
维度衡量内容评分依据
管道配置管道、每个管道中的交易数、空管道、开放阶段超过 10 个的管道空管道 + 臃肿管道
交易数据质量缺少金额、预计成交日期、负责人的开放交易，或未关联联系人的开放交易；没有失败原因的已关闭且失败的交易缺少金额 + 预计成交日期
管道规范与速度60 天或更久没有活动的开放交易、预计成交日期已过的交易、没有后续活动的交易；90 天赢单率长期停滞 + 逾期交易
销售负责人及交接由已停用负责人持有的开放交易；没有负责人的 SQL/Opportunity 联系人；没有关联交易的 Opportunity 联系人孤立交易 + 销售阶段中无负责人的联系人
活动与跟进开放和逾期任务；销售线索及无负责人的销售线索逾期任务

阈值（停滞交易时间范围、赢单率时间范围、阶段上限）位于脚本顶部的 # --- Configuration --- 区块中。

API 技术说明

  • 空值检查：使用 NOT_HAS_PROPERTY 运算符查找从未设置过属性的记录。HubSpot 会将“从未发生”存储为缺失属性，而不是 0 或空字符串。
  • 计数：脚本使用 Search API 的 total 进行计数，即使超过 10,000 条结果的分页上限，该值仍然精确。若要分页获取超过 10,000 条记录，需要对查询进行分段。
  • 搜索限制：每秒 5 个请求、每个查询 5 个筛选器组、每组 6 个筛选器。脚本会控制请求速率，使其低于速率限制。
  • n/a 不等于零：当令牌无法读取某个对象（缺少权限范围，或该 Hub 未购买相关服务）时，该行会显示 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.pyuv 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...

技能建议

脚本会自行生成建议：每个映射到修复技能且计数非零的指标都会成为一行，每项技能只出现一次，并按优先级（先 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
...

补充脚本无法给出的判断：哪些发现有共同根因，哪些是该业务的预期情况，以及怎样安排顺序才能遵循依赖关系（先补充数据再评分，先确定所有者再进行路由）。

步骤 3：处理缺失的技能

如果审计发现的问题没有任何现有技能可以处理，请执行以下操作：

  1. 向用户清楚说明：“此次审计发现了一个没有任何现有技能覆盖的问题：[description]。”

  2. 提出立即创建该技能：“我现在可以创建一个新技能。它的名称为 /[suggested-name]，可处理 [brief description]。”

  3. 询问是否要向上游贡献：“你想把这个新技能贡献回社区吗？如果想，我会：

    • 在 skills/[name]/SKILL.md 中创建该技能
    • Fork 代码库（如果尚未 Fork）
    • 将新技能推送到你的 Fork
    • 向 tomgranot/hubspot-admin-skills 提交拉取请求

    这有助于今后所有使用这些技能的人。”

  4. 如果用户同意，请按照标准的 SKILL.md 格式创建该技能，提交更改并创建 PR。

  5. 如果用户拒绝向上游贡献，仍要在本地创建该技能，供其使用。

步骤 4：建议下一步

以以下内容结尾：

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

运行后

  • 输出已保存报告的文件路径
  • 展示有序的技能处方（见上文步骤 2）
  • 突出显示最关键的 3 个发现
  • 标记没有匹配技能的发现（见上文步骤 3）
  • 建议运行 /hubspot-implementation-plan 获取完整的分阶段计划

评论

支持 Markdown