37 Claude Code skills for auditing, cleaning, enriching, and automating your HubSpot CRM
📖 Browse every skill with full docs at hubspot.granot.io — including common problems mapped to fixes and agent-readable endpoints (llms.txt, skills.json).
Built by Tom Granot — from deep experience with enterprise HubSpot CRM administration.
- Self-testing, BYO sandbox. New
/sandbox-self-testverifies the whole toolkit against a free, disposable HubSpot developer test account you bring: seeded fixtures, read-path smokes for every scripted skill, end-to-end destructive and enrichment cases (mock provider — zero credits), list + v4 workflow round-trips, a graded report, and marker-scoped teardown. Production is locked out in code (account-type gate, fails closed, no override). Optional manual-dispatch CI workflow included.
HubSpot's platform moved fast in 2026, and this release moves with it:
- Workflows are now API-first. HubSpot's v4 Automation API is stable (v3 is legacy), so the four workflow-builder skills now create their workflows via scripts — always disabled, for review in the UI before enabling — instead of walking you through 40 clicks. Nested branch designs are decomposed into small linear flows the API expresses cleanly.
- New
/workflows-as-code— export every workflow to versioned JSON, diff exports, restore from backup. HubSpot has no workflow recycle bin; now you have one. - Official MCP support. HubSpot's remote MCP server went GA in April 2026;
/connect-hubspot-mcpwires it into Claude Code for conversational spot-checks alongside the bulk scripts. - New
/waterfall-enrich-contacts— external enrichment with pluggable provider adapters (FullEnrich waterfall by default; Apollo, Hunter, Dropcontact included; bring your own), cost caps, and a no-overwrite safety model. - New
/audit-api-usage— HubSpot switched to date-based API versioning (2026-03) and legacy v1–v4 endpoints lose support on March 30, 2027. This skill finds everything in your stack that needs migrating. - Lead scoring refreshed for the post-2025 scoring tool (Fit + Engagement scores, decay, API-readable score properties), plus repo-wide consistency fixes — one env var, one Python house style, scripts linked from every skill. See CHANGELOG.md.
The skills use two complementary connection paths:
- Private app token + scripts (the default). Every scripted skill runs plain-Python
requestsagainst HubSpot's REST APIs using a private app token (HUBSPOT_ACCESS_TOKENin.env). This is the path for bulk operations — it gives you pagination, rate-limit handling, abort thresholds, and CSV audit trails. - HubSpot's official MCP server (optional, interactive). Connect Claude Code to
mcp.hubspot.comvia OAuth for conversational reads and spot-checks — "show me 5 contacts this cleanup touched" — without writing a script. Run/connect-hubspot-mcpto set it up and to see the full division of labor.
Audits, hygiene, enrichment, and segmentation run on scripts; use MCP alongside them for verification and triage.
Before trusting any of this with production, make the toolkit prove itself on a disposable portal:
- Create a free developer test account (HubSpot Settings > Testing > Developer test accounts — every account gets up to 10, no plan required).
- Create a private app inside it and put its token in
.envasHUBSPOT_SANDBOX_ACCESS_TOKEN. - Run
/sandbox-self-test.
The suite seeds synthetic fixtures (one defect per testable skill), smoke-tests every scripted skill's read path, runs destructive and enrichment cases end-to-end (enrichment uses a mock provider — no credits), round-trips a list and a v4 workflow, writes a PASS/FAIL/SKIP report to reports/, and tears everything down. It hard-refuses to run against anything that isn't a DEVELOPER_TEST or SANDBOX portal — the account-type check is enforced in every script, fails closed, and has no override. An opt-in GitHub Actions workflow (manual dispatch only) ships at skills/sandbox-self-test/ci/ — copy it into .github/workflows/ to run the suite in CI.
# Add the marketplace
/plugin marketplace add tomgranot/hubspot-admin-skills
# Install the plugin
/plugin install hubspot-admin@hubspot-admin-skillsOr clone directly: git clone https://github.com/TomGranot/hubspot-admin-skills.git
/hubspot-audit
This scans your entire HubSpot portal — contacts, companies, deals, engagement, deliverability, data quality, duplicates, owners, lists, workflows — and produces a graded report. Each finding gets a severity rating (A-F) and is mapped to the specific skill that fixes it.
/hubspot-implementation-plan
Reads your audit report and generates a phased roadmap: what to fix, in what order, which skill to run, how long it takes, and what can be automated vs. what needs manual UI work. The plan sequences tasks by dependency — you can't score leads before enriching company data, and you can't build ICP tiers before standardizing industries.
The plan tells you exactly which slash command to run next. Each skill follows a 4-stage pattern:
| Stage | What happens |
|---|---|
| Plan | Explains the approach, asks you for any configuration needed |
| Before | Audits current state, exports CSV baseline, shows you what will change |
| Execute | Makes the changes (API scripts or step-by-step UI instructions) |
| After | Verifies the fix, compares before/after, confirms success |
Skills that can be scripted include ready-to-run Python scripts (plain requests, run with uv run — no project setup needed). Skills that require HubSpot UI work (lead scoring, some workflow options) provide precise build instructions.
Once clean, use /weekly-cleanup-routine (5 min/week) and /quarterly-database-cleanup to keep it that way. The audit skill detects issues that no existing skill covers and offers to create new ones on the spot.
| Skill | Description |
|---|---|
hubspot-audit |
Run a comprehensive audit of your HubSpot portal — contacts, companies, deals, properties, lists, workflows, and forms |
hubspot-implementation-plan |
Generate a phased implementation plan from audit findings with prioritized action items |
connect-hubspot-mcp |
Connect Claude Code to HubSpot's official remote MCP server for conversational CRM reads and spot-checks |
audit-api-usage |
Find every integration calling legacy v1–v4 HubSpot endpoints before the March 2027 end of support |
sandbox-self-test |
Verify the whole toolkit against a disposable developer sandbox you bring — seed, test, report, tear down; production-locked |
| Skill | Description |
|---|---|
delete-no-email-contacts |
Identify and delete contacts that have no email address — unusable records that inflate your database |
suppress-hard-bounced |
Suppress contacts with hard-bounced email addresses to protect sender reputation |
suppress-global-unsubscribes |
Suppress globally unsubscribed contacts to ensure compliance and reduce wasted marketing spend |
suppress-ghost-contacts |
Find and suppress ghost contacts — records with no activity, no engagement, and no business value |
merge-duplicate-companies |
Detect and merge duplicate company records using domain matching and fuzzy name comparison |
reassign-deactivated-owners |
Reassign contacts and deals owned by deactivated HubSpot users to active team members |
| Skill | Description |
|---|---|
enrich-company-name |
Populate missing company names on contacts by pulling from their associated company records |
enrich-industry |
Backfill contact industry values from associated company industry data |
standardize-geo-values |
Normalize country and state/region values to consistent formats across your database |
assign-unowned-contacts |
Assign marketing contacts that have no owner to the appropriate team members based on territory or segment rules |
fix-lifecycle-stages |
Detect and correct lifecycle stage violations — contacts stuck in the wrong stage or regressed backwards |
waterfall-enrich-contacts |
Enrich emails, phones, and titles via external providers — FullEnrich waterfall by default, Apollo/Hunter/Dropcontact included, or bring your own |
| Skill | Description |
|---|---|
create-icp-tiers |
Create an ICP (Ideal Customer Profile) tier property and assign tier values based on firmographic criteria |
build-lead-scoring |
Design and implement a lead scoring model in HubSpot's Lead Scoring tool — separate Fit and Engagement scores with decay |
build-smart-lists |
Build active smart lists for key segments — ICP tiers, lifecycle stages, engagement levels, and suppression groups |
All four builders create their workflows via the stable v4 Automation API (always disabled, for UI review before enabling), with a manual UI path as fallback.
| Skill | Description |
|---|---|
new-contact-hygiene-workflow |
Build a workflow that screens new contacts on creation — validates email, enriches data, and assigns owners |
engagement-suppression-workflow |
Create a two-tier sunset system that re-engages dormant contacts before suppressing them |
lifecycle-progression-workflow |
Set up automated lifecycle stage progression based on engagement thresholds and sales activity |
bounce-monitoring-workflow |
Build workflows that monitor bounce events and auto-suppress contacts exceeding bounce thresholds |
workflows-as-code |
Export all workflows to versioned JSON, diff exports over time, and restore workflows from backup |
| Skill | Description |
|---|---|
quarterly-database-cleanup |
Run a quarterly hygiene sweep — re-audit contacts, prune stale records, and refresh suppression lists |
review-bounced-contacts |
Review contacts with 3+ bounces and decide on suppression or re-verification |
cleanup-lists |
Audit and archive unused, redundant, or stale lists cluttering your portal |
cleanup-forms |
Review forms for unused, broken, or duplicate entries and recommend consolidation |
cleanup-workflows |
Identify workflows that are off, broken, or redundant and recommend which to archive or fix |
weekly-cleanup-routine |
A repeatable weekly checklist covering the highest-impact maintenance tasks |
cleanup-dashboards |
Audit dashboards for unused, duplicate, or outdated reports and recommend consolidation |
cleanup-deals |
Review deal pipeline hygiene — stale deals, missing properties, and stage violations |
cleanup-properties |
Find unused, duplicate, or poorly named contact/company/deal properties and recommend cleanup |
cleanup-lead-owners |
Audit lead owner assignments for imbalances, orphaned records, and routing issues |
backfill-geo-data |
Backfill missing country and state values using IP geolocation, form submissions, and company data |
create-segment-lists |
Create a standard set of segment lists for reporting, targeting, and suppression |
- Claude Code installed and configured
- HubSpot account with a private app token in
.envasHUBSPOT_ACCESS_TOKEN. Typical scopes across the skill set:crm.objects.contacts.read/write,crm.objects.companies.read/write,crm.objects.deals.read/write,crm.objects.owners.read,crm.schemas.*(property management),crm.lists.read/write,automation(workflow skills),forms— grant per skill as documented in each SKILL.md - Python 3.10+ with uv — scripts carry inline metadata and run with
uv run, no project setup - HubSpot Marketing Professional plan or higher (for workflow-based skills)
- Optional: HubSpot's MCP server connection for conversational spot-checks (
/connect-hubspot-mcp) - Optional: an enrichment provider API key (FullEnrich, Apollo, Hunter, Dropcontact, or your own) for
/waterfall-enrich-contacts - Optional: a free developer test account with its token in
HUBSPOT_SANDBOX_ACCESS_TOKENfor/sandbox-self-test
Scripts target HubSpot's stable REST versions: /crm/v3/, /automation/v4/, /marketing/v3/ — all supported until March 30, 2027. HubSpot's current recommended target is the date-based 2026-03 release; this repo will migrate in a future major version, and /audit-api-usage helps you migrate everything else in your stack.
hubspot-admin-skills/
├── README.md
├── CLAUDE.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── LICENSE
├── .gitignore
├── assets/
│ └── hero.png
├── .claude-plugin/
│ ├── marketplace.json
│ └── plugin.json
└── skills/
├── hubspot-audit/
│ ├── SKILL.md
│ └── scripts/
│ └── audit_portal.py
├── hubspot-implementation-plan/
│ └── SKILL.md
├── delete-no-email-contacts/
│ ├── SKILL.md
│ └── scripts/
│ ├── before.py
│ ├── execute.py
│ └── after.py
├── suppress-hard-bounced/
│ ├── SKILL.md
│ └── scripts/
│ ├── before.py
│ └── after.py
├── waterfall-enrich-contacts/
│ ├── SKILL.md
│ └── scripts/
│ ├── before.py / execute.py / after.py
│ └── providers/ (fullenrich, apollo, hunter, dropcontact, _template)
├── sandbox-self-test/
│ ├── SKILL.md
│ ├── ci/
│ │ └── sandbox-self-test.yml (opt-in workflow — copy to .github/workflows/)
│ └── scripts/
│ └── preflight.py / seed.py / run_suite.py / teardown.py
├── ... (37 skills total, 21 with scripts)
└── backfill-geo-data/
└── SKILL.md
Every HubSpot portal is different. The audit skill will automatically detect issues that aren't covered by existing skills and offer to create new ones on the spot. When it does, it will ask:
"Would you like to contribute this new skill back to the community? It will help other HubSpot admins facing the same issue."
If you say yes, Claude Code will create the skill, push it to your fork, and open a PR — all automatically. You don't need to know git or write markdown.
See CONTRIBUTING.md for the full skill template, frontmatter spec, Python house style, safety-mechanism requirements, and category list. The short version:
- Fork:
gh repo fork TomGranot/hubspot-admin-skills --clone - Branch:
git checkout -b skill/your-skill-name - Create: Add
skills/<your-skill>/SKILL.mdfollowing the 4-stage pattern (Plan → Before → Execute → After, plus Rollback) - Test: Run the skill against a HubSpot sandbox portal
- PR:
gh pr create --repo TomGranot/hubspot-admin-skills
Please keep skills generic and company-agnostic. No customer data, API keys, or proprietary information.
Created by Tom Granot. Built from extensive experience administering HubSpot CRM at scale.
MIT -- see LICENSE for details.