hubspot-master_skill

Overview

This skill is a non-user-facing shared resource library for HubSpot integration skills. It centralizes setup guides, API references, authentication logic, error handling, and reusable scripts so individual HubSpot skills remain small and consistent. Use it indirectly—specific HubSpot skills reference these resources rather than loading this skill directly.

How this skill works

It exposes reference documents (setup, API patterns, auth, error handling) and a scripts folder with CLI utilities for configuration checks, interactive setup, and common CRM operations (contacts, companies, deals, associations, engagements). Each script follows HubSpot CRM endpoints and returns structured output or JSON for AI consumption. When an integration fails, the provided intelligent error detection flow runs a config check and maps ai_action results to concrete remediation steps.

When to use it

• When multiple HubSpot skills need consistent setup instructions or API patterns
• Before running any HubSpot operation to validate credentials (run check_hubspot_config.py)
• When initial integration is required or credentials must be reconfigured (run setup_hubspot.py)
• To perform common CRM tasks via scripts: list/create/update/search contacts, companies, deals, and engagements
• When diagnosing connection issues, missing scopes, or token problems via the intelligent error flow

Best practices

• Run check_hubspot_config.py with --json as the first step to get machine-readable diagnostics
• Use setup_hubspot.py for interactive initial configuration and to save credentials to .env securely
• Prefer the shared scripts for standard operations to avoid duplicating API logic across skills
• Handle ai_action outputs programmatically: prompt for token, create .env, add scopes, or verify token as directed
• Keep HUBSPOT_ACCESS_TOKEN in a secure environment file and never expose it in logs or public code

Example use cases

• Automated pre-flight config check that returns ai_action for remediation
• Interactive onboarding flow that guides users to create a HubSpot Private App and stores the token in .env
• Listing contacts or companies via scripts and returning JSON for downstream AI processing
• Creating or updating contacts and deals using consistent request templates and error handling
• Retrieving associations to show related contacts, companies, or deals in a downstream skill