create-icp-tiers

Files (4)

• SKILL.md
• after.py · scripts/
• before.py · scripts/
• execute.py · scripts/

SKILL.md (first lines)

# Create ICP Tier Property and Classification Workflows

Classify every company in the CRM into an Ideal Customer Profile tier based on firmographic data. Creates a custom dropdown property and 4 automated workflows that continuously classify companies as they enter or change.

## Why This Matters

Without ICP classification, every inbound lead looks the same regardless of whether they come from a large enterprise in a target vertical or a tiny company in an irrelevant industry. Sales and marketing have no systematic way to prioritize outreach, allocate resources, or differentiate campaigns by company fit. ICP Tier is also a major input to the lead scoring model.

## Prerequisites

- Super Admin permissions in HubSpot
- A HubSpot service key (`HUBSPOT_ACCESS_TOKEN` in `.env`; an existing legacy private app token also works) with company read/write and `crm.schemas.companies.write` scopes
- Python 3.10+ with [`uv`](https://github.com/astral-sh/uv)
- Access to Automation > Workflows (Marketing Hub Professional or higher)
- Data enrichment processes completed (company name, industry, geo values) so company data is as complete as possible
- Company properties **Number of Employees** and **Industry** should be well-populated. Check coverage:
  - Industry: aim for 80%+ populated
  - Employee count: aim for 80%+ populated
  - Companies missing these fields will fall to "Not ICP" (conservative, intentional)

## Interview: Gather Requirements

Before executing, collect the following information from the user:

**Q1: What industries define your ideal customer?**
- Examples: Manufacturing, Professional Services, Logistics, Retail, Education, Media & Entertainment, Hospitality, Real Estate, Agriculture
- Default: No default -- this is highly business-specific and must be provided by the user

**Q2: What employee count ranges define your tiers?**
- Examples: Tier 1: 1,000+, Tier 2: 200-999, Tier 3: 50-199, Not ICP: under 50
- Default: Tier 1: 1,000+, Tier 2: 200-999, Tier 3: 50-199

**Q3: Are there any other firmographic criteria?**
- Examples: Annual revenue thresholds, geographic restrictions (US-only, EMEA, etc.), specific technologies used, funding stage
- Default: None -- industry and employee count are the primary classification axes

## 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/create-icp-tiers/` in a clone of the repo).

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

`before.py` checks whether the tier property exists and audits industry/employee-count coverage. `execute.py` creates the ICP Tier property (review its configuration block first). `after.py` verifies coverage and tier distribution. The classification workflows themselves are built in the UI (see Execute).

## Plan

1. Define your ICP tier criteria (industry verticals + employee count thresholds)
2. Create the ICP Tier custom property via API or UI
3. Build 4 classification workflows (Tier 1, Tier 2, Tier 3, Not ICP)
4. Activate workflows in staggered sequence
5. Verify classification results (after state)

## Before

### Define Your ICP Tiers

Before building anything, define your criteria framework:

| Tier | Label | Industry Verticals | Employee Threshold |
|------|-------|-------------------|-------------------|
| Tier 1 | Primary ICP | [Your primary verticals, e.g., Manufacturing, Professional Services, Logistics] | [e.g., 1,000+] |
| Tier 2 | Secondary ICP | [Your secondary verticals, e.g., Retail, Education, Media & Entertainment] | [e.g., 200+] |
| Tier 3 | Tertiary ICP | [Your tertiary verticals, e.g., Hospitality, Real Estate, Agriculture] | [e.g., 200+] |
| Not ICP | Not ICP | Everything else | Any |

**Size-based demotion pattern:** Companies in a higher-tier industry but below that tier's employee threshold should be demoted to the next tier down, not classified as "Not ICP". For example:
- A company in a Tier 1 industry with fewer than 1,000 but more than 200 employees -> Tier 2
- A company in a Tier 2 industry with fewer than 200 but more than 50 employees -> Tier 3
- Only companies below 50 employees in any ICP industry, or in non-ICP industries entirely, should be "Not ICP"

This ensures ICP-relevant companies are never lost due to size alone.

### Audit Current State

Run `uv run scripts/before.py`. The core queries:

```python
# Check if the ICP Tier property already exists
# Use your chosen property name (e.g., "company_segment", "buyer_tier", "icp_tier")
PROPERTY_NAME = "company_segment"
resp = requests.get(f"{BASE}/crm/v3/properties/companies/{PROPERTY_NAME}",
                    headers=HEADERS)
print("Property exists" if resp.status_code == 200 else "Property does not exist yet")

# Check data coverage for classification
for prop_name in ["industry", "numberofemployees"]:
    resp = requests.post(f"{BASE}/crm/v3/objects/companies/search", headers=HEADERS, json={
        "filterGroups": [{"filters": [
            {"propertyName": prop_name, "operator": "NOT_HAS_PROPERTY"},
        ]}],
        "limit": 1,
    })
    print(f"Companies missing {prop_name}: {resp.json()['total']}")
```

## Execute

### Step 1: Create the ICP Tier Property

Choose a property name that fits your CRM conventions (e.g., `company_segment`, `buyer_tier`, or `icp_tier`). The name is configurable -- just be consistent across workflows and lists.

**Via API (recommended):** run `uv run scripts/execute.py`, which posts:

```python
# Configure your property name here
PROPERTY_NAME = "company_segment"

resp = requests.post(f"{BASE}/crm/v3/properties/companies", headers=HEADERS, json={
    "name": PROPERTY_NAME,
    "label": "ICP Tier",
    "type": "enumeration",
    "fieldType": "select",
    "groupName": "companyinformation",
    "description": "Automated ICP classification based on industry and employee count. "
                   "Set by workflow - do not edit manually.",

From TomGranot/hubspot-admin-skills, MIT.

More from TomGranot/hubspot-admin-skills