Flag HubSpot deals with missing fields and Slack the rep using a Claude Code skill

mkdir -p .claude/skills/missing-deal-fields/{templates,references}

.claude/skills/missing-deal-fields/
├── SKILL.md                                # workflow guidelines + config
├── templates/
│   └── slack-missing-fields-alert.md      # Block Kit template for Slack DMs
└── references/
    └── hubspot-deals-search-api.md        # HubSpot API patterns for deal field auditing

---
name: missing-deal-fields
description: Find HubSpot deals missing required fields (close date, amount) and DM each deal owner in Slack with a list of deals to fix
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Search for active deals in HubSpot that are missing required fields, group them by owner, and send each owner a Slack DM listing their incomplete deals with direct links to fix them.
 
## Configuration
 
Read these environment variables:
 
- `HUBSPOT_ACCESS_TOKEN` — HubSpot private app token (required)
- `HUBSPOT_PORTAL_ID` — HubSpot portal ID for building deal links (required)
- `SLACK_BOT_TOKEN` — Slack bot token starting with xoxb- (required)
 
Default required fields: `closedate`, `amount`. The user may request additional fields.
 
Owner-to-Slack mapping: The agent needs a way to map HubSpot owner IDs to Slack user IDs. Check for an `owner_map.json` file in the skill directory first. If not found, fetch the Slack users list and HubSpot owners list and match by email address.
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. For each required field, search HubSpot for active deals where that field has not been set. See `references/hubspot-deals-search-api.md` for the endpoint and filter syntax.
3. Deduplicate deals across searches (a deal missing both close date and amount appears in both results). Track which specific fields each deal is missing.
4. Group deals by `hubspot_owner_id`.
5. Resolve owner IDs to Slack user IDs using owner_map.json or by matching HubSpot owner emails to Slack user emails.
6. Send each owner a Slack DM using the format in `templates/slack-missing-fields-alert.md`.
7. Print a summary: total deals flagged, owners notified, and any owners without a Slack mapping.
 
## Important notes
 
- HubSpot's Search API applies AND logic within a filter group. You CANNOT combine multiple `NOT_HAS_PROPERTY` filters with OR in a single query. Run one search per field and merge results.
- `NOT_HAS_PROPERTY` only matches properties that were never set. If a field was set and then cleared, HubSpot may store it as an empty string. Consider also searching for `EQ` with empty string value.
- Exclude closed deals (`dealstage NOT_IN closedwon, closedlost`) from the search.
- Deal links follow the format: `https://app.hubspot.com/contacts/PORTAL_ID/deal/DEAL_ID`
- Slack user IDs start with U (not W). The bot must have chat:write scope to DM users.
- Use the `requests` library for HTTP calls and `slack_sdk` for Slack. Install them with pip if needed.

# Slack Missing Fields Alert Template
 
Use this Block Kit structure when DMing a deal owner about missing fields.
 
## Block Kit JSON
 
```json
{
  "channel": "<SLACK_USER_ID>",
  "text": "Missing deal fields: <count> deals",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "🔍 Missing Deal Fields (<count> deals)"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "<deal_lines>"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "Please update these deals today so forecasting stays accurate."
        }
      ]
    }
  ]
}
```
 
## Deal line format
 
Each deal line: `- <https://app.hubspot.com/contacts/PORTAL_ID/deal/DEAL_ID|Deal Name> — missing *close date, amount*`
 
## Notes
 
- The top-level `text` field is required by Slack as a fallback for notifications.
- Bold the missing field names with asterisks (Slack mrkdwn).
- If a deal is missing multiple fields, join them with commas.
- Use singular "1 deal" when count is 1.
- Sort deals alphabetically by name within each owner's message.

# HubSpot Deals Search API Reference — Missing Fields
 
## Search for deals missing a property
 
Use `NOT_HAS_PROPERTY` to find deals where a field has never been set.
 
**Request:**
 
