Audit and rebalance Pipedrive deal assignments using a Claude Code skill

mkdir -p .claude/skills/pd-deal-routing/{templates,references}

.claude/skills/pd-deal-routing/
├── SKILL.md
├── references/
│   └── pipedrive-deals-api.md
└── templates/
    └── slack-assignment.md

---
name: pd-deal-routing
description: Audit and rebalance Pipedrive deal assignments across the sales team using round-robin logic with Slack notifications.
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Audit deal distribution across the sales team in Pipedrive and optionally rebalance assignments using round-robin. For each reassigned deal, update the owner in Pipedrive and notify the rep via Slack.
 
## Configuration
 
Read these environment variables:
 
- `PIPEDRIVE_API_TOKEN` — Pipedrive API token from Settings > Personal > Tools and Integrations > API (required)
- `PIPEDRIVE_COMPANY_DOMAIN` — your Pipedrive subdomain, e.g. "yourcompany" from yourcompany.pipedrive.com (required)
- `SLACK_BOT_TOKEN` — Slack bot token starting with xoxb- (required for notifications, skip if not set)
- `SLACK_CHANNEL_ID` — Slack channel ID starting with C (required for channel summary)
 
Default scope: all open deals. The user may request a different filter (e.g., deals created this week, deals in a specific pipeline, unassigned deals only).
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Fetch active team members from Pipedrive (GET /v1/users, filter by active_flag=1). See `references/pipedrive-deals-api.md`.
3. Query deals to audit or reassign based on the user's request. See `references/pipedrive-deals-api.md`.
4. Apply round-robin assignment or show distribution analysis. Default to audit-only — show counts per rep, ideal distribution, and max imbalance.
5. For each reassigned deal, update owner via PUT /v1/deals/{id} with the new owner_id, then notify the rep via Slack using the format in `templates/slack-assignment.md`.
6. Print a summary of assignments made (or distribution audit if no changes requested).
 
## Important notes
 
- Default to audit-only mode — show the distribution without making changes. Only rebalance when the user explicitly asks.
- Deal owner is updated via `PUT /v1/deals/{id}` with the `owner_id` field in the request body.
- GET /v1/users returns all Pipedrive users. Filter by `active_flag=1` to exclude deactivated accounts.
- The API token does not expire (unlike OAuth tokens). It remains valid until regenerated in Pipedrive settings.
- `SLACK_CHANNEL_ID` must be the channel ID (starts with `C`), not the channel name. The bot must be invited to the channel.
- If `SLACK_BOT_TOKEN` is not set, skip Slack notifications and only print results to the terminal.
- Use `urllib.request` for HTTP calls (no external dependencies required).
- Rate limit: add 200ms delay between Pipedrive API calls to stay within burst limits (2-second rolling window).
- Stage IDs are numeric. Resolve them via /v1/stages if you need human-readable stage names in output.

# Pipedrive Deals & Users API Reference
 
## List active users
 
Fetch all users in the Pipedrive account. Filter by `active_flag` to get only active team members.
 
**Request:**
 
```
GET https://api.pipedrive.com/v1/users?api_token=<PIPEDRIVE_API_TOKEN>
```
 
**Response shape:**
 
```json
{
  "success": true,
  "data": [
    {
      "id": 12345,
      "name": "Marcus Johnson",
      "email": "marcus@example.com",
      "active_flag": true
    },
    {
      "id": 23456,
      "name": "Sarah Chen",
      "email": "sarah@example.com",
      "active_flag": true
    }
  ]
}
```
 
Filter to `active_flag: true` only. The `id` field is used as `owner_id` when assigning deals.
 
## List deals
 
Fetch deals with optional filters for status, pipeline, user, and stage.
 
**Request:**
 
```
GET https://api.pipedrive.com/v1/deals?api_token=<PIPEDRIVE_API_TOKEN>&status=open&start=0&limit=500
```
 
**Optional query parameters:**
 
- `status` — filter by deal status: `open`, `won`, `lost`, `deleted` (default: all)
- `user_id` — filter by deal owner
- `stage_id` — filter by pipeline stage
- `start` — pagination offset (default: 0)
- `limit` — page size (max 500)
 
**Response shape:**
 
```json
{
  "success": true,
  "data": [
    {
      "id": 98765,
      "title": "Northwind Traders — Enterprise Platform",
      "value": 42000,
      "currency": "USD",
      "status": "open",
      "stage_id": 3,
      "pipeline_id": 1,
      "user_id": {
        "id": 12345,
        "name": "Marcus Johnson",
        "email": "marcus@example.com"
      },
      "org_id": {
        "name": "Northwind Traders",
        "value": 11111
      },
      "person_id": {
        "name": "Elena Ruiz",
        "value": 54321
      },
      "add_time": "2026-03-01 10:30:00",
      "update_time": "2026-03-05 14:15:00",
      "expected_close_date": "2026-04-15"
    }
  ],
  "additional_data": {
    "pagination": {
      "start": 0,
      "limit": 500,
      "more_items_in_collection": false,
      "next_start": 500
    }
  }
}
```
 
