hubspot-connect

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: hubspot-connect
description: "Connect to HubSpot CRM for contact, company, deal, and engagement management. Load when user mentions 'hubspot', 'crm', 'contacts', 'companies', 'deals', 'list contacts', 'create contact', 'search deals', or any HubSpot CRM operations. Meta-skill that validates config, discovers CRM objects, and routes to appropriate operations."
---

# 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:

```bash
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:
```

After user provides token:
```bash
# Write to .env
HUBSPOT_ACCESS_TOKEN=pat-na1-xxx

# Re-run config check to verify
python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json
```

### Handling 403 Forbidden (Missing Scopes)

If user gets 403 errors after setup, they're missing scopes:

```
⚠️  Missing HubSpot permissions!

The operation failed because your Private App is missing required scopes.

To fix:
1. Go to HubSpot Settings → Integrations → Private Apps
2. Click on "Nexus Integration" (or your app name)
3. Go to "Scopes" tab
4. Add the missing scope: [scope name from error]
5. Click "Commit changes"
6. IMPORTANT: Copy the NEW access token (it changes after scope updates)
7. Update your .env with the new token

Then try again!
```

---

## Workflows

### Workflow 0: Config Check