USP

Unlike generic CRM tools, this artifact offers a structured 4-stage execution pattern (Plan, Before, Execute, After) for each skill, providing a phased roadmap for comprehensive HubSpot administration and data hygiene.

Use cases

• 01Auditing HubSpot portal health
• 02Cleaning duplicate or stale CRM data
• 03Automating contact and company enrichment
• 04Building lead scoring models
• 05Implementing email bounce monitoring workflows

Detected files (8)

• skills/cleanup-dashboards/SKILL.mdskill
  Show content (2568 bytes)

  ---
  name: cleanup-dashboards
  description: "Audit and consolidate HubSpot reporting dashboards. Identifies unused, duplicate, or outdated dashboards. Must be performed manually — no dashboard API is available."
  license: MIT
  metadata:
    author: tomgranot
    version: "1.0"
    category: ongoing-maintenance
  ---
  
  # Cleanup Dashboards
  
  Audit HubSpot dashboards to remove clutter and consolidate reporting. Too many dashboards means nobody uses any of them effectively.
  
  ## Important Limitation
  
  HubSpot does not provide a Dashboard API. This entire process must be performed manually in the HubSpot UI under Reports > Dashboards.
  
  ## Prerequisites
  
  - HubSpot portal access with dashboard management permissions
  - Input from team members on which dashboards they actively use
  
  ## Step-by-Step Instructions
  
  ### Stage 1: Before — Inventory All Dashboards
  
  1. Navigate to Reports > Dashboards in HubSpot.
  2. Create a spreadsheet listing every dashboard:
     - Name, owner/creator, number of reports, last viewed date (if visible), purpose
  
  ### Stage 2: Execute — Identify Candidates for Removal
  
  Flag dashboards matching any of these criteria:
  
  1. **Not viewed** in 90+ days (check with the owner first)
  2. **Duplicate** dashboards covering the same metrics
  3. **Test dashboards** (names containing "test", "draft", "copy of")
  4. **Personal dashboards** belonging to departed employees
  5. **Default dashboards** that were never customized
  
  Consolidation targets:
  - Merge dashboards with overlapping report widgets into a single comprehensive dashboard.
  - Aim for 5-10 core dashboards maximum (e.g., Marketing Overview, Sales Pipeline, Email Health, Data Quality, Executive Summary).
  
  ### Stage 3: After — Clean Up and Reorganize
  
  1. Delete confirmed unused dashboards.
  2. Rename remaining dashboards with a clear naming convention (e.g., `[Team] - Purpose`).
  3. Set appropriate sharing/visibility for each dashboard.
  4. Communicate changes to the team — share links to the consolidated dashboards.
  
  ### Stage 4: Rollback
  
  - Deleted dashboards cannot be restored.
  - Before deleting, screenshot each dashboard or note which reports it contained.
  - Individual reports within a dashboard are not deleted when the dashboard is removed — they remain available for re-use.
  
  ## Tips
  
  - Assign a dashboard owner for each core dashboard — someone responsible for keeping it current.
  - Review dashboards quarterly as part of the database cleanup routine.
  - If a report on a dashboard shows stale or broken data, fix the underlying report rather than creating a new dashboard.
  

• skills/cleanup-deals/SKILL.mdskill
  Show content (3173 bytes)

  ---
  name: cleanup-deals
  description: "Standardize deal pipelines, remove test deals, and address deals with missing amounts or close dates. Coordinates with Salesforce sync if applicable."
  license: MIT
  metadata:
    author: tomgranot
    version: "1.0"
    category: ongoing-maintenance
  ---
  
  # Cleanup Deals
  
  Standardize deal data to make pipeline reporting accurate. Test deals, missing amounts, and stale opportunities distort forecasts and pipeline metrics.
  
  ## Prerequisites
  
  - HubSpot API token in `.env`
  - Python with `hubspot-api-client` installed via `uv`
  - Knowledge of which deal pipelines are active and which are synced from Salesforce
  
  ## Important: Salesforce Sync Considerations
  
  If deals are synced from Salesforce:
  - Do NOT delete or modify synced deals without coordinating with the Salesforce admin.
  - Changes in HubSpot may sync back to Salesforce and cause data loss.
  - Identify synced deals by checking for the `hs_salesforceopportunityid` property.
  
  ## Step-by-Step Instructions
  
  ### Stage 1: Before — Audit Deal Data
  
  Pull deal metrics via the API:
  
  ```python
  from hubspot import HubSpot
  from hubspot.crm.deals import PublicObjectSearchRequest
  
  api_client = HubSpot(access_token=os.getenv("HUBSPOT_API_TOKEN"))
  
  # Deals missing amount
  no_amount = PublicObjectSearchRequest(
      filter_groups=[{
          "filters": [{
              "propertyName": "amount",
              "operator": "NOT_HAS_PROPERTY"
          }]
      }]
  )
  
  # Deals missing close date
  no_close = PublicObjectSearchRequest(
      filter_groups=[{
          "filters": [{
              "propertyName": "closedate",
              "operator": "NOT_HAS_PROPERTY"
          }]
      }]
  )
  ```
  
  Record: total deals, deals per pipeline stage, deals missing amount, deals missing close date, stale deals (open with no activity in 60+ days).
  
  ### Stage 2: Execute — Clean Up
  
  1. **Delete test deals** — search for deals with names containing "test", "demo", "sample", or with amount = $0 and no associated contacts.
  2. **Address missing amounts** — export deals without `amount` and work with sales to fill in values or mark as lost.
  3. **Close stale deals** — deals open with no activity in 90+ days should be reviewed with the deal owner. Set to "Closed Lost" if abandoned.
  4. **Standardize pipeline stages** — ensure all pipelines have consistent stage names and probability percentages.
  5. **Remove unused pipelines** — if a pipeline has zero active deals and is not in use, archive or delete it.
  
  ### Stage 3: After — Verify
  
  1. Re-run the deal audit queries. Confirm:
     - Test deals removed
     - Missing amount count decreased
     - Stale deal count decreased
  2. Check pipeline reports for accuracy.
  
  ### Stage 4: Rollback
  
  - Deleted deals can be restored from HubSpot's recycling bin within 90 days.
  - Stage changes and property updates can be reverted manually but there is no bulk undo.
  - For Salesforce-synced deals, check the Salesforce recycle bin as well.
  
  ## Tips
  
  - Establish a deal hygiene rule: deals without activity for 60 days get an automated reminder to the owner (build a simple workflow).
  - Require `amount` and `closedate` as mandatory deal properties to prevent future gaps.
  