Notes:
- `user_id` is an object containing the owner's `id`, `name`, and `email`. Use `user_id.id` for the numeric owner ID.
- If `more_items_in_collection` is `true`, fetch the next page with `start=<next_start>`.
- To find unassigned deals, look for deals where `user_id` is null or matches a queue/default user.
- `value` is a number. It may be null if no deal value is set.
 
## Update a deal (change owner)
 
**Request:**
 
```
PUT https://api.pipedrive.com/v1/deals/{deal_id}?api_token=<PIPEDRIVE_API_TOKEN>
Content-Type: application/json
```
 
**Body:**
 
```json
{
  "owner_id": 23456
}
```
 
**Response shape:**
 
```json
{
  "success": true,
  "data": {
    "id": 98765,
    "title": "Northwind Traders — Enterprise Platform",
    "user_id": {
      "id": 23456,
      "name": "Sarah Chen"
    }
  }
}
```
 
Notes:
- `owner_id` accepts a Pipedrive user ID (numeric, from the /v1/users endpoint).
- A successful update returns `"success": true` with the updated deal object.
- Rate limit: token-based daily budget (30,000 base tokens x plan multiplier x seats). A single update costs 1 token. Add 200ms between calls to avoid burst limits.
 
## Fetch pipeline stages
 
Resolve numeric stage IDs to human-readable names.
 
**Request:**
 
```
GET https://api.pipedrive.com/v1/stages?api_token=<PIPEDRIVE_API_TOKEN>
```
 
**Response shape:**
 
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Qualified Lead",
      "pipeline_id": 1,
      "order_nr": 1
    },
    {
      "id": 2,
      "name": "Discovery",
      "pipeline_id": 1,
      "order_nr": 2
    }
  ]
}
```
 
Build a dictionary mapping `id` to `name` for display purposes.

# Slack Assignment Notification Template
 
Use this Block Kit structure when notifying a rep about a newly assigned deal.
 
## Block Kit JSON (per-deal notification)
 
```json
{
  "channel": "<SLACK_CHANNEL_ID>",
  "text": "New deal assigned: <deal_title>",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": ":round_pushpin: *Deal Assigned to You*\n*<deal_title>*\nValue: $<deal_value>\nStage: <stage_name>"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "<<pipedrive_link>|View in Pipedrive>"
        }
      ]
    }
  ]
}
```
 
## Block Kit JSON (channel summary after rebalance)
 
```json
{
  "channel": "<SLACK_CHANNEL_ID>",
  "text": "Deal rebalance complete",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": ":arrows_counterclockwise: *Deal Rebalance Complete*\n<count> deals redistributed across <rep_count> reps:\n\n<per_rep_summary>"
      }
    }
  ]
}
```
 
## Notes
 
- The top-level `text` field is required by the Slack API as a fallback for notifications and accessibility.
- The Pipedrive deal link format: `https://<PIPEDRIVE_COMPANY_DOMAIN>.pipedrive.com/deal/<DEAL_ID>`.
- Format the value with comma separators (e.g., $42,000 not $42000). Display "N/A" if value is null.
- To post to a channel, use `SLACK_CHANNEL_ID`. To DM a user, set `channel` to their Slack User ID (starts with U).
- The bot must have `chat:write` scope and be invited to the target channel.
- Post the per-deal notification to the channel. If you have Slack User IDs for reps, DM each rep their assigned deals.

/pd-deal-routing

Checking deal distribution for open deals...
  Fetched 5 active users
  Found 47 open deals
 
  Distribution:
    Marcus Johnson:  14 deals (30%)
    Sarah Chen:       4 deals  (9%)
    Alex Rivera:     12 deals (26%)
    Jordan Lee:      11 deals (23%)
    Priya Patel:      6 deals (13%)
 
  Ideal per rep: 9.4
  Max imbalance: Marcus Johnson (+4.6 above average)
 
  No changes made. Ask me to rebalance if you'd like to redistribute.

# Audit every Monday morning (report only, no rebalance)
0 9 * * 1 cd /path/to/your/project && claude -p "Run /pd-deal-routing — show deal distribution for the last 7 days." --allowedTools 'Bash(*)' 'Read(*)'

name: Pipedrive Deal 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 /pd-deal-routing — show deal distribution for the last 7 days."
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          PIPEDRIVE_API_TOKEN: ${{ secrets.PIPEDRIVE_API_TOKEN }}
          PIPEDRIVE_COMPANY_DOMAIN: ${{ secrets.PIPEDRIVE_COMPANY_DOMAIN }}
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
          SLACK_CHANNEL_ID: ${{ secrets.SLACK_CHANNEL_ID }}