Skip to content
Skills Library
Sales & customer service · Automation

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).

Licence
MIT
Last repository change
13.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
3
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 13.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. Progression Paths
  2. Prerequisites
  3. Scripts
  4. Building the Workflow: Two Options
  5. Step-by-Step Build Instructions
  6. Rollback
  7. Notes
Original SKILL.md headings · 142 lines, 1,238 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.