hubspot-implementation-plan

Files (1)

• SKILL.md

SKILL.md (first lines)

# HubSpot Implementation Plan Generator

Generate a phased, prioritized cleanup and optimization plan from a HubSpot audit report. This skill reads audit findings, sequences them into phases with dependencies, and outputs a detailed implementation roadmap with automation feasibility for each task.

## Prerequisites

- A completed audit report in `reports/`, generated by `/hubspot-audit` (full), `/hubspot-marketing-audit`, or `/hubspot-sales-audit`
- If no audit report exists, ask which side of the portal the user owns and point them at the matching audit

## Steps

### 1. Load the Audit Report

Find the most recent audit report. The audit engine writes one of three names depending on scope:

| Scope | Report |
|-------|--------|
| full | `reports/hubspot-audit-*.md` |
| marketing | `reports/hubspot-marketing-audit-*.md` |
| sales | `reports/hubspot-sales-audit-*.md` |

Each has a `.json` twin with the same data in structured form: `dimensions` (grade, rows with count, percentage, and fix skill) and `prescription` (the ordered skill list). Prefer the JSON for counts and the markdown for context. Extract:
- Letter grades per dimension, and each dimension's lens (shared, marketing, sales)
- Exact counts for each metric
- The Prescription table

If multiple reports exist, use the most recent by date in the filename. If a marketing report and a sales report share a date, plan from both: their shared dimensions are identical, so merge them rather than double-counting.

**Plan only what the report covers.** A marketing-scoped report yields a plan without the Sales Pipeline phase; a sales-scoped report yields a plan without the deliverability and suppression tasks. Do not pad a scoped plan with tasks the audit did not measure.

### 2. Generate the Phased Plan

Analyze the audit findings and organize cleanup tasks into five phases. Each phase builds on the previous one. **Only include tasks that are relevant based on the audit findings** — if a dimension scored A, skip or deprioritize its tasks.

#### Phase 1: Immediate Hygiene (Week 1-2)

These tasks have direct billing or deliverability impact. Do them first.

| Task | Trigger (from audit) | Skill | Automation | Est. Time |
|------|----------------------|-------|------------|-----------|
| Delete contacts with no email address | Data Completeness: missing email count > 0 | `/delete-no-email-contacts` | Fully scriptable | 1 hr |
| Suppress hard bounced contacts | Deliverability: hard bounce count > 0 | `/suppress-hard-bounced` | Hybrid (API + workflow) | 1-2 hrs |
| Suppress global unsubscribes | Deliverability: global unsub count > 0 | `/suppress-global-unsubscribes` | Hybrid (API + workflow) | 1-2 hrs |
| Suppress ghost contacts (never engaged) | Engagement: never-engaged count > threshold | `/suppress-ghost-contacts` | Hybrid (API + workflow) | 2-3 hrs |
| Merge duplicate companies | Duplicates: duplicate domain count > 0 | `/merge-duplicate-companies` | Fully scriptable | 2-4 hrs |
| Reassign deactivated owner contacts | Owner Health: deactivated owners with records > 0 | `/reassign-deactivated-owners` | Fully scriptable | 1-2 hrs |

**Key constraint:** `hs_marketable_status` is **read-only via API**. All suppression tasks use a hybrid approach:
1. Script sets a custom flag property (e.g., `suppress_reason`) via API
2. A HubSpot workflow triggers on that flag and sets the contact as non-marketing

This workflow must be built manually in the HubSpot UI before running suppression scripts.

#### Phase 2: Data Enrichment (Week 3-4)

Fill data gaps to enable segmentation and scoring.

| Task | Trigger (from audit) | Skill | Automation | Est. Time |
|------|----------------------|-------|------------|-----------|
| Enrich company name from association | Completeness: missing company name | `/enrich-company-name` | Fully scriptable | 1-2 hrs |
| Enrich contact industry from company | Completeness: missing industry | `/enrich-industry` | Fully scriptable | 1-2 hrs |
| Standardize country/state values | Completeness: inconsistent geo data | `/standardize-geo-values` | Fully scriptable | 2-3 hrs |
| Backfill country/state from IP or company | Completeness: missing geo data | `/backfill-geo-data` | Fully scriptable | 2-3 hrs |
| Fix lifecycle stages | Completeness: missing or incorrect lifecycle stages | `/fix-lifecycle-stages` | Fully scriptable | 2-3 hrs |
| Assign unowned contacts | Owner Health: unowned contacts > 0 | `/assign-unowned-contacts` | Fully scriptable | 1-2 hrs |

**Key constraint:** Lifecycle stage is forward-only in HubSpot. To set a contact to an *earlier* stage, you must first clear the property (set to empty string), then set the desired value. The script must handle this two-step process.

#### Phase 3: Segmentation & Scoring (Week 4-6)

Build the targeting infrastructure.

