Check for large Salesforce deals using a Claude Code skill

mkdir -p .claude/skills/large-sf-deal-alert/{templates,references}

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

---
name: large-sf-deal-alert
description: Check for recently created large Salesforce opportunities and post alerts to Slack
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Check for Salesforce opportunities created in a given time window (default: today) with Amount >= $50,000 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 time window: today (CreatedDate = TODAY). The user may request a different window or threshold.
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Query Salesforce for opportunities created in the time window with Amount >= threshold 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
 
- The default SOQL uses `CreatedDate = TODAY` which returns opportunities created in the current UTC day. Adjust for the user's timezone if they ask.
- 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`.
- `Amount` may be null if the amount hasn't been set on the Opportunity. Filter these out.
- Use `urllib.request` for HTTP calls (no external dependencies required).

# Slack Alert Template
 
Use this Block Kit structure for each large Salesforce opportunity alert.
 
## Block Kit JSON
 
```json
{
  "channel": "<SLACK_CHANNEL_ID>",
  "text": "New large opportunity: <opportunity_name>",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": ":dart: *New Large Opportunity*\n*<opportunity_name>*\nAmount: $<amount>\nStage: <stage_name>\nOwner: <owner_name>\nAccount: <account_name>"
      }
    },
    {
      "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>/lightning/r/Opportunity/<OPPORTUNITY_ID>/view`.
- Format the amount with comma separators (e.g., $175,000 not $175000).
- To customize, you can add fields like close date, created date, or probability.

# Salesforce Opportunities API Reference
 
## Query large opportunities created today
 
Use SOQL via the REST API to find opportunities matching the criteria.
 
**Request:**
 
```
GET <SALESFORCE_INSTANCE_URL>/services/data/v59.0/query
Authorization: Bearer <SALESFORCE_ACCESS_TOKEN>
```
 
**Query parameter:**
 
```
q=SELECT Id, Name, Amount, StageName, Account.Name, Owner.Name, CreatedDate FROM Opportunity WHERE CreatedDate = TODAY AND Amount >= 50000
```
 
- `TODAY` is a SOQL date literal meaning the current UTC day. Other options: `YESTERDAY`, `LAST_N_DAYS:7`, `THIS_WEEK`.
- URL-encode the SOQL query when passing as a query parameter.
- Adjust the Amount threshold as needed (e.g., 100000 for $100K).
 
**Response shape:**
 
```json
{
  "totalSize": 2,
  "done": true,
  "records": [
    {
      "attributes": {
        "type": "Opportunity",
        "url": "/services/data/v59.0/sobjects/Opportunity/006XXXXXXXXXXXXXXX"
      },
      "Id": "006XXXXXXXXXXXXXXX",
      "Name": "NovaTech Cloud Infrastructure",
      "Amount": 175000,
      "StageName": "Prospecting",
      "Account": {
        "attributes": { "type": "Account" },
        "Name": "NovaTech Industries"
      },
      "Owner": {
        "attributes": { "type": "User" },
        "Name": "Rachel Nguyen"
      },
      "CreatedDate": "2026-03-05T10:30:00.000+0000"
    }
  ]
}
```
 
## Additional useful fields
 
To include close date or probability, expand the SOQL query:
 
```sql
SELECT Id, Name, Amount, StageName, Account.Name, Owner.Name,
       CloseDate, Probability, CreatedDate
FROM Opportunity
WHERE CreatedDate = TODAY AND Amount >= 50000
```
 
## 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.
- Account and Owner are relationship fields — access nested Name via `record["Account"]["Name"]` and `record["Owner"]["Name"]`. Either may be null.

/large-sf-deal-alert

Checking for large opportunities created today...
  Found 2 opportunity(ies) over $50K
  Posted: NovaTech Cloud Infrastructure — $175,000
  Posted: Meridian Systems Platform License — $92,000
Done. Posted 2 alert(s) to Slack.

# Run daily at 5 PM to catch the day's large deals
0 17 * * * cd /path/to/your/project && claude -p "Run /large-sf-deal-alert" --allowedTools 'Bash(*)' 'Read(*)'

name: Large Salesforce Deal Alerts
on:
  schedule:
    - cron: '0 17 * * 1-5'  # Weekdays at 5 PM UTC
  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 /large-sf-deal-alert"
          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 }}