hubspot-connect

HubSpot Connect

User-facing meta-skill for HubSpot CRM integration.

Purpose

Single entry point for all HubSpot CRM operations:

• Contacts - List, create, update, search
• Companies - List, create, search
• Deals - List, create, update, search
• Associations - Get linked records
• Engagements - Emails, calls, notes, meetings

Follows the master/connect pattern - references hubspot-master for shared scripts and references.

---

Trigger Phrases

Load this skill when user says:

• "hubspot" / "hubspot crm"
• "list contacts" / "show contacts"
• "create contact" / "add contact"
• "search contacts" / "find contact"
• "list companies" / "show companies"
• "create company" / "add company"
• "list deals" / "show deals" / "show pipeline"
• "create deal" / "new opportunity"
• "log email" / "log call" / "add note"
• Any CRM-related query

---

Pre-Flight Check (ALWAYS RUN FIRST)

Before ANY HubSpot operation, validate configuration:

uv run python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json

Handle Config Status

ai_action	What to Do
proceed_with_operation	Config OK → Continue
prompt_for_access_token	Ask user for access token, save to .env
create_env_file	Create .env with token
add_missing_scopes	Guide user to add scopes in HubSpot
verify_token	Token exists but invalid

If Setup Needed

Display this complete setup guide to user:

I need to set up HubSpot integration first.

---------------------------------------------------
HUBSPOT PRIVATE APP SETUP
---------------------------------------------------

STEP 1: Create Private App
─────────────────────────
1. Log into HubSpot
2. Click gear icon (Settings) → Integrations → Private Apps
3. Click "Create a private app"
4. Name: "Nexus Integration"

STEP 2: Select Required Scopes
──────────────────────────────
In the "Scopes" tab, enable these permissions:

CRM (Required):
  ☑️ crm.objects.contacts.read
  ☑️ crm.objects.contacts.write
  ☑️ crm.objects.companies.read
  ☑️ crm.objects.companies.write
  ☑️ crm.objects.deals.read
  ☑️ crm.objects.deals.write

Engagements (Optional - for emails/calls/notes/meetings):
  ☑️ crm.objects.emails.read
  ☑️ crm.objects.emails.write
  ☑️ crm.objects.calls.read
  ☑️ crm.objects.calls.write
  ☑️ crm.objects.notes.read
  ☑️ crm.objects.notes.write
  ☑️ crm.objects.meetings.read
  ☑️ crm.objects.meetings.write

STEP 3: Get Your Token
──────────────────────
1. Click "Create app"
2. Copy the access token shown
3. Token starts with: pat-na1-... or pat-eu1-...

[!]  IMPORTANT: Save this token securely - you won't see it again!

---------------------------------------------------

Please paste your HubSpot access token: