Send a Slack alert when a HubSpot deal changes stage using a Claude Code skill

Prerequisites

Why a Claude Code skill?

The other approaches in this guide are deterministic: they run the same logic every time, the same way. An Claude Code skill is different. You tell Claude what you want in plain language, and the skill gives it enough context to do it reliably.

That means you can say:

• "Check for deal stage changes and post alerts to Slack"
• "What deals moved to Negotiation this week?"
• "Post a summary of today's stage changes to #sales-leadership instead"

The skill contains workflow guidelines, API reference materials, and a message template that the agent reads on demand. When you invoke the skill, Claude reads these files, writes a script on the fly, runs it, and reports results. If you ask for something different next time — a longer lookback window, a filtered pipeline, a summary instead of individual posts — the agent adapts without you touching any code.

How it works

The skill directory has three parts:

1. SKILL.md — workflow guidelines telling the agent what steps to follow, which env vars to use, and what pitfalls to avoid
2. references/ — HubSpot API patterns (endpoints, request shapes, response formats) so the agent calls the right APIs with the right parameters
3. templates/ — a Slack Block Kit template so messages are consistently formatted across runs

When invoked, the agent reads SKILL.md, consults the reference and template files as needed, writes a Python script, executes it, and reports what it posted. The reference files act as guardrails — the agent knows exactly which endpoints to hit and what the responses look like, so it doesn't have to guess.

What is a Claude Code skill?

An Claude Code skill is a reusable command you add to your project that Claude Code can run on demand. Skills live in a .claude/skills/ directory and are defined by a SKILL.md file that tells the agent what the skill does, when to run it, and what tools it's allowed to use.

In this skill, the agent doesn't run a pre-written script. Instead, SKILL.md provides workflow guidelines and points to reference files — API documentation, message templates — that the agent reads to generate and execute code itself. This is the key difference from a traditional script: the agent can adapt its approach based on what you ask for while still using the right APIs and message formats.

Once installed, you can invoke a skill as a slash command (e.g., /deal-stage-alerts), or the agent will use it automatically when you give it a task where the skill is relevant. Skills are portable — anyone who clones your repo gets the same commands.

Step 1: Create the skill directory

mkdir -p .claude/skills/deal-stage-alerts/{templates,references}

This creates the layout:

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

Step 2: Write the SKILL.md

Create .claude/skills/deal-stage-alerts/SKILL.md:

---
name: deal-stage-alerts
description: Check for recent HubSpot deal stage changes and post alerts to Slack
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Check for HubSpot deals that changed stage in a given time window (default: last 1 hour) and post a formatted alert per deal to a Slack channel.
 
## 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)
- `HUBSPOT_PORTAL_ID` — HubSpot portal ID for building deal links (optional)
 
Default lookback window: 1 hour. The user may request a different window.
 
## 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. Search for deals modified in the lookback window using the HubSpot CRM Search API. See `references/hubspot-deals-api.md` for the request and response format.
4. For each deal, resolve the stage name from the map and post a message to Slack using the Block Kit format in `templates/slack-alert.md`.
5. Print a summary of how many alerts were posted.
 
## Important notes
 
- HubSpot's `hs_lastmodifieddate` updates on ANY property change, not just stage changes. Some results may not be actual stage transitions. 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 `chat.postMessage` API requires the ID.
- The Slack bot must be invited to the target channel or `chat.postMessage` will fail with `not_in_channel`.
- Use the `requests` library for HTTP calls and `slack_sdk` for Slack. Install them with pip if needed.

Understanding the SKILL.md

Unlike the script-based approach, this SKILL.md doesn't contain a Run: command pointing to a script. Instead, it provides:

The allowed-tools: Bash, Read setting lets the agent both read reference files and execute code. The agent writes its own script based on the workflow steps and reference materials.

Step 3: Add reference files

templates/slack-alert.md

Create .claude/skills/deal-stage-alerts/templates/slack-alert.md:

# Slack Alert Template
 
Use this Block Kit structure for each deal stage change alert.
 
## Block Kit JSON
 
```json
{
  "channel": "<SLACK_CHANNEL_ID>",
  "text": "Deal stage changed: <deal_name>",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": ":arrows_counterclockwise: *Deal Stage Changed*\n*<deal_name>* is now in *<stage_name>*\nAmount: $<amount>"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "<<hubspot_link>|View in HubSpot>"
        }
      ]
    }
  ]
}
```
 
## Notes
 
- The top-level `text` field is required by the Slack API as a fallback for notifications and accessibility. Always include it.
- The HubSpot link format: `https://app.hubspot.com/contacts/<PORTAL_ID>/deal/<DEAL_ID>` (if portal ID is set) or `https://app.hubspot.com/deal/<DEAL_ID>` (without portal ID).
- To customize, you can add fields like deal owner, close date, or pipeline name to the section block text.

