# HubSpot Admin Skills

> 37 open-source Claude Code skills for auditing, cleaning, enriching, segmenting, and automating HubSpot CRM. Each skill is a markdown playbook (SKILL.md) following a safe 4-stage pattern — Plan, Before (CSV baseline), Execute, After (verification) — and 21 skills include ready-to-run Python scripts (plain `requests` against HubSpot REST endpoints, PEP 723 inline metadata, run via `uv run`).

Install in Claude Code:

```
/plugin marketplace add tomgranot/hubspot-admin-skills
/plugin install hubspot-admin@hubspot-admin-skills
```

Requirements: a HubSpot private app token (HUBSPOT_ACCESS_TOKEN in .env), Python 3.10+ with uv for scripted skills.

Machine-readable catalog: https://hubspot.granot.io/api/skills.json
All skills in one fetch: https://hubspot.granot.io/llms-full.txt
Raw scripts: https://hubspot.granot.io/skills/%3Cslug%3E/scripts/%3Cfile%3E.py (before/execute/after stages plus any nested helpers; full list per skill in skills.json)
Source repository: https://github.com/TomGranot/hubspot-admin-skills

## Audit & Planning

Portal assessment, connectivity, and implementation planning.

- [audit-api-usage](https://hubspot.granot.io/skills/audit-api-usage.md): Inventory the integrations, private apps, and internal tooling that call HubSpot APIs, and flag anything on legacy v1-v4 endpoints ahead of HubSpot's March 30, 2027 end of support. Produces a migration checklist to date-based API versions.
- [connect-hubspot-mcp](https://hubspot.granot.io/skills/connect-hubspot-mcp.md): Connect Claude Code to HubSpot's official remote MCP server for natural-language CRM reads and writes. Covers OAuth setup, scope selection, verification, and when to use MCP versus this repo's API scripts.
- [hubspot-audit](https://hubspot.granot.io/skills/hubspot-audit.md): Run a comprehensive HubSpot CRM database audit. Analyzes contacts, companies, deals, engagement, data quality, and deliverability. Use when starting a CRM cleanup, onboarding a new client, or performing quarterly health checks.
- [hubspot-implementation-plan](https://hubspot.granot.io/skills/hubspot-implementation-plan.md): Generate a phased implementation plan from a HubSpot audit report. Creates prioritized, sequenced cleanup processes with effort estimates, dependencies, and automation feasibility. Use after running /hubspot-audit.
- [sandbox-self-test](https://hubspot.granot.io/skills/sandbox-self-test.md): Verify the entire toolkit against a disposable HubSpot developer test account or sandbox that you bring: seed synthetic fixtures, run every scripted skill's read path, exercise end-to-end and API round-trip cases, produce a graded report, and tear everything down. Hard-refuses to run against production.

## Database Hygiene

Removing bad data, suppressing contacts, deduplication.

- [delete-no-email-contacts](https://hubspot.granot.io/skills/delete-no-email-contacts.md): Delete contacts with no email address from a HubSpot CRM instance. These contacts cannot receive any communication and inflate billing. Fully automated via the HubSpot CRM Search and Batch Archive APIs.
- [merge-duplicate-companies](https://hubspot.granot.io/skills/merge-duplicate-companies.md): Identify duplicate company records by domain and name, export audit CSVs for review, and guide merging. API for discovery, third-party tools or manual UI for merging (HubSpot has no bulk merge API).
- [reassign-deactivated-owners](https://hubspot.granot.io/skills/reassign-deactivated-owners.md): Reassign contacts and companies from deactivated team members to active owners. Fully automated via the HubSpot Owners API and Batch Update API. Includes territory analysis for informed reassignment decisions.
- [suppress-ghost-contacts](https://hubspot.granot.io/skills/suppress-ghost-contacts.md): Identify and suppress ghost contacts who received marketing emails but never opened any. These contacts destroy sender reputation and deliverability. Hybrid approach: API for discovery, manual UI for suppression.
- [suppress-global-unsubscribes](https://hubspot.granot.io/skills/suppress-global-unsubscribes.md): Identify and suppress globally unsubscribed contacts to ensure legal compliance and reduce billing. Hybrid approach: API for discovery and audit, manual UI for suppression (hs_marketable_status is read-only).
- [suppress-hard-bounced](https://hubspot.granot.io/skills/suppress-hard-bounced.md): Identify and suppress hard-bounced contacts to protect email sender reputation. Hybrid approach: API for discovery and audit, manual UI for suppression (hs_marketable_status is read-only via API).

## Data Enrichment

Filling gaps in contact and company data.

- [assign-unowned-contacts](https://hubspot.granot.io/skills/assign-unowned-contacts.md): Assign an owner to marketing contacts that have no owner. Ensures every marketable contact has accountability for follow-up, proper lead routing, and accurate owner-based reporting.
- [enrich-company-name](https://hubspot.granot.io/skills/enrich-company-name.md): Populate missing contact company name fields from associated company records using a HubSpot workflow with optional API backfill. Ensures contacts inherit their company name for segmentation, personalization, and ICP classification.
- [enrich-industry](https://hubspot.granot.io/skills/enrich-industry.md): Backfill contact-level industry from associated company records using a HubSpot workflow. Enables industry-based segmentation for targeted campaigns aligned with ICP verticals.
- [fix-lifecycle-stages](https://hubspot.granot.io/skills/fix-lifecycle-stages.md): Ensure all contacts and companies have appropriate lifecycle stages. Backfills missing stages via API, fixes records stuck at disallowed stages, and creates prevention workflows to stop future gaps.
- [standardize-geo-values](https://hubspot.granot.io/skills/standardize-geo-values.md): Convert inconsistent country and state/region formats to standardized values across contacts and companies. Ensures geographic segmentation works reliably.
- [waterfall-enrich-contacts](https://hubspot.granot.io/skills/waterfall-enrich-contacts.md): Enrich HubSpot contacts (email, phone, job title) through an external enrichment provider and write results back safely. Pluggable provider adapters with FullEnrich waterfall enrichment as the default; Apollo, Hunter, and Dropcontact included; bring your own via a template.

## Segmentation & Scoring

ICP tiers, lead scoring, smart lists.

- [build-lead-scoring](https://hubspot.granot.io/skills/build-lead-scoring.md): Create a comprehensive lead scoring model with separate Fit and Engagement scores using HubSpot's new Lead Scoring tool. Replaces the deprecated HubSpot Score property.
- [build-smart-lists](https://hubspot.granot.io/skills/build-smart-lists.md): Create foundational segmented lists for marketing and sales operations via the Lists API, plus advanced UI-built segments: a master sendable list, ICP-based lists, persona lists, and engagement lists. All active (dynamic) lists.
- [create-icp-tiers](https://hubspot.granot.io/skills/create-icp-tiers.md): Classify companies into Ideal Customer Profile (ICP) tiers based on firmographic data (industry + employee count). Creates a custom property via API and 4 classification workflows in HubSpot UI.

## Automation Workflows

HubSpot workflows for ongoing hygiene.

- [bounce-monitoring-workflow](https://hubspot.granot.io/skills/bounce-monitoring-workflow.md): Build a workflow to protect sender reputation through automated bounce monitoring. Auto-suppresses contacts above a configurable bounce threshold, alerts on hard bounces, and flags high-bounce contacts for weekly manual review.
- [engagement-suppression-workflow](https://hubspot.granot.io/skills/engagement-suppression-workflow.md): Build a two-tier sunset workflow that re-engages dormant contacts before suppressing them. Tier 1 triggers a re-engagement campaign after a configurable inactivity window. Tier 2 suppresses contacts that fail to re-engage within a configurable re-engagement window.
- [lifecycle-progression-workflow](https://hubspot.granot.io/skills/lifecycle-progression-workflow.md): Build workflows to automate contact progression through the sales funnel: Lead to MQL to SQL to Opportunity to Customer. Each transition is triggered by a specific event (score threshold, meeting booked, deal created, deal won).
- [new-contact-hygiene-workflow](https://hubspot.granot.io/skills/new-contact-hygiene-workflow.md): Build a HubSpot workflow that auto-enriches and stages new contacts upon creation. Sets lifecycle stage via the v4 Automation API, copies company name and industry from the associated company (UI step), and branches on completeness.
- [workflows-as-code](https://hubspot.granot.io/skills/workflows-as-code.md): Export all HubSpot workflows to versioned JSON files via the v4 Automation API, diff exports over time, and restore or recreate workflows from JSON. Treats workflow definitions like code: backed up, reviewable, and recoverable.

## Ongoing Maintenance

Recurring cleanup and health checks.

- [backfill-geo-data](https://hubspot.granot.io/skills/backfill-geo-data.md): Enrich missing geographic data (country, state, city) on contacts and companies using HubSpot workflows, external data providers, or IP-based geolocation.
- [cleanup-dashboards](https://hubspot.granot.io/skills/cleanup-dashboards.md): Audit and consolidate HubSpot reporting dashboards. Identifies unused, duplicate, or outdated dashboards. Must be performed manually — no dashboard API is available.
- [cleanup-deals](https://hubspot.granot.io/skills/cleanup-deals.md): Standardize deal pipelines, remove test deals, and address deals with missing amounts or close dates. Coordinates with Salesforce sync if applicable.
- [cleanup-forms](https://hubspot.granot.io/skills/cleanup-forms.md): Audit and remove unused, test, or deprecated forms from HubSpot. Identifies forms with zero submissions, forms not embedded on any page, and test forms left over from development.
- [cleanup-lead-owners](https://hubspot.granot.io/skills/cleanup-lead-owners.md): Remove non-employee users from HubSpot and reassign their orphaned contacts, companies, and deals. Pairs with the assign-unowned-contacts skill for comprehensive ownership cleanup.
- [cleanup-lists](https://hubspot.granot.io/skills/cleanup-lists.md): Audit and remove unused, empty, or duplicate list definitions from HubSpot. Identifies lists with zero members, lists not used by any workflow or email, and overlapping list criteria.
- [cleanup-properties](https://hubspot.granot.io/skills/cleanup-properties.md): Archive or delete unused custom properties across all HubSpot object types (contacts, companies, deals). Identifies Salesforce sync properties, test/temp properties, and obsolete form fields.
- [cleanup-workflows](https://hubspot.granot.io/skills/cleanup-workflows.md): Audit and remove inactive, test, or deprecated workflows from HubSpot. Identifies workflows that have never enrolled contacts, workflows turned off for 90+ days, and test workflows.
- [create-segment-lists](https://hubspot.granot.io/skills/create-segment-lists.md): Create business segment lists in HubSpot for customers, partners, competitors, employees, ICP tiers, and industries. Enables segment-based targeting, suppression, and analytics.
- [quarterly-database-cleanup](https://hubspot.granot.io/skills/quarterly-database-cleanup.md): Run a comprehensive quarterly CRM audit covering list health, bounce monitoring, data quality, scoring calibration, engagement metrics, and property cleanup. Produces a health report with quarter-over-quarter trend comparison.
- [review-bounced-contacts](https://hubspot.granot.io/skills/review-bounced-contacts.md): Weekly manual review of contacts with 3+ bounce events. Decide whether to delete or attempt recovery for each flagged contact. Prevents over-suppression while removing truly bad data.
- [weekly-cleanup-routine](https://hubspot.granot.io/skills/weekly-cleanup-routine.md): A lightweight 5-minute weekly health check covering bounce monitoring, new contact quality, workflow health, list growth trends, and data quality sampling. Quick early warning system, not a comprehensive audit.

## Common problems mapped to skills

- [HubSpot is full of contacts with no email address](https://hubspot.granot.io/problems/hubspot-contacts-without-email): solved by the delete-no-email-contacts skill
- [Hard-bounced contacts are wrecking our email deliverability](https://hubspot.granot.io/problems/hubspot-hard-bounces-hurting-deliverability): solved by the suppress-hard-bounced skill
- [Globally unsubscribed contacts still count as marketing contacts](https://hubspot.granot.io/problems/hubspot-still-emailing-unsubscribed-contacts): solved by the suppress-global-unsubscribes skill
- [Thousands of contacts have never opened, clicked, or visited](https://hubspot.granot.io/problems/hubspot-ghost-contacts-never-engaged): solved by the suppress-ghost-contacts skill
- [Duplicate company records are splitting our account data](https://hubspot.granot.io/problems/hubspot-duplicate-companies): solved by the merge-duplicate-companies skill
- [Contacts and deals are owned by people who left the company](https://hubspot.granot.io/problems/hubspot-contacts-owned-by-deactivated-users): solved by the reassign-deactivated-owners skill
- [Lifecycle stages are missing, stuck, or plain wrong](https://hubspot.granot.io/problems/hubspot-lifecycle-stages-wrong-or-missing): solved by the fix-lifecycle-stages skill
- [Contacts are missing company names their company records already have](https://hubspot.granot.io/problems/hubspot-contacts-missing-company-name): solved by the enrich-company-name skill
- [“USA”, “U.S.” and “united states” are three different countries in our reports](https://hubspot.granot.io/problems/hubspot-country-state-values-inconsistent): solved by the standardize-geo-values skill
- [We need phones, emails, and titles our CRM just does not have](https://hubspot.granot.io/problems/hubspot-contact-data-incomplete-enrichment): solved by the waterfall-enrich-contacts skill
- [We cannot report on our best-fit accounts because ICP is not in the CRM](https://hubspot.granot.io/problems/hubspot-no-icp-tiers): solved by the create-icp-tiers skill
- [Our lead scoring broke when HubSpot retired the old score properties](https://hubspot.granot.io/problems/hubspot-lead-scoring-after-2025-changes): solved by the build-lead-scoring skill
- [Every campaign starts with rebuilding the same lists from scratch](https://hubspot.granot.io/problems/hubspot-segments-lists-missing): solved by the build-smart-lists skill
- [New contacts arrive with missing owners, stages, and bad data](https://hubspot.granot.io/problems/hubspot-new-contacts-arrive-dirty): solved by the new-contact-hygiene-workflow skill
- [Someone edited a workflow and nobody knows what changed](https://hubspot.granot.io/problems/hubspot-workflows-no-version-control): solved by the workflows-as-code skill
- [We keep emailing people who stopped engaging a year ago](https://hubspot.granot.io/problems/hubspot-contacts-disengaged-sunset-policy): solved by the engagement-suppression-workflow skill
- [Our HubSpot portal is a mess and we do not know where to start](https://hubspot.granot.io/problems/hubspot-audit-where-to-start): solved by the hubspot-audit skill
- [HubSpot is retiring v1–v4 APIs — is our stack ready for March 2027?](https://hubspot.granot.io/problems/hubspot-api-versions-2027-deadline): solved by the audit-api-usage skill
- [How do we test CRM automation without risking production data?](https://hubspot.granot.io/problems/hubspot-test-changes-without-production-risk): solved by the sandbox-self-test skill
- [The portal gets messy again a month after every cleanup](https://hubspot.granot.io/problems/hubspot-weekly-maintenance-routine): solved by the weekly-cleanup-routine skill

## Optional

- [Install guide](https://hubspot.granot.io/install): human and agent installation instructions
- [Contributing](https://hubspot.granot.io/contributing): how new skills are contributed, including automatically via the audit skill