beam-ai-team/hubspot-master

HubSpot Master

This is NOT a user-facing skill. It's a shared resource library referenced by HubSpot integration skills.

Safety Contract

This shared library may read and mutate HubSpot CRM data. Before scripts create/update/archive records, log engagements, change associations, or export data, show the portal/account, target records, payload summary, destination path when used, and expected side effects. Require explicit user approval in the current turn before mutating HubSpot or writing files. Config checks and read-only list/search operations do not require additional approval after scope is confirmed.

Purpose

Provides shared resources to eliminate duplication across:

• hubspot-connect - Meta-skill for HubSpot CRM operations
• hubspot-list-contacts - List contacts
• hubspot-create-contact - Create contact
• hubspot-update-contact - Update contact
• hubspot-search-contacts - Search contacts
• hubspot-list-companies - List companies
• hubspot-create-company - Create company
• hubspot-search-companies - Search companies
• hubspot-list-deals - List deals
• hubspot-create-deal - Create deal
• hubspot-update-deal - Update deal
• hubspot-search-deals - Search deals
• hubspot-get-associations - Get CRM associations
• hubspot-list-emails - List email engagements
• hubspot-log-email - Log email engagement
• hubspot-list-calls - List call engagements
• hubspot-log-call - Log call engagement
• hubspot-list-notes - List notes
• hubspot-create-note - Create note
• hubspot-list-meetings - List meetings
• hubspot-create-meeting - Create meeting

Instead of loading this skill, users directly invoke the specific skill they need above.

---

Architecture: DRY Principle

Problem solved: HubSpot skills would have duplicated content (setup instructions, API docs, auth flow, error handling).

Solution: Extract shared content into hubspot-master/references/ and hubspot-master/scripts/, then reference from each skill.

Result: Single source of truth, reduced context per skill.

---

Shared Resources

All HubSpot skills reference these resources (progressive disclosure).

references/

setup-guide.md - Complete setup wizard

• Creating Private App in HubSpot
• Configuring required scopes
• Getting access token
• Environment configuration

api-reference.md - HubSpot API patterns

• Base URL and authentication
• All CRM endpoints documented
• Request/response examples
• Common property names

error-handling.md - Troubleshooting

• Common errors and solutions
• HTTP error codes
• Validation error handling
• Rate limiting

authentication.md - Token management

• Private App setup
• Token format and usage
• Security best practices

scripts/

Authentication & Configuration

check_hubspot_config.py - Pre-flight validation

uv run python check_hubspot_config.py [--json]

| Argument | Required | Default | Description | |----------|----------|---------|-------------| | --json | No | False | Output structured JSON for AI consumption |

Exit codes: 0=configured, 1=partial, 2=not configured

When to Use: Run this FIRST before any HubSpot operation. Use to validate access token is configured, diagnose authentication issues, or check if setup is needed.

---

setup_hubspot.py - Interactive setup wizard

uv run python setup_hubspot.py

No arguments - runs interactively. Guides through Private App setup, tests connection, saves to .env.

When to Use: Use when HubSpot integration needs initial setup, when check_hubspot_config.py returns exit code 2, or when user needs to reconfigure credentials.

---

CRM Operations - Contacts

list_contacts.py - List contacts (GET /crm/v3/objects/contacts)

uv run python list_contacts.py [--limit N] [--properties PROPS] [--after CURSOR] [--json]

| Argument | Required | Default | Description | |----------|----------|---------|-------------| | --limit | No | 10 | Number of results (max 100) | | --properties | No | email,firstname,lastname | Comma-separated properties | | --after | No | - | Pagination cursor | | --json | No | False | Output as JSON |

When to Use: Use when user says "list contacts", "get contacts", "show contacts".

---

create_contact.py - Create contact (POST /crm/v3/objects/contacts)

uv run python create_contact.py --email EMAIL [--firstname NAME] [--lastname NAME] [--phone PHONE] [--company COMPANY] [--json]

| Argument | Required | Default | Description | |----------|----------|---------|-------------| | --email | Yes | - | Contact email address | | --firstname | No | - | First name | | --lastname | No | - | Last name | | --phone | No | - | Phone number | | --company | No | - | Company name | | --json | No | False | Output as JSON |

When to Use: Use when user says "create contact", "add contact", "new contact".

---

update_contact.py - Update contact (PATCH /crm/v3/objects/contacts/{id})

uv run python update_contact.py --id CONTACT_ID [--email EMAIL] [--firstname NAME] [--lastname NAME] [--phone PHONE] [--json]