```
POST https://api.hubapi.com/crm/v3/objects/deals/search
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
**Body (missing close date):**
 
```json
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "closedate",
          "operator": "NOT_HAS_PROPERTY"
        },
        {
          "propertyName": "dealstage",
          "operator": "NOT_IN",
          "values": ["closedwon", "closedlost"]
        }
      ]
    }
  ],
  "properties": ["dealname", "amount", "closedate", "dealstage", "hubspot_owner_id"],
  "limit": 100
}
```
 
**Body (missing amount):**
 
Same structure, but swap `closedate` for `amount` in the `NOT_HAS_PROPERTY` filter.
 
### Important: AND-only logic
 
HubSpot's Search API applies AND logic within a filter group. You CANNOT combine `closedate NOT_HAS_PROPERTY OR amount NOT_HAS_PROPERTY` in a single query. Run one search per field and merge results client-side.
 
### Catching cleared fields
 
`NOT_HAS_PROPERTY` only matches properties that were never set. If a rep entered a value and then cleared it, HubSpot may store an empty string. To catch both cases, add a second filter group:
 
```json
{
  "filterGroups": [
    {
      "filters": [
        { "propertyName": "closedate", "operator": "NOT_HAS_PROPERTY" },
        { "propertyName": "dealstage", "operator": "NOT_IN", "values": ["closedwon", "closedlost"] }
      ]
    },
    {
      "filters": [
        { "propertyName": "closedate", "operator": "EQ", "value": "" },
        { "propertyName": "dealstage", "operator": "NOT_IN", "values": ["closedwon", "closedlost"] }
      ]
    }
  ],
  "properties": ["dealname", "amount", "closedate", "dealstage", "hubspot_owner_id"],
  "limit": 100
}
```
 
Multiple filter groups are combined with OR logic.
 
**Response shape:**
 
```json
{
  "total": 8,
  "results": [
    {
      "id": "12345",
      "properties": {
        "dealname": "Acme Corp Expansion",
        "amount": null,
        "closedate": null,
        "dealstage": "qualifiedtobuy",
        "hubspot_owner_id": "67890"
      }
    }
  ],
  "paging": {
    "next": { "after": "100" }
  }
}
```
 
- `limit` max is 100. Use `paging.next.after` to paginate.
- Properties that have never been set return `null`.
 
## Get deal owners
 
Map HubSpot owner IDs to names and emails (for matching to Slack users).
 
**Request:**
 
```
GET https://api.hubapi.com/crm/v3/owners
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
```
 
**Response shape:**
 
```json
{
  "results": [
    {
      "id": "67890",
      "email": "jane@company.com",
      "firstName": "Jane",
      "lastName": "Smith"
    }
  ]
}
```
 
Use the owner's email to match against Slack users, or maintain a static `owner_map.json` mapping owner IDs to Slack user IDs.

{
  "12345678": "U0XXXXXXXXX",
  "87654321": "U0YYYYYYYYY"
}

/missing-deal-fields

Searching for deals missing close date... found 6
Searching for deals missing amount... found 4
After deduplication: 8 deals with missing fields
 
Grouped by owner:
  Jane Smith (3 deals): Acme Corp Expansion, Globex New Business, Initech Platform Deal
  Bob Jones (2 deals): Umbrella Renewal, Stark Industries Upgrade
  Unassigned (3 deals): skipped (no Slack mapping)
 
Sending Slack DMs...
  Notified Jane Smith about 3 deals
  Notified Bob Jones about 2 deals
 
Done. 8 deals flagged, 2 owners notified, 3 deals skipped (unassigned).

# Run every weekday at 7 AM
0 7 * * 1-5 cd /path/to/your/project && claude -p "Run /missing-deal-fields" --allowedTools 'Bash(*)' 'Read(*)'

name: Daily Missing Deal Fields Audit
on:
  schedule:
    - cron: '0 12 * * 1-5'  # 7 AM ET = 12 PM UTC, weekdays only
  workflow_dispatch: {}
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /missing-deal-fields"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          HUBSPOT_ACCESS_TOKEN: ${{ secrets.HUBSPOT_ACCESS_TOKEN }}
          HUBSPOT_PORTAL_ID: ${{ secrets.HUBSPOT_PORTAL_ID }}
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}