Skip to main content
skill CX Codex

hubspot-sales-audit — Claude Code skill: what it does, how to install

hubspot-sales-audit is a Claude Code skill for auditing HubSpot sales pipelines, deal data quality, stale deals and overdue deals. It makes no CRM changes.

MIT ★ 81 updated 2026-10-13

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add TomGranot/hubspot-admin-skills --skill hubspot-sales-audit -a claude-code
Open on GitHub

What hubspot-sales-audit does

The skill counts open deals missing an amount, close date or owner, flags deals past their close date, and tracks deals with no activity logged in 60 days. It also checks deals left behind by deactivated users, SQL and Opportunity contacts with no owner, and overdue open tasks. Results land in reports/hubspot-sales-audit-{YYYY-MM-DD}.md plus a matching .json file.

The scoring engine lives in a separate skill, hubspot-audit, which has to be installed alongside this one for the audit to run at all. You need a HUBSPOT_ACCESS_TOKEN in .env with read access to deals, contacts, companies and owners, plus tasks and leads if you want the follow-up section filled in. It runs through uv on Python 3.10+.

Thresholds such as the 60-day stale window and the 90-day win-rate window are constants in the script, so they can be tuned to match a sales cycle. The leads object only works on Sales Hub; without it those rows come back empty.

What it helps with

  • catch open deals with no amount or close date
  • flag deals past their close date
  • spot deals orphaned by deactivated reps
  • check which SQL contacts have no owner
  • count overdue tasks and unworked leads

Example prompts for the agent

  • Run the sales audit on this HubSpot portal with scope sales
  • Check how many open deals are missing a close date or owner
  • Find deals assigned to deactivated HubSpot users

How to install hubspot-sales-audit

1Skills CLI (Vercel)

npx skills add TomGranot/hubspot-admin-skills --skill hubspot-sales-audit -a claude-code

2Manually: put the files in place

~/.claude/skills/hubspot-sales-audit/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/hubspot-sales-audit/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about hubspot-sales-audit

How do I install hubspot-sales-audit in Claude Code?

Run npx skills add TomGranot/hubspot-admin-skills --skill hubspot-sales-audit -a claude-code; the skill lands at ~/.claude/skills/hubspot-sales-audit/SKILL.md.

What does hubspot-sales-audit do?

It reads data from a HubSpot portal and surfaces problems in deals: missing amounts and close dates, past-due or stale deals, unowned deals, and handoff gaps between sales and marketing.

What does hubspot-sales-audit need to run?

It needs the companion hubspot-audit skill installed alongside it, since that's where the scoring engine lives, plus a HUBSPOT_ACCESS_TOKEN with the right scopes and Python 3.10+ with uv.

Source text

SKILL.md · MIT
---
name: hubspot-sales-audit
description: "Audit the sales side of a HubSpot portal: pipeline configuration, deal data quality, stale and past-due deals, ownership and handoff gaps, and overdue follow-up. Read-only. Use when the forecast is not trusted, before a pipeline redesign or a new sales leader's first review, or when reps and reports disagree about what is in the pipeline."
license: MIT
metadata:
  author: tomgranot
  version: "1.0"
  category: audit-planning
---

# HubSpot Sales Audit

A read-only audit of everything sales operations owns in a HubSpot portal. It answers one question from several angles: can anyone trust what the pipeline says?

## Why This Matters

A forecast is a sum over deal records. If a fifth of open deals have no amount, a quarter have close dates in the past, and some belong to reps who left months ago, the forecast is wrong before anyone applies judgment to it. Pipeline reviews then turn into data-entry sessions, and leaders stop using the CRM to make decisions. Most of this is measurable in a few minutes, and most of it is fixable.

## How It Relates to the Other Audits

This skill is a lens on the same engine that powers `/hubspot-audit` and `/hubspot-marketing-audit`. It runs the **shared** dimensions (database size, owner health, company data, duplicates) plus the **sales** dimensions, and skips deliverability and engagement entirely. Because the shared dimensions are computed by the same code under every scope, the numbers here match what the marketing team sees in their audit.