references/hubspot-deals-api.md

Create .claude/skills/deal-stage-alerts/references/hubspot-deals-api.md:

# 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 recently modified deals
 
Find deals modified within a time window using the CRM Search API.
 
**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": "GTE",
          "value": "<cutoff_timestamp_ms>"
        }
      ]
    }
  ],
  "properties": ["dealname", "amount", "dealstage", "hubspot_owner_id"],
  "limit": 100
}
```
 
- `value` is a Unix timestamp in **milliseconds** (multiply seconds by 1000).
- `limit` max is 100. If there are more results, use the `after` cursor from `paging.next.after` in the response to paginate.
 
**Response shape:**
 
```json
{
  "total": 3,
  "results": [
    {
      "id": "12345",
      "properties": {
        "dealname": "Acme Corp Annual Contract",
        "amount": "72000",
        "dealstage": "contractsent",
        "hubspot_owner_id": "67890",
        "hs_lastmodifieddate": "2026-03-05T14:30:00.000Z"
      }
    }
  ],
  "paging": {
    "next": {
      "after": "100"
    }
  }
}
```

Step 4: Test the skill

Invoke the skill conversationally:

/deal-stage-alerts

Claude will read the SKILL.md, check the reference files, write a script, install any missing dependencies, run it, and report the results. A typical run looks like:

Checking for deals modified in the last 1 hour(s)...
  Loaded 12 pipeline stages
  Found 3 modified deal(s)
  Posted: Acme Corp Annual Contract → Negotiation
  Posted: Widget Inc Expansion → Proposal Sent
  Posted: Contoso Platform Deal → Discovery
Done. Posted 3 alert(s) to Slack.

What the Slack alert looks like

Because the agent generates code on the fly, you can also make ad hoc requests:

• "Check for deal stage changes in the last 4 hours" — the agent adjusts the lookback window
• "What deals moved to Negotiation today?" — the agent adds a stage filter
• "Post a summary of today's stage changes to #sales-leadership" — the agent adapts the output format and channel

Step 5: Schedule it (optional)

Option A: Cron + Claude CLI

# Run every hour on the hour
0 * * * * cd /path/to/your/project && claude -p "Run /deal-stage-alerts" --allowedTools 'Bash(*)' 'Read(*)'

Option B: GitHub Actions + Claude

name: Deal Stage Alerts
on:
  schedule:
    - cron: '0 * * * *'  # Every hour
  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 /deal-stage-alerts"
          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 }}

Option C: Cowork Scheduled Tasks

Claude Desktop's Cowork supports built-in scheduled tasks. Open a Cowork session, type /schedule, and configure the cadence — hourly, daily, weekly, or weekdays only. Each scheduled run has full access to your connected tools, plugins, and MCP servers.

When to use this approach

• You want conversational flexibility — ad hoc queries like "what moved to Closed Won this week?" alongside scheduled checks
• You want on-demand alerts during pipeline reviews or standups, not just automated notifications
• You're already using Claude Code and want skills that integrate with your workflow
• You want to run tasks in the background via Claude Cowork while focusing on other work
• You prefer guided references over rigid scripts — the agent adapts while staying reliable

When to switch approaches

• You need real-time alerts (under 1 minute latency) → use n8n with webhooks or the code approach
• You want a no-code setup with a visual builder → use Zapier or Make
• You need alerts running 24/7 with zero cost and no LLM usage → use the Code + Cron approach

Common questions

Why not just use a script?

A script runs the same way every time. The Claude Code skill adapts to what you ask — different lookback windows, filtered pipelines, summary format instead of individual posts, a different channel. The reference files ensure it calls the right APIs even when improvising, so you get flexibility without sacrificing reliability.

Does this use Claude API credits?

Yes. Unlike the old script-based approach, the agent reads skill files and generates code each time. Typical cost is $0.01-0.05 per invocation depending on how many deals are returned and how much the agent needs to read. The HubSpot and Slack APIs themselves are free.

Can I run this skill on a schedule without a server?

Yes. GitHub Actions (Option B in Step 5) runs Claude on a cron schedule using GitHub's infrastructure. The free tier includes 2,000 minutes/month.

Can I use this skill in a different repo or share it with my team?

Yes. The .claude/skills/ directory is portable — anyone who clones the repo gets the same skill. They just need to set the environment variables and have Claude Code installed. The skill works in any project directory as long as the .claude/skills/deal-stage-alerts/ path exists.

Cost

• Claude API — $0.01-0.05 per invocation (the agent reads files and generates code)
• HubSpot API — included in all plans, no per-call cost
• Slack API — included in all plans, no per-call cost
• GitHub Actions (if scheduled) — free tier includes 2,000 minutes/month