| Task | Trigger (from audit) | Skill | Automation | Est. Time |
|------|----------------------|-------|------------|-----------|
| Create ICP tier property and workflows | Always (after enrichment) | `/create-icp-tiers` | Hybrid (API + workflow) | 3-4 hrs |
| Build lead scoring model | Always (after enrichment) | `/build-lead-scoring` | Manual UI only | 4-6 hrs |
| Build smart lists for segments | Always (after scoring) | `/build-smart-lists` | Fully scriptable (Lists API) | 2-3 hrs |
| Create segment lists for campaigns | Always (after smart lists) | `/create-segment-lists` | Fully scriptable | 1-2 hrs |

**Key constraint:** Build lead scoring rules in the UI. A beta Lead Scoring API now exists (`/marketing/lead-scoring/2027-03-beta/scores`) and is useful for snapshotting or cloning a finished score, but it is subject to change and does not document decay. Each score generates CRM properties that ARE readable and filterable via API. Build the scoring model manually based on the ICP tier data from the previous step; verify score distributions via the Search API.

#### Phase 4: Automation (Week 6-8)

Set up ongoing automated hygiene.

| Task | Trigger (from audit) | Skill | Automation | Est. Time |
|------|----------------------|-------|------------|-----------|
| New contact hygiene workflow | Always | `/new-contact-hygiene-workflow` | Hybrid (API + UI review) | 1-2 hrs |
| Engagement-based suppression workflow | Engagement grade D or F | `/engagement-suppression-workflow` | Hybrid (API + UI review) | 1-2 hrs |
| Lifecycle stage progression workflow | Always | `/lifecycle-progression-workflow` | Hybrid (API + UI review) | 1-2 hrs |
| Bounce monitoring workflow | Deliverability grade C or worse | `/bounce-monitoring-workflow` | Hybrid (API + UI review) | 1 hr |
| Export workflows as versioned JSON | After any workflow build | `/workflows-as-code` | Fully scriptable | 30 min |

**Key update:** The v4 Automation API (documented by HubSpot as beta, and subject to change) supports creating, updating, and batch-reading workflows for contacts, companies, deals, and tickets, with all action types (the v3 workflows API is now legacy). The workflow skills are **API-first**: each ships before/execute/after scripts that create the workflows via `POST /automation/v4/flows` — always disabled, so a human reviews them in the UI before enabling. Two options per workflow:

1. **v4 Automation API (primary)** -- Run each skill's scripts, then complete the short UI review. Notes: flows touching sensitive-data properties require the corresponding sensitive-data scopes; a few action types (copy-from-associated-object, internal notifications) have undocumented API field shapes and are added in the UI during review.

2. **Manual UI Build (fallback)** -- Follow the step-by-step instructions in each skill. Required on plan tiers where the Automation API returns 403. (HubSpot Breeze AI can also scaffold workflows from prompts, but it creates event-based OR triggers instead of filter-based AND triggers and cannot configure re-enrollment or "is unknown" conditions — verify everything it builds. The Claude Chrome extension can drive the workflow builder UI directly.)

Each workflow skill (`/new-contact-hygiene-workflow`, `/engagement-suppression-workflow`, `/lifecycle-progression-workflow`, `/bounce-monitoring-workflow`) documents both options. The ICP tier classification workflows in `/create-icp-tiers` are still built in the UI due to their multi-group demotion filter logic. After building, run `/workflows-as-code` to export everything to versioned JSON.

#### Sales Pipeline Track (runs alongside Phases 1-2)

Include this track when the report has sales dimensions. It touches deals rather than contacts, so it does not block or depend on the marketing phases, with one exception: reassigning deactivated owners in Phase 1 covers deals and contacts in the same pass.

| Task | Trigger (from audit) | Skill | Automation | Est. Time |
|------|----------------------|-------|------------|-----------|
| Reassign open deals from deactivated owners | Sales Ownership: orphaned open deals > 0 | `/reassign-deactivated-owners` | Fully scriptable | with Phase 1 |
| Assign unowned SQL / Opportunity contacts | Sales Ownership: unowned sales-stage contacts > 0 | `/assign-unowned-contacts` | Fully scriptable | 1-2 hrs |
| Fix past-due close dates and missing amounts | Deal Data Quality or Pipeline Hygiene graded C or worse | `/cleanup-deals` | Partially scriptable (needs rep input) | 2-4 hrs |
| Review and close stale deals | Pipeline Hygiene: stale open deals > 0 | `/cleanup-deals` | Partially scriptable (needs rep input) | 2-3 hrs |
| Retire empty or over-staged pipelines | Pipeline Configuration graded C or worse | `/cleanup-deals` | Manual UI | 1-2 hrs |
| Reconcile Opportunity contacts with no deal | Sales Ownership: Opportunity contacts with no deal > 0 | `/fix-lifecycle-stages` | Fully scriptable | 1-2 hrs |

**Key constraint:** deal cleanup needs the people who own the deals. Scripts can find every stale or incomplete deal, but only the rep knows whether it is dead. Plan a review session per team rather than a bulk close, and coordinate with the Salesforce admin first if deals sync from Salesforce.

After cleanup, lock in prevention through portal settings: required properties per deal stage, pipeline rules, and a stale-deal task workflow.

#### Phase 5: Ongoing Maintenance (Ongoing)

From TomGranot/hubspot-admin-skills, MIT.

More from TomGranot/hubspot-admin-skills