Audit and rebalance Salesforce lead assignments using a Claude Code skill

mkdir -p .claude/skills/rebalance-sf-leads/{templates,references}

---
name: rebalance-sf-leads
description: Audit and rebalance Salesforce lead assignments across the sales team. Queries recent leads, reports distribution, and optionally redistributes evenly with Slack notifications.
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Workflow
 
1. Read `references/salesforce-api.md` for SOQL query and sObject update patterns
2. Read `references/slack-api.md` for posting rebalance notifications
3. Read `templates/rep-roster.md` for the team roster with Salesforce and Slack IDs
4. Query Salesforce for Leads created in the requested time window (default: last 7 days), filtered to reps in the roster
5. Group leads by OwnerId and count per rep
6. Report the current distribution: leads per rep, ideal per rep, and max imbalance
7. If the user asks to rebalance, redistribute leads evenly using round-robin across the roster
8. PATCH each reassigned Lead's OwnerId in Salesforce
9. Post a summary to Slack (#sales-ops) and DM each rep with their updated lead list
10. Print final distribution
 
## Rules
 
- Default to audit-only mode — show the distribution without making changes
- Only rebalance when the user explicitly asks
- Skip leads not assigned to reps in the roster (e.g., queue-owned leads)
- Rate limit: 200ms between Salesforce PATCH calls to stay within API limits
- If SLACK_BOT_TOKEN is not set, skip Slack notifications
- Use environment variables: SALESFORCE_INSTANCE_URL, SALESFORCE_ACCESS_TOKEN, SLACK_BOT_TOKEN

# Salesforce REST API Reference
 
## Query records with SOQL
 
```
GET {SALESFORCE_INSTANCE_URL}/services/data/v59.0/query?q={SOQL}
Authorization: Bearer {SALESFORCE_ACCESS_TOKEN}
```
 
Example SOQL — find recent leads assigned to specific reps:
```sql
SELECT Id, Name, Email, Company, OwnerId, CreatedDate
FROM Lead
WHERE CreatedDate >= 2024-01-01T00:00:00Z
AND OwnerId IN ('005xx0000012345','005xx0000023456')
ORDER BY CreatedDate ASC
```
 
Response:
```json
{
  "totalSize": 84,
  "records": [
    {
      "Id": "00Q5e000001abc",
      "Name": "Jane Smith",
      "Email": "jane@acme.com",
      "Company": "Acme Inc",
      "OwnerId": "005xx0000012345",
      "CreatedDate": "2024-01-15T14:30:00.000+0000"
    }
  ]
}
```
 
## Update a Lead
 
```
PATCH {SALESFORCE_INSTANCE_URL}/services/data/v59.0/sobjects/Lead/{LeadId}
Authorization: Bearer {SALESFORCE_ACCESS_TOKEN}
Content-Type: application/json
```
 
Request body:
```json
{
  "OwnerId": "005xx0000023456"
}
```
 
Successful response: HTTP 204 No Content.
 
Notes:
- OwnerId accepts both User IDs (005...) and Queue IDs (00G...)
- Access token expires per session timeout. Use refresh tokens for scheduled runs
- SOQL strings must be URL-encoded when passed as query params
- Salesforce enforces 15,000 API calls per 24-hour period on Enterprise Edition

# Slack API Reference
 
## Post a message
 
```
POST https://slack.com/api/chat.postMessage
Authorization: Bearer {SLACK_BOT_TOKEN}
Content-Type: application/json
```
 
Request body (channel message):
```json
{
  "channel": "#sales-ops",
  "text": "Lead rebalance complete — 84 leads redistributed",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Lead Rebalance Complete*\n84 leads redistributed across 4 reps:\n\n*Alice*: 21 leads\n*Bob*: 21 leads\n*Carol*: 21 leads\n*Dave*: 21 leads"
      }
    }
  ]
}
```
 
Request body (DM to a user):
```json
{
  "channel": "U01AAAA",
  "text": "Your leads have been rebalanced — you now have 21 leads"
}
```
 
Notes:
- To DM a user, set `channel` to their Slack User ID (starts with U)
- The bot must have `chat:write` scope
- The bot must be added to the target channel for channel messages
- `text` is the fallback shown in notifications; `blocks` render in the Slack client

# Rep Roster
 
Replace the placeholder IDs below with your actual Salesforce User IDs and Slack User IDs.
 
| Name | Salesforce User ID | Slack User ID | Active |
|------|-------------------|---------------|--------|
| Alice Smith | 005xx0000012345 | U01AAAA | yes |
| Bob Jones | 005xx0000023456 | U02BBBB | yes |
| Carol Chen | 005xx0000034567 | U03CCCC | yes |
| Dave Kim | 005xx0000045678 | U04DDDD | yes |
 
## How to find IDs
 
- **Salesforce User ID**: Setup → Users → click a user → the 18-character ID is in the URL (starts with `005`)
- **Slack User ID**: Click a user's profile in Slack → More → Copy member ID (starts with `U`)
 
## Rules
 
1. Only include reps who should receive leads in the rotation
2. Set Active to "no" for reps who are out of office — the agent will skip them
3. The rebalance distributes leads evenly across all active reps

# In Claude Code
/rebalance-sf-leads

# Audit every Monday morning (report only, no rebalance)
0 9 * * 1 cd /path/to/project && claude -p "Run /rebalance-sf-leads — show lead distribution for the last 7 days." --allowedTools 'Bash,Read' 2>&1 >> /var/log/sf-rebalance.log

name: Salesforce Lead Distribution Audit
on:
  schedule:
    - cron: '0 14 * * 1'  # 9 AM ET Monday = 2 PM UTC
  workflow_dispatch: {}
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /rebalance-sf-leads — show lead distribution for the last 7 days."
          allowed_tools: "Bash,Read"
        env:
          SALESFORCE_INSTANCE_URL: ${{ secrets.SALESFORCE_INSTANCE_URL }}
          SALESFORCE_ACCESS_TOKEN: ${{ secrets.SALESFORCE_ACCESS_TOKEN }}
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}