HubSpot CRM Database Audit

Run a full diagnostic audit of a HubSpot CRM portal. This skill collects metrics across eight dimensions, grades each one, and produces a prioritized report with actionable recommendations.

Setup

1. 1. Get the API token. Check .env for HUBSPOT_API_TOKEN. If it is not set, ask the user to provide their HubSpot private app API token and store it in .env:

CODEBLOCK0

1. 2. Install dependencies. Use uv (not pip):

CODEBLOCK1

1. 3. Create the output directory if it does not exist:

CODEBLOCK2

Audit Dimensions

Run queries for each of the following eight dimensions. Collect exact counts for every metric listed.

1. Database Size

• - Total contacts
• Total companies
• Total deals
• Marketing contacts vs non-marketing contacts (if Marketing Hub is active)

2. Email Deliverability

• - Hard bounced contacts (hs_email_hard_bounce_reason_enum is not empty)
• Soft bounced contacts (hs_email_bounce > 0 AND no hard bounce)
• Global unsubscribes (hs_is_unworked or hs_email_optout = true)
• Never-emailed contacts (no hs_email_last_send_date)
• Invalid email format (regex check on email property)
• Contacts with 3+ bounces

3. Data Completeness

• - Missing INLINECODE10
• Missing company (contact-level)
• Missing industry (contact-level)
• Missing country and/or INLINECODE14
• Missing INLINECODE15
• Missing INLINECODE16
• Missing INLINECODE17
• Companies missing INLINECODE18
• Companies missing INLINECODE19
• Companies missing city / state / INLINECODE22

4. Engagement Health

• - Last activity distribution: active in last 30 days, 31-90 days, 91-180 days, 181-365 days, 365+ days, never engaged
• Email open rate (last 90 days)
• Email click rate (last 90 days)
• Contacts with zero page views
• Contacts with zero form submissions

5. Duplicate Analysis

• - Duplicate email addresses (exact match)
• Companies sharing the same INLINECODE23
• Companies with very similar names (fuzzy — note: API cannot do fuzzy matching natively; count exact duplicates on name and flag for manual review)

6. Owner Health

• - Deactivated owners who still have assigned contacts
• Deactivated owners who still have assigned companies
• Deactivated owners who still have assigned deals
• Contacts with no owner
• Companies with no owner

7. List & Workflow Health

• - Total active lists vs static lists
• Lists with zero members
• Workflows currently active
• Workflows that have not enrolled anyone in 90+ days
• Forms with zero submissions
• Forms with submissions in last 30 days

8. Deal Pipeline Health

• - Deals without INLINECODE25
• Deals without INLINECODE26
• Deals in each pipeline stage
• Stale deals (no activity in 60+ days, still open)
• Average deal age by stage

API Technical Notes

These details are critical for getting accurate results:

• - Null checks: Use the NOT_HAS_PROPERTY filter operator to find contacts where a property has never been set. HubSpot stores "never happened" as null (property absent), not as 0 or empty string.

CODEBLOCK3

• - Search API pagination limit: The Search API returns a maximum of 10,000 results per query. If you expect more than 10K, segment queries by another property (e.g., createdate ranges, lifecycle stage, or first letter of email) and sum the results.

• - Deactivated owners: The Owners API does not return deactivated owners by default. Pass archived=True:

CODEBLOCK4

• - Rate limiting: Private apps are limited to 100 requests per 10 seconds. Add a small delay between batch calls or use exponential backoff on 429 responses.

• - Engagement timestamps: Use hs_last_sales_activity_timestamp and notes_last_contacted for activity dating. hs_email_last_open_date and hs_email_last_click_date are useful for email engagement specifically.

• - Marketing contact status: The property hs_marketable_status indicates whether a contact is set as a marketing contact. This property is read-only via API.

Script Structure

Write a single Python script (scripts/audit_portal.py) that:

1. 1. Loads the API token from INLINECODE36
2. Initializes the HubSpot client:

   from hubspot import HubSpot
   api_client = HubSpot(access_token=os.getenv("HUBSPOT_API_TOKEN"))
   

