Auto-archive stale HubSpot deals using a Claude Code skill

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

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

---
name: archive-stale-deals
description: Find HubSpot deals with no activity for 60+ days, present them for review, and archive confirmed deals to Closed Lost with Slack notification
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Find all active deals in HubSpot with no activity for 60+ days, display them for user review, and close confirmed deals to Closed Lost with a Slack notification.
 
## 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 stale threshold: 60 days. The user may request a different threshold.
 
## Workflow
 
### Phase 1: Discovery
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Fetch pipeline stage definitions from HubSpot to build a stage ID → label map. See `references/hubspot-deals-api.md` for the endpoint.
3. Fetch all deal owners from HubSpot to build an owner ID → name map.
4. Search for deals where `hs_lastmodifieddate` is older than the stale threshold and `dealstage` is not `closedwon` or `closedlost`. Paginate if needed.
5. Print a formatted table showing: Deal ID, Deal Name, Owner, Stage, Amount, Days Stale.
6. Print the total count and total pipeline value at risk.
 
### Phase 2: Confirmation
 
7. **STOP and ask the user** which deals to archive. Wait for explicit confirmation. The user may say:
   - "Archive all of them"
   - "Archive everything except deal 12345"
   - "Just archive the ones owned by [name]"
   - "Skip it for now"
 
### Phase 3: Archive
 
8. For each confirmed deal, PATCH the deal stage to `closedlost` with `closed_lost_reason` set to "Stale — auto-archived after 60 days".
9. Post a single Slack notification listing all archived deals using the format in `templates/slack-archive-notification.md`.
10. Print a summary of how many deals were closed and how many failed.
 
## Important notes
 
- Deal amounts may be null or empty. Treat missing amounts as $0.
- The Deals Search API returns max 100 results per request. Use the `after` cursor from `paging.next.after` to paginate.
- Use `hs_lastmodifieddate` (not `closedate`) to determine if a deal is stale.
- Stage IDs in deal properties are internal identifiers — map them to human-readable labels using the pipelines endpoint.
- The `closed_lost_reason` property name depends on your HubSpot configuration. Some portals use `hs_closed_lost_reason` or a custom property.
- NEVER close a deal without explicit user confirmation. The confirmation step is mandatory.
- Use the `requests` library for HTTP calls and `slack_sdk` for Slack. Install them with pip if needed.

# Slack Archive Notification Template
 
Use this Block Kit structure when notifying Slack about archived deals.
 
## Block Kit JSON
 
```json
{
  "channel": "<SLACK_CHANNEL_ID>",
  "text": "Stale deals auto-archived",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "🗄️ Deals Auto-Archived"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*<count> deals* moved to Closed Lost after 60+ days of inactivity:\n\n<deal_lines>"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "Archived <date_string> • Total value: $<total_value>"
        }
      ]
    }
  ]
}
```
 
## Deal line format
 
Each deal line: `• <Deal Name> — $<Amount> (<X>d stale)`
 
## Notes
 
- The top-level `text` field is required by Slack as a fallback for notifications.
- Format dollar amounts with commas (e.g., $150,000).
- If only one deal was archived, use "1 deal" (singular).
- Omit the amount from deal lines if the deal has no amount set.

# HubSpot Deals API Reference
 
## Get pipeline stages
 
Build a stage ID → label map for displaying human-readable stage names.
 
**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": "qualifiedtobuy", "label": "Qualified to Buy" },
        { "id": "closedwon", "label": "Closed Won" },
        { "id": "closedlost", "label": "Closed Lost" }
      ]
    }
  ]
}
```
 
## Get deal owners
 
Build an owner ID → name map for the stale deals table.
 
**Request:**
 
```
GET https://api.hubapi.com/crm/v3/owners
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
```
 
**Response shape:**
 
```json
{
  "results": [
    {
      "id": "12345",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane@company.com"
    }
  ]
}
```
 
## Search for stale deals
 
Use the CRM Search API to find deals with no activity for 60+ days.
 
**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>"
        },
        {
          "propertyName": "dealstage",
          "operator": "NOT_IN",
          "values": ["closedwon", "closedlost"]
        }
      ]
    }
  ],
  "properties": ["dealname", "amount", "dealstage", "hubspot_owner_id", "hs_lastmodifieddate"],
  "sorts": [{ "propertyName": "hs_lastmodifieddate", "direction": "ASCENDING" }],
  "limit": 100
}
```
 
- `limit` max is 100. Use the `after` cursor from `paging.next.after` to paginate.
- `value` for the date filter must be a Unix timestamp in **milliseconds** (not seconds).
- Compute the cutoff as: `int((now - timedelta(days=60)).timestamp() * 1000)`
- `amount` may be null or empty for deals without a dollar value set.
- `hs_lastmodifieddate` is an ISO 8601 timestamp (e.g., `"2026-01-15T10:30:00.000Z"`).
- `dealstage` is an internal stage ID — map it using the pipelines endpoint above.
 
**Response shape:**
 
```json
{
  "total": 12,
  "results": [
    {
      "id": "98765",
      "properties": {
        "dealname": "Acme Corp — Enterprise",
        "amount": "150000",
        "dealstage": "qualifiedtobuy",
        "hubspot_owner_id": "12345",
        "hs_lastmodifieddate": "2025-12-20T14:30:00.000Z"
      }
    }
  ],
  "paging": {
    "next": { "after": "100" }
  }
}
```
 
## Update a deal (close as lost)
 
**Request:**
 
```
PATCH https://api.hubapi.com/crm/v3/objects/deals/<deal_id>
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
**Body:**
 
```json
{
  "properties": {
    "dealstage": "closedlost",
    "closed_lost_reason": "Stale — auto-archived after 60 days"
  }
}
```
 
- The `dealstage` value `closedlost` is the default internal name. Your pipeline may use a different ID — check HubSpot > Settings > Objects > Deals > Pipelines.
- The `closed_lost_reason` property name may vary. Some portals use `hs_closed_lost_reason` or a custom property.
- Returns 200 on success with the updated deal object.

/archive-stale-deals

Fetching pipeline stages... found 6 stages
Fetching deal owners... found 12 owners
Searching for stale deals (60+ days)...
 
Found 8 stale deals:
 
ID          Deal Name                    Owner          Stage              Amount    Days Stale
─────────────────────────────────────────────────────────────────────────────────────────────
98765       Acme Corp — Enterprise       Jane Smith     Proposal Sent      $150,000        85
87654       Beta Inc — Starter           Unassigned     Qualified          $12,000         72
...
 
Total pipeline value at risk: $340,000
 
Which deals should I archive? You can say "all", list specific IDs, or "skip".

# Run every Friday at 9 AM for weekly pipeline cleanup
0 9 * * 5 cd /path/to/your/project && claude -p "Run /archive-stale-deals — show me the stale deals" --allowedTools 'Bash(*)' 'Read(*)'

name: Weekly Stale Deal Review
on:
  schedule:
    - cron: '0 14 * * 5'  # 9 AM ET = 2 PM UTC, Fridays
  workflow_dispatch: {}
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /archive-stale-deals — find stale deals and post the summary to Slack. Do not archive without confirmation."
          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 }}