Post a daily Slack leaderboard of rep activity from HubSpot using a Claude Code skill

mkdir -p .claude/skills/rep-leaderboard/{templates,references}

.claude/skills/rep-leaderboard/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── slack-leaderboard.md          # Block Kit template for Slack messages
└── references/
    └── hubspot-engagements-api.md    # HubSpot API patterns

---
name: rep-leaderboard
description: Generate a daily rep activity leaderboard from HubSpot and post it to Slack
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Fetch yesterday's rep activity (calls, emails, meetings) from HubSpot, rank reps by total activity, and post a formatted leaderboard to Slack.
 
## 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)
 
Default lookback window: 1 day (yesterday midnight to today midnight UTC). 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 the owner roster from HubSpot to build an owner ID → display name map. See `references/hubspot-engagements-api.md` for the endpoint.
3. Compute yesterday's midnight-to-midnight UTC timestamp range in milliseconds.
4. Search for calls, emails, and meetings logged yesterday using the HubSpot CRM Search API. See `references/hubspot-engagements-api.md` for request and response formats.
5. Aggregate per-owner counts across all three activity types. Rank by total descending.
6. Post a leaderboard to Slack using the Block Kit format in `templates/slack-leaderboard.md`. Assign medal emojis to the top 3.
7. Print a summary of how many reps were ranked and the leaderboard posted.
 
## Important notes
 
- HubSpot engagement objects use `hs_timestamp` for the activity date, not `createdate`. Filter on `hs_timestamp` for accurate date matching.
- Timestamps must be in Unix **milliseconds** (13 digits). Passing seconds (10 digits) returns zero results with no error.
- Activities without a `hubspot_owner_id` should be excluded from the ranking.
- The Search API returns max 100 results per request. Use the `after` cursor from `paging.next.after` to paginate if needed.
- The Search API rate limit is 5 requests per second. Add a small delay between searches if needed.
- Use the `requests` library for HTTP calls and `slack_sdk` for Slack. Install them with pip if needed.

# Slack Leaderboard Template
 
Use this Block Kit structure for the daily rep activity leaderboard.
 
## Block Kit JSON
 
```json
{
  "channel": "<SLACK_CHANNEL_ID>",
  "text": "Rep Activity Leaderboard",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "🏆 Rep Activity Leaderboard"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "Activity for <date_string>"
        }
      ]
    },
    {
      "type": "divider"
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "<ranked_lines>"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "C = Calls | E = Emails | M = Meetings"
        }
      ]
    }
  ]
}
```
 
## Ranking format
 
Each rep line should follow this format:
- Top 3: `🥇 *Name* — X activities (YC ZE WM)`
- Others: `4. *Name* — X activities (YC ZE WM)`
 
Where C = calls, E = emails, M = meetings.
 
## Notes
 
- The top-level `text` field is required by Slack as a fallback for notifications.
- To customize, you can add team totals, weighted scores, or trend indicators.

# HubSpot Engagements API Reference
 
## Get owners
 
Build an owner ID → display name map for the leaderboard.
 
**Request:**
 
```
GET https://api.hubapi.com/crm/v3/owners?limit=100
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
```
 
**Response shape:**
 
```json
{
  "results": [
    {
      "id": "12345",
      "email": "sarah@example.com",
      "firstName": "Sarah",
      "lastName": "Chen"
    }
  ]
}
```
 
Build the name as `firstName + " " + lastName`. Fall back to `email` if both are empty.
 
## Search for engagements
 
Use the CRM Search API to find calls, emails, or meetings within a time range.
 
**Request:**
 
```
POST https://api.hubapi.com/crm/v3/objects/<object_type>/search
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
Where `<object_type>` is one of: `calls`, `emails`, `meetings`.
 
**Body:**
 
```json
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "hs_timestamp",
          "operator": "GTE",
          "value": "<start_timestamp_ms>"
        },
        {
          "propertyName": "hs_timestamp",
          "operator": "LT",
          "value": "<end_timestamp_ms>"
        }
      ]
    }
  ],
  "properties": ["hs_timestamp", "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` to paginate.
 
**Response shape:**
 
```json
{
  "total": 15,
  "results": [
    {
      "id": "67890",
      "properties": {
        "hs_timestamp": "2026-03-04T14:30:00.000Z",
        "hubspot_owner_id": "12345"
      }
    }
  ],
  "paging": {
    "next": {
      "after": "100"
    }
  }
}
```

/rep-leaderboard

Fetching owners... found 8 reps
Fetching yesterday's activities...
  Found: 42 calls, 67 emails, 12 meetings
Posting leaderboard to Slack...
Done. Posted leaderboard with 8 reps ranked.

# Run every weekday at 8 AM
0 8 * * 1-5 cd /path/to/your/project && claude -p "Run /rep-leaderboard" --allowedTools 'Bash(*)' 'Read(*)'

name: Daily Rep Leaderboard
on:
  schedule:
    - cron: '0 13 * * 1-5'  # 8 AM ET = 1 PM UTC, weekdays only
  workflow_dispatch: {}
jobs:
  leaderboard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /rep-leaderboard"
          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 }}