HubSpot Admin Skills for Claude Code

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.

What's New in 1.2

• Self-testing, BYO sandbox. New /sandbox-self-test verifies 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.

What's New in 1.1

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-mcp wires 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.

Connecting to HubSpot

The skills use two complementary connection paths:

1. Private app token + scripts (the default). Every scripted skill runs plain-Python requests against HubSpot's REST APIs using a private app token (HUBSPOT_ACCESS_TOKEN in .env). This is the path for bulk operations — it gives you pagination, rate-limit handling, abort thresholds, and CSV audit trails.
2. HubSpot's official MCP server (optional, interactive). Connect Claude Code to mcp.hubspot.com via OAuth for conversational reads and spot-checks — "show me 5 contacts this cleanup touched" — without writing a script. Run /connect-hubspot-mcp to 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.

Self-Testing (Bring Your Own Sandbox)

Before trusting any of this with production, make the toolkit prove itself on a disposable portal:

1. Create a free developer test account (HubSpot Settings > Testing > Developer test accounts — every account gets up to 10, no plan required).
2. Create a private app inside it and put its token in .env as HUBSPOT_SANDBOX_ACCESS_TOKEN.
3. 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.

Quick Start

1. Install

# Add the marketplace
/plugin marketplace add tomgranot/hubspot-admin-skills

# Install the plugin
/plugin install hubspot-admin@hubspot-admin-skills

Or clone directly: git clone https://github.com/TomGranot/hubspot-admin-skills.git

2. Audit your portal

/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.

3. Get your cleanup plan

/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.

4. Execute skill by skill

The plan tells you exactly which slash command to run next. Each skill follows a 4-stage pattern:

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.

5. Maintain

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.

Skills Reference

Audit & Planning (5)

Database Hygiene (6)

Data Enrichment (6)

Segmentation & Scoring (3)

Automation Workflows (5)

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.

Ongoing Maintenance (12)

Prerequisites

• Claude Code installed and configured
• HubSpot account with a private app token in .env as HUBSPOT_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_TOKEN for /sandbox-self-test

API versioning

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.

Directory Structure

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

Community-Driven: Help Build the Skill Set

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.

Manual Contributing

See CONTRIBUTING.md for the full skill template, frontmatter spec, Python house style, safety-mechanism requirements, and category list. The short version:

1. Fork: gh repo fork TomGranot/hubspot-admin-skills --clone
2. Branch: git checkout -b skill/your-skill-name
3. Create: Add skills/<your-skill>/SKILL.md following the 4-stage pattern (Plan → Before → Execute → After, plus Rollback)
4. Test: Run the skill against a HubSpot sandbox portal
5. PR: gh pr create --repo TomGranot/hubspot-admin-skills

Please keep skills generic and company-agnostic. No customer data, API keys, or proprietary information.

Author

Created by Tom Granot. Built from extensive experience administering HubSpot CRM at scale.

License

MIT -- see LICENSE for details.