Round-robin route HubSpot leads and notify reps in Slack using a Claude Code skill

mkdir -p .claude/skills/round-robin-leads/{templates,references}

.claude/skills/round-robin-leads/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── rep-roster.md                 # Rep roster and Slack message template
└── references/
    └── hubspot-contacts-api.md       # HubSpot CRM search, update, and batch API patterns

---
name: round-robin-leads
description: Assign unassigned HubSpot leads to reps via round-robin and notify in Slack
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Assign unassigned HubSpot contacts to reps via round-robin and DM each rep in Slack with their new leads. Default: assign only unassigned contacts. The user may request a full rebalance of all contacts.
 
## Configuration
 
Read these environment variables:
 
- `HUBSPOT_ACCESS_TOKEN` — HubSpot private app token (required)
- `SLACK_BOT_TOKEN` — Slack bot token with chat:write scope (required)
- `HUBSPOT_PORTAL_ID` — HubSpot portal ID for contact links (required)
 
The rep roster is defined in `templates/rep-roster.md`. Read it for the list of reps with their HubSpot owner IDs and Slack user IDs.
 
## Workflow
 
1. Validate that `HUBSPOT_ACCESS_TOKEN`, `SLACK_BOT_TOKEN`, and `HUBSPOT_PORTAL_ID` are set. If any are missing, print the error and exit.
2. Read the rep roster from `templates/rep-roster.md`.
3. Search for contacts to assign. Default: filter to contacts without `hubspot_owner_id`. If the user requests a rebalance, fetch all contacts. See `references/hubspot-contacts-api.md`.
4. Assign contacts via round-robin — cycle through the rep roster evenly using modular indexing.
5. Update each contact's `hubspot_owner_id` in HubSpot. For large volumes (50+), use the batch update endpoint. See `references/hubspot-contacts-api.md`.
6. DM each rep in Slack with a summary of their newly assigned leads (names, companies, HubSpot links). See `templates/rep-roster.md` for the message format.
7. Print a summary: total contacts assigned, count per rep, and whether this was a new assignment or rebalance.
 
## Important notes
 
- When rebalancing, warn the user first: "This will reassign ALL contacts, including ones reps are already working. Proceed?" Wait for confirmation before executing.
- Use the batch update endpoint for 50+ contacts to stay within HubSpot's rate limits (150 requests per 10 seconds).
- The rep roster in the template must be updated with real HubSpot owner IDs and Slack user IDs before running.
- Use the `requests` library for HTTP calls. Install with pip if needed.
- Paginate search results using the `after` cursor from `paging.next.after`.
- Cap the Slack message at 20 lead names per rep. If a rep gets more than 20, show the first 20 and add "...and N more."

# HubSpot Contacts API Reference
 
## Authentication
 
```
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
## Search for unassigned contacts
 
**Request:**
 
```
POST https://api.hubapi.com/crm/v3/objects/contacts/search
Authorization: Bearer <token>
Content-Type: application/json
```
 
**Body (unassigned contacts only):**
 
```json
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "hubspot_owner_id",
          "operator": "NOT_HAS_PROPERTY"
        }
      ]
    }
  ],
  "properties": ["firstname", "lastname", "email", "company", "jobtitle"],
  "limit": 100
}
```
 
**Body (all contacts — for rebalancing):**
 
```json
{
  "properties": ["firstname", "lastname", "email", "company", "jobtitle", "hubspot_owner_id"],
  "limit": 100
}
```
 
**Response shape:**
 
```json
{
  "total": 45,
  "results": [
    {
      "id": "12345",
      "properties": {
        "firstname": "Jamie",
        "lastname": "Park",
        "email": "jamie@northwind.com",
        "company": "Northwind Traders",
        "jobtitle": "Marketing Manager"
      }
    }
  ],
  "paging": {
    "next": {
      "after": "100"
    }
  }
}
```
 
Paginate using `after` cursor until `paging.next` is absent.
 
## Update a contact's owner
 
**Request:**
 
```
PATCH https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}
Authorization: Bearer <token>
Content-Type: application/json
```
 
**Body:**
 
```json
{
  "properties": {
    "hubspot_owner_id": "12345678"
  }
}
```
 
## Batch update (for large volumes)
 
```
POST https://api.hubapi.com/crm/v3/objects/contacts/batch/update
```
 
**Body:**
 
```json
{
  "inputs": [
    {"id": "12345", "properties": {"hubspot_owner_id": "12345678"}},
    {"id": "67890", "properties": {"hubspot_owner_id": "23456789"}}
  ]
}
```
 
Up to 100 contacts per batch request. Use this for 50+ contacts to stay within rate limits.
 
## Rate limits
 
150 requests per 10 seconds for private apps. For large rebalances, use the batch endpoint.

# Rep Roster
 
Update this list with your real HubSpot owner IDs and Slack user IDs.
 
## Reps
 
| Name | HubSpot Owner ID | Slack User ID |
|------|-------------------|---------------|
| Alice | 12345678 | U01AAAA |
| Bob | 23456789 | U02BBBB |
| Carol | 34567890 | U03CCCC |
| Dave | 45678901 | U04DDDD |
 
Find HubSpot owner IDs in Settings > Users & Teams.
Find Slack user IDs by clicking a profile > three dots > Copy member ID.
 
## Slack notification format
 
Send each rep a DM summarizing their newly assigned leads:
 
```
📋 *{count} Leads Assigned to You*
• Jamie Park — Marketing Manager at Northwind Traders (View: <hubspot_link>)
• Alex Rivera — VP of Engineering at TechCorp (View: <hubspot_link>)
...and {overflow_count} more
```
 
HubSpot link format: `https://app.hubspot.com/contacts/{PORTAL_ID}/contact/{contact_id}`
 
Cap at 20 lead names per message. If more than 20, add "...and N more" at the end.

/round-robin-leads

Assigning 12 unassigned contacts across 4 reps...
 
  Alice: 3 leads (Jamie Park, Alex Rivera, Sam Ortiz)
  Bob: 3 leads (Morgan Lee, Taylor Kim, Jordan Cruz)
  Carol: 3 leads (Casey Patel, Avery Singh, Drew Nakamura)
  Dave: 3 leads (Riley Zhao, Quinn Adams, Blake Fernandez)
 
Done. Assigned 12 contacts. Each rep was DM'd in Slack.

# Assign unassigned leads every hour
0 * * * * cd /path/to/your/project && claude -p "Run /round-robin-leads" --allowedTools 'Bash(*)' 'Read(*)'

name: Lead Round Robin
on:
  schedule:
    - cron: '0 * * * *'  # Every hour
  workflow_dispatch: {}    # Manual trigger for testing
jobs:
  assign:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /round-robin-leads"
          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 }}
          HUBSPOT_PORTAL_ID: ${{ secrets.HUBSPOT_PORTAL_ID }}