| If you own | Run |
|------------|-----|
| Sales only | this skill |
| Marketing only | `/hubspot-marketing-audit` |
| The whole portal | `/hubspot-audit` (both lenses in one report) |

## Prerequisites

- The `hubspot-audit` skill installed alongside this one (it ships the engine)
- `HUBSPOT_ACCESS_TOKEN` in `.env`, with read scopes for deals, contacts, companies, and owners. Add read scopes for tasks and leads to fill in the Activity & Follow-up dimension
- Python 3.10+ with [`uv`](https://github.com/astral-sh/uv)

The audit runs on any HubSpot tier with deals. The leads object needs Sales Hub; without it those rows show `n/a`.

## Run It

The engine lives in the `hubspot-audit` skill, one directory over from this one. Run it from your project directory so `.env` and `reports/` resolve there (in a clone of the repo the path is `skills/hubspot-audit/scripts/audit_portal.py`).

```bash
uv run ../hubspot-audit/scripts/audit_portal.py --scope sales
```

Output: `reports/hubspot-sales-audit-{YYYY-MM-DD}.md` and a `.json` twin.

## What It Measures

| Dimension | Metrics | Graded on |
|-----------|---------|-----------|
| Pipeline Configuration | Number of pipelines, deals (and open deals) per pipeline, pipelines with zero deals, pipelines with more than 10 open stages | empty + bloated pipelines |
| Deal Data Quality | Open deals missing amount, close date, owner, or any associated contact; closed-lost deals with no loss reason | missing amount + close date |
| Pipeline Hygiene & Velocity | Open deals with no logged activity in 60+ days, open deals whose close date has passed, open deals with no next activity; deals closed and win rate over the last 90 days | stale + past-due deals |
| Sales Ownership & Handoff | Open deals owned by deactivated users; SQL and Opportunity contacts with no owner; Opportunity-stage contacts with no deal | orphaned deals + unowned sales-stage contacts |
| Activity & Follow-up | Open tasks, overdue open tasks, leads, leads with no owner | overdue tasks |
| *Shared:* Owner Health, Company Data, Database Size, Duplicates | see `/hubspot-audit` | |

Thresholds are constants in the script's `# --- Configuration ---` block: `STALE_DEAL_DAYS` (60), `WIN_RATE_WINDOW_DAYS` (90), `MAX_STAGES_PER_PIPELINE` (10). Set them to match your sales cycle before reading the grades. A 60-day stale window is strict for enterprise deals and generous for transactional ones.

## Reading the Results

1. **Past-due close dates come first.** An open deal with a close date in the past is wrong by definition: it either closed, slipped, or died, and the record says none of those. This is the cheapest forecast fix available.
2. **Stale is a conversation, not a deletion.** No logged activity in 60 days can mean a dead deal or a rep who does not log. Check a sample (the MCP server is good for this, see `/connect-hubspot-mcp`) before deciding which problem you have. The fixes are different: one is pipeline cleanup, the other is activity capture.
3. **Missing amounts skew weighted pipeline more than missing deals.** A deal with no amount contributes zero to every weighted report. If early stages legitimately have no amount yet, make amount conditionally required from the stage where it should exist.
4. **Orphaned open deals are P0.** A deal owned by a deactivated user gets no follow-up and appears in nobody's forecast. Reassign before anything else.
5. **Handoff gaps show where marketing and sales disagree.** SQL or Opportunity contacts with no owner mean routing broke. Opportunity-stage contacts with no deal mean lifecycle stage is being set by hand or by a workflow that does not create deals. Share these two rows with marketing ops: the root cause usually sits on their side of the line.
6. **Loss reasons are the cheapest win/loss data you will ever get.** If most closed-lost deals have none, make the property required on the Closed Lost stage.
7. **Win rate is context.** It is reported so the other numbers can be read against it and does not affect any grade. A healthy win rate on a pipeline full of stale deals usually means the losses are never being closed out.

## From Findings to Fixes

| Order | Skill | Fixes |
|-------|-------|-------|
| 1 | `/reassign-deactivated-owners` | Open deals and contacts owned by people who have left |
| 2 | `/assign-unowned-contacts` | Sales-stage contacts nobody is working |
| 3 | `/cleanup-deals` | Missing amounts and close dates, stale and past-due deals, test deals, unused pipelines |
| 4 | `/cleanup-lead-owners` | Unowned companies, deals, and leads; non-employee users |
| 5 | `/fix-lifecycle-stages` | Opportunity-stage contacts with no deal; customers at the wrong stage |
| 6 | `/lifecycle-progression-workflow` | Handoff automation, so the gaps do not reopen |
| 7 | `/merge-duplicate-companies` | Duplicate accounts splitting deal history |

Run `/hubspot-implementation-plan` to turn the report into a phased plan.

Prevention matters more than cleanup here. Three portal settings stop most of what this audit finds, and all three are configured in the HubSpot UI: required properties per deal stage (Settings > Objects > Deals > Pipelines), pipeline rules that restrict skipping stages and backward movement, and a workflow that creates a task for the owner when an open deal has had no activity for your stale window.

## What This Audit Does Not Cover

- **Forecast accuracy and time in stage.** HubSpot's forecast tool and pipeline reports own these. Forecast submissions are readable by API on Sales Hub Professional and above (`crm.objects.forecasts.read`) if you want to extend the engine.
- **Sequences.** The Sequences API only works with user-level authentication, so an account-level token cannot audit enrollment.
- **Rep performance.** The audit measures data quality, not people. Per-owner breakdowns are a deliberate omission: add them only if the team has agreed how they will be used.
- **Quotes, products, and line items.** Out of scope for now.

## Rollback

Nothing to roll back: the audit only reads. To remove its output, delete the files it wrote under `reports/`.

© tomgranot · MIT · TomGranot/hubspot-admin-skills

Similar skills

All skills for Marketing and content →

From the same set39

The whole set →
quarterly-database-cleanup quarterly-database-cleanup audits HubSpot lists, contact data, engagement and scoring, then creates a report comparing quarters. Use it for recurring CRM maintenance. CX Codex +1 ★ 81repo stars new-contact-hygiene-workflow new-contact-hygiene-workflow is a Claude Code skill that builds a HubSpot workflow to enrich new contacts on creation, setting lifecycle stage via the v4 Automation API; company field copies are added in the UI. CX Codex +1 ★ 81repo stars merge-duplicate-companies merge-duplicate-companies flags duplicate HubSpot company records by domain and name, exports CSV audits, and structures the manual cleanup workflow. CX Codex +1 ★ 81repo stars lifecycle-progression-workflow lifecycle-progression-workflow — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. It builds four HubSpot workflows that move contacts from Lead to Customer when specific events fire. CX Codex +1 ★ 81repo stars hubspot-marketing-audit hubspot-marketing-audit runs a read-only audit of HubSpot marketing data to uncover dead contacts, deliverability risks, and missing properties before cleanup or migration. CX Codex +1 ★ 81repo stars hubspot-implementation-plan hubspot-implementation-plan is a Claude Code skill that turns a HubSpot audit report into a phased cleanup plan, ordering tasks by findings and accounting for dependencies and automation options. CX Codex +1 ★ 81repo stars hubspot-audit hubspot-audit scores a HubSpot portal's database, email deliverability, pipelines and deal quality without touching a single record. Runs at the start of a CRM cleanup or before a quarterly review. CX Codex +1 ★ 81repo stars fix-lifecycle-stages fix-lifecycle-stages audits contacts and companies with missing or disallowed lifecycle stages in HubSpot, backfilling them via API and setting prevention workflows. CX Codex +1 ★ 81repo stars

Project sponsors

Companies that keep this analytics open