• skills/assign-unowned-contacts/SKILL.mdskill
  Show content (7742 bytes)

  ---
  name: assign-unowned-contacts
  description: "Assign an owner to marketing contacts that have no owner. Ensures every marketable contact has accountability for follow-up, proper lead routing, and accurate owner-based reporting."
  license: MIT
  metadata:
    author: tomgranot
    version: "1.0"
    category: data-enrichment
  ---
  
  # Assign Unowned Marketing Contacts
  
  Assign an owner to all marketing contacts that currently have no owner. Unowned contacts create gaps in reporting, prevent proper lead routing, and mean no one is accountable for follow-up on marketing-generated responses.
  
  ## Why This Matters
  
  Marketing contacts without an owner are a blind spot. They receive campaigns but no one sees their responses. They appear in aggregate metrics but not in individual pipeline views. In owner-based dashboards and reports, they simply do not exist. For teams using round-robin or territory-based routing, unowned contacts bypass the entire system.
  
  ## Prerequisites
  
  - Phase 1 hygiene and earlier Phase 3 enrichment processes completed
  - Access to Contacts with permission to bulk edit owner assignments
  - **Approval from team leads before bulk assignment.** This is a business decision, not just a technical one. Get sign-off on the assignment strategy before proceeding.
  
  ## Interview: Gather Requirements
  
  Before executing, collect the following information from the user:
  
  **Q1: Who should unowned contacts be assigned to?**
  - Examples: "Assign all to our Integration User", "Distribute across the sales team", "Assign to the Marketing Team user", "Assign to specific reps by territory"
  - Default: No default -- this is a business decision that requires team lead approval
  
  **Q2: Should we use territory-based routing, round-robin, or a single catch-all owner?**
  - Examples: Territory-based (assign by geography or industry), round-robin (distribute evenly across active reps), catch-all (assign all to one user)
  - Default: Catch-all to a single integration/service user as a temporary measure, with plans to implement proper routing later
  
  ## Plan
  
  1. Identify all marketing contacts with no owner (before state)
  2. Decide on the assignment strategy (catch-all user vs. territory rules)
  3. Execute the bulk assignment
  4. Verify all marketing contacts have owners (after state)
  
  ## Before State
  
  ### Create the Unowned Marketing Contacts List
  
  1. Go to **Contacts > Lists > Create list**
  2. Select **Active list**
  3. Name: `CLEANUP: Unowned Marketing Contacts`
  4. Add filters:
     - Marketing contact status > is any of > Marketing contact
     - AND Contact owner > is unknown
  5. Save the list and note the count
  
  ### Script Approach
  
  ```python
  import os
  from hubspot import HubSpot
  from dotenv import load_dotenv
  
  load_dotenv()
  api_client = HubSpot(access_token=os.getenv("HUBSPOT_API_TOKEN"))
  
  # Count unowned marketing contacts
  result = api_client.crm.contacts.search_api.do_search(
      public_object_search_request={
          "filterGroups": [{
              "filters": [
                  {
                      "propertyName": "hs_marketable_status",
                      "operator": "EQ",
                      "value": "true"
                  },
                  {
                      "propertyName": "hubspot_owner_id",
                      "operator": "NOT_HAS_PROPERTY"
                  }
              ]
          }],
          "limit": 0
      }
  )
  print(f"Unowned marketing contacts: {result.total}")
  ```
  
  ## Execute
  
  ### Assignment Strategy Decision
  
  Choose one of these approaches (requires team lead approval):
  
  **Option A: Catch-All User (Simplest)**
  - Assign all unowned contacts to a single integration/service user
  - Pro: Fast, ensures 100% coverage immediately
  - Con: One "owner" accumulates a large number of contacts; not meaningful for routing
  - Best when: You plan to implement proper routing later and just need coverage now
  
  **Option B: Territory/Region Rules**
  - Assign based on contact geography, industry, or company size
  - Pro: More meaningful ownership, better for sales follow-up
  - Con: Requires a defined routing matrix and more complex execution
  - Best when: You have established sales territories
  
  **Option C: Round-Robin**
  - Distribute evenly across active sales reps
  - Pro: Fair distribution, immediate accountability
  - Con: May assign contacts to reps who do not cover that segment
  - Best when: Small team, all reps handle all segments
  
  ### Bulk Assignment via UI
  
  1. Open the unowned marketing contacts list
  2. Click the checkbox in the table header to select all contacts on the page
  3. Click **Select all X contacts** to select across all pages
  4. Click **Edit** in the toolbar
  5. In the property dropdown, select **Contact owner**
  6. Search for and select the chosen owner
  7. Click **Update**
  8. Confirm the bulk edit
  9. For large numbers (5,000+), HubSpot processes in batches. This may take several minutes.
  
  ### Bulk Assignment via API
  
  ```python
  # Pattern for API-based assignment
  # Useful for territory-based rules or when UI bulk edit times out
  
  OWNER_ID = "your-owner-id"  # Get from Owners API
  
  # 1. Search for unowned marketing contacts (paginate through all)
  # 2. Build batch update payload with hubspot_owner_id = OWNER_ID
  # 3. Submit in batches of 100 via crm.contacts.batch_api.update
  
  # For territory-based routing:
  # 1. Search for unowned marketing contacts
  # 2. For each contact, determine territory based on country/state/industry
  # 3. Map territory to owner ID
  # 4. Batch update with the appropriate owner per contact
  ```
  
  **API notes:**
  - Get owner IDs from the Owners API: `api_client.crm.owners.owners_api.get_page()`
  - To find a specific owner by email: iterate through owners and match on `email`
  - Batch update accepts up to 100 records per call
  - Rate limit: 100 requests per 10 seconds
  
  ## After State
  
  Wait 5-10 minutes for HubSpot to finish processing, then verify.
  
  ```python
  # Re-run the same search
  result = api_client.crm.contacts.search_api.do_search(
      public_object_search_request={
          "filterGroups": [{
              "filters": [
                  {
                      "propertyName": "hs_marketable_status",
                      "operator": "EQ",
                      "value": "true"
                  },
                  {
                      "propertyName": "hubspot_owner_id",
                      "operator": "NOT_HAS_PROPERTY"
                  }
              ]
          }],
          "limit": 0
      }
  )
  print(f"Unowned marketing contacts: {result.total} (should be 0)")
  ```
  
  **Verification checklist:**
  
  1. The unowned marketing contacts list shows 0 contacts
  2. Re-run the before-state script — count should be 0
  3. Spot-check 5-10 contacts that were previously unowned — confirm they show the assigned owner
  4. Check owner-based dashboards/reports to confirm the previously invisible contacts now appear
  
  ## Key Technical Learnings
  
  - **This is a business decision, not just a technical one.** Always get approval from sales/marketing leadership on the assignment strategy before executing. Bulk-assigning contacts to the wrong people creates confusion and erodes trust.
  - **A catch-all user is a temporary solution.** If you assign to a single integration user, plan a follow-up process to redistribute contacts to actual sales reps when proper routing is established.
  - **Pair with lead owner cleanup.** Once proper routing is in place, revisit contacts under the catch-all user and reassign them to real owners.
  - **HubSpot bulk edit limits.** For very large batches (10,000+), the UI bulk edit may time out. Use the API approach instead, which handles pagination and batching gracefully.
  - **New contacts need routing too.** After this one-time cleanup, implement a workflow or lead rotation rule to automatically assign owners to new marketing contacts going forward.
  

