Alert Slack when a HubSpot deal is stuck in a stage for over 14 days using a Claude Code skill

mkdir -p .claude/skills/stale-deals/{templates,references}

.claude/skills/stale-deals/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── slack-alert.md                # Block Kit template for Slack messages
└── references/
    └── hubspot-deals-api.md          # HubSpot API patterns

---
name: stale-deals
description: Find HubSpot deals with no activity for 14+ days and post alerts to Slack
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Search HubSpot for open deals that haven't been modified in a given time window (default: 14 days). Exclude closed-won and closed-lost deals. Post a summary to Slack listing each stale deal with its name, current stage, amount, and days since last activity.
 
## Configuration
 
Read these environment variables:
 
- `HUBSPOT_ACCESS_TOKEN` — HubSpot private app token (required)
- `SLACK_BOT_TOKEN` — Slack bot token starting with xoxb- (required)
- `SLACK_CHANNEL_ID` — Slack channel ID starting with C (required)
 
Default staleness threshold: 14 days. The user may request a different threshold.
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Fetch pipeline stages from HubSpot to build a stage ID → display label map. See `references/hubspot-deals-api.md` for the endpoint and response format.
3. Calculate a cutoff timestamp (default: 14 days ago) in Unix milliseconds.
4. Search for deals where `hs_lastmodifieddate` is before the cutoff using the HubSpot CRM Search API. See `references/hubspot-deals-api.md` for the request and response format.
5. Filter out deals in closed stages (closedwon, closedlost) client-side.
6. For each remaining deal, calculate days stale, resolve the stage name, and include it in a summary message.
7. Post a single summary to Slack using the template in `templates/slack-alert.md`.
8. Print a summary of how many stale deals were found and posted.
 
## Important notes
 
- HubSpot's CRM Search API expects date filter values as Unix timestamps in **milliseconds** (multiply seconds by 1000).
- Use `LT` (less than) operator for `hs_lastmodifieddate` to find deals modified BEFORE the cutoff.
- `hs_lastmodifieddate` updates on ANY property change, not just stage transitions. Some deals with recent notes may not appear as stale even if they haven't moved stages. Mention this in your summary.
- Stage IDs are internal strings like `closedwon` or `appointmentscheduled`, not display labels. You must resolve them via the Pipelines API (step 2).
- `SLACK_CHANNEL_ID` must be the channel ID (starts with `C`), not the channel name.
- The Slack bot must be invited to the target channel or `chat.postMessage` will fail with `not_in_channel`.
- Use `urllib.request` for HTTP calls (no external dependencies required).

# Slack Alert Template
 
Use this Block Kit structure for the stale deals summary message.
 
## Block Kit JSON
 
```json
{
  "channel": "<SLACK_CHANNEL_ID>",
  "text": "<count> stale deal(s) need attention",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "Stale Deal Alert"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*<count> deal(s)* haven't been updated in <threshold>+ days:\n\n- <https://app.hubspot.com/contacts/<PORTAL_ID>/deal/<DEAL_ID>|Deal Name> — *Stage* — $amount — Xd stale\n- ..."
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "Update or close these deals in HubSpot to clear them from future alerts."
        }
      ]
    }
  ]
}
```
 
## Notes
 
- The top-level `text` field is required by the Slack API as a fallback for notifications and accessibility.
- List all stale deals in a single message. If there are more than 20 deals, summarize the total and list the top 20 by staleness.
- Sort deals by days stale (most stale first).
- Include a direct HubSpot link for each deal.

# HubSpot Deals API Reference
 
## Get pipeline stages
 
Build a stage ID → display label map so you can resolve internal IDs like `closedwon` to labels like "Closed Won".
 
**Request:**
 
```
GET https://api.hubapi.com/crm/v3/pipelines/deals
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
```
 
**Response shape:**
 
```json
{
  "results": [
    {
      "id": "default",
      "label": "Sales Pipeline",
      "stages": [
        {
          "id": "appointmentscheduled",
          "label": "Appointment Scheduled"
        },
        {
          "id": "closedwon",
          "label": "Closed Won"
        }
      ]
    }
  ]
}
```
 
Iterate over `results[].stages[]` to build the map: `stage["id"] → stage["label"]`.
 
## Search for stale deals
 
Find deals whose `hs_lastmodifieddate` is before a cutoff date. Use `LT` (less than) to find deals modified BEFORE the cutoff.
 
**Request:**
 
```
POST https://api.hubapi.com/crm/v3/objects/deals/search
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
**Body:**
 
```json
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "hs_lastmodifieddate",
          "operator": "LT",
          "value": "<cutoff_timestamp_ms>"
        }
      ]
    }
  ],
  "properties": ["dealname", "amount", "dealstage", "hs_lastmodifieddate", "hubspot_owner_id"],
  "sorts": [{"propertyName": "hs_lastmodifieddate", "direction": "ASCENDING"}],
  "limit": 100
}
```
 
- `value` is a Unix timestamp in **milliseconds** (multiply seconds by 1000).
- `LT` means "less than" — deals whose last modified date is BEFORE the cutoff.
- `limit` max is 100. If there are more results, use the `after` cursor from `paging.next.after` to paginate.
- Sorting ascending by `hs_lastmodifieddate` puts the most stale deals first.
 
**Response shape:**
 
```json
{
  "total": 12,
  "results": [
    {
      "id": "12345",
      "properties": {
        "dealname": "GlobalTech Platform Upgrade",
        "amount": "45000",
        "dealstage": "qualificationscheduled",
        "hubspot_owner_id": "67890",
        "hs_lastmodifieddate": "2026-02-15T10:30:00.000Z"
      }
    }
  ],
  "paging": {
    "next": {
      "after": "100"
    }
  }
}
```
 
## Excluding closed deals
 
The search API supports `NOT_IN` for the `dealstage` filter, but it's safer to filter client-side since custom closed stages may have different IDs. After fetching results, exclude deals where `dealstage` is `closedwon` or `closedlost`.
 
## Calculating days stale
 
Parse `hs_lastmodifieddate` as an ISO 8601 datetime and subtract it from the current UTC time. Convert the timedelta to days.

/stale-deals

Checking for deals with no activity for 14+ days...
  Loaded 12 pipeline stages
  Found 8 stale open deal(s)
  Posted summary to Slack
Done. Flagged 8 stale deal(s).
Note: hs_lastmodifieddate updates on any property change, so some deals
with recent notes may not appear as stale even if they haven't moved stages.

# Run every weekday at 8:30am
30 8 * * 1-5 cd /path/to/your/project && claude -p "Run /stale-deals" --allowedTools 'Bash(*)' 'Read(*)'

name: Stale Deal Alerts
on:
  schedule:
    - cron: '30 13 * * 1-5'  # Weekdays at 8:30am ET
  workflow_dispatch: {}       # Manual trigger for testing
jobs:
  alert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /stale-deals"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          HUBSPOT_ACCESS_TOKEN: ${{ secrets.HUBSPOT_ACCESS_TOKEN }}
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
          SLACK_CHANNEL_ID: ${{ secrets.SLACK_CHANNEL_ID }}