Auto-triage and tag Zendesk tickets using a Claude Code skill

mkdir -p .claude/skills/zendesk-triage/{templates,references}

.claude/skills/zendesk-triage/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── classification-prompt.md      # Prompt template for ticket classification
└── references/
    └── zendesk-tickets-api.md        # Zendesk search, update, and groups API patterns

---
name: zendesk-triage
description: Classify untagged Zendesk tickets by topic using Claude and apply tags and group assignments
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Fetch untagged open tickets from Zendesk, classify each by topic using Claude (claude-haiku-4-5), and update each ticket with the appropriate topic tag and support group assignment.
 
## Configuration
 
Read these environment variables:
 
- `ZENDESK_SUBDOMAIN` — Zendesk subdomain, e.g. "acme" for acme.zendesk.com (required)
- `ZENDESK_EMAIL` — Zendesk agent email for API auth (required)
- `ZENDESK_API_TOKEN` — Zendesk API token (required)
- `ANTHROPIC_API_KEY` — Anthropic API key for classification (required)
 
Default batch size: 50 tickets per run. The user may request a different size.
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Fetch Zendesk groups to build a group name → group ID map. See `references/zendesk-tickets-api.md`.
3. Search for open tickets that don't have any topic tag. See `references/zendesk-tickets-api.md` for the search query and response format.
4. For each untagged ticket, classify it using Claude with the prompt in `templates/classification-prompt.md`. Use claude-haiku-4-5 with max_tokens=20.
5. Map the classification label to a topic tag and group. Update the ticket via the Zendesk API with the tag and group assignment. See `references/zendesk-tickets-api.md`.
6. Print a summary of how many tickets were classified and the breakdown by topic.
 
## Important notes
 
- The classification prompt returns one of: BILLING, SHIPPING, PRODUCT, ACCOUNT, TECHNICAL, OTHER. Map these to tags: topic-billing, topic-shipping, etc.
- Authentication uses Basic Auth with `email/token:api_token` format. The `/token` suffix after the email is required.
- The Anthropic SDK (`anthropic` pip package) is required. Install it with `pip install anthropic` if not present.
- The Zendesk PUT endpoint replaces the entire tags array. Merge new tags with existing tags before updating.
- Group names must match exactly what's configured in Zendesk (Admin Center > People > Groups). The script should fetch groups dynamically rather than hardcoding IDs.
- Use only Python standard library for Zendesk API calls (`urllib.request`, `json`, `base64`). Use the `anthropic` package for classification.

# Zendesk Tickets API Reference
 
## Authentication
 
All Zendesk API requests use Basic Auth. The username is `email/token:api_token` (note the `/token` suffix after the email address).
 
```
Authorization: Basic base64(email/token:api_token)
```
 
Base URL: `https://{subdomain}.zendesk.com/api/v2`
 
## Search for untagged open tickets
 
Find tickets that don't have any topic tag assigned yet.
 
**Request:**
 
```
GET https://{subdomain}.zendesk.com/api/v2/search.json?query=type:ticket status:open -tags:topic-billing -tags:topic-shipping -tags:topic-product -tags:topic-account -tags:topic-technical -tags:topic-uncategorized&per_page=50
Authorization: Basic <credentials>
```
 
**Parameters:**
 
- `query` — URL-encoded search string. `-tags:topic-billing` excludes tickets with that tag.
- `per_page` — results per page (max 100)
 
**Response shape:**
 
```json
{
  "results": [
    {
      "id": 48291,
      "subject": "Can't log into my account",
      "description": "I've been trying to reset my password but the link expired...",
      "tags": [],
      "status": "open",
      "group_id": null,
      "requester_id": 67890
    }
  ],
  "count": 23
}
```
 
Note: The Zendesk Search API has a 1-2 minute indexing delay. Newly created tickets may not appear immediately.
 
## Update a ticket (add tags and group)
 
