Automate a sales-to-CS handoff when a HubSpot deal closes won using a Claude Code skill

mkdir -p .claude/skills/cs-handoff/{templates,references}

.claude/skills/cs-handoff/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── slack-handoff.md              # Block Kit template for handoff messages
└── references/
    └── hubspot-deals-api.md          # HubSpot API patterns

---
name: cs-handoff
description: Process recent closed-won deals from HubSpot, send handoff notifications to the CS Slack channel, and create onboarding tasks in HubSpot.
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Find HubSpot deals that recently moved to Closed Won, post a handoff message to Slack with deal context and contact information, and create a high-priority onboarding task in HubSpot for the CS rep.
 
## Configuration
 
Read these environment variables:
 
- `HUBSPOT_ACCESS_TOKEN` — HubSpot private app token (required)
- `SLACK_BOT_TOKEN` — Slack bot token starting with xoxb- (required)
- `SLACK_CHANNEL_ID` — Slack channel ID starting with C (required)
- `CS_OWNER_ID` — HubSpot owner ID for CS task assignment (optional)
 
Default lookback window: 24 hours. The user may request a different window.
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Search for closed-won deals modified in the lookback window using the HubSpot CRM Search API. See `references/hubspot-deals-api.md` for the request and response format.
3. Track processed deal IDs in a local JSON file to avoid duplicate handoffs.
4. For each new deal:
   a. Fetch associated contacts via the deals API.
   b. Get the primary contact's details (name, email, phone, title).
   c. Resolve the deal owner's name from the owner ID.
5. Post a handoff message to Slack using the template in `templates/slack-handoff.md`.
6. If `CS_OWNER_ID` is set, create a high-priority onboarding task in HubSpot associated to the deal.
7. Print a summary of handoffs processed.
 
## Important notes
 
- HubSpot's `hs_lastmodifieddate` updates for any property change, not just stage changes. Some results may not be actual Closed Won transitions. Filter on `dealstage == closedwon` in the search.
- The HubSpot Search API `value` for date filters must be a Unix timestamp in **milliseconds** (multiply seconds by 1000).
- `SLACK_CHANNEL_ID` must be the channel ID (starts with `C`), not the channel name.
- The Slack bot must be invited to the target channel.
- Task association type ID for deal-to-task is `204` (HUBSPOT_DEFINED).
- Use the `requests` library for HubSpot and `slack_sdk` for Slack. Install with pip if needed.

# CS Handoff Slack Template
 
Use this Block Kit structure for each closed-won deal handoff.
 
## Block Kit JSON
 
```json
{
  "channel": "<SLACK_CHANNEL_ID>",
  "text": "CS Handoff: <deal_name>",
  "unfurl_links": false,
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "New Closed-Won Deal — CS Handoff"
      }
    },
    {
      "type": "section",
      "fields": [
        { "type": "mrkdwn", "text": "*Deal*\n<deal_name>" },
        { "type": "mrkdwn", "text": "*Value*\n$<amount>" },
        { "type": "mrkdwn", "text": "*Sales Rep*\n<owner_name>" },
        { "type": "mrkdwn", "text": "*Close Date*\n<close_date>" }
      ]
    },
    { "type": "divider" },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Primary Contact*\n<firstname> <lastname> (<jobtitle>)\n<email>\n<phone>"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Contract Length*\n<contract_length>"
      }
    }
  ]
}
```
 
## Notes
 
- If the deal has a `description` (sales notes), add it as an additional section block.
- Format amount with commas and no decimal places for readability.
- Truncate the close date to YYYY-MM-DD format.
- Set `unfurl_links: false` to keep the message clean.

# HubSpot Deals API Reference
 
## Authentication
 
All requests use Bearer token authentication:
```
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
## Search for closed-won deals
 
**Request:**
 
```
POST https://api.hubapi.com/crm/v3/objects/deals/search
```
 
**Body:**
 
```json
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "dealstage",
          "operator": "EQ",
          "value": "closedwon"
        },
        {
          "propertyName": "hs_lastmodifieddate",
          "operator": "GTE",
          "value": "<cutoff_timestamp_ms>"
        }
      ]
    }
  ],
  "properties": ["dealname", "amount", "closedate", "hubspot_owner_id", "contract_length", "description"],
  "limit": 100
}
```
 
- `value` for date filters is a Unix timestamp in **milliseconds**.
- `limit` max is 100. Paginate using `paging.next.after` if needed.
 
**Response shape:**
 
```json
{
  "total": 2,
  "results": [
    {
      "id": "12345",
      "properties": {
        "dealname": "Meridian Logistics",
        "amount": "96000",
        "closedate": "2026-03-05T00:00:00.000Z",
        "hubspot_owner_id": "67890",
        "contract_length": "24 months",
        "description": "Custom API integration required. Go-live target: Apr 1."
      }
    }
  ]
}
```
 
## Get deal with associations
 
**Request:**
 
```
GET https://api.hubapi.com/crm/v3/objects/deals/{deal_id}?associations=contacts
```
 
**Response associations shape:**
 
```json
{
  "associations": {
    "contacts": {
      "results": [
        { "id": "55001" }
      ]
    }
  }
}
```
 
## Get a contact
 
**Request:**
 
```
GET https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}?properties=firstname,lastname,email,phone,jobtitle,company
```
 
## Get a deal owner
 
**Request:**
 
```
GET https://api.hubapi.com/crm/v3/owners/{owner_id}
```
 
**Response:**
 
```json
{
  "firstName": "James",
  "lastName": "Okoro"
}
```
 
## Create a task
 
**Request:**
 
```
POST https://api.hubapi.com/crm/v3/objects/tasks
```
 
**Body:**
 
```json
{
  "properties": {
    "hs_task_subject": "Onboarding: <deal_name>",
    "hs_task_body": "New closed-won deal ready for CS onboarding.\n\nDeal: ...\nValue: ...",
    "hs_task_status": "NOT_STARTED",
    "hs_task_priority": "HIGH",
    "hubspot_owner_id": "<CS_OWNER_ID>"
  },
  "associations": [
    {
      "to": { "id": "<deal_id>" },
      "types": [
        { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 204 }
      ]
    }
  ]
}
```
 
- `associationTypeId: 204` is the standard deal-to-task association.
- Requires `crm.objects.tasks.write` scope on the private app.

/cs-handoff

Searching for closed-won deals in the last 24 hours...
Found 3 closed-won deals, 2 new
 
Processing: Meridian Logistics
  Slack: posted handoff message
  HubSpot: created onboarding task (ID: 78901)
 
Processing: Widget Corp Expansion
  Slack: posted handoff message
  HubSpot: CS_OWNER_ID not set — skipping task
 
Done. Processed 2 handoff(s).

# Run every hour during business hours
0 8-18 * * 1-5 cd /path/to/your/project && claude -p "Run /cs-handoff" --allowedTools 'Bash(*)' 'Read(*)'

name: CS Handoff Check
on:
  schedule:
    - cron: '0 13-23 * * 1-5'  # 8 AM-6 PM ET, weekdays
  workflow_dispatch: {}
jobs:
  handoff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /cs-handoff"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          HUBSPOT_ACCESS_TOKEN: ${{ secrets.HUBSPOT_ACCESS_TOKEN }}
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
          SLACK_CHANNEL_ID: ${{ secrets.SLACK_CHANNEL_ID }}
          CS_OWNER_ID: ${{ secrets.CS_OWNER_ID }}