Score HubSpot leads based on firmographic and technographic fit using a Claude Code skill

mkdir -p .claude/skills/lead-scoring/{templates,references}

.claude/skills/lead-scoring/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── scoring-model.md              # Default scoring weights and criteria
└── references/
    └── hubspot-contacts-api.md       # HubSpot CRM search and update API patterns

---
name: lead-scoring
description: Score or re-score HubSpot contacts based on firmographic and technographic fit
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Score HubSpot contacts based on ICP fit using firmographic criteria (company size, industry, seniority) and write the score to the `icp_fit_score` custom property. Default: score only unscored contacts. The user may request a full re-score.
 
## Configuration
 
Read these environment variables:
 
- `HUBSPOT_ACCESS_TOKEN` — HubSpot private app token (required)
 
Default mode: score only contacts missing the `icp_fit_score` property.
The user may say "re-score all" to recalculate every contact.
 
## Workflow
 
1. Validate that `HUBSPOT_ACCESS_TOKEN` is set. If missing, print the error and exit.
2. Search for contacts using the HubSpot CRM Search API. Default: filter to contacts without `icp_fit_score`. If re-scoring all, omit the filter. See `references/hubspot-contacts-api.md`.
3. For each contact, apply the scoring model from `templates/scoring-model.md` to calculate a 0-100 score.
4. Update each contact's `icp_fit_score` property via the HubSpot API. See `references/hubspot-contacts-api.md`.
5. Print each contact's name and score, then a summary with the total count and distribution by tier (Hot 80+, Warm 50-79, Cold <50).
 
## Important notes
 
- The `icp_fit_score` custom property must exist in HubSpot before running. If it doesn't, instruct the user to create it (Settings > Properties > Contact Properties, Number type, 0-100).
- HubSpot stores `numberofemployees` as a string. Parse it as an integer, handling empty strings and non-numeric values gracefully.
- Industry values in HubSpot are lowercase strings like "computer software" or "financial services".
- HubSpot allows 150 API requests per 10 seconds. For large contact lists, add a small delay between updates or use the batch update endpoint.
- Use the `requests` library for HTTP calls. Install with pip if needed.
- Paginate search results using the `after` cursor from `paging.next.after`.

# HubSpot Contacts API Reference
 
## Authentication
 
All HubSpot API requests use Bearer token auth.
 
```
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
## Search for contacts
 
Find contacts to score using the CRM Search API.
 
**Request:**
 
```
POST https://api.hubapi.com/crm/v3/objects/contacts/search
Authorization: Bearer <token>
Content-Type: application/json
```
 
**Body (unscored contacts only):**
 
```json
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "icp_fit_score",
          "operator": "NOT_HAS_PROPERTY"
        }
      ]
    }
  ],
  "properties": ["firstname", "lastname", "jobtitle", "company", "numberofemployees", "industry", "hs_analytics_source"],
  "limit": 100
}
```
 
**Body (all contacts — omit filterGroups):**
 
```json
{
  "properties": ["firstname", "lastname", "jobtitle", "company", "numberofemployees", "industry", "hs_analytics_source"],
  "limit": 100
}
```
 
**Response shape:**
 
```json
{
  "total": 250,
  "results": [
    {
      "id": "12345",
      "properties": {
        "firstname": "Sarah",
        "lastname": "Chen",
        "jobtitle": "VP of Sales",
        "company": "Acme Corp",
        "numberofemployees": "250",
        "industry": "computer software",
        "hs_analytics_source": "ORGANIC_SEARCH"
      }
    }
  ],
  "paging": {
    "next": {
      "after": "100"
    }
  }
}
```
 
Paginate using `after` cursor until `paging.next` is absent.
 
## Update a contact's score
 
**Request:**
 
```
PATCH https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}
Authorization: Bearer <token>
Content-Type: application/json
```
 
**Body:**
 
```json
{
  "properties": {
    "icp_fit_score": "82"
  }
}
```
 
Note: Property values are strings, even for number properties.
 
## Batch update (for large volumes)
 
```
POST https://api.hubapi.com/crm/v3/objects/contacts/batch/update
```
 
**Body:**
 
```json
{
  "inputs": [
    {"id": "12345", "properties": {"icp_fit_score": "82"}},
    {"id": "67890", "properties": {"icp_fit_score": "45"}}
  ]
}
```
 
Up to 100 contacts per batch request. Use this for large volumes to stay within rate limits.
 
## Rate limits
 
150 requests per 10 seconds for private apps. For 150+ contacts, use the batch endpoint or add delays.

# Lead Scoring Model
 
Default scoring weights. Total max: 100 points.
 
## Company Size (0-30 points)
 
| Employee Count | Points |
|---------------|--------|
| 200-2,000 | 30 (ideal mid-market) |
| 50-199 | 20 (growing company) |
| 2,001-10,000 | 15 (enterprise) |
| 1-49 or 10,001+ | 5 (outside sweet spot) |
| Unknown/0 | 0 |
 
Parse `numberofemployees` as integer. Handle empty strings and non-numeric values as 0.
 
## Industry Match (0-25 points)
 
| Industry | Points |
|----------|--------|
| saas, technology, software, computer software | 25 (ideal) |
| financial services, consulting, marketing | 15 (good fit) |
| Any other known industry | 5 |
| Unknown/empty | 0 |
 
Match using lowercase comparison against HubSpot's `industry` property.
 
## Job Title Seniority (0-30 points)
 
| Title Keywords | Points |
|---------------|--------|
| ceo, cto, cfo, coo, cmo, cro, chief | 30 (C-suite) |
| vp, vice president, head of | 25 (VP-level) |
| director | 20 |
| manager, lead | 10 |
| Other/unknown | 0 |
 
Match using case-insensitive substring search on `jobtitle`.
 
## Traffic Source (0-15 points)
 
| Source | Points |
|--------|--------|
| ORGANIC_SEARCH | 15 |
| DIRECT_TRAFFIC | 12 |
| REFERRALS | 10 |
| PAID_SEARCH | 8 |
| SOCIAL_MEDIA | 5 |
| Other/unknown | 0 |
 
Match against `hs_analytics_source` (uppercase in HubSpot).
 
## Score Tiers
 
| Tier | Range |
|------|-------|
| Hot | 80-100 |
| Warm | 50-79 |
| Cold | 0-49 |
 
## Customization
 
The user may request different weights, additional criteria, or modified tier boundaries. Adjust the scoring model accordingly while keeping the total max at 100.

/lead-scoring

Scoring unscored contacts...
  Found 45 contacts to score
 
  Sarah Chen (VP of Sales, Acme Corp): 82/100
  Mike Johnson (Director, Widget Inc): 55/100
  ...
 
Done. Scored 45 contacts.
  Hot (80+): 8
  Warm (50-79): 19
  Cold (below 50): 18

# Score unscored contacts every hour
0 * * * * cd /path/to/your/project && claude -p "Run /lead-scoring" --allowedTools 'Bash(*)' 'Read(*)'

name: Lead Scoring
on:
  schedule:
    - cron: '0 * * * *'  # Every hour
  workflow_dispatch: {}   # Manual trigger for testing
jobs:
  score:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /lead-scoring"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          HUBSPOT_ACCESS_TOKEN: ${{ secrets.HUBSPOT_ACCESS_TOKEN }}