Cleans and organizes CRM deal data for accurate reporting and forecasting.

Install

mkdir -p .claude/skills/cleanup-deals && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/16182" && unzip -o skill.zip -d .claude/skills/cleanup-deals && rm skill.zip

Installs to .claude/skills/cleanup-deals

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Standardize deal pipelines, remove test deals, and address deals with missing amounts or close dates. Coordinates with Salesforce sync if applicable.
149 charsno explicit “when” trigger
Intermediate

Key capabilities

  • →Identify deals with missing amounts or close dates.
  • →Delete test deals from HubSpot pipelines.
  • →Close stale deals based on inactivity.
  • →Standardize pipeline stage names and probability percentages.
  • →Archive or delete unused pipelines.
  • →Coordinate with Salesforce admin for synced deals.

How it works

The skill audits HubSpot deal data, identifies issues like test deals or missing information, and then executes cleanup actions such as deletion, closing, or standardization.

Inputs & outputs

You give it
User request to clean up HubSpot deal data.
You get back
Cleaned HubSpot deal pipelines, reduced counts of test/stale deals, and standardized deal properties.

When to use cleanup-deals

  • →Clean up test deals in pipeline
  • →Remove stale opportunities
  • →Standardize CRM deal data

About this skill

Cleanup Deals

Standardize deal data to make pipeline reporting accurate. Test deals, missing amounts, and stale opportunities distort forecasts and pipeline metrics.

The fix for most bad deal data is a decision only the deal owner can make: is this deal alive, what is it worth, when will it close, why was it lost. So the scripted path here finds the problems precisely and puts them in front of the right person. It does not make those decisions for them.

Prerequisites

  • A HubSpot service key (HUBSPOT_ACCESS_TOKEN in .env; an existing legacy private app token also works) with:
    • crm.objects.deals.read and crm.objects.owners.read (all stages)
    • crm.objects.contacts.write (HubSpot gates task creation on it; review-task mode only)
    • crm.objects.deals.write (reviewed-deletion mode only)
  • Python 3.10+ with 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.

Every script sets synced deals aside: they never appear in a finding CSV, never go into a review task, and execute.py refuses to delete them even if they are marked in a CSV. before.py reports how many were skipped per finding so you can raise them with the Salesforce admin.

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/cleanup-deals/ in a clone of the repo).

StageScriptRun with
Beforescripts/before.pyuv run scripts/before.py [--stale-days 60] [--pipeline ID]
Executescripts/execute.pyuv run scripts/execute.py (review tasks)
Executescripts/execute.pyuv run scripts/execute.py --delete-from-csv PATH (reviewed test-deal deletion)
Afterscripts/after.pyuv run scripts/after.py

before.py is read-only: it exports one CSV per finding to data/audit-logs/cleanup-deals-before-<finding>.csv plus a summary the After stage compares against. execute.py creates one review task per deal owner, or deletes only the test deals a person marked. after.py re-counts every finding and prints a before/after table. All three share their finding definitions through scripts/deal_findings.py, so every stage counts the same deals. The scripts target HubSpot's date-based API version 2026-09 (API_VERSION in deal_findings.py).

Findings

FindingDefinition
past-close-dateOpen deal whose closedate is before today
staleOpen deal with no logged activity (notes_last_updated) in N days (default 60). A deal with no activity at all counts only once it is older than N days.
missing-amount-or-close-dateOpen deal with no amount or no closedate
lost-no-reasonClosed-lost deal with no closed_lost_reason
likely-testAny deal whose name contains the word test, dummy, sample, or asdf, or with amount 0 and no associated contacts. "demo" is excluded on purpose: real deals are often named after the demo that opened them.

Why Execute Does Not Bulk-Close Deals

The obvious script would set every stale or past-due deal to Closed Lost. This skill does not ship one, for four reasons:

  1. Inactivity is not a loss. notes_last_updated only moves when someone logs an activity in HubSpot. Deals worked by phone, from a personal inbox, or in another tool look stale while they are alive. A bulk close marks real pipeline as lost.
  2. A close is not cleanly reversible. Moving a deal to Closed Lost writes a close date, fires stage-based workflows and notifications, and changes win rate, forecast, and quota attainment reports. Moving it back does not unsend the emails or undo the workflow actions, and the deal's stage history keeps the false loss.
  3. A bulk close destroys the signal it was meant to fix. A loss reason filled in by a script ("Closed by cleanup") tells you nothing about why deals are lost, which is the reason to collect loss reasons at all.
  4. The owner has the answer. Amount, close date, next step, and loss reason are facts the rep knows and the CRM does not. Routing each rep one task with their flagged deals gets those facts into the record. A script can only guess them.

Deletion is narrower still: only deals a person marked yes in the review column of the likely-test CSV, never Salesforce-synced deals, never closed-won deals (deleting them rewrites revenue history), and at most 100 per run.

Step-by-Step Instructions

Stage 1: Plan

Confirm with the user before starting:

  1. Which pipelines are in scope, and which are Salesforce-synced (hands off without coordination)? Pass --pipeline ID to limit a run to one pipeline.
  2. The staleness cutoff (default: 60 days without logged activity; --stale-days N).
  3. Who receives the review tasks. Every flagged deal's owner gets one task. Deals with no owner or a deactivated owner are listed in the plan CSV but get no task: fix ownership first with /cleanup-lead-owners or /reassign-deactivated-owners.

Stage 2: Before

uv run scripts/before.py

Present the counts table to the user, with the number of Salesforce-synced matches skipped. Walk through a few rows of each CSV to confirm the findings are right for this portal (for example, that the test-deal heuristic is not catching real deals).