1. 3. Runs each dimension's queries sequentially (respect rate limits)
2. Collects all results into a structured dict
3. Computes letter grades per dimension (see grading rubric below)
4. Renders the markdown report
5. Saves to INLINECODE37

Grading Rubric

Assign a letter grade to each dimension based on severity:

Grade	Meaning	Criteria
A	Healthy	< 5% of records affected
B

Minor issues | 5-15% of records affected |
| C | Needs attention | 15-30% of records affected |
| D | Significant problems | 30-50% of records affected |
| F | Critical | > 50% of records affected |

For dimensions without a simple percentage (e.g., Owner Health), use judgment based on the number of affected records and business impact.

Output Format

Save the report to reports/hubspot-audit-{YYYY-MM-DD}.md with this structure:

CODEBLOCK6

Skill Prescription

After generating the audit report, prescribe a specific ordered list of skills the user should run. Do not just present findings — tell the user exactly what to do next.

Step 1: Map Findings to Skills

For each audit finding that scored C or worse, map it to the appropriate skill. Use this category-ordered lookup:

Database Hygiene (run first — billing and deliverability impact):

Finding	Skill	Priority
Contacts missing email	INLINECODE39	P0
Hard bounced contacts

/suppress-hard-bounced | P0 |
| Global unsubscribes | /suppress-global-unsubscribes | P0 |
| Ghost/never-engaged contacts | /suppress-ghost-contacts | P1 |
| Duplicate companies | /merge-duplicate-companies | P1 |
| Deactivated owners with contacts | /reassign-deactivated-owners | P1 |

Data Enrichment (run second — data quality):

Finding	Skill	Priority
Missing company name	INLINECODE45	P1
Missing industry

/enrich-industry | P1 |
| Inconsistent geo data | /standardize-geo-values | P2 |
| Missing geo data | /backfill-geo-data | P2 |
| Missing/wrong lifecycle stage | /fix-lifecycle-stages | P1 |
| Unowned marketing contacts | /assign-unowned-contacts | P1 |

Segmentation & Scoring (run third — targeting):

Finding	Skill	Priority
No ICP classification	INLINECODE51	P2
No lead scoring

/build-lead-scoring | P2 |
| No segment lists | /build-smart-lists | P2 |

Automation Workflows (run fourth — prevention):

Finding	Skill	Priority
No new-contact hygiene	INLINECODE54	P2
High disengagement rate

/engagement-suppression-workflow | P2 |
| No lifecycle automation | /lifecycle-progression-workflow | P3 |
| No bounce monitoring | /bounce-monitoring-workflow | P2 |

Ongoing Maintenance (run last — sustainability):

Finding	Skill	Priority
Unused lists	INLINECODE58	P3
Unused forms

/cleanup-forms | P3 |
| Stale workflows | /cleanup-workflows | P3 |
| Dashboard clutter | /cleanup-dashboards | P3 |
| Deal pipeline issues | /cleanup-deals | P3 |
| Unused properties | /cleanup-properties | P3 |

Step 2: Present the Ordered Prescription

After the audit report, present a numbered action list — not just findings. Format like this:

CODEBLOCK7

Step 3: Handle Missing Skills

If the audit reveals a problem that no existing skill covers, do the following:

1. 1. Tell the user clearly: "This audit found an issue that isn't covered by any existing skill: [description]."
2. Offer to create it on the spot: "I can create a new skill for this right now. It would be called /[suggested-name] and would handle [brief description]."
3. Ask about contributing upstream: "Would you like to contribute this new skill back to the community? If yes, I'll:

- Create the skill in skills/[name]/SKILL.md - Fork the repo (if not already forked) - Push the new skill to your fork - Open a pull request to INLINECODE66

This helps everyone who uses these skills in the future."

1. 4. If the user agrees, create the skill following the standard SKILL.md format, commit it, and open the PR.
2. If the user declines the upstream contribution, still create the skill locally so they can use it.

Step 4: Suggest Next Step

End with:
CODEBLOCK8

After Running

• - Print the file path of the saved report
• Present the ordered skill prescription (Step 2 above)
• Highlight the top 3 most critical findings
• Flag any findings that have no matching skill (Step 3 above)
• Suggest running /hubspot-implementation-plan for the full phased plan