• skills/backfill-geo-data/SKILL.mdskill
  Show content (3526 bytes)

  ---
  name: backfill-geo-data
  description: "Enrich missing geographic data (country, state, city) on contacts and companies using HubSpot workflows, external data providers, or IP-based geolocation."
  license: MIT
  metadata:
    author: tomgranot
    version: "1.0"
    category: ongoing-maintenance
  ---
  
  # Backfill Geographic Data
  
  Fill in missing country, state, and city values on contacts and companies. Geographic data enables territory assignment, regional reporting, and compliance (GDPR, state privacy laws).
  
  ## Prerequisites
  
  - HubSpot API token in `.env`
  - Python with `hubspot-api-client` installed via `uv`
  - Standardized geo values already in place (run `/standardize-geo-values` first)
  
  ## Enrichment Methods
  
  ### Method 1: HubSpot Workflow Enrichment (Simplest)
  
  Use HubSpot's built-in Operations Hub data quality tools or Breeze Intelligence (if available on your plan) to auto-fill geographic fields.
  
  1. Create a workflow triggered by: country is unknown AND email is known
  2. Use the "Enrich contact" action (Operations Hub Professional+) or Breeze Intelligence enrichment
  3. If enrichment fills country/state, the workflow completes
  4. If enrichment fails, branch to flag for manual review
  
  ### Method 2: Company Domain Lookup (API-based)
  
  For contacts with a company domain but no geo data, look up the company's geographic information:
  
  ```python
  from hubspot import HubSpot
  from hubspot.crm.contacts import PublicObjectSearchRequest
  
  api_client = HubSpot(access_token=os.getenv("HUBSPOT_API_TOKEN"))
  
  # Find contacts missing country but with company association
  search = PublicObjectSearchRequest(
      filter_groups=[{
          "filters": [
              {"propertyName": "country", "operator": "NOT_HAS_PROPERTY"},
              {"propertyName": "associatedcompanyid", "operator": "HAS_PROPERTY"}
          ]
      }],
      properties=["email", "associatedcompanyid"]
  )
  ```
  
  Copy country/state/city from the associated company to the contact (same pattern as `/enrich-company-name`).
  
  ### Method 3: External Data Provider
  
  Integrate with a third-party enrichment service (Clearbit, ZoomInfo, Apollo, etc.):
  1. Export contacts missing geo data
  2. Run through enrichment provider
  3. Import enriched data back via CSV or API
  
  ## Step-by-Step Instructions
  
  ### Stage 1: Before — Assess the Gap
  
  1. Count contacts missing country, state, and city.
  2. Segment by source — which lead sources tend to have missing geo data?
  3. Choose the enrichment method based on volume and budget.
  
  ### Stage 2: Execute — Run Enrichment
  
  1. Apply the chosen method (or combine methods for maximum coverage).
  2. Process in batches of 100 to respect rate limits.
  3. Validate enriched values against the standardized geo format from `/standardize-geo-values`.
  
  ### Stage 3: After — Verify
  
  1. Re-count contacts missing geographic fields. Calculate improvement percentage.
  2. Spot-check 20-30 enriched contacts for accuracy.
  3. Set up the new-contact hygiene workflow to prevent future gaps.
  
  ### Stage 4: Rollback
  
  - If enrichment data is inaccurate, filter contacts updated by the enrichment process (use `hs_lastmodifieddate` range) and clear the geo fields.
  - Keep a backup export of the original data before running enrichment.
  
  ## Tips
  
  - IP-based geolocation (from form submissions) is already captured by HubSpot in `ip_city`, `ip_state`, `ip_country`. Copy these to the standard fields if the standard fields are empty.
  - Do not overwrite manually-entered geo data with enrichment data — always check "if empty" before writing.
  

