build-lead-scoring

Files (1)

• SKILL.md

SKILL.md (first lines)

# Build Lead Scoring Model

Create a two-score lead scoring model using HubSpot's new Lead Scoring tool: a Fit score (ICP company fit + persona match) and an Engagement score (behavioral signals with time decay). This enables sales to prioritize by company fit and marketing to prioritize by engagement recency.

## Why This Matters

Without scoring, every lead looks equally (un)important. Sales has no ranked list of who to call first, marketing cannot trigger stage progressions based on engagement, and there is no way to differentiate between a senior decision-maker at a target-vertical enterprise and a generic contact who has never opened an email.

## Prerequisites

- Super Admin permissions in HubSpot
- HubSpot Marketing Hub Professional or Enterprise
- ICP Tier property created and workflows processed (create-icp-tiers skill must be completed first)
- Access to **Marketing > Lead Scoring** (the new tool, NOT the deprecated "HubSpot Score" property)

## Critical: Old vs New Lead Scoring

**The legacy "HubSpot Score" property was retired on August 31, 2025** — it stopped being editable in July 2025 and stopped updating entirely at the retirement date. Any workflow, list, or report still referencing `hubspotscore` has been running on frozen data since then; part of this skill's job is to find and repoint those references.

The **Lead Scoring tool** (Marketing > Lead Scoring) supports:
- Layered architecture: total score limit → group limits → rules → criteria
- Engagement decay (points reduce over time automatically)
- Separate Fit vs Engagement score types, with time frames and thresholds
- Scoring for **contacts, companies, and deals**
- Up to 5 total scores per portal

**Scores are API-readable, and configuration now has a beta API.** HubSpot's Lead Scoring API (`/marketing/lead-scoring/2027-03-beta/scores`, scopes `marketing.lead_scoring.read` and `marketing.lead_scoring.write`, Marketing or Sales Hub Professional and above) can create a score as a draft, overwrite the draft, publish, deactivate, clone, and delete, for contacts and companies. It is beta and subject to change, a `PUT` replaces the whole draft, and its reference does not cover decay settings. This skill therefore still builds the model in the UI, where every option is visible, and treats the API as a way to back up or clone a finished score. Each score you create auto-generates CRM properties (the score value and a threshold property). Those properties are readable and filterable through the CRM Search API like any other property, which is what the After stage and the `/lifecycle-progression-workflow` scripts rely on. Find the internal property names under Settings > Properties after creating each score.

## Interview: Gather Requirements

Before executing, collect the following information from the user:

**Q1: What job titles/personas are most valuable to you?**
- Examples: CEO, COO, CFO, CTO, CRO, VP of Operations, VP of Marketing, Director of Operations, Director of Marketing, Head of Procurement, Engineering Manager
- Default: C-suite and VP-level leaders get the highest scores, followed by Director and Manager-level roles

**Q2: What engagement actions matter most?**
- Examples: Email opens, email clicks, form submissions, website visits, content downloads, webinar registrations
- Default: Form submissions (+30), email clicks (+25), website visits (+20), email opens (+15)

**Q3: What negative signals should reduce scores?**
- Examples: Unsubscribe, hard bounce, competitor domain, no activity in 6+ months, free email domain (gmail, yahoo)
- Default: Global unsubscribe (-100), hard bounce (-50), no activity 6+ months (-20), missing company name (-10)

**Q4: What score threshold should trigger MQL status?**
- Examples: Fit > 30 AND Engagement > 20, combined score > 50, any threshold that matches your sales handoff criteria
- Default: Fit Score > 30 AND Engagement Score > 20

## Plan

1. Review any existing scoring models in the portal
2. Create the Fit Score (company fit + persona match)
3. Create or update the Engagement Score (behavioral signals with decay)
4. Allow 4-6 hours for HubSpot to recalculate all contacts
5. Verify scoring distribution and accuracy (after state)

## Before

1. Navigate to **Marketing > Lead Scoring**
2. Note any existing scores (you have a limit of 5 total)
3. Review existing score criteria — decide whether to update or replace
4. Check that ICP Tier property is fully populated on companies (run create-icp-tiers after state check)
5. Search for leftover references to the retired `hubspotscore` property in workflows, lists, and reports — these have been frozen since August 2025 and must be repointed to the new score properties

## Execute

### Create the Fit Score

1. Go to **Marketing > Lead Scoring**
2. Click **Create score**
3. Select **Fit** as the score type
4. Select **Contact** as the scored object
5. Name it descriptively (e.g., "Lead Fit Score")

#### Score Group 1: ICP Company Tier

Use **Associated company property > ICP Tier**:

These are starting points -- calibrate based on your actual conversion data after 30 days.

| Criteria | Condition | Points (suggested range) |
|----------|-----------|------------------------|
| Primary ICP Company | ICP Tier is "Tier 1 - Primary ICP" | +25 to +35 |
| Secondary ICP Company | ICP Tier is "Tier 2 - Secondary ICP" | +15 to +25 |
| Tertiary ICP Company | ICP Tier is "Tier 3 - Tertiary ICP" | +5 to +15 |
| Not ICP Company | ICP Tier is "Not ICP" | -10 to -20 |

#### Score Group 2: Persona / Job Title

Use **Contact property > Job title > contains any of**:

These are starting points -- adjust titles and weights to match your buyer personas.

| Criteria | Example Title Values | Points (suggested range) |
|----------|---------------------|------------------------|
| C-Suite Executives | CEO, COO, CFO, CTO, CRO, CMO, Chief Revenue Officer | +20 to +30 |
| VP-Level Leaders | VP of Operations, VP of Marketing, VP of Sales, VP of Finance | +20 to +30 |
| Director-Level | Director of Operations, Director of Marketing, Head of Procurement, Director of Finance | +15 to +25 |
| Manager-Level | Engineering Manager, Operations Manager, Marketing Manager, Procurement Manager | +10 to +20 |
| Other Relevant Titles | Analyst, Coordinator, Specialist (if relevant to your sales process) | +5 to +10 |

Customize these titles based on your buyer personas. The point values should reflect how likely each persona is to be a decision-maker or champion for your product. The ranges above are starting points -- review after 30 days and adjust based on which titles actually convert.

#### Score Group 3: Negative Fit Signals

| Criteria | Condition | Points |
|----------|-----------|--------|
| Missing Company Name | Company name is unknown | -10 |
| Hard Bounced | Hard bounce reason is known | -50 |
| Globally Unsubscribed | Unsubscribed from all email = True | -100 |

6. Set the overall score maximum (recommended: 100)
7. Save and turn ON

### Create the Engagement Score

1. Click **Create score** (or edit existing engagement score)
2. Select **Engagement** as the score type
3. Select **Contact** as the scored object

From TomGranot/hubspot-admin-skills, MIT.

More from TomGranot/hubspot-admin-skills