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

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

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

---
name: sf-deal-stage-alerts
description: Check for recent Salesforce opportunity stage changes and post alerts to Slack
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Check for Salesforce opportunities modified in a given time window (default: last 1 hour) and post a formatted alert per opportunity to a Slack channel.
 
## Configuration
 
Read these environment variables:
 
- `SALESFORCE_INSTANCE_URL` — Salesforce instance URL, e.g. https://yourorg.my.salesforce.com (required)
- `SALESFORCE_ACCESS_TOKEN` — Salesforce access token with API access (required)
- `SLACK_BOT_TOKEN` — Slack bot token starting with xoxb- (required)
- `SLACK_CHANNEL_ID` — Slack channel ID starting with C (required)
 
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. Query Salesforce for opportunities modified in the lookback window using SOQL via the REST API. See `references/salesforce-opportunities-api.md` for the query and endpoint.
3. For each opportunity, post a message to Slack using the Block Kit format in `templates/slack-alert.md`.
4. Print a summary of how many alerts were posted.
 
## Important notes
 
- Salesforce's `LastModifiedDate` updates on ANY field change, not just stage changes. Some results may not be actual stage transitions. Mention this in your summary.
- Unlike HubSpot, Salesforce stores stage names as human-readable text on `StageName` — no ID-to-label mapping is needed.
- Salesforce access tokens expire based on session timeout settings. If the token has expired, the API returns INVALID_SESSION_ID. For long-running automations, use a refresh token flow.
- `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 each Salesforce opportunity stage change alert.
 
## Block Kit JSON
 
```json
{
  "channel": "<SLACK_CHANNEL_ID>",
  "text": "Deal stage changed: <opportunity_name>",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": ":arrows_counterclockwise: *Deal Stage Changed*\n*<opportunity_name>* is now in *<stage_name>*\nAmount: $<amount>"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "<<salesforce_link>|View in Salesforce>"
        }
      ]
    }
  ]
}
```
 
## Notes
 
- The top-level `text` field is required by the Slack API as a fallback for notifications and accessibility.
- The Salesforce record link format: `<SALESFORCE_INSTANCE_URL>/<OPPORTUNITY_ID>`.
- Format the amount with comma separators (e.g., $120,000 not $120000).
- To customize, you can add fields like account name, owner, or close date.

# Salesforce Opportunities API Reference
 
## Query recently modified opportunities
 
Use SOQL via the REST API to find opportunities modified within a time window.
 
**Request:**
 
```
GET <SALESFORCE_INSTANCE_URL>/services/data/v59.0/query
Authorization: Bearer <SALESFORCE_ACCESS_TOKEN>
```
 
**Query parameter:**
 
```
q=SELECT Id, Name, Amount, StageName, LastModifiedDate FROM Opportunity WHERE LastModifiedDate > LAST_N_HOURS:1 AND StageName != null
```
 
- `LAST_N_HOURS:1` is a SOQL date literal meaning "within the last 1 hour." Adjust the number for different lookback windows (e.g., `LAST_N_HOURS:4`, `LAST_N_DAYS:1`).
- URL-encode the SOQL query when passing as a query parameter.
 
**Response shape:**
 
```json
{
  "totalSize": 3,
  "done": true,
  "records": [
    {
      "attributes": {
        "type": "Opportunity",
        "url": "/services/data/v59.0/sobjects/Opportunity/006XXXXXXXXXXXXXXX"
      },
      "Id": "006XXXXXXXXXXXXXXX",
      "Name": "Pinnacle Health Data Migration",
      "Amount": 120000,
      "StageName": "Proposal/Price Quote",
      "LastModifiedDate": "2026-03-05T14:30:00.000+0000"
    }
  ]
}
```
 
## Additional useful fields
 
To include account and owner details, expand the SOQL query:
 
```sql
SELECT Id, Name, Amount, StageName, Account.Name, Owner.Name,
       CloseDate, LastModifiedDate
FROM Opportunity
WHERE LastModifiedDate > LAST_N_HOURS:1 AND StageName != null
```
 
## Notes
 
- Salesforce stores stage names as human-readable text on `StageName`, not internal IDs. No mapping is needed.
- `Amount` is a number (not a string). It may be null if the amount hasn't been set.
- The `done` field indicates whether all results are returned. If `done` is `false`, use the `nextRecordsUrl` to fetch additional pages.
- Salesforce access tokens expire based on session timeout settings. A 401 response with `INVALID_SESSION_ID` means the token has expired.

/sf-deal-stage-alerts

Checking for opportunities modified in the last 1 hour(s)...
  Found 3 modified opportunity(ies)
  Posted: Pinnacle Health Data Migration → Proposal/Price Quote
  Posted: Contoso Platform Expansion → Negotiation/Review
  Posted: Acme Corp Annual Renewal → Closed Won
Done. Posted 3 alert(s) to Slack.
Note: LastModifiedDate updates on any field change, so some alerts
may be for non-stage modifications.

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

name: Salesforce 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 /sf-deal-stage-alerts"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          SALESFORCE_INSTANCE_URL: ${{ secrets.SALESFORCE_INSTANCE_URL }}
          SALESFORCE_ACCESS_TOKEN: ${{ secrets.SALESFORCE_ACCESS_TOKEN }}
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
          SLACK_CHANNEL_ID: ${{ secrets.SLACK_CHANNEL_ID }}