If the user wants test deals deleted, have them open data/audit-logs/cleanup-deals-before-likely-test.csv, read the reason column, and put yes in the delete column of each row that is a genuine test deal. Leave every other row blank. Rows without yes are never deleted.

Stage 3: Execute

Review tasks (the default):

uv run scripts/execute.py

The script groups the flagged deals by owner, writes the plan to data/audit-logs/cleanup-deals-execute-tasks-plan.csv, prints one line per owner, and asks for CREATE TASKS. Each owner gets one task, due in 7 days, associated with their flagged deals and listing why each was flagged. Owners who already have an open review task from a previous run are skipped, so re-running does not stack duplicate tasks on a rep. No deal is modified.

Reviewed test-deal deletion (opt-in):

uv run scripts/execute.py --delete-from-csv data/audit-logs/cleanup-deals-before-likely-test.csv

The script reads only the rows marked yes, re-reads those deals from HubSpot, refuses Salesforce-synced and closed-won deals, writes every deal's current properties to data/audit-logs/cleanup-deals-execute-delete-backup.csv, and asks for DELETE.

Manual follow-ups the scripts do not cover:

  1. Standardize pipeline stages: ensure all pipelines have consistent stage names and probability percentages (Settings > Objects > Deals > Pipelines).
  2. Remove unused pipelines: if a pipeline has zero active deals and is not in use, archive or delete it. The sales audit's Pipeline Configuration section lists them.

Stage 4: After

uv run scripts/after.py

Prints Before, After, and Change per finding, using the stale cutoff and pipeline recorded by before.py. Review tasks change nothing on their own, so run this after the task due date: the counts fall as owners work their tasks. A finding that does not move points to a process gap (no required close date, no loss-reason field on the Closed Lost stage) rather than a data gap. See Tips.

Safety Mechanisms

MechanismDetail
Read-only Before and Afterbefore.py and after.py issue only searches and reads. The offline tests assert that neither makes a write call.
No bulk close, no property editsexecute.py has no code path that changes a deal's stage or properties. See "Why Execute Does Not Bulk-Close Deals".
Abort thresholdsReview tasks: 50 per run (TASK_ABORT_THRESHOLD), since each one lands on a person's task queue. Deletion: 100 deals per run (DELETE_ABORT_THRESHOLD), checked before any API call. Above either, the script exits without writing. Narrow with --pipeline, or raise the constant only after the user reviews the plan.
CSV audit trailTask mode writes the full owner-by-deal plan before creating anything, then a log of created task IDs. Deletion mode writes every targeted deal's properties to a backup CSV before archiving, then a per-deal deletion log.
Typed confirmationCREATE TASKS for review tasks, DELETE for deletion. Any other input aborts with nothing changed.
Human review gate for deletionOnly rows a person marked yes in the CSV's delete column are deleted. A CSV without that column is refused.
Salesforce and closed-won protectionSynced deals are excluded from every finding and refused in deletion mode. Closed-won deals are refused in deletion mode.
No duplicate tasksOwners with an open task carrying the review subject are skipped on re-runs.
Recovery windowDeleted deals can be restored for 90 days from the deals index page (Actions > Restore records). Review tasks can be deleted from the task queue.

Technical Gotchas

  1. 2026-09 paths have not been run against a live portal. The scripts use the date-based paths documented for 2026-09 (/crm/objects/2026-09/deals/search, /crm/objects/2026-09/tasks, /crm/owners/2026-09). HubSpot states most v3 contracts carry over but not all, and 2026-09 rejects writes that omit admin-required pr

Content truncated.

When not to use it

  • →When deleting or modifying Salesforce-synced deals without coordination.

Prerequisites

A HubSpot private app access token with crm.objects.deals.read and crm.objects.deals.write scopesPython 3.10+uv

Limitations

  • →It requires a HubSpot private app access token with specific scopes.
  • →It cannot delete or modify Salesforce-synced deals without coordination.
  • →Deleted deals can only be restored from HubSpot's recycling bin within 90 days.

How it compares

This skill automates the process of cleaning and standardizing HubSpot deal data, unlike manual review and correction.

Compared to similar skills

cleanup-deals side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
cleanup-deals (this skill)08moReviewIntermediate
googlesheets-automation37moNo flagsIntermediate
add-vault-note18moNo flagsIntermediate
taxonomy-management06moReviewIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

You might also like

googlesheets-automation

sickn33

Automate Google Sheets operations (read, write, format, filter, manage spreadsheets) via Rube MCP (Composio). Read/write data, manage tabs, apply formatting, and search rows programmatically.

321

add-vault-note

tradingstrategy-ai

Add a note to specific vault

11

taxonomy-management

DusanEngIt

Manage the skill taxonomy: add new skills, deprecate old ones, review and approve pending skill proposals from imports or employee free-text input, check for duplicates, and invalidate taxonomy cache. Use when HR needs to update taxonomy or clear a backlog of unreviewed skill proposals.

00

airtable-automation

diegosouzapw

Airtable Automation via Rube MCP workflow skill. Use this skill when the user needs Automate Airtable tasks via Rube MCP (Composio): records, bases, tables, fields, views. Always search tools first for current schemas and the operator should preserve the upstream workflow, copied support files, and

00

project-management

elhaddajiOtmane

Automated workflows for Git version control, database backups, semantic naming, and task tracking. Use this skill whenever the user asks to save progress, commit changes, or perform project management tasks.

00

everjust-documents

ever-just

Operate the "Documents" app of an everjust.app Odoo 19 tenant (browse/create/move folders and files, upload, download, tag, migrate storage, point Documents at the tenant's private cloud) via the Odoo MCP/ORM. Use to read or mutate a tenant's documents — create a folder (dms.directory) or file (dms.

00

Search skills

Search the agent skills registry