**Request:**
 
```
PUT https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}.json
Authorization: Basic <credentials>
Content-Type: application/json
```
 
**Body:**
 
```json
{
  "ticket": {
    "tags": ["existing-tag", "topic-billing"],
    "group_id": 12345
  }
}
```
 
Important: The `tags` field replaces the entire tag array. Merge existing tags with new tags before sending.
 
## List groups
 
Fetch all support groups to map group names to IDs.
 
**Request:**
 
```
GET https://{subdomain}.zendesk.com/api/v2/groups.json
Authorization: Basic <credentials>
```
 
**Response shape:**
 
```json
{
  "groups": [
    {
      "id": 12345,
      "name": "Billing Support"
    },
    {
      "id": 67890,
      "name": "Shipping Support"
    }
  ]
}
```
 
## Topic-to-group mapping
 
Default mapping (customize to match your Zendesk groups):
 
| Classification | Tag | Group Name |
|---------------|-----|------------|
| BILLING | topic-billing | Billing Support |
| SHIPPING | topic-shipping | Shipping Support |
| PRODUCT | topic-product | Product Support |
| ACCOUNT | topic-account | Account Support |
| TECHNICAL | topic-technical | Technical Support |
| OTHER | topic-uncategorized | General Support |
 
## Rate limits
 
~700 requests/minute on Professional plans. Each ticket classification requires 1 PUT call. 50 tickets = 50 API calls + 1 search + 1 groups lookup = 52 total.

# Ticket Classification Prompt
 
Use this prompt template when classifying each ticket with Claude.
 
## Prompt
 
```
You are a support ticket classifier. Classify this ticket into exactly one topic.
 
Subject: {subject}
Description (first 500 chars): {description_truncated}
 
Reply with exactly one of:
- BILLING — invoices, charges, payments, subscriptions, pricing, refunds
- SHIPPING — delivery, tracking, packages, lost items, shipping delays, returns
- PRODUCT — product quality, defects, wrong item, size/color issues, product questions
- ACCOUNT — login, password, account access, profile settings, two-factor auth
- TECHNICAL — errors, bugs, crashes, API issues, integrations, performance problems
- OTHER — doesn't fit any of the above
 
Reply with only the label, nothing else.
```
 
## Model settings
 
- Model: `claude-haiku-4-5-20251001`
- max_tokens: 20
- No system prompt needed — the classification instructions are in the user message
 
## Notes
 
- Truncate the description to 500 characters to keep costs low and classification fast
- Claude Haiku costs ~$0.001 per classification at these token counts
- The prompt should be customized if you add or rename categories

/zendesk-triage

Fetching untagged open tickets...
  Found 23 untagged tickets to classify
 
  #48291  "Can't log into my account"  →  topic-account (Account Support)
  #48295  "Invoice shows wrong amount"  →  topic-billing (Billing Support)
  #48301  "Package never arrived"  →  topic-shipping (Shipping Support)
  ...
 
Classified 23 tickets:
  topic-account: 6
  topic-billing: 5
  topic-shipping: 4
  topic-technical: 4
  topic-product: 3
  topic-uncategorized: 1

# Run every 30 minutes during business hours
*/30 8-18 * * 1-5 cd /path/to/your/project && claude -p "Run /zendesk-triage" --allowedTools 'Bash(*)' 'Read(*)'

name: Zendesk Ticket Triage
on:
  schedule:
    - cron: '*/30 13-22 * * 1-5'  # 8 AM-5 PM ET, weekdays
  workflow_dispatch: {}   # Manual trigger for testing
jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /zendesk-triage"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          ZENDESK_SUBDOMAIN: ${{ secrets.ZENDESK_SUBDOMAIN }}
          ZENDESK_EMAIL: ${{ secrets.ZENDESK_EMAIL }}
          ZENDESK_API_TOKEN: ${{ secrets.ZENDESK_API_TOKEN }}