| Argument | Required | Default | Description | |----------|----------|---------|-------------| | --id | Yes | - | Contact ID to update | | --email | No | - | New email | | --firstname | No | - | New first name | | --lastname | No | - | New last name | | --phone | No | - | New phone | | --json | No | False | Output as JSON |

When to Use: Use when user says "update contact", "edit contact", "modify contact".

---

search_contacts.py - Search contacts (POST /crm/v3/objects/contacts/search)

uv run python search_contacts.py [--email EMAIL] [--name NAME] [--company COMPANY] [--limit N] [--json]

| Argument | Required | Default | Description | |----------|----------|---------|-------------| | --email | No | - | Search by email | | --name | No | - | Search by name (first or last) | | --company | No | - | Search by company | | --limit | No | 10 | Max results | | --json | No | False | Output as JSON |

When to Use: Use when user says "search contacts", "find contact", "lookup contact".

---

CRM Operations - Companies

list_companies.py - List companies (GET /crm/v3/objects/companies)

uv run python list_companies.py [--limit N] [--properties PROPS] [--after CURSOR] [--json]

When to Use: Use when user says "list companies", "get companies", "show companies".

---

create_company.py - Create company (POST /crm/v3/objects/companies)

uv run python create_company.py --name NAME [--domain DOMAIN] [--industry INDUSTRY] [--json]

When to Use: Use when user says "create company", "add company", "new company".

---

search_companies.py - Search companies (POST /crm/v3/objects/companies/search)

uv run python search_companies.py [--name NAME] [--domain DOMAIN] [--industry INDUSTRY] [--limit N] [--json]

When to Use: Use when user says "search companies", "find company", "lookup company".

---

CRM Operations - Deals

list_deals.py - List deals (GET /crm/v3/objects/deals)

uv run python list_deals.py [--limit N] [--properties PROPS] [--after CURSOR] [--json]

When to Use: Use when user says "list deals", "get deals", "show deals", "show pipeline".

---

create_deal.py - Create deal (POST /crm/v3/objects/deals)

uv run python create_deal.py --name NAME [--amount AMOUNT] [--stage STAGE] [--pipeline PIPELINE] [--json]

When to Use: Use when user says "create deal", "add deal", "new deal", "new opportunity".

---

update_deal.py - Update deal (PATCH /crm/v3/objects/deals/{id})

uv run python update_deal.py --id DEAL_ID [--name NAME] [--amount AMOUNT] [--stage STAGE] [--json]

When to Use: Use when user says "update deal", "edit deal", "change deal stage".

---

search_deals.py - Search deals (POST /crm/v3/objects/deals/search)

uv run python search_deals.py [--name NAME] [--stage STAGE] [--min-amount N] [--max-amount N] [--limit N] [--json]

When to Use: Use when user says "search deals", "find deal", "lookup deal".

---

Associations

get_associations.py - Get associations (GET /crm/v4/objects/{type}/{id}/associations/{toType})

uv run python get_associations.py --object-type TYPE --object-id ID --to-type TO_TYPE [--json]

When to Use: Use when user says "get associations", "linked records", "related contacts".

---

Engagements

list_emails.py - List email engagements log_email.py - Log email engagement list_calls.py - List call engagements log_call.py - Log call engagement list_notes.py - List notes create_note.py - Create note list_meetings.py - List meetings create_meeting.py - Create meeting

---

Intelligent Error Detection Flow

When a HubSpot skill fails due to missing configuration, the AI should:

Step 1: Run Config Check with JSON Output

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

Step 2: Parse the ai_action Field

| ai_action | What to Do | |-----------|------------| | proceed_with_operation | Config OK, continue with the original operation | | prompt_for_access_token | Ask user: "I need your HubSpot access token. Create a Private App to get one." | | create_env_file | Create .env file and ask user for credentials | | add_missing_scopes | Guide user to add scopes in HubSpot Private App settings | | verify_token | Token exists but connection failed - verify it's correct |

Step 3: Help User Fix Issues

If ai_action is prompt_for_access_token:

1. Tell user: "HubSpot integration needs setup. I need your Private App access token."
2. Show them: "Create one in HubSpot: Settings → Integrations → Private Apps"
3. Ask: "Paste your HubSpot access token here (starts with 'pat-'):"
4. Once they provide it, write directly to .env:

   HUBSPOT_ACCESS_TOKEN=pat-na1-their-token-here
   

5. Re-run config check to verify

---

Environment Variables

Required in .env:

HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxxxxxxx

---

API Base URL

All API requests go to: https://api.hubapi.com

---

Version: 1.0 Created: 2025-12-13 Status: Production Ready