/hubspot

name: hubspot
description: "Read HubSpot contacts, companies, and deals; update deal stages and lifecycle stages; log notes and tasks through gateway-managed bearer tokens."
user-invocable: true
requires:
  bins:
    - node
credentials:
  - id: hubspot-access-token
    kind: bearer
    required: true
    secret_ref:
      source: store
      id: HUBSPOT_ACCESS_TOKEN
    scope: "api.hubapi.com and api.hubspot.com"
    how_to_obtain: "Create a HubSpot Service Key from Development > Keys > Service keys and copy the key. Set `HUBSPOT_ACCESS_TOKEN` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set HUBSPOT_ACCESS_TOKEN <token>` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set HUBSPOT_ACCESS_TOKEN <token>`. Service keys are the recommended single-account system-to-system credential for HubSpot REST APIs. Legacy private app access tokens and OAuth access tokens are also accepted bearer credentials; HubSpot personal access keys and developer keys are not valid CRM REST bearer tokens."
metadata:
  hybridclaw:
    category: business
    short_description: "HubSpot CRM reads and guarded writes."
    tags:
      - hubspot
      - crm
      - contacts
      - companies
      - deals
      - service-key
      - private-app-token
      - oauth
    stakes_tiers:
      green:
        - contact-read
        - company-read
        - deal-read
        - property-read
      amber:
        - deal-stage-update
        - lifecycle-stage-update
        - note-create
        - task-create
    escalation:
      writes: confirm-each
      route: f14
    cost_measurement:
      system: UsageTotals
      sub_limit_key: hubspot

HubSpot

Use this skill for HubSpot CRM work when the operator has connected HubSpot to HybridClaw with a HubSpot Service Key, legacy private app access token, or OAuth credentials.

Scope

• read contacts, companies, and deals
• search high-frequency CRM objects by common properties
• inspect HubSpot CRM properties for contacts, companies, and deals
• update a deal's `dealstage`
• update contact, company, or deal `lifecyclestage`
• create timeline notes associated with contacts, companies, or deals
• create tasks associated with contacts, companies, or deals
• plan common natural-language CRM requests before building API calls
• build ordered natural-language workflows with lookup, property-validation, and

write steps for the high-frequency CRM operations

• validate internal HubSpot stage option values from saved property metadata
• interpret common HubSpot authentication, authorization, stage, and rate-limit

errors

• measure cost per assistant run through normal HybridClaw `UsageTotals`

Credential Rules

For normal single-account HubSpot use, create a HubSpot Service Key and store it as `HUBSPOT_ACCESS_TOKEN` in HybridClaw encrypted runtime secrets. Service Keys are HubSpot's recommended account-level, system-to-system bearer credential for direct REST API requests when OAuth and webhooks are not needed. Never paste tokens into a prompt.

Create the Service Key in HubSpot under **Development > Keys > Service keys** or open <https://app.hubspot.com/service-keys>. Give it only the scopes needed for the requested CRM operations, copy the key, and store that value as `HUBSPOT_ACCESS_TOKEN`. Do not use a HubSpot Personal Access Key or Developer Key for this skill; those are for other HubSpot developer workflows and are not valid CRM REST bearer tokens for these calls. HubSpot Service Key docs: <https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/account-service-keys>.

Recommended setup order:

1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets` and set `HUBSPOT_ACCESS_TOKEN`. 2. Browser `/chat` or TUI fallback: `/secret set HUBSPOT_ACCESS_TOKEN <token>`. 3. Local console fallback:

hybridclaw secret set HUBSPOT_ACCESS_TOKEN

Equivalent setup when passing the Service Key explicitly:

hybridclaw auth login hubspot \
  --access-token "<hubspot-service-key>" \
  --account sales@example.com

Legacy private app access tokens can also be stored as `HUBSPOT_ACCESS_TOKEN`, but new single-account REST integrations should prefer Service Keys.

OAuth client credentials are also supported for public app installations:

hybridclaw auth login hubspot \
  --client-id "<hubspot-oauth-client-id>" \
  --client-secret "<hubspot-oauth-client-secret>" \
  --refresh-token "<refresh-token>"

The gateway injects `HUBSPOT_ACCESS_TOKEN` only when an `http_request` uses `bearerSecretName: "HUBSPOT_ACCESS_TOKEN"` against HubSpot API hosts. With OAuth credentials, the gateway mints the access token from `HUBSPOT_CLIENT_SECRET` and `HUBSPOT_REFRESH_TOKEN`; with Service Key or legacy private app setup, the stored bearer credential is used directly.

Required HubSpot scopes depend on the task. The default OAuth login scope set covers contacts, companies, deals, notes, tasks, CRM schema reads, and `oauth`.

Default Workflow

1. Start with reads or `plan`. Do not mutate CRM state unless the user clearly asks for the exact write. 2. Run the bundled helper to build an `http_request` wrapper:

   node skills/hubspot/hubspot.cjs ...

3. Pass only the emitted `httpRequest` object to the built-in `http_request` tool when dry-running or when the helper cannot reach the gateway. For live HubSpot reads and writes, use the helper `run` command so the CJS script owns request construction, gateway submission, and auth-error handling. 4. Never handcraft HubSpot `http_request` calls from memory. The helper owns endpoint selection, method, payload, secret refs, and auth-error handling. 5. For natural-language writes, run `workflow` first. It emits ordered property metadata, lookup, operator confirmation, and write steps. 6. For writes, confirm the target record and intended field change, then pass