Auto-triage Gorgias tickets using a Claude Code skill

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

.claude/skills/ticket-triage/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── classification-prompt.md      # prompt for topic classification
└── references/
    └── gorgias-tickets-api.md        # Gorgias API patterns

---
name: ticket-triage
description: Classify untagged open Gorgias tickets by reading subject and body, then apply a topic tag (billing, shipping, returns, technical, account, or feedback) via the Gorgias API.
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Fetch untagged open tickets from Gorgias, classify each one by topic using Claude (Haiku), and write the tag back via the Gorgias API.
 
## Configuration
 
Read these environment variables:
 
- `GORGIAS_DOMAIN` — your Gorgias subdomain (required)
- `GORGIAS_EMAIL` — Gorgias account email for API auth (required)
- `GORGIAS_API_KEY` — Gorgias API key (required)
- `ANTHROPIC_API_KEY` — Anthropic API key for classification (required)
 
Default categories: billing, shipping, returns, technical, account, feedback, other. The user may request different categories.
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Fetch open tickets from Gorgias. See `references/gorgias-tickets-api.md` for the endpoint.
3. Filter to tickets with no existing tags.
4. For each ticket, read the subject and first 500 characters of the message body.
5. Call Claude (Haiku) with the classification prompt from `templates/classification-prompt.md` to determine the topic.
6. Apply the tag via `PUT /tickets/{id}`, merging with any existing tags.
7. Print each ticket ID, subject, and assigned tag.
 
## Important notes
 
- The Gorgias `PUT /tickets/{id}` endpoint REPLACES the entire tags array. Fetch current tags first, merge the new tag, then PUT the combined list.
- Use claude-haiku-4-5 for classification — it's fast (~$0.001 per ticket) and accurate for topic classification.
- If Claude returns a category not in the defined list, default to "other".
- Rate limit: Gorgias allows roughly 2 requests per second.
- Use the `requests` library for Gorgias and `anthropic` for Claude. Install with pip if needed.

# Ticket Classification Prompt
 
Use this prompt when calling Claude to classify a ticket.
 
## Prompt
 
```
Classify this customer support ticket into exactly one category.
 
Categories: billing, shipping, returns, technical, account, feedback, other
 
Subject: {subject}
Body (first 500 chars): {body}
 
Reply with only the category name, nothing else.
```
 
## Notes
 
- Use `claude-haiku-4-5-20251001` as the model.
- Set `max_tokens: 20` — the response is a single word.
- Parse the response and lowercase it. If it doesn't match any category, use "other".
- To customize categories, update the list in this prompt and in the SKILL.md.

# Gorgias Tickets API Reference
 
## Authentication
 
All requests use HTTP Basic Auth:
- Username: `GORGIAS_EMAIL`
- Password: `GORGIAS_API_KEY`
- Base URL: `https://{GORGIAS_DOMAIN}.gorgias.com/api`
 
## List open tickets
 
**Request:**
 
```
GET /api/tickets?status=open&limit=50
```
 
**Response shape:**
 
```json
{
  "data": [
    {
      "id": 12345,
      "subject": "My order hasn't arrived yet",
      "status": "open",
      "tags": [],
      "messages": [
        {
          "id": 99001,
          "body_text": "Hi, I placed an order a week ago and haven't received it...",
          "source": { "type": "email" }
        }
      ]
    }
  ]
}
```
 
- Filter for tickets where `tags` is an empty array to find untagged tickets.
- The first message in `messages` is typically the customer's original message.
 
## Update a ticket (apply tag)
 
**Request:**
 
```
PUT /api/tickets/{ticket_id}
Content-Type: application/json
```
 
**IMPORTANT:** The `tags` field REPLACES the entire array. Fetch current tags first, add the new category tag, then PUT the merged list.
 
```json
{
  "tags": [
    { "name": "shipping" }
  ]
}
```

/ticket-triage

Fetching untagged open tickets...
Found 15 untagged tickets
 
  #14401  "My order hasn't arrived yet"       →  shipping
  #14405  "Can I get a refund for this?"       →  returns
  #14408  "Error on checkout page"             →  technical
  #14412  "Update my billing address"          →  account
  #14415  "Love the new packaging!"            →  feedback
 
Tagged 15 ticket(s).

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

name: Ticket Triage
on:
  schedule:
    - cron: '0 13-22 * * 1-5'  # 8 AM-5 PM ET, weekdays
  workflow_dispatch: {}
jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /ticket-triage"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GORGIAS_DOMAIN: ${{ secrets.GORGIAS_DOMAIN }}
          GORGIAS_EMAIL: ${{ secrets.GORGIAS_EMAIL }}
          GORGIAS_API_KEY: ${{ secrets.GORGIAS_API_KEY }}