• skills/build-lead-scoring/SKILL.mdskill
  Show content (10627 bytes)

  ---
  name: build-lead-scoring
  description: "Create a comprehensive lead scoring model with separate Fit and Engagement scores using HubSpot's new Lead Scoring tool. Replaces the deprecated HubSpot Score property."
  license: MIT
  metadata:
    author: tomgranot
    version: "1.0"
    category: segmentation-scoring
  ---
  
  # 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 old "HubSpot Score" property is deprecated.** Score properties stopped being editable as of July 2025 and stopped updating as of August 2025. Do NOT reference the old HubSpot Score property in any workflows, lists, or reports.
  
  The **new Lead Scoring tool** (Marketing > Lead Scoring) supports:
  - Score groups with max point limits
  - Engagement decay (points reduce over time automatically)
  - Separate Fit vs Engagement score types
  - Up to 5 total scores per portal
  
  ## 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 State
  
  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)
  
  ## 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
  4. Name it descriptively (e.g., "Lead Engagement Score")
  
  #### Positive Engagement Criteria
  
  | Criteria | Condition | Points | Decay |
  |----------|-----------|--------|-------|
  | Opened Marketing Email | Last marketing email open date within last 30 days | +15 | Monthly |
  | Clicked Marketing Email | Last marketing email click date within last 30 days | +25 | Monthly |
  | Visited Website | Number of Sessions > 0 | +20 | Quarterly |
  | Submitted a Form | Number of Form Submissions > 0 | +30 | Quarterly |
  
  #### Negative Engagement Criteria
  
  | Criteria | Condition | Points |
  |----------|-----------|--------|
  | No Email Activity 6+ Months | Last marketing email open date > 180 days ago | -20 |
  
  5. Set the overall score maximum (recommended: 100)
  6. Save and turn ON
  
  ### Example Combined Scoring Framework
  
  For reference, here is how the two scores work together to prioritize contacts:
  
  | Contact Profile | Fit Score | Engagement Score | Priority |
  |----------------|-----------|-----------------|----------|
  | CEO at Tier 1 company, clicked email this week | ~60 | ~55 | Highest |
  | Director of Operations at Tier 2 company, form submission | ~40 | ~50 | High |
  | Unknown title at Tier 3 company, email open only | ~10 | ~15 | Medium |
  | No title, Not ICP, no activity in 6 months | ~-25 | ~-20 | Lowest |
  
  ### For Lifecycle Progression
  
  If you want to automatically progress contacts through lifecycle stages based on scoring:
  
  - Define a combined threshold (e.g., Fit Score > 30 AND Engagement Score > 20 = MQL; typically the combined threshold falls in the 40-60 range, but calibrate based on your pipeline)
  - Build this as a separate workflow (not part of the scoring model itself)
  - This is a separate task from building the scoring model
  
  ## After State
  
  **Allow 4-6 hours for HubSpot to fully recalculate all contact scores.** The new Lead Scoring tool processes asynchronously, and large databases take time.
  
  ### Verification
  
  1. Go to **Contacts > Contacts**
  2. Click **Edit columns** and add both score properties to visible columns
  3. Sort by Fit Score descending
  
  **Check the top 20 contacts:**
  - Job titles should be target personas (CEO, VP of Operations, Director of Marketing, etc.)
  - Associated companies should be Tier 1 or Tier 2
  - If a non-relevant contact appears at the top, review the scoring criteria for issues
  
  **Check the bottom contacts:**
  - Sort ascending (lowest scores first)
  - Bottom contacts should be unsubscribed, bounced, or at Not ICP companies
  - If relevant contacts appear at the bottom, review negative signal weights
  
  **Check score distribution:**
  - Filter Fit Score > 50: High-priority fit (should be your best prospects)
  - Filter Fit Score 20-50: Medium fit
  - Filter Fit Score 1-19: Low fit
  - Filter Fit Score <= 0: Disqualified (should be unsubscribed, bounced, or bad data)
  
  **Sanity check:**
  - Pick 3 contacts at random
  - Manually calculate their expected scores based on your criteria
  - Compare to actual scores
  - Investigate any discrepancies
  
  ## Key Technical Learnings
  
  - **The old "HubSpot Score" property is frozen.** It will not update. Do not reference it in workflows, lists, or reports. Use the new Lead Scoring tool scores instead.
  - **Two separate scores are better than one.** Fit and Engagement serve different purposes: Fit tells you WHO to talk to (company and persona match), Engagement tells you WHEN to talk to them (behavioral recency). Combining into one number obscures both signals.
  - **Score decay is a major improvement.** Enable it on engagement criteria so scores naturally decrease over time. Without decay, a contact who clicked one email two years ago looks the same as one who clicked yesterday.
  - **Allow 4-6 hours for recalculation.** Do not panic if scores show 0 immediately after creation. The new tool processes asynchronously across the entire database.
  - **Limit of 5 scores per portal.** Plan carefully. You may want to reserve slots for future scores (e.g., product-specific engagement scores).
  - **Tune the model after 30 days.** Review whether top-scored contacts are actually converting. Adjust point values based on real conversion data. Lead scoring is iterative, not one-and-done.
  - **Negative signals are as important as positive ones.** Hard bounces and global unsubscribes should carry heavy negative weight to push these contacts to the bottom regardless of other factors.
  - **ICP Tier is the highest-leverage scoring input.** It captures firmographic fit in a single property. Without it, the Fit score has no company-level signal and relies entirely on persona matching.
  

