build-smart-lists — Claude Code skill: what it does, how to install

---
name: build-smart-lists
description: "Create foundational segmented lists for marketing and sales operations via the Lists API, plus advanced UI-built segments: a master sendable list, ICP-based lists, persona lists, and engagement lists. All active (dynamic) lists."
license: MIT
metadata:
  author: tomgranot
  version: "1.1"
  category: segmentation-scoring
---

# Build Smart Lists for Segmentation

Create the core active (dynamic) lists that serve as the foundation for all marketing campaigns, sales prioritization, and database health monitoring. Ten foundation lists are created automatically via the Lists API (v3); a further set of advanced segments is built in the UI.

## Why This Matters

Without predefined lists, every email campaign requires building filters from scratch, there is no standardized definition of "who can we actually email", and there is no persona-based segmentation. The marketing team cannot quickly answer basic questions like "How many senior decision-makers can we email right now?" or "How many engaged contacts do we have?"

## Prerequisites

- Super Admin or Marketing Hub Admin permissions
- A HubSpot service key (`HUBSPOT_ACCESS_TOKEN` in `.env`; an existing legacy private app token also works) with `crm.lists.read` and `crm.lists.write` scopes
- Python 3.10+ with [`uv`](https://github.com/astral-sh/uv)
- ICP Tier property created and workflows processed (create-icp-tiers skill) — the script assumes the property name `company_segment` with values like `tier_1_primary_icp`; adjust its configuration block if yours differ
- Lead scoring model created (build-lead-scoring skill) is recommended but not required
- Lifecycle Stage property populated for customers and partners (fix-lifecycle-stages skill)

## Scripts

Script paths are relative to this skill's directory. Run them from your project directory so `.env`, `data/`, and `reports/` resolve there: prefix each path with wherever this skill is installed (`skills/build-smart-lists/` in a clone of the repo).

| Stage | Script | Run with |
|-------|--------|----------|
| Execute | [`scripts/execute.py`](./scripts/execute.py) | `uv run scripts/execute.py` |

`execute.py` creates the 10 foundation lists below via `POST /crm/v3/lists`, skips lists that already exist (409), and writes a CSV audit trail of created list IDs. There are no before/after scripts: the before-state inventory is a single Lists API query (see Before), and verification is a member-count review in the UI.

## Interview: Gather Requirements

Before executing, collect the following information from the user:

**Q1: What defines "engaged" for your business? (e.g., activity in last 60-120 days)**
- Examples: Email open or click in last 90 days, website visit in last 60 days, form submission in last 30 days
- Default: Email open or click in the last 90 days (set `ACTIVE_WINDOW_DAYS` in the script; shorter cycles suit high-velocity sales, longer cycles suit enterprise)

**Q2: What job titles represent your target personas?**
- 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/Director-level leaders across business functions (used for the UI-built persona list)

## The List Library

### Foundation lists (created by the script)

| # | List Name | Object | Key Filter |
|---|-----------|--------|-----------|
| 1 | All Marketing Contacts | Contacts | `hs_marketable_status` = true |
| 2 | All Leads | Contacts | Lifecycle stage = Lead |
| 3 | All MQLs | Contacts | Lifecycle stage = MQL |
| 4 | All SQLs | Contacts | Lifecycle stage = SQL |
| 5 | All Customers | Contacts | Lifecycle stage = Customer |
| 6 | ICP Tier 1 Companies | Companies | ICP Tier = Tier 1 |
| 7 | ICP Tier 2 Companies | Companies | ICP Tier = Tier 2 |
| 8 | ICP Tier 3 Companies | Companies | ICP Tier = Tier 3 |
| 9 | Engaged Last 90 Days | Contacts | Email open OR click within the active window |
| 10 | Unengaged 180+ Days | Contacts | Marketable + no email open beyond the re-engagement window |

### Advanced segments (built in the UI)

These use features that benefit from human judgment and portal-specific configuration (list-membership filters, persona keywords, form-name keywords):

| # | List Name | Purpose | Key Filters |
|---|-----------|---------|-------------|
| A | Marketable - Active | Master sendable list (who CAN receive email) | Marketing contact + not unsubscribed + not bounced + has email + not quarantined |
| B | ICP Tier 1 Contacts | Highest priority *contacts* | Associated company ICP Tier = Tier 1 + member of Marketable - Active |
| C | ICP Tier 2 Contacts | Secondary priority contacts | Associated company ICP Tier = Tier 2 + member of Marketable - Active |
| D | Partners | Partner communications and exclusion | Lifecycle stage = Partner (or custom contact type property) |
| E | Re-engagement Needed | Sunset candidates | 5+ emails delivered + no open in 180 days + member of Marketable - Active |
| F | Senior Decision Makers | Top persona list | Job title contains target titles |
| G | Industry Leaders | Contacts at companies in target verticals | Associated company industry is any of target industries |
| H | Content Engaged | Form submissions and content downloads | Form submissions > 0 OR conversion contains content keywords |

Overlap note: "All Customers" (script) covers the Customers use case; "Unengaged 180+ Days" (script) is a simpler variant of "Re-engagement Needed" (UI, adds the delivered-count guard). Keep whichever fits your operation — do not maintain both without a reason.

## Plan

1. Run the interview above; set `ACTIVE_WINDOW_DAYS`, `REENGAGEMENT_WINDOW_DAYS`, and `ICP_PROPERTY_NAME` in the script's configuration block
2. Decide which advanced segments to build in the UI
3. Create foundation lists via the script, advanced segments via the UI
4. Verify list sizes make sense relative to the database

## Before

Inventory existing lists to avoid duplicates (`POST /crm/v3/lists/search` with an empty query returns all lists, paginated). Check for name collisions with the library above — the script skips exact name matches (HTTP 409), but near-duplicates ("Customers" vs "All Customers") need a human decision: merge, rename, or skip.

## Execute

### Step 1: Foundation lists (script)

```bash
uv run scripts/execute.py
```

The script posts each definition to `POST /crm/v3/lists` with `processingType: "DYNAMIC"`. Example payload shape (see the script for all ten):

```python
{
    "name": "All Customers",
    "objectTypeId": "0-1",  # contacts ("0-2" for companies)
    "processingType": "DYNAMIC",
    "filterBranch": {
        "filterBranchType": "AND",
        "filterBranches": [],
        "filters": [{
            "filterType": "PROPERTY",
            "property": "lifecyclestage",
            "operation": {
                "operationType": "ENUMERATION",
                "operator": "IS_EQUAL_TO",
                "value": "customer",
            },
        }],
    },
}
```

If the Lists API returns 403 on your plan tier, build the same lists manually in the UI using the table above.

### Step 2: Marketable - Active (master sendable list — UI)

**This is the most important advanced list.** It defines the single source of truth for "who can receive marketing email." All campaign sends should reference this list.

1. Go to **Contacts > Lists > Create list**
2. Select **Contact-based > Active list**
3. Name: `Marketable - Active`
4. Add filters (all AND logic):
   - Marketing contact status > is any of > Marketing contact
   - AND Unsubscribed from all email > is not equal to > True
   - AND Hard bounce reason > is unknown
   - AND Email > is known
   - AND Email quarantined > is not equal to > True
5. Save the list

### Step 3: Remaining advanced segments (UI)

**ICP Tier 1 / Tier 2 Contacts (B, C):**
- Filters: Associated company property > ICP Tier > is any of > [tier] AND List membership > is member of > Marketable - Active
- **Using List membership as a filter** is a powerful pattern: these lists automatically inherit all deliverability and consent logic from Marketable - Active. New disqualification conditions added there propagate automatically.

**Partners (D):** Lifecycle stage > is any of > Partner. Always exclude from prospect campaigns.

**Re-engagement Needed (E):**
- Marketing emails delivered > is greater than > 5
- AND Last marketing email open date > is more than > 180 days ago (tune to your cycle: 120-270)
- AND List membership > is member of > Marketable - Active
- Feeds the engagement-based suppression workflow.

**Senior Decision Makers (F):** Job title > contains any of > [your target titles]. Customize keywords to your buyer personas.

**Industry Leaders (G):** Associated company property > Industry > is any of > [your target industries].

**Content Engaged (H):** OR logic between groups:
- Number of Form Submissions > is greater than > 0
- OR First conversion > contains any of > [content keywords like "Download", "Guide", "Checklist", "E-Book", "Whitepaper"]
- OR Recent conversion > contains any of > [same keywords]
- The conversion-based filters depend on your form naming conventions — review actual form names (Marketing > Forms) and adjust.

## After

### Verify List Sizes

After all lists are created and processed:

| List | Expected Range | Red Flag If... |
|------|---------------|----------------|
| All Marketing Contacts / Marketable - Active | 30-80% of total contacts | Below 10% (too many excluded) or above 90% (filters too loose) |
| ICP Tier lists | 2-10% of marketable | 0 (ICP Tier not populated) |
| Engaged (active window) | 5-30% of total contacts | Below 2% (possible engagement tracking issue) |
| All Customers | Known customer count | Off by more than 20% from expected |
| Partners | Known partner count | Off by more than 20% from expected |
| Unengaged / Re-engagement Needed | 10-40% of marketable | Above 60% (possible date threshold issue) |
| Senior Decision Makers | 5-25% of total contacts | 0 (job title data missing) |
| Industry Leaders | 10-50% of total contacts | 0 (industry data missing) |
| Content Engaged | 1-10% of total contacts | 0 (no form submissions or wrong keywords) |

### Verification Checklist

1. **All lists show as Active** (not Static) in the list view
2. **All lists have completed processing** (no "Processing" status)
3. **Sendable-list sanity check:** Open Marketable - Active (or All Marketing Contacts), click 5 random contacts. Each should have a valid email, not be unsubscribed, not be bounced.
4. **ICP list check:** Open an ICP Tier 1 list, click 5 records. Each should have ICP Tier = Tier 1.
5. **Persona list check:** Open Senior Decision Makers, verify job titles match expected patterns. Watch for false positives (e.g., "Marketing Intern" matching on "Marketing").
6. **Re-engagement check:** Verify contacts have 5+ emails delivered and no open beyond your configured window.

## Rollback

- Lists can be deleted via `DELETE /crm/v3/lists/{listId}` or the UI — the script's CSV audit trail records every list ID it created.
- Deleting a list does not affect the contacts in it — only the list definition is removed.
- Check whether any workflows, emails, or dependent lists (list-membership filters!) reference a list before deleting it.

## Key Technical Learnings

- **The master sendable list is the foundation.** Every email campaign should either send directly to it (with additional filters) or use it as an inclusion filter. Never send to a list that does not incorporate deliverability and consent checks.
- **List membership as a filter is a powerful pattern.** Changes to the master list's criteria automatically propagate to all dependent lists.
- **"Contains any of" for job titles is broad by design.** It matches the keyword anywhere in the title string, so "CTO" matches "CTO", "Former CTO", "Assistant to the CTO". Review lists periodically and add exclusion terms (e.g., AND Job title does not contain "Former", "Assistant", "Intern") if false positives become a problem.
- **Content and event lists depend on form naming conventions.** The keyword-based filters only work if forms follow a naming convention that includes the keywords. After creating the lists, check if counts seem too low and adjust keywords to match actual form names.
- **Active lists have a processing delay.** HubSpot processes active lists periodically (every few minutes for small lists, potentially longer for complex ones). Wait for processing to complete before judging counts.
- **Each list should be active (dynamic), not static.** Static lists are snapshots that never update. Active lists update automatically as contact properties change, which is essential for ongoing segmentation.
- **The ICP property name and values must match the create-icp-tiers skill.** The script defaults to property `company_segment` with values `tier_1_primary_icp` / `tier_2_secondary_icp` / `tier_3_tertiary_icp`. If you chose different names, update the script's configuration block before running.
- **Plan for growth.** These lists cover core use cases. As marketing operations mature, add more targeted lists: "MQL Ready" (score threshold), "Competitor Employees" (for exclusion), "Recent Form Submitters (Last 30 Days)" (for fast follow-up), or service/product-specific interest lists.
- **Build a dashboard.** Create a dashboard with one KPI tile per list showing the current count. This gives at-a-glance visibility into segment health and makes it easy to spot sudden changes (e.g., Marketable list drops 50% = something broke).