lifecycle-progression-workflow
/lifecycle-progression-workflow
Build workflows to automate contact progression through the sales funnel: Lead to MQL to SQL to Opportunity to Customer. Each transition is triggered by a specific event (score threshold, meeting booked, deal created, deal won).
- Author
- TomGranot ↗
- Repository
- hubspot-admin-skills ↗
- Licence
- MIT
- Last repository change
- 13.10.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 3
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 13.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 3 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/after.py, scripts/before.py, scripts/execute.py
What it does and when to use it
Build workflows to automate contact progression through the sales funnel: Lead to MQL to SQL to Opportunity to Customer. Each transition is triggered by a specific event (score threshold, meeting booked, deal created, deal won).
Original author description
Build workflows to automate contact progression through the sales funnel: Lead to MQL to SQL to Opportunity to Customer. Each transition is triggered by a specific event (score threshold, meeting booked, deal created, deal won).
How it works
- Progression Paths
- Prerequisites
- Scripts
- Building the Workflow: Two Options
- Step-by-Step Build Instructions
- Rollback
- Notes
SKILL.md preview
--- name: lifecycle-progression-workflow description: "Build workflows to automate contact progression through the sales funnel: Lead to MQL to SQL to Opportunity to Customer. Each transition is triggered by a specific event (score threshold, meeting booked, deal created, deal won)." license: MIT metadata: author: tomgranot version: "1.1" category: automation-workflows --- # Lifecycle Stage Progression Workflow Automate the contact journey through the sales funnel with four progression workflows, each triggered by a specific business event. ## Progression Paths | From | To | Trigger | |------|----|---------| | Lead | MQL | Lead score exceeds threshold | | MQL | SQL | Meeting booked | | SQL | Opportunity | Deal created and associated | | Opportunity | Customer | Deal marked as closed-won | ## Prerequisites - HubSpot Marketing Professional or Enterprise plan - A HubSpot service key (`HUBSPOT_ACCESS_TOKEN` in `.env`; an existing legacy private app token also works) with the `automation` scope (for the API path) - Python 3.10+ with [`uv`](https://github.com/astral-sh/uv) - Lead scoring model configured (run `/build-lead-scoring` first) — you need the internal name of your score property - Deal pipeline set up with a "Closed Won" stage - Meeting tool or integration configured (for SQL transition) ## 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/lifecycle-progression-workflow/` 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` inventories existing workflows and checks name collisions. `execute.py` creates all four progression workflows via `POST /automation/v4/flows` — **always disabled, for review before enabling**. `after.py` verifies and reports enabled state. ## Building the Workflow: Two Options ### Option A: Create via the v4 Automation API (primary) **API status:** HubSpot documents the Workflows API as **beta** and subject to change. Its current reference is the date-based beta path `/automation/v4/2027-03-beta/flows`; this skill's scripts still call the unversioned `/automation/v4/flows` path, which v4's end of support on March 30, 2027 also covers. Creating workflows disabled and reviewing them in the UI is what makes a beta API acceptable here. If a script's create call starts failing, the manual UI build below is the fallback. All four progression workflows are linear (filter-based AND trigger → set lifecycle stage), which the v4 API expresses directly. The script encodes: | Workflow | Enrollment (AND) | Action | |----------|------------------|--------| | Lead → MQL | score property >= threshold + stage = Lead | set stage = MQL | | MQL → SQL | `engagements_last_meeting_booked` is known + stage = MQL | set stage = SQL | | SQL → Opportunity | `num_associated_deals` >= 1 + stage = SQL | set stage = Opportunity | | Opportunity → Customer | `hs_current_customer` = true + stage = Opportunity | set stage = Customer | The last workflow uses `hs_current_customer` — the read-only system property HubSpot introduced in June 2026 that marks contacts belonging to a current customer — as a cleaner signal than inspecting associated deal stages. **Before running:** set `LEAD_SCORE_PROPERTY` in `execute.py` to your score property's internal name. With HubSpot's post-2025 lead scoring tool, each score you create generates its own property — find the internal name under Settings > Properties (it is not the retired `hubspotscore`). ```bash uv run scripts/before.py uv run scripts/execute.py ``` **Safety model:** all four workflows are created with `isEnabled: false`. Review the triggers in the UI, add the optional internal-notification actions (marketing team, sales owner, CS/onboarding — recipients are portal-specific), then enable them one at a time, watching the first enrollments. ### Option B: Manual UI Build Follow the step-by-step instructions in Stage 3 below. Use this on portals where the Automation API is unavailable, or when you prefer to configure the meeting/deal triggers with portal-specific event conditions instead of the property-based equivalents the script uses. **Alternatives:** HubSpot Breeze AI can scaffold these workflows from prompts, but it creates event-based (OR) triggers where AND logic between the event and the current stage is required, and cannot configure re-enrollment — verify everything it builds. The Claude Chrome extension can drive the workflow builder UI directly. Both are secondary options. ## Step-by-Step Build Instructions ### Stage 1: Plan 1. Define your MQL score threshold (typically 40-60 on a 0-100 scale). Adjust after 30-60 days of observation. 2. Identify your lead score property's internal name (post-2025 scoring tool properties are per-score; see `/build-lead-scoring`). 3. Confirm your deal pipeline stages include a clear "Closed Won" equivalent. ### Stage 2: Before 1. Run `uv run scripts/before.py` to inventory workflows and check name collisions. 2. Document current lifecycle stage distribution (run the audit or check the property breakdown) so you can measure the impact. ### Stage 3: Execute **Option A:** run `uv run scripts/execute.py`, then complete the UI review steps listed above. **Option B — manual UI build:** build each as a separate contact-based workflow. #### Workflow 1: Lead to MQL 1. **Trigger:** Your lead score property is greater than or equal to [threshold] AND lifecycle stage is "Lead" 2. **Action:** Set lifecycle stage to "Marketing Qualified Lead" 3. **Action (optional):** Send internal notification to marketing team 4. **Re-enrollment:** OFF #### Workflow 2: MQL to SQL 1. **Trigger:** Meeting booked (use "Meeting activity date" is known, or "Number of meetings booked" is greater than 0) AND lifecycle stage is "Marketing Qualified Lead" 2. **Action:** Set lifecycle stage to "Sales Qualified Lead" 3. **Action (optional):** Send internal notification to sales owner 4. **Re-enrollment:** OFF #### Workflow 3: SQL to Opportunity 1. **Trigger:** Associated deal is created (use "Number of associated deals" is greater than 0) AND lifecycle stage is "Sales Qualified Lead" 2. **Action:** Set lifecycle stage to "Opportunity" 3. **Re-enrollment:** OFF #### Workflow 4: Opportunity to Customer 1. **Trigger:** Associated deal stage equals "Closed Won" AND lifecycle stage is "Opportunity" 2. **Action:** Set lifecycle stage to "Customer" 3. **Action (optional):** Send internal notification to CS/onboarding team 4. **Re-enrollment:** OFF #### Workflow Settings (all four) - Re-enrollment: OFF (lifecycle should only progress forward) - Suppression list: None needed — the lifecycle stage condition prevents backwards movement - Time zone: Not applicable ### Stage 4: After 0. Run `uv run scripts/after.py` (API path) to confirm all four workflows exist and report enabled state. 1. Test each workflow with a test contact: - Manually adjust score/create meeting/create deal/close deal and confirm progression. 2. Verify that workflows do not conflict — a contact should not be enrolled in two progression workflows simultaneously. 3. Check that lifecycle stages only move forward (HubSpot enforces this by default, but verify). 4. After one week, review the workflow history for each. Check for: - Contacts stuck at a stage despite meeting criteria - Unexpected enrollment volumes ## Rollback 1. Turn off any or all four workflows. 2. Lifecycle stages already set remain — HubSpot does not allow backward movement without manual override or a dedicated reset workflow. 3. If stages were set incorrectly, create a temporary workflow or use the API to reset affected contacts. ## Notes - **Backward movement:** HubSpot prevents lifecycle stage from going backward by default. If a deal is lost and the contact should return to MQL, you need a separate "regression" workflow that explicitly sets the stage. - **Multiple deals:** If a contact has multiple deals, the Opportunity-to-Customer workflow fires when any associated deal is closed-won. This is usually the desired behavior. - **Score decay:** HubSpot's post-2025 scoring tool supports engagement decay, so a contact's score may drop below the MQL threshold after promotion. This is fine — the lifecycle stage is already set and will not regress.
Files in this package (4)
- SKILL.md 9 KB
- scripts/after.py 3 KB
- scripts/before.py 3 KB
- scripts/execute.py 12 KB
Versions
The database has no other skills named lifecycle-progression-workflow.
Database snapshot: 13.11.2026 · package version 219363e97997 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100prd-v08-marketing-ops-handoff
Define lifecycle stages and marketing → sales / CSM handoff rules for leads captured by GTM channels during PRD v0.8 Deployment & Ops. Triggers on requests to set up lead lifecycle, define MQL/SQL criteria, build handoff process, or when user asks "what's an MQL?", "marketing to… - 100revops
Designs revenue operations plumbing: lead lifecycle stages, MQL and SQL definitions, lead routing, speed-to-lead and handoff SLAs, pipeline stage definitions, CRM automation, data hygiene and the new-business deal desk. Use when leads are not reaching sales, defining MQL and… - 95revops
When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes. Also use when the user mentions 'RevOps,' 'revenue operations,' 'lead scoring,' 'lead routing,' 'MQL,' 'SQL,' 'pipeline stages,' 'deal desk,' 'CRM automation,'… - 100revops
When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes. Also use when the user mentions 'RevOps,' 'revenue operations,' 'lead scoring,' 'outbound pipeline stages,' 'lead routing,' 'MQL,' 'SQL,' 'pipeline stages,'… - 100lead-handoff-designer
Designs the marketing to sales lead handoff from your CRM lead export, setting MQL vs SQL rules, lead routing, a response time SLA, rejected lead recycling and no-show steps. Use to define MQL and SQL, write a sales SLA or fix speed to lead. Not for scoring (use lead-scoring-model-builder). - 100revops
Audits a client's revenue operations layer — CRM hygiene, MQL→SQL routing, lead scoring, sales-cycle stage definitions, funnel reporting — and produces a prioritized fix-list. Distinct from /lifecycle-marketing (which runs campaigns) and /sales-enablement (which equips reps with…