• skills/build-smart-lists/SKILL.mdskill
  Show content (11682 bytes)

  ---
  name: build-smart-lists
  description: "Create foundational segmented lists for marketing and sales operations. Includes a master sendable list, ICP-based lists, persona lists, engagement lists, and behavioral lists. All active (dynamic) lists."
  license: MIT
  metadata:
    author: tomgranot
    version: "1.0"
    category: segmentation-scoring
  ---
  
  # Build Smart Lists for Segmentation
  
  Create 10 core active (dynamic) lists that serve as the foundation for all marketing campaigns, sales prioritization, and database health monitoring. These lists update automatically as contact properties change.
  
  ## 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
  - ICP Tier property created and workflows processed (create-icp-tiers skill)
  - 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)
  
  ## 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: Any email open, email click, or website session in the last 60-120 days (90 days is a common starting point; 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
  
  ## Plan
  
  1. Define the 10 core lists and their filter logic
  2. Create each list as an active (dynamic) list
  3. Verify list sizes make sense relative to the database
  4. Optionally create a dashboard to monitor list sizes
  
  ## The 10 Core Lists
  
  | # | List Name | Purpose | Key Filters |
  |---|-----------|---------|-------------|
  | 1 | Marketable - Active | Master sendable list (who CAN receive email) | Marketing contact + not unsubscribed + not bounced + has email |
  | 2 | ICP Tier 1 Contacts | Highest priority prospects | Associated company ICP Tier = Tier 1 + is Marketable |
  | 3 | ICP Tier 2 Contacts | Secondary priority prospects | Associated company ICP Tier = Tier 2 + is Marketable |
  | 4 | Engaged (Active Window) | Warm contacts showing signs of life | Email open/click in 60-120 days (default: 90) OR website sessions > 0 |
  | 5 | Customers | Customer marketing and exclusion | Lifecycle stage = Customer |
  | 6 | Partners | Partner communications and exclusion | Lifecycle stage = Partner |
  | 7 | Re-engagement Needed | Sunset candidates | 5+ emails delivered + no open in 120-270 days (default: 180) + is Marketable |
  | 8 | Senior Decision Makers | Top persona list | Job title contains target titles |
  | 9 | Industry Leaders | Contacts at companies in target verticals | Associated company industry is any of target industries |
  | 10 | Content Engaged | Form submissions and content downloads | Form submissions > 0 OR conversion contains content keywords |
  
  ## Execute
  
  ### List 1: Marketable - Active (Master Sendable List)
  
  **This is the most important 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
  
  ### List 2: ICP Tier 1 Contacts
  
  1. Create active list: `ICP Tier 1 Contacts`
  2. Filters:
     - Associated company property > ICP Tier > is any of > Tier 1 - Primary ICP
     - AND List membership > is member of > Marketable - Active
  3. Save
  
  **Using List membership as a filter** is a powerful pattern. It means this list automatically inherits all deliverability and consent logic from List 1. If you add a new disqualification condition to List 1 in the future, it propagates here automatically.
  
  ### List 3: ICP Tier 2 Contacts
  
  1. Create active list: `ICP Tier 2 Contacts`
  2. Filters:
     - Associated company property > ICP Tier > is any of > Tier 2 - Secondary ICP
     - AND List membership > is member of > Marketable - Active
  3. Save
  
  ### List 4: Engaged (Active Window)
  
  Configure the engagement window based on your sales cycle: 60-120 days is typical (use 60-90 for high-velocity sales, 90-120 for enterprise). Default: 90 days.
  
  1. Create active list: `Engaged Last [X] Days`
  2. Filters (OR logic between groups):
     - Group 1: Last marketing email open date > is less than > [X] days ago
     - OR Group 2: Last marketing email click date > is less than > [X] days ago
     - OR Group 3: Number of Sessions > is greater than > 0
  3. Save
  
  ### List 5: Customers
  
  1. Create active list: `Customers`
  2. Filters:
     - Lifecycle stage > is any of > Customer
  3. Save
  
  **Purpose:** Use for customer marketing (upsell, cross-sell, retention) and to EXCLUDE customers from acquisition campaigns.
  
  ### List 6: Partners
  
  1. Create active list: `Partners`
  2. Filters:
     - Lifecycle stage > is any of > Partner
  3. Save
  
  **Purpose:** Partner communications and co-marketing. Always exclude from prospect campaigns.
  
  ### List 7: Re-engagement Needed
  
  Configure the re-engagement window based on your sales cycle: 120-270 days is typical (use shorter windows for high-velocity sales, longer for enterprise). Default: 180 days.
  
  1. Create active list: `Re-engagement Needed`
  2. Filters (all AND logic):
     - Marketing emails delivered > is greater than > 5
     - AND Last marketing email open date > is more than > [Y] days ago (default: 180)
     - AND List membership > is member of > Marketable - Active
  3. Save
  
  **Purpose:** Ongoing identification of contacts who should receive a re-engagement campaign before being suppressed or downgraded to non-marketing contacts. Feeds the engagement-based suppression workflow.
  
  ### List 8: Senior Decision Makers
  
  1. Create active list: `Senior Decision Makers`
  2. Filters:
     - Job title > contains any of > [your target titles]
     - Example titles: CEO, COO, CFO, CTO, CRO, VP of Operations, VP of Marketing, VP of Sales, Director of Operations, Director of Marketing, Head of Procurement
  
  Customize the title keywords based on your buyer personas.
  
  3. Save
  
  ### List 9: Industry Leaders
  
  1. Create active list: `Industry Leaders`
  2. Filters:
     - Associated company property > Industry > is any of > [your target industries]
     - Example: Manufacturing, Professional Services, Logistics, Retail, Education, Media & Entertainment
  3. Save
  
  ### List 10: Content Engaged
  
  1. Create active list: `Content Engaged`
  2. Filters (OR logic between groups):
     - Group 1: Number of Form Submissions > is greater than > 0
     - OR Group 2: First conversion > contains any of > [content keywords like "Download", "Guide", "Checklist", "E-Book", "Whitepaper"]
     - OR Group 3: Recent conversion > contains any of > [same content keywords]
  3. Save
  
  **Note:** The conversion-based filters depend on your form naming conventions. Review your actual form names (Marketing > Forms) and adjust the keywords to match.
  
  ## After State
  
  ### Verify List Sizes
  
  After all lists are created and processed:
  
  | List | Expected Range | Red Flag If... |
  |------|---------------|----------------|
  | Marketable - Active | 30-80% of total contacts | Below 10% (too many excluded) or above 90% (filters too loose) |
  | ICP Tier 1 Contacts | 2-10% of marketable | 0 (ICP Tier not populated) |
  | ICP Tier 2 Contacts | 2-10% of marketable | 0 (ICP Tier not populated) |
  | Engaged (Active Window) | 5-30% of total contacts | Below 2% (possible engagement tracking issue) |
  | Customers | Known customer count | Off by more than 20% from expected |
  | Partners | Known partner count | Off by more than 20% from expected |
  | 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. **Marketable - Active sanity check:** Open the list, click 5 random contacts. Each should have a valid email, not be unsubscribed, not be bounced.
  4. **ICP list check:** Open ICP Tier 1 list, click 5 contacts. Each should have an associated company with 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:** Open Re-engagement Needed, verify contacts have 5+ emails delivered and no open beyond your configured re-engagement window.
  
  ## Key Technical Learnings
  
  - **List 1 (Marketable - Active) is the foundation.** Every email campaign should either send directly to this list (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.** Lists 2, 3, and 7 use "is member of Marketable - Active" as a filter. Changes to List 1'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.
  - **Plan for growth.** These 10 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).
  

• skills/bounce-monitoring-workflow/SKILL.mdskill
  Show content (7453 bytes)

  ---
  name: bounce-monitoring-workflow
  description: "Build a workflow to protect sender reputation through automated bounce monitoring. Auto-suppresses contacts above a configurable bounce threshold, alerts on hard bounces, and flags high-bounce contacts for weekly manual review."
  license: MIT
  metadata:
    author: tomgranot
    version: "1.0"
    category: automation-workflows
  ---
  
  # Bounce Monitoring Workflow
  
  Protect your email sender reputation with automated bounce detection and suppression. This workflow catches bounces as they happen rather than waiting for periodic cleanup.
  
  ## How It Works
  
  | Condition | Action |
  |-----------|--------|
  | Hard bounce detected | Alert admin immediately, suppress contact |
  | Suppression threshold reached (commonly 2-3 bounces) | Auto-suppress from marketing emails |
  | Review threshold reached (commonly 3-5 bounces) | Flag for weekly manual review (delete vs. recover) |
  
  ## Prerequisites
  
  - HubSpot Marketing Professional or Enterprise plan
  - A custom contact property (e.g., `email_health_flag` or `delivery_status`) — checkbox or dropdown with value: "flagged for review"
  - Admin email or Slack channel for hard bounce alerts
  
  ## Building the Workflow: Three Options
  
  ### Option 1: Manual UI Build
  
  Follow the step-by-step instructions in the "Execute" section below. This is the most reliable method and gives you full control over every trigger, branch, and action.
  
  ### Option 2: HubSpot Breeze AI
  
  HubSpot's built-in Breeze AI can generate a workflow skeleton from a natural language prompt. Navigate to **Automation > Workflows > Create workflow > "Describe what you want"** and paste the following prompt:
  
  ```
  Create a contact-based workflow that triggers when the "Email Bounce" property
  is known (has a value). The workflow should:
  
  1. First, check if the contact has a hard bounce reason (hard_bounce_reason is known):
     - If YES: send an internal notification saying "Hard bounce: [email]" and set the
       contact as a non-marketing contact
     - If NO: continue to the next check
  
  2. Check if the bounce count is greater than or equal to [your suppression threshold, commonly 2-3]:
     - If YES: set the contact as a non-marketing contact, then check if bounce count
       is >= [your review threshold, commonly 3-5]. If so, set a custom property
       "[your bounce review property]" to "flagged" and send an internal notification
       saying "Contact [email] has [review threshold]+ bounces - review for deletion"
     - If NO: end (below threshold, monitor only)
  
  Enable re-enrollment so the contact re-enters if their bounce count increases.
  ```
  
  **CRITICAL WARNING: Breeze trigger limitations.** Breeze creates **event-based triggers (OR logic)** instead of **filter-based triggers (AND logic)**. After Breeze creates the workflow, you MUST manually verify and fix the trigger/enrollment conditions in the UI. Breeze is best used for creating the workflow skeleton (actions, branches, delays) -- the trigger conditions almost always need manual correction.
  
  **Additional Breeze limitations for this workflow:**
  - Breeze **cannot** create "is unknown" branch conditions -- you must verify that branch conditions checking for hard bounce reason are correctly configured
  - Breeze **cannot** configure re-enrollment rules -- you must enable re-enrollment manually
  - Breeze may flatten the nested branch structure (hard bounce check > 2+ bounces > 3+ bounces) into a single level
  
  ### Option 3: Claude Anthropic Chrome Extension
  
  The Claude Anthropic Chrome extension lets Claude see and interact with the HubSpot workflow builder UI directly. You can describe the workflow logic in natural language and Claude will click through the UI to build it. This is often more accurate than Breeze for workflows with nested branching logic (this workflow has three levels of branches), because Claude can verify the branch hierarchy visually.
  
  To use this approach:
  1. Open the HubSpot workflow builder in Chrome (Automation > Workflows > Create workflow)
  2. Activate the Claude Chrome extension
  3. Describe the workflow using the design table and instructions from this skill
  
  > **Note on Fast Mode**: If you're using Claude Code's Fast Mode to speed up workflow creation,
  > be aware of the billing model: Haiku usage is included in your subscription, but Opus in
  > Fast Mode consumes extra credits. For workflow building tasks (which are UI-heavy and may
  > require many interactions), consider whether the speed tradeoff is worth the credit cost.
  
  ## Step-by-Step Build Instructions
  
  ### Stage 1: Before — Create Properties
  
  1. Create your bounce review property (e.g., `email_health_flag` or `delivery_status`):
     - Object: Contact
     - Type: Single checkbox or dropdown
     - Group: Contact information
  
  2. Identify your current bounce baseline — run a quick search for contacts where `hs_email_bounce` > 0 to understand the starting volume.
  
  ### Stage 2: Execute — Build the Workflow
  
  Build a single contact-based workflow with branching logic.
  
  1. **Trigger:** `hs_email_bounce` is known (fires when bounce count updates)
  
  2. **Branch 1: Hard bounce check**
     - Condition: `hs_email_hard_bounce_reason_enum` is known
     - **YES:**
       - Send internal notification: "Hard bounce: {email} — {hs_email_hard_bounce_reason_enum}"
       - Set `hs_marketable_status` to non-marketing (workflow action)
     - **NO:** Continue to Branch 2
  
  3. **Branch 2: Bounce count >= your suppression threshold (commonly 2-3)**
     - Condition: `hs_email_bounce` is greater than or equal to your suppression threshold
     - **YES:**
       - Set `hs_marketable_status` to non-marketing (workflow action)
       - Continue to Branch 3
     - **NO:** No action (below threshold — monitor only)
  
  4. **Branch 3: Bounce count >= your review threshold (commonly 3-5)**
     - Condition: `hs_email_bounce` is greater than or equal to your review threshold
     - **YES:**
       - Set your bounce review property = flagged
       - Send internal notification: "Contact {email} has [review threshold]+ bounces — review for deletion"
     - **NO:** No further action
  
  5. **Settings:**
     - Re-enrollment: ON (contact should re-enter if bounce count increases)
     - Goal: None
  
  6. **Turn on the workflow.**
  
  ### Stage 3: After — Verify
  
  1. Check workflow history after the first week of email sends.
  2. Review the flagged contacts list weekly — decide for each contact:
     - **Delete** if the email is clearly invalid (typo domain, defunct company)
     - **Attempt recovery** if the domain is valid (could be a temporary mailbox issue)
  3. Monitor overall bounce rate in HubSpot email health dashboard.
  
  ### Stage 4: Rollback
  
  1. Turn off the workflow.
  2. Contacts already suppressed remain non-marketing. To reverse:
     - Filter contacts suppressed by this workflow (check your bounce review property or workflow history)
     - Manually set back to marketing contacts in the UI
  3. Clear your bounce review property values in bulk if needed.
  
  ## Weekly Review Process
  
  For contacts flagged at your review threshold:
  
  1. Export the flagged contacts list.
  2. For each contact, check:
     - Is the email domain still active? (Quick MX record check)
     - Is this a known customer or high-value contact?
     - Was the bounce recent or historical?
  3. **Delete** contacts with invalid domains or clearly fake emails.
  4. **Keep suppressed** contacts with valid domains but repeated soft bounces.
  5. Clear the bounce review property after review.
  

• .claude-plugin/marketplace.jsonmarketplace
  Show content (678 bytes)

  {
    "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
    "name": "hubspot-admin-skills",
    "description": "30+ Claude Code skills for auditing, cleaning, enriching, and automating HubSpot CRM",
    "owner": {
      "name": "Tom Granot",
      "email": "tom@granot.io"
    },
    "metadata": {
      "version": "1.0.0"
    },
    "plugins": [
      {
        "name": "hubspot-admin",
        "source": "./",
        "description": "Complete HubSpot CRM administration toolkit — audit, clean, enrich, segment, automate, and maintain your database",
        "category": "enterprise",
        "homepage": "https://consume.granot.io",
        "author": { "name": "Tom Granot" }
      }
    ]
  }
  

README

# Add the marketplace
/plugin marketplace add tomgranot/hubspot-admin-skills

# Install the plugin
/plugin install hubspot-admin@hubspot-admin-skills

/hubspot-audit

/hubspot-implementation-plan

hubspot-admin-skills/
├── README.md
├── CLAUDE.md
├── LICENSE
├── .gitignore
├── assets/
│   └── hero.png
├── .claude-plugin/
│   ├── marketplace.json
│   └── plugin.json
└── skills/
    ├── hubspot-audit/
    │   └── SKILL.md
    ├── hubspot-implementation-plan/
    │   └── SKILL.md
    ├── delete-no-email-contacts/
    │   ├── SKILL.md
    │   └── scripts/
    │       ├── before.py
    │       ├── execute.py
    │       └── after.py
    ├── suppress-hard-bounced/
    │   ├── SKILL.md
    │   └── scripts/
    │       ├── before.py
    │       └── after.py
    ├── ...                        (32 skills total, 13 with scripts)
    └── backfill-geo-data/
        └── SKILL.md